Inquire Channel Status

The Inquire Channel Status (MQCMD_INQUIRE_CHANNEL_STATUS) 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)

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.

Without this authority this command runs without error, but a value of zero is output for the MsgsAvailable parameter of the Inquire Channel Status (Response) command. If we 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:

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

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

  We 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_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.

  We cannot use MQIACF_MONITORING as a parameter to filter on.

  MQIACH_BATCH_SIZE_INDICATOR

  Batch size.

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

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

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

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

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

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

  This parameter does not apply to 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.

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

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

We 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, we 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, we cannot also specify the ConnectionName or XmitQName parameter.

If you specify a string filter, we 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_XMIT_Q_NAME_ERROR

Transmission queue name error.