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 shown in Table 15.

The CICS two-phase commit process

This process applies to those versions of WebSphere MQ that support an XA-compliant external syncpoint coordinator as shown in Table 15.

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 application server 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 16. CICS task termination exits

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