Procedure

1. Decide on the organization of the cluster and its name

You have decided to link the two queue managers, LONDON and NEWYORK, into a cluster. A cluster with only two queue managers offers only marginal benefit over a network that is to use distributed queuing, but is a good way to start and provides scope for future expansion. When you open new branches of your store, you will be able to add the new queue managers to the cluster easily and without any disruption to the existing network. Task 2a: Adding a new queue manager to a cluster describes how to do this.

For the time being the only application you are running is the inventory application. The cluster name is INVENTORY.

2. Determine which queue managers should hold full repositories

In any cluster you need to nominate at least one queue manager, or preferably two, to hold full repositories. See Selecting queue managers to hold full repositories for more information. In this example there are only two queue managers, LONDON and NEWYORK, both of which hold full repositories.

Notes:
  1. You can perform the remaining steps in any order.
  2. As you proceed through the steps, warning messages might be written to the queue-manager log or the z/OS(R) system console if you have yet to make some expected definitions.
    Examples of the responses to the commands are shown in a box
    like this after each step in this task.
    These examples show the responses returned by WebSphere MQ for AIX.
    The responses vary on other platforms.
  3. Before proceeding with these steps, make sure that the queue managers are started.

3. Alter the queue-manager definitions to add repository definitions

On each queue manager that is to hold a full repository, you need to alter the queue-manager definition, using the ALTER QMGR command and specifying the REPOS attribute:

ALTER QMGR REPOS(INVENTORY)

     1 : ALTER QMGR REPOS(INVENTORY)
AMQ8005: Websphere MQ queue manager changed.

If you enter

  1. C:\..runmqsc jupiter.queue.manager
  2. ALTER QMGR REPOS(INVENTORY) (as shown above)

jupiter.queue.manager will be changed to a full repository.

Note:
If you just runmqsc and enter the ALTER QMGR command, the local queue manager will be changed.

4. Define the CLUSRCVR channels

On every queue manager in a cluster you need to define a cluster-receiver channel on which the queue manager can receive messages. This definition defines the queue manager's connection name and the CLUSTER keyword shows the queue manager's availability to receive messages from other queue managers in the cluster. The queue manager's connection name is stored in the repositories, where other queue managers can refer to it.

Choose one of the following examples

Using transport protocol TCP/IP

On the LONDON queue manager, define:

DEFINE CHANNEL(TO.LONDON) CHLTYPE(CLUSRCVR) TRPTYPE(TCP)
CONNAME(LONDON.CHSTORE.COM) CLUSTER(INVENTORY)
DESCR('TCP Cluster-receiver channel for queue manager LONDON')

     1 : DEFINE CHANNEL(TO.LONDON) CHLTYPE(CLUSRCVR) TRPTYPE(TCP)
         CONNAME(LONDON.CHSTORE.COM) CLUSTER(INVENTORY)
         DESCR('TCP Cluster-receiver channel for queue manager LONDON')
AMQ8014: Websphere MQ channel created.
07/09/98  12:56:35  No repositories for cluster 'INVENTORY'

In this example the channel name is TO.LONDON, and the connection name (CONNAME) is the network address of the machine the queue manager resides on, which is LONDON.CHSTORE.COM. (The network address can be entered either as an alphanumeric DNS hostname, or as a dotted-decimal IP address.) Do not allow the CONNAME to specify a generic name.

On the NEWYORK queue manager, define:

DEFINE CHANNEL(TO.NEWYORK) CHLTYPE(CLUSRCVR) TRPTYPE(TCP)
CONNAME(NEWYORK.CHSTORE.COM) CLUSTER(INVENTORY)
DESCR('TCP Cluster-receiver channel for queue manager NEWYORK')
Using transport protocol LU 6.2

On the LONDON queue manager, define:

DEFINE CHANNEL(TO.LONDON) CHLTYPE(CLUSRCVR) TRPTYPE(LU62)
CONNAME(LONDON.LUNAME) CLUSTER(INVENTORY)
MODENAME('#INTER') TPNAME('MQSERIES')
DESCR('LU62 Cluster-receiver channel for queue manager LONDON')

     1 : DEFINE CHANNEL(TO.LONDON) CHLTYPE(CLUSRCVR) TRPTYPE(LU62)
         CONNAME(LONDON.LUNAME) CLUSTER(INVENTORY)
         MODENAME('#INTER') TPNAME('MQSERIES')
         DESCR('LU62 Cluster-receiver channel for queue manager LONDON')
AMQ8014: Websphere MQ channel created.
07/09/98  12:56:35  No repositories for cluster 'INVENTORY'

In this example the channel name is TO.LONDON, and the connection name (CONNAME) specifies the LU name of the queue manager, which is LONDON.LUNAME. Do not allow the CONNAME to specify a generic LU name.

On the NEWYORK queue manager, define:

DEFINE CHANNEL(TO.NEWYORK) CHLTYPE(CLUSRCVR) TRPTYPE(LU62)
CONNAME(NEWYORK.LUNAME) CLUSTER(INVENTORY)
MODENAME('#INTER') TPNAME('MQSERIES')
DESCR('LU62 Cluster-receiver channel for queue manager NEWYORK')

5. Define the CLUSSDR channels

On every queue manager in a cluster you need to define one cluster-sender channel on which the queue manager can send messages to one of the full repository queue managers. In this case there are only two queue managers, both of which hold full repositories. They must each have a CLUSSDR definition that points to the CLUSRCVR channel defined at the other queue manager. Note that the channel names given on the CLUSSDR definitions must match those on the corresponding CLUSRCVR definitions.

Choose one of the following examples.

Using transport protocol TCP/IP

On the LONDON queue manager, define:

DEFINE CHANNEL(TO.NEWYORK) CHLTYPE(CLUSSDR) TRPTYPE(TCP)
CONNAME(NEWYORK.CHSTORE.COM) CLUSTER(INVENTORY)
DESCR('TCP Cluster-sender channel from LONDON to repository at NEWYORK')

     1 : DEFINE CHANNEL(TO.NEWYORK) CHLTYPE(CLUSSDR) TRPTYPE(TCP)
         CONNAME(NEWYORK.CHSTORE.COM) CLUSTER(INVENTORY)
         DESCR('TCP Cluster-sender channel from LONDON to repository at NEWYORK')
AMQ8014: Websphere MQ channel created.
07/09/98  13:00:18    Channel program started.

On the NEWYORK queue manager, define:

DEFINE CHANNEL(TO.LONDON) CHLTYPE(CLUSSDR) TRPTYPE(TCP)
CONNAME(LONDON.CHSTORE.COM) CLUSTER(INVENTORY)
DESCR('TCP Cluster-sender channel from NEWYORK to repository at LONDON')
Using transport protocol LU 6.2

On the LONDON queue manager, either define:

DEFINE CHANNEL(TO.NEWYORK) CHLTYPE(CLUSSDR) TRPTYPE(LU62)
CONNAME(NEWYORK.LUNAME) CLUSTER(INVENTORY)
MODENAME('#INTER') TPNAME('MQSERIES')
DESCR('LU62 Cluster-sender channel from LONDON to repository at NEWYORK')

or

DEFINE CHANNEL(TO.NEWYORK) CHLTYPE(CLUSSDR) TRPTYPE(LU62)
CONNAME(CPIC) CLUSTER(INVENTORY)
DESCR('LU62 Cluster-sender channel from LONDON to repository at NEWYORK')
     1 : DEFINE CHANNEL(TO.NEWYORK) CHLTYPE(CLUSSDR) TRPTYPE(LU62)
         CONNAME(NEWYORK.LUNAME) CLUSTER(INVENTORY)
         MODENAME('#INTER') TPNAME('MQSERIES')
         DESCR('LU62 Cluster-sender channel from LONDON to repository at NEWYORK')
AMQ8014: Websphere MQ channel created.
07/09/98  13:00:18    Channel program started.

or

     2 : DEFINE CHANNEL(TO.NEWYORK) CHLTYPE(CLUSSDR) TRPTYPE(LU62)
         CONNAME(CPIC) CLUSTER(INVENTORY)
         DESCR('LU62 Cluster-sender channel from LONDON to repository at NEWYORK')
AMQ8014: Websphere MQ channel created.
07/09/98  13:00:18    Channel program started.

On the NEWYORK queue manager, define:

DEFINE CHANNEL(TO.LONDON) CHLTYPE(CLUSSDR) TRPTYPE(LU62)
CONNAME(LONDON.LUNAME) CLUSTER(INVENTORY)
DESCR('LU62 Cluster-sender channel from NEWYORK to repository at LONDON')

Once a queue manager has definitions for both a cluster-receiver channel and a cluster-sender channel in the same cluster, the cluster-sender channel is started.

6. Define the cluster queue INVENTQ

Define the INVENTQ queue on the NEWYORK queue manager, specifying the CLUSTER keyword.

DEFINE QLOCAL(INVENTQ) CLUSTER(INVENTORY)

     1 : DEFINE QLOCAL(INVENTQ) CLUSTER(INVENTORY)
AMQ8006: Websphere MQ queue created.

The CLUSTER keyword causes the queue to be advertised to the cluster. As soon as the queue is defined it becomes available to the other queue managers in the cluster. They can send messages to it without having to make a remote-queue definition for it.

Now that you have completed all the definitions, if you have not already done so start the channel initiator on WebSphere MQ for z/OS and, on all platforms, start a listener program on each queue manager. The listener program listens for incoming network requests and starts the cluster-receiver channel when it is needed. See Establishing communication in a cluster for more information.

The cluster set up by this task looks like this:

Figure 5. The INVENTORY cluster with two queue managers
The diagram shows a cluster with two connected queue managers, London and New York. NEWYORK has a queue called INVENTQ.

Clearly, this is a very small cluster. However, it is useful as a proof of concept. The important thing to understand about this cluster is the scope it offers for future enhancement.

If you are converting an existing network into a cluster like this, in step 6, you need to alter the existing queue definition. You also need to delete the remote queue definition at LONDON for the INVENTQ queue. See Task 6: Converting an existing network into a cluster for an example of this.

7. Verify and test the cluster

Issue some DISPLAY commands to verify the cluster that you have set up. The responses you see should be similar to those shown in the examples that follow.

From the NEWYORK queue manager, issue the command:

dis clusqmgr(*)

     1 : dis clusqmgr(*)
AMQ8441: Display Cluster Queue Manager details.
   CLUSQMGR(NEWYORK)             CLUSTER(INVENTORY)
   CHANNEL(TO.NEWYORK)
AMQ8441: Display Cluster Queue Manager details.
   CLUSQMGR(LONDON)              CLUSTER(INVENTORY)
   CHANNEL(TO.LONDON)

Now issue the corresponding DISPLAY CHANNEL STATUS command:

dis chstatus(*)

     1 : dis chstatus(*)
AMQ8417: Display Channel Status details.
   CHANNEL(TO.NEWYORK)           XMITQ( )
   CONNAME(9.20.40.24)           CURRENT
   CHLTYPE(CLUSRCVR)             STATUS(RUNNING)
   RQMNAME(LONDON)
AMQ8417: Display Channel Status details.
   CHANNEL(TO.LONDON)            XMITQ(SYSTEM.CLUSTER.TRANSMIT.QUEUE)
   CONNAME(9.20.51.25)           CURRENT
   CHLTYPE(CLUSSDR)              STATUS(RUNNING)
   RQMNAME(LONDON)

For more details on troubleshooting see Appendix A. Troubleshooting.

Because the INVENTQ queue has been advertised to the cluster there is no need for remote-queue definitions. Applications running on NEWYORK and applications running on LONDON can put messages to the INVENTQ queue. They can receive responses to their messages by providing a reply-to queue and specifying its name when they put messages.

Using the sample program

Test your setup by sending some messages between the two queue managers, using amqsput. In the following example LONDON puts a message to the INVENTQ at NEWYORK:

  1. On LONDON issue the command:
  2. Type some messages
  3. On NEW YORK issue the command:
  4. You should now see the messages you entered on LONDON
Using your own programs

Test your setup by sending some messages between the two queue managers. In the following example LONDON puts a message to the INVENTQ at NEWYORK and receives a reply on its queue LONDON_reply.

  1. Define a local queue called LONDON_reply
  2. Set the MQOPEN options to MQOO_OUTPUT
  3. Issue the MQOPEN call to open the queue INVENTQ
  4. Set the ReplyToQ name in the message descriptor to LONDON_reply
  5. Issue the MQPUT call to put the message
  6. Commit the message

On NEWYORK:

  1. Set the MQOPEN options to MQOO_BROWSE
  2. Issue the MQOPEN call to open the queue INVENTQ
  3. Issue the MQGET call to get the message from INVENTQ
  4. Retrieve the ReplyToQ name from the message descriptor
  5. Put the ReplyToQ name in the ObjectName field of the object descriptor
  6. Set the MQOPEN options to MQOO_OUTPUT
  7. Issue the MQOPEN call to open LONDON_reply at queue manager LONDON
  8. Issue the MQPUT call to put the message to LONDON_reply

On LONDON:

  1. Set the MQOPEN options to MQOO_BROWSE
  2. Issue the MQOPEN call to open the queue LONDON_reply
  3. Issue the MQGET call to get the message from LONDON_reply
Note:
The definition for the local queue LONDON_reply does not need the CLUSTER attribute. NEWYORK replies to this queue by explicitly specifying the queue manager name. Another way of doing is to use a temporary dynamic queue. See the WebSphere MQ Application Programming Guide for more information.

If you are converting an existing network into a cluster like this, in step 7, you need to alter the existing queue definition. You also need to delete the remote queue definition at LONDON for the INVENTQ queue. See Task 6: Converting an existing network into a cluster for an example of this.