Post installation setup

Note:: Remember to check the README file installed with the WebSphere MQ Java programs for information that may supersede this book.

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
ldap.jar¹
providerutil.jar

Environment variables

There are a number of scripts in the bin subdirectory of the WebSphere MQ JMS installation. These are intended 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, you must edit the scripts in the bin directory accordingly.

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

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 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.

You should also be familiar with publish/subscribe concepts as discussed in Chapter 11, Programming publish/subscribe applications.

Ensure 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 Publish/Subscribe)
WebSphere MQ Integrator V2
WebSphere MQ Event Broker

Differences between these brokers are discussed in Chapter 11, Programming publish/subscribe applications. Please look at the documentation for each broker for installation and configuration instructions.

Ensure that the broker is running

MQSeries Publish/Subscribe

To verify that the broker is installed and is 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 please 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 please 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, a number of system queues must be created. 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 & AS/400:

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')

Call the script file using STRMQMMQSC:

STRMQMMQSC  SRCMBR(MQJMS_PSQ) SRCFILE(QGPL/QCLSRC)

For z/OS & OS/390:

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.
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 check 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.

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.
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.
Setup the local queue manager for communication with the remote broker:
1. Define a local transmission queue. You must give it 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 should use the transmission queue defined in step 3a.
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 channels).
3. Start the sender and receiver channels to the local queue manager.
4. Start the broker on the remote queue manager.
  An example command is
```
strmqbrk -m MyBrokerMgr
```
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 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 require put authority.
Queues that are used by QueueReceivers and QueueBrowsers require get, inq and browse authorities.
The QueueSession.createTemporaryQueue method requires access to the model queue that is defined in the QueueConnectionFactory temporaryModel field (by default this will be 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 requires 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 the functionality of ConnectionConsumer, additional authorization may 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.

Footnotes:

¹: For z/OS & OS/390, use ibmjndi.jar and jndi.jar from /usr/lpp/ldap/lib instead of jndi.jar and ldap.jar. These files are supplied with the operating system.