MQPUT

MQPUT is how application data enters IBM MQ: invoices, JSON events, COBOL copybooks, or flat files become messages on a queue with descriptors the queue manager stores until a consumer MQGETs them or a channel forwards them to a partner site. The call requires Hconn from MQCONN, Hobj from MQOPEN with output intent, a message descriptor (MQMD) carrying format and identity, a put message options structure (MQPMO) controlling syncpoint and context, and a buffer with length. One successful put does not mean the remote partner processed the work—it means the queue manager accepted responsibility according to persistence and syncpoint rules. Beginners confuse 2035 authority with 2053 queue full and 2014 wrong open options; this tutorial separates those failures, explains header fields beginners must set, compares persistent versus non-persistent puts, documents logical message grouping, and shows request/reply patterns using ReplyToQ and MsgId/CorrelId pairing.

Message Descriptor (MQMD) Essentials

MQMD is metadata about the payload, not the business data itself. Format (MQFMT_STRING, MQFMT_NONE, or custom) tells receivers how to interpret bytes. MsgId uniquely identifies the message—MQPMO_NEW_MSG_ID lets the queue manager generate one. CorrelId links replies to requests when the consumer copies request MsgId into reply CorrelId. Expiry limits lifetime in milliseconds—zero often means no expiry per platform defaults. Priority influences order only when multiple messages wait and the queue is not FIFO-strict in all configurations. Encoding and CodedCharSetId matter for EBCDIC mainframe to ASCII Linux conversion—wrong values produce mojibake without failing the put.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
MQMD md = {MQMD_DEFAULT};
MQPMO pmo = {MQPMO_DEFAULT};
char buffer[] = "ORDER 12345";
MQLONG buflen = (MQLONG)strlen(buffer);
 
md.Format[0] = MQFMT_STRING;
memcpy(md.Format, MQFMT_STRING, (size_t)MQ_FORMAT_LENGTH);
pmo.Options = MQPMO_NO_SYNCPOINT | MQPMO_NEW_MSG_ID;
 
MQPUT(Hconn, Hobj, &md, &pmo, buflen, buffer, &compCode, &reason);
 
if (compCode != MQCC_OK) {
  /* 2053 full, 2035 auth, 2014 wrong open */
}

Persistence: MQPER_PERSISTENT vs MQPER_NOT_PERSISTENT

Persistent messages are logged to disk (subject to queue DEFPSIST and put persistence). They survive queue manager restart at the cost of I/O. Non-persistent messages are faster but may be lost if the queue manager stops abruptly—acceptable for high-volume telemetry where loss is tolerable. Default persistence may come from queue DEFPSIST(YES) when MQMD does not override. Compare at-least-once business requirements: payments need persistence; ephemeral metrics may not.

Explainer: Dropping a Letter in the Slot

MQPUT is sliding your letter into the mailbox slot you unlocked with MQOPEN. The envelope label (MQMD) says who it is for and whether the post office must keep a copy in a safe if the building loses power (persistent).

Transactional Puts

Under MQPMO_SYNCPOINT, the message is invisible to other applications until commit. Pair database SQL and MQPUT in one unit of work using XA or coordinated transaction managers where supported. MQBACK rolls back puts since the last syncpoint. A common bug is MQPUT with NO_SYNCPOINT while database rolls back—orphan messages or missing messages result. COBOL and Java EE have different boilerplate but same semantics.

Request/Reply Pattern

Set ReplyToQ and ReplyToQMgr in MQMD so the server knows where to MQPUT the answer. Server copies request MsgId into reply CorrelId. Client MQGET on reply queue with MQGMO_MATCH_CORREL_ID. Temporary dynamic reply queues use model queue open pattern on client side. Document queue names in API contracts—hard-coded strings break across environments unless externalized.

Large Messages and Fragments

When payload exceeds one buffer, applications may use MQPUT with multiple buffers or message segmentation features per IBM documentation for your version. MAXMSGL on queue and channel caps single message size—raising limits has operational impact on memory and channel batching. Consider sending a reference in the message body (file path, S3 key) instead of multi-megabyte MQPUT for some architectures.

Put to Topic (Publish)

Publish APIs ultimately put publication data to topic infrastructure. MQPUT on alias topic or MQ publish calls set different MD fields. Subscribers receive copies per subscription durability. Distinct from point-to-point QLOCAL depth but MQMD concepts overlap.

Reason Codes on Put

• 2053 — queue full; scale consumers or increase MAXDEPTH temporarily.
• 2035 — not authorized; check OAM put on profile.
• 2014 — open options incompatible with put.
• 2110 — message too big for queue MAXMSGL.
• 2195 — object type does not support put (wrong queue type).

Monitoring Producer Health

Operators watch CURDEPTH rising, age of oldest message, and channel XMITQ depth for remote targets. Application metrics: put rate, put failure count by reason. Alert on sustained 2053. Idempotent consumers handle duplicate puts when producers retry after ambiguous failures.

Explain Like I'm Five: MQPUT

MQPUT is putting your drawing into the classroom turn-in box so the teacher can hold it until the right student picks it up.

Practice Exercises

Exercise 1

Write MQPUT pseudocode with SYNCPOINT and describe when MQCMIT runs.

Exercise 2

Design request/reply MQMD fields for ORDER.REQ and ORDER.RESP queues.

Exercise 3

Compare one persistent and one non-persistent put for a audit log versus metrics stream.

Frequently Asked Questions

Test Your Knowledge