Clustering: Switching cluster transmission queues

Plan how the changes to the cluster transmission queues of an existing production queue manager are going to be brought into effect.

Before you begin

If you reduce the number of messages the switching process has to transfer to the new transmission queue, switching completes more quickly. Read How the process to switch cluster-sender channel to a different transmission queue works for the reasons for trying to empty the transmission queue before proceeding any further.

About this task

You have a choice of two ways of making the changes to cluster transmission queues take effect.

Let the queue manager make the changes automatically. This is the default. The queue manager switches cluster-sender channels with pending transmission queue changes when a cluster-sender channel next starts.
Make the changes manually. You can make the changes to a cluster-sender channel when it is stopped. You can switch it from one cluster transmission queue to another before the cluster-sender channel starts.

What factors do you take into account when deciding which of the two options to choose, and how do you manage the switch?

Procedure

Option 1: Let the queue manager make the changes automatically; see Switching active cluster-sender channels to another set of cluster-transmission queues.
Choose this option if you want the queue manager to make the switch for you.

An alternative way to describe this option is to say the queue manager switches a cluster-sender channel without you forcing the channel to stop. You do have the option of forcing the channel to stop, and then starting the channel, to make the switch happen sooner. The switch starts when the channel starts, and runs while the channel is running, which is different to option 2. In option 2, the switch takes place when the channel is stopped.
- If you choose this option by letting the switch happen automatically, the switching process starts when a cluster-sender channel starts. If the channel is not stopped, it starts after it becomes inactive, if there is a message to process. If the channel is stopped, start it with the START CHANNEL command.
- The switch process completes as soon as there are no messages left for the cluster-sender channel on the transmission queue the channel was serving. As soon as that is the case, newly arrived messages for the cluster-sender channel are stored directly on the new transmission queue. Until then, messages are stored on the old transmission queue, and the switching process transfers messages from the old transmission queue to the new transmission queue. The cluster-sender channel forwards messages from the new cluster transmission queue during the whole switching process.
- When the switch process completes depends on the state of the system. If you are making the changes in a maintenance window, assess beforehand whether the switching process will complete in time. Whether it will complete in time depends on whether the number of messages that are awaiting transfer from the old transmission queue reaches zero.
The advantage of the first method is it is automatic. A disadvantage is that if the time to make the configuration changes is limited to a maintenance window, you must be confident that you can control the system to complete the switch process inside the maintenance window. If you cannot be sure, option 2 might be a better choice.
Option 2: Make the changes manually; see Switching a stopped cluster-sender channel to another cluster transmission queue.
Choose this option if you want to control the entire switching process manually, or if you want to switch a stopped or inactive channel. It is a good choice, if you are switching a few cluster-sender channels, and you want to do the switch during a maintenance window.

An alternative description of this option is to say that you switch the cluster-sender channel, while the cluster-sender channel is stopped.
- If you choose this option you have complete control over when the switch takes place.
- You can be certain about completing the switching process in a fixed amount of time, within a maintenance window. The time the switch takes depends on how many messages have to be transferred from one transmission queue to the other. If messages keep arriving, it might take a time for the process to transfer all the messages.
- You have the option of switching the channel without transferring messages from the old transmission queue. The switch is instant.
- When you restart the cluster-sender channel, it starts processing messages on the transmission queue you newly assigned to it.
The advantage of the second method is you have control over the switching process. The disadvantage is that you must identify the cluster-sender channels to be switched, run the necessary commands, and resolve any in-doubt channels that might be preventing the cluster-sender channel stopping.

Switching active cluster-sender channels to another set of cluster-transmission queues

This task gives you three options for switching active cluster-sender channels. One option is to let the queue manager make the switch automatically, which does not affect running applications. The other options are to stop and start channels manually, or to restart the queue manager.

Before you begin

Change the cluster transmission queue configuration. You can change the DEFCLXQ queue manager attribute, or add or modify the CLCHNAME attribute of transmission queues.

About this task

Use the steps in the task as a basis for working out your own plan for making cluster-transmission queue configuration changes.

Procedure

Optional: Record the current channel status
Make a record of the status of current and saved channels that are serving cluster transmission queues. The following commands display the status associated with system cluster transmission queues. Add your own commands to display the status associated with cluster-transmission queues that you have defined. Use a convention, such as XMITQ. ChannelName, to name cluster transmission queues that you define to make it easy to display the channel status for those transmission queues.
```
DISPLAY CHSTATUS(*) WHERE(XMITQ LK 'SYSTEM.CLUSTER.TRANSMIT.*')
DISPLAY CHSTATUS(*) SAVED WHERE(XMITQ LK 'SYSTEM.CLUSTER.TRANSMIT.*')
```
Switch transmission queues.
- Do nothing. The queue manager switches cluster-sender channels when they restart after being stopped or inactive.
  Choose this option if you have no rules or concerns about altering a queue manager configuration. Running applications are not affected by the changes.
- Restart the queue manager. All cluster-sender channels are stopped and restarted automatically on demand.
  Choose this option to initiate all the changes immediately. Running applications are interrupted by the queue manager as it shuts down and restarts.
- Stop individual cluster-sender channels and restart them.
  Choose this option to change a few channels immediately. Running applications experience a short delay in message transfer between your stopping and starting the message channel again. The cluster-sender channel remains running, except during the time you stopped it. During the switch process messages are delivered to the old transmission queue, transferred to the new transmission queue by the switching process, and forwarded from the new transmission queue by the cluster-sender channel.
Optional: Monitor the channels as they switch
Display the channel status and the transmission queue depth during the switch. The following example display the status for system cluster transmission queues.
```
DISPLAY CHSTATUS(*) WHERE(XMITQ LK 'SYSTEM.CLUSTER.TRANSMIT.*')
DISPLAY CHSTATUS(*) SAVED WHERE(XMITQ LK 'SYSTEM.CLUSTER.TRANSMIT.*')
DISPLAY QUEUE('SYSTEM.CLUSTER.TRANSMIT.*') CURDEPTH
```
Optional: Monitor the messages AMQ7341 The transmission queue for channel ChannelName switched from queue QueueName to QueueName that are written to the queue manager error log.

Switching a stopped cluster-sender channel to another cluster transmission queue

Before you begin

You might make some configuration changes, and now want to make them effective without starting the cluster-sender channels that are affected. Alternatively, you make the configuration changes you require as one of the steps in the task.

About this task

This task switches the transmission queues served by stopped or inactive cluster-sender channels. You might do this task because a cluster-sender channel is stopped, and you want to switch its transmission queue immediately. For example, for some reason a cluster-sender channel is not starting, or has some other configuration problem. To resolve the problem, you decide to create a cluster-sender channel, and associate the transmission queue for the old cluster-sender channel with the new cluster-sender channel you defined.

A more likely scenario is you want to control when reconfiguration of cluster transmission queues is performed. To fully control the reconfiguration, you stop the channels, change the configuration, and then switch the transmission queues.

Procedure

Stop the channels that you intend to switch
1. Stop any running or inactive channels that you intend to switch. Stopping an inactive cluster-sender channel prevents it starting while you are making configuration changes.
```
STOP CHANNEL(ChannelName) MODE(QUIESCSE) STATUS(STOPPED)
```
Optional: Make the configuration changes.

For example, see Clustering: Example configuration of multiple cluster transmission queues.
Switch the cluster-sender channels to the new cluster transmission queues.
On distributed platforms, issue the following command:
```
runswchl -m QmgrName -c ChannelName
```
On z/OS®, use the SWITCH function of the CSQUTIL command to switch the messages or monitor what is happening. Use the following command.
```
SWITCH CHANNEL(channel_name) MOVEMSGS(YES)
```
For more information, see SWITCH function.
The runswchl, or CSQUTIL SWITCH, command transfers any messages on the old transmission queue to the new transmission queue. When the number of messages on the old transmission queue for this channel reaches zero, the switch is completed. The command is synchronous. The command writes progress messages to the window during the switching process.

During the transfer phase existing and new messages destined for the cluster-sender channel are transferred in order to the new transmission queue.

Because the cluster-sender channel is stopped, the messages build up on the new transmission queue. Contrast the stopped cluster-sender channel, to step 2 in Switching active cluster-sender channels to another set of cluster-transmission queues. In that step, the cluster-sender channel is running, so messages do not necessarily build up on the new transmission queue.
Optional: Monitor the channels as they switch
In a different command window, display the transmission queue depth during the switch. The following example display the status for system cluster transmission queues.
```
DISPLAY QUEUE('SYSTEM.CLUSTER.TRANSMIT.*') CURDEPTH
```
Optional: Monitor the messages AMQ7341 The transmission queue for channel ChannelName switched from queue QueueName to QueueName that are written to the queue manager error log.
Restart the cluster-sender channels that you stopped.

The channels do not start automatically, as you stopped them, placing them into STOPPED status.
```
START CHANNEL(ChannelName)
```