External syncpoint coordination

A global unit of work can also be coordinated by an external X/Open XA-compliant transaction manager. Here the WebSphere MQ queue manager participates in, but does not coordinate, the unit of work.

The flow of control in a global unit of work coordinated by an external transaction manager is as follows:

1. An application tells the external syncpoint coordinator (for example, TXSeries) that it wants to start a transaction.
2. The syncpoint coordinator tells known resource managers, such as WebSphere MQ, about the current transaction.
3. The application issues calls to resource managers associated with the current transaction. For example, the application could issue MQGET calls to WebSphere MQ.
4. The application issues a commit or back-out request to the external syncpoint coordinator.
5. The syncpoint coordinator completes the transaction by issuing the appropriate calls to each resource manager, typically using two-phase commit protocols.

Table 15 lists the external syncpoint coordinators that can provide a two-phase commit process for transactions in which WebSphere MQ participates. Minimum versions and releases are shown; later versions or releases, if any, can be used.

Table 15. XA-compliant external syncpoint coordinators

Notes:

1. Composed of TXSeries V4.3 and Transarc Encina.

2. In Tuxedo, configure each application that accesses WebSphere MQ under a single global transaction ID (GTRID) to be within its own Tuxedo server group. This is because processes in the same server group use the same XID when accessing resource managers on behalf of a single GTRID, but WebSphere MQ allows only one process to work on a transaction branch XID at a time. If Tuxedo starts work on a transaction branch in one process while a previous process is still accessing it, WebSphere MQ blocks the xa_start call of the second process until the first process has completed its work with the transaction. Processes in different server groups use separate XIDs when accessing resource managers, and so do not have to serialize their transaction work in WebSphere MQ.

See the WebSphere MQ Application Programming Guide for information about writing and building transactions to be coordinated by an external syncpoint coordinator.

The rest of this chapter describes how to enable external units of work.

The WebSphere 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 syncpoint coordinator.

WebSphere MQ provides two versions of this structure:

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

In WebSphere MQ for Windows the structures are located in the following libraries:

mqmxa.dll

(contains only the MQRMIXASwitch version)

mqmenc.dll

(for use with Encina for Windows)

mqmc4swi.dll

(for use with IBM TXSeries^(TM) for Windows)

In WebSphere MQ for UNIX systems, these structures are located in the following libraries:

libmqmxa.a

(nonthreaded)

libmqmxa_r.a

(threaded)

Some external syncpoint 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 WebSphere MQ resource manager name is "WebSphere MQ XA RMI".

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

The following considerations apply to using WebSphere MQ with all XA-compliant syncpoint coordinators:

• The xa_info structure passed on any xa_open call by the syncpoint coordinator includes the name of a WebSphere 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.
• Only one queue manager at a time can participate in a transaction coordinated by an instance of an external syncpoint coordinator. The syncpoint 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 syncpoint 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 syncpoint coordinator must start before the external syncpoint coordinator. Similarly, the syncpoint coordinator must end before the queue manager.
• If your external syncpoint coordinator terminates abnormally, stop and restart your queue manager before restarting the syncpoint coordinator to ensure that any messaging operations uncommitted at the time of the failure are properly resolved.