Installing and configuring WebSphere MQ

WebSphere MQ is messaging software that enables communication between InterChange Server and adapters. InterChange Server accesses the WebSphere MQ Server as an MQI Java client or JMS.

Install WebSphere MQ on the same network as InterChange Server. To install WebSphere MQ, you must be the ICS administrator.

WebSphere MQ can also be configured to be used as a JMS provider. For specific configuration instructions for this option, see "Configuring WebSphere MQ for JMS".

HA

For high availability, install WebSphere MQ on each machine in the cluster. Refer to the WebSphere MQ documentation for more information.

Installing WebSphere MQ

The following sections describe how to install WebSphere MQ:

"Upgrading WebSphere MQ"

Installing the WebSphere MQ software

Upgrading WebSphere MQ

If you are upgrading WebSphere MQ and it is running as a Windows service, you must stop the service before upgrading to a newer version or applying a patch to the installation. If the service is not stopped, a series of WebSphere MQ errors may be generated when InterChange Server is restarted. To stop WebSphere MQ as a service, do the following:

  1. Click Start > Settings > Control Panel, then double-click Administrative Tools.
  2. Double-click Service. The Services dialog box appears.
  3. Right-click IBM WebSphere MQ, then click Stop.
Note:
To verify the version of WebSphere MQ in your current environment, type mqver at the command prompt.

Refer to the WebSphere MQ documentation for specific information on how to preserve existing data in the queues during an upgrade.

Installing the WebSphere MQ software

IBM delivers the 5.3.0.2 version of the WebSphere MQ software on a separate CD-ROM.

  1. Insert the WebSphere MQ 5.3.0.2 CD. (download the CSD from: https://www6.software.ibm.com/dl/wsmqcsd/wsmqcsd-p )
  2. Follow the instructions in the WebSphere MQ Installation Launch Pad. For more information, see

    http://www.ibm.com/software/ts/mqseries/messaging/v53/.

  3. At the end of the Launch Pad process, click the Launch WebSphere MQ Installer.
  4. After the Welcome and License Agreement screens, click Custom in the Setup Type screen, then click Next.
  5. Accept the default folder locations for the Program, Data-files, and Log files.
  6. Select Java Messaging in the Features selection screen, then click Next. This feature installs the MQ Java Client Library.
    Note:
    If you are planning a Remote Agent installation and you are not installing the server, you must select the Windows Client feature to provide the necessary client files.
  7. Click Install in the Ready to Install WebSphere MQ screen.
  8. Click Finish when the Installation Wizard Completed Successfully screen appears.
  9. Click Cancel when the Welcome to the Prepare WebSphere MQ Wizard appears.
  10. Click OK when asked to confirm the exit.
    Note:
    After completing the WebSphere MQ installation process for the first time, MQ will automatically startup. Before installing the CSD 5 fix pack, it is necessary that MQ be stopped by right-clicking on the WebSphere MQ icon in the taskbar and then clicking Stop WebSphere MQ. If MQ is not stopped, the CSD installer will fail.
  11. Install the CSD 5 fix pack.
  12. Restart your machine.
    Important:
    Proceed to Installing InterChange Server, System Monitor, and associated software. You will be directed back to this chapter to configure WebSphere MQ after you complete the InterChange Server installation and configuration.

Configuring WebSphere MQ message queues

The WebSphere MQ queues carry messages from the connector to InterChange Server. InterChange Server requires a message queue for each active connector. The configure_mq.bat file creates the queue manager and creates all queues specified in the crossworlds_mq.tst file. These files are located in \IBM\WebSphereICS\mqseries.

You may need to change the default configuration of your WebSphere MQ message queues to handle large objects or numbers of messages. This may require changing the log file size for the WebSphere MQ message queue, message queue properties, or both.

Changing log file size

To change the log file size for a WebSphere MQ message queue, modify the configure_mq.bat file.

  1. Make a copy of the ProductDir\mqseries\configure_mq.bat file. Rename the copy, for example, ibm_mq_orig.bat.
  2. Open the copied configure_mq.bat file. Use the WebSphere MQ crtmqm command to set values for the properties, in this format:
    crtmqm -lp integer -ls integer -lf integer -q "%QUEUE%"
    

    The parameters are as follows:

    -lp
    Specifies the number of primary log files. The default value is 3, the minimum is 2, and the maximum is 62.

    -ls
    Specifies the number of secondary log files to be allocated. The default value is 2, the minimum is 1, and the maximum is 61.

    -lf
    Specifies the size of the log files in units of 4 KB.The default value is 1024, giving a default log size of 4 MB.

    -q
    Specifies that this queue manager is to be made the default queue manager. The new queue manager replaces any existing default queue manager.

    For example, you might change an existing crtmqm -q "%QUEUE%" statement as follows:

    crtmqm -lp 20 -ls 10 -lf 2048 -q "%QUEUE%" 
    

Changing message queue properties

To change the maximum allowed length of the message queue, set values for the MAXDEPTH, MAXMSGL, AND MAXUMSGS properties in the crossworlds_mq.tst file as described in the following procedure:

  1. Navigate to ProductDir\mqseries\crossworlds_mq.tst and make a copy of the crossworlds_mq.tst file. Rename the copy, for example, ibm_mq_orig.tst.
  2. Open the copied crossworlds_mq.tst file. Use the WebSphere MQ ALTER command to set values for the MAXDEPTH or MAXMSGL properties, as described in the Changing the MAXDEPTH value and Changing the MAXMSGL value sections below.
  3. Save the file, then reboot your machine.
  4. Configure your MQ Manager again by clicking Start > Programs > IBM WebSphere InterChange Server > IBM WebSphere MQ > Configure Queue Manager.
  5. Proceed to Starting InterChange Server for the first time.

Changing the MAXDEPTH value

WebSphere MQ message queues are set up by default to hold up to 5000 messages. During times of high traffic volumes or an initial WebSphere business integration system conversion, this default may be exceeded, causing errors and preventing connectors from posting messages to ICS. To help avoid this, you can increase the maximum number of messages allowed in a queue and the maximum number of uncommitted messages allowed across all queues. The preferred values may vary according to your specific circumstances. For example, if you are performing an initial WebSphere business integration system conversion, it is recommended that you set the maximum queue depth to at least 20,000 messages.

To change the MAXDEPTH setting, after each queue definition, add the following:

ALTER QLOCAL (QUEUENAME) MAXDEPTH (DEPTH DESIRED

For example:

DEFINE QLOCAL(AP/EMailConnector/Server_Name)
 
ALTER QLOCAL(AP/EMailConnector/Server_Name) MAXDEPTH(20000)

You can also alter the queue manager to allow for more than the standard uncommitted messages across all queues. The number of allowed uncommitted messages should be the sum of the maximum message depth (MAXDEPTH) of each queue. The memory used by InterChange Server should not increase unless the number of uncommitted messages increases.

To change the MAXUMSGS setting, add the following line:

ALTER QMGR MAXUMSGS (NUMBER)

For example:

ALTER QMGR MAXUMSGS (400000)

Changing the MAXMSGL value

Modify this value only if you know you have business objects larger than the default MAXMSG value of 4 MB. To change the MAXMSGL value, add the following command after each queue definition:

ALTER QLOCAL (QUEUENAME) MAXMSGL (Maximum number of bytes to allow in a message)

Proceed to step 3.

Defining queues (JMS only)

ICS requires that you configure queues with the properties listed below. Specify the name of each queue as a standard property in the connector's configuration file.

Configuring queues for adapters

You can configure the WebSphere MQ queues needed for your adapter using any of the following methods:

Tip

To make it easy to identify the adapter with which a queue is associated, use the name of the adapter as a prefix in the queue name. For example, name the adapter for Clarify's event delivery queue: ClarifyConnector/deliveryqueue.

Using batch files to configure WebSphere MQ queues

WebSphere Business Integration Adapters provides batch files to configure the WebSphere MQ queues needed for the adapters you are deploying.

The following files are located in ProductDir\mqseries:

configure_mq.bat
Run this batch file to configure the WebSphere MQ queues specified in crossworlds_mq.tst.

crossworlds_mq.tst
Edit this file to specify the WebSphere MQ queues in the ICS system. This file is read as input by configure_mq.bat.

The contents of the crossworlds_mq.tst file are shown below. You must manually edit this file. The top portion of the file contains the native MQ information, and the bottom portion contains JMS-specific information. Use this file to define the queues needed by each adapter that you are configuring. Edit the file as follows:

  1. In the native WebSphere MQ portion of the file, delete the following statements:
    DEFINE QLOCAL(IC/SERVER_NAME/DestinationAdapter)
    DEFINE QLOCAL(AP/DestinationAdapter/SERVER_NAME)
    

    These apply only to business integration systems that use WebSphere InterChange Server.

  2. For each adapter you are deploying, create a separate set of queue definition statements in the JMS portion of the file, using as a template the statements beginning with DEFINE QLOCAL(AdapterName/AdminInQueue).

***************************************************************/
*                                                                 */
*   Define the local queues for all Server/Adapter pairs.         */
*   For MQ queues, they must have the following definition:       */
*       Application = DEFINE QLOCAL (AP/AdapterName/ServerName)    */
*                                                                  */
*   Example:                                                       */
*   DEFINE QLOCAL(AP/ClarifyConnector/CrossWorlds)                 */
*                                                                  */
*   DEFINE QLOCAL(AP/SAPConnector/CrossWorlds)                     */
*                                                                  */
*   If your server is named something different than 'CrossWorlds' */
*   make sure to change the entries to reflect that.               */
********************************************************************/
    DEFINE QLOCAL(IC/SERVER_NAME/DestinationAdapter)
    DEFINE QLOCAL(AP/DestinationAdapter/SERVER_NAME)
********************************************************************/
*   For each JMS queue (delivery Transport is JMS), 
*   default values follow the convention:
*           AdapterName/QueueName
********************************************************************/
    DEFINE QLOCAL(AdapterName/AdminInQueue)
    DEFINE QLOCAL(AdapterName/AdminOutQueue)
    DEFINE QLOCAL(AdapterName/DeliveryQueue)
    DEFINE QLOCAL(AdapterName/RequestQueue)
    DEFINE QLOCAL(AdapterName/ResponseQueue)
    DEFINE QLOCAL(AdapterName/FaultQueue)
    DEFINE QLOCAL(AdapterName/SynchronousRequestQueue)
    DEFINE QLOCAL(AdapterName/SynchronousResponseQueue)
********************************************************************/
*   Define the default CrossWorlds channel type                    */
********************************************************************/
    DEFINE CHANNEL(CHANNEL1) CHLTYPE(SVRCONN) TRPTYPE(TCP)
********************************************************************/
*   End of CrossWorlds MQSeries Object Definitions                 */
********************************************************************/

Using WebSphere MQ Explorer to configure WebSphere MQ queues

For information about configuring queues using WebSphere MQ Explorer, open WebSphere MQ Explorer and refer to its online help.

Using WebSphere MQ commands to configure WebSphere MQ queues

For information about configuring queues using WebSphere MQ commands, see WebSphere MQ: System Administration Guide and WebSphere MQ: Script (MQSC) Command Reference.

Note:
If you do not need to revise the default configuration of your WebSphere MQ message queues, proceed to Configuring WebSphere MQ for JMS, or Starting InterChange Server for the first time.After defining the queues, do not rerun the configure_mq.bat file while the ICS and the queue manager are running. This can cause errors in the existing queues.

Configuring WebSphere MQ

You must configure a WebSphere MQ queue manager and a WebSphere MQ listener.

Configuring WebSphere MQ queue manager

You must create a queue manager the first time you configure an InterChange Server system. Click Start > Programs > IBM WebSphere InterChange Server > IBM WebSphere MQ > Configure Queue Manager.

A default queue manager is created and is given the name you defined during installation.

Adding the listener to the WebSphere MQ service

After you create the queue manager, you must add the WebSphere MQ listener as a Windows service and configure it for automatic startup:

  1. Click Start > Programs > IBM WebSphere MQ > WebSphere MQ Explorer to launch the WebSphere MQ Explorer.
  2. In the left pane of the WebSphere MQ Explorer, select the queue managers folder with the name of the queue manager. The Queue Manager Status in the right pane should show the queue manager status as Running. If it does not, right-click on the queue manager name, then select Start from the drop-down list. The Queue Manager Status should change to Running.
  3. Open WebSphere MQ Services by right-clicking the queue manager name in the right pane, then selecting All Tasks > Services from the drop-down list.
  4. In the Console Root tree of the MQServices window, expand WebSphere MQ Services, then select the queue manager.

    There should be three entries for your particular queue listed in the right pane: Queue Manager, Command Server, and Channel Initiator. (If you do not see a Channel Initiator, it will appear after you reboot your system.)

  5. For the three entries in the right pane--Queue Manager, Command Server, Channel Initiator--configure the Startup mode to Automatic by right-clicking each, then selecting All Tasks > Automatic.
  6. Add a listener entry by right-clicking the queue manager name in the Console Root tree and then selecting New > Listener from the drop-down list.
  7. In the Parameters tab of the Create Listener Service dialog box, select TCP as the Protocol and 1414 as the port number, then click OK.

    You must use a unique port number for each listener. Assign the port a number other than the default of 1414,then click OK.

  8. Configure the listener for automatic startup by right-clicking listener it and then selecting All Tasks > Automatic.
  9. Close IBM WebSphere MQ Explorer. Click Yes when prompted to save your changes.
  10. Restart your machine.
  11. Verify that Channel Initiator has been started by following these steps:
    1. Start > Programs > IBM WebSphere MQ > WebSphere MQ Services. (Alternatively, right-click the WebSphere MQ icon on your taskbar, then select MQ Services.)
    2. In the MQ Services window, verify that Channel Initiator is running and that it is set for Automatic.
    3. Close the MQ Services window.

Configuring WebSphere MQ for JMS

For every connector configured for use with WebSphere MQ for JMS transport, use the Connector Configurator tool to edit the local connector's configuration file.

WebSphere MQ should use the JMS transport because native WebSphere MQ relies on CORBA for its administration and other components. When used as a JMS provider there is no longer a reliance on CORBA. Additionally native MQ only persists incoming events to the server.

Specify a queue manager and configure the property values as listed in Table 5. In this example, JmsConnector is the connector being configured

Table 5. Property values for JMS transport

Property Value
AdminInQueue JMSCONNECTOR\ADMININQUEUE
AdminOutQueue JMSCONNECTOR\ADMINOUTQUEUE
DeliveryQueue JMSCONNECTOR\DELIVERYQUEUE
FaultQueue JMSCONNECTOR\FAULTQUEUE
RequestQueue JMSCONNECTOR\REQUESTQUEUE
ResponseQueue JMSCONNECTOR\RESPONSEQUEUE
SynchronousRequestQueue JMSCONNECTOR\SYNCHRONOUS
REQUESTQUEUE
SynchronousResponseQueue JMSCONNECTOR\SYNCHRONOUS
RESPONSEQUEUE

You can leave the UserName and Password blank unless you are accessing the queue manager using the client mode.

Important:
If you are configuring WebSphere MQ for JMS in an internationalized environment, you must install the internationalized version of WebSphere MQ classes for JMS.

Specify the local configuration file that has been updated for the specific connector in the following location:

  1. Navigate to Start > Programs > IBM WebSphere Integration Adapters > Adapters > Connectors > Connector Name.
  2. Right-click the connector name and select Properties.
  3. Insert the -c filename command at the end of the Target field's path.

    Where filename is the fully qualified path of the local configuration file that has entries for that connector.

Reload the repository and restart InterChange Server and the connector after you make these changes. Proceed to Starting InterChange Server for the first time.

Copyright IBM Corp. 1997, 2004