Automatic client reconnection

We can make 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.

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, we 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.

1. Set managed or unmanaged mode in the WCF binding configuration.

Automatic reconnection has the following configuration requirements:

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

Client application

• 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 we 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:

  MQRC_RECONNECTING

  The connection failed, and the system is attempting to reconnect. You receive multiple MQRC_RECONNECTING events if multiple reconnect attempts are made.

  MQRC_RECONNECTED

  The reconnection made and all handles successfully reestablished.

  MQRC_RECONNECT_FAILED

  The reconnection was not successful.

  MQRC_RECONNECT_QMID_MISMATCH

  A reconnectable connection specified MQCNO_RECONNECT_Q_MGR and the connection attempted to reconnect to a different queue manager.

  MQRC_RECONNECT_Q_MGR_REQD

  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.

  MQRC_RECONNECT_INCOMPATIBLE

  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.

  MQRC_CALL_INTERRUPTED

  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.

We 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 we want an IBM MQ MQI client to reconnect only to the same queue manager. It might have an affinity to a queue manager.

• 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.

We 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

Client and server channel definitions

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.

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.

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

• Reconnections performed automatically by the transport are invisible to IBM MQ.
• Set HBINT helps to deal with network failures that are invisible to IBM MQ.

Queue managers and IBM MQ listeners

• If we 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 we 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 the 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 we have written a channel exit program for the connection, the exit receives these additional MQI calls.
• We 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 we can configure to limit the time a client waits for reconnection. The value (in seconds) is set in the mqclient.ini file.

Channels:
MQReconnectTimeout = 1800

Related information

• Stopping a queue manager
• Reconnectable clients