MQCMIT - Commit changes

The MQCMIT call indicates to the queue manager that the application has reached a sync point, and that all the message gets and puts that have occurred since the last sync point 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.

  • On z/OS®, the call is used only by batch programs (including IMS batch DL/I programs).


Syntax

MQCMIT (Hconn, 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.

    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

    The reason codes listed are the ones that the queue manager can return for the Reason parameter.

    If CompCode is MQCC_OK:

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

    If CompCode is MQCC_WARNING:

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

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

    If CompCode is MQCC_FAILED:

      MQRC_ADAPTER_SERV_LOAD_ERROR
      (2130, X'852') Unable to load adapter service module.

      MQRC_API_EXIT_ERROR
      (2374, X'946') API exit failed.

      MQRC_ASID_MISMATCH
      (2157, X'86D') Primary and home ASIDs differ.

      MQRC_CALL_IN_PROGRESS
      (2219, X'8AB') MQI call entered before previous call complete.

      MQRC_CALL_INTERRUPTED
      (2549, X'9F5') MQPUT or MQCMIT was interrupted and reconnection processing cannot reestablish a definite outcome.

      MQRC_CF_STRUC_IN_USE
      (2346, X'92A') Coupling-facility structure in use.

      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_OBJECT_DAMAGED
      (2101, X'835') Object damaged.

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

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

      MQRC_RECONNECT_FAILED
      (2548, X'9F4') After reconnecting, an error occurred reinstating the handles for a reconnectable connection.

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

      MQRC_STORAGE_MEDIUM_FULL
      (2192, X'890') External storage medium is full.

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

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

    For detailed information about these codes, see Reason codes.


Usage notes

  1. Use this call only when the queue manager itself coordinates the unit of work. This can be:

    • A local unit of work, where the changes affect only IBM MQ resources.
    • A global unit of work, where the changes can affect resources belonging to other resource managers, as well as affecting IBM MQ resources.
    For further details about local and global units of work, see MQBEGIN - Begin unit of work.
  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 might also support an implicit commit caused by the application terminating normally.

    • On z/OS, use the following calls:

      • Batch programs (including IMS batch DL/I programs) can use the MQCMIT call if the unit of work affects only IBM MQ resources. However, if the unit of work affects both IBM MQ resources and resources belonging to other resource managers (for example, Db2® ), use the SRRCMIT call provided by the z/OS Recoverable Resource Service (RRS). The SRRCMIT call commits changes to resources belonging to the resource managers that have been enabled for RRS coordination.
      • CICS® applications must use the EXEC CICS SYNCPOINT command to commit the unit of work explicitly. Alternatively, ending the transaction results in an implicit commit of the unit of work. The MQCMIT call cannot be used for CICS applications.
      • IMS applications (other than batch DL/I programs) must use IMS calls such as GU and CHKP to commit the unit of work. The MQCMIT call cannot be used for IMS applications (other than batch DL/I programs).
    • On IBM i, use this call 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 MQDISC usage notes 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 GroupId, MsgSeqNumber, Offset, and MsgFlags 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 is advantageous if the local queue manager has only limited queue storage. However, the application must maintain sufficient information 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 MQPMO_LOGICAL_ORDER and MQGMO_LOGICAL_ORDER.

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

  5. A unit of work has the same scope as a connection handle; all IBM MQ calls that 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.
  6. Only messages that were put or retrieved as part of the current unit of work are affected by this call.
  7. A long-running application that issues MQGET, MQPUT, or MQPUT1 calls within a unit of work, but that never issues a commit or back-out call, can fill queues with messages that are not available to other applications. To guard against this, the administrator must 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.
  8. On UNIX and Windows systems, if the Reason parameter is MQRC_CONNECTION_BROKEN (with a CompCode of MQCC_FAILED), or MQRC_UNEXPECTED_ERROR it is possible that the unit of work was successfully committed.


C invocation

MQCMIT (Hconn, &CompCode, &Reason);
Declare the parameters as follows: 
MQHCONN  Hconn;     /* Connection handle */
MQLONG   CompCode;  /* Completion code */
MQLONG   Reason;    /* Reason code qualifying CompCode */


COBOL invocation

CALL 'MQCMIT' USING HCONN, COMPCODE, REASON.
Declare the parameters as follows: 
**   Connection handle
 01  HCONN     PIC S9(9) BINARY.
**   Completion code
 01  COMPCODE  PIC S9(9) BINARY.
**   Reason code qualifying COMPCODE
 01  REASON    PIC S9(9) BINARY.


PL/I invocation

call MQCMIT (Hconn, CompCode, Reason);
Declare the parameters as follows: 
dcl Hconn     fixed bin(31);  /* Connection handle */
dcl CompCode  fixed bin(31);  /* Completion code */
dcl Reason    fixed bin(31);  /* Reason code qualifying CompCode */


High Level Assembler invocation

CALL MQCMIT,(HCONN,COMPCODE,REASON)
Declare the parameters as follows: 
HCONN     DS  F  Connection handle
COMPCODE  DS  F  Completion code
REASON    DS  F  Reason code qualifying COMPCODE


Visual Basic invocation

MQCMIT Hconn, CompCode, Reason
Declare the parameters as follows: 
Dim Hconn    As Long 'Connection handle'
Dim CompCode As Long 'Completion code'
Dim Reason   As Long 'Reason code qualifying CompCode'