Automatic client reconnection

You can make your client applications reconnect automatically, without writing any additional code, by configuring a number of components.

Automatic client reconnection is inline. The connection is automatically restored at any point in the client application program, and the handles to open objects are all restored.

In contrast, manual reconnection requires the client application to re-create a connection using MQCONN or MQCONNX, and to reopen objects. Automatic client reconnection is suitable for many, but not all client applications.

Table 1 lists the earliest release of IBM® MQ client support that must be installed on a client workstation. You must upgrade client workstations to one of these levels for an application to use automatic client reconnection. Table 2 lists other requirements to enable automatic client reconnection.

With program access to reconnection options, a client application can set reconnection options. Except for JMS and XMS clients, if a client application has access to reconnection options, it can also create an event handler to handle reconnection events.

An existing client application might be able to benefit from reconnection support, without recompilation and linking:

  • For a non-JMS client, set the mqclient.ini environment variable DefRecon to set reconnection options. Use a CCDT to connect to a queue manager. If the client is to connect to a multi-instance queue manager, provide the network addresses of the active and standby queue manager instances in the CCDT. For a replicated data queue manager, or an HA queue manager on an IBM MQ Appliance, you can specify a floating IP address used by both active and standby queue managers to simplify configuration.
  • For a JMS client, set the reconnection options in the connection factory configuration. When running inside the EJB container of a Java EE server, MDBs can reconnect to IBM MQ using the reconnect mechanism provided by activation specifications of the IBM MQ resource adapter (or listener ports if running in WebSphere® Application Server). However, if the application is not an MDB (or is running in the web container) the application must implement its own reconnect logic because automatic client reconnect is not supported in this scenario. The IBM MQ resource adapter provides this reconnect ability for the delivery of messages to message driven beans, but other Java EE elements such as servlets must implement their own reconnection.
Note: Automatic client reconnection is not supported by IBM MQ classes for Java.
Table 1. Supported clients
Client interface Client Program access to reconnection options Reconnection support
Messaging APIs C, C++, COBOL, Unmanaged Visual Basic, XMS (Unmanaged XMS on Windows) 7.0.1 7.0.1
JMS (JSE, and Java EE client container and managed containers)
IBM MQ classes for Java Not supported Not supported
Managed XMS and managed .NET clients: C#, Visual Basic, 7.1 7.1
Other APIs Windows Communication Foundation (Unmanaged 1 ) Not supported 7.0.1
Windows Communication Foundation (Managed 1 ) Not supported Not supported
Axis 1 Not supported Not supported
Axis 2 Not supported
HTTP (web 2.0) Not supported
  1. Set managed or unmanaged mode in the WCF binding configuration.
Automatic reconnection has the following configuration requirements:
Table 2. Automatic reconnection configuration requirements
Component Requirement Effect of not meeting requirement
IBM MQ MQI client installation See Table 1 MQRC_OPTIONS_ERROR
IBM MQ Server installation Level 7.0.1 MQRC_OPTIONS_ERROR
Application environment Must be threaded MQRC_ENVIRONMENT_ERROR
MQI One of:
  • Defrecon=YES|QMGR in mqclient.ini
  • In JMS set the CLIENTRECONNECTOPTIONS property of the connection factory.
MQCC_FAILED when a connection is broken or queue manager ends or fails.

Figure 1 shows the main interactions between components that are involved in client reconnection.

Figure 1. Automatic client reconnection
Six components involved in automatic client reconnection, with some of the interactions between them identified with labeled arrows.

Client application

The client application is an IBM MQ MQI client. For details about automatic client reconnection for a JMS client, see Using automatic JMS client reconnection.
  • By default clients are not automatically reconnected. Enable the automatic client reconnection by setting the MQCONNX MQCNO Option MQCNO_RECONNECT or MQCNO_RECONNECT_Q_MGR.
  • Many applications are written in such a way that they are able to take advantage of auto-reconnection with no additional coding. Enable automatic reconnection for existing programs, without making any coding changes, by setting the DefRecon attribute in the channels stanza of the mqclient.ini configuration file.
  • Use one of these three options:
    1. Modify the program so that the logic is unaffected by reconnection. For example, you might have to issue MQI calls within the sync point, and resubmit backed-out transactions.
    2. Add an event handler to detect reconnection, and restore the state of the client application when the connection is reestablished.
    3. Do not enable auto-reconnection: instead, disconnect the client and issue a new MQCONN or MQCONNX MQI call to find another queue manager instance that is running in the same queue manager group.
    For further details about these three options, see Application recovery.
  • Reconnecting to a queue manager of the same name does not guarantee that you have reconnected to the same instance of a queue manager.

    Use an MQCNO option MQCNO_RECONNECT_Q_MGR, to reconnect to an instance of the same queue manager.

  • A client can register an event handler so that it can be informed the state of reconnection. The MQHCONN passed in the event handler cannot be used. The following reason codes are provided:
    The connection failed, and the system is attempting to reconnect. You receive multiple MQRC_RECONNECTING events if multiple reconnect attempts are made.
    The reconnection made and all handles successfully reestablished.
    The reconnection was not successful.
    A reconnectable connection specified MQCNO_RECONNECT_Q_MGR and the connection attempted to reconnect to a different queue manager.
    An option, such MQMO_MATCH_MSG_TOKEN in an MQGET call, was specified in the client program that requires reconnection to the same queue manager.
  • A reconnectable client is able to reconnect automatically only after connecting. That is, the MQCONNX call itself is not tried again if it fails. For example, if you receive the return code 2543 - MQRC_STANDBY_Q_MGR from MQCONNX, reissue the call after a short delay.
    This reason code is returned when the application tries to use MQPMO_LOGICAL_ORDER (with MQPUT and MQPUT1) or MQGMO_LOGICAL_ORDER (with MQGET ) when reconnect options are set. The reason for returning the reason code is to make sure that applications never use reconnect in such cases.
    This reason code is returned when the connection breaks during the execution of Commit call and the client reconnects. An MQPUT of a persistent message outside the sync point also results in the same reason code being returned to the application.

High availability queue managers

High availability queue managers have an active instance and one or more standby instances of a queue manager. The active queue manager is synchronized with the standby queue managers, such that a standby can automatically take over if the active instance fails. There are a number of different solutions to provide high availability queue managers, see High availability configurations.

You can simplify restarting IBM MQ MQI client applications, after a high availability queue manager has activated its standby instance, by using automatic client reconnection.

The standby instance of a high availability queue manager is typically at a different network address to the active instance. Include the network addresses of both the instances in the client connection definition table (CCDT). Either provide a list of network addresses for the CONNAME parameter, or define multiple rows for the queue manager in the CCDT. Replicated data queue managers and IBM MQ Appliance high availability queue managers support floating IP addresses, where you specify a single address for use with active or standby queue managers.

Queue manager groups

Commonly, IBM MQ MQI clients reconnect to any queue manager in a queue manager group. Sometimes you want an IBM MQ MQI client to reconnect only to the same queue manager. It might have an affinity to a queue manager.

You can select whether the client application always connects and reconnects to a queue manager of the same name, to the same queue manager, or to any of a set of queue managers that are defined with the same QMNAME value in the client connection table.
  • The queue manager name attribute, QMNAME, in the client channel definition is the name of a queue manager group.
  • In your client application, if you set the value of the MQCONN or MQCONNX QmgrName parameter to a queue manager name, the client connects only to queue managers with that name. If you prefix the queue manager name with an asterisk(*), the client connects to any queue manager in the queue manager group with the same QMNAME value. For a full explanation, see Queue manager groups in the CCDT.
You can prevent a client from reconnecting to a different queue manager. Set the MQCNO option, MQCNO_RECONNECT_Q_MGR. The IBM MQ MQI client fails if it reconnects to a different queue manager. If you set the MQCNO option, MQCNO_RECONNECT_Q_MGR, do not include other queue managers in the same queue manager group. The client returns an error if the queue manager it reconnects to is not the same queue manager as the one it connected to.

Queue sharing groups

Automatic client reconnection to z/OS® queue sharing groups, uses the same mechanisms for reconnection as any other environment. The client will reconnect to the same selection of queue managers as is configured for the original connection. For example, when using the client channel definition table the administrator should ensure that all entries in the table, resolve to the same z/OS queue sharing group.

Client and server channel definitions

Client and server channel definitions define the groups of queue managers a client application can reconnect to. The definitions govern the selection and timing of reconnections, and other factors, such as security; see the related topics. The most relevant channel attributes to consider for reconnection are listed in two groups:
Client connection attributes
Connection affinity (AFFINITY) AFFINITY
Connection affinity.
Client channel weight (CLNTWGHT) CLNTWGHT
Client channel weight.
Connection name (CONNAME) CONNAME
Connection information.
Heartbeat interval (HBINT) HBINT
Heartbeat interval. Set the heartbeat interval on the server connection channel.
Keepalive Interval (KAINT) KAINT
Keepalive interval. Set the keepalive interval on the server connection channel.

[z/OS]Note that KAINT applies to z/OS only.

Queue manager name (QMNAME) QMNAME
Queue manager name.
Server connection attributes
Heartbeat interval (HBINT) HBINT
Heartbeat interval. Set the heartbeat interval on the client connection channel.
Keepalive Interval (KAINT) KAINT
Keepalive interval. Set the keepalive interval on the client connection channel.

[z/OS]Note that KAINT applies to z/OS only.

KAINT is a network layer heartbeat, and HBINT is an IBM MQ heartbeat between the client and the queue manager. Setting these heartbeats to a shorter time serves two purposes:
  1. By simulating activity on the connection, network layer software that is responsible for closing inactive connections is less likely to shut down your connection.
  2. If the connection is shut down, the delay before the broken connection is detected, is shortened.

The default TCP/IP keepalive interval is two hours. Consider setting the KAINT and HBINT attributes to a shorter time. Do not assume that the normal behavior of a network suits the needs of automatic reconnection. For example, some firewalls can shut down an inactive TCP/IP connection after as little as 10 minutes.

Network connectivity

Only network failures that are passed to the IBM MQ MQI client by the network, are handled by the automatic reconnection capability of the client.
  • Reconnections performed automatically by the transport are invisible to IBM MQ.
  • Setting HBINT helps to deal with network failures that are invisible to IBM MQ.

Queue managers and IBM MQ listeners

Client reconnection is triggered by server failure, queue manager failure, network connectivity failure, and by an administrator switching over to another queue manager instance.
  • If you are using a multi-instance queue manager, an additional cause of client reconnection occurs when you switch control from the active queue manager instance to a standby instance.
  • Ending a queue manager using the default endmqm command does not trigger automatic client reconnection. Add the -r option on the endmqm command to request automatic client reconnection, or the -s option to transfer to a standby queue manager instance after shutting down.

IBM MQ MQI client automatic reconnection support

If you use the automatic client reconnection support in the IBM MQ MQI client, the client application automatically reconnects and continues processing without you issuing an MQCONN or MQCONNX MQI call to reconnect to the queue manager.

  • Automatic client reconnection is triggered by one of the following occurrences:
    • Queue manager failure
    • Ending a queue manager and specifying the -r, reconnect, option on the endmqm command
  • The MQCONNX MQCNO options control whether you have enabled the automatic client reconnection. The options are described in Reconnection options.
  • Automatic client reconnection issues MQI calls on behalf of your application to restore the connection handle and the handles to other open objects, so that your program can resume normal processing after it has processed any MQI errors that resulted from the broken connection. See Recovery of an automatically reconnected client.
  • If you have written a channel exit program for the connection, the exit receives these additional MQI calls.
  • You can register a reconnection event handler, which is triggered when reconnection begins and when it finishes.
Although the intended reconnection time is no more than a minute, reconnection can take longer because a queue manager might have numerous resources to manage. During this time, a client application might be holding locks that do not belong to IBM MQ resources. There is a timeout value you can configure to limit the time a client waits for reconnection. The value (in seconds) is set in the mqclient.ini file.

MQReconnectTimeout = 1800
No reconnection attempts are made after the timeout has expired. When the system detects that the timeout has expired it returns a MQRC_RECONNECT_FAILED error.