Ping Channel

The Ping Channel (MQCMD_PING_CHANNEL) command tests a channel by sending data as a special message to the remote message queue manager and checking that the data is returned. The data is generated by the local queue manager.

This command can only be used for channels with a ChannelType value of MQCHT_SENDER, MQCHT_SERVER, or MQCHT_CLUSSDR.

Where there is both a locally defined channel and an auto-defined cluster-sender channel of the same name, the command applies to the locally defined channel.

If there is no locally defined channel but more than one auto-defined cluster-sender channel, the command applies to the last channel added to the repository on the local queue manager.

The command is not valid if the channel is running; however it is valid if the channel is stopped or in retry mode.


Required parameters

    ChannelName (MQCFST)
    Channel name (parameter identifier: MQCACH_CHANNEL_NAME).

    The name of the channel to be tested. The maximum length of the string is MQ_CHANNEL_NAME_LENGTH.


Optional parameters

    DataCount (MQCFIN)
    Data count (parameter identifier: MQIACH_DATA_COUNT).

    Specifies the length of the data.

    Specify a value in the range 16 through 32 768. The default value is 64 bytes.

    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 processed on the queue manager on which it was entered.
    • a queue manager name. The command is processed 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 processed 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.

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

    Specifies the disposition of the channels to be tested.

    If this parameter is omitted, then the value for the channel disposition is taken from the default channel disposition attribute of the channel object.

    The value can be any of the following values:

      MQCHLD_PRIVATE
      A receiving channel is private if it was started in response to an inbound transmission directed to the queue manager.

      A sending channel is private if its transmission queue has a disposition other than MQQSGD_SHARED.

      MQCHLD_SHARED
      A receiving channel is shared if it was started in response to an inbound transmission directed to the queue sharing group.

      A sending channel is shared if its transmission queue has a disposition of MQQSGD_SHARED.

      MQCHLD_FIXSHARED
      Tests shared channels, tied to a specific queue manager.

    The combination of the ChannelDisposition and CommandScope parameters also controls from which queue manager the channel is operated. The possible options are:

    • On the local queue manager where the command is issued.
    • On another specific named queue manager in the group.
    • On the most suitable queue manager in the group, determined automatically by the queue manager itself.

    The various combinations of ChannelDisposition and CommandScope are summarized in Table 1

    Table 1. ChannelDisposition and CommandScope for PING CHANNEL
    ChannelDisposition CommandScope blank or local-qmgr CommandScope qmgr-name CommandScope(*)
    MQCHLD_PRIVATE Ping private channel on the local queue manager Ping private channel on the named queue manager Ping private channel on all active queue managers
    MQCHLD_SHARED Ping a shared channel on the most suitable queue manager in the group

    MQCHLD_SHARED might automatically generate a command using CommandScope and send it to the appropriate queue manager. If there is no definition for the channel on the queue manager to which the command is sent, or if the definition is unsuitable for the command, the command fails.

    The definition of a channel on the queue manager where the command is entered might be used to determine the target queue manager where the command is run. Therefore, it is important that channel definitions are consistent. Inconsistent channel definitions might result in unexpected command behavior.

    		Not permitted Not permitted
    MQCHLD_FIXSHARED Ping a shared channel on the local queue manager Ping a shared channel on the named queue manager Not permitted


Error codes

This command might return the following error codes 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_ALLOCATE_FAILED
      Allocation failed.

      MQRCCF_BIND_FAILED
      Bind failed.

      MQRCCF_CCSID_ERROR
      Coded character-set identifier error.

      MQRCCF_CHANNEL_CLOSED
      Channel closed.

      MQRCCF_CHANNEL_IN_USE
      Channel in use.

      MQRCCF_CHANNEL_NOT_FOUND
      Channel not found.

      MQRCCF_CHANNEL_TYPE_ERROR
      Channel type not valid.

      MQRCCF_CONFIGURATION_ERROR
      Configuration error.

      MQRCCF_CONNECTION_CLOSED
      Connection closed.

      MQRCCF_CONNECTION_REFUSED
      Connection refused.

      MQRCCF_DATA_TOO_LARGE
      Data too large.

      MQRCCF_ENTRY_ERROR
      Connection name not valid.

      MQRCCF_HOST_NOT_AVAILABLE
      Remote system not available.

      MQRCCF_NO_COMMS_MANAGER
      Communications manager not available.

      MQRCCF_PING_DATA_COMPARE_ERROR
      Ping Channel command failed.

      MQRCCF_PING_DATA_COUNT_ERROR
      Data count not valid.

      MQRCCF_PING_ERROR
      Ping error.

      MQRCCF_RECEIVE_FAILED
      Receive failed.

      MQRCCF_RECEIVED_DATA_ERROR
      Received data error.

      MQRCCF_REMOTE_QM_TERMINATING
      Remote queue manager terminating.

      MQRCCF_REMOTE_QM_UNAVAILABLE
      Remote queue manager not available.

      MQRCCF_SEND_FAILED
      Send failed.

      MQRCCF_STRUCTURE_TYPE_ERROR
      Structure type not valid.

      MQRCCF_TERMINATED_BY_SEC_EXIT
      Channel terminated by security exit.

      MQRCCF_UNKNOWN_REMOTE_CHANNEL
      Remote channel not known.

      MQRCCF_USER_EXIT_NOT_AVAILABLE
      User exit not available.