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® WebSphere® 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 JMS client, set the reconnection options in the connection factory configuration. When you use the WebSphere MQ Resource adapter or a JMS Client that is integrated in a Java EE Environment, automatic client reconnection might not be available. There are restrictions in some of the managed environments, for more information see Using automatic client reconnection in Java SE and Java EE environments.

Note: Automatic client reconnection is not supported by WebSphere 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)	7.0.1.3	7.0.1.3
	WebSphere 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¹)	Not supported	7.0.1
	Windows Communication Foundation (Managed¹)	Not supported	Not supported
	Axis 1	Not supported	Not supported
	Axis 2	Not supported	7.0.1.3
	HTTP (web 2.0)	Not supported	7.0.1.3

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
WebSphere MQ MQI client installation	See Table 1	`MQRC_OPTIONS_ERROR`
WebSphere MQ Server installation	Level 7.0.1	`MQRC_OPTIONS_ERROR`
Channel	`SHARECNV > 0`	`MQRC_ENVIRONMENT_ERROR`
Application environment	Must be threaded	`MQRC_ENVIRONMENT_ERROR`
MQI	One of: MQCONNX with MQCNO Options set to `MQCNO_RECONNECT` or `MQCNO_RECONNECT_Q_MGR`. `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.

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

Client application

The client application is an IBM WebSphere MQ MQI client.

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:

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.

Multi-instance queue managers

Simplify restarting WebSphere MQ MQI client applications, after a multi-instance queue manager has activated its standby instance, by using automatic client reconnection.

The standby instance of a multi-instance 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.

Commonly, WebSphere MQ MQI clients reconnect to any queue manager in a queue manager group. Sometimes you want a WebSphere MQ MQI client to reconnect only to the same queue manager. It might have an affinity to a queue manager. You can prevent a client from reconnecting to a different queue manager. Set the MQCNO option, MQCNO_RECONNECT_Q_MGR. The WebSphere 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 manager groups

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.

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.
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 a WebSphere MQ heartbeat between the client and the queue manager. Setting these heartbeats to a shorter time serves two purposes:

By simulating activity on the connection, network layer software that is responsible for closing inactive connections is less likely to shut down your connection.
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 WebSphere 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 WebSphere MQ.
Setting HBINT helps to deal with network failures that are invisible to WebSphere MQ.

Queue managers and WebSphere 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.

WebSphere MQ MQI client automatic reconnection support

If you use the automatic client reconnection support in the WebSphere 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 reconnection takes 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 WebSphere 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.

Channels:
    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.