MQCMIT (Commit changes) on IBM i

The MQCMIT call indicates to the queue manager that the application has reached a syncpoint, and that all of the message gets and puts that have occurred since the last syncpoint are to be made permanent. Messages put as part of a unit of work are made available to other applications; messages retrieved as part of a unit of work are deleted.


Syntax

MQCMIT (HCONN, COMCOD, REASON)


Usage notes

Consider these usage notes when using MQCMIT.

  1. This call can be used only when the queue manager itself coordinates the unit of work. This is a local unit of work, where the changes affect only IBM MQ resources.
  2. In environments where the queue manager does not coordinate the unit of work, the appropriate commit call must be used instead of MQCMIT. The environment may also support an implicit commit caused by the application terminating normally.

    • On IBM i, this call can be used for local units of work coordinated by the queue manager. This means that a commitment definition must not exist at job level, that is, the STRCMTCTL command with the CMTSCOPE(*JOB) parameter must not have been issued for the job.

  3. If an 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.
  4. When an application puts or gets messages in groups or segments of logical messages, the queue manager retains information relating to the message group and logical message for the last successful MQPUT and MQGET calls. This information is associated with the queue handle, and includes such things as:

    • The values of the MDGID, MDSEQ, MDOFF, and MDMFL fields in MQMD.
    • Whether the message is part of a unit of work.
    • For the MQPUT call: whether the message is persistent or nonpersistent.

    When a unit of work is committed, the queue manager retains the group and segment information, and the application can continue putting or getting messages in the current message group or logical message.

    Retaining the group and segment information when a unit of work is committed allows the application to spread a large message group or large logical message consisting of many segments across several units of work. Using several units of work might be advantageous if the local queue manager has only limited queue storage. However, the application must maintain sufficient information to be able to restart putting or getting messages at the correct point if a system failure occurs. For details of how to restart at the correct point after a system failure, see the PMLOGO option described in MQPMO (Put-message options) on IBM i, and the GMLOGO option described in MQGMO (Get-message options) on IBM i.

The remaining usage notes apply only when the queue manager coordinates the units of work:

  1. A unit of work has the same scope as a connection handle. This means that all IBM MQ calls which affect a particular unit of work must be performed using the same connection handle. Calls issued using a different connection handle (for example, calls issued by another application) affect a different unit of work. See the HCONN parameter described in MQCONN for information about the scope of connection handles.
  2. Only messages that were put or retrieved as part of the current unit of work are affected by this call.
  3. A long-running application that issues MQGET, MQPUT, or MQPUT1 calls within a unit of work, but which never issues a commit or back-out call, can cause queues to fill up with messages that are not available to other applications. To guard against this possibility, the administrator should set the MaxUncommittedMsgs queue manager attribute to a value that is low enough to prevent runaway applications filling the queues, but high enough to allow the expected messaging applications to work correctly.


Parameters

The MQCMIT 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.

    COMCOD (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 COMCOD.

    If COMCOD is CCOK:

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

    If COMCOD is CCWARN:

      RC2003
      (2003, X'7D3') Unit of work backed out.

      RC2124
      (2124, X'84C') Result of commit operation is pending.

    If COMCOD is CCFAIL:

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

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

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

      RC2101
      (2101, X'835') Object damaged.

      RC2123
      (2123, X'84B') Result of commit or back-out operation is mixed.

      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.


RPG Declaration

     C*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     C                     CALLP     MQCMIT(HCONN : COMCOD : REASON)
The prototype definition for the call is: 
     D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     DMQCMIT           PR                  EXTPROC('MQCMIT')
     D* Connection handle
     D HCONN                         10I 0 VALUE
     D* Completion code
     D COMCOD                        10I 0
     D* Reason code qualifying COMCOD
     D REASON                        10I 0
Parent topic: Function calls on IBM i