Global units of work
Use global units of work when you also need to include updates to resources belonging to other resource managers.
Here the coordination can be internal or external to the queue manager:
Internal syncpoint coordination
Queue manager coordination of global units of work is not supported by IBM MQ for IBM i or IBM MQ for z/OS . It is not supported in an IBM MQ MQI client environment.
Here, IBM MQ does the coordination. To start a global unit of work, the application issues the MQBEGIN call.
As input to the MQBEGIN call, we must supply the connection handle (Hconn) that is returned by the MQCONN or MQCONNX call. This handle represents the connection to the IBM MQ queue manager.
The application issues MQGET, MQPUT, or MQPUT1 requests specifying the appropriate syncpoint option. This means that we can use MQBEGIN to initiate a global unit of work that updates local resources, resources belonging to other resource managers, or both. Updates made to resources belonging to other resource managers are made using the API of that resource manager. However, we cannot use the MQI to update queues that belong to other queue managers. Issue MQCMIT or MQBACK before starting further units of work (local or global).
The global unit of work is committed using MQCMIT; this initiates a two-phase commit of all the resource managers involved in the unit of work. A two-phase commit process is used whereby resource managers (for example, XA-compliant database managers such as Db2, Oracle, and Sybase) are first all asked to prepare to commit. Only if all are prepared are they asked to commit. If any resource manager signals that it cannot commit, each is asked to back out instead. Alternatively, we can use MQBACK to roll back the updates of all the resource managers.
If an application disconnects (MQDISC) while a global unit of work is still active, the unit of work is committed. If, however, the application terminates without disconnecting, the unit of work is rolled back as the application is deemed to have terminated abnormally.
The output from MQBEGIN is a completion code and a reason code.
When we use MQBEGIN to start a global unit of work, all the external resource managers that have been configured with the queue manager are included. However, the call starts a unit of work but completes with a warning if:
- There are no participating resource managers (that is, no resource managers have been configured with the queue manager)
or
- One or more resource managers are not available.
In these cases, the unit of work must include updates to only those resource managers that were available when the unit of work was started.
If one of the resource managers cannot commit its updates, all the resource managers are instructed to roll back their updates, and MQCMIT completes with a warning. In unusual circumstances (typically, operator intervention), an MQCMIT call might fail if some resource managers commit their updates but others roll them back; the work is deemed to have completed with a mixed outcome. Such occurrences are diagnosed in the error log of the queue manager so that remedial action may be taken.
An MQCMIT of a global unit of work succeeds if all the resource managers involved commit their updates.
For a description of the MQBEGIN call, see MQBEGIN.
External syncpoint coordination
This occurs when a syncpoint coordinator other than IBM MQ has been selected; for example, CICS, Encina, or Tuxedo.
In this situation, IBM MQ on UNIX and Linux systems and IBM MQ for Windows register their interest in the outcome of the unit of work with the syncpoint coordinator so that they can commit or roll back any uncommitted get or put operations as required. The external syncpoint coordinator determines whether one- or two-phase commitment protocols are provided.
When we use an external coordinator, MQCMIT, MQBACK, and MQBEGIN cannot be issued. Calls to these functions fail with the reason code MQRC_ENVIRONMENT_ERROR.
The way in which an externally coordinated unit of work is started depends on the programming interface provided by the syncpoint coordinator. An explicit call might be required. If an explicit call is required, and we issue an MQPUT call specifying the MQPMO_SYNCPOINT option when a unit of work is not started, the completion code MQRC_SYNCPOINT_NOT_AVAILABLE is returned.
The scope of the unit of work is determined by the syncpoint coordinator. The state of the connection between the application and the queue manager affects the success or failure of MQI calls that an application issues, not the state of the unit of work. An application can, for example, 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 known as a pending disconnect.
We can use IBM MQ API calls in CICS programs, whether you choose to use the XA abilities of CICS. If we do not use XA, then the puts and gets of messages to and from queues will not be managed within CICS atomic units of work. One reason for choosing this method is that the overall consistency of the unit of work is not important to you.
If the integrity of our units of work is important to you, then we must use XA. When we use XA, CICS uses a two-phase commit protocol to ensure all resources within the unit of work are updated together.
For more information about setting up transactional support, see Transactional support scenarios, and also TXSeries CICS documentation, for example, TXSeries for Multiplatforms CICS Administration Guide for Open Systems.
Parent topic: Syncpoints in IBM MQ for IBM i, UNIX, Linux, and Windows