Committing and backing out units of work

This information describes how to commit and back out any recoverable get and put operations that have occurred in a unit of work.

The following terms are used in this topic:

  • Commit
  • Back out
  • Syncpoint coordination
  • Syncpoint
  • Unit of work
  • Single-phase commit
  • Two-phase commit

If we are familiar with these transaction processing terms, we can skip to Syncpoint considerations in IBM MQ applications.

    Commit and back out
    When a program puts a message on a queue within a unit of work, that message is made visible to other programs only when the program commits the unit of work. To commit a unit of work, all updates must be successful to preserve data integrity. If the program detects an error and decides that the put operation is not permanent, it can back out the unit of work. When a program performs a backout, IBM MQ restores the queue by removing the messages that were put on the queue by that unit of work. The way in which the program performs the commit and back out operations depends on the environment in which the program is running.

    Similarly, when a program gets a message from a queue within a unit of work, that message remains on the queue until the program commits the unit of work, but the message is not available to be retrieved by other programs. The message is permanently deleted from the queue when the program commits the unit of work. If the program backs out the unit of work, IBM MQ restores the queue by making the messages available to be retrieved by other programs.

    Syncpoint coordination, syncpoint, unit of work
    Syncpoint coordination is the process by which units of work are either committed or backed out with data integrity.

    The decision to commit or back out the changes is taken, in the simplest case, at the end of a transaction. However, it can be more useful for an application to synchronize data changes at other logical points within a transaction. These logical points are called syncpoints (or synchronization points ) and the period of processing a set of updates between two syncpoints is called a unit of work. Several MQGET calls and MQPUT calls can be part of a single unit of work.

    On z/OS, the maximum number of messages within a unit of work can be controlled by the DEFINE MAXSMGS command.

    On Multiplatforms, the maximum number of messages within a unit of work can be controlled by the MAXUMSGS attribute of the ALTER QMGR command.

    Single-phase commit
    A single-phase commit process is one in which a program can commit updates to a queue without coordinating its changes with other resource managers.

    Two-phase commit
    A two-phase commit process is one in which updates that a program has made to IBM MQ queues can be coordinated with updates to other resources (for example, databases under the control of Db2 ). Under such a process, updates to all resources are committed or backed out together.

    To help handle units of work, IBM MQ provides the BackoutCount attribute. This is incremented each time that a message within a unit of work is backed out. If the message repeatedly causes the unit of work to abnormally end, the value of the BackoutCount finally exceeds that of the BackoutThreshold. This value is set when the queue is defined. In this situation, the application can remove the message from the unit of work and put it onto another queue, as defined in BackoutRequeueQName. When the message is moved, the unit of work can commit.

Use the following links to find out more about committing and backing out units of work:

Parent topic: Writing a procedural application for queuing


Related concepts