Rollback is how IBM MQ undoes work that should never have become permanent. When validation fails, the database throws an error, or the business rule rejects an order, MQBACK ends the unit of work and reverses syncpointed puts and gets. The message you got under syncpoint reappears for another attempt; the payment notification you put under syncpoint vanishes. Operators learn rollback through poison messages—applications that always MQBACK on bad JSON until BackoutCount exceeds BACKOUTTHRESH and the queue manager routes to a dead-letter queue. This tutorial explains MQBACK, backout count mechanics, poison handling strategies, CICS SYNCPOINT ROLLBACK, rollback versus disconnect, partial failure in batch, and how rollback enables at-least-once delivery instead of silent loss.
MQBACK(Hconn, &compCode, &reason) rolls back the current UOW on that connection. All MQPMO_SYNCPOINT puts since last commit disappear from queues. All MQGMO_SYNCPOINT gets since last commit are reversed—messages return with increased backout count. A new UOW begins for subsequent operations. Call MQBACK in catch blocks after logging the failure reason.
123456if (processing_failed) { MQBACK(Hconn, &compCode, &reason); /* message from syncpoint get is visible again */ } else { MQCMIT(Hconn, &compCode, &reason); }
| Operation in UOW | After MQBACK |
|---|---|
| Syncpoint put | Message removed (never visible) |
| Syncpoint get | Message restored to queue |
| NO_SYNCPOINT put | Not in UOW — already committed |
| Committed prior UOW | Unchanged |
Rollback is crumpling every draft on the clerk desk and putting the retrieved letter back in the mailbox slot for someone else to try.
Each rollback after a syncpoint get increments BackoutCount on that message copy. DEFINE QLOCAL BACKOUTTHRESH(3) means after three rollbacks the queue manager may move the message to BOTHQ or DLQ per configuration. This protects infinite loops where bad data never commits. Handlers should detect high backout and skip to error queue without exhausting threshold when possible.
Blind MQBACK on every failure without cap creates poison loop until threshold—acceptable only when data might become valid later.
EXEC CICS SYNCPOINT ROLLBACK backs out MQ and other recoverable resources in the task. Use when ABEND handlers or business failure require full task undo. Understand what is not recoverable—some external HTTP calls cannot roll back.
MQDISC without commit often rolls back open UOW—similar outcome but less controlled than explicit MQBACK. Prefer explicit rollback in application error paths for clear logs. Kill -9 on process may leave indoubt XA states—different recovery path.
After rollback, another consumer may process the same message—design idempotent database updates (natural keys, status checks). At-least-once delivery depends on rollback returning messages to the queue when processing fails before commit.
DISPLAY QLOCAL CURDEPTH and DLQ depth rising together suggests poison traffic. Inspect MQMD backout count in DLQ browser. Fix producer schema or consumer code. Requeue to input after fix. Document whether rollback was application MQBACK or channel error—different tools.
Rollback is undo in a video game when you fall in lava—the level goes back to before you jumped, and you can try again.
Trace backout count from 0 to BACKOUTTHRESH+1 for a failing consumer.
Design error path that avoids infinite MQBACK on invalid XML.
Compare MQBACK versus moving message to ERROR.Q with commit.
1. MQBACK undoes:
2. After rollback of syncpointed get:
3. BackoutCount increases when:
4. BACKOUTTHRESH on queue: