Put Message Options (MQPMO) tell IBM MQ how each MQPUT should behave beyond the raw bytes in MQMD. The same queue and descriptor can participate in a transaction or auto-commit immediately; can receive a queue-manager-generated MsgId or preserve one you supply; can pass identity context for audit or hide the real user; can respect logical message grouping for segmented payloads. Beginners often ignore MQPMO and use MQPMO_DEFAULT, then wonder why messages roll back on disconnect or why duplicates appear after retry. Operations teams debugging syncpoint hangs start with whether producers used MQPMO_SYNCPOINT without matching MQCMIT. This tutorial explains initializing MQPMO, combining option flags, syncpoint interaction with databases, identity and authority context options, NEW_MSG_ID and NEW_CORREL_ID, logical order and grouping, quiesce and fail options, MQPUT1, and comparison tables against MQGMO for symmetric get behavior.
Start with MQPMO_DEFAULT before each put in loops—reusing a structure from a previous put can leave stale Options bits. Set Options field by OR-ing MQ constants. Version field must match structure level expected by your client library version.
12345678MQPMO pmo = {MQPMO_DEFAULT}; pmo.Options = MQPMO_NO_SYNCPOINT | MQPMO_NEW_MSG_ID | MQPMO_NEW_CORREL_ID | MQPMO_FAIL_IF_QUIESCING; MQPUT(Hconn, Hobj, &md, &pmo, buflen, buffer, &compCode, &reason);
| Option | Effect | Contrast |
|---|---|---|
| MQPMO_SYNCPOINT | Put under current UOW | Versus NO_SYNCPOINT immediate commit path |
| MQPMO_NO_SYNCPOINT | Put outside syncpoint when allowed | Default for many fire-and-forget apps |
| MQPMO_NEW_MSG_ID | QM assigns MsgId | Omit if app sets unique MsgId |
| MQPMO_NEW_CORREL_ID | QM assigns CorrelId | Request/reply often sets CorrelId manually |
| MQPMO_SET_IDENTITY_CONTEXT | Pass user identity in MD | Needs authority; audited |
| MQPMO_PASS_IDENTITY_CONTEXT | Propagate context from message | Used in forwarding chains |
| MQPMO_LOGICAL_ORDER | Group segments in order | Advanced segmented messages |
| MQPMO_FAIL_IF_QUIESCING | Fail put during quiesce | Pair with consumer FAIL_IF_QUIESCING |
MQPMO_SYNCPOINT enrolls the put in the connection's unit of work. Until MQCMIT, other consumers typically do not see the message (visibility rules per platform and get options). MQBACK removes the put. Database + MQ single UOW requires XA or container-managed transactions—plain SYNCPOINT without coordination still helps all-MQ batch steps. Mixed NO_SYNCPOINT puts and SYNCPOINT puts in one program require clear design—accidental auto-commit of half the steps breaks atomicity.
MQPMO is instructions to the clerk: put this letter in the pending tray until the manager approves the batch (SYNCPOINT), assign a tracking number automatically (NEW_MSG_ID), or refuse new letters if the office is closing (FAIL_IF_QUIESCING).
SET_IDENTITY_CONTEXT writes UserIdentifier and related MQMD fields from the putting application when permitted—useful when a gateway represents many users. PASS_IDENTITY_CONTEXT forwards context from an incoming message to an outbound put. Authority checks prevent spoofing. Wrong use causes 2035 or messages attributed to wrong audit user.
Large payloads split into multiple puts with MQMF_MSG_IN_GROUP and MQMF_LAST_MSG_IN_GROUP in MsgFlags (MQMD), combined with MQPMO_LOGICAL_ORDER so the queue manager preserves order within the group. Middleware and file transfer scenarios use this; simple JSON producers rarely need it. Misconfigured flags produce partial messages consumers cannot reassemble.
MQPUT1 opens implicitly, puts once, closes—same MQPMO. Useful for stateless HTTP handlers that cannot hold Hobj across requests. Overhead of repeated open per message may matter at extreme throughput—benchmark versus long-lived Hobj.
NEW_MSG_ID clears application-supplied MsgId and replaces after put—read back MsgId from MQMD output. Persistence and Priority remain in MQMD, not PMO. Report and feed back options cross both structures for advanced COA/COD—see IBM reference for Report field in MQMD with PMO report flags on some APIs.
MQPMO is telling the mail clerk whether to wait for your parent to say okay before mailing (syncpoint), or to mail right away.
Design a two-put batch: both SYNCPOINT, one CMIT—what happens on BACK after first put only?
When would you omit NEW_MSG_ID?
Add FAIL_IF_QUIESCING to producer shutdown story during endmqm.
1. MQPMO_SYNCPOINT means:
2. MQPMO_NEW_MSG_ID:
3. NO_SYNCPOINT on put:
4. FAIL_IF_QUIESCING helps: