Creating Subscriptions

Creating a subscription is how a consumer tells the IBM MQ queue manager which events it wants and where to deliver them. Without a subscription, publish returns success but no copy is queued—beginners often debug publishers for hours while the gap is simply no DEFINE SUB. Subscriptions can be permanent administrative objects (DEFINE SUB in MQSC), application-created dynamic subscriptions (MQSUB in MQI, createDurableSubscriber in JMS), or hybrid patterns where DevOps defines the DEST queue and applications register interest at startup. This tutorial walks through prerequisites, DEFINE SUB attribute by attribute, managed versus unmanaged destinations, durable flags, topic object versus TOPICSTR, authority checks, verifying delivery, deleting and altering subs, and cluster considerations at create time. Pair this page with subscription scopes for SUBSCOPE and with managed subscriptions for JMS-heavy estates.

Before You Define: Checklist

1. Destination queue exists (UNMANAGED) or you accept MANAGED auto-create.
2. Subscriber application MCAUSER or connection has MQGET on DEST and +sub on topic prefix.
3. Publisher topic string matches TOPICSTR or wildcard pattern—hierarchy documented.
4. Queue manager pub/sub enabled; on z/OS verify appropriate subsystem settings per your environment.
5. For cluster, SUBSCOPE and cluster topic parents defined—see clustered topics tutorial.

DEFINE SUB Core Attributes

Step-by-Step: Unmanaged Durable Subscription

1
2
3
4
5
6
7
8
9
10
11
DEFINE QLOCAL('INVENTORY.UPDATES.Q') REPLACE +
  DESCR('Subscriber queue for item updates') MAXDEPTH(50000) MAXMSGL(4194304)
DEFINE SUB('INVENTORY.UPDATES.SUB') REPLACE +
  TOPICSTR('prod/inventory/item/#') DESTQL('INVENTORY.UPDATES.Q') +
  DESTQMGR('QM1') DESTTYPE(UNMANAGED) DURSUB(YES) +
  SUBSCOPE(QMGR) DESCR('All prod inventory item events')
ALTER AUTHREC PROFILE('prod/inventory/item/#') OBJTYPE(TOPIC) +
  PRINCIPAL('invapp') AUTHADD(SUB)
ALTER AUTHREC PROFILE('INVENTORY.UPDATES.Q') OBJTYPE(QUEUE) +
  PRINCIPAL('invapp') AUTHADD(GET)
DISPLAY SUB('INVENTORY.UPDATES.SUB') ALL

REPLACE on DEFINE SUB allows redeploy scripts to run twice. After define, start publisher test with matching prod/inventory/item/price/changed string; MQGET from INVENTORY.UPDATES.Q should return a message. If not, DISPLAY SUB and compare TOPICSTR character by character to publish log.

Using TOPICOBJ Instead of TOPICSTR

DEFINE SUB('FIN.PAY.SUB') TOPICOBJ('FIN.PAYMENT.POSTED') DESTQL('FIN.PAY.Q') ... binds to whatever TOPSTR is on FIN.PAYMENT.POSTED today. Central teams love this for catalog-driven ops; integration teams fear silent breakage when TOPSTR changes. Document whether partners must use object names or literal strings in contracts.

Application-Defined Dynamic Subscriptions

MQI MQSUB and JMS createSubscription can register interest without prior DEFINE SUB in MQSC. The queue manager assigns SUBID and may create MANAGED DEST queues with system-generated names—DISPLAY SUB(*) after app start reveals them. Dynamic subs suit microservices; mainframe batch often prefers fixed SUBNAME in MQSC for audit. Non-durable dynamic subs disappear when the application disconnects unless configured otherwise.

DURSUB: Durable vs Non-Durable at Create Time

DURSUB(YES) keeps the subscription across application disconnect and typically queue manager restart—publications queue on DEST while offline subject to persistent message settings. DURSUB(NO) suits temporary monitoring sessions. Do not confuse durability with message persistence: a durable sub can still receive non-persistent publications that vanish on restart. See durable subscriptions tutorial for retain interaction.

Explainer: Mailing List Sign-Up

Creating a subscription is signing up for a mailing list about a subject (topic). You give your mailbox address (DEST queue). The post office (queue manager) drops a copy of every matching letter into your box. No sign-up, no letters—even if senders think they mailed you.

ALTER and DELETE

ALTER SUB changes TOPICSTR, DEST, or durability—impact running consumers. Changing TOPICSTR mid-flight may leave messages on DEST from old pattern while new events use new pattern; plan drain and cutover. DELETE SUB removes registration; MANAGED DEST may be deleted per rules—verify before delete in production. Use DISPLAY SUB STATUS commands on your release to see consumer connection state.

Verification Commands

• DISPLAY SUB('name') ALL — attributes.
• DISPLAY QLOCAL('DEST') CURDEPTH — messages arriving.
• DISPLAY TPSTATUS or topic status — active publishers on string.
• Application log — publish topic string emitted.

Common Creation Errors

• 2035 not authorized on topic or queue—fix OAM before re-test.
• DESTQMGR wrong on multi-QM complex—messages route elsewhere.
• Wildcard typo: finance/#/payment invalid; # must be last.
• FORGOT DURSUB(YES) for overnight batch—miss messages published while down.

Explain Like I'm Five: Creating Subscriptions

You tell the mail carrier: “whenever someone talks about puppies, put a copy in my blue mailbox.” Creating the subscription is writing that rule down. The blue mailbox must exist, and you need permission to read it.

Practice Exercises

Exercise 1

Write full MQSC for QLOCAL, DEFINE SUB exact topic, and AUTHREC stubs.

Exercise 2

Compare TOPICSTR versus TOPICOBJ for a payment posted event—pros and cons.

Exercise 3

Publisher sends prod/retail/order/created; sub is prod/retail/+/created—will it match?

Frequently Asked Questions

Test Your Knowledge