Transactions

Transactions are how IBM MQ groups messaging work into all-or-nothing steps. Put ten messages and a database row update, then commit once—either everything succeeds or nothing does. Roll back after a validation error and the messages you put under that unit of work never appear on the queue for others to consume. On z/OS, CICS and IMS tasks often end with SYNCPOINT that includes MQ; on distributed systems, Java and .NET applications use XA transaction managers with MQ as a resource manager. Beginners confuse transactions with exactly-once delivery; transactions give atomicity within one boundary, while at-least-once redelivery still applies across failures between separate units of work. This page covers local units of work, MQCMIT and MQBACK, MQGMO_SYNCPOINT and MQPMO_SYNCPOINT, global two-phase commit, CICS integration, performance implications, and runbook cues when transactions hang in-doubt.

Unit of Work Basics

A unit of work (UoW) begins implicitly with the first syncpointable call or explicitly with MQBEGIN on some platforms. Every put, get, or publish under that UoW is provisional until commit. Other applications generally do not consume messages you got under syncpoint until you commit—the message is locked for your UoW. Multiple puts in one UoW commit together, which batch jobs use to reduce commit overhead. The companion tutorial on units of work goes deeper into boundaries; here we focus on commit protocols and coordination.

Put Options: MQPMO_SYNCPOINT

When MQPMO_SYNCPOINT is set on MQPUT, the message is not visible to other applications until the putting application commits (subject to queue and share options). If the application backs out, the message vanishes from the queue as if the put never happened for consumers. Combine with persistent messages so that after commit the message survives restart. Without syncpoint on put, the message may be visible immediately after the put completes—simpler but harder to coordinate with a database insert in the same business action.

Get Options: MQGMO_SYNCPOINT

MQGMO_SYNCPOINT on MQGET includes the removal of the message in the UoW. Process, validate, update Db2, then MQCMIT. Failure triggers MQBACK and the message remains for retry—foundation of at-least-once consumers. MQGMO_NO_SYNCPOINT removes the message immediately when the get succeeds (platform and option details in your Application Programming Reference)—dangerous for business data if you process after get without another safety net.

Local vs Global Transactions

A local transaction involves only the queue manager: MQCMIT commits MQ work alone. A global transaction enrolls MQ with a transaction manager (IBM MQ with supported XA bindings, application servers, or CICS). Phase one prepares; phase two commits or rolls back all participants. If the database commits but MQ rolls back due to a failure, you avoid orphan rows without messages—the reason banks use global transactions for transfer flows. Global transactions cost more latency and require tuning in-doubt transaction resolution when a participant crashes mid-commit.

CICS and IMS on z/OS

CICS applications using the MQ API or EXEC CICS LINK to MQ adapters often run under the task syncpoint. A successful task end commits MQ and VSAM or Db2 updates together. HANDLE CONDITION and transaction routing errors can leave messages needing operational review. IMS OTMA and similar interfaces also coordinate syncpoint with message processing. Mainframe developers should read their region's transaction definitions and whether implicit syncpoint on return applies to every path including abends.

In-Doubt Transactions

After a failure during two-phase commit, a transaction can be in-doubt—MQ unsure whether the global decision was commit or rollback. Administrators use PCF commands and transaction manager consoles to resolve. Depth on queues may look frozen; channels can stall. Runbooks document who may force commit or rollback and when. Never force without understanding business impact on paired database work.

Performance and Batch Sizing

• One commit per thousand small puts reduces sync overhead versus per-message commit.
• Long UoW holds locks and increases depth visibility delay for other consumers.
• Log fill rate rises with large committed batches of persistent messages.
• Global transactions add prepare/commit round trips—use only where needed.

Tutorial: Conceptual CICS and Distributed Flow

1
2
3
4
5
6
7
8
9
10
Distributed (conceptual):
  begin XA transaction
  MQPUT ORDERS.IN with SYNCPOINT + DB insert ORDERS table
  commit XA -> both visible
 
CICS (conceptual):
  EXEC CICS MQGET ... SYNCPOINT
  update VSAM or Db2
  EXEC CICS SYNCPOINT  -> commits task including MQ
  on error EXEC CICS SYNCPOINT ROLLBACK

Explain Like I'm Five: Transactions

You put three toys in a box and write a note on the chalkboard. You are allowed to say done only when both the toys and the note are ready. If you spill juice on the note, you undo everything—toys back on the shelf, chalkboard erased—and start over. Commit is saying done for real; rollback is oops, pretend this never happened.

Practice Exercises

Exercise 1: Rollback Effect

Under syncpoint, put three messages then MQBACK. What does CURDEPTH show? What do other consumers see?

Exercise 2: Global vs Local

List a flow that needs XA and one that can use local MQ-only commit.

Exercise 3: In-Doubt

Channel partner sees message; database team says no row. What transaction states do you investigate first?

Frequently Asked Questions

Test Your Knowledge