Skipping backout
Supported only on WebSphere MQ for z/OS.
As part of a unit of work, an application program can issue one or more
MQGET calls to get messages from a queue. If the application program detects
an error, it can back out the unit of work. This restores all the resources
updated during that unit of work to the state that they were in before the
unit of work started, and reinstates the messages retrieved by the MQGET calls.
Once reinstated, these messages are available to subsequent MQGET calls
issued by the application program. In many cases, this does not cause a problem
for the application program. However, in cases where the error leading to
the backout cannot be circumvented, having the message reinstated on the queue
can cause the application program to enter an MQGET-error-backout loop.
To avoid this problem, specify the MQGMO_MARK_SKIP_BACKOUT option on the
MQGET call. This marks the MQGET request as not being involved in application-initiated
backout; that is, it should not be backed out. Use of this option means that
when a backout occurs, updates to other resources are backed out as required,
but the marked message is treated as if it had been retrieved under a new
unit of work.
The application program must issue a WebSphere MQ call either to commit
the new unit of work, or to back out the new unit of work. For example, the
program can perform exception handling, such as informing the originator that
the message has been discarded, and commit the unit of work so removing the
message from the queue, If the new unit of work is backed out (for any reason)
the message is reinstated on the queue.
Within a unit of work, there can be only one MQGET request marked as skipping
backout; however, there can be several other messages that are not marked
as skipping backout. Once a message has been marked as skipping backout,
any further MQGET calls within the unit of work that specify MQGMO_MARK_SKIP_BACKOUT
fail with reason code MQRC_SECOND_MARK_NOT_ALLOWED.
Notes:
- The marked message skips backout only if the unit of work containing it
is terminated by an application request to back it out. If the unit of work
is backed out for any other reason, the message is backed out onto the queue
in the same way that it would be if it was not marked to skip backout.
- Skip backout is not supported within DB2 stored procedures participating
in units of work controlled by RRS. For
example, an MQGET call with the MQGMO_MARK_SKIP_BACKOUT option will fail with
the reason code MQRC_OPTION_ENVIRONMENT_ERROR.
Figure 12 illustrates a typical sequence of steps that an
application program might contain when an MQGET request is required to skip
backout.
The steps in Figure 12 are:
- Step 1
- Initial processing occurs within the transaction, including an MQOPEN
call to open the queue (specifying one of the MQOO_INPUT_* options in order
to get messages from the queue in Step 2).
- Step 2
- MQGET is called, with MQGMO_SYNCPOINT and MQGMO_MARK_SKIP_BACKOUT. MQGMO_SYNCPOINT
is required because MQGET must be within a unit of work for MQGMO_MARK_SKIP_BACKOUT
to be effective. In Figure 12 this unit of work is referred
to as UOW1.
- Step 3
- Other resource updates are made as part of UOW1. These can include
further MQGET calls (issued without MQGMO_MARK_SKIP_BACKOUT).
- Step 4
- All updates from Steps 2 and 3 complete as required. The application
program commits the updates and UOW1 ends. The message retrieved in Step
2 is removed from the queue.
- Step 5
- Some of the updates from Steps 2 and 3 do not complete as required.
The application program requests that the updates made during these steps
are backed out.
- Step 6
- The updates made in Step 3 are backed out.
- Step 7
- The MQGET request made in Step 2 skips backout and becomes part of a
new unit of work, UOW2.
- Step 8
- UOW2 performs exception handling in response to UOW1 being backed out.
(For example, an MQPUT call to another queue, indicating that a problem occurred
that caused UOW1 to be backed out.)
- Step 9
- Step 8 completes as required, the application program commits the activity,
and UOW2 ends. As the MQGET request is part of UOW2 (see Step 7), this commit
causes the message to be removed from the queue.
- Step 10
- Step 8 does not complete as required and the application program backs
out UOW2. Because the get message request is part of UOW2 (see Step 7), it
too is backed out and reinstated on the queue. It is now available to further
MQGET calls issued by this or another application program (in the same way
as any other message on the queue).