STOP CHANNEL

• ¹ Valid only on z/OS when the queue manager is a member of a queue-sharing group.
• ² Valid only on z/OS.

Usage notes for STOP CHANNEL

1. If you specify either QMNAME or CONNAME, STATUS must either be INACTIVE or not specified. Do not specify a QMNAME or CONNAME and STATUS(STOPPED). It is not possible to have a channel stopped for one partner but not for others. This sort of function can be provided by a channel security exit. For more information about channel exits, see Channel exit programs.
2. On z/OS, the command server and the channel initiator must be running.
3. Any channels in STOPPED state need to be started manually; they are not started automatically. See Restarting stopped channels for information about restarting stopped channels.
4. This command can be issued to a channel of any type except CLNTCONN channels (including those that have been defined automatically).
5. 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 channel that was last added to the local queue manager repository.

Parameter descriptions for STOP CHANNEL

(channel-name)

The name of the channel to be stopped. This parameter is required for all channel types.

CHLDISP

This parameter applies to z/OS only and can take the values of:

• DEFAULT
• PRIVATE
• SHARED

If this parameter is omitted, then the DEFAULT value applies. This is taken from the default channel disposition attribute, DEFCDISP, of the channel object.

In conjunction with the various values of the CMDSCOPE parameter, this parameter controls two types of channel:

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

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

Note: This disposition is not related to the disposition set by the disposition of the queue-sharing group of the channel definition. The combination of the CHLDISP and CMDSCOPE 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 CHLDISP and CMDSCOPE are summarized in the following table:

Table 1. CHLDISP and CMDSCOPE for STOP CHANNEL

CHLDISP	CMDSCOPE( ) or CMDSCOPE (local-qmgr)	CMDSCOPE (qmgr-name)	CMDSCOPE(*)
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
SHARED	For RCVR and SVRCONN channels, stop as shared channel on all active queue managers. For SDR, RQSTR, and SVR channels, 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. This might automatically generate a command using CMDSCOPE 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 actually run. Therefore, it is important that channel definitions are consistent. Inconsistent channel definitions might result in unexpected command behavior.	Not permitted	Not permitted

CMDSCOPE

This parameter applies to z/OS only and specifies how the command runs when the queue manager is a member of a queue sharing group. If CHLDISP is set to SHARED, CMDSCOPE must be blank or the local queue manager.

' '

The command runs on the queue manager on which it was entered. This is the default value.

qmgr-name

The command runs on the queue manager you specify, providing the queue manager is active within the queue sharing group.

We can specify a queue manager name only if you are using a queue sharing group environment and if the command server is enabled.

*

The command runs on the local queue manager and is also passed to every active queue manager in the queue sharing group. The effect of this is the same as entering the command on every queue manager in the queue sharing group.

CONNAME (connection-name)

Connection name. Only channels matching the specified connection name are stopped.

When issuing the STOP CHANNEL command using a CONNAME parameter, ensure that the value specified in the CONNAME parameter is exactly as shown in DISPLAY CHSTATUS.

MODE

Specifies whether the current batch is allowed to finish in a controlled manner. This parameter is optional.

QUIESCE

This is the default.

On Multiplatforms, allows the current batch to finish processing.

On z/OS, the channel stops after the current message has finished processing. (The batch is then ended and no more messages are sent, even if there are messages waiting on the transmission queue.)

For a receiving channel, if there is no batch in progress, the channel waits for either of the following to take place before it stops:

• The next batch to start
• The next heartbeat (if heartbeats are being used)

For server-connection channels, allows the current connection to end.

If you issue a STOP CHANNEL channelname MODE (QUIESCE) command on a server-connection channel, 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.

If a client application is using the server-connection channel and is performing either of the following operations at the time that the command is issued, then the MQPUT or MQGET operation fails:

• An MQPUT operation with the PMO option MQPMO_FAIL_IF_QUIESCING set.
• An MQGET operation with the GMO option MQGMO_FAIL_IF_QUIESCING set.

The client application receives reason code MQRC_CONNECTION_QUIESCING. If a client application is using the server-connection channel and is performing either of the following operations, then the client application is allowed to complete the MQPUT or MQGET operation:

• An MQPUT operation without the PMO option MQPMO_FAIL_IF_QUIESCING set.
• An MQGET operation without the GMO option MQGMO_FAIL_IF_QUIESCING set.

Any subsequent FAIL_IF_QUIESCING calls using this connection fail with MQRC_CONNECTION_QUIESCING. Calls which do not specify FAIL_IF_QUIESCING, are usually permitted to complete, although the application should complete such operations in a timely manner, to permit the channel to end.

If the client application is not performing an MQ API call when the server-connection channel is stopped, it becomes aware of the stop request as a result of issuing a subsequent call to IBM MQ and receives return code MQRC_CONNECTION_QUIESCING.

After sending the MQRC_CONNECTION_QUIESCING return code to the client, and allowing any outstanding MQPUT or MQGET operations to complete if necessary, the server ends the client connections for the server-connection channel.

Due to the imprecise timing of network operations, the client application should not attempt further MQ API operations.

FORCE

For server-connection channels, breaks the current connection, returning MQRC_CONNECTION_BROKEN. For other channel types, terminates transmission of any current batch. This is likely to result in in-doubt situations.

On IBM MQ for z/OS, specifying FORCE interrupts any message reallocation in progress, which might leave BIND_NOT_FIXED messages partially reallocated or out of order.

TERMINATE

On z/OS, TERMINATE is synonymous with FORCE.

On other platforms, TERMINATE terminates transmission of any current batch.

This allows the command to actually terminate the channel thread or process.

For server-connection channels, TERMINATE breaks the current connection, returning MQRC_CONNECTION_BROKEN.

On z/OS, specifying TERMINATE interrupts any message reallocation in progress, which might leave BIND_NOT_FIXED messages partially reallocated or out of order.

QMNAME (qmname)

Queue manager name. Only channels matching the specified remote queue manager are stopped.

STATUS

Specifies the new state of any channels stopped by this command. For more information about channels in STOPPED state, especially SVRCONN channels on z/OS, see Restarting stopped channels.

STOPPED

The channel is stopped. For a sender or server channel the transmission queue is set to GET(DISABLED) and NOTRIGGER.

This is the default if QMNAME or CONNAME are not specified.

INACTIVE

The channel is inactive.

This is the default if QMNAME or CONNAME are specified.