MQDISC - Disconnect queue manager

The MQDISC call breaks the connection between the queue manager and the application program, and is the inverse of the MQCONN or MQCONNX call.

  • On z/OS, all applications that use asynchronous message consumption, event handling or callback, the main control thread must issue an MQDISC call before ending. See Asynchronous consumption of IBM MQ messages for more details.
  • On z/OS, CICS applications do not need to issue this call to disconnect from the queue manager. If a CICS application does make this call it has no effect unless an earlier MQCONNX call was made, specifying one of the:

    • MQCNO_SERIALIZE_CONN_TAG_Q_MGR
    • MQCNO_SERIALIZE_CONN_TAG_QSG
    • MQCNO_RESTRICT_CONN_TAG_Q_MGR or
    • MQCNO_RESTRICT_CONN_TAG_QSG

    options, in which case all currently open object handles are closed.


Syntax

MQDISC (Hconn, CompCode, Reason)


Parameters

    Hconn
    Type: MQHCONN - input/output

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

    On z/OS for CICS applications we can omit the MQCONN call, and specify the following value for Hconn :

      MQHC_DEF_HCONN
      Default connection handle.

    On successful completion of the call, the queue manager sets Hconn to a value that is not a valid handle for the environment. This value is:

      MQHC_UNUSABLE_HCONN
      Unusable connection handle.

    On z/OS, Hconn is set to a value that is undefined.

    CompCode
    Type: MQLONG - output The completion code; it is one of the following codes:

      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_BACKED_OUT
      (2003, X'7D3') Unit of work backed out.

      MQRC_CONN_TAG_NOT_RELEASED
      (2344, X'928') Connection tag not released.

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

    If CompCode is MQCC_FAILED:

      MQRC_ADAPTER_DISC_LOAD_ERROR
      (2138, X'85A') Unable to load adapter disconnection module.

      MQRC_ADAPTER_NOT_AVAILABLE
      (2204, X'89C') Adapter not available.

      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_API_EXIT_INIT_ERROR
      (2375, X'947') API exit initialization failed.

      MQRC_API_EXIT_TERM_ERROR
      (2376, X'948') API exit termination 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_CONNECTION_BROKEN
      (2009, X'7D9') Connection to queue manager lost.

      MQRC_CONNECTION_STOPPING
      (2203, X'89B') Connection shutting down.

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

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

      MQRC_PAGESET_ERROR
      (2193, X'891') Error accessing page-set data set.

      MQRC_Q_MGR_NAME_ERROR
      (2058, X'80A') Queue manager name not valid or not known.

      MQRC_Q_MGR_NOT_AVAILABLE
      (2059, X'80B') Queue manager not available for connection.

      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.

    For detailed information about these codes, see Reason codes.


Usage notes

  1. If an MQDISC call is issued when the connection still has objects open under that connection, the queue manager closes those objects, with the close options set to MQCO_NONE.
  2. If the application ends with uncommitted changes in a unit of work, the disposition of those changes depends on how the application ends:
    1. If the application issues the MQDISC call before ending:

      • For a queue manager-coordinated unit of work, the queue manager issues the MQCMIT call on behalf of the application. The unit of work is committed if possible, and backed out if not.

      • For an externally coordinated unit of work, there is no change in the status of the unit of work; however, the queue manager typically indicates that the unit of work must be committed when asked by the unit-of-work coordinator.

        On z/OS, CICS, IMS (other than batch DL/1 programs), and RRS applications are like this.

    2. If the application ends normally but without issuing the MQDISC call, the action taken depends on the environment:

      • On z/OS, except for MQ Java or MQ JMS applications, the actions described in note 2a occur.
      • In all other cases, the actions described in note 2c occur.

      Because of the differences between environments, ensure that applications that we want to port either commit or back out the unit of work before they end.

    3. If the application ends abnormally without issuing the MQDISC call, the unit of work is backed out.

  3. On z/OS, the following points apply:

    • CICS applications do not have to issue the MQDISC call to disconnect from the queue manager, because the CICS system itself connects to the queue manager, and the MQDISC call has no effect on this connection.
    • CICS, IMS (other than batch DL/1 programs), and RRS applications use units of work that are coordinated by an external unit-of-work coordinator. As a result, the MQDISC call does not affect the status of the unit of work (if any) that exists when the call is issued.

      However the MQDISC call does indicate the end of use of the connection tag ConnTag that was associated with the connection by an earlier MQCONNX call issued by the application. If there is an active unit of work that references the connection tag when the MQDISC call is issued, the call completes with completion code MQCC_WARNING and reason code MQRC_CONN_TAG_NOT_RELEASED. The connection tag does not become available for reuse until the external unit-of-work coordinator has resolved the unit of work.

Note: In CICS, MQOP_START is not supported. Instead, use the MQOP_START_WAIT function call.


C invocation

MQDISC (&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 'MQDISC' 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 MQDISC (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 */


System/390 assembler invocation

CALL MQDISC,(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

MQDISC 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'
Parent topic: Function calls