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 Troubleshooting queue manager cluster problems.

  • All clustered definitions of the same named topic object in a cluster must have the same CLROUTE setting. You 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 you have spelled the cluster name correctly on your topic. You 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.
  • Setting the CLROUTE parameter at a point in the topic tree causes the entire branch beneath it to route topics in that way. You 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.
  • You can use the following MQSC command to check the topic status of all the topics in the topic tree: 
    display tpstatus('#')
    If you 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, you 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.
  • Changing 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) you cannot change the value of the CLROUTE property. The object must be un-clustered (CLUSTER set to ' ') before you 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, you 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.
  • You 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.
    Attention: Attempting to define a clustered topic with CLROUTE(TOPICHOST) underneath an existing administration topic, also defined with CLROUTE(TOPICHOST), results in error message AMQ8849 being reported.
    Although the configuration described in the preceding text seemingly results in a consistent routing behavior, IBM® MQ prevents conflicting (and potentially conflicting definitions on remote members of the cluster) in order to eliminate unexpected and potentially random routing behavior, resulting from inconsistent definitions elsewhere in the topology. For example:
    • Publications being discarded, when wildcard subscribers are attached in the topic tree above a new administration topic.
    • Definitions not being created equally in number.