Inquire Channel Status (MQTT)

The Inquire Channel Status (MQCMD_INQUIRE_CHANNEL_STATUS) (MQTT) command inquires about the status of one or more Telemetry 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.

Note: The Inquire Channel Status command for IBM® MQ Telemetry has the potential to return a far larger number of responses than if the command was run for an IBM MQ channel. For this reason, the IBM MQ Telemetry server does not return more responses than fit on the reply-to queue. The number of responses is limited to the value of MAXDEPTH parameter of the SYSTEM.MQSC.REPLY.QUEUE queue. When an IBM MQ Telemetry command is truncated by the IBM MQ Telemetry server, the AMQ8492 message is displayed specifying how many responses are returned based on the size of MAXDEPTH.

If the ClientIdentifier parameter is not specified, the output of the Inquire Channel Status command is a summary of statuses of all clients connected to the channel. One PCF response message is returned per channel.

If the ClientIdentifier parameter is specified, separate PCF response messages are returned for each client connection. The ClientIdentifier parameter may be a wildcard, in which the status for all clients that match the ClientIdentifier string is returned (within the limits of MaxResponses and ResponseRestartPoint if they are set).

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 which have names that start with the selected character string. An asterisk on its own matches all possible names.

This parameter is allowed for only when the ResponseType parameter is set to MQRESP_TOTAL.

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

The maximum length of the string is MQ_CHANNEL_NAME_LENGTH.

ChannelType (MQCFIN)

Channel type (parameter identifier: MQIACH_CHANNEL_TYPE).

The value must be:

MQCHT_MQTT: Telemetry.

Optional parameters

ClientIdentifer (MQCFST): The ClientId of the client (parameter identifier: MQCACH_CLIENT_ID).
MaxResponses (MQCFIN): The maximum number of clients to return status for (parameter identifier: MQIA_MAX_RESPONSES).
This parameter is only allowed when the ClientIdentifier parameter is specified.
ResponseRestartPoint (MQCFIN): The first client to return status for (parameter identifier: MQIA_RESPONSE_RESTART_POINT). The combination of this parameter with MaxResponses enables the range of clients to be specified.
This parameter is only allowed when the ClientIdentifier parameter is specified.

Client details mode

STATUS: The current status of the client (parameter identifier: MQIACH_CHANNEL_STATUS).
CONNAME: The name of the remote connection (ip address) (parameter identifier: MQCACH_CONNECTION_NAME).
KAINT: The keep alive interval of the client (parameter identifier: MQIACH_KEEP_ALIVE_INTERVAL).
MCANAME: Message channel agent name (parameter identifier: MQCACH_MCA_USER_ID).
MSGSNT: Number of messages sent by the client since it last connected (parameter identifier: MQIACH_MSGS_SENT).
MSGRCVD: Number of messages received by the client since it last connected (parameter identifier: MQIACH_MSGS_RECEIVED / MQIACH_MSGS_RCVD).
INDOUBTIN: Number of in doubt, inbound messages to the client (parameter identifier: MQIACH_IN_DOUBT_IN).
INDOUBTOUT: Number of in doubt, outbound messages to the client (parameter identifier: MQIACH_IN_DOUBT_OUT).
PENDING: Number of outbound pending messages (parameter identifier: MQIACH_PENDING_OUT).
LMSGDATE: Date last message was received or sent (parameter identifier: MQCACH_LAST_MSG_DATE).
LMSGTIME: Time last message was received or sent (parameter identifier: MQCACH_LAST_MSG_TIME).
CHLSDATE: Date channel started (parameter identifier: MQCACH_CHANNEL_START_DATE).
CHLSTIME: Time channel was started (parameter identifier: MQCACH_CHANNEL_START_TIME).

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.