Scenario 2: Other software provides the coordination

 

---

Overview

In scenario 2, an external transaction manager coordinates global units of work, starting and committing them under control of the transaction manager's API. The MQBEGIN, MQCMIT, and MQBACK verbs are unavailable.

This section describes this scenario, including:

• External syncpoint coordination
• Using CICS
• Using the Microsoft Transaction Server (MTS)

 

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 backout 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.

The supported levels of external syncpoint coordinators that can provide a two-phase commit process for transactions in which WebSphere MQ participates are defined at:

http://www.ibm.com/software/ts/mqseries/platforms/supported.html

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

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 you use 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 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 MQSeries_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.

 

Using CICS

CICS is one of the elements of TXSeries. The versions of TXSeries that are XA-compliant (and use a two-phase commit process) are defined at:

http://www.ibm.com/software/ts/mqseries/platforms/supported.html

 

The CICS two-phase commit process

This process applies to those versions of WebSphere MQ that support an XA-compliant external syncpoint coordinator, as defined at:

http://www.ibm.com/software/ts/mqseries/platforms/supported.html

 

Requirements of the two-phase commit process

When you use the CICS two-phase commit process with WebSphere MQ, note the following requirements:

• WebSphere MQ and CICS must reside on the same physical machine.

• WebSphere MQ does not support CICS on a WebSphere MQ client.

• You must start the queue manager, with its name specified in the XAD resource definition stanza, before you attempt to start CICS. Failure to do this will prevent you from starting CICS if you have added an XAD resource definition stanza for WebSphere MQ to the CICS region.

• Only one WebSphere MQ queue manager can be accessed at a time from a single CICS region.

• A CICS transaction must issue an MQCONN request before it can access WebSphere MQ resources. The MQCONN call must specify the name of the WebSphere MQ queue manager specified on the XAOpen entry of the XAD resource definition stanza for the CICS region. If this entry is blank, the MQCONN request must specify the default queue manager.

• A CICS transaction that accesses WebSphere MQ resources must issue an MQDISC call from the transaction before returning to CICS. Failure to do this might mean that the CICS appserver is still connected, leaving queues open.

• You must ensure that the CICS user ID (cics) is a member of the mqm group, so that the CICS code has the authority to call WebSphere MQ.

  For transactions running in a CICS environment, the queue manager adapts its methods of authorization and determining context as follows:

  • The queue manager queries the user ID under which CICS runs the transaction. This is the user ID checked by the Object Authority Manager, and is used for context information.

  • In the message context, the application type is MQAT_CICS.

  • The application name in the context is copied from the CICS transaction name.

 

Enabling the CICS two-phase commit process

To enable CICS to use a two-phase commit process to coordinate transactions that include MQI calls, add a CICS XAD resource definition stanza entry to the CICS region.

Here is an example of adding an XAD stanza entry for WebSphere MQ for Windows, where <Drive> is the drive where WebSphere MQ is installed (for example, D:).

cicsadd -cxad -r<cics_region> \
     ResourceDescription="MQM XA Product Description" \
     SwitchLoadFile="<Drive>:\Program Files\IBM\WebSphere MQ\bin\mqmc4swi.dll" \
     XAOpen=<queue_manager_name>

Here is an example of adding an XAD stanza entry for WebSphere MQ for UNIX systems:

cicsadd -cxad -r<cics_region> \
      ResourceDescription="MQM XA Product Description" \
      SwitchLoadFile="/opt/mqm/lib/amqzsc" \
      XAOpen=<queue_manager_name>

For information about using the cicsadd command, see the CICS Administration Reference, or CICS Administration Guide for your platform.

Calls to WebSphere MQ can be included in a CICS transaction, and the WebSphere MQ resources will be committed or rolled back as directed by CICS. This support is not available to client applications.

You must issue an MQCONN from your CICS transaction in order to access WebSphere MQ resources, followed by a corresponding MQDISC on exit.

 

Enabling CICS user exits

Before using a CICS user exit, read the CICS Administration Guide for your platform.

A CICS user exit point (normally referred to as a user exit) is a place in a CICS module at which CICS can transfer control to a program that you have written (a user exit program), and at which CICS can resume control when your exit program has finished its work.

One of the user exits supplied with CICS is the Task termination user exit (UE014015), invoked at normal and abnormal task termination (after any syncpoint has been taken).

WebSphere MQ supplies a CICS task termination exit in source and executable form:

Table 18. CICS task termination exits

WebSphere MQ for...	Source	Executable
Windows	amqzscgn.c	mqmc1415.dll
UNIX systems	amqzscgx.c	amqzscg

If you are currently using this exit, add the WebSphere MQ calls from the supplied exits to your current exits. Integrate the WebSphere MQ calls into your existing exits at the appropriate place in the program logic. See the comments in the sample source file for help with this.

If you are not currently using this exit, add a CICS PD program definition stanza entry to the CICS region.

Here is an example of adding a PD stanza entry for Windows:

cicsadd -cpd -r<cics_region> \
      PathName="<Drive>:\Program Files\IBM\WebSphere MQ\bin\mqmc1415.dll" \
      UserExitNumber=15

Here is an example of adding a PD stanza entry for UNIX systems:

cicsadd -cpd -r<cics_region> \
      PathName="/opt/mqm/lib/amqzscg" \
      UserExitNumber=15

 

Using the Microsoft Transaction Server (MTS)

MTS (Microsoft Transaction Server) is designed to help users run business logic applications in a typical middle tier server. MTS divides work up into activities, which are typically short independent chunks of business logic, such as transfer funds from account A to account B. MTS relies heavily on object orientation and in particular on COM; loosely an MTS activity is represented by a COM (business) object.

Note:

MTS is the name of the component that you can install (from the Option Pack) on Windows NT. On Windows 2000 and Windows XP, it is known as COM+ and is an integrated part of the operating system. To use COM+ on Windows 2000 and Windows XP, you need Hotfix Q313582 (also known as COM+ Rollup Package 19.1). Throughout this section, we refer to it as MTS.

MTS provides three services to the business object administrator, removing much of the worry from the business object programmer:

• Transaction management

• Security

• Resource pooling

You usually use MTS with front end code that is a COM client to the objects held within MTS, and back end services such as a database, with WebSphere MQ bridging between the MTS business object and the back end.

The front end code can be a standalone program, or an Active Server Page (ASP) hosted by the Microsoft Internet Information Server (IIS). The front end code can reside on the same computer as MTS and its business objects, with connection through COM. Alternatively, the front end code can reside on a different computer, with connection through DCOM. You can use different clients to access the same MTS business object in different situations.

The back end code can reside on the same computer as MTS and its business objects, or on a different computer with connection through any of the WebSphere MQ supported protocols.

For detailed information on using MTS, including how to configure it, and how to develop your applications and object code, read the WebSphere MQ MTS Support part of the Help Center.

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.