MQCMD_INQUIRE_CHANNEL_STATUS (Inquire Channel Status)

The Inquire Channel Status (MQCMD_INQUIRE_CHANNEL_STATUS) PCF command inquires about the status of one or more channel instances.

You must specify the name of the channel for which you want to inquire status information. This name can be a specific channel name or a generic channel name. By using a generic channel name, you can inquire either:

Status information for all channels, or
Status information for one or more channels that match the specified name.

You must also specify whether you want:

The status data (of current channels only), or
The saved status data of all channels, or
On z/OS® only, the short status data of the channel.
Status for all channels that meet the selection criteria is returned, whether the channels were defined manually or automatically.

Selection

The way to make a selection, is to use one of the following four options:

XmitQname (MQCACH_XMIT_Q_NAME)
ConnectionName (MQCACH_CONNECTION_NAME)
ChannelDisposition (MQIACH_CHANNEL_DISP)
ChannelInstanceType (MQIACH_CHANNEL_INSTANCE_TYPE)

[UNIX, Linux, Windows, IBM i] This command includes a check on the current depth of the transmission queue for the channel, if the channel is a CLUSSDR channel. To issue this command, you must be authorized to inquire the queue depth, and to do this requires +inq authority on the transmission queue. Note that another name for this authority is MQZAO_INQUIRE.

[UNIX, Linux, Windows, IBM i] Without this authority this command runs without error, but a value of zero is output for the MsgsAvailable parameter of the MQCMD_INQUIRE_CHANNEL_STATUS (Inquire Channel Status) Response command. If you have the correct authority, the command provides the correct value for MsgsAvailable.

There are three classes of data available for channel status. These classes are saved, current, and short. The status fields available for saved data are a subset of the fields available for current data and are called common status fields. Although the common data fields are the same, the data values might be different for saved and current status. The rest of the fields available for current data are called current-only status fields.

Saved data consists of the common status fields. This data is reset at the following times:
- For all channels:
  - When the channel enters or leaves STOPPED or RETRY state
- For a sending channel:
  - Before requesting confirmation that a batch of messages has been received
  - When confirmation has been received
- For a receiving channel:
  - Just before confirming that a batch of messages has been received
- For a server connection channel:
  - No data is saved
Therefore, a channel which has never been current does not have any saved status.
Current data consists of the common status fields and current-only status fields. The data fields are continually updated as messages are sent or received.
Short data consists of the queue manager name that owns the channel instance. This class of data is available only on z/OS.

This method of operation has the following consequences:

An inactive channel might not have any saved status if it has never been current or has not yet reached a point where saved status is reset.
The common data fields might have different values for saved and current status.
A current channel always has current status and might have saved status.

Channels can be current or inactive:

Current channels: These are channels that have been started, or on which a client has connected, and that have not finished or disconnected normally. They might not yet have reached the point of transferring messages, or data, or even of establishing contact with the partner. Current channels have current status and can also have saved or short status.
The term Active is used to describe the set of current channels which are not stopped.
Inactive channels: These are channels that have either not been started or on which a client has not connected, or that have finished or disconnected normally. (If a channel is stopped, it is not yet considered to have finished normally and is, therefore, still current.) Inactive channels have either saved status or no status at all.

There can be more than one instance of a receiver, requester, cluster-sender, cluster-receiver, or server-connection channel current at the same time (the requester is acting as a receiver). This situation occurs if several senders, at different queue managers, each initiate a session with this receiver, using the same channel name. For channels of other types, there can only be one instance current at any time.

For all channel types, however, there can be more than one set of saved status information available for a particular channel name. At most one of these sets relates to a current instance of the channel, the rest relate to previously current instances. Multiple instances arise if different transmission queue names or connection names have been used with the same channel. This situation can happen in the following cases:

At a sender or server:
- If the same channel has been connected to by different requesters (servers only),
- If the transmission queue name has been changed in the definition, or
- If the connection name has been changed in the definition.
At a receiver or requester:
- If the same channel has been connected to by different senders or servers, or
- If the connection name has been changed in the definition (for requester channels initiating connection).

The number of sets returned for a particular channel can be limited by using the XmitQName, ConnectionName and ChannelInstanceType parameters.

Required parameters

ChannelName (MQCFST)

Channel name (parameter identifier: MQCACH_CHANNEL_NAME).

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

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

The maximum length of the string is MQ_CHANNEL_NAME_LENGTH.

Optional parameters

ChannelDisposition (MQCFIN)

Channel disposition (parameter identifier: MQIACH_CHANNEL_DISP). This parameter applies to z/OS only.

Specifies the disposition of the channels for which information is to be returned. The value can be any of the following values:

MQCHLD_ALL: Returns requested status information for private channels.
In a shared queue environment where the command is being executed on the queue manager where it was issued, or if ChannelInstanceType has a value of MQOT_CURRENT_CHANNEL, this option also displays the requested status information for shared channels.
MQCHLD_PRIVATE: Returns requested status information for private channels.
MQCHLD_SHARED: Returns requested status information for shared channels.

The status information that is returned for various combinations of


ChannelDisposition


CommandScope

, and status type, is summarized in Table 1, Table 2, and Table 3.

Table 1. ChannelDisposition and CommandScope for Inquire Channel Status, Current
`ChannelDisposition`	`CommandScope` blank or local queue manager	`CommandScope(qmgr-name)`	`CommandScope(*)`
MQCHLD_PRIVATE	Common and current-only status for current private channels on the local queue manager	Common and current-only status for current private channels on the named queue manager	Common and current-only status for current private channels on all queue managers
MQCHLD_SHARED	Common and current-only status for current shared channels on the local queue manager	Common and current-only status for current shared channels on the named queue manager	Common and current-only status for current shared channels on all queue managers
MQCHLD_ALL	Common and current-only status for current private and shared channels on the local queue manager	Common and current-only status for current private and shared channels on the named queue manager	Common and current-only status for current private and shared channels on all active queue managers

Table 2. ChannelDisposition and CommandScope for Inquire Channel Status, Short
`ChannelDisposition`	`CommandScope` blank or local queue manager	`CommandScope(qmgr-name)`	`CommandScope(*)`
MQCHLD_PRIVATE	`ChannelStatus` and short status for current private channels on the local queue manager	`ChannelStatus` and short status for current private channels on the named queue manager	`ChannelStatus` and short status for current private channels on all active queue managers
MQCHLD_SHARED	`ChannelStatus` and short status for current shared channels on all active queue managers in the queue sharing group	Not permitted	Not permitted
MQCHLD_ALL	`ChannelStatus` and short status for current private channels on the local queue manager and current shared channels in the queue sharing group( 1 )	`ChannelStatus` and short status for current private channels on the named queue manager	`ChannelStatus` and short status for current private, and shared, channels on all active queue managers in the queue sharing group( 1 )

Note:

In this case you get two separate sets of responses to the command on the queue manager where it was entered; one for MQCHLD_PRIVATE and one for MQCHLD_SHARED.

Table 3. ChannelDisposition and CommandScope for Inquire Channel Status, Saved
`ChannelDisposition`	`CommandScope` blank or local queue manager	`CommandScope(qmgr-name)`	`CommandScope(*)`
MQCHLD_PRIVATE	Common status for saved private channels on the local queue manager	Common status for saved private channels on the named queue manager	Common status for saved private channels on all active queue managers
MQCHLD_SHARED	Common status for saved shared channels on all active queue managers in the queue sharing group	Not permitted	Not permitted
MQCHLD_ALL	Common status for saved private channels on the local queue manager and saved shared channels in the queue sharing group	Common status for saved private channels on the named queue manager	Common status for saved private, and shared, channels on all active queue managers in the queue sharing group

You cannot use this parameter as a filter keyword.

ChannelInstanceAttrs (MQCFIL)

Channel instance attributes (parameter identifier: MQIACH_CHANNEL_INSTANCE_ATTRS).

The ChannelInstanceAttrs parameter names the list of attributes to be returned. This parameter does not provide any way to select, based upon the value of the items in that list of attributes.

If status information is requested which is not relevant for the particular channel type, it is not an error. Similarly, it is not an error to request status information that is applicable only to active channels for saved channel instances. In both of these cases, no structure is returned in the response for the information concerned.

For a saved channel instance, the MQCACH_CURRENT_LUWID, MQIACH_CURRENT_MSGS, and MQIACH_CURRENT_SEQ_NUMBER attributes have meaningful information only if the channel instance is in doubt. However, the attribute values are still returned when requested, even if the channel instance is not in-doubt.

The attribute list might specify the following value on its own:

MQIACF_ALL: All attributes.

MQIACF_ALL is the default value used if the parameter is not specified or it can specify a combination of the following:

Relevant for common status:
The following information applies to all sets of channel status, whether the set is current.

MQCACH_CHANNEL_NAME

Channel name.

MQCACH_CONNECTION_NAME

Connection name.

MQCACH_CURRENT_LUWID

Logical unit of work identifier for current batch.

MQCACH_LAST_LUWID

Logical unit of work identifier for last committed batch.

MQCACH_XMIT_Q_NAME

Transmission queue name.

MQIACH_CHANNEL_INSTANCE_TYPE

Channel instance type.

MQIACH_CHANNEL_TYPE

Channel type.

MQIACH_CURRENT_MSGS

Number of messages sent or received in current batch.

MQIACH_CURRENT_SEQ_NUMBER

Sequence number of last message sent or received.

MQIACH_INDOUBT_STATUS

Whether the channel is currently in-doubt.

MQIACH_LAST_SEQ_NUMBER

Sequence number of last message in last committed batch.

MQCACH_CURRENT_LUWID, MQCACH_LAST_LUWID, MQIACH_CURRENT_MSGS, MQIACH_CURRENT_SEQ_NUMBER, MQIACH_INDOUBT_STATUS and MQIACH_LAST_SEQ_NUMBER do not apply to server-connection channels, and no values are returned. If specified on the command, they are ignored.
Relevant for current-only status:
The following information applies only to current channel instances. The information applies to all channel types, except where stated.

MQCA_Q_MGR_NAME

Name of the queue manager that owns the channel instance. This parameter is valid only on z/OS.

MQCA_REMOTE_Q_MGR_NAME

Queue manager name, or queue sharing group name of the remote system. The remote queue manager name is always returned regardless of the instance attributes requested.

MQCACH_CHANNEL_START_DATE

Date channel was started.

MQCACH_CHANNEL_START_TIME

Time channel was started.

MQCACH_LAST_MSG_DATE

Date last message was sent, or MQI call was handled.

MQCACH_LAST_MSG_TIME

Time last message was sent, or MQI call was handled.

MQCACH_LOCAL_ADDRESS

Local communications address for the channel.

MQCACH_MCA_JOB_NAME

Name of MCA job.
This parameter is not valid on z/OS.

You cannot use MQCACH_MCA_JOB_NAME as a parameter to filter on.

MQCACH_MCA_USER_ID

The user ID used by the MCA.

MQCACH_REMOTE_APPL_TAG

Remote partner application name. MQCACH_REMOTE_APPL_TAG is the name of the client application at the remote end of the channel. This parameter applies only to server-connection channels.

MQCACH_REMOTE_PRODUCT

Remote partner product identifier. This is the product identifier of the IBM® MQ code running at the remote end of the channel.

MQCACH_REMOTE_VERSION

Remote partner version. This is the version of the IBM MQ code running at the remote end of the channel.

MQCACH_SSL_CIPHER_SPEC

CipherSpec in use on the connection.

MQCACH_SSL_SHORT_PEER_NAME

TLS short peer name.

MQCACH_SSL_CERT_ISSUER_NAME

The full Distinguished Name of the issuer of the remote certificate.

MQCACH_SSL_CERT_USER_ID

User ID associated with the remote certificate; valid on z/OS only.

MQCACH_TOPIC_ROOT

Topic root for AMQP channel.

MQIA_MONITORING_CHANNEL

The level of monitoring data collection.

MQIA_STATISTICS_CHANNEL

The level of statistics data collection; valid on z/OS only.

MQIACF_MONITORING

All channel status monitoring attributes. These attributes are:

MQIA_MONITORING_CHANNEL

The level of monitoring data collection.

MQIACH_BATCH_SIZE_INDICATOR

Batch size.

MQIACH_COMPRESSION_RATE

The compression rate achieved displayed to the nearest percentage.

MQIACH_COMPRESSION_TIME

The amount of time per message, displayed in microseconds, spent during compression or decompression.

MQIACH_EXIT_TIME_INDICATOR

Exit time.

MQIACH_NETWORK_TIME_INDICATOR

Network time.

MQIACH_XMITQ_MSGS_AVAILABLE

Number of messages available to the channel on the transmission queue.

MQIACH_XMITQ_TIME_INDICATOR

Time on transmission queue.

You cannot use MQIACF_MONITORING as a parameter to filter on.

MQIACH_BATCH_SIZE_INDICATOR

Batch size.
You cannot use MQIACH_BATCH_SIZE_INDICATOR as a parameter to filter on.

MQIACH_BATCHES

Number of completed batches.

MQIACH_BUFFERS_RCVD

Number of buffers received.

MQIACH_BUFFERS_SENT

Number of buffers sent.

MQIACH_BYTES_RCVD

Number of bytes received.

MQIACH_BYTES_SENT

Number of bytes sent.

MQIACH_CHANNEL_SUBSTATE

The channel substate.

MQIACH_COMPRESSION_RATE

The compression rate achieved displayed to the nearest percentage.
You cannot use MQIACH_COMPRESSION_RATE as a parameter to filter on.

MQIACH_COMPRESSION_TIME

The amount of time per message, displayed in microseconds, spent during compression or decompression.
You cannot use MQIACH_COMPRESSION_TIME as a parameter to filter on.

MQIACH_CURRENT_SHARING_CONVS

Requests information about the current number of conversations on this channel instance.
This attribute applies only to TCP/IP server-connection channels.

MQIACH_EXIT_TIME_INDICATOR

Exit time.
You cannot use MQIACH_EXIT_TIME_INDICATOR as a parameter to filter on.

MQIACH_HDR_COMPRESSION

Technique used to compress the header data sent by the channel.

MQIACH_KEEP_ALIVE_INTERVAL

The KeepAlive interval in use for this session. This parameter is significant only for z/OS.

MQIACH_LONG_RETRIES_LEFT

Number of long retry attempts remaining.

MQIACH_MAX_MSG_LENGTH

Maximum message length. MQIACH_MAX_MSG_LENGTH is valid only on z/OS.

MQIACH_MAX_SHARING_CONVS

Requests information about the maximum number of conversations on this channel instance.
This attribute applies only to TCP/IP server-connection channels.

MQIACH_MCA_STATUS

MCA status.
You cannot use MQIACH_MCA_STATUS as a parameter to filter on.

MQIACH_MSG_COMPRESSION

Technique used to compress the message data sent by the channel.

MQIACH_MSGS

Number of messages sent or received, or number of MQI calls handled.

MQIACH_NETWORK_TIME_INDICATOR

Network time.
You cannot use MQIACH_NETWORK_TIME_INDICATOR as a parameter on which to filter.

MQIACH_SECURITY_PROTOCOL

Security protocol currently in use.
This parameter does not apply to client-connection channels.

From IBM MQ 9.1.1, this parameter is supported on z/OS.

MQIACH_SHORT_RETRIES_LEFT

Number of short retry attempts remaining.

MQIACH_SSL_KEY_RESETS

Number of successful TLS key resets.

MQIACH_SSL_RESET_DATE

Date of previous successful TLS secret key reset.

MQIACH_SSL_RESET_TIME

Time of previous successful TLS secret key reset.

MQIACH_STOP_REQUESTED

Whether user stop request has been received.

MQIACH_XMITQ_MSGS_AVAILABLE

Number of messages available to the channel on the transmission queue.

MQIACH_XMITQ_TIME_INDICATOR

Time on transmission queue.
You cannot use MQIACH_XMITQ_TIME_INDICATOR as a parameter to filter on.

The following value is supported on all platforms:

MQIACH_BATCH_SIZE

Batch size.

The following value is supported on all platforms:

MQIACH_HB_INTERVAL

Heartbeat interval (seconds).

MQIACH_NPM_SPEED

Speed of nonpersistent messages.
The following attributes do not apply to server-connection channels, and no values are returned. If specified on the command they are ignored:
- MQIACH_BATCH_SIZE_INDICATOR
- MQIACH_BATCH_SIZE
- MQIACH_BATCHES
- MQIACH_LONG_RETRIES_LEFT
- MQIACH_NETWORK_TIME
- MQIACH_NPM_SPEED
- MQCA_REMOTE_Q_MGR_NAME
- MQIACH_SHORT_RETRIES_LEFT
- MQIACH_XMITQ_MSGS_AVAILABLE
- MQIACH_XMITQ_TIME_INDICATOR
The following attributes apply only to server-connection channels. If specified on the command for other types of channel the attribute is ignored and no value is returned:
- MQIACH_CURRENT_SHARING_CONVS
- MQIACH_MAX_SHARING_CONVS
Relevant for short status:
The following parameter applies to current channels on z/OS:

MQCACH_Q_MGR_NAME

Name of the queue manager that owns the channel instance.

ChannelInstanceType (MQCFIN)

Channel instance type (parameter identifier: MQIACH_CHANNEL_INSTANCE_TYPE).

It is always returned regardless of the channel instance attributes requested.

The value can be:

MQOT_CURRENT_CHANNEL

The channel status.

MQOT_CURRENT_CHANNEL is the default, and indicates that only current status information for active channels is to be returned.

Both common status information and active-only status information can be requested for current channels.

MQOT_SAVED_CHANNEL

Saved channel status.

Specify MQOT_SAVED_CHANNEL to cause saved status information for both active and inactive channels to be returned.

Only common status information can be returned. Active-only status information is not returned for active channels if this keyword is specified.

MQOT_SHORT_CHANNEL

Short channel status (valid on z/OS only).

Specify MQOT_SHORT_CHANNEL to cause short status information for current channels to be returned.

Other common status and current-only status information are not returned for current channels if this keyword is specified.

You cannot use MQIACH_CHANNEL_INSTANCE_TYPE as a parameter to filter on.

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

You cannot use CommandScope as a parameter to filter on.

ConnectionName (MQCFST)

Connection name (parameter identifier: MQCACH_CONNECTION_NAME).

If this parameter is present, eligible channel instances are limited to those using this connection name. If it is not specified, eligible channel instances are not limited in this way.

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

The value returned for ConnectionName might not be the same as in the channel definition, and might differ between the current channel status and the saved channel status. (Using ConnectionName for limiting the number of sets of status is therefore not recommended.)

For example, when using TCP, if


ConnectionName

in the channel definition:

Is blank or is in host name format, the channel status value has the resolved IP address.
Includes the port number, the current channel status value includes the port number (except on z/OS ), but the saved channel status value does not.

The maximum length of the string is MQ_CONN_NAME_LENGTH.

IntegerFilterCommand (MQCFIF)

Integer filter command descriptor. The parameter identifier must be any integer type parameter allowed in


ChannelInstanceAttrs

except MQIACF_ALL and others as noted. 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, you cannot also specify a string filter using the StringFilterCommand parameter.

StringFilterCommand (MQCFSF)

String filter command descriptor. The parameter identifier must be any string type parameter allowed in


ChannelInstanceAttrs

except MQCACH_CHANNEL_NAME and others as noted. 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 for ConnectionName or XmitQName, you cannot also specify the ConnectionName or XmitQName parameter.

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

XmitQName (MQCFST)

Transmission queue name (parameter identifier: MQCACH_XMIT_Q_NAME).

If this parameter is present, eligible channel instances are limited to those using this transmission queue. If it is not specified, eligible channel instances are not limited in this way.

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

The maximum length of the string is MQ_Q_NAME_LENGTH.

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_CHANNEL_NAME_ERROR: Channel name error.
MQRCCF_CHANNEL_NOT_FOUND: Channel not found.
MQRCCF_CHL_INST_TYPE_ERROR: Channel instance type not valid.
MQRCCF_CHL_STATUS_NOT_FOUND: Channel status not found.
MQRCCF_NONE_FOUND: Channel status not found.
MQRCCF_XMIT_Q_NAME_ERROR: Transmission queue name error.