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 the MQCONN call can be omitted, and the following value specified for Hconn :

      MQHC_DEF_HCONN
      Default connection handle.

    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 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