Units of Work

A unit of work is the invisible fence around a batch of IBM MQ operations that must succeed or fail together. Until you commit that fence, your puts might be hidden and your gets might hold messages hostage for other consumers. Mis-sized units of work—too small and you burn CPU on commits; too large and you block queues and risk long recovery—are a common tuning problem in both distributed MQ and z/OS CICS regions. This page defines when a UoW starts and ends, how syncpoint options enroll puts and gets, how implicit boundaries differ from MQBEGIN, how global transaction managers extend the fence across Db2, how batch jobs choose commit intervals, and what operators see when a UoW never completes.

What Belongs Inside One Unit of Work

Any call with syncpoint participation joins the current UoW: typically MQPUT with MQPMO_SYNCPOINT, MQGET with MQGMO_SYNCPOINT, and some publish/subscribe operations depending on options. Calls without syncpoint may take effect immediately outside the fence—useful for read-only probes but dangerous if mixed carelessly with coordinated database updates. Architects draw sequence diagrams with a shaded box labeled UoW around the messaging and database steps that must align.

Implicit vs Explicit Boundaries

Many client programs use an implicit UoW per thread: commit at the end of processing each message or each batch. MQBEGIN makes boundaries explicit where the MQI supports it—helpful when one connection serves multiple unrelated business actions and you must not commit them together. CICS often uses the task as the boundary: everything between task start and EXEC CICS SYNCPOINT is one UoW unless you split with additional syncpoints. Splitting syncpoints inside a CICS task commits MQ work mid-task—only do that when requirements demand partial progress.

Multiple Queues, One Fence

A payment flow might put to AUDIT.LOG, update BALANCE.QUEUE, and publish to PAYMENTS.TOPIC in one UoW before commit. If any step fails and you MQBACK, none of the partial effects remain for other applications. That atomicity is powerful but increases lock duration on all touched queues. Design smaller UoWs when queues are independent; enlarge UoWs when business rules require strict coupling.

Global Units of Work (XA)

The transaction manager owns the logical UoW; MQ is a participant. Prepare phase asks each resource if it can commit; commit phase finalizes. The application may call fewer explicit MQCMIT APIs because the manager drives completion—still understand what is inside the fence. In-doubt state means the global UoW outcome was not recorded everywhere; resolution is operational, not automatic retry.

Sizing Commits for Batch

1. Estimate messages per second and acceptable recovery replay window.
2. Choose batch size so one UoW commits every N messages or every T seconds.
3. On failure, identify whether the whole batch rolls back or you use checkpoint files outside MQ.
4. Monitor log utilization—large persistent batches expand log before commit.

Interaction with Persistence

Persistent messages enrolled in a UoW are logged as part of commit. Non-persistent messages in a UoW can still roll back before commit, but after commit they remain vulnerable to crash like any non-persistent message. Do not confuse UoW atomicity with restart durability—persistence answers survival after queue manager restart; UoW answers visibility before commit.

z/OS Queue Sharing Groups

In a queue sharing group, UoW and syncpoint semantics still apply; coupling facility structures hold shared queue data. Failed members and structure recovery can affect in-flight UoW—operations follow IBM recovery guides. Beginners on QSG should pair this tutorial with queue sharing documentation when planning commit frequency on shared queues.

Tutorial: Batch Loop with UoW Boundaries

1
2
3
4
5
6
7
8
9
10
11
12
13
14
Batch producer pseudocode:
  for each group of 100 records:
    start UoW (implicit or MQBEGIN)
    for each record in group:
      MQPUT PAYMENTS.IN with SYNCPOINT
    MQCMIT
  on error:
    MQBACK  -> entire group of 100 puts undone
 
Consumer pseudocode:
  start UoW
  MQGET with SYNCPOINT
  process one message
  MQCMIT   -> one message per UoW = smaller fence, more commits

Explain Like I'm Five: Units of Work

You are packing three lunches in one bag. You do not hand the bag to the bus driver until all three lunches are inside. If you forget the juice box, you empty the whole bag and start packing again—that is one unit of work. Commit is handing over the full bag; rollback is emptying it because something was wrong.

Practice Exercises

Exercise 1: Size the UoW

10,000 msgs/sec, max 2 seconds of replay acceptable. Propose commit batch size and justify.

Exercise 2: CICS Task

Task does two MQGETs and one SYNCPOINT at end. When is the UoW committed? What if the task abends before SYNCPOINT?

Exercise 3: Mixed Options

Put A uses SYNCPOINT; put B does not. Can one MQBACK undo both? Explain visibility.

Frequently Asked Questions

Test Your Knowledge