MQSTAT - Retrieve status information

Use the MQSTAT call to retrieve status information. The type of status information returned is determined by the Type value specified on the call.

Syntax

MQSTAT (Hconn, Type, Stat, 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.

On z/OS® for CICS® applications, and on IBM® i for applications running in compatibility mode, the MQCONN call can be omitted, and the following value specified for Hconn :
MQHC_DEF_HCONN
Default connection handle.
[IBMi]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
Type
Type: MQLONG - input

Type of status information being requested. The > valid values are:

MQSTAT_TYPE_ASYNC_ERROR
Return information about previous asynchronous put operations.
MQSTAT_TYPE_RECONNECTION

Return information about reconnection. If the connection is reconnecting or failed to reconnect, the information describes the failure which caused the connection to begin reconnecting.

This value is only valid for client connections. For other types of connection, the call fails with reason code MQRC_ENVIRONMENT_ERROR

MQSTAT_TYPE_RECONNECTION_ERROR

Return information about a previous failure related to reconnect. If the connection failed to reconnect, the information describes the failure which caused reconnection to fail.

This value is only valid for client connections. For other types of connection, the call fails with reason code MQRC_ENVIRONMENT_ERROR.

Stat
Type: MQSTS - input/output

Status information structure. See MQSTS - Status reporting structure for details.

CompCode
Type: MQLONG - output
The completion code; it is one of the following:
MQCC_OK
Successful completion.
MQCC_FAILED
Call failed.
Reason
Type: MQLONG - output

The reason code qualifying CompCode.

If CompCode is MQCC_OK:
MQRC_NONE
(0, X'000') No reason to report.
If CompCode is MQCC_FAILED:
MQRC_API_EXIT_ERROR
(2374, X'946') API exit failed
MQRC_API_EXIT_LOAD_ERROR
(2183, X'887') Unable to load API exit.
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_FUNCTION_NOT_SUPPORTED
(2298, X'8FA') The function requested is not available in the current environment.
MQRC_HCONN_ERROR
(2018, X'7E2') Connection handle not valid.
MQRC_Q_MGR_STOPPING
(2162,X'872' - Queue manager stopping
MQRC_RESOURCE_PROBLEM
(2102, X'836') Insufficient system resources available.
MQRC_STAT_TYPE_ERROR
(2430, X'97E' Error with MQSTAT type
MQRC_STORAGE_NOT_AVAILABLE
(2071, X'817') Insufficient storage available.
MQRC_STS_ERROR
(2426, X'97A') Error with MQSTS structure
MQRC_UNEXPECTED_ERROR
(2195, X'893') Unexpected error occurred.

For detailed information about these codes, see Messages and reason codes.

Usage notes

  1. A call to MQSTAT specifying a type of MQSTAT_TYPE_ASYNC_ERROR returns information about previous asynchronous MQPUT and MQPUT1 operations. The MQSTS structure passed back on return from the MQSTAT call contains the first recorded asynchronous warning or error information for that connection. If further errors or warnings follow the first, they do not normally alter these values. However, if an error occurs with a completion code of MQCC_WARNING, a subsequent failure with a completion code of MQCC_FAILED is returned instead.
  2. If no errors have occurred since the connection was established or since the last call to MQSTAT then a CompCode of MQCC_OK and Reason of MQRC_NONE are returned in the MQSTS structure.
  3. Counts of the number of asynchronous calls that have been processed under the connection handle are returned by way of three counter fields; PutSuccessCount, PutWarningCount and PutFailureCount. These counters are incremented by the queue manager each time an asynchronous operation is processed successfully, has a warning, or fails (note that for accounting purposes a put to a distribution list counts once per destination queue rather than once per distribution list). A counter is not incremented beyond the maximum positive value AMQ_LONG_MAX.
  4. A successful call to MQSTAT results in any previous error information or counts being reset.
  5. The behavior of MQSTAT depends on the value of the MQSTAT Type parameter you provide.
  6. MQSTAT_TYPE_ASYNC_ERROR
    1. A call to MQSTAT specifying a type of MQSTAT_TYPE_ASYNC_ERROR returns information about previous asynchronous MQPUT and MQPUT1 operations. The MQSTS structure passed back on return from the MQSTAT call contains the first recorded asynchronous warning or error information for that connection. If further errors or warnings follow the first, they do not normally alter these values. However, if an error occurs with a completion code of MQCC_WARNING, a subsequent failure with a completion code of MQCC_FAILED is returned instead.
    2. If no errors have occurred since the connection was established or since the last call to MQSTAT then a CompCode of MQCC_OK and Reason of MQRC_NONE are returned in the MQSTS structure.
    3. Counts of the number of asynchronous calls that have been processed under the connection handle are returned by way of three counter fields; PutSuccessCount, PutWarningCount and PutFailureCount. These counters are incremented by the queue manager each time an asynchronous operation is processed successfully, has a warning, or fails (note that for accounting purposes a put to a distribution list counts once per destination queue rather than once per distribution list). A counter is not incremented beyond the maximum positive value AMQ_LONG_MAX.
    4. A successful call to MQSTAT results in any previous error information or counts being reset.
    MQSTAT_TYPE_RECONNECTION
    Suppose you call MQSTAT with Type set to MQSTAT_TYPE_RECONNECTION inside an event handler during reconnection. Consider these examples.
    The client is attempting reconnection or failed to reconnect.
    CompCode in the MQSTS structure is MQCC_FAILED and Reason might be either MQRC_CONNECTION_BROKEN or MQRC_Q_MGR_QUIESCING. ObjectType is MQOT_Q_MGR, ObjectName is the name of the queue manager, and ObjectQMgrName is blank.
    The client completed reconnection successfully or was never disconnected.
    CompCode in the MQSTS structure is MQCC_OK and the Reason is MQRC_NONE
    Subsequent calls to MQSTAT return the same results.
    MQSTAT_TYPE_RECONNECTION_ERROR
    Suppose you call MQSTAT with Type set to MQSTAT_TYPE_RECONNECTION_ERROR in response to receiving MQRC_RECONNECT_FAILED to an MQI call. Consider these examples.
    An authorization failure occurred when a queue was being reopened during reconnection to a different queue manager.
    CompCode in the MQSTS structure is MQCC_FAILED and Reason is the reason that the reconnection failed, such as MQRC_NOT_AUTHORIZED. ObjectType is the type of object that caused the problem, such as MQOT_QUEUE, ObjectName is the name of the queue and ObjectQMgrName the name of the queue manager owning the queue.
    A socket connection error occurred during reconnection.
    CompCode in the MQSTS structure is MQCC_FAILED and Reason is the reason that the reconnection failed, such as MQRC_HOST_NOT_AVAILABLE. ObjectType is MQOT_Q_MGR, ObjectName is the name of the queue manager, and ObjectQMgrName is blank.
    Subsequent calls to MQSTAT return the same results.

C invocation


MQSTAT (Hconn, StatType, &Stat, &CompCode, &Reason);
Declare the parameters as follows: 

MQHCONN Hconn;		/* Connection Handle */
MQLONG StatType;	/* Status type */
MQSTS Stat;	     	/* Status information structure */
MQLONG CompCode;	/* Completion code */
MQLONG Reason;		/* Reason code qualifying CompCode */

COBOL invocation


CALL 'MQSTAT' USING HCONN, STATTYPE, STAT, COMPCODE, REASON.
Declare the parameters as follows: 

**	Connection handle
 01	HCONN      PIC S9(9)      BINARY.
**	Status type
 01	STATTYPE   PIC S9(9)      BINARY.
**	Status information
 01	STAT.
	COPY CMQSTSV.
**	Completion code
 01	COMPCODE   PIC S9(9)      BINARY.
**	Reason code qualifying COMPCODE
 01	REASON     PIC S9(9)      BINARY.

PL/I invocation


call MQSTAT (Hconn, StatType, Stat, Compcode, Reason);
Declare the parameters as follows: 

dcl Hconn       fixed bin(31); /* Connection handle */
dcl StatType    fixed bin(31); /* Status type */
dcl Stat        like MQSTS;    /* Status information structure */
dcl CompCode    fixed bin(31); /* Completion code */
dcl Reason      fixed bin(31); /* Reason code qualifying CompCode */

System/390 Assembler invocation


CALL MQSTAT,(HCONN,STATTYPE,STAT,COMPCODE,REASON)
Declare the parameters as follows: 

HCONN     DS     F    Connection handle
STATTYPE  DS     F    Status type
STAT      CMQSTSA,    Status information structure
COMPCODE  DS     F    Completion code	
REASON    DS     F    Reason code qualifying COMPCODE