Configure XA-compliant transaction managers
First configure the IBM MQ base client, then configure the extended transactional function using the information in these topics.
Note: This section assumes that we have a basic understanding of the XA interface as published by The Open Group in Distributed Transaction Processing: The XA Specification. To configure an extended transactional client, we must first configure the IBM MQ base client as described in:
- Installing an IBM MQ client on AIX
- Installing an IBM MQ client on Linux
- Installing an IBM MQ client on Windows
- Installing an IBM MQ client on IBM i
Using the information for the platform, we can then configure the extended transactional function for an XA-compliant transaction manager such as CICS and Tuxedo.
A transaction manager communicates with a queue manager as a resource manager using the same MQI channel as that used by the client application that is connected to the queue manager. When the transaction manager issues a resource manager (xa_) function call, the MQI channel is used to forward the call to the queue manager, and to receive the output back from the queue manager.
Either the transaction manager can start the MQI channel by issuing an xa_open call to open the queue manager as a resource manager, or the client application can start the MQI channel by issuing an MQCONN or MQCONNX call.
- If the transaction manager starts the MQI channel, and the client application later calls MQCONN or MQCONNX on the same thread, the MQCONN or MQCONNX call completes successfully and a connection handle is returned to the application. The application does not receive a MQCC_WARNING completion code with an MQRC_ALREADY_CONNECTED reason code.
- If the client application starts the MQI channel, and the transaction manager later calls xa_open on the same thread, the xa_open call is forwarded to the queue manager using the MQI channel.
In a recovery situation following a failure, when no client applications are running, the transaction manager can use a dedicated MQI channel to recover any incomplete units of work in which the queue manager was participating at the time of the failure. Note the following conditions when using an extended transactional client with an XA-compliant transaction manager:
- Within a single thread, a client application can be connected to only one queue manager at a time. This restriction applies only when using an extended transactional client; a client application that is using an IBM MQ base client can be connected to more than one queue manager concurrently within a single thread.
- Each thread of a client application can connect to a different queue manager.
- A client application cannot use shared connection handles.
To configure the extended transactional function, we must provide the following information to the transaction manager for each queue manager that acts as a resource manager:
- An xa_open string
- A pointer to an XA switch structure
When the transaction manager calls xa_open to open the queue manager as a resource manager, it passes the xa_open string to the extended transactional client as the argument, xa_info, on the call. The extended transactional client uses the information in the xa_open string in the following ways:
- To start an MQI channel to the server queue manager, if the client application has not already started one
- To check that the queue manager that the transaction manager opens as a resource manager is the same as the queue manager to which the client application connects
- To locate the transaction manager's ax_reg and ax_unreg functions, if the queue manager uses dynamic registration
For the format of an xa_open string, and for more details about how the information in the xa_open string is used by an extended transactional client, see The format of an xa_open string.
An XA switch structure enables the transaction manager to locate the xa_ functions provided by the extended transactional client, and specifies whether the queue manager uses dynamic registration. For information about the XA switch structures supplied with an extended transactional client, see The XA switch structures.
For information about how to configure the extended transactional function for a particular transaction manager, and for any other information about using the transaction manager with an extended transactional client, see the following sections:
- Configure an extended transactional client for CICS
- Configure an extended transactional client for Tuxedo
- IBM MQ for z/OS considerations for extended transactional client connections
Some XA transaction managers use sequences of transaction coordination calls which are incompatible with the features normally available to clients connecting to IBM MQ for z/OS .- The format of an xa_open string
An xa_open string contains pairs of defined parameter names and values.- The CHANNEL, TRPTYPE, CONNAME, and QMNAME parameters of the xa_open string
Use this information to understand how the extended transactional client uses these parameters to determine the queue manager to connect to.- The TPM and AXLIB parameters
An extended transactional client uses the TPM and AXLIB parameters to locate the transaction manager's ax_reg and ax_unreg functions. These functions are used only if the queue manager uses dynamic registration.- Additional error processing for xa_open
The xa_open call fails in certain circumstances.- Recovery following a failure in extended transactional processing
Following a failure, a transaction manager must be able to recover any incomplete units of work. To do this, the transaction manager must be able to open as a resource manager any queue manager that was participating in an incomplete unit of work at the time of the failure.- The XA switch structures
Two XA switch structures are supplied with the extended transactional client on each platform.- Use the extended transactional client with TLS channels
We cannot set up an TLS channel using the xa_open string. Follow these instructions to use the client channel definition table (ccdt).- Configure an extended transactional client for CICS
You configure an extended transactional client for use by CICS by adding an XAD resource definition to a CICS region.- Configure an extended transactional client for Tuxedo
To configure XAD resource definition for use by Tuxedo, update the UBBCONFIG file and resource manager table.Parent topic: Configure an extended transactional client
Related concepts
- The CHANNEL, TRPTYPE, CONNAME, and QMNAME parameters of the xa_open string
- Additional error processing for xa_open
Related tasks
- Use the extended transactional client with TLS channels
Related reference