Configuring the WebSphere MQ-bridge

The configuration of the WebSphere MQ-bridge requires you to perform some actions on the WebSphere MQ queue manager, and some on the WebSphere MQ Everyplace queue manager. The bridge is logically broken into two pieces, one for each direction of the message (WebSphere MQ Everyplace to WebSphere MQ and WebSphere MQ to WebSphere MQ Everyplace)

The bridge objects are defined in a hierarchy as shown in Figure 23

The following rules govern the relationship between the various objects:

Figure 23. Bridge object hierarchy

Diagrammatic representation of hierarchy of bridge objects described above.

Naming recommendations for inter-operability with a WebSphere MQ network

To create an WebSphere MQ Everyplace network that can interoperates with a WebSphere MQ network, it is necessary to adopt the same limitations in naming convention for both systems. It is therefore important to understand the differences between valid queue names in both systems:

If you choose not to follow these guidelines, then you may experience problems when trying to address an WebSphere MQ Everyplace queue from a WebSphere MQ application.

Configuring a basic installation

To configure a very basic installation of the WebSphere MQ-bridge you need to complete the following steps:

  1. Make sure you have a WebSphere MQ system installed and that you understand local routing conventions, and how to configure the system.
  2. Install WebSphere MQ Everyplace on a system (It can be the same system as your WebSphere MQ system is located on if you wish)
  3. If WebSphere MQ Classes for Java is not already installed, download it from the Web and install it. (See WebSphere MQ Classes for Java.)
  4. Set up your WebSphere MQ Everyplace system and verify that it is working properly before you try to connect it to WebSphere MQ.
  5. Make sure that the supportpac MA88 .jar files are in the classpath. This is set by the MQE_VM_OPTIONS_LOCN which should be set to point to the vm_options.txt file during installation. See Installation.
  6. Plan the routing you intend to implement. You need to decide which WebSphere MQ queue managers are going to talk to which WebSphere MQ Everyplace queue managers.
  7. Decide on a naming convention for WebSphere MQ Everyplace objects and WebSphere MQ objects and document it for future use.
  8. Modify your WebSphere MQ Everyplace system to define a WebSphere MQ-bridge on your chosen WebSphere MQ Everyplace server.
  9. Connect the chosen WebSphere MQ queue manager to the bridge on the WebSphere MQ Everyplace server as follows:
  10. Modify your configuration on both WebSphere MQ Everyplace and WebSphere MQ to allow messages to pass from WebSphere MQ to WebSphere MQ Everyplace.
    1. Decide on the number of routes from WebSphere MQ to your WebSphere MQ Everyplace network. The number of routes you need depends on the amount of message traffic (load) you will be using across each route. If your message load is high you may wish to split your traffic into multiple routes.
    2. Define your routes as follows:
      1. For each route define a transmission queue on your WebSphere MQ system. DO NOT define a connection for these transmission queues.
      2. For each route create a matching transmission queue listener on your WebSphere MQ Everyplace system.
      3. Define a number of remote queue definitions, (such as remote queue manager aliases and queue aliases) to allow WebSphere MQ messages to be routed onto the various WebSphere MQ Everyplace-bound transmission queues that you defined in step 10b.i.
  11. Modify your configuration on WebSphere MQ Everyplace to allow messages to pass from WebSphere MQ Everyplace to WebSphere MQ:
    1. Publish details about all the queue managers on your WebSphere MQ network you want to send messages to from the WebSphere MQ Everyplace network. Each WebSphere MQ queue manager requires a connections definition on your WebSphere MQ Everyplace server. All fields except the Queue manager name should be null, to indicate that the normal WebSphere MQ Everyplace communications connections should not be used to talk to this queue manager.
    2. Publish details about all the queues on your WebSphere MQ network you want to send messages to from the WebSphere MQ Everyplace network. Each WebSphere MQ queue requires a WebSphere MQ-bridge queue definition on your WebSphere MQ Everyplace server. (This is the WebSphere MQ Everyplace equivalent of a DEFINE QREMOTE in WebSphere MQ).
      • The queue name is the name of the WebSphere MQ queue to which the bridge should send any messages arriving on this WebSphere MQ-bridge queue.
      • The queue manager name is the name of the WebSphere MQ queue manager on which the queue is located.
      • The bridge name indicates which bridge should be used to send messages to the WebSphere MQ network.
      • The WebSphere MQ queue manager proxy name is the name of the WebSphere MQ queue manager proxy object, in the WebSphere MQ Everyplace configuration, that can connect to a WebSphere MQ queue manager.
      • The WebSphere MQ queue manager should have a route defined to allow messages to be posted to the Queue Name on Queue Manager Name to deliver the message to its final destination.
  12. Start your WebSphere MQ and WebSphere MQ Everyplace systems to allow messages to flow. The WebSphere MQ system client channel listener must be started. All the objects you have defined on the WebSphere MQ Everyplace must be started. The simplest way to start objects manually, is to send a start command to the relevant bridge object. This command should indicate that all the children of the bridge, and children's children should be started as well.
  13. Create transformer classes, and modify your WebSphere MQ Everyplace configuration to use them. A transformer class converts messages from WebSphere MQ message formats into an WebSphere MQ Everyplace message format, and vice-versa. These format-converters must be written in Java and configured in several places in the WebSphere MQ-bridge configuration.
    1. Create transformer classes
      • Determine the message formats of the WebSphere MQ messages that need to pass over the bridge.
      • Write a transformer class, or a set of transformer classes to convert each WebSphere MQ message format into an WebSphere MQ Everyplace message. Transformers are not directly supported by the C Bindings. SeeWebSphere MQ Everyplace Application Programming Guide for information about writing transformers in Java.
    2. You can replace the default transformer class. Use the administration GUI to update the default transformer class parameter in the bridge object's configuration.
    3. You can specify a non-default transformer for each WebSphere MQ-bridge queue definition. Use the administration GUI to update the transformer field of each WebSphere MQ-bridge queue in the configuration.
    4. You can specify a non-default transformer for each WebSphere MQ transmission queue listener. Use the administration GUI to update the transformer field of each listener in the configuration.
    5. Restart the bridge, and listeners.

Configuration example

This section describes an example configuration of 4 systems.

Figure 24. Configuration example

Diagram of four interconnected queue managers in an MQe/MQ network. The queue managers and their configurations are described in detail below.

The four systems are:

MQeMoonQM
This is an WebSphere MQ Everyplace client queue manager, sited on a handheld PC. The user periodically attaches the handheld PC to the network, to communicate with the MQeEarthQM WebSphere MQ Everyplace gateway.

MQeEarthQM
This is on a Windows/2000 machine, with an I/P address of 20.8.9.50 This is an WebSphere MQ Everyplace gateway (server) queue manager.

MQSaturnQM
This is a WebSphere MQ queue manager, installed on a Windows/NT platform. The I/P address is 20.8.9.51

MQJupiterQM
This is a WebSphere MQ queue manager, installed on a System/390 platform.

Requirement

The requirement for this example is that all machines are able to post a message to a queue on any of the other machines.

It is assumed that all machines are permanently connected to the network, except the MQeMoonQM machine, which is only occasionally connected.

Initial setup

For this example, it is assumed that there are local queues, to which messages can be put, on all the queue managers. These queues are called:

Enabling MQeMoonQM to put and get messages to and from the MQeEarthQM queue manager

On MQeMoonQM:
  1. Define a connection with the following parameters:
    Target queue manager name: MQeEarthQM
    Adapter: FastNetwork:20.8.9.50
    Note:
    Check that the adapter you specify when you define the connection matches the adapter used by the Listener on the MQeEarthQM queue manager.
    Applications can now connect directly to any queue defined on the MQeEarthQM queue manager directly, when the MQeMoonQM is connected to the network. The requirement states that applications on MQeMoonQM must be able to send messages to MQeEarthQ in an asynchronous manner. This requires a remote queue definition to set up the asynchronous linkage to the MQeEarthQ queue.
  2. Define a remote queue with the following parameters:
    Queue name: MQeEarthQ
    Queue manager name: MQeEarthQM
    Access mode: Asynchronous

    Applications on MQeMoonQM now have access to the MQeMoonQ (a local queue) in a synchronous manner, and the MQeEarthQ in an asynchronous manner.

Enabling the MQeEarthQM to send messages to the MQeMoonQM queue manager

Since the MQeMoonQM is not attached to the network for most of the time, use a store-and-forward queue on the MQeEarthQM to collect messages destined for the MQeMoonQM queue manager.

On MQeEarthQM:
  1. Define a store-and-forward-queue with the following parameters:
    Queue name: TO.HANDHELDS
    Queue Manager Name: MQeEarthQM
  2. Add a queue manager to the store-and-forward queue using the following parameters:
    Queue Name: TO.HANDHELDS
    Queue manager: MQeMoonQM

A (similarly named) home-server queue is needed on the MQeMoonQM queue manager. This queue pulls messages out of the store-and-forward queue and puts them to a queue on the MQeMoonQM queue manager.

On MQeMoonQM:
  1. Define a home-server queue with the following parameters:
    Queue Name: TO.HANDHELDS
    Queue manager name: MQeEarthQM

Any messages arriving at MQeEarthQM that are destined for MQeMoonQM are stored temporarily in the store-and-forward queue TO.HANDHELDS. When MQeMoonQM next connects to the network, it's home-server queue TO.HANDHELDS gets any messages currently on the store-and-forward queue, and delivers them to the MQeMoonQM queue manager, for storage on local queues.

Applications on MQeEarthQM can now send messages to MQeMoonQ in an asynchronous manner.

Enabling MQeEarthQM to send a message to MQSaturnQ

On MQeEarthQM:
  1. Define a bridge with the following parameters:
    Bridge name: MQeEarthQMBridge
  2. Define an WebSphere MQ queue manager proxy with the following parameters:
    Bridge Name: MQeEarthQMBridge
    MQ QMgr Proxy Name: MQSaturnQM
    Hostname: 20.8.9.51
  3. Define a client connection with the following parameters:
    Bridge Name: MQeEarthQMBridge
    MQ QMgr Proxy Name: MQSaturnQM
    ClientConnectionName: MQeEarth.CHANNEL
    SyncQName: MQeEarth.SYNC.QUEUE
  4. Define a connection with the following parameters:
    ConnectionName: MQSaturnQM
    Channel: null
    Adapter: null
  5. Define an WebSphere MQ-bridge queue with the following parameters:
    Queue Name: MQSaturnQ
    MQ Queue manager name: MQSaturnQM
    Bridge name: MQeEarthQMBridge
    MQ QMgr Proxy Name: MQSaturnQM
    ClientConnectionName: MQeEarth.CHANNEL

On MQSaturnQM:
  1. Define a server connection channel with the following parameters:
    Name: MQeEarth.CHANNEL
  2. Define a local sync queue with the following parameters:
    Name: MQeEarth.SYNC.QUEUE

    The sync queue is needed for assured delivery.

Applications on MQeEarthQM can now send messages to the MQSaturnQ on MQSaturnQM.

Enabling MQeEarthQM to send a message to MQJupiterQ

On MQeEarthQM:
  1. Define a connection with the following parameters:
    ConnectionName: MQeJupiterQM
    Channel: null
    Adapter: null
  2. Define an WebSphere MQ-bridge queue with the following parameters:
    Queue Name: MQJupiterQ
    MQ Queue manager name: MQJupiterQM
    Bridge name: MQeEarthQMBridge
    MQ QMgr Proxy Name: MQSaturnQM
    ClientConnectionName: MQeEarth.CHANNEL

On MQSaturnQM:
  1. Define a remote queue definition with the following parameters:
    Queue Name: MQJupiterQ
    Transmission Queue: MQJupiterQM.XMITQ

On both MQSaturnQM and MQJupiterQM:
  1. Define a channel to move the message from the MQJupiterQM.XMITQ on MQSaturnQM to MQJupiterQM.

Now applications on MQeEarthQM can send a message to MQJupiterQ on MQJupiterQM, through MQSaturnQM.

Enabling MQeMoonQM to send a message to MQJupiterQ and MQSaturnQ

On MQeMoonQM:
  1. Define a connection with the following parameters:
    Target Queue manager name: MQSaturnQM
    Adapter: MQeEarthQM

    The connection indicates that any message bound for the MQSaturnQM queue manager should go through the MQeEarthQM queue manager.

  2. Define a remote queue definition with the following parameters:
    Queue name: MQSaturnQ
    Queue manager name: MQSaturnQM
    Access mode: Asynchronous
  3. Define a connection with the following parameters:
    Target Queue manager name: MQJupiterQM
    Adapter: MQeEarthQM
  4. Define a remote queue definition with the following parameters:
    Queue name: MQJupiterQ
    Queue manager name: MQJupiterQM
    Access mode: Asynchronous

Applications connected to MQeMoonQM can now issue messages to MQeMoonQ, MQeEarthQ, MQSaturnQ, and MQJupiterQ, even when the handheld PC is disconnected from the network.

Enabling MQSaturnQM to send messages to the MQeEarthQ

On MQSaturnQM:
  1. Define a local queue with the following parameters:
    Queue name: MQeEarth.XMITQ
    Queue type: transmission queue
  2. Define a queue manager alias (remote queue definition) with the following parameters:
    Queue name: MQeEarthQM
    Remote queue manager name: MQeEarthQM
    Transmission queue: MQeEarth.XMITQ

On MQeEarthQM:
  1. Define a Transmission queue listener with the following parameters:
    Bridge name: MQeEarthQMBridge
    MQ QMgr Proxy Name: MQSaturnQM
    ClientConnectionName: MQeEarth.CHANNEL
    Listener Name: MQeEarth.XMITQ

Applications on MQSaturnQM can now send messages to MQeEarthQ using the MQeEarthQM queue manager alias . This routes each message onto the MQeEarth.XMITQ, where the WebSphere MQ Everyplace transmission queue listener MQeEarth.XMITQ gets them, and moves them onto the WebSphere MQ Everyplace network.

Enabling MQSaturnQM to send messages to the MQeMoonQ

On MQSaturnQM:
  1. Define a queue manager alias (remote queue definition) with the following parameters:
    Queue name: MQeMoonQM
    Remote queue manager name: MQeMoonQM
    Transmission queue: MQeEarth.XMITQ

Applications on MQSaturnQM can now send messages to MQeMoonQ using the MQeMoonQM queue manager alias . This routes each message to the MQeEarth.XMITQ, where the WebSphere MQ Everyplace transmission queue listener MQeEarth.XMITQ gets them, and posts them onto the WebSphere MQ Everyplace network.

The store-and-forward queue TO.HANDHELDS collects the message, and when the MQeMoonQM next connects to the network, the home-server queue retrieves the message from the store-and-forward queue, and delivers the message to the MQeMoonQ.

Enabling the MQJupiterQM to send messages to the MQeMoonQ

On MQJupiterQM:
Set up remote queue manager aliases for the MQeEarthQM and MQeMoonQM to route messages to MQSaturnQM using normal WebSphere MQ routing techniques.

Now any application connected to any of the queue managers can post a message to any of the queues MQeMoonQ, MQeEarthQ, MQSaturnQ or MQJupiterQ.



© IBM Corporation 2002. All Rights Reserved