This is part of a series of small blog posts which will cover some of the smaller, perhaps less likely to be noticed, features of IBM MQ. Read other posts in this series.

No doubt you have used the IBM MQ STOP CHANNEL command many a time, but did you ever notice that there are parameters on the command beyond just the channel name?

If you're using generic receivers or server-connection channels, where more than one inbound connection is using the same channel name, then these additional parameters may be useful to you.

Selecting a specific running channel instance to stop

If you have these multiple inbound connections and you issue the following plain ordinary stop command:-

STOP CHANNEL(TO.MQG1)

then you will stop all the running instances of that channel, and that might not have been what you wanted to do.

If instead you wanted to be a little more specific, and only stop one instance of a generic receiver channel then you could instead issue one of the following commands.

STOP CHANNEL(TO.MQG1) QMNAME(MQG2)

STOP CHANNEL(TO.MQG1) CONNAME('192.168.2.104')

Here you can see that you can select the running instance you specifically want to stop by either the remote queue manager name of the partner, or by the IP address of the partner. To be absolutely certain that you have the correct data to put into these parameters, you can first use the DISPLAY CHSTATUS command to see the information.

DISPLAY CHSTATUS(TO.MQG1)

In response to which you would see output like this:

AMQ8417: Display Channel Status details.
   CHANNEL(TO.MQG1)                        CHLTYPE(RCVR)
   CONNAME(192.168.2.104)                  CURRENT
   RQMNAME(MQG2)                           STATUS(RUNNING)
   SUBSTATE(RECEIVE)                    
AMQ8417: Display Channel Status details.
   CHANNEL(TO.MQG1)                        CHLTYPE(RCVR)
   CONNAME(192.168.2.106)                  CURRENT
   RQMNAME(MQG3)                           STATUS(RUNNING)
   SUBSTATE(RECEIVE)                    

In order to stop the appropriate running instance of the channel, the CONNAME value, if used, must match what is shown in the DISPLAY CHSTATUS output. You may expect a different IP address if things like Network Address Translation or some such is active on this link, but what matters is what the queue manager knows as the CONNAME in order for it to look up in the channel status table and find the running channel instance to be stopped.

This technique is also applicable to server-connection channels, but of course the QMNAME parameter is not relevant, so you can only use the CONNAME parameter to make your STOP CHANNEL command more specific. Sometimes of course there will be multiple client/server-connection channels running from the same client machine, and then even STOP CHANNEL using the CONNAME parameter won't be able to be specific enough. In that case, you can still look to use the STOP CONN command, since each client connection will equate to one entry shown by the DISPLAY CONN command. Perhaps that can be the subject of a future MQ Little Gem post!

Stopping Mode

Having stopped a channel from the responding end (that is the receiver or server-connection end), it make take a little while before the initiating end (that is the sender or the client end) to notice. If you just quiesce the channel, which is the default behaviour, then you might wait up to 5 minutes before the sender notices (assuming default heartbeat interval values) if no messages are flowing over the channel. This is because the sender is sitting in a Get-Wait on the transmission queue and hasn't yet seen the request to stop. You'll see an indication of this on your receiver channel status as follows:-

DISPLAY CHSTATUS(TO.MQG1) STOPREQ

In response to which you would see output like this:

AMQ8417: Display Channel Status details.
   CHANNEL(TO.MQG1)                        CHLTYPE(RCVR)
   CONNAME(127.0.0.1)                      CURRENT
   RQMNAME(MQG2)                           STATUS(STOPPING) 
   STOPREQ(YES)                            SUBSTATE(RECEIVE)

When the sender wakes up, or finishes the next batch of messages, it will then see that the receiver has asked for the channel to stop, and will follow suit.

Instead of allowing the channel to quiesce, there are two other modes of stopping a channel. You can use MODE(FORCE) or MODE(TERMINATE). Both of these force the channel to stop immediately at the queue manager where the command is issued by forcibly terminating the comms link. MODE(TERMINATE) is the harshest of all because it terminates the channel thread. This is mainly useful when a MODE(FORCE) style stop has already been tried and failed. It can be useful, for example, when a channel is stuck in a channel exit that has not returned, and generally wouldn't be needed in the normal day-to-day running of a production system.

Status of a stopped channel

When you stop a channel using a plain ordinary stop command:-

STOP CHANNEL(TO.MQG1)

all the running instances of the channel are stopped and have STATUS(STOPPED).

If you want to stop a channel but leave it in a state where it could later be successfully started up again, you can instead use the following command:-

STOP CHANNEL(TO.MQG1) STATUS(INACTIVE)

This is applicable whether you are stopping a responding or an initiating channel. For example, it leaves a sender channel in a state where it is ready to be re-triggered again should messages turn up for it to move, where the earlier command did not.

If you are stopping a single running instance of a channel, the stop command always acts like you have used STATUS(INACTIVE). This is because you cannot have a channel that is stopped for one partner but not for others.

If your intention when stopping a single instance of the channel was simple to recycle it, perhaps to pick up some new configuration attributes, then the sender end will likely immediately retry and get reconnected again, and if it's a client connection, then the client application may (depending on how it was coded) re-connect in immediately.

If however, your intention when stopping a single instance of the channel was to kick out a connection that shouldn't be there, you should first put in place something that will disallow it from connecting in again. For example, some Channel Authentication rules. Otherwise, you will find five minutes later that the same connection is back again!

I hope this has introduced you to some handy additional parameters that the STOP CHANNEL command provides.