Working with example WebSphere MQ Everyplace scenarios

The set of sample files described in this topic give you a quick start at connecting WebSphere MQ Everyplace to a WebSphere Business Integration Event Broker broker. With these samples, you can:

You can modify any of the samples provided. If you do so, you must recompile the Java source code.

The following steps explain how to run the example.

  1. Set up the CLASSPATH for every system from which you will run programs that communicate with WebSphere MQ Everyplace within WebSphere Business Integration Event Broker and with WebSphere MQ Everyplace itself (standalone). You need to add:
    • install_dir\classes\mqimqe.jar;
    • install_dir\classes\MQeDevice.jar;
    • install_dir\classes\MQeExamples.jar;
    • install_dir\classes\MQeGateway.jar;
    • install_dir\classes\MQeMQBridge.jar;

    On some versions of Windows, there is a limit of 255 characters in a CLASSPATH setting. To avoid encountering this restriction, you can assign these to a new environment variable, for example MQEPATH, and add %MQEPATH%; to your CLASSPATH.

  2. Copy the example files from the directory install_dir\sample\MQe to a directory of your choice.
    1. Copy the following .ini files:
      • ClientQM1.ini
      • ServerQM1.ini

      Start of changeThese .ini files are used by the CreateQueueManager program (and ServerQM1.ini can be used as a configuration file for the node), during the sample setup, to specify the properties of the WebSphere MQ Everyplace queue managers, and create appropriate directory structures. Therefore the directory name specified in the Registry section of the .ini file should be amended to be valid for the operating system the command is being executed on. End of change

      Start of changeWithin each file, find the Registry section:
      *------------------------------------------------------------------------*
      *
      *  Registry ( configuration data store )
      *
      [Registry]
      *
      *   Type of registry for config data
      *
      (ascii)LocalRegType=FileRegistry
      *
      *   Location of the registry
      *
      (ascii)DirName=C:\ClientQM1\Registry\
      *------------------------------------------------------------------------*
      and update the directory name in this section to the correct value for the operating system on which you are to invoke the CreateQueueManager command. For example, (ascii)DirName=/home/wmqiuser/ClientQM1/Registry/End of change

      Start of changeThe directory specified must be able to be created and written to by the user running the CreateQueueManager program.End of change

    2. Copy the following Java source files to the same directory:
      • SendMessages.java
      • SendPubSubMessages.java
      • SetupMQeExample1.java
      • SetupMQeExample2.java
    3. Compile the Java source files.
  3. Create WebSphere MQ Everyplace queue managers on the WebSphere MQ Everyplace client. The file name is case sensitive; specify it exactly as shown.

    At a command prompt, type:

    java examples.install.CreateQueueManager

    In the Configuration File box, browse for and select the ClientQM1.ini file. Set the directory for the queues to be the directory above the one that was specified in step 2.a, for example c:\ClientQM1. Click OK.

    A WebSphere MQ Everyplace client queue manager is created with a name ClientQM1, with a registry located at c:\ClientQM1\Registry.

  4. Create the WebSphere MQ Everyplace server queue manager within WebSphere Business Integration Event Broker. The file name is case sensitive; specify it exactly as shown.

    At a command prompt, type:

    java examples.install.CreateQueueManager

    In the Configuration File box, browse for and select the ServerQM.ini file. Set the directory for the queues to be the directory above the one that was specified in step 2.a, for example c:\ServerQM1. Click OK.

    A WebSphere MQ Everyplace server queue manager is created with a name ServerQM1, with a registry located at c:\ServerQM1\Registry.

    If you browse the sample ServerQM1.ini file, you might see that the listener is set to listen on port 8081. This setting is ignored on the creation of the queue manager. Later in the configuration, if you configure the MQeInput node to use configuration file values, this port number is used.

    If you get an error on creating the server queue manager with text:
    com.ibm.broker.mqimqe.examples.rule.AttributeRule
    check that you have correctly referenced install_dir\classes\mqimqe.jar in the CLASSPATH.
  5. Configure message flows. You can either add WebSphere MQ Everyplace nodes to existing message flows or create new flows. Switch to the Broker Application Development perspective. Add the nodes into the message flow. For point-to-point (non publish/subscribe) messaging, you must include an MQeInput node and an MQeOutput node. For publish/subscribe messaging, you must include an MQeInput node and a Publication node.
    Configuring the MQeInput node

    Start of changeYou must specify the Queue Name on the General page; each MQeInput node must have a different queue name. In step 8 below, the example uses the queue name, MQeInputQ1. Set the Directory property on the Registry page to contain the same value that you set in the .ini files. You can set the directory property either in the node's properties dialog or in the MQeInput node's configurable properties in the bar file before you deploy. If the Directory property does not specify the correct location of the WebSphere MQ Everyplace registry, the WebSphere MQ Everyplace queue manager cannot be started. End of change

    You might also want to make other configuration changes (for example, setting the level of trace) but this is not necessary to run these scripts.

    Start of changeIf you wish to configure the MQeInput node using a config file (by selecting the Use Config File checkbox on the MQeInput node) it is essential that the format used is like that in the install_dir\sample\MQe\ServerQM1.ini and that the file's line terminators are in the Windows format; Carriage Return, Line Feed (CRLF x'0D0A'). One method to ensure that the line terminators are correct is to edit the config file on Windows and use FTP to transfer the file to UNIX using the binary mode to maintain the line terminators as CRLF. End of change

    If a line terminator other than CRLF (x'0D0A') is used, a WebSphere MQ Everyplace queue manager error occurs.

    Configuring the MQeOutput node
    Select Advanced in the properties dialog navigator. Check that the Destination Mode is set to Destination List. Leave all other fields blank.
    Configuring the Publication node
    No action required.
  6. Deploy the message flow.

    Save the message flow and check that it has no errors. Add the message flow to a bar file and deploy that to the broker.

    Check that the deploy is successful in the Event Log. You can expect to see messages BIP4040I and BIP2056I.

    • The client queue manager is started when the client starts.
    • The server queue manager is only started when an MQeInput node is running and is deployed in a flow where a WebSphere Business Integration Event Broker broker is running.
    • Deploying a point-to-point message flow (MQeInput to MQeOutput) also starts the WebSphere MQ Everyplace server queue manager.
    If the wrong WebSphere MQ Everyplace registry is specified (see step 2.a and step 5) or a configuration file is used with the wrong line terminators (see step 5), the system log will report BIP2111E and BIP4202S, indicating that the WebSphere MQ Everyplace queue manager failed to start.
  7. Set up the WebSphere MQ Everyplace queue managers.

    Compile and run the SetupMQeExample1 and SetupMQeExample2 programs to set up the WebSphere MQ Everyplace queue managers.

    • SetupMQeExample1 creates a route so that the client queue manager can contact the server queue manager.
    • SetupMQeExample2 creates a queue on the server queue manager called Inbox that can be used in the examples for returning messages.

    These programs take the following parameters. SetupMQeExample1 requires all five parameters, in the sequence shown. SetupMQeExample2 requires the first two only.

    1. WebSphere MQ Everyplace queue manager name (ServerQM1 in this example).
    2. The path to the WebSphere MQ Everyplace client configuration file (ClientQM1.ini in this example).
    3. The IP address of the WebSphere MQ Everyplace server (1.23.45.678 in this example).
    4. The port on which the WebSphere MQ Everyplace server is listening. The port number must match the value set for the Port property. Select Listener in the MQeInput node properties dialog navigator to set this property. The default value for Port is 8081.
    5. The name of the WebSphere MQ queue manager hosting the WebSphere Business Integration Event Broker broker (for example, WBRK_QM).
    For example, at a command prompt type:
    java SetupMQeExample1 ServerQM1 ClientQM1.ini 1.23.45.678 8081 WBRK_QM
  8. Send messages through the message flows.
    • For point-to-point messages, use the program SendMessages. This sends a message using both the MQeMsgObj class and the MQeMbMsgObj class.
    • For publish/subscribe messages, use the program SendPubSubMessages. This subscribes, publishes, reads the message, and unsubscribes.
    Both these programs take the following five parameters, all of which must be present in the order shown:
    1. The WebSphere MQ Everyplace queue manager name (ServerQM1 in this example).
    2. The path to the WebSphere MQ Everyplace client configuration file (ClientQM1.ini).
    3. The name of the WebSphere MQ queue manager hosting the WebSphere Business Integration Event Broker broker (for example WBRK_QM).
    4. The name of the WebSphere MQ bridge queue receiving the input (the queue you named on the MQInput node Queue Name property; for example MQeInputQ1).
    5. The name of the WebSphere MQ Everyplace queue where you want to receive messages back from the broker. The sample code creates a queue called Inbox but if you already have a WebSphere MQ Everyplace queue defined, you can specify that queue.
      If this queue does not exist, you receive the exception:
      The message retrieved did not contain all of the expected fields.
      If you get this exception but the queue has been created, the limit of retrieve attempts has been reached, and no message can be retrieved.
    For example, to send point-to-point messages, type the following command at a command prompt:
    java SendMessages ServerQM1 ClientQM1.ini WBRK_QM MQeInputQ1 Inbox

    If you send a message to the broker that is constructed using an MQeMsgObject object (when all fields are passed to the broker) the output is similar to:

    Reading message from queue
    Message:         This is the payload
    Own message tag: My own tag with some data

    If you send a message to the broker that is constructed using an MQeMbMsgObject object (when only the fields compatible within the broker are sent) the output is similar to:

    Reading message from queue
    Message:         This is the payload

    For example, to send publish/subscribe messages, type the following command at a command prompt:

    java SendPubSubMessages ServerQM1 ClientQM1.ini WBRK_QM MQeInputQ1 Inbox

    If messages are sent and received successfully, you should see output similar to:

    Started queue manager: ClientQM1
    Subscribing to the topics:
    climate
    humidity
    temperature
    Put message to QM/queue: WBRK_QM/MQeInputQ2
    Publishing message to topic 'climate'
    Reading message from queue
    Topic:  climate
    Message: sunny
    un-subscribing from the topics:
    climate
    humidity
    temperature
    Put message to QM/queue: WBRK_QM/MQeInputQ2

    (where MQeInputQ2 is the name of the MQeInput node used).

    If, after the sample attempts to put a message to the broker queue manager and the WebSphere MQ bridge queue, you see the following WebSphere MQ Everyplace exception:
    java.net.ConnectException: Connection refused
    you must check:
    1. The broker is started (mqsistart brokername).
    2. The port number that you specified when you ran SetupMQeExample1 matches the port number that you set for the MQeInput node. Select Listener in the node properties dialog navigator to check and set this property.
    3. There is a listener running on that port number (type netstat at a command prompt to check).
    4. You have specified a WebSphere MQ Everyplace bridge queue name. (The deploy appears to succeed even if you have not set this parameter.)
Related concepts
WebSphere MQ Mobile Transport
Related tasks
Securing WebSphere MQ Everyplace resources
Creating a message flow
Deploying
Checking the results of deployment
Related reference
MQeInput node
MQeOutput node