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 can be divided into two pieces:

Figure 41.

This diagram shows the configuration of resources required to route a message from WebSphere MQ Everyplace to WebSphere MQ and from WebSphere MQ to WebSphere MQ Everyplace

Configuration of both types of routes are discussed in the following sections.

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

The following rules govern the relationship between the various objects:

Figure 42. Bridge object hierarchy

Diagrammatic representation of hierarchy of bridge objects described above.

The bridge configuration option allows a WebSphere MQ Everyplace queue manager to communicate with WebSphere MQ host and distributed queue managers through client channels. The bridge component manages a pool of client channels that can be attached to one or more host or distributed queue managers. You can configure multiple bridge-enabled WebSphere MQ Everyplace queue managers in a single network.

A gateway may have a number of transmit queue listeners that use that gateway to connect to the WebSphere MQ queue manager and retrieve a messages from WebSphere MQ to WebSphere MQ Everyplace. A listener uses only one service to establish its connection, with each listener connecting to a single transmission queue on the WebSphere MQ queue manager. Each listener moves messages from a single WebSphere MQ transmission queue to anywhere on the WebSphere MQ Everyplace network, via its parent gateway queue manager. Thus, a single gateway queue manager can funnel multiple WebSphere MQ message sources into the WebSphere MQ Everyplace network.

When moving messages in the other direction, from WebSphere MQ Everyplace to WebSphere MQ, the gateway queue manager configures one or more bridge queues. Each bridge queue can connect to any queue manager directly and send its messages to the target queue. In this way a gateway can dispatch WebSphere MQ Everyplace messages routed through a single WebSphere MQ Everyplace queue manager to any WebSphere MQ queue manager, either directly or indirectly.

The bridges resource

The bridges resource is responsible for maintaining a list of bridge resources. The bridges resource is responsible for maintaining a list of bridge resources. It provides a single-resource which can be started and stopped, where starting and stopping a bridges resource can start and stop all the resources beneath it in the resource hierarchy. It is "owned" by the WebSphere MQ Everyplace queue manager. If the WebSphere MQ Everyplace queue manager is bridge-enabled, then a bridges resource is automatically created, and present. This resource has no persistent information associated with it. It has the following properties:


Table 18. Bridges properties

Property Explanation
Bridgename List of bridge names
Run state Status: running or stopped

The bridges, and the other bridge resources can be started and stopped independently of the WebSphere MQ Everyplace queue manager. If such a bridge resource is started (or stopped) the action also applies to all of its children, that is all bridges, queue manager proxies, client connections, and transmission queue listeners.

More detail of these properties can be found in the WebSphere MQ Everyplace Java Programming Reference in the administration class com.ibm.mqe.mqbridge.MQeMQBridgesAdminMsg. The bridges resource supports the Inquire and InquireAll, start, and stop operations. Create, delete, and update are not appropriate actions to use with this resource. Examples of how to inquire, start, and stop a bridges resource can be found in the Java class examples.mqbridge.administration.programming.AdminHelperBridges

The bridge resource

The bridge resource is responsible for holding a number of persistent property values, and a list of WebSphere MQ queue manager proxy resources. If started or stopped, it can act as a single point of control to start and stop all the resources beneath it in the bridge hierarchy. Each bridge object supports the full range of create, inquire, inquire-all, update, start, stop, and delete operations. Examples of these operations can be found in the Java class examples.mqbridge.administration.programming.AdminHelperBridge. The bridge resource has the following properties:

Table 19. Bridge properties

Property Explanation
Class Bridge class
Default transformer The default class, rule class, to be used to transform a message from WebSphere MQ Everyplace to WebSphere MQ, or vice versa, if no other transformer class has been associated with the destination queue
Heartbeat interval The basic timing unit to be used for performing actions against bridges
Name Name of the bridge
Run state Status: running or stopped
Startup rule class Rule class used when the bridge is started
WebSphere MQ Queue Manager Proxy Children List of all Queue Manager Proxies that are owned by this bridge

More detail of each property can be found in the WebSphere MQ Everyplace Java Programming Reference, in the administration class com.ibm.mqe.mqbridge.MQeMQBridgeAdminMsg.

In simple cases a default transformer (rule) can be used to handle all message conversions. Additionally a transformer can be set on a per listener basis (for messages from WebSphere MQ to WebSphere MQ Everyplace) that overrides this default. For more specific control the transformation rules can be set on a target queue basis using bridge queue definitions on the WebSphere MQ Everyplace Java Programming Reference. This applies both to WebSphere MQ Everyplace and WebSphere MQ target queues.

The WebSphere MQ queue manager proxy

The WebSphere MQ queue manager proxy holds the properties specific to a single WebSphere MQ queue manager. The proxy properties are shown in the following table:

Table 20. WebSphere MQ queue manager proxy properties

Property Explanation
Class WebSphere MQ queue manager proxy class
WebSphere MQ host name IP host name used to create connections to the WebSphere MQ queue manager via the Java client classes. If not specified then the WebSphere MQ queue manager is assumed to be on the same machine as the bridge and the Java bindings are used
WebSphere MQ queue manager proxy name The name of the WebSphere MQ queue manager
Name of owning bridge Name of the bridge that owns this WebSphere MQ queue manager proxy
Run state Status: running or stopped
Startup rule class Rule class used when the WebSphere MQ queue manager is started
Client Connection Children List of all the client connections that are owned by this proxy

More detail of each property can be found in the WebSphere MQ Everyplace Java Programming Reference, in the administration class com.ibm.mqe.mqbridge.MQeMQQMgrProxyAdminMsg.

Each proxy object supports the full range of create, inquire, inquire-all, update, start, stop, and delete operations. Examples of these operations can be found in the Java class examples.mqbridge.administration.programming.AdminHelperMQQMgrProxy.

The client connection resource

The client connection definition holds the detailed information required to make a connection to a WebSphere MQ queue manager. The connection properties are shown in the following table:

Table 21. Client connection service properties

Property Explanation
Adapter class Class to be used as the gateway adapter
CCSID* The integer WebSphere MQ CCSID value to be used
Class Bridge client connection service class
Max connection idle time The maximum time a connection is allowed to be idle before being terminated
WebSphere MQ password* Password for use by the Java client
WebSphere MQ port* IP port number used to create connections to the WebSphere MQ queue manager via the Java client classes. If not specified then the WebSphere MQ queue manager is assumed to be on the same machine as the bridge and the Java bindings are used
WebSphere MQ receive exit class* Used to match the receive exit used at the other end of the client channel; the exit has an associated string to allow data to be passed to the exit code
WebSphere MQ security exit class* Used to match the security exit used at the other end of the client channel; the exit has an associated string to allow data to be passed to the exit code
WebSphere MQ send exit class* Used to match the send exit used at the other end of the client channel; the exit has an associated string to allow data to be passed to the exit code
WebSphere MQ user ID* user ID for use by the Java client
Client connection service name Name of the server connection channel on the WebSphere MQ machine
Name of owning queue manager proxy The name of the owning queue manager proxy
Startup rule class Rule class used when the bridge client connection service is started
Sync queue name The name of the WebSphere MQ queue that is used by the bridge for synchronization purposes
Sync queue purger rules class The rules class to be used when a message is found on the synchronous queue
Run state Status: running or stopped
Name of owning Bridge The name of the bridge that owns this client connection
MQ XmitQ Listener Children List of all the listeners that use this client connection

The adapter class is used to send messages from WebSphere MQ Everyplace to WebSphere MQ and the sync queue is used to keep track of the status of this process. Its contents are used in recovery situations to guarantee assured messaging; after a normal shutdown the queue is empty. It can be shared across multiple client connections and across multiple bridge definitions provided that the receive, send and security exits are the same. This queue can also be used to store state about messages moving from WebSphere MQ to WebSphere MQ Everyplace , depending upon the listener properties in use. The sync queue purger rules class is used when a message is found on the sync queue, indicating a failure of WebSphere MQ Everyplace to confirm a message.

The maximum connection idle time is used to control the pool of Java client connections maintained by the bridge client connection service to its WebSphere MQ system. When a WebSphere MQ connection becomes idle, through lack of use, a timer is started and the idle connection is discarded if the timer expires before the connection is reused. Creation of WebSphere MQ connections is an expensive operation and this process ensures that they are efficiently reused without consuming excessive resources. A value of zero indicates that a connection pool should not be used.

More detail of each property can be found in the WebSphere MQ Everyplace Java Programming Reference, in the administration class com.ibm.mqe.mqbridge.MQeClientConnectionAdminMsg.

Each client connection object supports the full range of create, inquire, inquire-all, update, start, stop,and delete operations. Examples of these operations can be found in the Java class examples.mqbridge.administration.programming.AdminHelperMQClientConnection.

The transmit queue listener resource

The listener moves messages from WebSphere MQ to WebSphere MQ Everyplace.

Table 22. Listener properties

Property Explanation
Class Listener class
Dead letter queue name Queue used to hold messages from WebSphere MQ to WebSphere MQ Everyplace that cannot be delivered
Listener state store adapter Class name of the adapter used to store state information
Listener name Name of the WebSphere MQ XMIT queue supplying messages
Owning client connection service name Client connection service name
Run state Status: running or stopped
Startup rule class Rule class used when the listener is started
Transformer class Rule class used to determine the conversion of a WebSphere MQ message to WebSphere MQ Everyplace
Undelivered message rule class Rule class used to determine action when messages from WebSphere MQ to WebSphere MQ Everyplace cannot be delivered
Seconds wait for message An advanced option that can be used to control listener performance in exceptional circumstances

More detail of each property can be found in the WebSphere MQ Everyplace Java Programming Reference, in the administration class com.ibm.mqe.mqbridge.MQeListenerAdminMsg.

Each transmit queue listener object supports the full range of create, inquire, inquire-all, update, start, stop, and delete operations. Examples of these operations can be found in the Java class

// type all on one line, no spacing
examples.mqbridge.administration.programming.
			AdminHelperMQTransmitQueueListener

The undelivered message rule class determines what action is taken when a message from WebSphere MQ to WebSphere MQ Everyplace cannot be delivered. Typically it is placed in the dead letter queue of the WebSphere MQ system.

In order to provide assured delivery of messages, the listener class uses the listener state store adapter to store state information, either on the WebSphere MQ Everyplace system or in the sync queue of the WebSphere MQ system.

The transmission queue listener allows WebSphere MQ remote queues to refer to WebSphere MQ Everyplace local queues. You can also create WebSphere MQ Everyplace remote queues that refer to WebSphere MQ local queues. These WebSphere MQ Everyplace remote queue definitions are called WebSphere MQ bridge queues and they can be used to get, put and browse messages on a WebSphere MQ queue.

The bridge queue

A WebSphere MQ bridge queue definition can contain the following attributes.

Table 23. WebSphere MQ bridge queue properties

Property Explanation
Alias names Alternative names for the queue
Authenticator Must be null
Class Object class
Client connection Name of the client connection service to be used
Compressor Must be null
Cryptor Must be null
Expiry Passed to transformer
Maximum message size Passed to the rules class
Mode Must be synchronous
MQ queue manager proxy Name of the WebSphere MQ queue manager to which the message should first be sent
WebSphere MQ bridge Name of the bridge to convey the message to WebSphere MQ
Name Name by which the remote WebSphere MQ queue is known to WebSphere MQ Everyplace
Owning queue manager Queue manager owning the definition
Priority Priority to be used for messages, unless overridden by a message value
Remote WebSphere MQ queue name Name of the remote WebSphere MQ queue
Rule Rule class used for queue operations
Queue manager target WebSphere MQ queue manager owning the queue
Transformer Name of the transformer class that converts the message from WebSphere MQ Everyplace format to WebSphere MQ format
Type WebSphere MQ bridge queue

More detail of each property can be found in the WebSphere MQ Everyplace Java Programming Reference, in the administration class com.ibm.mqe.mqbridge.MQeMQBridgeQueueAdminMsg.

Example code which manipulates a bridge queue can be found in the Java class examples.mqbridge.administration.programmingAdminHelperBridgeQueue.

Note:
The cryptor, authenticator, and compressor classes define a set of queue attributes that dictate the level of security for any message passed to this queue. From the time on WebSphere MQ Everyplace that the message is sent initially, to the time when the message is passed to the WebSphere MQ bridge queue, the message is protected with at least the queue level of security. These security levels are not applicable when the WebSphere MQ bridge queue passes the message to the WebSphere MQ system, the security send and receive exits on the client connection are used during this transfer. No checks are made to make sure that the queue level of security is maintained.

WebSphere MQ bridge queues are synchronous only. Asynchronous applications must therefore use either a combination of WebSphere MQ Everyplace store-and-forward and home-server queues, or asynchronous remote queue definitions as an intermediate step when sending messages to WebSphere MQ bridge queues.

Applications make use of WebSphere MQ bridge queues like any other WebSphere MQ Everyplace remote queue, using the putMessage, browseMessages, and getMessage methods of the MQeQueueManager class. The queue name parameter in these calls is the name of the WebSphere MQ bridge queue, and the queue manager name parameter is the name of the WebSphere MQ queue manager. However, in order for this queue manager name to be accepted by the local WebSphere MQ Everyplace server, a connection definition with this WebSphere MQ queue manager name must exist with null for all the parameters, including the channel name.

Note:
there are some restrictions on the use of getMessage and browseMessages with WebSphere MQ bridge queues. It is not possible to get or browse messages from WebSphere MQ bridge queues that point to WebSphere MQ remote queue definitions. Nor is it possible to use nonzero Confirm Ids on WebSphere MQ bridge queue gets. This means that the getMessage operation on WebSphere MQ bridge queues does not provide assured delivery. If you need a get operation to be assured, you should use transmission-queue listeners to transfer messages from WebSphere MQ.

Administration of the WebSphere MQ bridge is handled in the same way as the administration of a normal WebSphere MQ Everyplace queue manager, through the use of administration messages. New classes of messages are defined as appropriate to the queue.

Naming recommendations for interoperability 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.
  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. Update the MQe_java\Classes\JavaEnv.bat file so that it points to the Java classes that are part of the WebSphere MQ Classes for Java, and to the classpath for your JRE (Java Runtime Environment). Ensure that the SupportPac MA88 .jar files are in the classpath, and that the java\lib and \bin directories are in your path. This is set by the MQE_VM_OPTIONS_LOCN which should be set to point to the vm_options.txt file during 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. See the WebSphere MQ Everyplace Java Programming Reference for information on using examples.mqbridge.awt.AwtMQBridgeServer to define a bridge.
  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 use 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 transmission queues that you defined in step b. 1.
  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. These objects can be started in any of the following ways:

    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.

Configuring a bridge using WebSphere MQ Everyplace administration messages and WebSphere MQ PCF messages

PCF messages are administration messages used by WebSphere MQ queue managers. Supportpac "MS0B: MQSeries Java classes for PCF" contains Java code, which supplies PCF message support. This code is available as a free download from the WebSphere MQ download site at http://www.ibm.com/software/ts/mqseries/txppacs.

If you download and install it, and put the com.ibm.mq.pcf.jar file on your classpath environment variable, you have access to Java classes, which can dynamically manipulate WebSphere MQ resources. When PCF messages are combined with WebSphere MQ Everyplace administration messages, complete programmatic configuration of bridge resources, and corresponding resources on a WebSphere MQ Everyplace queue manager are possible. Example code contained in the examples.mqbridge.administration.programming.AdminHelperMQ class, used in conjunction with the examples.mqbridge.administration.programming.MQAgent demonstrate how to do this. This example code has been added to the examples.awt.AwtMQeServer program, such that using the view -> "Connect local MQ default queue manager" menu item will:

Configuration example

This section describes an example configuration of 4 systems.

Figure 43. 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(R) 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:
    BridgeName: MQeEarthQMBridge
  2. Define an WebSphere MQ queue manager proxy with the following parameters:
    BridgeName: MQeEarthQMBridge
    MQQMgrProxyName: MQSaturnQM
    Hostname: 20.8.9.51
  3. Define a client connection with the following parameters:
    BridgeName: MQeEarthQMBridge
    MQQMgrProxyName: 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:
    QueueName: MQSaturnQ
    MQQueueManagerName: MQSaturnQM
    BridgeName: MQeEarthQMBridge
    MQQMgrProxyName: MQSaturnQM
    ClientConnectionName: MQeEarth.CHANNEL

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

    The synchronous 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:
    QueueName: MQJupiterQ
    MQQueueManagerName: MQJupiterQM
    BridgeName: MQeEarthQMBridge
    MQQMgrProxyName: 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:
    BridgeName: MQeEarthQMBridge
    MQQMgrProxyName: MQSaturnQM
    ClientConnectionName: MQeEarth.CHANNEL
    ListenerName: 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.

Administration of the WebSphere MQ bridge

This section contains information on the tasks associated with the administration of the WebSphere MQ bridge

The example administration GUI application

An example administration GUI is provided with the WebSphere MQ bridge. It is a subclass of the examples.administration.console.Admin example described in Example administration console.

The subclass is called examples.mqbridge.administration.console.AdminGateway.

WebSphere MQ bridge function cannot execute on a client queue manager, so using this class in conjunction with a client queue manager does not allow the administration of bridge objects on that client queue manager, but it does enable administration of a remote WebSphere MQ bridge-enabled server queue manager.

You can administer all the resources required to configure a bridge so that it can communicate with WebSphere MQ, without programming in Java, or using the Java examples supplied with WebSphere MQ Everyplace. For example, using the examples.awt.AwtMQeServer, open a queue manager and select View - > Admin menu item to bring up the administration GUI.

You can also use the examples.mqbridge.administration.commandline tools in conjunction with the the examples.administration.commandline package, to configure the WebSphere MQ bridge. The WebSphere MQ Everyplace Java Programming Reference describes how to use these tools. Use batch files to combine a sequence of these example configuration tools, as described in Example of use of command-line tools.

WebSphere MQ bridge administration actions

Run state

Each administered object has a run state. This can be 'running' or 'stopped' indicating whether the administered object is active or not.

When an administered object is 'stopped', it cannot be used, but its configuration parameters can be queried or updated.

If the WebSphere MQ bridge queue references a bridge administered object that is 'stopped', it is unable to convey a WebSphere MQ Everyplace message onto the WebSphere MQ network until the bridge, WebSphere MQ queue manager proxy, and client connection objects are all 'started'.

The run state of administered objects can be changed using the start and stop actions from the MQeMQBridgeAdminMsg, MQeMQQMgrProxyAdminMsg, MQeClientConnectionAdminMsg, or MQeListenerAdminMsg administration message classes.

The actions supported by the WebSphere MQ bridge administration objects are described in the following sections.

Start action

An administrator can send a start action to any of the administered objects.

The affect children boolean flag affects the results of this action. The start action starts the administered object and all its children (and children's children) if the affect children boolean field is in the message and is set to true. If the flag is not in the message or is set to false, only the administered object receiving the start action changes its run-state. For example, sending start to a bridge object with affect children as true causes all proxy, client connection, and listeners that are ancestors, to start. If affect children is not specified, only the bridge is started. An object cannot be started unless its parent object has already been started. Sending a start event to an administered object attempts to start all the objects higher in the hierarchy that are not already running.

Stop action

An administered object can be stopped by sending it a stop action. The receiving administered object always makes sure all the objects below it in the hierarchy are stopped before it is stopped itself.

Inquire action

The inquire action queries values from an administered object.

If the administered object is running, the values returned on the inquire are those that are currently in use. The values returned from a stopped object reflect any recent changes to values made by an update action. Thus, a sequence of start, update, inquire, returns the values configured before the update, while start, update, stop, inquire, returns the values configured after the update.

You may find it less confusing if you stop any administered object before updating variable values.

Update action

The update action changes one or more values for characteristics for an administered object. The values set by an update action do not become current until the administered object is next stopped. (See Inquire action.)

Delete action

The delete action permanently removes all current and persistent information about the administered object. The affect children boolean flag affects the outcome of this action. If the affect children flag is present and set to true the administered object receiving this action issues a stop action, and then a delete action to all the objects below it in the hierarchy, removing a whole piece of the hierarchy with one action. If the flag is not present, or it is set to false, the administered object deletes only itself, but this action cannot take place unless all the objects in the hierarchy below the current one have already been deleted.

Create action

The create action creates an administered object. The run state of the administered object created is initially set to stopped.

WebSphere MQ bridge considerations when shutting down a WebSphere MQ queue manager

We recommend that before you stop a WebSphere MQ queue manager, you issue a stop administration message to all the WebSphere MQ queue-manager-proxy bridge objects. This stops the WebSphere MQ Everyplace network from trying to use the WebSphere MQ queue manager and possibly interfering with the shutdown of the WebSphere MQ queue manager. This can also be achieved by issuing a single stop administration message to the MQeBridges object.

If you choose not to stop the WebSphere MQ queue-manager-proxy bridge object before you shut the WebSphere MQ queue manager, the behavior of the WebSphere MQ shutdown and the WebSphere MQ bridge depends on the type of WebSphere MQ queue manager shutdown you choose, immediate shutdown or controlled shutdown.

Immediate shutdown

Stopping a WebSphere MQ queue manager using immediate shutdown severs any connections that the WebSphere MQ bridge has to the WebSphere MQ queue manager (this applies to connections formed using the MQSeries Classes for Java in either the bindings or client mode). The WebSphere MQ system shuts down as normal.

This causes all the WebSphere MQ bridge transmission queue listeners to stop immediately, each one warning that it has shut down due to the WebSphere MQ queue manager stop.

Any WebSphere MQ bridge queues that are active retain a broken connection to the WebSphere MQ queue manager until:

When a WebSphere MQ bridge queue has no connection, the next operation on that queue causes a new connection to be obtained. If the WebSphere MQ queue manager is not available, the operation on the queue fails synchronously. If the WebSphere MQ queue manager has been restarted after the shutdown, and a queue operation, such as putMessage, acts on the bridge queue, then a new connection to the active WebSphere MQ queue manager is established, and the operation executes as expected.

Controlled shutdown

Stopping a WebSphere MQ queue manager using the controlled shutdown does not sever any connections immediately, but waits until all connections are closed (this applies to connections formed using the MQSeries Classes for Java in either the bindings or client mode). Any active WebSphere MQ bridge transmission queue listeners notice that the WebSphere MQ system is quiesce, and stop with a relevant warning.

Any WebSphere MQ bridge queues that are active retain a connection to the WebSphere MQ queue manager until:

The bridge client-connection object maintains a pool of connections, that are awaiting use. If there is no bridge activity, the pool retains WebSphere MQ client channel connections until the connection idle time exceeds the idle time-out period (as specified on the client connection object configuration), at which point the channels in the pool are closed.

When the last client channel connection to the WebSphere MQ queue manager is closed, the WebSphere MQ controlled shutdown completes.

Administered objects and their characteristics

This section describes the characteristics of the different types of administered objects associated with the WebSphere MQ Everyplace WebSphere MQ bridge. Characteristics are object attributes that can be queried using an inquireAll() administration message. The results can be read and used by the application, or they can be sent in an update or create administration message to set the values of the characteristics. Some characteristics can also be set using the create and update administration messages. Each characteristic has a unique label associated with it and this label is used to set and get the characteristic value.

The following lists show the attributes that apply to each administered object. The label constants are defined in the header file published/MQe_MQBridge_Constants.h. If you include published/MQe_API.h in you installation, this file is included automaticallyclass com.ibm.mqe.mqbridge.MQeCharacteristicLabels.

Characteristics of bridges objects
Refer to the WebSphere MQ Everyplace Java Programming Reference for information on the com.ibm.mqe.mqbridge.MQeMQBridgesAdminMsg.

Characteristics of bridge objects
Refer to the WebSphere MQ Everyplace Java Programming Reference for information on the com.ibm.mqe.mqbridge.MQeMQBridgeAdminMsg.

Characteristics of WebSphere MQ queue manager proxy objects
Refer to the WebSphere MQ Everyplace Java Programming Reference for information on the com.ibm.mqe.mqbridge.MQeMQQMgrProxyAdminMsg.

Characteristics of client connection objects
Refer to the WebSphere MQ Everyplace Java Programming Reference for information on the com.ibm.mqe.mqbridge.MQeClientConnectionAdminMsg.

Characteristics of WebSphere MQ transmission queue listener objects
Refer to the WebSphere MQ Everyplace Java Programming Reference for information on the com.ibm.mqe.mqbridge.MQeListenerAdminMsg.

Handling undeliverable messages

The WebSphere MQ bridge transmission queue listener acts in a similar way to a WebSphere MQ channel, pulling messages from a WebSphere MQ transmission queue, and delivering them to the WebSphere MQ Everyplace network. It follows the WebSphere MQ Everyplace convention in that if a message cannot be delivered, an undelivered message rule is consulted to determine how the transmission queue listener should react. If the rule indicates the report options in the message header, and these indicate that the message should be put onto a dead-letter queue, the message is placed on the WebSphere MQ queue, on the sending queue manager.



© IBM Corporation 2002. All Rights Reserved