Inquire Queue Status

The Inquire Queue Status (MQCMD_INQUIRE_Q_STATUS) command inquires about the status of a local IBM MQ queue. You must specify the name of a local queue for which you want to receive status information.


Required parameters

    QName (MQCFST)
    Queue name (parameter identifier: MQCA_Q_NAME).

    Generic queue names are supported. A generic name is a character string followed by an asterisk (*), for example ABC*, and it selects all queues having names that start with the selected character string. An asterisk on its own matches all possible names.

    The queue name is always returned, regardless of the attributes requested.

    The maximum length of the string is MQ_Q_NAME_LENGTH.


Optional parameters (Inquire Queue Status)

    ByteStringFilterCommand (MQCFBF)
    Byte string filter command descriptor. The parameter identifier must be MQBACF_EXTERNAL_UOW_ID or MQBACF_Q_MGR_UOW_ID. Use this parameter to restrict the output from the command by specifying a filter condition. See MQCFBF - PCF byte string filter parameter for information about using this filter condition.

    If you specify a byte string filter, we cannot also specify an integer filter using the IntegerFilterCommand parameter, or a string filter using the StringFilterCommand parameter.

    CommandScope (MQCFST)
    Command scope (parameter identifier: MQCACF_COMMAND_SCOPE). This parameter applies to z/OS® only. Specifies how the command is initiated when the queue manager is a member of a queue-sharing group. We can specify one of the following:

    • Blank (or omit the parameter altogether). The command is initiated on the queue manager on which it was entered.
    • Queue manager name. The command is initiated on the queue manager you specify, providing it is active within the queue sharing group. If you specify a queue manager name other than the queue manager on which it was entered, you must be using a queue sharing group environment, and the command server must be initiated.
    • An asterisk (*). The command is initiated on the local queue manager and is also passed to every active queue manager in the queue sharing group.

    The maximum length is MQ_QSG_NAME_LENGTH.

    We cannot use CommandScope as a parameter to filter on.

    IntegerFilterCommand (MQCFIF)
    Integer filter command descriptor. The parameter identifier must be any integer type parameter allowed in QStatusAttrs except MQIACF_ALL, MQIACF_MONITORING, and MQIACF_Q_TIME_INDICATOR. Use this parameter to restrict the output from the command by specifying a filter condition. See MQCFIF - PCF integer filter parameter for information about using this filter condition.

    If you specify an integer filter, we cannot also specify a byte string filter using the ByteStringFilterCommand parameter or a string filter using the StringFilterCommand parameter.

    OpenType (MQCFIN)
    Queue status open type (parameter identifier: MQIACF_OPEN_TYPE).

    It is always returned, regardless of the queue instance attributes requested.

    The value can be:

      MQQSOT_ALL
      Selects status for queues that are open with any type of access.

      MQQSOT_INPUT
      Selects status for queues that are open for input.

      MQQSOT_OUTPUT
      Selects status for queues that are open for output.

    The default value if this parameter if not specified is MQQSOT_ALL.

    Filtering is not supported for this parameter.

    QSGDisposition (MQCFIN)
    QSG disposition (parameter identifier: MQIA_QSG_DISP). Specifies the disposition of the object (that is, where it is defined and how it behaves). This parameter is valid only on z/OS. The value can be any of the following values:

      MQQSGD_COPY
      The object is defined as MQQSGD_COPY.

      MQQSGD_Q_MGR
      The object is defined as MQQSGD_Q_MGR.

      MQQSGD_SHARED
      The object is defined as MQQSGD_SHARED.

    We cannot use QSGDisposition as a parameter to filter on.

    QStatusAttrs (MQCFIL)
    Queue status attributes (parameter identifier: MQIACF_Q_STATUS_ATTRS). The attribute list can specify the following value on its own - default value used if the parameter is not specified:

      MQIACF_ALL
      All attributes.

    or a combination of the following:

    Where StatusType is MQIACF_Q_STATUS:

      MQCA_Q_NAME
      Queue name.

      MQCACF_LAST_GET_DATE
      Date of the last message successfully destructively read from the queue.

      MQCACF_LAST_GET_TIME
      Time of the last message successfully destructively read from the queue.

      MQCACF_LAST_PUT_DATE
      Date of the last message successfully put to the queue.

      MQCACF_LAST_PUT_TIME
      Time of the last message successfully put to the queue.

      MQCACF_MEDIA_LOG_EXTENT_NAME
      Identity of the oldest log extent required to perform media recovery of the queue.

      On IBM i, this parameter identifies the name of the oldest journal receiver require to perform media recovery of the queue.

      MQIA_CURRENT_Q_DEPTH
      The current number of messages on the queue.

      MQIA_MONITORING_Q
      Current level of monitoring data collection.

      MQIA_OPEN_INPUT_COUNT
      The number of handles that are currently open for input for the queue. MQIA_OPEN_INPUT_COUNT does not include handles that are open for browse.

      MQIA_OPEN_OUTPUT_COUNT
      The number of handles that are currently open for output for the queue.

      MQIACF_HANDLE_STATE
      Whether an API call is in progress.

      MQIACF_MONITORING
      All the queue status monitoring attributes. These attributes are:

      • MQCACF_LAST_GET_DATE
      • MQCACF_LAST_GET_TIME
      • MQCACF_LAST_PUT_DATE
      • MQCACF_LAST_PUT_TIME
      • MQIA_MONITORING_Q
      • MQIACF_OLDEST_MSG_AGE
      • MQIACF_Q_TIME_INDICATOR
      Filtering is not supported for this parameter.

      MQIACF_OLDEST_MSG_AGE
      Age of oldest message on the queue.

      MQIACF_Q_TIME_INDICATOR
      Indicator of the time that messages remain on the queue.

      MQIACF_UNCOMMITTED_MSGS
      The number of uncommitted messages on the queue.

    Where StatusType is MQIACF_Q_HANDLE:

      MQBACF_EXTERNAL_UOW_ID
      Unit of recovery identifier assigned by the queue manager.

      MQBACF_Q_MGR_UOW_ID
      External unit of recovery identifier associated with the connection.

      MQCA_Q_NAME
      Queue name.

      MQCACF_APPL_TAG
      This parameter is a string containing the tag of the application connected to the queue manager.

      MQCACF_ASID
      Address-space identifier of the application identified by ApplTag. This parameter is valid on z/OS only.

      MQCACF_PSB_NAME
      Name of the program specification block (PSB) associated with the running IMS transaction. This parameter is valid on z/OS only.

      MQCACF_PSTID
      Identifier of the IMS program specification table (PST) for the connected IMS region. This parameter is valid on z/OS only.

      MQCACF_TASK_NUMBER
      CICS® task number. This parameter is valid on z/OS only.

      MQCACF_TRANSACTION_ID
      CICS transaction identifier. This parameter is valid on z/OS only.

      MQCACF_USER_IDENTIFIER
      The user name of the application that has opened the specified queue.

      MQCACH_CHANNEL_NAME
      The name of the channel that has the queue open, if any.

      MQCACH_CONNECTION_NAME
      The connection name of the channel that has the queue open, if any.

      MQIA_APPL_TYPE
      The type of application that has the queue open.

      MQIACF_OPEN_BROWSE
      Open browse.

      Filtering is not supported for this parameter.

      MQIACF_OPEN_INPUT_TYPE
      Open input type.

      Filtering is not supported for this parameter.

      MQIACF_OPEN_INQUIRE
      Open inquire.

      Filtering is not supported for this parameter.

      MQIACF_OPEN_OPTIONS
      The options used to open the queue. If this parameter is requested, the following parameter structures are also returned:

      • OpenBrowse
      • OpenInputType
      • OpenInquire
      • OpenOutput
      • OpenSet
      Filtering is not supported for this parameter.

      MQIACF_OPEN_OUTPUT
      Open output.

      Filtering is not supported for this parameter.

      MQIACF_OPEN_SET
      Open set.

      Filtering is not supported for this parameter.

      MQIACF_PROCESS_ID
      The process identifier of the application that has opened the specified queue.

      MQIACF_ASYNC_STATE

      MQIACF_THREAD_ID
      The thread identifier of the application that has opened the specified queue.

      MQIACF_UOW_TYPE
      Type of external unit of recovery identifier as seen by the queue manager.

    StatusType (MQCFIN)
    Queue status type (parameter identifier: MQIACF_Q_STATUS_TYPE).

    Specifies the type of status information required.

    The value can be any of the following values:

      MQIACF_Q_STATUS
      Selects status information relating to queues.

      MQIACF_Q_HANDLE
      Selects status information relating to the handles that are accessing the queues.

    The default value, if this parameter is not specified, is MQIACF_Q_STATUS.

    We cannot use StatusType as a parameter to filter on.

    StringFilterCommand (MQCFSF)
    String filter command descriptor. The parameter identifier must be any string type parameter allowed in QStatusAttrs except MQCA_Q_NAME. Use this parameter to restrict the output from the command by specifying a filter condition. See MQCFSF - PCF string filter parameter for information about using this filter condition.

    If you specify a string filter, we cannot also specify a byte string filter using the ByteStringFilterCommand parameter or an integer filter using the IntegerFilterCommand parameter.


Error codes

This command might return the following error code in the response format header Error codes applicable to all commands along with any additional pertinent values.

    Reason (MQLONG)
    The value can be any of the following values:

      MQRCCF_Q_TYPE_ERROR
      Queue type not valid.