Syncpoints in WebSphere MQ for z/OS applications

Syncpoints in WebSphere MQ for z/OS applications

This section explains how to use syncpoints in transaction manager (CICS and IMS) and batch applications.

Syncpoints in CICS Transaction Server for z/OS and CICS for MVS/ESA applications

In a CICS application you establish a syncpoint by using the EXEC CICS SYNCPOINT command. To back out all changes to the previous syncpoint, you can use the EXEC CICS SYNCPOINT ROLLBACK command. For more information, see the CICS Application Programming Reference.
If other recoverable resources are also involved in the unit of work, the queue manager (in conjunction with the CICS syncpoint manager) participates in a two-phase commit protocol; otherwise, the queue manager performs a single-phase commit process.
If a CICS application issues the MQDISC call, no implicit syncpoint is taken. If the application closes down normally, any open queues are closed and an implicit commit occurs. If the application closes down abnormally, any open queues are closed and an implicit backout occurs.

Syncpoints in IMS applications

In an IMS application, you establish a syncpoint by using IMS calls such as GU (get unique) to the IOPCB and CHKP (checkpoint). To back out all changes since the previous checkpoint, you can use the IMS ROLB (rollback) call. For more information, see the following books:

IMS/ESA(R) Version 4 Application Programming: DL/I Calls
IMS/ESA Version 4 Application Programming: Design Guide
IMS/ESA Version 5 Application Programming: Database Manager
IMS/ESA Version 5 Application Programming: Design Guide

The queue manager (in conjunction with the IMS syncpoint manager) participates in a two-phase commit protocol if other recoverable resources are also involved in the unit of work.
All open handles are closed by the IMS adapter at a syncpoint (except in a nonmessage batch-oriented BMP). This is because a different user could initiate the next unit of work and WebSphere MQ security checking is performed when the MQCONN, MQCONNX, and MQOPEN calls are made, not when the MQPUT or MQGET calls are made. The handles are closed at the beginning of the MQI call following the IMS call which initiated the syncpoint.
If you have not installed IMS APAR PN83757, handles are also closed after a ROLB call unless you are running IMS Version 3 or are running a nonmessage BMP.
If an IMS application (either a BMP or an MPP) issues the MQDISC call, open queues are closed but no implicit syncpoint is taken. If the application closes down normally, any open queues are closed and an implicit commit occurs. If the application closes down abnormally, any open queues are closed and an implicit backout occurs.

Syncpoints in z/OS batch applications

For batch applications, you can use the WebSphere MQ syncpoint management calls: MQCMIT and MQBACK. For backward compatibility, CSQBCMT and CSQBBAK are available as synonyms.

Note:

To commit or back out updates to resources managed by different resource managers, such as WebSphere MQ and DB2, within a single unit of work you could use RRS. For further information see Transaction management and recoverable resource manager services.

Committing changes using the MQCMIT call

As input, supply the connection handle (Hconn), which is returned by the MQCONN or MQCONNX call.
The output from MQCMIT is a completion code and a reason code. The call completes with a warning if the syncpoint was completed but the queue manager backed out the put and get operations since the previous syncpoint.
Successful completion of the MQCMIT call indicates to the queue manager that the application has reached a syncpoint and that all put and get operations made since the previous syncpoint have been made permanent.
Not all failure responses mean that the MQCMIT did not complete. For example, the application can receive MQRC_CONNECTION_BROKEN.
There is a description of the MQCMIT call in WebSphere MQ Application Programming Reference.

Backing out changes using the MQBACK call

As input, supply a connection handle (Hconn). Use the handle that is returned by the MQCONN or MQCONNX call.
The output from MQBACK is a completion code and a reason code.
The output indicates to the queue manager that the application has reached a syncpoint and that all gets and puts that have been made since the last syncpoint have been backed out.
There is a description of the MQBACK call in WebSphere MQ Application Programming Reference.

Transaction management and recoverable resource manager services

Transaction management and recoverable resource manager services (RRS) is an z/OS facility to provide two-phase syncpoint support across participating resource managers. An application can update recoverable resources managed by various z/OS resource managers such as WebSphere MQ and DB2, and then commit or back out these updates as a single unit of work. RRS provides the necessary unit-of-work status logging during normal execution, coordinates the syncpoint processing, and provides appropriate unit-of-work status information during subsystem restart.
WebSphere MQ for z/OS RRS participant support enables WebSphere MQ applications in the batch, TSO, and DB2 stored procedure environments to update both WebSphere MQ and non-WebSphere MQ resources (for example, DB2) within a single logical unit of work. For information about RRS participant support, see the MVS Programming: Resource Recovery book.
Your WebSphere MQ application can use either MQCMIT and MQBACK or the equivalent RRS calls, SRRCMIT and SRRBACK. See RRS batch adapter for more information.

RRS availability

If RRS is not active on your z/OS system, any WebSphere MQ call issued from a program linked with either RRS stub (CSQBRSTB or CSQBRRSI) returns MQRC_ENVIRONMENT_ERROR.

DB2 stored procedures

If you use DB2 stored procedures with RRS be aware of the following guidelines:

DB2 stored procedures that use RRS must be WLM-managed.
If a DB2-managed stored procedure contains WebSphere MQ calls, and it is linked with either RRS stub (CSQBRSTB or CSQBRRSI), the MQCONN or MQCONNX call returns MQRC_ENVIRONMENT_ERROR.
If a WLM-managed stored procedure contains WebSphere MQ calls, and is linked with a non-RRS stub, the MQCONN or MQCONNX call returns MQRC_ENVIRONMENT_ERROR, unless it is the first WebSphere MQ call executed since the stored procedure address space started.
If your DB2 stored procedure contains WebSphere MQ calls and is linked with a non-RRS stub, WebSphere MQ resources updated in that stored procedure are not committed until the stored procedure address space ends, or until a subsequent stored procedure does an MQCMIT (using a WebSphere MQ Batch/TSO stub).
Multiple copies of the same stored procedure can execute concurrently in the same address space. You should ensure that your program is coded in a reentrant manner if you want DB2 to use a single copy of your stored procedure. Otherwise you may receive MQRC_HCONN_ERROR on any WebSphere MQ call in your program.
You must not code MQCMIT or MQBACK in a WLM-managed DB2 stored procedure.
All programs must be designed to run in Language Environment^(R) (LE).

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.