Integrate Domino and WebSphere MQ

Integrate Domino and WebSphere MQ
Message queues unite disparate systems
Skill Level: Introductory
George Brichacek (george_brichacek@us.ibm.com)

Product Marketing Manager
IBM Software Group
30 Jul 2003
Companies today have business software on disparate systems. For example, the
human resource system might be on a Sun Solaris server, a customer relationship
management system might be on Windows, and financials might be on the
mainframe. Companies have a need to connect these systems, and developing the
middleware to connect these systems is expensive. WebSphere MQ can connect all
your business software to form one efficient enterprise. All this integration is based
on two actions: putting messages on queues and reading them off of queues. In this
tutorial, you'll learn how to perform these tasks using a Domino database and the
Java platform. These simple examples will open a wide vista of integration options to
you.
Section 1. Introduction
What is this tutorial about?

Collaboration enables individuals to access information, expertise, and resources
regardless of time or geography. Lotus Domino provides you with the means to
realize this collaboration.
The WebSphere MQ products enable programs to communicate with one another

across a network of dissimilar components -- processors, operating systems,

© Copyright IBM Corporation 1994, 2008. All rights reserved. Page 1 of 39
developerWorks® ibm.com/developerWorks
subsystems, and communication protocols -- using a consistent application

programming interface.
This tutorial discusses how you can integrate Lotus Domino with WebSphere MQ
using LotusScript and the Java platform. We'll set up two forms in Lotus Domino for
use by a Lotus Notes client -- one to put a message to, and the other to get a
message from, WebSphere MQ. Then we'll set up two more forms for the Web to do
the same thing. We could have created just two forms -- one for the Notes client and
the other for the browser client -- but by proceeding in this way, we'll see two
different ways to use the Java platform within Domino. Finally, we'll set up a Domino
Java scheduled agent that will execute every hour to see if there are any messages
on a particular queue.
Companies today have business software on disparate systems. For example, the
human resources system might be on a Sun Solaris server, a customer relationship
management system might be on Microsoft Windows, and financials might be on a
mainframe. Companies have a need to connect these systems, and developing the
middleware to connect these systems is expensive. WebSphere MQ can connect all
your business software to form one efficient enterprise. WebSphere MQ minimizes
time taken to integrate applications on different systems, so your company can
respond quickly to new market strategies. While the examples we're using here may
seem simple, many of WebSphere MQ's integration functions are based on two
actions: putting messages on queues and reading them off of queues. Once you've
learned a few simple ways to achieve these tasks with Domino, a wide vista of
integration options is open to you.
Who should take this tutorial?

This tutorial will be useful for developers who are working in an environment where
Lotus Domino and WebSphere MQ are deployed, and who would like to know how
to integrate these two products.
Also, this tutorial will be useful for developers who are using the LotusScript
extension for MQSeries (MQLSX) today. MQLSX is not supported in the Lotus
Domino 6 environment, and since support for MQLSX will end on December 31,
2004, it is recommended that any new solutions be written in the Java language
within the Domino 6 environment.
After completing this tutorial, you should know how to integrate Lotus Domino and
WebSphere MQ using LotusScript and the Java language.
Required software
For the purposes of this tutorial, we'll be using Lotus Domino 6 and WebSphere MQ

Page 2 of 39 © Copyright IBM Corporation 1994, 2008. All rights reserved.
ibm.com/developerWorks developerWorks®
5.3, which, at the time of writing, are the most current releases of those products.
For more information on the system requirements for running these applications, see
the documentation that accompanies them.
This tutorial guides you through the use of a Lotus Domino database that uses the
WebSphere MQ Java set of classes to put and get messages. You'll need a Lotus
Domino version 6 server, Domino Designer version 6, and a Lotus Notes version 6
client. The Domino database will put a message and get the message from a
WebSphere MQ queue. You'll also need a WebSphere MQ version 5.3 server
installed. If the WebSphere MQ server is not installed on the same machine as the
Lotus Domino server, you need to install the WebSphere MQ client on the same
machine as the Lotus Domino server.
You can download trial versions of the required Lotus software at no charge. All of
this software is accompanied by installation instructions.
WebSphere MQ has available downloadable packages of code and documentation,

called SupportPacs, which complement the entire family of WebSphere MQ
products. The majority of SupportPacs are available at no charge. Others can be
purchased as fee-based services from IBM.
To test your WebSphere MQ installation, refer to the WebSphere MQ installation

verification section of this tutorial.
Section 2. WebSphere MQ: An overview
Renaming MQSeries
MQSeries is taking on a new name -- WebSphere MQ. WebSphere is IBM's brand
for e-business which includes many individual products and offerings. Rebranding
the MQSeries name with the WebSphere software platform signals a
better-integrated e-business software platform. The MQSeries family of products will
continue to grow and develop in the way that has already made it the industry
standard for integration.
Introduction to message queuing

The WebSphere MQ products enable developers to write application programs to
communicate with other application programs without knowing anything about where
that other program is. Applications don't have to know anything about what system

potential partner applications are on, what platform they're on, what language they're
written in, or what communication protocol they need to use in order to
communicate.
Applications designed and written using this interface are known as message
queuing applications, as they use the messaging and queuing. What exactly does
this mean?
• Programs that use messaging communicate by sending each other data

in messages rather than calling each other directly.
• In queuing systems, messages are placed on queues in storage, allowing
programs to run independently of one another, at different speeds and
times, in different locations, and without being logically connected.
Message queuing has been around the computer industry for several years.
Electronic mail is prime example of message queuing. Without queuing, when you
sent an e-mail, every node would need to be available to forward the message, and
the addressee would need to be logged on and ready to accept the message. With
message queuing, messages are stored and then forwarded when the next system
is available to forward the message. At the final destination, the message is stored in
an inbox until the addressee is ready to read it.
WebSphere MQ is middleware software for message queuing applications. There is

so much to this product that we will not be able to cover all of what it can do here.
Instead, we'll focus on how you can put a message on a queue from Lotus Domino,
and then how you get a message from a queue using Lotus Domino. There are
several application programming languages you can use to put and get messages
from queues using the WebSphere MQ Message Queue Interface (MQI): C, C++,
COBOL, Assembler, RPG, PL/I, Visual Basic, and the Java language. We'll focus on
the Java language in this tutorial.
There is another interface, called the Application Messaging Interface (AMI), that
you can use with WebSphere MQ. AMI provides a simple interface that application
programmers can use without needing to understand all the functions available in
MQI. The functions that are required in a particular installation are defined by a
system administrator, using services and policies. We will not discuss AMI in this
tutorial, just MQI.
WebSphere MQ and the Java language

There are two ways of writing Java applications that communicate with WebSphere
MQ:

1. WebSphere MQ classes for the Java language. A Java program written

in this way consists of a set of WebSphere MQ objects; you act upon
those objects by calling methods on them. For example, the queue
manager is represented by an object of class MQQueueManager. You
disconnect from the queue manager by calling the disconnect() method
on that class, like so:
// declare an object of type queue manager

MQQueueManager queueManager=new MQQueueManager();
...
// do something...
...
// disconnect from the queue manager
queueManager.disconnect();
2. WebSphere MQ classes for the Java Message Service (WebSphere

MQ JMS). The Java Message Service (JMS) defines a generic view of a
message-passing service. The generic JMS model is based around the
following interfaces, which are defined in Sun's javax.jms package:
• Connection: Provides access to the underlying transport, and is used
to create Sessions.
• Session: Provides a context for producing and consuming messages,
including the methods used to create MessageProducers and
MessageConsumers.
• MessageProducer: Used to send messages.
• MessageConsumer: Used to receive messages.
This tutorial focuses on the WebSphere MQ classes for the Java language. The
WebSphere MQ classes for JMS use a JNDI namespace for their administered
objects, which is the expected operation of JMS client applications. Setting up a
JNDI-based repository is relatively complex, and hence is beyond the scope of this
tutorial.
WebSphere MQ messages
Messages are data sent from one program to another. A message consists of two
parts, the message descriptor and the application data, as illustrated below.

When a message is exchanged, the receiving program needs to know the layout of
the data. For example, suppose the message describes a person. The first 12 bytes
of the message could be the first name, the next 24 bytes could be the last name,
the next 30 bytes could be the first address line, the next 30 bytes could be the
second address line, and we could continue on from there. The receiving program
would know all this in advance and parse the message to extract the various parts of
the person message.
On the other hand, the message could be an order number, and the sending
program might like to know more about the order. The sending program would send
the message and get a reply message back with all the information about that order.
There are several questions you need to answer at the design stage that will affect
the way you create messages.
• What type of message should I use? Are you designing a simple

application in which you can send a message and then take no further
action? Or are you asking for a reply to a question? Do you want your
request and reply messages to be synchronous? This implies that you set
a timeout period for the reply to answer your request, and, if you do not
receive the reply within that period, your application treats the exchange
as an error. Or would you prefer to work asynchronously, so that your
processes do not have to depend upon the occurrence of specific events,
such as common timing signals?
• Should I assign different priorities to some of the messages I
create? You can assign a priority value to each message, and define the
queue so that it maintains its messages in order of their priority. If you do
this, when another program retrieves a message from the queue, it
always gets the message with the highest priority. If the queue does not
maintain its messages in priority order, a program that retrieves
messages from the queue will retrieve them in the order in which they
were added to the queue. Programs can also select a message using the
identifier that the queue manager assigned when the message was put on
the queue. Alternatively, you can generate your own identifiers for each of
your messages.
• Will my messages be discarded when the queue manager restarts?
When restarted, the queue manager preserves all persistent messages,

recovering them when necessary from the WebSphere MQ log files.

Nonpersistent messages and temporary dynamic queues are not
preserved. Any messages that you do not want discarded must be
defined as persistent when they are created.
• Do I want to give information about myself to the recipient of my
messages? Normally, the queue manager sets the user ID, but suitably
authorized applications can also set this field, so that you can include
your own user ID and other information that the receiving program can
use for accounting or security purposes.
• Will the message be a string, number, or something else? The layout
of the message must be understood by both the sending program and the
receiving program. The sending program will construct the message and
the receiving program must deconstruct the message in the same way it
was built.
Types of messages
You can create several different types of messages. These are four of the most
common:
• Datagram: You should use a datagram when you do not require a reply
from the application that receives the message.
• Request: You should use a request message when you want a reply from
the application that receives the message.
• Reply: You should use a reply message when you reply to another
message.
• Report: Report messages inform applications about events such as the
occurrence of an error when processing a message. They can be
generated at any time, and they may arrive on a queue when your
application is not expecting them. Report messages can be generated by:
• A queue manager
• A message channel agent (if the agent cannot deliver the message,
for instance)
• An application (if the application cannot use the data in the message,
for instance)
For more information about messages, refer to the WebSphere MQ Application
Programming Guide, which is available on the WebSphere MQ CD-ROM. The
documentation is also available online in HTML and PDF formats after installing
WebSphere MQ.

Application data in the message

The receiving program needs to know the layout of the application data in the
message; therefore, the sending program needs to conform to that layout or things
can get messy.
The application data in the message can be in any format. As described in our
previous example, the data could represent a person, i.e., first name, last name,
address, etc. The data could be one long string, or it could include integers,
decimals, floats, and so on. The most important thing is that both programs -- the put
program and the get program -- need to know the layout of the data in the message.
There are several methods to ensure this. The simplest is documenting and
standardizing on message layouts for your system ahead of time. That way, when
applications are developed, they adhere to the standard message layout.
In our Java language example later in this tutorial, we'll use a string for the
application data in the message. To build a new message that may contain a string,
an integer, or a decimal, you create a new instance of the MQMessage class, and
use the writeXXX() methods to put data into the message buffer.
The following Java code creates a message and puts it onto a queue. You first
create the message, then put any type of data into the message buffer in the order
you want. For example, you write the age first with the writeInt() method, then you
write the string name with the writeUTF() method. This is just one example; there are
several other writeXXX() methods that you could use.
// Build a new message containing my age followed by my name.

MQMessage myMessage = new MQMessage();
myMessage.writeInt(48);
myMessage.writeUTF("George Brichacek");
// Use the default put message options...
MQPutMessageOptions pmo = new MQPutMessageOptions();
// put the message!
queue.put(myMessage,pmo);
The following example will get the message from the queue.
// Get a message from the queue

MQMessage theMessage = new MQMessage();
MQGetMessageOptions gmo = new MQGetMessageOptions();
queue.get(theMessage,gmo);
// Extract the message data
int age = theMessage.readInt();
String name = theMessage.readUTF();
For more information about writing application data in a message, refer to the

WebSphere MQ Using Java book, which is available on the WebSphere MQ

CD-ROM. The documentation is also available online in HTML and PDF formats
after installing WebSphere MQ.
WebSphere MQ queues
A WebSphere MQ queue is a named object on which applications can put
messages, and from which applications can get messages. Messages are stored on
a queue, so if the putting application expects a reply to its message, it is free to do
other work while waiting for that reply. Applications access a queue by using the
Message Queue Interface (MQI).
Before a message can be put on a queue, the queue must have already been
created. A queue is owned by a queue manager, and that queue manager can own
many queues. However, each queue must have a name that is unique among
queues managed by a single queue manager.
Before using a queue, you must open it in your application program, specifying what
you want to do with it. For example, you can open a queue:
• For browsing messages only (not retrieving them)

• For retrieving messages (either sharing the access with other programs,
or with exclusive access)
• For putting messages on the queue
• For inquiring about the attributes of the queue
• For setting the attributes of the queue
Types of queues
WebSphere MQ supports several types of queues:
• Local and remote queues. A queue is known to a program as local if it is

owned by the queue manager to which the program is connected. The
queue is known as remote if it is owned by a different queue manager.
The important difference between these two types of queue is that you
can get messages only from local queues. (You can put messages on
both local and remote queues.)
• Shared queues (only available on WebSphere MQ for z/OS). A shared
queue is a type of local queue whose messages can be accessed by one
or more queue managers that are in a queue-sharing group.

• Alias queues. To your program, an alias queue appears to be a queue,

but it is really a WebSphere MQ object that you can use to access
another queue. This means that more than one program can work with
the same queue, each program accessing it under a different name.
• Model and dynamic queues. A model queue is a template of a queue
definition used only when you want to create a dynamic local queue. You
can create a local queue dynamically from your application program,
naming the model queue you wish to use as the template for the queue
attributes.
• Cluster queues. A cluster queue is a queue that is hosted by a cluster
queue manager and made available to other queue managers in the
cluster.
For more information about queues, refer to the WebSphere MQ Application
Programming Guide, which is available on the WebSphere MQ CD-ROM. The
documentation is also available online in HTML and PDF formats after installing
WebSphere MQ.
Section 3. WebSphere MQ installation verification
Servers and client installation

Before going any further, you should test your installation of WebSphere MQ. There
are several ways to install the software, but there are two typical setups:
1. Lotus Domino and the WebSphere MQ client are on the same box, and
the WebSphere MQ server is on another box.
2. Lotus Domino server and the WebSphere MQ server are on the same
box. With this setup, the WebSphere MQ client code is already installed
with the WebSphere MQ server.
The following two illustrations highlight these installations. For our purposes, it
doesn't matter which way you install the servers; this tutorial and the sample code
will work either way.
Client/server -- two boxes Two servers -- one box

Test the installation

Use the following procedures to configure your queue manager to accept incoming
connection requests from a client. (These procedures are for the Windows platform.
Refer to the documentation for other platforms.)
1. If your queue manager is not started, start it by using the strmqm

command.
2. Type the following command to start the runmqsc program:
runmqsc [QMNAME]
3. Define a sample channel called JAVA.CHANNEL by issuing the following

command:
DEF CHL('JAVA.CHANNEL') CHLTYPE(SVRCONN) TRPTYPE(TCP) MCAUSER(' ')

DESCR('Sample channel')
4. If a listener has not already been started, start a listener program with the
following commands:
runmqlsr -t tcp [-m QMNAME] -p 1414

5. Change to your WebSphere MQ samples directory (by default it is

C:\Program Files\IBM\WebSphere MQ\tools\Java\base) and type:
java MQIVP
The next panel provides the information you'll need when you run the MQIVP
program, and the results you should expect from it.
Verification results
The installation verification program requires some input. The prompts are:
• Please enter the IP address of the MQ server -- Enter

either the IP address or the hostname of the machine where your queue
manager is installed.
• Please enter the port to connect to -- Enter the default port,
1414.
• Please enter the server connection channel name -- Enter
JAVA.CHANNEL, which we created in the previous panel, or enter an
existing channel you've already created.
• Please enter the queue manager name -- Enter the queue
manager name.
The program connects to your queue manager, puts a message on a queue, gets
the message from the queue, and then disconnects. You should see a message
indicating that the MQ transport is functioning correctly, which should look something
like this:

Now that you have WebSphere MQ installed, you're ready to write Domino code that
takes advantages of its features.
Section 4. Lotus Domino and WebSphere MQ
Support issues
The majority of organizations integrating Lotus Domino and WebSphere MQ today
are using the MQSeries Link for LotusScript. This product supports Domino R4 and
R5, and MQSeries 5.2 and WebSphere MQ 5.3. (Note that in the transition from
version 5.2 to 5.3 of this software, IBM integrated MQSeries into its WebSphere
offerings, which is the reason for the name change.) The MQSeries Link for
LotusScript (MQLSX) will not be supported in the Domino 6 environment, and its
end-of-service date is December 31, 2004. Furthermore, you will no longer be able
to download MQLSX after January 2, 2004.
As you move forward with Lotus Domino 6 and WebSphere MQ 5.3, it is

recommended that you write any new solutions in the Java language.
The question now is: How do we move from MQLSX to the Java platform? Hopefully
this tutorial will provide some guidance.

Java runtime environments

When integrating Lotus Domino and WebSphere MQ, be aware of the Java runtime
environment. Lotus Domino 5 supports Java v1.1.8, and WebSphere MQ 5.3
requires Java 2 v1.3. So, if you are planning on using WebSphere MQ 5.3, you need
to use Lotus Domino 6.
If you have Lotus Domino 5 or 6, you can still use earlier versions of WebSphere MQ
(5.1 or 5.2), but these versions do not include the necessary MQ Java classes. You
need to install the SupportPac MA88: MQSeries classes for Java and MQSeries
classes for Java Message Service. For more information about SupportPacs, visit
WebSphere MQ SupportPacs.
Lotus Domino 6 and LotusScript to Java

One possible solution to integrate Lotus Domino and WebSphere MQ is to use a
new feature in Lotus Domino 6 called LotusScript to Java (LS2J). It allows
LotusScript to access Java classes. Developers can access Java in LotusScript
programs as a set of predefined LotusScript objects. This set of objects allows
LotusScript to use existing Java classes that are available in script libraries or found
using the classpath. The Java classes we'll use in this tutorial put a message on a
queue and get a message from a queue.
Using LS2J with Lotus Domino 6 allows developers to take advantage of all the
LotusScript front-end and back-end classes, instead of a writing a solution entirely in
the Java language, which provides access only to the back-end classes.
We'll provide three examples in this tutorial: one for the Lotus Notes client, one for
the browser client, and the last is a scheduled agent to get a message off of a
queue. The first example uses LS2J and the second uses a Lotus Domino agent
written entirely in the Java language. These first two examples put a message on a
queue and get a message from a queue. The third example is a scheduled agent
that will only get a message off of a queue. This last example is written entirely in
Java code, too.
Section 5. Lotus Notes client example
Java library

The first example is for the Lotus Notes client. In this panel, we'll highlight the design
of the sample database that we'll be accessing with the client. (You can download
the complete database from Resources.)
The first part of the database we will discuss is the Java code used to put a
message on a queue and to get a message from a queue. With Lotus Domino
Designer 6, you have the capability to create Java libraries, just like you've been
able to create LotusScript libraries in the past.
You should be able to use the sample database with no modifications, but there are
some setup steps you'll need to walk through for Lotus Notes and Domino to work
properly. First, you'll need to edit the Java user classes parameter in the Notes.ini
file. You need to add the following line to the Notes.ini file:
JavaUserClasses=C:\WebSphereMQ\Java\lib;C:\WebSphereMQ\Java\lib\com.ibm.mq.jar;
C:\WebSphereMQ\tools\java\base\;C:\WebSphereMQ\Java\lib\connector.jar;
C:\WebSphereMQ\Java\lib\jta.jar;C:\WebSphereMQ\Java\lib\providerutil.jar;
C:\WebSphereMQ\Java\lib\com.ibm.mqjms.jar;C:\WebSphereMQ\Java\lib\ldap.jar;
C:\WebSphereMQ\Java\lib\jndi.jar;C:\WebSphereMQ\Java\lib\jms.jar;
C:\WebSphereMQ\Java\lib\fscontext.jar;
These Java user classes need to be added to the Lotus Notes client file and the
Lotus Domino server file. For this example, we've assumed that WebSphere MQ is
installed at C:\WebSphereMQ\; obviously, you'll need to change this to match your
environment.
Download the sample database and move it to your Domino 6 server. Open the
Domino Designer 6 client and the sample database. Expand Shared Code and
Script Libraries, then select DominoMQC. You'll notice two Java programs:
• MQGetC.java
• MQPutC.java
These are standalone Java applications; we'll look at them in more detail later in this
section. You can copy them from the Java library, save them as Java applications,
compile them, and then execute them. This is a good test to try out the Java code,
connectivity, and the put and the get of a message.
In this section, we'll use a Notes front end to access these applications. First,
however, we'll take a look a potential error that might cause you problems.
Unsatisfied link error

At this point, you may encounter an error running LS2J. The error message indicates
that the program could not find a file named mqjbnd05.dll, even though this file is in

the Java path, as illustrated below.
The problem is with the Java runtime environment. Lotus Domino 6 supports Java 2
Runtime Environment, Standard Edition 1.3.1 and java.exe is located in
c:\lotus\domino\jvm\bin. Make sure you are using this executable.
There is a workaround. Copy mqjbnd05.dll to the Lotus Domino binary directory (by
default, this directory is C:\Lotus\Domino).
The put form

The put form for Notes is simple. It has seven fields and a button. The first six fields
are the input to the Java putMessage() method, and the last is a field for errors.

Now let's look at the code behind this form. What follows is the LotusScript code that
will invoke the Java putMessage() method, which puts a message on a queue. In the
Options section, it's important to include the Use statement; this is where the Java
code is located. The Uselsx statement is required to use LS2J; it's the LotusScript
extension that allows LotusScript to execute Java methods. The Declarations
section initializes the objects. The Click routine sets the objects and gets the values
from the form and invokes the Java putMessage() method.
(Options)
Use "DominoMQC"
Uselsx "*javacon"
(Declarations)
'New LotusScript classes that access Java
Dim mySession As JavaSession
Dim myClass As JavaClass
Dim myObject As JavaObject
Dim port As Integer
Dim ws As NotesUIWorkSpace

Dim uidoc As NotesUIDocument

Sub Click(Source As Button)
'Initialize a Java session
Set mySession = New JavaSession()
'Initialize a Java class
Set myClass = mySession.GetClass("MQPutC")
'Initialize a Java object
Set myObject = myClass.CreateObject
Set ws = New NotesUIWorkspace
Set uidoc = ws.currentDocument
hostName = uidoc.FieldGetText("hostName")
port = Cint( uidoc.FieldGetText("port") )
channel = uidoc.FieldGetText("channel")
mqManager = uidoc.FieldGetText("mqManager")
mqQname = uidoc.FieldGetText("mqQname")
message = uidoc.FieldGetText("message")
'Invoke the Java method
returnStatus = myObject.putMessage( hostName, port, channel, mqManager, _
mqQname, message )
If Isempty( returnStatus ) Then
Call uidoc.FieldSetText( "Errors", "MQ Put Message Successful" )
Else
Call uidoc.FieldSetText( "Errors", returnStatus )
End If
End Sub
MQPutC.java
The following is the Java code used to put a message on a queue. This is the code
that our put form from the previous panel is accessing. For more information about
the Java code, refer to the Java agent code explained section.
import com.ibm.mq.*;
public class MQPutC {
public MQPutC() {
}
public static void main(String args[]){
try {
String hostName = "gfbrich";
int port = 1414;
String channel = "JAVA.CHANNEL";
String mqManager = "QM_gfbrich";
String mqQname = "SYSTEM.DEFAULT.LOCAL.QUEUE";
String message = "This is my first message";
String returnStatus = putMessage(hostName, port, channel,
mqManager, mqQname, message);
}
catch (Exception e) {
e.printStackTrace();
}
}
public static String putMessage(String hostName, int port, String channel,
String mqManager, String mqQname, String message) throws Exception {

String returnStatus = null;

try {
MQEnvironment.hostname = hostName;
MQEnvironment.channel = channel;
MQEnvironment.port = port;
MQEnvironment.properties.put(MQC.TRANSPORT_PROPERTY, MQC.TRANSPORT_MQSERIES);
MQQueueManager qMgr = new MQQueueManager(mqManager);
int openOptions = MQC.MQOO_OUTPUT | MQC.MQOO_FAIL_IF_QUIESCING ;
MQQueue qName = qMgr.accessQueue(mqQname, openOptions, null, null, null);
MQMessage mqMsg = new MQMessage();
mqMsg.format = MQC.MQFMT_NONE;
mqMsg.writeUTF(message);
MQPutMessageOptions pmo = new MQPutMessageOptions();
qName.put(mqMsg,pmo);
qName.close();
qMgr.disconnect();
}
catch (MQException ex) {
returnStatus = "A WebSphere MQ error occurred : Completion code "
+ ex.completionCode + " Reason code " + ex.reasonCode;
return returnStatus;
}
catch (java.io.IOException ex) {
returnStatus = "An error occurred whilst writing to the message buffer: " + ex;
}
}
}
The putMessage() method is the most important part of the program. As we saw,
this is the method we call from LotusScript in the Domino database. The input
parameters are:
• hostName: The host name of the WebSphere MQ server

• port: The listener port of the WebSphere MQ server
• channel: The channel name of the WebSphere MQ server
• mqManager: The name of the WebSphere MQ server
• mqQname: The name of the queue to put the message on
• message: The actual message to put on the queue
The get form

The get form is a simple one, too. It has six fields and a button. The first five fields
are the input to the Java getMessage() method and the last is a field for the
message.

Now let's look at the code behind the form. The following listing is the LotusScript
code to get a message from a queue. It invokes the Java getMessage() method.
Again, remember that it's important to include the Use statement, and that the
Uselsx statement is required to use LS2J. The Click routine here sets the objects
and gets the values from the form and invokes the Java getMessage() method.
(Options)
Use "DominoMQC"
Uselsx "*javacon"
(Declarations)
'New LotusScript classes that access Java
Dim mySession As JavaSession
Dim myClass As JavaClass
Dim myObject As JavaObject
Dim port As Integer
Dim ws As NotesUIWorkSpace
Dim uidoc As NotesUIDocument
Sub Click(Source As Button)

'Initialize a Java session

Set mySession = New JavaSession()
'Initialize a Java class
Set myClass = mySession.GetClass("MQGetC")
'Initialize a Java object
Set myObject = myClass.CreateObject
Set ws = New NotesUIWorkspace
Set uidoc = ws.currentDocument
hostName = uidoc.FieldGetText("hostName")
port = Cint( uidoc.FieldGetText("port") )
channel = uidoc.FieldGetText("channel")
mqManager = uidoc.FieldGetText("mqManager")
mqQname = uidoc.FieldGetText("mqQname")
'Invoke the Java method
message = myObject.getMessage( hostName, port, channel, mqManager, _
mqQname )
Call uidoc.FieldSetText( "message", message )
End Sub
MQGetC.java
The following is the Java code used to get a message off of a queue. This is the
code that our get form from the previous panel is accessing. For more information
about the Java code, refer to the Java agent code explained section.
import com.ibm.mq.*;
public class MQGetC {
public MQGetC() {
}
public static void main(String args[]){
try {
String hostName = "gfbrich";
int port = 1414;
String channel = "JAVA.CHANNEL";
String qManager = "QM_gfbrich";
String mqQname = "SYSTEM.DEFAULT.LOCAL.QUEUE";
String retrievedMessage = getMessage(hostName, port, channel,
qManager, mqQname);
System.out.println("Message = " + retrievedMessage);
}
catch (Exception e) {
}
}
public static String getMessage(String hostName, int port, String channel,
String mqManager, String mqQname) throws Exception {
String msgText = new String();
try {
MQEnvironment.hostname = hostName;
MQEnvironment.port = port;
MQEnvironment.channel = channel;
MQEnvironment.properties.put(MQC.TRANSPORT_PROPERTY, MQC.TRANSPORT_MQSERIES);
MQQueueManager qMgr = new MQQueueManager(mqManager);
int openOptions = MQC.MQOO_INPUT_AS_Q_DEF | MQC.MQGMO_FAIL_IF_QUIESCING;
MQQueue qName = qMgr.accessQueue(mqQname, openOptions, null, null, null);

MQMessage retrievedMessage = new MQMessage();

MQGetMessageOptions gmo = new MQGetMessageOptions();
gmo.options = MQC.MQGMO_WAIT | MQC.MQGMO_FAIL_IF_QUIESCING | MQC.MQGMO_NO_SYNCPOINT;
gmo.waitInterval = 10000;
qName.get(retrievedMessage,gmo);
msgText = retrievedMessage.readUTF();
qName.close();
qMgr.disconnect();
}
catch (MQException ex) {
return "A WebSphere MQ error occurred : Completion code " +
ex.completionCode + " Reason code " + ex.reasonCode;
}
catch (java.io.IOException ex) {
return "An error occurred whilst writing to the message buffer: " + ex;
}
return msgText;
}
}
The getMessage() method is the most important part of the program. As we saw in
the previous panel, this is the method we call from LotusScript in the Domino
database. The input parameters are:
• hostName: The host name of the WebSphere MQ server

• port: The listener port of the WebSphere MQ server
• channel: The channel name of the WebSphere MQ server
• mqManager: The name of the WebSphere MQ server
• mqQname: The name of the queue to get the message from
Another feature of this application is noteworthy. As written, the program waits for 10
seconds for a message on the queue. The get message options value of
MQC.MQGMO_WAIT indicates to wait and waitInterval indicates the time to wait, in
milliseconds. If you don't want the program to wait the 10 seconds, remove the wait
parameter and the interval from the code.
Section 6. Web browser example
Java agents
Our second example uses a Web browser for the client. There are two forms, one
for the put message and the other for the get message. For each form, there is a
corresponding Domino Java agent.

For the Java agents to call WebSphere MQ, you need to update the Java user
classes parameter in the Notes.ini file for the Domino server. Shut down the Domino
server, add the following line, then restart the server.
JavaUserClasses=C:\WebSphereMQ\Java\lib;C:\WebSphereMQ\Java\lib\com.ibm.mq.jar;
C:\WebSphereMQ\tools\java\base\;C:\WebSphereMQ\Java\lib\connector.jar;
C:\WebSphereMQ\Java\lib\jta.jar;C:\WebSphereMQ\Java\lib\providerutil.jar;
C:\WebSphereMQ\Java\lib\com.ibm.mqjms.jar;C:\WebSphereMQ\Java\lib\ldap.jar;
C:\WebSphereMQ\Java\lib\jndi.jar;C:\WebSphereMQ\Java\lib\jms.jar;
C:\WebSphereMQ\Java\lib\fscontext.jar;
For this example, we've assumed that WebSphere MQ is installed at

C:\WebSphereMQ\; obviously, you'll need to change this to match your environment.
MQPutC Web form

The put message form for the Web has the same number of fields as the
corresponding Notes client, but the Web form has a WebQuerySave event to
execute an agent. The formula for this event is @Command([ToolsRunMacro];
"MQPutAgent").
The form also has a hidden field, SaveOptions, for which the default value is 0. This
indicates not to save the document into the Domino database after the Submit
button is pressed. If you want to save the document, remove the field or change the
default value to 1.

MQPutAgent
Now let's examine the Domino Java agent that will retrieve the field values from the
form and then put the message on the queue.
The agent gets a handle to the document doc and issues a getItemValueString() to
get the host name, channel, queue manager, queue, and message. It issues a
getItemValueInteger() for the port, since the port is an integer value.
The agent sets environment values for the host name, channel, and port. The agent
creates a new queue manager, new message, and new message options objects. It
accesses the queue name and, finally, puts the message on the queue. For more
information about the Java code, refer to the Java agent code explained section.
Here's the code:

import
com.ibm.mq.*;
import
java.io.PrintWriter;
import
lotus.domino.*;
public
class
JavaAgent
extends
AgentBase {
public
void
NotesMain()
{
try {
Session
session =
getSession();
AgentContext
agentContext
=
session.getAgentContext();
PrintWriter
pw =
getAgentOutput();
pw.println("Content-Type:
text/html");
pw.println("<html><head><title>DominoMQ</title></head><body>");
pw.println("<table><tr>");
pw.println("<td
width=\"200\"
rowspan=\"2\"><img
src=\"
/DominoMQ.nsf/ibmlogo-S.gif?OpenImageResource\"></td>");
pw.println("<td><img
src=\"
/DominoMQ.nsf/LOT_18P.GIF?OpenImageResource\"></td>");
pw.println("</tr><tr><td>");
pw.println("<img
src=\"
/DominoMQ.nsf/WS_18P.GIF?OpenImageResource\"></td>");
pw.println("</tr></table>");
pw.println("<body><h1>DominoMQ
Put</h1>");
Document
doc =
agentContext.getDocumentContext();
String
returnStatus
= null;
pw.println("<p>Host:
" +
doc.getItemValueString("hostName"));
pw.println("<p>Channel:
" +
doc.getItemValueString("channel"));
pw.println("<p>Port:
" +
doc.getItemValueInteger("port"));
pw.println("<p>Message:
" +
doc.getItemValueString("message"));
MQEnvironment.hostname
=
doc.getItemValueString("hostName");
MQEnvironment.channel
=

doc.getItemValueString("channel");
MQEnvironment.port
=
doc.getItemValueInteger("port");
MQEnvironment.properties.put(MQC.TRANSPORT_PROPERTY,
MQC.TRANSPORT_MQSERIES);
MQQueueManager
qMgr = new
MQQueueManager(doc.getItemValueString("mqManager"));
int
openOptions
=
MQC.MQOO_INPUT_AS_Q_DEF
|
MQC.MQOO_OUTPUT;
MQQueue mqQ
=
qMgr.accessQueue(doc.getItemValueString("mqQname"),openOptions);
MQMessage
mqMsg = new
MQMessage();
mqMsg.writeUTF(doc.getItemValueString("message"));
MQPutMessageOptions
pmo = new
MQPutMessageOptions();
mqQ.put(mqMsg,pmo);
mqQ.close();
qMgr.disconnect();
pw.println("<h2>Message
successfully
put</h2>");
pw.println("</body></html>");
}
catch(NotesException
ne) {
System.out.println("A
Lotus
Domino
error
occurred: "
+ ne.id + "
" +
ne.text);
}
catch
(MQException
ex) {
WebSphere
MQ error
occurred :
Completion
code " +
ex.completionCode
+ " Reason
code " +
ex.reasonCode);
}
catch
(java.io.IOException
ex) {
System.out.println("An
error
occurred
writing to
the message
buffer: " +
ex);
}

catch(Exception
e) {
}
}
}
MQGetC Web form

The get message form for the Web has the same number of fields as the
corresponding Notes client, but the Web form has a WebQuerySave event to
execute an agent. The formula for this event is @Command([ToolsRunMacro];
"MQGetAgent").
The form also has a hidden field, SaveOptions, with a default value of 0. This
indicates not to save the document into the Domino database after the Submit
button is pressed. If you want to save the document, remove the field or change the
default value to 1.

MQGetAgent
Now let's discuss the Domino Java agent that will retrieve the field values from the
form and then get the message from the queue.
The agent gets a handle to the document doc and issues a getItemValueString() to
get the host name, channel, queue manager, queue, and message. It issues a
getItemValueInteger() for the port, since the port is an integer value.
The agent sets environment values for the host name, channel, and port. The agent
creates a new queue manager, new message, and new message options objects. It
accesses the queue name and finally gets the message from the queue. If there is
still no message on the queue at that point, the get operation will wait for
approximately 10 seconds for a message. If there is no message, a Completion
Code of 2 and a Reason Code of 2033 will be printed to the Domino console. For
more information about the Java code, refer to the Java agent code explained

section.
import
com.ibm.mq.*;
import
java.io.PrintWriter;
import
lotus.domino.*;
public
class
JavaAgent
extends
AgentBase {
public
void
NotesMain()
{
try {
Session
session =
getSession();
AgentContext
agentContext
=
PrintWriter
pw =
getAgentOutput();
pw.println("Content-Type:
text/html");
pw.println("<html><head><title>DominoMQ</title></head><body>");
pw.println("<table><tr>");
pw.println("<td
width=\"200\"
rowspan=\"2\"><img
src=\"
/DominoMQ.nsf/ibmlogo-S.gif?OpenImageResource\"></td>");
pw.println("<td><img
src=\"
/DominoMQ.nsf/LOT_18P.GIF?OpenImageResource\"></td>");
pw.println("</tr><tr><td>");
pw.println("<img
src=\"
/DominoMQ.nsf/WS_18P.GIF?OpenImageResource\"></td>");
pw.println("</tr></table>");
pw.println("<body><h1>DominoMQ
Get</h1>");
String
msgText =
new
String();
Document
doc =
agentContext.getDocumentContext();
pw.println("<p>Host:
" +
doc.getItemValueString("hostName"));
pw.println("<p>Channel:
" +
doc.getItemValueString("channel"));
pw.println("<p>Port:
" +
doc.getItemValueInteger("port"));
=
doc.getItemValueString("hostName");

=
doc.getItemValueString("channel");
MQEnvironment.port
=
doc.getItemValueInteger("port");
MQQueueManager
qMgr = new
MQQueueManager(doc.getItemValueString("mqManager"));
int
openOptions
=
|
MQC.MQOO_OUTPUT;
MQQueue mqQ
=
qMgr.accessQueue(doc.getItemValueString("mqQname"),
openOptions);
MQMessage
retrievedMessage
= new
MQMessage();
MQGetMessageOptions
gmo = new
MQGetMessageOptions();
gmo.options
=
MQC.MQGMO_WAIT
|
MQC.MQGMO_FAIL_IF_QUIESCING
|
MQC.MQGMO_NO_SYNCPOINT;
gmo.waitInterval
= 10000;
mqQ.get(retrievedMessage,gmo);
msgText =
retrievedMessage.readUTF();
mqQ.close();
qMgr.disconnect();
pw.println("<h2>Message:
" + msgText
+ "</h2>");
pw.println("</body></html>");
}
ne) {
Lotus
Domino
error
occurred: "
+ ne.id + "
" +
ne.text);
}
catch
(MQException
ex) {
WebSphere
MQ error
occurred :
Completion
code " +
ex.completionCode
+ " Reason
code " +

ex.reasonCode);
}
catch
ex) {
error
occurred
writing to
the message
buffer: " +
ex);
}
catch(Exception
e) {
}
}
}
Section 7. Lotus Domino scheduled agent example
Java code for the agent

Now let's create a Domino scheduled agent that can carry out some of the functions
of our earlier example applications on a timed basis, without human intervention.
First, create a new agent in your Domino database. For Trigger, select On schedule.
Then select the Schedule button, which pops up the Agent Schedule dialog box. For
our example, we'll run the agent every hour. Select Java for the agent; the code
follows. The program will remove messages from a queue and create a Domino
document for each message. For more information about the Java code, refer to the
Java agent code explained section.
import
com.ibm.mq.*;
import
lotus.domino.*;
public
class
JavaAgent
extends
AgentBase {
public
void
NotesMain()
{
String
hostname =
"gfbrich";
String
channel =

"JAVA.CHANNEL";
Integer
port = new
Integer(1414);
String
mqManager =
"QM_gfbrich";
String
mqQname =
"SYSTEM.DEFAULT.LOCAL.QUEUE";
String
msgText =
new
String();
boolean
forever =
true;
try {
Session
session =
getSession();
AgentContext
agentContext
=
Database db
=
agentContext.getCurrentDatabase();
= hostname;
= channel;
MQEnvironment.port
=
port.intValue();
MQQueueManager
qMgr = new
MQQueueManager(mqManager);
int
openOptions
=
|
MQC.MQOO_OUTPUT;
MQQueue mqQ
=
qMgr.accessQueue(mqQname,
openOptions);
MQMessage
retrievedMessage
= new
MQMessage();
MQGetMessageOptions
gmo = new
gmo.options
=
MQC.MQGMO_WAIT
|
|
gmo.waitInterval
= 10000;
while
(forever) {

msgText =
retrievedMessage.messageId
= null;
retrievedMessage.correlationId
= null;
Document
doc =
db.createDocument();
doc.replaceItemValue("Form",
"MQScheduledGetForm");
doc.replaceItemValue("hostName",
hostname);
doc.replaceItemValue("port",
port);
doc.replaceItemValue("channel",
channel);
doc.replaceItemValue("mqManager",
mqManager);
doc.replaceItemValue("mqQname",
mqQname);
doc.replaceItemValue("message",
msgText);
if
(doc.save())
System.out.println("Document
created and
saved");
else
System.out.println("Something
went
wrong");
doc.recycle();
}
mqQ.close();
qMgr.disconnect();
}
ne) {
Lotus
Domino
error
occurred: "
+ ne.id + "
" +
ne.text);
}
catch
(MQException
ex) {
if
(ex.reasonCode
== 2033) {
//Queue is
empty
}
else
{
WebSphere
MQ error
occurred :
Completion
code " +
ex.completionCode
+ " Reason
code " +
ex.reasonCode);

}
}
catch
ex) {
error
occurred
writing to
the message
buffer: " +
ex);
}
catch(Exception
e) {
}
}
}
On the next panel, we'll look at this code in more detail.
Java agent code explained

We'll highlight some of the agent code here.
In the first part of the program, we initialize some variables. We use the class Integer
for the port because this is what Domino requires for a numeric field. Later in the
program, we use the intValue() method on the port object, which returns the primitive
int value for use by the port environment value. The last value, forever, is used for a
while loop to retrieve all messages on the queue. The code will loop forever until
there are no more messages on the queue, which will throw an exception and exit
the loop.
String
hostname =
"gfbrich";
String
channel =
"JAVA.CHANNEL";
Integer
port = new
Integer(1414);
String
mqManager =
"QM_gfbrich";
String
mqQname =
"SYSTEM.DEFAULT.LOCAL.QUEUE";
String
msgText =
new
String();
boolean
forever =
true;

The next three lines initialize the objects used for Domino. We start with a Session,
and then AgentContext, which represents the agent environment of our program.
Lastly, we get a handle to the current Domino database.
Session
session =
getSession();
AgentContext
agentContext
=
Database db
=
agentContext.getCurrentDatabase();
To connect to the WebSphere MQ server, the client relies on environment variables

to control the behavior of the connection. The variables are hostname, channel, and
port. The port value must be an int value. There are two other variables, userId and
password, if you need to use them.
= hostname;
= channel;
MQEnvironment.port
=
port.intValue();
We are now ready to connect to the queue manager. We create a new instance of
the MQQueueManager class.
MQQueueManager
qMgr = new
MQQueueManager(mqManager);
Next, we access the queue and create new message and message options objects.
One of the options you should note here is MQGMO_WAIT. This option, along with
the wait interval value, will have the program wait on a queue if there are no
messages for the desired time in milliseconds. In our example, we'll wait 10 seconds
for a message if the queue is empty.
int
openOptions
=
|
MQC.MQOO_OUTPUT;
MQQueue mqQ
=
qMgr.accessQueue(mqQname,
openOptions);
MQMessage

retrievedMessage
= new
MQMessage();
MQGetMessageOptions
gmo = new
gmo.options
=
MQC.MQGMO_WAIT
|
|
gmo.waitInterval
= 10000;
The while loop will get all messages on the queue, one at a time. It's important to set
the message and correlation IDs to null after each message is retrieved. The
program will create a new document in the Domino database. The document will
contain the host name, port, channel, queue manager, queue name, and the
retrieved message.
while
(forever) {
msgText =
retrievedMessage.messageId
= null;
retrievedMessage.correlationId
= null;
Document
doc =
db.createDocument();
doc.replaceItemValue("Form",
"MQScheduledGetForm");
doc.replaceItemValue("hostName",
hostname);
doc.replaceItemValue("port",
port);
doc.replaceItemValue("channel",
channel);
doc.replaceItemValue("mqManager",
mqManager);
doc.replaceItemValue("mqQname",
mqQname);
doc.replaceItemValue("message",
msgText);
if
(doc.save())
System.out.println("Document
created and
saved");
else
System.out.println("Something
went
wrong");
doc.recycle();
}
The last piece of code closes the queue, and disconnects from the queue manager.

mqQ.close();
qMgr.disconnect();
Section 8. Wrap up
Summary
Lotus Domino enables individuals to access information, expertise, and resources
regardless of time or geography. WebSphere MQ enables programs to communicate
with one another across a network of unlike components -- processors, operating
systems, subsystems, and communication protocols -- using a consistent application
programming interface.
Lotus Domino usually is not the only system in an enterprise. There are other
systems on other platforms. These systems could be written in Visual Basic, C,
COBOL, or the Java language, and you need to share data between Lotus Domino
and these systems. WebSphere MQ is the middleware that will enable Lotus Domino
to communicate with virtually any program on any platform you have in your
enterprise.
With Lotus Domino 6, integrating WebSphere MQ with your Domino database is

fairly simple. You create a Java library to handle your WebSphere MQ requests -- a
put and a get message, for instance. Then, through LotusScript to Java (LS2J), you
can use that library and methods to pass the host name, channel, port, queue
manager, queue name, and whatever other parameters you might have using
LotusScript.
Hopefully, this tutorial will help you integrate your Domino databases with
WebSphere MQ. Also, if you are currently using the MQSeries Link for LotusScript
(MQLSX), then this tutorial should help you move to a Java platform-based -- and
supported -- solution.

Resources
Learn
• Here are a few IBM redbooks on Domino, Domino Designer, and WebSphere
MQ.
• Domino Designer 6: A Developer's Handbook
• What's new with IBM Lotus Domino 6 for iSeries
• Upgrading to Lotus Notes and Domino 6
• Lotus Domino 6 for Linux
• IBM Lotus Domino 6 for iSeries implementation
• MQSeries primer
• MQSeries publish/subscribe applications
• The following books are available on the WebSphere MQ CD-ROM.

• WebSphere MQ Using Java
• WebSphere MQ Application Programming Guide
• WebSphere MQ Application Programming Reference
• WebSphere MQ Clients
• Stay current with developerWorks technical events and Webcasts.

Get products and technologies
• Download the sample Lotus Domino database that accompanies this tutorial.
• Build your next development project with IBM trial software, available for
download directly from developerWorks.
Discuss
• Participate in the discussion forum for this content.
About the author

George Brichacek
George Brichacek is a product marketing manager with IBM Lotus Software, IBM
Software Group, focused on application development and enterprise integration. He
has presented and developed several memorable demos for the Lotus Masters

Broadcast, as well as for customers and internal field enablement. He works with
Lotus product management to bring the latest and greatest technologies on Lotus
application development and enterprise integration to you. During his spare time, he
developed and supported a Lotus Notes utility called CalPrint. George resides in the
Chicago area. He can be reached at george_brichacek@us.ibm.com


Integrate Domino and WebSphere MQ

Încărcat de

Informații document

Descriere originală:

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

Integrate Domino and WebSphere MQ

Încărcat de

Drepturi de autor:

Formate disponibile

Integrate Domino and WebSphere MQ

Message queues unite disparate systems

Skill Level: Introductory

George Brichacek (george_brichacek@us.ibm.com)

What is this tutorial about?

The WebSphere MQ products enable programs to communicate with one another