amqsput

amqsput is the IBM MQ sample program every messaging administrator should know. After you DEFINE QLOCAL, ALTER channel TLS, or fix CHLAUTH, the business asks are messages flowing? amqsput answers that question by performing a real MQPUT from the command line—exercising queue manager connection, optional client channel, object authority, and queue attributes such as MAXMSGL and DEFPSIST. It is not a performance tool and not for bulk load; it is a surgical smoke test. Beginners confuse amqsput with runmqsc: runmqsc talks to the command server; amqsput talks to the queue like an application. This tutorial covers invocation syntax on Linux and Windows, bindings versus client mode, line-by-line prompts, persistent versus non-persistent choice, putting to alias and remote queue names, common MQRC codes 2035 and 2085, pairing with amqsget and DISPLAY QSTATUS, and safe use in production change windows.

Basic Invocation

The typical pattern is amqsput queue_name queue_manager_name. The queue name is the target QLOCAL, QALIAS, or resolved name your application uses. The queue manager name must match the active queue manager you intend—typo here produces 2059 queue manager not available or connection to wrong host. When omitted on some platforms, environment variables MQSERVER or default connection may apply; explicit naming reduces mistakes during overnight incidents.

1
2
3
4
5
6
7
# Linux example — paths vary by installation
/opt/mqm/samp/bin/amqsput ORDERS.IN QM1
# Prompt: enter message text, blank line to end
# Second prompt may ask persistence — answer Y or N per test plan
 
DISPLAY QSTATUS('ORDERS.IN') CURDEPTH
# CURDEPTH should increase by number of messages put

Bindings Mode Versus Client Mode

Run amqsput on the same machine as the queue manager with your user in the mqm group and you usually get bindings mode—fast local connection without TCP client channel. Run from a laptop against a remote queue manager and you need MQSERVER pointing at a server-connection channel, for example MQSERVER=QM1.TCP://mqhost.example.com(1414). Client mode tests CHLAUTH, TLS, and CONNAUTH exactly like a remote application. Failures that only happen in client mode implicate channel security, not queue DEFINITION. Test both paths if your application uses client connections.

1
2
3
4
5
export MQSERVER='QM1.TCP://mqserver.example.com(1414)'
export MQCHLLIB=/var/mqm
export MQCHLTAB=AMQCLCHL.TAB
amqsput ORDERS.IN QM1
# Exercises same path as remote Java or .NET client

Message Text, Persistence, and Size

amqsput reads lines from stdin until an empty line ends the message. Large messages hit MAXMSGL on the queue—if put fails with reason 2014, compare message size to DISPLAY QLOCAL MAXMSGL. Persistence prompt: Y creates persistent messages stored in logs; N creates non-persistent messages suitable for quick tests but lost on restart. Match persistence to what your application uses when validating disaster recovery. For multiple messages, run amqsput repeatedly or pipe a script; some sites use amqsbcg for browse instead of put when testing read paths.

Remote Queues, Aliases, and Cluster Queues

Putting through QALIAS tests alias target resolution. Putting through QREMOTE tests transmission queue and channel path—amqsput may return success locally while CURDEPTH on the remote business queue increases only after channel delivers. DISPLAY QSTATUS on XMITQ and partner queue confirms end-to-end flow. Cluster queue puts require cluster routing; failure with 2085 on one member but success on owner member indicates cluster cache issue—see REFRESH CLUSTER tutorial, not amqsput syntax.

Common Errors and Fixes

• 2035 not authorized—grant +put +connect via setmqaut; check CONNAUTH and CHLAUTH.
• 2085 unknown object—DEFINE queue or fix typo; check OPEN options on alias.
• 2059 queue manager unavailable—strmqm or wrong host in MQSERVER.
• 2014 message too long—reduce payload or ALTER MAXMSGL with change control.
• 2053 queue full—CURDEPTH equals MAXDEPTH; drain or raise depth.

Production Etiquette

Use dedicated test queues in production, never payroll queues without approval. Label message content TEST and include change ticket in the text. Coordinate with consumers so test messages are not processed as real events—or use queues with no active consumer. Remove test messages with amqsget or CLEAR QLOCAL per policy. Audit logs record OS user and queue name; do not put PCI or personal data in test payloads.

Pairing With amqsget and DISPLAY

1. DISPLAY QLOCAL and QSTATUS before put—baseline CURDEPTH.
2. Run amqsput with identifiable text.
3. DISPLAY QSTATUS—CURDEPTH incremented.
4. Run amqsget on same queue or partner remote queue to consume test message.
5. Confirm CURDEPTH returned to baseline.

Explainer: Dropping a Letter in the Mailbox

DEFINE built the mailbox. amqsput is dropping a real letter in it so you can check the flag on the box went up—proving the slot works, not just that the mailbox has a nameplate.

Explain Like I'm Five: amqsput

amqsput is sliding a note through the door slot to see if it lands in the basket inside—without building a whole robot to deliver notes.

Practice Exercises

Exercise 1

Put a persistent and non-persistent message; restart queue manager in lab; observe which survives.

Exercise 2

Revoke PUT authority; capture 2035; restore authority; confirm success.

Exercise 3

Put through QREMOTE; verify CURDEPTH on remote queue via partner DISPLAY.

Frequently Asked Questions

Test Your Knowledge