Topic objects are the administrative face of IBM MQ publish/subscribe. While applications can publish raw strings, operations teams catalog events as DEFINE TOPIC names—FIN.PAYMENT.POSTED with TOPSTR('finance/payment/posted')—so DISPLAY TOPIC, change control, and security profiles have stable handles. Each TOPIC object carries attributes that influence cluster routing, who may publish or subscribe under a branch, whether definitions act as administrative parents in the topic tree, and how aliases redirect old names to new hierarchies during migrations. This page is a reference-depth companion to the Topics tutorial: attribute by attribute, what to set in lab versus production, how TOPTYPE choices change propagation, and how topic objects interact with subscriptions without duplicating general pub/sub introductions.
DEFINE TOPIC('NAME') creates the object. TOPSTR names the canonical string—slashes define levels. DESCR documents owner and schema version for humans. REPLACE allows scripted redeploy. Cluster name on cluster topics ties to the cluster repository. Wrong TOPSTR spelling strands publishers and subscribers on different logical subjects with silent non-delivery.
| Attribute | Purpose | Beginner note |
|---|---|---|
| TOPSTR | Hierarchical subject path | Must align with enterprise naming standard |
| TOPTYPE | LOCAL, CLUS, or ALIAS behavior | CLUS for multi-QM; ALIAS for rename |
| TOPICSTR | On ALIAS: target topic string or object | Indirection target—verify chain |
| PUBSCOPE | Where publishes from this branch propagate | Cluster designs—read IBM table |
| SUBSCOPE | Where subscriptions may attach | Pair with SUB SUBSCOPE |
| MDUR | Model durability hints for tree | Affects default sub durability context |
| DEFPRTY | Default publication priority | Inherited by apps if not overridden |
LOCAL topics anchor a branch on the queue manager where they are defined. Publications to strings under the branch route to matching subscriptions on that manager unless cluster or stream configuration extends reach. Use LOCAL for single-QM estates or leaf topics in a tree where cluster routing is handled higher up by a CLUS parent topic.
Cluster topics publish routing information to full and partial repositories so remote queue managers learn how to forward publications and subscriptions. A missing or misspelled CLUSTER attribute on the topic or queue manager cluster membership prevents fan-out—symptom: works on publishing QM only. Test with DISPLAY CLUSQMGR and cluster topic status commands on your release after DEFINE.
ALIAS topics let you retire legacy object names while pointing to new TOPSTR—applications open FIN.PAYMENT.V2 alias while strings consolidate under finance/payment/v2. Chain aliases carefully; loops are invalid. Authority on alias and target must allow intended publishers.
123456DEFINE TOPIC('FIN.PAYMENT.BRANCH') TOPSTR('finance/payment') + TOPTYPE(LOCAL) DESCR('Payment events root') DEFINE TOPIC('FIN.PAYMENT.POSTED') TOPSTR('finance/payment/posted') TOPTYPE(LOCAL) DEFINE TOPIC('FIN.PAYMENT.LEGACY') TOPTYPE(ALIAS) + TOPICSTR('finance/payment/posted') DESCR('Old name → new string') DISPLAY TOPIC('FIN.PAYMENT.BRANCH')
Parent topics in the tree can define defaults for child strings—administrative topic objects shape wildcard authority inheritance and proxy behavior per IBM documentation. Planning the tree top-down (domain → entity → event) beats defining hundreds of flat leaves without parents. Administrative objects often carry no publishers themselves—they structure the namespace.
setmqaut -t topic -n 'finance/payment/#' +pub grants publish on a branch. Topic object names can also appear in authority commands depending on platform—verify whether your site uses string or object profile naming. Align TOPIC object change control with RACF or LDAP groups that own the business domain.
ALTER TOPIC changes TOPSTR only with impact analysis—subscriptions and publishers using old strings stop matching. Prefer ALIAS during migration windows. DISPLAY TOPIC(*) audits catalog drift. Export MQSC with SAVE CONTEXT or your pipeline tool before bulk changes.
The topic object is the card in the catalog drawer (FIN.PAYMENT.POSTED). The topic string is the shelf location code (finance/payment/posted). Readers and writers can use either if the catalog is kept current.
A topic object is a nickname tag on a folder in a filing cabinet—the nickname helps grown-ups find the folder, but the real address is still written on the folder tab (topic string).
Define LOCAL branch topic plus two leaf topics under retail/order/.
When would you use ALIAS instead of ALTER TOPSTR?
List DISPLAY commands to verify cluster topic propagation.
1. TOPSTR on DEFINE TOPIC sets:
2. TOPTYPE CLUS is for:
3. ALIAS topic allows:
4. Messages are stored on: