The IBM MQ XA switch structure

Each resource manager participating in an externally coordinated unit of work must provide an XA switch structure. This structure defines both the capabilities of the resource manager and the functions that are to be called by the sync point coordinator.

IBM MQ provides two versions of this structure:

  • MQRMIXASwitch for static XA resource management
  • MQRMIXASwitchDynamic for dynamic XA resource management

Consult your transaction manager documentation to determine whether to use the static or dynamic resource management interface. Wherever a transaction manager supports it, we recommend that we use dynamic XA resource management.

Some 64-bit transaction managers treat the long type in the XA specification as 64-bit, and some treat it as 32-bit. IBM MQ supports both models:

  • If your transaction manager is 32-bit, or your transaction manager is 64-bit but treats the long type as 32-bit, use the switch load file listed in Table 1.
  • If your transaction manager is 64-bit and treats the long type as 64-bit, use the switch load file listed in Table 2.
A list of known 64-bit transaction managers that treat the long type as 64-bit is provided in Table 3. Consult your transaction manager documentation if you are unsure which model your transaction manager uses.
Table 1. XA switch load file names
Platform Switch load file name
(server)
 Switch load file name
(extended transactional client)
Windows mqmxa.dll mqcxa.dll
AIX (nonthreaded) libmqmxa.a libmqcxa.a
AIX (threaded) libmqmxa_r.a libmqcxa_r.a
HP-UX (nonthreaded) libmqmxa.so libmqcxa.so
HP-UX (threaded) libmqmxa_r.so libmqcxa_r.so
Linux (nonthreaded) libmqmxa.so libmqcxa.so
Linux (threaded) libmqmxa_r.so libmqcxa_r.so
Solaris libmqmxa.so libmqcxa.so
Table 2. Alternative 64-bit XA switch load file names
Platform Switch load file name
(server)
 Switch load file name
(extended transactional client)
AIX (nonthreaded) libmqmxa64.a libmqcxa64.a
AIX (threaded) libmqmxa64_r.a libmqcxa64_r.a
HP-UX (nonthreaded) libmqmxa64.so libmqcxa64.so
HP-UX (threaded) libmqmxa64_r.so libmqcxa64_r.so
Linux (nonthreaded) libmqmxa64.so libmqcxa64.so
Linux (threaded) libmqmxa64_r.so libmqcxa64_r.so
Solaris libmqmxa64.so libmqcxa64.so
Table 3. 64-bit transaction managers that require the alternative 64-bit switch load file
Transaction Manager
Tuxedo

Some external sync point coordinators (not CICS® ) require that each resource manager participating in a unit of work supplies its name in the name field of the XA switch structure. The IBM MQ resource manager name is MQSeries_XA_RMI.

The sync point coordinator defines how the IBM MQ XA switch structure links to it. Information about linking the IBM MQ XA switch structure with CICS is provided in Use CICS. For information about linking the IBM MQ XA switch structure with other XA-compliant sync point coordinators, consult the documentation supplied with those products.

The following considerations apply to using IBM MQ with all XA-compliant sync point coordinators:

  • It is expected that the transaction manager library code (running as part of their API that the application programmer has called) will call xa_open into IBM MQ at some point, before calling MQCONN.

    The xa_open call must be made on the same thread where the MQCONN call is made. The reason for this requirement, is that the XA specification requires that the thread is used to imply context.

    Note that this is the approach taken in sample program amqstxsx.c. This sample program assumes that an xa_open call is made into IBM MQ, from the library code of the transaction manager, within their function tpopen).

    If no xa_open call is made on the same thread, before the MQCONN call, then the IBM MQ queue manager connection will not be associated with an XA context.

    For more information, see MQCTL.

  • The xa_info structure passed on any xa_open call by the sync point coordinator includes the name of an IBM MQ queue manager. The name takes the same form as the queue manager name passed to the MQCONN call. If the name passed on the xa_open call is blank, the default queue manager is used.

    Alternatively, the xa_info structure can contain values for the TPM and AXLIB parameters. The TPM parameter specifies the transaction manager being used. The valid values are CICS, TUXEDO and ENCINA. The AXLIB parameter specifies the name of the library that contains the transaction manager's ax_reg and ax_unreg functions. For more information on these parameters, see Configure an extended transactional client. If the xa_info structure contains either of these parameters, the queue manager name is specified in the QMNAME parameter, unless the default queue manager is being used.

  • Only one queue manager at a time can participate in a transaction coordinated by an instance of an external sync point coordinator. The sync point coordinator is effectively connected to the queue manager, and is subject to the rule that only one connection at a time is supported.
  • All applications that include calls to an external sync point coordinator can connect only to the queue manager that is participating in the transaction managed by the external coordinator (because they are already effectively connected to that queue manager). However, such applications must issue an MQCONN call to obtain a connection handle, and an MQDISC call before they exit.
  • A queue manager with resource updates coordinated by an external sync point coordinator must start before the external sync point coordinator. Similarly, the sync point coordinator must end before the queue manager.
  • If your external sync point coordinator terminates abnormally, stop and restart your queue manager before restarting the sync point coordinator to ensure that any messaging operations uncommitted at the time of the failure are properly resolved.