Get Message Options (MQGMO) steer every MQGET: block or poll, remove or peek, match a specific correlation id, convert EBCDIC to UTF-8, accept truncated buffers, or enroll the get in a syncpoint that rolls back on processing failure. Consumer bugs usually trace to wrong Options combination—NO_WAIT spin loops, browse without BROWSE_FIRST/NEXT sequence, or MATCH_CORREL_ID with unset CorrelId in MQMD. Poison message handling depends on MQGMO_SYNCPOINT plus MQBACK incrementing backout count. This tutorial documents MQGMO initialization, wait intervals, browse families, match options for MsgId and GroupId, conversion, syncpoint and commit pairing, truncated message strategies, properties compatibility flags, quiesce fail option, and symmetric comparison to MQPMO for transactional pipelines.
Use MQGMO_DEFAULT per iteration. Set Options with OR. WaitInterval only applies when MQGMO_WAIT is set—interval 0 may return immediately. Version must match client library. ReturnedMsgHandle and other advanced fields appear in pub/sub and browse APIs per IBM version.
123456789MQGMO gmo = {MQGMO_DEFAULT}; gmo.Options = MQGMO_WAIT | MQGMO_CONVERT | MQGMO_FAIL_IF_QUIESCING | MQGMO_SYNCPOINT; gmo.WaitInterval = 60000; /* 60 seconds */ MQGET(Hconn, Hobj, &md, &gmo, buflen, buffer, &buflen, &compCode, &reason);
| Option | Effect | Note |
|---|---|---|
| MQGMO_WAIT | Block up to WaitInterval | Pair with interval ms |
| MQGMO_NO_WAIT | Return immediately | 2033 if empty |
| MQGMO_BROWSE | Non-destructive read | Needs MQOO_BROWSE open |
| MQGMO_BROWSE_FIRST | First message in queue | Start browse pass |
| MQGMO_BROWSE_NEXT | Next after browse | Walk queue |
| MQGMO_MATCH_CORREL_ID | Filter by CorrelId | Set in input MQMD |
| MQGMO_MATCH_MSG_ID | Filter by MsgId | Exact message fetch |
| MQGMO_SYNCPOINT | Get under UOW | BACK rolls back visibility |
| MQGMO_CONVERT | Convert charset | Uses MD encoding fields |
| MQGMO_ACCEPT_TRUNCATED_MSG | Allow short buffer | Check reason truncated |
Dedicated consumer threads use WAIT with 30–60 second intervals and shutdown flag checked on 2033 timeout. Microservices with reactive loops may use shorter waits to pick up SIGTERM between gets. NO_WAIT in tight loop without sleep burns CPU—anti-pattern. Compare WebSphere MQ client asynchronous consume APIs that hide wait but still set GMO equivalents underneath.
MQGMO_WAIT is deciding to stand at the mailbox up to one minute for a letter. MQGMO_NO_WAIT is peeking once and walking away immediately if empty. BROWSE is reading through the window without taking the letter out.
Open with MQOO_BROWSE. First call uses MQGMO_BROWSE combined with BROWSE_FIRST. Subsequent calls use BROWSE_NEXT. Destructive get requires ending browse or separate open without browse per IBM rules—mixing browse and get on same handle has constraints documented for your release. Support teams browse DLQ depth without removing messages until decision to requeue.
Copy request MsgId into MQMD CorrelId before get; set MQGMO_MATCH_CORREL_ID. Multiple clients sharing one reply queue each wait on different correl values. MATCH_MSG_ID fetches one specific message—useful for idempotent replay from known id. Wrong endian or cleared MQMD between puts causes eternal 2033 waits.
MQGMO_SYNCPOINT gets message under UOW. Processing failure calls MQBACK—message reappears, BackoutCount increments. Exceed BACKOUTTHRESH triggers DLQ or backout queue. Some handlers use NO_SYNCPOINT get, copy to memory, commit business side, then commit MQ—risky if crash between steps. Prefer syncpoint when exactly-once processing matters.
MQGMO_CONVERT asks queue manager to translate payload to encoding in MQMD output fields for the application. Truncation: without ACCEPT_TRUNCATED_MSG, short buffer may fail; with it, reason indicates truncated accept and buflen shows bytes copied—allocate larger buffer or use segmented read pattern from samples.
Transactional pipelines often use MQPMO_SYNCPOINT on put and MQGMO_SYNCPOINT on get with single MQCMIT after database update. Producer NO_SYNCPOINT with consumer SYNCPOINT is inconsistent for handoff guarantees. FAIL_IF_QUIESCING on both sides helps coordinated shutdown.
MQGMO_PROPERTIES_COMPATIBILITY and related flags affect how RFH2 properties surface in Java and C—consult IBM when migrating clients. Raw C on JMS-produced messages may need property-aware get APIs instead of manual buffer skip.
MQGMO is how you tell the teacher whether to wait at the cubby hole for your paper, peek without taking it, or only take the paper with your name on it.
Write GMO options for a consumer with 45s wait, syncpoint, convert, quiesce fail.
Outline browse-first support workflow on a DLQ without deleting messages.
Explain MATCH_CORREL_ID flow with two outstanding client requests.
1. MQGMO_WAIT requires:
2. MQGMO_BROWSE:
3. MATCH_CORREL_ID is used for:
4. MQGMO_SYNCPOINT on get: