MQGET

MQGET removes or copies messages from a queue your application opened for input. Where MQPUT is the producer dropping work into the system, MQGET is the worker picking it up—payment processor, inventory updater, or bridge forwarding to another system. The call supplies MQMD (filled on output with actual identifiers), MQGMO controlling wait and match rules, a buffer, and length in/out because messages can be larger than expected. A consumer loop typically: MQGET with wait, process payload, commit syncpoint if used, repeat. Wrong get options cause busy loops burning CPU (no wait on empty queue) or stuck threads (infinite wait without shutdown hook). This tutorial explains destructive versus browse gets, wait intervals, correlation matching, transactional gets with rollback, message truncation when buffer too small, backout count and poison messages, and graceful shutdown when the queue manager quiesces.

Basic Destructive Get

After MQOPEN with MQOO_INPUT, MQGET with default get options removes the first available message in FIFO order for standard local queues. MsgId and CorrelId in MQMD output reflect the stored message. Buffer length must be at least message size or the call succeeds with truncation and MQRC_TRUNCATED_MSG_ACCEPTED depending on options—beginners should allocate buffers from MQINQ MaxMsgLength or use two-step get patterns from IBM samples.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
MQMD md = {MQMD_DEFAULT};
MQGMO gmo = {MQGMO_DEFAULT};
char buffer[65535];
MQLONG buflen = sizeof(buffer);
 
gmo.Options = MQGMO_WAIT | MQGMO_CONVERT;
gmo.WaitInterval = 30000; /* 30 seconds */
 
MQGET(Hconn, Hobj, &md, &gmo, buflen, buffer, &buflen, &compCode, &reason);
 
if (compCode == MQCC_OK) {
  /* buflen now actual message length */
} else if (reason == MQRC_NO_MSG_AVAILABLE) {
  /* timeout or empty */
}

Wait Versus Poll

MQGMO_WAIT with WaitInterval 30000 blocks up to thirty seconds—efficient for dedicated consumer threads. MQGMO_NO_WAIT in a tight loop with sleep(1) adds latency but simplifies shutdown flags checked each iteration. Event-driven microservices often use wait with long interval plus MQ callback APIs in some clients. Compare CPU: no wait on empty queue spins at 100% CPU—never do that in production without delay.

Explainer: Taking the Letter Out

MQGET is taking the letter out of the mailbox so nobody else gets the same letter. Browse is reading the letter through the window while leaving it inside for the official pickup later.

Request/Reply Consumer

Server MQGET on WORK.IN, processes order, MQPUT reply with CorrelId equal to request MsgId. Client opened reply queue earlier, sets MQGMO_MATCH_CORREL_ID and CorrelId from saved request id, MQGET waits for matching reply only. Multiple outstanding requests need unique MsgIds and a map in application memory—correlation is not automatic magic without correct fields.

Transactional Get and Poison Messages

MQGMO_SYNCPOINT under UOW: message hidden from other consumers until commit. Processing exception triggers MQBACK—message returns to queue and BackoutCount increments. When BackoutCount exceeds queue BACKOUTTHRESH, message goes to backout queue or DLQ per configuration—poison message scenario. Handlers should catch bad JSON schema and route to error queue without infinite rollback loops. Monitor DLQ depth alerts.

Truncation and Large Messages

If buffer smaller than message, options determine failure versus truncate. Production code queries message size or uses variable buffer reallocation patterns from IBM samples. Channels may reject oversize before message reaches consumer—fix MAXMSGL chain end to end.

Shared Conversations and Multiple Consumers

Multiple instances MQGET same queue—each message typically to one consumer only (competing consumers pattern). Scale horizontally by adding consumer processes. Message ordering is not guaranteed across consumers unless using FIFO groups or partition keys in advanced patterns. INHIBIT(GET) stops all consumers administratively during drain maintenance.

Get from Topic Subscriptions

Subscribers receive publications via get on associated queues or callback interfaces depending on API. Durable subscriptions retain messages for offline subscribers. Non-durable drops if subscriber disconnected—choose per business requirement.

Shutdown and Quiesce

During endmqm quiesce, MQGET with MQGMO_FAIL_IF_QUIESCING fails new gets so threads exit. Applications register signal handlers to set shutdown flag and break wait. MQDISC after MQCLOSE on open objects. Hung consumers block quiesce—operations kill process only after coordination.

Troubleshooting

1. 2033 always — producer not putting, wrong queue name, or filter too strict.
2. 2035 — get authority missing on profile.
3. Messages reappear — rollback without commit; check exception handlers.
4. DLQ growth — poison payloads; inspect MQMD and body.
5. Garbled text — encoding mismatch; use MQGMO_CONVERT.

Explain Like I'm Five: MQGET

MQGET is when you take the next note out of the class turn-in box and read it—once you take it, your friend cannot get the same note.

Practice Exercises

Exercise 1

Write consumer loop pseudocode with 30s wait and clean shutdown flag.

Exercise 2

Describe browse-first then destructive get audit pattern for support team.

Exercise 3

Explain poison message path from failed processing to DLQ in five steps.

Frequently Asked Questions

Test Your Knowledge