WebSphere MQ Java Post installation setup

 

Overview

To make all the necessary resources available to WebSphere MQ JMS programs, you need to update the following system variables:

 

CLASSPATH

Successful operation of JMS programs requires a number of Java packages to be available to the JVM. You must specify these on the classpath after you have obtained and installed the necessary packages.

Add the following .jar files to the classpath:

  • com.ibm.mq.jar
  • com.ibm.mqjms.jar
  • connector.jar
  • jms.jar
  • jndi.jar
  • jta.jar
  • providerutil.jar
  • fscontext.jar
  • ldap.jar

Include the java/lib directory itself in the classpath to access the properties files used by the base Java API.

Include providerutil.jar, jndi.jar, and either ldap.jar or fscontext.jar if you need to access a JNDI namespace.

In certain environments, typically J2EE application servers, classes contained in these jars are provided by the environment. In these circumstances, use the classes provided by the environment instead of those provided with WebSphere MQ.

Setup java.library.path:

  • Define java.library.path on command line, ie.java -D=/opt/mqm/java/lib/ ...

    or

  • Define environ variable

    export LD_LIBRARY_PATH=/opt/mqm/java/lib/

 

Environment variables

There are a number of scripts in the bin subdirectory of the WebSphere MQ JMS installation. These are for use as convenient shortcuts for a number of common actions. Many of these scripts assume that the environment variables MQ_JAVA_INSTALL_PATH and MQ_JAVA_DATA_PATH are defined, pointing to the directory in which WebSphere MQ JMS is installed and a directory for log and trace output, respectively. If you do not set these variables, edit the scripts in the bin directory accordingly.

On Windows NT, you can set the classpath and other environment variables by using the Environment tab of System Properties. On Windows 2000 and Windows XP, Environment is a button on the Advanced tab of System Properties. On UNIX, these are normally set from each user's logon scripts. On any platform, you can use scripts to maintain different classpaths and other environment variables for different projects.

Note:
If you are migrating from the SupportPac MA88, be aware that the connector.jar is now packaged in the java/lib directory with the other jar files, with the following consequences:

  • You need an entry for connector.jar in the classpath, as explained above.

  • If you have previously implemented your own ConnectionManagers, as described in Supplying your own ConnectionManager, replace references to com.ibm.mq.resource and com.ibm.mq.resource.spi with references to javax.resource and javax.resource.spi respectively.

 

Additional setup for publish/subscribe mode

Before you can use the WebSphere MQ JMS implementation of JMS publish/subscribe, some additional setup is required:

  • Ensure that you have access to a publish/subscribe broker.
  • Ensure that the broker is running.
  • Create the WebSphere MQ JMS system queues. This step is not required for direct connection across a TCP/IP socket to a WebSphere MQ Event Broker broker.

 

Ensure that you have access to a publish/subscribe broker

With WebSphere MQ JMS you have the choice of three brokers:

  • WebSphere MQ with SupportPac MA0C (also known as MQSeries lish/Subscribe)
  • WebSphere MQ Integrator V2
  • WebSphere MQ Event Broker

To use broker-based subscription stores, use SupportPac MA0C or the WebSphere MQ Event Broker. No other combination of queue manager and broker supports this option.

 

Ensure that the broker is running

MQSeries Publish/Subscribe
To verify that the broker is installed and running, use the command: 

dspmqbrk -m MY.QUEUE.MANAGER

where MY.QUEUE.MANAGER is the name of the queue manager on which the broker is running. If the broker is running, a message similar to the following is displayed: 

WebSphere MQ message broker for queue manager MY.QUEUE.MANAGER running.

If the operating system reports that it cannot run the dspmqbrk command, ensure that the MQSeries Publish/Subscribe broker is installed properly.

If the operating system reports that the broker is not active, start it using the command: 

strmqbrk -m MY.QUEUE.MANAGER

WebSphere MQ Integrator V2
To verify that the broker provided in WebSphere MQ Integrator V2 is installed and running, refer to the product documentation.

The command to start the broker in WebSphere MQ Integrator V2 is: 

mqsistart MYBROKER

where MYBROKER is the name of the broker.

WebSphere MQ Event Broker
To verify that the broker provided in WebSphere MQ Event Broker is installed and running, refer to the product documentation.

The command to start the broker in WebSphere MQ Event Broker is: 

wmqpsstart MYBROKER

where MYBROKER is the name of the broker.

 

Create the WebSphere MQ JMS system queues

This does not apply if you use a direct connection across TCP/IP to WebSphere MQ Event Broker.

For a publish/subscribe implementation to work correctly, create a number of system queues. A script is supplied, in the bin subdirectory of the WebSphere MQ JMS installation, to assist with this task. To use the script, enter the following commands:

For iSeries and AS/400:

  1. Copy the script from the integrated file system to a native file system library using a command similar to: 
    CPYFRMSTMF FROMSTMF('/QIBM/ProdData/mqm/java/bin/MQJMS_PSQ.mqsc')
           TOMBR('/QSYS.LIB/QGPL.LIB/QCLSRC.FILE/MQJMS_PSQ.MBR')

  2. Call the script file using STRMQMMQSC: 
    STRMQMMQSC  SRCMBR(MQJMS_PSQ) SRCFILE(QGPL/QCLSRC)

For z/OS and OS/390:

  1. Copy the script from the HFS into a PDS using a TSO command similar to 
    OGET '/usr/lpp/mqm/java/bin/MQJMS_PSQ.mqsc' 'USERID.MQSC(MQJMSPSQ)'

    The PDS should be of fixed-block format with a record length of 80.

  2. Either use the CSQUTIL application to execute this command script, or add the script to the CSQINP2 DD concatenation in your queue manager's started task JCL. In either case, refer to the WebSphere MQ for z/OS System Setup Guide and the WebSphere MQ for z/OS System Administration Guide for further details.

For other platforms:
runmqsc MY.QUEUE.MANAGER < MQJMS_PSQ.mqsc

If an error occurs, check that you typed the queue manager name correctly and that the queue manager is running.

 

For a broker running on a remote queue manager

For operation with a broker running on a remote queue manager, further setup is required.

  1. Define a transmission queue on the remote queue manager with a queue name matching the local queue manager. These names must match for correct routing of messages by WebSphere MQ.

  2. Define a sender channel on the remote queue manager and a receiver channel on the local queue manager. The sender channel should use the transmission queue defined in step 1.

  3. Set up the local queue manager for communication with the remote broker:

    1. Define a local transmission queue with the same name as the queue manager running the remote broker.

    2. Define local sender and remote receiver channels to the remote broker queue manager. The sender channel must use the transmission queue defined in step 3a.

  4. To operate the remote broker, take the following steps:
    1. Start the remote broker queue manager.

    2. Start a listener for the remote broker queue manager (TCP/IP nnels).

    3. Start the sender and receiver channels to the local queue manager.

    4. Start the broker on the remote queue manager. For example: 

      strmqbrk -m MyBrokerMgr

  5. To operate the local queue manager to communicate with the remote broker, take the following steps:
    1. Start the local queue manager.
    2. Start a listener for the local queue manager.
    3. Start the sender and receiver channels to the remote broker queue manager.

 

Queues that require authorization for non-privileged users

Non-privileged users need authorization granted to access the queues used by JMS. For details about access control in WebSphere MQ, see the chapter about protecting WebSphere MQ objects in the WebSphere MQ System Administration Guide.

For JMS point-to-point mode, the access control issues are similar to those for the WebSphere MQ classes for Java:

  • Queues that are used by QueueSender need put authority.
  • Queues that are used by QueueReceivers and QueueBrowsers need get, inq, and browse authorities.
  • The QueueSession.createTemporaryQueue method needs access to the model queue that is defined in the QueueConnectionFactory temporaryModel field (by default this is SYSTEM.DEFAULT.MODEL.QUEUE).

For JMS publish/subscribe mode, the following system queues are used:

SYSTEM.JMS.ADMIN.QUEUE
SYSTEM.JMS.REPORT.QUEUE
SYSTEM.JMS.MODEL.QUEUE
SYSTEM.JMS.PS.STATUS.QUEUE
SYSTEM.JMS.ND.SUBSCRIBER.QUEUE
SYSTEM.JMS.D.SUBSCRIBER.QUEUE
SYSTEM.JMS.ND.CC.SUBSCRIBER.QUEUE
SYSTEM.JMS.D.CC.SUBSCRIBER.QUEUE
SYSTEM.BROKER.CONTROL.QUEUE

Also, any application that publishes messages needs access to the STREAM queue that is specified in the topic connection factory being used. The default value for this is SYSTEM.BROKER.DEFAULT.STREAM.

If you use ConnectionConsumer, additional authorization might be needed. Queues to be read by the ConnectionConsumer must have get, inq and browse authorities. The system dead-letter queue, and any backout-requeue queue or report queue used by the ConnectionConsumer must have put and passall authorities.

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.