Only supported in 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 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 can then perform exception handling, such as informing the originator
that the message has been discarded, and then commit the new unit of work,
causing the message to be removed 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 will fail with reason code
MQRC_SECOND_MARK_NOT_ALLOWED.
Notes:
- The marked message only skips backout 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 on to 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. Skipping backout using MQGMO_MARK_SKIP_BACKOUT
Figure 12 illustrates a typical sequence of steps that an application
program might contain when an MQGET request is required to skip backout:
- 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 may 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).
© IBM Corporation 1993, 2002. All Rights Reserved