Interfaces to the i5/OS external syncpoint manager

 

WebSphere MQ for iSeries can use native i5/OS commitment control as an external syncpoint coordinator. Thread-independent (shared) connections are not allowed with commitment control. See the AS/400 Programming: Backup and Recovery Guide, SC21-8079 for more information about the commitment control capabilities of i5/OS.

To start the i5/OS commitment control facilities, use the STRCMTCTL system command. To end commitment control, use the ENDCMTCTL system command.

The default value of Commitment definition scope is *ACTGRP. This must be defined as *JOB for WebSphere MQ for iSeries. For example: 

STRCMTCTL LCKLVL(*ALL) CMTSCOPE(*JOB)

WebSphere MQ for iSeries can also perform local units of work containing only updates to WebSphere MQ resources. The choice between local units of work and participation in global units of work coordinated byi5/OS is made in each application when the application calls MQPUT, MQPUT1, or MQGET, specifying MQPMO_SYNCPOINT or MQGMO_SYNCPOINT, or MQBEGIN. If commitment control is not active when the first such call is issued, WebSphere MQ starts a local unit of work and all further units of work for this connection to WebSphere MQ will also use local units of work, regardless of whether commitment control is subsequently started. To commit or back out a local unit of work, use MQCMIT or MQBACK respectively in the same way as other WebSphere MQ products. Thei5/OS commit and rollback calls such as the CL command COMMIT have no effect on WebSphere MQ local units of work.

If you want to use WebSphere MQ for iSeries with native i5/OS commitment control as an external syncpoint coordinator, ensure that any job with commitment control is active and that you are using WebSphere MQ in a single-threaded job. If you call MQPUT, MQPUT1, or MQGET, specifying MQPMO_SYNCPOINT or MQGMO_SYNCPOINT, in a multithreaded job in which commitment control has been started, the call fails with a reason code of MQRC_SYNCPOINT_NOT_AVAILABLE.

It is possible to use local units of work and the MQCMIT and MQBACK calls in a multithreaded job.

If you call MQPUT, MQPUT1, or MQGET, specifying MQPMO_SYNCPOINT or MQGMO_SYNCPOINT, after starting commitment control, WebSphere MQ for iSeries adds itself as an API commitment resource to the commitment definition. This is typically the first such call in a job. While there are any API commitment resources registered under a particular commitment definition, we cannot end commitment control for that definition.

WebSphere MQ for iSeries removes its registration as an API commitment resource when you disconnect from the queue manager, provided that there are no pending MQI operations in the current unit of work.

If you disconnect from the queue manager while there are pending MQPUT, MQPUT1, or MQGET operations in the current unit of work, WebSphere MQ for iSeries remains registered as an API commitment resource so that it is notified of the next commit or rollback. When the next syncpoint is reached, WebSphere MQ for iSeries commits or rolls back the changes as required. An application can disconnect and reconnect to a queue manager during an active unit of work and perform further MQGET and MQPUT operations inside the same unit of work (this is a pending disconnect).

If you attempt to issue an ENDCMTCTL system command for that commitment definition, message CPF8355 is issued, indicating that pending changes were active. This message also appears in the job log when the job ends. To avoid this, commit or roll back all pending WebSphere MQ for iSeries operations, and disconnect from the queue manager. Thus, using COMMIT or ROLLBACK commands before ENDCMTCTL should enable end-commitment control to complete successfully.

When you use i5/OS commitment control as an external syncpoint coordinator, we cannot issue MQCMIT, MQBACK, and MQBEGIN calls. Calls to these functions fail with the reason code MQRC_ENVIRONMENT_ERROR.

To commit or roll back (that is, to back out) your unit of work, use one of the programming languages that supports the commitment control. For example:

When you use i5/OS commitment control as an external syncpoint coordinator with WebSphere MQ for iSeries, i5/OS performs a two-phase commit protocol in which WebSphere MQ participates. Because each unit of work is committed in two phases, the queue manager might become unavailable for the second phase after having voted to commit in the first phase. This can happen, for example, if the queue manager's internal jobs are ended. In this situation, the job log performing the commit contains message CPF835F indicating that a commit or rollback operation failed. The messages preceding this indicate the cause of the problem, whether it occurred during a commit or rollback operation, and also the logical unit of work ID (LUWID) for the failed unit of work.

If the problem was caused by the failure of the WebSphere MQ API commitment resource during the commit or rollback of a prepared unit of work, we can use the WRKMQMTRN command to complete the operation and restore the integrity of the transaction. The command requires that you know the LUWID of the unit of work to commit and back out.

 

Parent topic:

Committing and backing out units of work


fg13800_