MQCMD_INQUIRE_CONNECTION (Inquire Connection)

The Inquire connection (MQCMD_INQUIRE_CONNECTION) PCF 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, you cannot also specify an integer filter using the IntegerFilterCommand parameter, or a string filter using the StringFilterCommand parameter.

[z/OS]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. You 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.

You 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.
[UNIX, Linux, Windows, IBM i]MQBACF_CONN_TAG
[UNIX, Linux, Windows, IBM i]Connection tag.
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.

You 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.
[z/OS]MQIA_QSG_DISP
Disposition of the object (valid on z/OS only).

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

You 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. You 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, you 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, you 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.