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.

We must specify the name of the channel for which we 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 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 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 MQ Telemetry command is truncated by the 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.

Parent topic: Definitions of the Programmable Command Formats