integrate domino and websphere mq

Integrate Domino and WebSphere MQMessage queues unite disparate systems

Skill Level: Introductory

George Brichacek ([email protected])Product Marketing ManagerIBM Software Group

30 Jul 2003

Companies today have business software on disparate systems. For example, thehuman resource system might be on a Sun Solaris server, a customer relationshipmanagement system might be on Windows, and financials might be on themainframe. Companies have a need to connect these systems, and developing themiddleware to connect these systems is expensive. WebSphere MQ can connect allyour business software to form one efficient enterprise. All this integration is basedon two actions: putting messages on queues and reading them off of queues. In thistutorial, you'll learn how to perform these tasks using a Domino database and theJava platform. These simple examples will open a wide vista of integration options toyou.

Section 1. Introduction

What is this tutorial about?

Collaboration enables individuals to access information, expertise, and resourcesregardless of time or geography. Lotus Domino provides you with the means torealize this collaboration.

The WebSphere MQ products enable programs to communicate with one anotheracross a network of dissimilar components -- processors, operating systems,

Integrate Domino and WebSphere MQ© Copyright IBM Corporation 1994, 2008. All rights reserved. of 39

mailto:[email protected]

http://www.ibm.com/legal/copytrade.shtml

subsystems, and communication protocols -- using a consistent applicationprogramming interface.

This tutorial discusses how you can integrate Lotus Domino with WebSphere MQusing LotusScript and the Java platform. We'll set up two forms in Lotus Domino foruse by a Lotus Notes client -- one to put a message to, and the other to get amessage from, WebSphere MQ. Then we'll set up two more forms for the Web to dothe same thing. We could have created just two forms -- one for the Notes client andthe other for the browser client -- but by proceeding in this way, we'll see twodifferent ways to use the Java platform within Domino. Finally, we'll set up a DominoJava scheduled agent that will execute every hour to see if there are any messageson a particular queue.

Companies today have business software on disparate systems. For example, thehuman resources system might be on a Sun Solaris server, a customer relationshipmanagement system might be on Microsoft Windows, and financials might be on amainframe. Companies have a need to connect these systems, and developing themiddleware to connect these systems is expensive. WebSphere MQ can connect allyour business software to form one efficient enterprise. WebSphere MQ minimizestime taken to integrate applications on different systems, so your company canrespond quickly to new market strategies. While the examples we're using here mayseem simple, many of WebSphere MQ's integration functions are based on twoactions: putting messages on queues and reading them off of queues. Once you'velearned a few simple ways to achieve these tasks with Domino, a wide vista ofintegration options is open to you.

Who should take this tutorial?

This tutorial will be useful for developers who are working in an environment whereLotus Domino and WebSphere MQ are deployed, and who would like to know howto integrate these two products.

Also, this tutorial will be useful for developers who are using the LotusScriptextension for MQSeries (MQLSX) today. MQLSX is not supported in the LotusDomino 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 languagewithin the Domino 6 environment.

After completing this tutorial, you should know how to integrate Lotus Domino andWebSphere 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

developerWorks® ibm.com/developerWorks

Integrate Domino and WebSphere MQ of 39 © Copyright IBM Corporation 1994, 2008. All rights reserved.


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, seethe documentation that accompanies them.

This tutorial guides you through the use of a Lotus Domino database that uses theWebSphere MQ Java set of classes to put and get messages. You'll need a LotusDomino version 6 server, Domino Designer version 6, and a Lotus Notes version 6client. The Domino database will put a message and get the message from aWebSphere MQ queue. You'll also need a WebSphere MQ version 5.3 serverinstalled. If the WebSphere MQ server is not installed on the same machine as theLotus Domino server, you need to install the WebSphere MQ client on the samemachine as the Lotus Domino server.

You can download trial versions of the required Lotus software at no charge. All ofthis 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 MQproducts. The majority of SupportPacs are available at no charge. Others can bepurchased as fee-based services from IBM.

To test your WebSphere MQ installation, refer to the WebSphere MQ installationverification 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 brandfor e-business which includes many individual products and offerings. Rebrandingthe MQSeries name with the WebSphere software platform signals abetter-integrated e-business software platform. The MQSeries family of products willcontinue to grow and develop in the way that has already made it the industrystandard for integration.

Introduction to message queuing

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

ibm.com/developerWorks developerWorks®


http://www.ibm.com/developerworks/downloads/ls/lsndad/?S_TACT=103AMW13&S_CMP=TUT


potential partner applications are on, what platform they're on, what language they'rewritten in, or what communication protocol they need to use in order tocommunicate.

Applications designed and written using this interface are known as messagequeuing applications, as they use the messaging and queuing. What exactly doesthis mean?

• Programs that use messaging communicate by sending each other datain messages rather than calling each other directly.

• In queuing systems, messages are placed on queues in storage, allowingprograms to run independently of one another, at different speeds andtimes, 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 yousent an e-mail, every node would need to be available to forward the message, andthe addressee would need to be logged on and ready to accept the message. Withmessage queuing, messages are stored and then forwarded when the next systemis available to forward the message. At the final destination, the message is stored inan inbox until the addressee is ready to read it.

WebSphere MQ is middleware software for message queuing applications. There isso 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 areseveral application programming languages you can use to put and get messagesfrom 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 onthe Java language in this tutorial.

There is another interface, called the Application Messaging Interface (AMI), thatyou can use with WebSphere MQ. AMI provides a simple interface that applicationprogrammers can use without needing to understand all the functions available inMQI. The functions that are required in a particular installation are defined by asystem administrator, using services and policies. We will not discuss AMI in thistutorial, just MQI.

WebSphere MQ and the Java language

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




1. WebSphere MQ classes for the Java language. A Java program writtenin this way consists of a set of WebSphere MQ objects; you act uponthose objects by calling methods on them. For example, the queuemanager is represented by an object of class MQQueueManager. Youdisconnect from the queue manager by calling the disconnect() methodon that class, like so:

// declare an object of type queue managerMQQueueManager queueManager=new MQQueueManager();...// do something......// disconnect from the queue managerqueueManager.disconnect();

2. WebSphere MQ classes for the Java Message Service (WebSphereMQ JMS). The Java Message Service (JMS) defines a generic view of amessage-passing service. The generic JMS model is based around thefollowing interfaces, which are defined in Sun's javax.jms package:

• Connection: Provides access to the underlying transport, and is usedto create Sessions.

• Session: Provides a context for producing and consuming messages,including the methods used to create MessageProducers andMessageConsumers.

• MessageProducer: Used to send messages.

• MessageConsumer: Used to receive messages.

This tutorial focuses on the WebSphere MQ classes for the Java language. TheWebSphere MQ classes for JMS use a JNDI namespace for their administeredobjects, which is the expected operation of JMS client applications. Setting up aJNDI-based repository is relatively complex, and hence is beyond the scope of thistutorial.

WebSphere MQ messages

Messages are data sent from one program to another. A message consists of twoparts, the message descriptor and the application data, as illustrated below.




When a message is exchanged, the receiving program needs to know the layout ofthe data. For example, suppose the message describes a person. The first 12 bytesof 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 thesecond address line, and we could continue on from there. The receiving programwould know all this in advance and parse the message to extract the various parts ofthe person message.

On the other hand, the message could be an order number, and the sendingprogram might like to know more about the order. The sending program would sendthe 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 affectthe way you create messages.

• What type of message should I use? Are you designing a simpleapplication in which you can send a message and then take no furtheraction? Or are you asking for a reply to a question? Do you want yourrequest and reply messages to be synchronous? This implies that you seta timeout period for the reply to answer your request, and, if you do notreceive the reply within that period, your application treats the exchangeas an error. Or would you prefer to work asynchronously, so that yourprocesses 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 Icreate? You can assign a priority value to each message, and define thequeue so that it maintains its messages in order of their priority. If you dothis, when another program retrieves a message from the queue, italways gets the message with the highest priority. If the queue does notmaintain its messages in priority order, a program that retrievesmessages from the queue will retrieve them in the order in which theywere added to the queue. Programs can also select a message using theidentifier that the queue manager assigned when the message was put onthe queue. Alternatively, you can generate your own identifiers for each ofyour 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 notpreserved. Any messages that you do not want discarded must bedefined as persistent when they are created.

• Do I want to give information about myself to the recipient of mymessages? Normally, the queue manager sets the user ID, but suitablyauthorized applications can also set this field, so that you can includeyour own user ID and other information that the receiving program canuse for accounting or security purposes.

• Will the message be a string, number, or something else? The layoutof the message must be understood by both the sending program and thereceiving program. The sending program will construct the message andthe receiving program must deconstruct the message in the same way itwas built.

Types of messages

You can create several different types of messages. These are four of the mostcommon:

• Datagram: You should use a datagram when you do not require a replyfrom the application that receives the message.

• Request: You should use a request message when you want a reply fromthe application that receives the message.

• Reply: You should use a reply message when you reply to anothermessage.

• Report: Report messages inform applications about events such as theoccurrence of an error when processing a message. They can begenerated at any time, and they may arrive on a queue when yourapplication 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 ApplicationProgramming Guide, which is available on the WebSphere MQ CD-ROM. Thedocumentation is also available online in HTML and PDF formats after installingWebSphere MQ.




Application data in the message

The receiving program needs to know the layout of the application data in themessage; therefore, the sending program needs to conform to that layout or thingscan get messy.

The application data in the message can be in any format. As described in ourprevious 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 putprogram 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 andstandardizing on message layouts for your system ahead of time. That way, whenapplications are developed, they adhere to the standard message layout.

In our Java language example later in this tutorial, we'll use a string for theapplication 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, anduse the writeXXX() methods to put data into the message buffer.

The following Java code creates a message and puts it onto a queue. You firstcreate the message, then put any type of data into the message buffer in the orderyou want. For example, you write the age first with the writeInt() method, then youwrite the string name with the writeUTF() method. This is just one example; there areseveral 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 queueMQMessage theMessage = new MQMessage();MQGetMessageOptions gmo = new MQGetMessageOptions();queue.get(theMessage,gmo);

// Extract the message dataint 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 MQCD-ROM. The documentation is also available online in HTML and PDF formatsafter installing WebSphere MQ.

WebSphere MQ queues

A WebSphere MQ queue is a named object on which applications can putmessages, and from which applications can get messages. Messages are stored ona queue, so if the putting application expects a reply to its message, it is free to doother work while waiting for that reply. Applications access a queue by using theMessage Queue Interface (MQI).

Before a message can be put on a queue, the queue must have already beencreated. A queue is owned by a queue manager, and that queue manager can ownmany queues. However, each queue must have a name that is unique amongqueues managed by a single queue manager.

Before using a queue, you must open it in your application program, specifying whatyou 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 isowned by the queue manager to which the program is connected. Thequeue is known as remote if it is owned by a different queue manager.The important difference between these two types of queue is that youcan get messages only from local queues. (You can put messages onboth local and remote queues.)

• Shared queues (only available on WebSphere MQ for z/OS). A sharedqueue is a type of local queue whose messages can be accessed by oneor 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 accessanother queue. This means that more than one program can work withthe same queue, each program accessing it under a different name.

• Model and dynamic queues. A model queue is a template of a queuedefinition used only when you want to create a dynamic local queue. Youcan create a local queue dynamically from your application program,naming the model queue you wish to use as the template for the queueattributes.

• Cluster queues. A cluster queue is a queue that is hosted by a clusterqueue manager and made available to other queue managers in thecluster.

For more information about queues, refer to the WebSphere MQ ApplicationProgramming Guide, which is available on the WebSphere MQ CD-ROM. Thedocumentation is also available online in HTML and PDF formats after installingWebSphere MQ.

Section 3. WebSphere MQ installation verification

Servers and client installation

Before going any further, you should test your installation of WebSphere MQ. Thereare 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, andthe WebSphere MQ server is on another box.

2. Lotus Domino server and the WebSphere MQ server are on the samebox. With this setup, the WebSphere MQ client code is already installedwith the WebSphere MQ server.

The following two illustrations highlight these installations. For our purposes, itdoesn't matter which way you install the servers; this tutorial and the sample codewill 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 incomingconnection 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 strmqmcommand.

2. Type the following command to start the runmqsc program:

runmqsc [QMNAME]

3. Define a sample channel called JAVA.CHANNEL by issuing the followingcommand:

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 thefollowing commands:

runmqlsr -t tcp [-m QMNAME] -p 1414




5. Change to your WebSphere MQ samples directory (by default it isC:\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 MQIVPprogram, 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 -- Entereither the IP address or the hostname of the machine where your queuemanager is installed.

• Please enter the port to connect to -- Enter the default port,1414.

• Please enter the server connection channel name -- EnterJAVA.CHANNEL, which we created in the previous panel, or enter anexisting channel you've already created.

• Please enter the queue manager name -- Enter the queuemanager name.

The program connects to your queue manager, puts a message on a queue, getsthe message from the queue, and then disconnects. You should see a messageindicating that the MQ transport is functioning correctly, which should look somethinglike this:




Now that you have WebSphere MQ installed, you're ready to write Domino code thattakes advantages of its features.

Section 4. Lotus Domino and WebSphere MQ

Support issues

The majority of organizations integrating Lotus Domino and WebSphere MQ todayare using the MQSeries Link for LotusScript. This product supports Domino R4 andR5, and MQSeries 5.2 and WebSphere MQ 5.3. (Note that in the transition fromversion 5.2 to 5.3 of this software, IBM integrated MQSeries into its WebSphereofferings, which is the reason for the name change.) The MQSeries Link forLotusScript (MQLSX) will not be supported in the Domino 6 environment, and itsend-of-service date is December 31, 2004. Furthermore, you will no longer be ableto download MQLSX after January 2, 2004.

As you move forward with Lotus Domino 6 and WebSphere MQ 5.3, it isrecommended that you write any new solutions in the Java language.

The question now is: How do we move from MQLSX to the Java platform? Hopefullythis tutorial will provide some guidance.




Java runtime environments

When integrating Lotus Domino and WebSphere MQ, be aware of the Java runtimeenvironment. Lotus Domino 5 supports Java v1.1.8, and WebSphere MQ 5.3requires Java 2 v1.3. So, if you are planning on using WebSphere MQ 5.3, you needto 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. Youneed to install the SupportPac MA88: MQSeries classes for Java and MQSeriesclasses for Java Message Service. For more information about SupportPacs, visitWebSphere MQ SupportPacs.

Lotus Domino 6 and LotusScript to Java

One possible solution to integrate Lotus Domino and WebSphere MQ is to use anew feature in Lotus Domino 6 called LotusScript to Java (LS2J). It allowsLotusScript to access Java classes. Developers can access Java in LotusScriptprograms as a set of predefined LotusScript objects. This set of objects allowsLotusScript to use existing Java classes that are available in script libraries or foundusing the classpath. The Java classes we'll use in this tutorial put a message on aqueue and get a message from a queue.

Using LS2J with Lotus Domino 6 allows developers to take advantage of all theLotusScript front-end and back-end classes, instead of a writing a solution entirely inthe 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 forthe browser client, and the last is a scheduled agent to get a message off of aqueue. The first example uses LS2J and the second uses a Lotus Domino agentwritten entirely in the Java language. These first two examples put a message on aqueue and get a message from a queue. The third example is a scheduled agentthat will only get a message off of a queue. This last example is written entirely inJava code, too.

Section 5. Lotus Notes client example

Java library



http://www.ibm.com/software/integration/support/supportpacs/


The first example is for the Lotus Notes client. In this panel, we'll highlight the designof the sample database that we'll be accessing with the client. (You can downloadthe complete database from Resources.)

The first part of the database we will discuss is the Java code used to put amessage on a queue and to get a message from a queue. With Lotus DominoDesigner 6, you have the capability to create Java libraries, just like you've beenable to create LotusScript libraries in the past.

You should be able to use the sample database with no modifications, but there aresome setup steps you'll need to walk through for Lotus Notes and Domino to workproperly. First, you'll need to edit the Java user classes parameter in the Notes.inifile. 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 theLotus Domino server file. For this example, we've assumed that WebSphere MQ isinstalled at C:\WebSphereMQ\; obviously, you'll need to change this to match yourenvironment.

Download the sample database and move it to your Domino 6 server. Open theDomino Designer 6 client and the sample database. Expand Shared Code andScript 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 thissection. 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 indicatesthat 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 2Runtime Environment, Standard Edition 1.3.1 and java.exe is located inc:\lotus\domino\jvm\bin. Make sure you are using this executable.

There is a workaround. Copy mqjbnd05.dll to the Lotus Domino binary directory (bydefault, 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 fieldsare 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 thatwill invoke the Java putMessage() method, which puts a message on a queue. In theOptions section, it's important to include the Use statement; this is where the Javacode is located. The Uselsx statement is required to use LS2J; it's the LotusScriptextension that allows LotusScript to execute Java methods. The Declarationssection initializes the objects. The Click routine sets the objects and gets the valuesfrom the form and invokes the Java putMessage() method.

(Options)Use "DominoMQC"Uselsx "*javacon"

(Declarations)'New LotusScript classes that access JavaDim mySession As JavaSessionDim myClass As JavaClassDim myObject As JavaObject

Dim port As IntegerDim ws As NotesUIWorkSpace




Dim uidoc As NotesUIDocument

Sub Click(Source As Button)'Initialize a Java sessionSet mySession = New JavaSession()'Initialize a Java classSet myClass = mySession.GetClass("MQPutC")'Initialize a Java objectSet myObject = myClass.CreateObject

Set ws = New NotesUIWorkspaceSet 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 methodreturnStatus = myObject.putMessage( hostName, port, channel, mqManager, _

mqQname, message )

If Isempty( returnStatus ) ThenCall uidoc.FieldSetText( "Errors", "MQ Put Message Successful" )

ElseCall uidoc.FieldSetText( "Errors", returnStatus )

End IfEnd Sub

MQPutC.java

The following is the Java code used to put a message on a queue. This is the codethat our put form from the previous panel is accessing. For more information aboutthe 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;return returnStatus;

}return returnStatus;

}}

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 inputparameters 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 fieldsare the input to the Java getMessage() method and the last is a field for themessage.




Now let's look at the code behind the form. The following listing is the LotusScriptcode 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 theUselsx statement is required to use LS2J. The Click routine here sets the objectsand gets the values from the form and invokes the Java getMessage() method.

(Options)Use "DominoMQC"Uselsx "*javacon"

(Declarations)'New LotusScript classes that access JavaDim mySession As JavaSessionDim myClass As JavaClassDim myObject As JavaObject

Dim port As IntegerDim ws As NotesUIWorkSpaceDim uidoc As NotesUIDocument

Sub Click(Source As Button)




'Initialize a Java sessionSet mySession = New JavaSession()'Initialize a Java classSet myClass = mySession.GetClass("MQGetC")'Initialize a Java objectSet myObject = myClass.CreateObjectSet ws = New NotesUIWorkspaceSet 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 methodmessage = 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 thecode that our get form from the previous panel is accessing. For more informationabout 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) {e.printStackTrace();

}}

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 inthe previous panel, this is the method we call from LotusScript in the Dominodatabase. 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 10seconds for a message on the queue. The get message options value ofMQC.MQGMO_WAIT indicates to wait and waitInterval indicates the time to wait, inmilliseconds. If you don't want the program to wait the 10 seconds, remove the waitparameter 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, onefor the put message and the other for the get message. For each form, there is acorresponding Domino Java agent.




For the Java agents to call WebSphere MQ, you need to update the Java userclasses parameter in the Notes.ini file for the Domino server. Shut down the Dominoserver, 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 atC:\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 thecorresponding Notes client, but the Web form has a WebQuerySave event toexecute 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. Thisindicates not to save the document into the Domino database after the Submitbutton is pressed. If you want to save the document, remove the field or change thedefault value to 1.




MQPutAgent

Now let's examine the Domino Java agent that will retrieve the field values from theform and then put the message on the queue.

The agent gets a handle to the document doc and issues a getItemValueString() toget the host name, channel, queue manager, queue, and message. It issues agetItemValueInteger() for the port, since the port is an integer value.

The agent sets environment values for the host name, channel, and port. The agentcreates a new queue manager, new message, and new message options objects. Itaccesses the queue name and, finally, puts the message on the queue. For moreinformation about the Java code, refer to the Java agent code explained section.

Here's the code:




importcom.ibm.mq.*;importjava.io.PrintWriter;importlotus.domino.*;publicclassJavaAgentextendsAgentBase {public

voidNotesMain(){

try {Sessionsession =getSession();AgentContextagentContext=session.getAgentContext();PrintWriterpw =getAgentOutput();pw.println("Content-Type:text/html");pw.println("<html><head><title>DominoMQ</title></head><body>");pw.println("<table><tr>");pw.println("<tdwidth=\"200\"rowspan=\"2\"><imgsrc=\"/DominoMQ.nsf/ibmlogo-S.gif?OpenImageResource\"></td>");pw.println("<td><imgsrc=\"/DominoMQ.nsf/LOT_18P.GIF?OpenImageResource\"></td>");pw.println("</tr><tr><td>");pw.println("<imgsrc=\"/DominoMQ.nsf/WS_18P.GIF?OpenImageResource\"></td>");pw.println("</tr></table>");pw.println("<body><h1>DominoMQPut</h1>");Documentdoc =agentContext.getDocumentContext();StringreturnStatus= 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);MQQueueManagerqMgr = newMQQueueManager(doc.getItemValueString("mqManager"));

intopenOptions=MQC.MQOO_INPUT_AS_Q_DEF|MQC.MQOO_OUTPUT;MQQueue mqQ=qMgr.accessQueue(doc.getItemValueString("mqQname"),openOptions);MQMessagemqMsg = newMQMessage();mqMsg.writeUTF(doc.getItemValueString("message"));MQPutMessageOptionspmo = newMQPutMessageOptions();mqQ.put(mqMsg,pmo);mqQ.close();qMgr.disconnect();pw.println("<h2>Messagesuccessfullyput</h2>");pw.println("</body></html>");

}catch(NotesExceptionne) {System.out.println("ALotusDominoerroroccurred: "+ ne.id + "" +ne.text);

}catch

(MQExceptionex) {System.out.println("AWebSphereMQ erroroccurred :Completioncode " +ex.completionCode+ " Reasoncode " +ex.reasonCode);

}catch

(java.io.IOExceptionex) {System.out.println("Anerroroccurredwriting tothe messagebuffer: " +ex);

}




catch(Exceptione) {e.printStackTrace();

}}

}

MQGetC Web form

The get message form for the Web has the same number of fields as thecorresponding Notes client, but the Web form has a WebQuerySave event toexecute 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. Thisindicates not to save the document into the Domino database after the Submitbutton is pressed. If you want to save the document, remove the field or change thedefault value to 1.




MQGetAgent

Now let's discuss the Domino Java agent that will retrieve the field values from theform and then get the message from the queue.

The agent gets a handle to the document doc and issues a getItemValueString() toget the host name, channel, queue manager, queue, and message. It issues agetItemValueInteger() for the port, since the port is an integer value.

The agent sets environment values for the host name, channel, and port. The agentcreates a new queue manager, new message, and new message options objects. Itaccesses the queue name and finally gets the message from the queue. If there isstill no message on the queue at that point, the get operation will wait forapproximately 10 seconds for a message. If there is no message, a CompletionCode of 2 and a Reason Code of 2033 will be printed to the Domino console. Formore information about the Java code, refer to the Java agent code explained




section.

importcom.ibm.mq.*;importjava.io.PrintWriter;importlotus.domino.*;publicclassJavaAgentextendsAgentBase {public

voidNotesMain(){

try {Sessionsession =getSession();AgentContextagentContext=session.getAgentContext();PrintWriterpw =getAgentOutput();pw.println("Content-Type:text/html");pw.println("<html><head><title>DominoMQ</title></head><body>");pw.println("<table><tr>");pw.println("<tdwidth=\"200\"rowspan=\"2\"><imgsrc=\"/DominoMQ.nsf/ibmlogo-S.gif?OpenImageResource\"></td>");pw.println("<td><imgsrc=\"/DominoMQ.nsf/LOT_18P.GIF?OpenImageResource\"></td>");pw.println("</tr><tr><td>");pw.println("<imgsrc=\"/DominoMQ.nsf/WS_18P.GIF?OpenImageResource\"></td>");pw.println("</tr></table>");pw.println("<body><h1>DominoMQGet</h1>");StringmsgText =newString();Documentdoc =agentContext.getDocumentContext();pw.println("<p>Host:" +doc.getItemValueString("hostName"));pw.println("<p>Channel:" +doc.getItemValueString("channel"));pw.println("<p>Port:" +doc.getItemValueInteger("port"));MQEnvironment.hostname=doc.getItemValueString("hostName");MQEnvironment.channel




=doc.getItemValueString("channel");MQEnvironment.port=doc.getItemValueInteger("port");MQEnvironment.properties.put(MQC.TRANSPORT_PROPERTY,MQC.TRANSPORT_MQSERIES);MQQueueManagerqMgr = newMQQueueManager(doc.getItemValueString("mqManager"));

intopenOptions=MQC.MQOO_INPUT_AS_Q_DEF|MQC.MQOO_OUTPUT;MQQueue mqQ=qMgr.accessQueue(doc.getItemValueString("mqQname"),openOptions);MQMessageretrievedMessage= newMQMessage();MQGetMessageOptionsgmo = newMQGetMessageOptions();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>");


}catch

(MQExceptionex) {System.out.println("AWebSphereMQ erroroccurred :Completioncode " +ex.completionCode+ " Reasoncode " +




ex.reasonCode);}catch


}catch(Exceptione) {e.printStackTrace();

}}

}

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 functionsof 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. Forour example, we'll run the agent every hour. Select Java for the agent; the codefollows. The program will remove messages from a queue and create a Dominodocument for each message. For more information about the Java code, refer to theJava agent code explained section.

importcom.ibm.mq.*;importlotus.domino.*;publicclassJavaAgentextendsAgentBase {public

voidNotesMain(){

Stringhostname ="gfbrich";

Stringchannel =




"JAVA.CHANNEL";Integer

port = newInteger(1414);

StringmqManager ="QM_gfbrich";

StringmqQname ="SYSTEM.DEFAULT.LOCAL.QUEUE";

StringmsgText =newString();

booleanforever =true;

try {Sessionsession =getSession();AgentContextagentContext=session.getAgentContext();Database db=agentContext.getCurrentDatabase();MQEnvironment.hostname= hostname;MQEnvironment.channel= channel;MQEnvironment.port=port.intValue();MQEnvironment.properties.put(MQC.TRANSPORT_PROPERTY,MQC.TRANSPORT_MQSERIES);MQQueueManagerqMgr = newMQQueueManager(mqManager);

intopenOptions=MQC.MQOO_INPUT_AS_Q_DEF|MQC.MQOO_OUTPUT;MQQueue mqQ=qMgr.accessQueue(mqQname,openOptions);MQMessageretrievedMessage= newMQMessage();MQGetMessageOptionsgmo = newMQGetMessageOptions();gmo.options=MQC.MQGMO_WAIT|MQC.MQGMO_FAIL_IF_QUIESCING|MQC.MQGMO_NO_SYNCPOINT;gmo.waitInterval= 10000;

while(forever) {mqQ.get(retrievedMessage,gmo);




msgText =retrievedMessage.readUTF();retrievedMessage.messageId= null;retrievedMessage.correlationId= null;Documentdoc =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("Documentcreated andsaved");elseSystem.out.println("Somethingwentwrong");doc.recycle();

}mqQ.close();qMgr.disconnect();


}catch

(MQExceptionex) {

if(ex.reasonCode== 2033) {//Queue isempty

}else

{System.out.println("AWebSphereMQ erroroccurred :Completioncode " +ex.completionCode+ " Reasoncode " +ex.reasonCode);




}}catch


}catch(Exceptione) {e.printStackTrace();

}}

}

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 Integerfor the port because this is what Domino requires for a numeric field. Later in theprogram, we use the intValue() method on the port object, which returns the primitiveint value for use by the port environment value. The last value, forever, is used for awhile loop to retrieve all messages on the queue. The code will loop forever untilthere are no more messages on the queue, which will throw an exception and exitthe loop.

Stringhostname ="gfbrich";Stringchannel ="JAVA.CHANNEL";Integerport = newInteger(1414);StringmqManager ="QM_gfbrich";StringmqQname ="SYSTEM.DEFAULT.LOCAL.QUEUE";StringmsgText =newString();booleanforever =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.

Sessionsession =getSession();AgentContextagentContext=session.getAgentContext();Database db=agentContext.getCurrentDatabase();

To connect to the WebSphere MQ server, the client relies on environment variablesto control the behavior of the connection. The variables are hostname, channel, andport. The port value must be an int value. There are two other variables, userId andpassword, if you need to use them.

MQEnvironment.hostname= hostname;MQEnvironment.channel= channel;MQEnvironment.port=port.intValue();

We are now ready to connect to the queue manager. We create a new instance ofthe MQQueueManager class.

MQQueueManagerqMgr = newMQQueueManager(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 withthe wait interval value, will have the program wait on a queue if there are nomessages for the desired time in milliseconds. In our example, we'll wait 10 secondsfor a message if the queue is empty.

intopenOptions=MQC.MQOO_INPUT_AS_Q_DEF|MQC.MQOO_OUTPUT;MQQueue mqQ=qMgr.accessQueue(mqQname,openOptions);MQMessage




retrievedMessage= newMQMessage();MQGetMessageOptionsgmo = newMQGetMessageOptions();gmo.options=MQC.MQGMO_WAIT|MQC.MQGMO_FAIL_IF_QUIESCING|MQC.MQGMO_NO_SYNCPOINT;gmo.waitInterval= 10000;

The while loop will get all messages on the queue, one at a time. It's important to setthe message and correlation IDs to null after each message is retrieved. Theprogram will create a new document in the Domino database. The document willcontain the host name, port, channel, queue manager, queue name, and theretrieved message.

while(forever) {mqQ.get(retrievedMessage,gmo);msgText =

retrievedMessage.readUTF();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("Documentcreated andsaved");else

System.out.println("Somethingwentwrong");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 resourcesregardless of time or geography. WebSphere MQ enables programs to communicatewith one another across a network of unlike components -- processors, operatingsystems, subsystems, and communication protocols -- using a consistent applicationprogramming interface.

Lotus Domino usually is not the only system in an enterprise. There are othersystems 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 Dominoand these systems. WebSphere MQ is the middleware that will enable Lotus Dominoto communicate with virtually any program on any platform you have in yourenterprise.

With Lotus Domino 6, integrating WebSphere MQ with your Domino database isfairly simple. You create a Java library to handle your WebSphere MQ requests -- aput and a get message, for instance. Then, through LotusScript to Java (LS2J), youcan use that library and methods to pass the host name, channel, port, queuemanager, queue name, and whatever other parameters you might have usingLotusScript.

Hopefully, this tutorial will help you integrate your Domino databases withWebSphere 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 -- andsupported -- solution.




Resources

Learn

• Here are a few IBM redbooks on Domino, Domino Designer, and WebSphereMQ.

• 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 fordownload directly from developerWorks.

Discuss

• Participate in the discussion forum for this content.

About the author

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



http://publib-b.boulder.ibm.com/Redbooks.nsf/9445fa5b416f6e32852569ae006bb65f/11473411839829d285256bc200513eca?OpenDocument

http://publib-b.boulder.ibm.com/Redbooks.nsf/9445fa5b416f6e32852569ae006bb65f/f99ba2232229850085256c46006e08ab?OpenDocument

http://publib-b.boulder.ibm.com/Redbooks.nsf/9445fa5b416f6e32852569ae006bb65f/d095795dec90e99285256c2a0042bc55?OpenDocument

http://publib-b.boulder.ibm.com/Redbooks.nsf/9445fa5b416f6e32852569ae006bb65f/984a1b2d1cf9a13a85256b900051c393?OpenDocument

http://publib-b.boulder.ibm.com/Redbooks.nsf/9445fa5b416f6e32852569ae006bb65f/c2563f36eef996e485256b6c005f5f7f?OpenDocument

http://publib-b.boulder.ibm.com/Redbooks.nsf/9445fa5b416f6e32852569ae006bb65f/cdce1eb0c77b2105852569900072a3f4?OpenDocument

http://publib-b.boulder.ibm.com/Redbooks.nsf/9445fa5b416f6e32852569ae006bb65f/2515e2d9a5b242b785256a4000588c70?OpenDocument

http://www.ibm.com/developerworks/offers/techbriefings/?S_TACT=103AMW13&S_CMP=TUT

DominoMQC.nsf

http://www.ibm.com/developerworks/downloads/?S_TACT=103AMW13&S_CMP=TUT

http://www-128.ibm.com/developerworks/community/


Broadcast, as well as for customers and internal field enablement. He works withLotus product management to bring the latest and greatest technologies on Lotusapplication development and enterprise integration to you. During his spare time, hedeveloped and supported a Lotus Notes utility called CalPrint. George resides in theChicago area. He can be reached at [email protected]



mailto:[email protected]


integrate domino and websphere mq

Documents