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.
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
DefReconto 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.
|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)||220.127.116.11||18.104.22.168|
|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||22.214.171.124|
|HTTP (web 2.0)||Not supported||126.96.36.199|
- Set managed or unmanaged mode in the WCF binding configuration.
|Component||Requirement||Effect of not meeting requirement|
|IBM MQ MQI client installation||See Table 1||
|IBM MQ Server installation||Level 7.0.1||
|Application environment||Must be threaded||
Figure 1 shows the main interactions between components that are involved in client reconnection.
Client applicationThe 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
- 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:
- 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.
- Add an event handler to detect reconnection, and restore the state of the client application when the connection is reestablished.
- 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.
- 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
MQHCONNpassed 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_RECONNECTINGevents 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_MGRand the connection attempted to reconnect to a different queue manager.
- An option, such
MQMO_MATCH_MSG_TOKENin 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_MGRfrom 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.
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 groupsAutomatic 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 definitionsClient 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.
- 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 connectivityOnly 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 listenersClient 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.
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.
Channels: MQReconnectTimeout = 1800