MQBEGIN - Begin unit of work
The MQBEGIN call begins a unit of work that is coordinated by the queue manager, and that can involve external resource managers.
Syntax
MQBEGIN (Hconn, BeginOptions, Compcode, Reason)
Parameters
- Hconn
- Type: MQHCONN - input
This handle represents the connection to the queue manager. The value of
Hconn
was returned by a previous MQCONN or MQCONNX call.Hconn
must be a nonshared connection handle. If a shared connection handle is specified, the call fails with reason code MQRC_HCONN_ERROR. See the description of the MQCNO_HANDLE_SHARE_* options in MQCNO - Connect options for more information about shared and nonshared handles. - BeginOptions
- Type: MQBO - input/output
These are options that control the action of MQBEGIN, as described in MQBO - Begin options.
If no options are required, programs written in C or S/390 assembler can specify a null parameter address, instead of specifying the address of an MQBO structure.
- CompCode
- Type: MQLONG - output
The completion code; it is one of the following:
- MQCC_OK
- Successful completion.
- MQCC_WARNING
- Warning (partial completion).
- MQCC_FAILED
- Call failed.
- Reason
- Type: MQLONG - output
If
CompCode
is MQCC_OK:- MQRC_NONE
- (0, X'000') No reason to report.
IfCompCode
is MQCC_WARNING:- MQRC_NO_EXTERNAL_PARTICIPANTS
- (2121, X'849') No participating resource managers registered.
- MQRC_PARTICIPANT_NOT_AVAILABLE
- (2122, X'84A') Participating resource manager not available.
IfCompCode
is MQCC_FAILED:- MQRC_API_EXIT_ERROR
- (2374, X'946') API exit failed.
- MQRC_BO_ERROR
- (2134, X'856') Begin-options structure not valid.
- MQRC_CALL_IN_PROGRESS
- (2219, X'8AB') MQI call entered before previous call complete.
- MQRC_CONNECTION_BROKEN
- (2009, X'7D9') Connection to queue manager lost.
- MQRC_ENVIRONMENT_ERROR
- (2012, X'7DC') Call not valid in environment.
- MQRC_HCONN_ERROR
- (2018, X'7E2') Connection handle not valid.
- MQRC_OPTIONS_ERROR
- (2046, X'7FE') Options not valid or not consistent.
- MQRC_Q_MGR_STOPPING
- (2162, X'872') Queue manager shutting down.
- MQRC_RESOURCE_PROBLEM
- (2102, X'836') Insufficient system resources available.
- MQRC_STORAGE_NOT_AVAILABLE
- (2071, X'817') Insufficient storage available.
- MQRC_UNEXPECTED_ERROR
- (2195, X'893') Unexpected error occurred.
- MQRC_UOW_IN_PROGRESS
- (2128, X'850') Unit of work already started.
For more information about these reason codes, see Messages and reason codes.
Usage notes
- Use the MQBEGIN call to start a unit of work that is coordinated by the queue manager and that might involve changes to resources owned by other resource managers. The queue manager supports three types of unit-of-work:
- Queue-manager-coordinated local unit of work: A unit of work in which the queue manager is the only resource manager participating, and so the queue manager acts as the unit-of-work coordinator.
- To start this type of unit of work, specify the MQPMO_SYNCPOINT or MQGMO_SYNCPOINT option on the first MQPUT, MQPUT1, or MQGET call in the unit of work.
- To commit or back out this type of unit of work, use the MQCMIT or MQBACK call.
- To start this type of unit of work, specify the MQPMO_SYNCPOINT or MQGMO_SYNCPOINT option on the first MQPUT, MQPUT1, or MQGET call in the unit of work.
- Queue-manager-coordinated global unit of work: A unit of work in which the queue manager acts as the unit-of-work coordinator, both for MQ resources and for resources belonging to other resource managers. Those resource managers cooperate with the queue manager to ensure that all changes to resources in the unit of work are committed or backed out together.
- To start this type of unit of work, use the MQBEGIN call.
- To commit or back out this type of unit of work, use the MQCMIT and MQBACK calls.
- Externally-coordinated global unit of work: A unit of work in which the queue manager is a participant, but the queue manager does not act as the unit-of-work coordinator. Instead, there is an external unit-of-work coordinator with which the queue manager cooperates.
- To start this type of unit of work, use the relevant call provided by the external unit-of-work coordinator.
If the MQBEGIN call is used to try to start the unit of work, the call fails with reason code MQRC_ENVIRONMENT_ERROR.
- To commit or back out this type of unit of work, use the commit and back-out calls provided by the external unit-of-work coordinator.
If you use the MQCMIT or MQBACK call to commit or back out the unit of work, the call fails with reason code MQRC_ENVIRONMENT_ERROR.
- To start this type of unit of work, use the relevant call provided by the external unit-of-work coordinator.
- Queue-manager-coordinated local unit of work: A unit of work in which the queue manager is the only resource manager participating, and so the queue manager acts as the unit-of-work coordinator.
- If the application ends with uncommitted changes in a unit of work, the disposition of those changes depends on whether the application ends normally or abnormally. See the usage notes in MQDISC - Disconnect queue manager for further details.
- An application can participate in only one unit of work at a time. The MQBEGIN call fails with reason code MQRC_UOW_IN_PROGRESS if there is already a unit of work in existence for the application, regardless of which type of unit of work it is.
- The MQBEGIN call is not valid in an MQ MQI client environment. An attempt to use the call fails with reason code MQRC_ENVIRONMENT_ERROR.
- When the queue manager is acting as the unit-of-work coordinator for global units of work, the resource managers that can participate in the unit of work are defined in the queue manager configuration file.
- On IBM® i, the three types of unit of work are supported as follows:
- Queue-manager-coordinated local unit of work can be used only when a commitment definition does not exist at the job level, that is, the
STRCMTCTL
command with theCMTSCOPE(*JOB)
parameter must not have been issued for the job. - Queue-manager-coordinated global unit of work is not supported.
- Externally-coordinated global unit of work can be used only when a commitment definition exists at job level, that is, the
STRCMTCTL
command with theCMTSCOPE(*JOB)
parameter must have been issued for the job. If this has been done, the IBM iCOMMIT
andROLLBACK
operations apply to MQ resources as well as to resources belonging to other participating resource managers.
- Queue-manager-coordinated local unit of work can be used only when a commitment definition does not exist at the job level, that is, the
C invocation
MQBEGIN (Hconn, &BeginOptions, &CompCode, &Reason);
MQHCONN Hconn; /* Connection handle */
MQBO BeginOptions; /* Options that control the action of MQBEGIN */
MQLONG CompCode; /* Completion code */
MQLONG Reason; /* Reason code qualifying CompCode */
COBOL invocation
CALL 'MQBEGIN' USING HCONN, BEGINOPTIONS, COMPCODE, REASON.
** Connection handle
01 HCONN PIC S9(9) BINARY.
** Options that control the action of MQBEGIN
01 BEGINOPTIONS.
COPY CMQBOV.
** Completion code
01 COMPCODE PIC S9(9) BINARY.
** Reason code qualifying COMPCODE
01 REASON PIC S9(9) BINARY.
PL/I invocation
call MQBEGIN (Hconn, BeginOptions, CompCode, Reason);
dcl Hconn fixed bin(31); /* Connection handle */
dcl BeginOptions like MQBO; /* Options that control the action of
MQBEGIN */
dcl CompCode fixed bin(31); /* Completion code */
dcl Reason fixed bin(31); /* Reason code qualifying CompCode */
Visual Basic invocation
MQBEGIN Hconn, BeginOptions, CompCode, Reason
Dim Hconn As Long 'Connection handle'
Dim BeginOptions As MQBO 'Options that control the action of MQBEGIN'
Dim CompCode As Long 'Completion code'
Dim Reason As Long 'Reason code qualifying CompCode'