MQBEGIN (Begin unit of work) on IBM i

The MQBEGIN call begins a unit of work that is coordinated by the queue manager, and that may involve external resource managers.

  • This call is supported in the following environments:

    • AIX
    • IBM i
    • Windows


Syntax

MQBEGIN (HCONN, BEGOP, CMPCOD, REASON)


Usage notes

  1. The MQBEGIN call can be used 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
      This is 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, the PMSYP or GMSYP option should be specified on the first MQPUT, MQPUT1, or MQGET call in the unit of work.

        It is not necessary for the application to issue the MQBEGIN call to start the unit of work, but if MQBEGIN is used, the call completes with CCWARN and reason code RC2121.

      • To commit or back out this type of unit of work, the MQCMIT or MQBACK call must be used.

      Queue manager-coordinated global unit of work
      This is a unit of work in which the queue manager acts as the unit-of-work coordinator, both for IBM 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, the MQBEGIN call must be used.
      • To commit or back out this type of unit of work, the MQCMIT and MQBACK calls must be used.

      Externally-coordinated global unit of work
      This is 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 whom the queue manager cooperates.

      • To start this type of unit of work, the relevant call provided by the external unit-of-work coordinator must be used.

        If the MQBEGIN call is used to try to start the unit of work, the call fails with reason code RC2012.

      • To commit or back out this type of unit of work, the commit and back-out calls provided by the external unit-of-work coordinator must be used.

        If the MQCMIT or MQBACK call is used to try to commit or back out the unit of work, the call fails with reason code RC2012.

  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) on IBM i for further details.
  3. An application can participate in only one unit of work at a time. The MQBEGIN call fails with reason code RC2128 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 IBM MQ client environment. An attempt to use the call fails with reason code RC2012.
  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's configuration file.
  6. On IBM i, the three types of unit of work are supported as follows:

    • Queue manager-coordinated local units 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 units of work are not supported.
    • Externally-coordinated global units 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 IBM MQ resources as well as to resources belonging to other participating resource managers.


Parameters

The MQBEGIN call has the following parameters:

    HCONN (10-digit signed integer) - input

    Connection handle.

    This handle represents the connection to the queue manager. The value of HCONN was returned by a previous MQCONN or MQCONNX call.

    BEGOP (MQBO) - input/output

    Options that control the action of MQBEGIN.

    See MQBO (Begin options) on IBM i for details.

    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.

    CMPCOD (10-digit signed integer) - output

    Completion code.

    It is one of the following:

      CCOK
      Successful completion.

      CCWARN
      Warning (partial completion).

      CCFAIL
      Call failed.

    REASON (10-digit signed integer) - output

    Reason code qualifying CMPCOD.

    If CMPCOD is CCOK:

      RCNONE
      (0, X'000') No reason to report.

    If CMPCOD is CCWARN:

      RC2121
      (2121, X'849') No participating resource managers registered.

      RC2122
      (2122, X'84A') Participating resource manager not available.

    If CMPCOD is CCFAIL:

      RC2134
      (2134, X'856') Begin-options structure not valid.

      RC2219
      (2219, X'8AB') MQI call reentered before previous call complete.

      RC2009
      (2009, X'7D9') Connection to queue manager lost.

      RC2012
      (2012, X'7DC') Call not valid in environment.

      RC2018
      (2018, X'7E2') Connection handle not valid.

      RC2046
      (2046, X'7FE') Options not valid or not consistent.

      RC2162
      (2162, X'872') Queue manager shutting down.

      RC2102
      (2102, X'836') Insufficient system resources available.

      RC2071
      (2071, X'817') Insufficient storage available.

      RC2195
      (2195, X'893') Unexpected error occurred.

      RC2128
      (2128, X'850') Unit of work already started.


RPG Declaration

     C*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     C                     CALLP     MQBEGIN(HCONN : BEGOP : CMPCOD :
     C                                       REASON)
The prototype definition for the call is: 
     D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     DMQBEGIN          PR                  EXTPROC('MQBEGIN')
     D* Connection handle
     D HCONN                         10I 0 VALUE
     D* Options that control the action of MQBEGIN
     D BEGOP                         12A
     D* Completion code
     D CMPCOD                        10I 0
     D* Reason code qualifying CMPCOD
     D REASON                        10I 0
Parent topic: Function calls on IBM i