Retained publications answer a narrow but important question: “What is the current value?” A new subscriber to inventory/warehouse/door3/status should not wait for the next physical door toggle to know whether the door is open—the last retained publication already says OPEN or CLOSED. IBM MQ retain semantics (controlled by publish options and topic attributes per your release documentation) store the latest message for a topic context and deliver it when matching subscriptions become active, distinct from durable subscriptions that queue every event published while offline. Confusing retain with durability leads teams to retain high-frequency trading ticks and wonder why memory grows, or to use durable subs for status flags and store millions of duplicate “CLOSED” messages. This tutorial explains when retain fits, how publishers set retain flags in MQI and JMS, interaction with wildcards, clearing stale retain, security implications, and comparison tables versus durable subs and persistent queues.
Durable subscription: every matching publish while the sub exists (or existed) copies to DEST—full stream. Retain: typically one latest message replayed to new interest—not a replay of history. Choose retain for state snapshots; choose durable for event logs. You may combine them: durable sub drains all changes; retain gives instant state to brand-new consumers before the next change.
| Pattern | What is kept | New subscriber gets |
|---|---|---|
| Ordinary publish | Nothing on topic | Only future publishes |
| Retained publish | Last retained message | Last retained then future |
| Durable sub (offline) | Queue depth on DEST | Backlog on DEST when up |
MQI sets retain in the publish message descriptor or put message options per IBM definitions—often PMO or MD fields documented as retain support for topics. JMS may expose setRetain or delivery mode variants—verify your client library. A retain publish with empty body can clear previous retained content on some configurations—test in lab before automating “delete status” patterns.
123456* Administrative topic may influence retain behavior — see DEFINE TOPIC attrs * Application publish with retain flag set in API (not shown in pure MQSC) DEFINE TOPIC('PLANT.LINE1.STATUS') TOPSTR('plant/line1/status') TOPTYPE(LOCAL) DEFINE SUB('SUB.STATUS.MONITOR') TOPICSTR('plant/line1/status') + DEST('STATUS.MONITOR.Q') DURSUB(YES) * First subscriber after retain publish should receive last status without waiting
Inappropriate: order/created at 5000 per second, audit events, anything requiring legally complete history—use durable queues and archival systems instead.
Retain applies to specific topic strings. Subscriptions with + or # receive retained messages when they match the retained topic node per IBM matching rules—understand which level in the tree holds retention before designing wildcards. A retain on plant/# semantics differs from plant/line1/status—read release notes for tree behavior.
A retained “LINE RUNNING” message after emergency stop is dangerous—procedures must publish retained STOP or clear retain during incidents. Include retain topics in runbooks beside DLQ and channel restarts. DISPLAY commands for pub/sub status on your release show retained message presence—consult IBM docs for exact command names (e.g. DISPLAY TPSTATUS variants).
Retain is a whiteboard in the hallway showing today’s lunch menu. New students read it when they arrive. It is not a filing cabinet of every lunch menu ever (durable history).
The teacher leaves the latest homework assignment written on the board so kids who come late still know what to do, even if they missed the announcement.
Choose retain, durable, or neither: door sensor, order feed, config version.
Describe how to clear a wrong retained “SYSTEM OK” after outage.
Why is retain dangerous on finance/payment/#?
1. Retain typically keeps:
2. Late joiner benefit:
3. Retain is poor fit for:
4. Durable sub offline gets: