Inquire Connection

The Inquire connection (MQCMD_INQUIRE_CONNECTION) command inquires about the applications which are connected to the queue manager, the status of any transactions that those applications are running, and the objects which the application has open.


Required parameters

    ConnectionId (MQCFBS)
    Connection identifier (parameter identifier: MQBACF_CONNECTION_ID).

    This parameter is the unique connection identifier associated with an application that is connected to the queue manager. Specify either this parameter or GenericConnectionId.

    All connections are assigned a unique identifier by the queue manager regardless of how the connection is established.

    If you need to specify a generic connection identifier, use the GenericConnectionId parameter instead.

    The length of the string is MQ_CONNECTION_ID_LENGTH.

    GenericConnectionId (MQCFBS)
    Generic specification of a connection identifier (parameter identifier: MQBACF_GENERIC_CONNECTION_ID).

    Specify either this parameter or ConnectionId.

    If you specify a byte string of zero length, or one which contains only null bytes, information about all connection identifiers is returned. This value is the only value permitted for GenericConnectionId.

    The length of the string is MQ_CONNECTION_ID_LENGTH.


Optional parameters

    ByteStringFilterCommand (MQCFBF)
    Byte string filter command descriptor. The parameter identifier must be MQBACF_EXTERNAL_UOW_ID, MQBACF_ORIGIN_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 executed 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 executed on the queue manager on which it was entered.
    • a queue manager name. The command is executed 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 enabled.
    • an asterisk (*). The command is executed on the local queue manager and is also passed to every active queue manager in the queue sharing group.

    The maximum length is MQ_Q_MGR_NAME_LENGTH.

    We cannot use CommandScope as a parameter to filter on.

    ConnectionAttrs (MQCFIL)
    Connection attributes (parameter identifier: MQIACF_CONNECTION_ATTRS). The attribute list can specify the following value on its own - default value if the parameter is not specified:

      MQIACF_ALL
      All attributes of the selected ConnInfoType.

    or, if you select a value of MQIACF_CONN_INFO_CONN for ConnInfoType, a combination of the following:

      MQBACF_CONNECTION_ID
      Connection identifier.

      MQBACF_EXTERNAL_UOW_ID
      External unit of recovery identifier associated with the connection.

      MQBACF_ORIGIN_UOW_ID
      Unit of recovery identifier assigned by the originator (valid on z/OS only).

      MQBACF_Q_MGR_UOW_ID
      Unit of recovery identifier assigned by the queue manager.

      MQCACF_APPL_TAG
      Name of an application that is connected to the queue manager.

      MQCACF_ASID
      The 4-character address-space identifier of the application identified in MQCACF_APPL_TAG (valid on z/OS only).

      MQCACF_ORIGIN_NAME
      Originator of the unit of recovery (valid on z/OS only).

      MQCACF_PSB_NAME
      The 8-character name of the program specification block (PSB) associated with the running IMS transaction (valid on z/OS only).

      MQCACF_PST_ID
      The 4-character IMS program specification table (PST) region identifier for the connected IMS region (valid on z/OS only).

      MQCACF_TASK_NUMBER
      A 7-digit CICS® task number (valid on z/OS only).

      MQCACF_TRANSACTION_ID
      A 4-character CICS transaction identifier (valid on z/OS only).

      MQCACF_UOW_LOG_EXTENT_NAME
      Name of the first extent required to recover the transaction. MQCACF_UOW_LOG_EXTENT_NAME is not valid on z/OS.

      MQCACF_UOW_LOG_START_DATE
      Date on which the transaction associated with the current connection first wrote to the log.

      MQCACF_UOW_LOG_START_TIME
      Time at which the transaction associated with the current connection first wrote to the log.

      MQCACF_UOW_START_DATE
      Date on which the transaction associated with the current connection was started.

      MQCACF_UOW_START_TIME
      Time at which the transaction associated with the current connection was started.

      MQCACF_USER_IDENTIFIER
      User identifier of the application that is connected to the queue manager.

      MQCACH_CHANNEL_NAME
      Name of the channel associated with the connected application.

      MQCACH_CONNECTION_NAME
      Connection name of the channel associated with the application.

      MQIA_APPL_TYPE
      Type of the application that is connected to the queue manager.

      MQIACF_CONNECT_OPTIONS
      Connect options currently in force for this application connection.

      We cannot use the value MQCNO_STANDARD_BINDING as a filter value.

      MQIACF_PROCESS_ID
      Process identifier of the application that is currently connected to the queue manager.

      This parameter is not valid on z/OS.

      MQIACF_THREAD_ID
      Thread identifier of the application that is currently connected to the queue manager.

      This parameter is not valid on z/OS.

      MQIACF_UOW_STATE
      State of the unit of work.

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

    or, if you select a value of MQIACF_CONN_INFO_HANDLE for ConnInfoType, a combination of the following:

      MQCACF_OBJECT_NAME
      Name of each object that the connection has open.

      MQCACH_CONNECTION_NAME
      Connection name of the channel associated with the application.

      MQIA_QSG_DISP
      Disposition of the object (valid on z/OS only).

      We cannot use MQIA_QSG_DISP as a parameter to filter on.

      MQIA_READ_AHEAD
      The read ahead connection status.

      MQIA_UR_DISP
      The unit of recovery disposition associated with the connection (valid on z/OS only).

      MQIACF_HANDLE_STATE
      Whether an API call is in progress.

      MQIACF_OBJECT_TYPE
      Type of each object that the connection has open.

      MQIACF_OPEN_OPTIONS
      Options used by the connection to open each object.

    or, if you select a value of MQIACF_CONN_INFO_ALL for ConnInfoType, any of the previous values.

    ConnInfoType (MQCFIN)
    Type of connection information to be returned (parameter identifier: MQIACF_CONN_INFO_TYPE). The value can be any of the following values:

      MQIACF_CONN_INFO_CONN
      Connection information. On z/OS, MQIACF_CONN_INFO_CONN includes threads which might be logically or actually disassociated from a connection, together with those threads that are in-doubt and for which external intervention is needed to resolve them. MQIACF_CONN_INFO_CONN is the default value used if the parameter is not specified.

      MQIACF_CONN_INFO_HANDLE
      Information pertaining only to those objects opened by the specified connection.

      MQIACF_CONN_INFO_ALL
      Connection information and information about those objects that the connection has open.

    We cannot use ConnInfoType as a parameter to filter on.

    IntegerFilterCommand (MQCFIF)
    Integer filter command descriptor. The parameter identifier must be any integer type parameter allowed in ConnectionAttrs except as noted and MQIACF_ALL. Use this parameter to restrict the output from the command by specifying a filter condition. We cannot use the value MQCNO_STANDARD_BINDING on the MQIACF_CONNECT_OPTIONS parameter with either the MQCFOP_CONTAINS or MQCFOP_EXCLUDES operator. See MQCFIF - PCF integer filter parameter for information about using this filter condition.

    If you filter on MQIACF_CONNECT_OPTIONS or MQIACF_OPEN_OPTIONS, in each case the filter value must have only 1 bit set.

    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.

    StringFilterCommand (MQCFSF)
    String filter command descriptor. The parameter identifier must be any string type parameter allowed in ConnectionAttrs. 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.

    URDisposition (MQCFIN)
    The unit of recovery disposition associated with the connection (parameter identifier: MQI_UR_DISP). This parameter is valid only on z/OS. The value can be any of the following values:

      MQQSGD_ALL
      Specifies that all connections must be returned.

      MQQSGD_GROUP
      Specifies that only connections with a GROUP unit of recovery disposition must be returned.

      MQQSGD_Q_MGR
      Specifies that only connections with a QMGR unit of recovery disposition must be returned.


Error code

This command might return the following error code in the response format header, in addition to the values shown in Error codes applicable to all commands.

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

      MQRCCF_CONNECTION_ID_ERROR
      Connection identifier not valid.