Subscriptions

Subscriptions are the receiving side of IBM MQ publish/subscribe. A publisher emits once; the queue manager evaluates every active subscription; each match produces a put to a destination queue. Subscriber applications keep using MQGET—they rarely read the topic directly. DEFINE SUB (or application-defined dynamic subs) records the topic pattern, durability, destination queue, and scope. This tutorial explains subscription objects, managed versus unmanaged destinations, durable behavior, wildcards, SUBID and sub name, cluster propagation, capacity planning when fan-out grows, and administration commands beginners use daily.

How a Subscription Routes Messages

When a publication arrives with topic string retail/order/shipped, the pub/sub engine compares it to each subscription TOPICSTR. Sub A might be retail/order/shipped exactly; Sub B might be retail/order/#; both match. Sub C on retail/customer/# does not. For each match, MQ enqueues a new message on DEST. Persistence, expiry, and message size follow publish options and queue attributes—fan-out multiplies disk and CPU when ten subscribers match a large persistent payload.

Explainer: Managed Subscriptions

In JMS, Session.createDurableSubscriber often results in a managed subscription: the queue manager creates a system queue name and tracks it. Administrators see DISPLAY SUB(*) with DEST names they did not define manually. Unmanaged subscriptions suit MQI shops that want fixed queue names like AUDIT.FINANCE.SUB1 for monitoring and backup. DEST must exist (or be auto-created per options) before publications flow; starting the subscriber app without a sub definition yields silence.

Durable vs Non-Durable

Durable subscriptions (DURSUB YES) support applications that disconnect overnight but must not miss events—inventory sync, compliance audit. The queue manager retains the subscription record; messages accumulate on DEST while the app is down, subject to queue MAXDEPTH. Non-durable fits ephemeral UI clients that only care about live ticks. Administrative DEFINE SUB with DURSUB YES is common for server-side consumers; client SDKs may create dynamic non-durable subs. After queue manager restart, durable admin subs reload from the repository; verify your platform behavior for API-created subs in release notes.

Wildcards in Subscriptions

• + matches exactly one topic level: finance/+/done matches finance/payment/done.
• # matches zero or more trailing levels: finance/# matches finance/payment and finance/payment/done.
• Overlapping subs both receive copies if both match—deduplication is not automatic.
• Design teams document allowed wildcard breadth to avoid accidental enterprise-wide taps.

Cluster Subscriptions

In clusters, subscriptions may propagate so publications on QM_A reach a subscriber on QM_B. SUBSCOPE and cluster topic definitions must align. Troubleshooting cluster pub/sub often starts with DISPLAY SUB on both queue managers and verifying cluster topic TOPTYPE CLUS. Network partitions can leave stale subscription knowledge until REFRESH CLUSTER or repository recovery.

Tutorial: Administrative Subscription

1
2
3
4
5
6
7
8
9
DEFINE QLOCAL('AUDIT.RETAIL.SUB') REPLACE MAXDEPTH(500000) DEFPSIST(YES)
DEFINE SUB('AUDIT.RETAIL.ORDERS') REPLACE +
  TOPICSTR('retail/order/#') DEST('AUDIT.RETAIL.SUB') +
  DESTTYPE(QUEUE) DURSUB(YES) SUBTYPE(ADMIN) +
  DESCR('Audit all retail order events')
DISPLAY SUB('AUDIT.RETAIL.ORDERS')
* Publish test message to retail/order/created
* DISPLAY QLOCAL('AUDIT.RETAIL.SUB') CURDEPTH
* Consumer: amqsget AUDIT.RETAIL.SUB QM1

Monitoring and Capacity

Each matching subscription adds one queue put per publish. Ten subs on a high-rate topic means ten times disk I/O for persistent messages. Alert on DEST CURDEPTH, not only publisher health. DISPLAY SUBSTATUS shows runtime state for active subs. Remove obsolete subs—orphan subs waste resources and may violate data retention policy if DEST queues fill with regulated data nobody consumes.

Explain Like I'm Five: Subscriptions

The ice cream truck plays a song (publish). Kids who signed up on the club list (subscription) get a text telling them to come to their driveway (destination queue). Kids not on the list do not get a text. Durable means your name stays on the list even when you are at school; non-durable means they erase your name when you go inside.

Practice Exercises

Exercise 1

Three teams need retail/order/#, retail/customer/#, and retail/order/shipped only. Design three DEFINE SUB commands with DEST queues.

Exercise 2

DEST queue hits MAXDEPTH. What happens to new publications for that subscription?

Exercise 3

Compare operational steps to migrate a subscriber from non-durable to durable without losing the topic pattern.

Frequently Asked Questions

Test Your Knowledge