Routing for publish/subscribe clusters: Notes on behavior

Use the advice given here to help you to detect and deal with routing problems when you are using clustered publish/subscribe messaging.

For information about status checking and troubleshooting for any queue manager cluster, see Queue manager clusters troubleshooting.

All clustered definitions of the same named topic object in a cluster must have the same CLROUTE setting. We can check the CLROUTE setting for all topics on all hosts in the cluster using the following MQSC command:
```
display tcluster(*) clroute
```
The CLROUTE property has no effect unless the topic object specifies a value for the CLUSTER property.
Check that we have spelled the cluster name correctly on your topic. We can define a cluster object such as a topic before defining the cluster. Therefore, when you define a cluster topic, no validation is done on the cluster name because it might not yet exist. Consequently, the product does not alert you to misspelt cluster names.
When you set the CLROUTE property, if the queue manager knows of a clustered definition of the same object from another queue manager that has a different CLROUTE setting, the system generates an MQRCCF_CLUSTER_TOPIC_CONFLICT exception. However, through near simultaneous object definition on different queue managers, or erratic connectivity with full repositories, differing definitions might be created. In this situation the full repository queue managers arbitrate, accepting one definition and reporting an error for the other one. To get more information about the conflict, use the following MQSC command to check the cluster state of all topics on all queue managers in the cluster:
```
display tcluster(*) clstate
```
A state of invalid, or pending (if this does not soon turn to active), indicates a problem. If an invalid topic definition is detected, identify the incorrect topic definition and remove it from the cluster. The full repositories have information about which definition was accepted and which was rejected, and the queue managers that created the conflict have some indication of the nature of the problem. See also CLSTATE in DISPLAY TOPIC.
Set the CLROUTE parameter at a point in the topic tree causes the entire branch beneath it to route topics in that way. We cannot change the routing behavior of a sub-branch of this branch. For this reason, defining a topic object for a lower or higher node in the topic tree with a different CLROUTE setting is rejected with an MQRCCF_CLUSTER_TOPIC_CONFLICT exception.
We can use the following MQSC command to check the topic status of all the topics in the topic tree:
```
display tpstatus('#')
```
If we have a large number of branches in the topic tree, the previous command might display status for an inconveniently large number of topics. If that is the case, we can instead display a manageably small branch of the tree, or an individual topic in the tree. The information displayed includes the topic string, cluster name and cluster route setting. It also includes the publisher count and subscription count (number of publishers and subscribers), to help you judge whether the number of users of this topic is as you expect.
Change the cluster routing of a topic in a cluster is a significant change to the publish/subscribe topology. After a topic object has been clustered (through setting the CLUSTER property) we cannot change the value of the CLROUTE property. The object must be un-clustered (CLUSTER set to ' ') before we can change the value. Un-clustering a topic converts the topic definition to a local topic, which results in a period during which publications are not delivered to subscriptions on remote queue managers; this should be considered when performing this change. See The effect of defining a non-cluster topic with the same name as a cluster topic from another queue manager. If you try to change the value of the CLROUTE property while it is clustered, the system generates an MQRCCF_CLROUTE_NOT_ALTERABLE exception.
For topic host routing, we can explore alternative routes through the cluster by adding and removing the same cluster topic definition on a range of cluster queue managers. To stop a given queue manager from acting as a topic host for your cluster topic, either delete the topic object, or use the PUB(DISABLED) setting to quiesce message traffic for this topic, as discussed in Special handling for the PUB parameter. Do not un-cluster the topic by setting the CLUSTER property to ' ', because removing the cluster name converts the topic definition to a local topic, and prevents the clustering behavior of the topic when used from this queue manager. See The effect of defining a non-cluster topic with the same name as a cluster topic from another queue manager.
We cannot change the cluster of a sub-branch of the topic tree when the branch has already been clustered to a different cluster and CLROUTE is set to TOPICHOST. If such a definition is detected at define time, the system generates an MQRCCF_CLUSTER_TOPIC_CONFLICT exception. Similarly, inserting a newly clustered topic definition at a higher node for a different cluster generates an exception. Because of the clustering timing issues previously described, if such an inconsistency is later detected, the queue manager issues errors to the queue manager log.