Publication Routing

Publication routing is the journey from MQPUT on a topic string to one or more puts on subscriber destination queues. The publisher does not address each consumer by name—the queue manager pub/sub engine resolves the topic in the tree, evaluates every active subscription, and routes copies according to local rules, wildcard matching, retained publication options, and cluster topology. Understanding routing separates “publish returned OK” from “consumer received data”—orphan publishes with zero matching subs succeed without error. Cluster routing adds hops over CLUSSDR and CLUSRCVR with PUBSCOPE and propagated SUBSCOPE in the decision. This tutorial walks the local routing path step by step, cluster forwarding, fan-out arithmetic, interaction with persistent and non-persistent messages, proxy and stream edge cases at overview level, failure modes, DISPLAY diagnostics, and performance planning when routing multiplies puts across data centers.

Local Routing Path

1. Application issues MQPUT with topic string or topic handle.
2. OAM checks PUB authority on resolved string.
3. Pub/sub engine locates topic tree node and active subscriptions.
4. For each match, engine formats copy and puts to DEST queue.
5. Subscriber applications MQGET from their DEST independently.

No match means successful publish with zero deliveries—log publish string and DISPLAY SUB TOPICSTR when debugging “lost” events.

Wildcard Matching in Routing

Engine compares published string segments to subscription patterns. Publish retail/uk/order/created does not match retail/+/created because two levels exist between retail and created where + allows one. Test patterns in lab with amqspub and a known subscriber queue. Hierarchy design and routing success are the same problem—see topic hierarchies tutorial.

1
2
3
4
5
DEFINE SUB('ORDERS.UK') TOPICSTR('retail/uk/order/#') DESTQL('UK.ORDERS.SUB')
DEFINE SUB('ORDERS.ANY.SHIPPED') TOPICSTR('retail/+/shipped') DESTQL('SHIP.SUB')
* Publish retail/uk/order/created -> UK.ORDERS.SUB only
* Publish retail/us/shipped -> SHIP.SUB only
DISPLAY QLOCAL('UK.ORDERS.SUB') CURDEPTH

Cluster Publication Routing

When publisher and subscriber live on different queue managers, routing consults cluster repository knowledge: clustered topic PUBSCOPE, subscription SUBSCOPE propagation, and channel availability. Local engine on publishing QM may hand off to cluster transport; receiving QM puts to local DEST. Asymmetric cluster ACL or stopped CLUSSDR mimics routing failure. Pair with subscription propagation and clustered topics tutorials.

Fan-Out and Capacity

One publish to prod/announcement/company with fifty ALL-scoped subscriptions across ten queue managers can produce fifty puts and significant channel bytes. High-rate publishers on broad topics need subscription governance—avoid accidental duplicate subs during testing. Monitor publish rate × match count = delivery rate.

Retained Publications in Routing

When retain is set on a publish, new matching subscriptions may receive the last retained message on registration per IBM rules—routing includes retain lookup in addition to live publish stream. Do not confuse with durable subscription backlog from offline consumers.

Troubleshooting Routing Failures

• Character-compare publish log string to DISPLAY SUB TOPICSTR.
• DISPLAY QLOCAL DEST CURDEPTH during publish test.
• Check AMQ error messages for authority on topic or DEST put.
• Cluster: channel status, SUBSCOPE, PUBSCOPE, CLUS topic defined.
• Multiple subs—verify which DEST should have received copy.

Explainer: Mail Sorting Room

Publication routing is the sorting room: one incoming package (publish) is photocopied for every person on the matching mailing list (subscriptions) and placed in their mailbox (DEST). No list match means the package is discarded after accept—still “posted OK.”

Explain Like I'm Five: Publication Routing

When someone shouts a dinosaur fact, the teacher makes a copy for every kid who raised their hand for dinosaur news and puts it in their cubby. Routing is making and delivering those copies.

Practice Exercises

Exercise 1

Given two subs, predict which DEST receives publish retail/de/ship/done.

Exercise 2

Calculate puts if publish matches 7 subs on 3 queue managers.

Exercise 3

Write debug command list for publish OK, empty DEST.

Frequently Asked Questions

Test Your Knowledge