Clustered Topics

Single-queue-manager publish/subscribe is the training ground; production estates often run IBM MQ clusters so applications on QM_LONDON publish once and subscribers on QM_PARIS and QM_NEWYORK receive copies without bespoke channel wiring per pair. Clustered topics make that possible: TOPTYPE(CLUS) topic objects register branches of the topic tree in the cluster repository, full and partial repositories exchange definitions, and the pub/sub engine routes publications across members according to PUBSCOPE, SUBSCOPE, subscription location, and stream configuration. When clustered topics are wrong, symptoms look like “works locally”—DISPLAY SUB shows interest on remote queue managers but no messages arrive, or publications never leave the publishing QM. This tutorial covers DEFINE TOPIC CLUS, cluster name alignment, scope attributes, relationship to administrative parents, repository troubleshooting, comparison with point-to-point cluster queues, performance cautions, and beginner MQSC you can trace in a three-QM lab cluster.

Prerequisites: Queue Manager in a Cluster

A clustered topic cannot route what the queue manager does not know about. Each queue manager must belong to a cluster—CLUSTER attribute on the QM, cluster channels, repository role (full or partial). DEFINE TOPIC('ORDERS.CLUS') TOPTYPE(CLUS) CLUSTER('SALES') TOPSTR('retail/order') ties the topic branch to cluster SALES. If CLUSTER on the topic mismatches the QM cluster name, definitions sit orphaned. Beginners should DISPLAY QMGR CLUSTER and DISPLAY CLUSQMGR(*) before debugging pub/sub.

Defining Clustered Topics

1
2
3
4
5
6
7
8
* Queue manager must be in cluster SALES
DEFINE TOPIC('RETAIL.ORDER.CLUS') TOPSTR('retail/order') +
  TOPTYPE(CLUS) CLUSTER('SALES') PUBSCOPE(ALL) SUBSCOPE(ALL) +
  DESCR('Cluster-wide order events')
DEFINE TOPIC('RETAIL.ORDER.CREATED') TOPSTR('retail/order/created') +
  TOPTYPE(LOCAL) ADMINTOPIC('RETAIL.ORDER.CLUS')
DISPLAY TOPIC('RETAIL.ORDER.CLUS') CLUSTER TOPTYPE
DISPLAY CLUSQMGR(*) CLUSTER(SALES)

Pattern: one CLUS administrative parent at domain branch; LOCAL leaves for specific events under it. Putting CLUS on every leaf floods the repository with redundant definitions. Operations teams standardize one CLUS object per shared prefix (retail/order) not per event (retail/order/created, retail/order/shipped, ... each CLUS).

How Routing Differs from Cluster Queues

Cluster queues (CLUSQ) route point-to-point messages to one destination chosen by cluster workload algorithms. Clustered topics duplicate publications to every matching subscription on every interested queue manager—fan-out multiplies bandwidth and disk. A hot topic with ALL scope and a # subscription on five queue managers creates five puts per publish minimum. Capacity planning for clustered topics is subscription-count times message rate, not single-target cluster queue depth.

Publication Path Across Members

1. Publisher connects to QM_A and publishes to retail/order/created.
2. Local pub/sub engine evaluates local subscriptions; copies to local DEST queues.
3. Cluster logic determines remote interest using repository knowledge and scope.
4. Messages traverse cluster channels to QM_B, QM_C where matching subs exist.
5. Remote engines put to their local DEST queues; applications MQGET locally.

Channel health (CLUSRCVR, CLUSSDR) still matters—pub/sub rides the same infrastructure as point-to-point cluster traffic. Channel retry during repository sync delays can defer topic definition visibility on partial repositories.

Explainer: Radio Network Affiliates

A clustered topic is like a radio network syndicating a show: the studio (publishing QM) transmits once; affiliate stations (remote QMs) rebroadcast to local listeners (subscriptions). If an affiliate never signed the syndication contract (cluster definition missing), local listeners hear silence even though the studio aired the episode.

Troubleshooting Cluster Pub/Sub

• DISPLAY TOPIC—CLUSTER and TOPTYPE CLUS on parent branch.
• DISPLAY SUB on each QM—SUBSCOPE and TOPICSTR must allow remote matching.
• DISPLAY CLUSQMGR—membership and channel state RUNNING.
• Compare publish string case and depth against subscription patterns.
• Check authority for remote put and subscribe on topic prefix.
• Review IBM technote for pub/sub clustering on your maintenance level.

Design Best Practices

Use administrative CLUS parents at stable domain roots; keep leaves LOCAL when possible. Align enterprise topic catalog with cluster names—one cluster per business domain reduces cross-cluster confusion. Avoid cluster-wide # subscriptions for high-rate telemetry; prefer targeted leaves or stream partitioning. Test fail-over: when publishing QM stops, understand whether publishers reconnect elsewhere and whether definitions survive repository switch.

Explain Like I'm Five: Clustered Topics

Clustered topics let friends in different houses hear the same announcement. Each house has its own mailbox (queue) for kids who signed up (subscriptions). The announcement travels between houses on roads (channels), not by everyone running to one mailbox.

Practice Exercises

Exercise 1

Sketch three-QM cluster with one CLUS parent and subs on two remote QMs.

Exercise 2

Why is CLUS on every leaf a repository problem?

Exercise 3

List DISPLAY commands for “publish OK on QM1, zero messages on QM2 sub.”

Frequently Asked Questions

Test Your Knowledge