MAXMSGL

MAXMSGL answers one question: how large can a single message be on this queue? While MAXDEPTH counts messages, MAXMSGL counts bytes per message. Integration failures where “small test messages work but production fails” often trace to payloads exceeding MAXMSGL after go-live, or to a remote queue with a smaller limit than the sender. Administrators set MAXMSGL on DEFINE QLOCAL, on model queues for dynamic queues, and must respect the queue manager-wide ceiling. Developers need the limit when allocating buffers and when splitting large files into multiple messages. This tutorial explains the attribute, queue manager caps, reason codes, end-to-end sizing across remote queues and channels, and how MAXMSGL interacts with persistence and disk.

Setting MAXMSGL on DEFINE and ALTER

1
2
3
4
5
6
7
DISPLAY QMGR MAXMSGL
DEFINE QLOCAL('PAYLOAD.IN') REPLACE +
  MAXMSGL(4194304) +
  MAXDEPTH(100000) +
  DESCR('Max 4MB per message - matches QMGR cap')
ALTER QLOCAL('PAYLOAD.IN') MAXMSGL(8388608)
* Only if DISPLAY QMGR MAXMSGL allows 8MB

DISPLAY QMGR MAXMSGL shows the platform maximum for the entire queue manager—often 4 MB on many distributed installs unless raised. Queue MAXMSGL must be less than or equal to that value. Raising queue manager MAXMSGL is a major change affecting memory and channel buffers; follow IBM guidance for your release and restart requirements.

What Counts Toward Message Length

Application payload is the bulk of size, but the message also includes the message descriptor (MQMD) and any additional headers (RFH2, JMS headers, MQDLH if present). Measuring only JSON body size in Postman understates wire length. COBOL programs using fixed buffers must allocate at least MAXMSGL for get buffers or use dynamic buffer techniques per language guide. Pub/sub publications fan out the same message size to many subscriber queues—each must accept MAXMSGL.

End-to-End MAXMSGL in Multi-QM Designs

1. Application puts to QLOCAL or QREMOTE on QM_A.
2. QM_A accepts if local queue MAXMSGL allows.
3. Channel transmits to QM_B; receiver puts to target QLOCAL.
4. Target MAXMSGL on QM_B must be at least message size or put fails at destination.

A spoke with MAXMSGL 10 MB sending to a hub queue with MAXMSGL 4 MB fails at the hub even though the spoke accepted the put. Standardize MAXMSGL tiers (small/medium/large queue classes) across the estate. Document in naming conventions: ORDERS.* queues are 4 MB class; BLOB.* queues are 100 MB class with special QMGR tuning.

Splitting Oversized Business Data

When payload exceeds practical MAXMSGL, architects split into multiple messages with a header describing sequence, total parts, and correlation ID—or move bulk data to shared storage and send a reference message through MQ. Message fragmentation adds application complexity but keeps queue managers within supported buffer sizes. Never assume raising MAXMSGL to extreme values is free—it increases channel agent memory and risk.

MAXMSGL on Model and Dynamic Queues

DEFINE QMODEL('REPLY.MODEL') MAXMSGL(1048576) copies to each temporary dynamic queue. If replies can be larger than requests, set model MAXMSGL to the reply size, not the request size. Permanent dynamic queues inherit at creation; ALTER model does not change existing dynamic queues until recreated.

Monitoring and Testing

• Lab test: put message at MAXMSGL, MAXMSGL+1 byte, and empty message.
• Compare DISPLAY QLOCAL MAXMSGL across environments in CI drift checks.
• Alert on message-too-big errors in application logs—often precedes DLQ routing.
• After QMGR MAXMSGL change, regression test channels and clients.

z/OS and Distributed Differences

Maximum sizes and defaults differ between z/OS and distributed MQ; always read the IBM MQ product documentation for your platform. Mainframe COBOL and IMS bridges may have additional limits below MQ MAXMSGL. Capacity on z/OS includes page set and CF structure sizes for shared queues—large messages multiply storage pressure faster than small ones even at low CURDEPTH.

Explain Like I'm Five: MAXMSGL

The mailbox has a slot size limit. MAXMSGL is how big one package can be. If you try to shove a huge box through the slot, it does not fit (put fails). You can still have many small packages (MAXDEPTH)—each must fit the slot individually.

Practice Exercises

Exercise 1

QMGR MAXMSGL 4MB, queue MAXMSGL 8MB. Will DEFINE succeed? What should you do?

Exercise 2

Test works with 1KB messages; production JSON is 5MB. Which objects need review?

Exercise 3

Why is end-to-end MAXMSGL the minimum of all queues in the path?

Frequently Asked Questions

Test Your Knowledge