Stop Channel

The Stop Channel (MQCMD_STOP_CHANNEL) command stops an IBM MQ channel.

This command can be issued to a channel of any type (except MQCHT_CLNTCONN).

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.

None of the following attributes are applicable to MQTT channels unless specifically mentioned in the parameter description.

Required parameters

ChannelName (MQCFST)

Channel name (parameter identifier: MQCACH_CHANNEL_NAME).

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

This parameter is required for all channel types..

Optional parameters

ChannelDisposition (MQCFIN)

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

Specifies the disposition of the channels to be stopped.

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.

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 every active 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

ChannelDisposition	CommandScope blank or local-qmgr	CommandScope qmgr-name	CommandScope(*)
MQCHLD_PRIVATE	Stop as a private channel on the local queue manager	Stop as a private channel on the named queue manager	Stop as a private channel on all active queue managers
MQCHLD_SHARED	For channels of ChannelType MQCHT_RECEIVER or MQCHT_SVRCONN, stop as shared channel on all active queue managers. For channels of ChannelType MQCHT_SENDER, MQCHT_REQUESTER, and MQCHT_SERVER, stop as a shared channel on the queue manager where it is running. If the channel is in an inactive state (not running), or if it is in RETRY state because the channel initiator on which it was running has stopped, a STOP request for the channel is issued on the local queue manager. 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

ChannelDisposition

CommandScope blank or local-qmgr

CommandScope qmgr-name

CommandScope(*)

MQCHLD_PRIVATE

Stop as a private channel on the local queue manager

Stop as a private channel on the named queue manager

Stop as a private channel on all active queue managers

MQCHLD_SHARED

For channels of ChannelType MQCHT_RECEIVER or MQCHT_SVRCONN, stop as shared channel on all active queue managers.

For channels of ChannelType MQCHT_SENDER, MQCHT_REQUESTER, and MQCHT_SERVER, stop as a shared channel on the queue manager where it is running. If the channel is in an inactive state (not running), or if it is in RETRY state because the channel initiator on which it was running has stopped, a STOP request for the channel is issued on the local queue manager.

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

ChannelStatus (MQCFIN)

The new state of the channel after the command is executed (parameter identifier: MQIACH_CHANNEL_STATUS). The value can be any of the following values:

MQCHS_INACTIVE: Channel is inactive.
MQCHS_STOPPED: Channel is stopped. MQCHS_STOPPED is the default if nothing is specified.

CommandScope (MQCFST)

Command scope (parameter identifier: MQCACF_COMMAND_SCOPE). This parameter applies to z/OS only. Specifies how the command is processed 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, we 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.

ConnectionName (MQCFST)

Connection name of channel to be stopped (parameter identifier: MQCACH_CONNECTION_NAME).

This parameter is the connection name of the channel to be stopped. If this parameter is omitted, all channels with the specified channel name and remote queue manager name are stopped. On Multiplatforms, the maximum length of the string is MQ_CONN_NAME_LENGTH. On z/OS, the maximum length of the string is MQ_LOCAL_ADDRESS_LENGTH.

If this parameter is specified, ChannelStatus must be MQCHS_INACTIVE.

Mode (MQCFIN)

How the channel must be stopped (parameter identifier: MQIACF_MODE). The value can be:

MQMODE_QUIESCE: Quiesce the channel. MQMODE_QUIESCE is the default.
If we issue a Stop Channel channelname Mode(MQMODE_QUIESCE) command on a server-connection channel with the sharing conversations feature enabled, the IBM MQ client infrastructure becomes aware of the stop request in a timely manner; this time is dependent upon the speed of the network. The client application becomes aware of the stop request as a result of issuing a subsequent call to IBM MQ.
MQMODE_FORCE: Stop the channel immediately; the thread or process of the channel is not terminated. Stops transmission of any current batch.; For server-connection channels, breaks the current connection, returning MQRC_CONNECTION_BROKEN.; For other types of channels, this situation is likely to result in in-doubt situations.; On z/OS, this option interrupts any message reallocation in progress, which can leave BIND_NOT_FIXED messages partially reallocated or out of order.
MQMODE_TERMINATE: On Multiplatforms, stop the channel immediately; the thread or process of the channel is terminated.; On z/OS, MQMODE_TERMINATE is synonymous with FORCE.; On z/OS, this option interrupts any message reallocation in progress, which can leave BIND_NOT_FIXED messages partially reallocated or out of order.

Note: This parameter was previously called Quiesce (MQIACF_QUIESCE), with values MQQO_YES and MQQO_NO. The old names can still be used.

QMgrName (MQCFST)

Name of remote queue manager (parameter identifier: MQCA_Q_MGR_NAME).

This parameter is the name of the remote queue manager to which the channel is connected. If this parameter is omitted, all channels with the specified channel name and connection name are stopped. The maximum length of the string is MQ_Q_MGR_NAME_LENGTH.

If this parameter is specified, ChannelStatus must be MQCHS_INACTIVE.

MQIACF_IGNORE_STATE

This parameter allows you to specify whether we want the command to return an error return code, if the object is already in the state the command would move it to. Possible values are:

MQIS_NO: If the channel being stopped is already in that state, the command returns RC=10. This is the existing behavior, and NO is the default value.
MQIS_YES: If the channel being stopped is already in that state, the command returns RC=0. The return code is the case as if the channel is not running.

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_CHANNEL_DISABLED: Channel disabled.
MQRCCF_CHANNEL_NOT_ACTIVE: Channel not active.
MQRCCF_CHANNEL_NOT_FOUND: Channel not found.
MQRCCF_MODE_VALUE_ERROR: Mode value not valid.
MQRCCF_MQCONN_FAILED: MQCONN call failed.
MQRCCF_MQOPEN_FAILED: MQOPEN call failed.
MQRCCF_MQSET_FAILED: MQSET call failed.

Parent topic: Definitions of the Programmable Command Formats