amqsget

amqsget is the IBM MQ sample program that completes the smoke test amqsput starts. Putting a message proves the producer path; getting it proves the consumer path, GET authority, and that nothing else stole the message first. Operators use amqsget after channel fixes, authority changes, and backup recovery drills. Developers use it before writing application GET loops to confirm queue attributes—DEFPSIST, MAXMSGL, share options—and wait behavior. amqsget is destructive by default: every successful read removes a message from CURDEPTH. In production that matters when you accidentally drain a backlog onto your terminal. This tutorial explains syntax, wait and timeout behavior, bindings versus client mode, pairing with DISPLAY QSTATUS, difference from browse utilities, syncpoint considerations, common MQRC codes, and safe cleanup of test messages put by amqsput.

Basic Invocation

Invoke amqsget with queue_name and queue_manager_name similar to amqsput. The program connects, opens the queue for GET, and waits for a message according to sample options on your release—often displaying message text to stdout when a message arrives. If the queue is empty, you may see no output until wait ends or reason 2033 no message available appears depending on how the sample is built on your platform.

1
2
3
4
5
DISPLAY QSTATUS('ORDERS.IN') CURDEPTH
/opt/mqm/samp/bin/amqsget ORDERS.IN QM1
# Reads and removes one message if present
DISPLAY QSTATUS('ORDERS.IN') CURDEPTH
# CURDEPTH should decrease after successful get

Wait Interval and Empty Queue

Applications use MQGMO with wait interval so GET blocks until a message arrives or timeout hits. Sample amqsget may wait a fixed period—consult your installation source or help text. If amqsput was run on another queue manager remote definition, allow channel time to deliver before amqsget times out. DISPLAY QSTATUS CURDEPTH zero while partner XMITQ has depth means messages are in flight—not yet on your target queue. Teaching point: GET waits on the queue you open, not on the transmission queue.

Bindings Versus Client Mode

Same MQSERVER and MQCHLLIB rules as amqsput apply. Client mode amqsget from a workstation tests server-connection channel, TLS, and GET authority for the mapped user. MCAUSER on the channel may map your OS user to a different MQ principal—if amqsput works but amqsget fails with 2035, compare effective user on both operations. RACF on z/OS maps TSO or batch user to MQ profiles; distributed Linux uses OAM object records.

1
2
3
4
export MQSERVER='QM1.TCP://mqserver.example.com(1414)'
amqsget PAYROLL.IN QM1
# Requires +get on PAYROLL.IN for effective user
# Production: use only approved test queues

Destructive Get and Production Risk

Each successful amqsget removes one message. Draining a thousand-message backlog by scripting amqsget in a loop is indistinguishable from a runaway consumer in CURDEPTH terms—business processing may be lost. Use TEST queues. If you must sample one production message, prefer browse (amqsbcg) with change approval, or ask application team to export. After accidental get, restore from backup or replay from source system per disaster recovery plan—MQ cannot undelete a destructive get.

Syncpoint and Transactional Get

Application GET under syncpoint can be rolled back; amqsget sample typically runs without client transaction coordination unless modified. Testing transactional consumers requires your application or a custom program using MQGMO_SYNCPOINT. Commit and rollback tutorial explains units of work. For basic connectivity proof, non-transactional amqsget is sufficient.

Common Errors

• 2033 no message available—queue empty or wait timed out.
• 2035 not authorized—missing +get on queue.
• 2085 unknown object—queue name wrong or not defined on this QM.
• 2016 message length—buffer too small for large message; use appropriate sample options.
• 2053 queue full—not a get error but seen when putting after get test.

End-to-End Test Script Pattern

1. DISPLAY QSTATUS CURDEPTH baseline.
2. amqsput unique string including timestamp.
3. DISPLAY QSTATUS—depth increased.
4. amqsget—verify string matches.
5. DISPLAY QSTATUS—depth back to baseline.
6. Attach output to change ticket.

Message Properties and Format

amqsget prints payload as character data for simple text messages. Binary or RFH2 headers may look garbled on the terminal—that is expected. Applications use MQMD format field; sample does not teach COBOL copybooks. For JMS or RFH2 test messages use application consumers or specialized tools. MQGET tutorial covers MQGMO options in API terms that map conceptually to what samples implement internally.

Explainer: Taking the Letter Out of the Mailbox

amqsput dropped the letter in. amqsget takes one letter out and reads it aloud—so the mailbox count goes down. If you only wanted to peek without taking, you need a browse tool instead.

Explain Like I'm Five: amqsget

amqsget is opening the basket, reading one note, and throwing it away so the basket has one fewer note—unless you use a peeking tool that copies without removing.

Practice Exercises

Exercise 1

Put three messages with amqsput; run amqsget three times; verify CURDEPTH returns to zero.

Exercise 2

Run amqsget on empty queue; document wait behavior and reason code.

Exercise 3

Compare one message via amqsbcg browse versus amqsget—note CURDEPTH difference.

Frequently Asked Questions

Test Your Knowledge