Interfaces to the IBM i external syncpoint manager

IBM MQ for IBM i can use native IBM i commitment control as an external syncpoint coordinator.

Thread-independent (shared) connections are not allowed with commitment control. See the IBM i Programming: Backup and Recovery Guide, SC21-8079 for more information about the commitment control capabilities of IBM i.

To start the IBM i commitment control facilities, use the STRCMTCTL system command. To end commitment control, use the ENDCMTCTL system command.

Note: The default value of Commitment definition scope is *ACTGRP. This must be defined as *JOB for IBM MQ for IBM i. For example: 
STRCMTCTL LCKLVL(*ALL) CMTSCOPE(*JOB)

IBM MQ for IBM i can also perform local units of work containing only updates to IBM MQ resources. The choice between local units of work and participation in global units of work coordinated by IBM i 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, IBM MQ starts a local unit of work and all further units of work for this connection to IBM MQ also use local units of work, regardless of whether commitment control is then started. To commit a local unit of work, use MQCMIT. To back out a local unit of work, use MQBACK. The IBM i commit and rollback calls such as the CL command COMMIT have no effect on IBM MQ local units of work.

If you want to use IBM MQ for IBM i with native IBM i commitment control as an external syncpoint coordinator, ensure that any job with commitment control is active and that you are using IBM 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, IBM MQ for IBM i 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.

IBM MQ for IBM i removes its registration as an API commitment resource when you disconnect from the queue manager, if 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, IBM MQ for IBM i remains registered as an API commitment resource so that it is notified of the next commit or rollback. When the next syncpoint is reached, IBM MQ for IBM i 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 IBM MQ for IBM i operations, and disconnect from the queue manager. Thus, using COMMIT or ROLLBACK commands before ENDCMTCTL enables end-commitment control to complete successfully.

When we use IBM i 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:

  • CL commands: COMMIT and ROLLBACK
  • ILE C Programming Functions: _Rcommit and _Rrollback
  • ILE RPG: COMMIT and ROLBK
  • COBOL/400®: COMMIT and ROLLBACK

When we use IBM i commitment control as an external syncpoint coordinator with IBM MQ for IBM i, IBM i performs a two-phase commit protocol in which IBM 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 IBM 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.