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
- On IBM i, applications running in compatibility
mode do not need to issue this call. See MQCONN - Connect queue manager for more information. Important: If you are still using compatibility mode, consider recompiling your application and using static bound calls instead. See Compatibility mode for RPG applications on IBM i
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, and on IBM i for applications running in compatibility mode, you can omit the MQCONN call, and specify the following value forHconn
:- MQHC_DEF_HCONN
- Default connection handle.
On successful completion of the call, the queue manager setsHconn
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.
IfCompCode
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.
IfCompCode
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 Messages and reason codes.
Usage notes
- 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.
- If the application ends with uncommitted changes in a unit of work, the disposition of those changes depends on how the application ends:
- 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.
- 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.
- 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.
- If the application ends abnormally without issuing the MQDISC call, the unit of work is backed out.
- If the application issues the MQDISC call before ending:
- 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.
- On IBM i, applications running in compatibility mode do not have to issue this call; see the MQCONN call for more details.
C invocation
MQDISC (&Hconn, &CompCode, &Reason);
MQHCONN Hconn; /* Connection handle */
MQLONG CompCode; /* Completion code */
MQLONG Reason; /* Reason code qualifying CompCode */
COBOL invocation
CALL 'MQDISC' USING HCONN, COMPCODE, REASON.
** 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);
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)
HCONN DS F Connection handle
COMPCODE DS F Completion code
REASON DS F Reason code qualifying COMPCODE
Visual Basic invocation
MQDISC Hconn, CompCode, Reason
Dim Hconn As Long 'Connection handle'
Dim CompCode As Long 'Completion code'
Dim Reason As Long 'Reason code qualifying CompCode'