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.

    If CompCode 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.

    If CompCode 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 Reason codes.


Usage notes

  1. 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.
    • 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 we use the MQCMIT or MQBACK call to commit or back out the unit of work, the call fails with reason code MQRC_ENVIRONMENT_ERROR.

  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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 the CMTSCOPE(*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 the CMTSCOPE(*JOB) parameter must have been issued for the job. If this has been done, the IBM i COMMIT and ROLLBACK operations apply to MQ resources as well as to resources belonging to other participating resource managers.


C invocation

MQBEGIN (Hconn, &BeginOptions, &CompCode, &Reason);
Declare the parameters as follows: 
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.
Declare the parameters as follows: 
**   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);
Declare the parameters as follows: 
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
Declare the parameters as follows: 
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'