Queue manager groups in the CCDT

We can define a set of connections in the client channel definition table (CCDT) as a queue manager group. We can connect an application to a queue manager that is part of a queue manager group. This can be done by prefixing the queue manager name on an MQCONN or MQCONNX call with an asterisk.

You might choose to define connections to more than one server machine because:

• You want to connect a client to any one of a set of queue managers that is running, to improve availability.
• You want to reconnect a client to the same queue manager it connected to successfully last time, but connect to a different queue manager if the connection fails.
• You want to be able to retry a client connection to a different queue manager if the connection fails, by issuing the MQCONN in the client program again.
• You want to automatically reconnect a client connection to another queue manager if the connection fails, without writing any client code.
• You want to automatically reconnect a client connection to a different instance of a multi-instance queue manager if a standby instance takes over, without writing any client code.
• You want to balance your client connections across a number of queue managers, with more clients connecting to some queue managers than others.
• You want to spread the reconnection of many client connections over multiple queue managers and over time, in case the high volume of connections causes a failure.
• You want to be able to move your queue managers without changing any client application code.
• You want to write client application programs that do not need to know queue manager names.

It is not always appropriate to connect to different queue managers. An extended transactional client or a Java client in WebSphere Application Server, for example, might need to connect to a predictable queue manager instance. Automatic client reconnect is not supported by IBM MQ classes for Java.

A queue manager group is a set of connections defined in the client channel definition table (CCDT). The set is defined by its members having the same value of the QMNAME attribute in their channel definitions.

Figure 1 is a graphical representation of a client connection table, showing three queue manager groups, two named queue manager groups written in the CCDT as QMNAME (QM1) and QMNAME (QMGrp1), and one blank or default group written as QMNAME (' ').

1. Queue manager group QM1 has three client connection channels, connecting it to queue managers QM1 and QM2. QM1 might be a multi-instance queue manager located on two different servers.
2. The default queue manager group has six client connection channels connecting it to all the queue managers.
3. QMGrp1 has client connection channels to two queue managers, QM4 and QM5.

Four examples of using this client connection table are described with the help of the numbered client applications in Figure 1.

1. In the first example, the client application passes a queue manager name, QM1, as the QmgrName parameter to its MQCONN or MQCONNX MQI call. The IBM MQ client code selects the matching queue manager group, QM1. The group contains three connection channels, and the IBM MQ MQI client tries to connect to QM1 using each of these channels in turn until it finds an IBM MQ listener for the connection attached to a running queue manager called QM1.

   The order of connection attempts depends on the value of the client connection AFFINITY attribute and the client channel weightings. Within these constraints, the order of connection attempts is randomized, both over the three possible connections, and over time, in order to spread out the load of making connections.

   The MQCONN or MQCONNX call issued by the client application succeeds when a connection is established to a running instance of QM1.

2. In the second example, the client application passes a queue manager name prefixed with an asterisk, *QMGrp1 as the QmgrName parameter to its MQCONN or MQCONNX MQI call. The IBM MQ client selects the matching queue manager group, QMGrp1. This group contains two client connection channels, and the IBM MQ MQI client tries to connect to any queue manager using each channel in turn. In this example, the IBM MQ MQI client needs to make a successful connection; the name of the queue manager that it connects to does not matter.

   The rule for the order of making connection attempts is the same as before. The only difference is that by prefixing the queue manager name with an asterisk, the client indicates that the name of the queue manager is not relevant.

   The MQCONN or MQCONNX call issued by the client application succeeds when a connection is established to a running instance of any queue manager connected to by the channels in the QMGrp1 queue manager group.

3. The third example is essentially the same as the second because the QmgrName parameter is prefixed by an asterisk, *QM1. The example illustrates that we cannot determine which queue manager a client channel connection is going to connect to by inspecting the QMNAME attribute in one channel definition by itself. The fact that the QMNAME attribute of the channel definition is QM1, is not sufficient to require a connection is made to a queue manager called QM1. If your client application prefixes its QmgrName parameter with an asterisk then any queue manager is a possible connection target.

   In this case the MQCONN or MQCONNX calls issued by the client application succeed when a connection is established to a running instance of either QM1 or QM2.

4. The fourth example illustrates use of the default group. In this case the client application passes an asterisk, '*', or blank ' ', as the QmgrName parameter to its MQCONN or MQCONNX MQI call. By convention in the client channel definition, a blank QMNAME attribute signifies the default queue manager group and either a blank or asterisk QmgrName parameter matches a blank QMNAME attribute.

   In this example the default queue manager group has client channel connections to all the queue managers. By selecting the default queue manager group the application might be connected to any queue manager in the group.

   The MQCONN or MQCONNX call issued by the client application succeeds when a connection is established to a running instance of any queue manager.

   Note: The default group is different from a default queue manager, although an application uses a blank QmgrName parameter to connect to either the default queue manager group or to the default queue manager. The concept of a default queue manager group is only relevant to a client application, and a default queue manager to a server application.

Define your client connection channels on one queue manager only, including those channels that connect to a second or third queue manager. Do not define them on two queue managers and then try to merge the two client channel definition tables. Only one client channel definition table can be accessed by the client.

Examples

Look again at the list of reasons for using queue manager groups at the beginning of the topic. How does using a queue manager group provide those capabilities?

Connect to any one of a set of queue managers.

Define a queue manager group with connections to all the queue managers in the set, and connect to the group using the QmgrName parameter prefixed by an asterisk.

Reconnect to the same queue manager, but connect to a different one, if the queue manager connected to last time is unavailable.

Define a queue manager group as before but set the attribute, AFFINITY (PREFERRED) on each client channel definition.

Retry a connection to another queue manager if a connection fails.

Connect to a queue manager group, and reissue the MQCONN or MQCONNX MQI call if the connection is broken or the queue manager fails.

Automatically reconnect to another queue manager if a connection fails.

Connect to a queue manager group using the MQCONNX MQCNO option MQCNO_RECONNECT.

Automatically reconnect to a different instance of a multi-instance queue manager.

Do the same as the preceding example. In this case, if you want to restrict the queue manager group to connect to the instances of a particular multi-instance queue manager, define the group with connections to only the multi-instance queue manager instances.

We can also ask the client application to issue its MQCONN or MQCONNX MQI call with no asterisk prefixed to the QmgrName parameter. That way the client application can only connect to the named queue manager. Finally, we can set the MQCNO option to MQCNO_RECONNECT_Q_MGR. This option accepts reconnections to the same queue manager that was previously connected. We can also use this value to restrict reconnections to the same instance of a normal queue manager.

Balance client connections across queue managers, with more clients connected to some queue managers than others.

Define a queue manager group, and set the CLNTWGHT attribute on each client channel definition to distribute the connections unevenly.

Spread the client reconnection load unevenly, and spread it over time, after a connection or queue manager failure.

Do the same as the preceding example. The IBM MQ MQI client randomizes reconnections across queue managers and spreads the reconnections over time.

Move your queue managers without changing any client code.

The CCDT isolates your client application from the location of the queue manager. The CCDT is a data file which can be defined at the client, read from a shared location or fetched from a web-server. For more information, see Client channel definition table.

Write a client application that does not know queue manager names.

Use queue manager group names and establish a naming convention for queue manager group names that is relevant to your client applications in your organization, and reflects the architecture of your solutions rather than the naming of queue managers.