MAXMSGL on Channels

IBM MQ uses the name MAXMSGL in two places beginners must not confuse: on queues and on channels. The queue tutorial explains how MAXMSGL caps each put to a QLOCAL. This page covers MAXMSGL on channel definitions—SDR, RCVR, SVRCONN, and cluster variants—where it caps how large a single message may be when the channel agent sends or receives protocol data. A payment file split incorrectly is only half the story if your spoke queue allows eight megabytes but the hub channel still enforces four. Channel MAXMSGL is therefore an integration limit, not a storage limit alone. You will learn how to DISPLAY and ALTER it, how it relates to queue manager MAXMSGL, how to align both sides of a channel pair, and how to diagnose “works locally, fails over the channel” production incidents.

Why Channels Have Their Own Size Limit

Message channel agents allocate buffers for sending and receiving batches. MQI channels bound client puts to server resources. A channel MAXMSGL prevents a single enormous message from exhausting agent memory or monopolizing a TCP session. Even when a source queue accepts a large put, the channel may refuse to move it if MAXMSGL on the SDR is lower. Conversely, a channel configured for large payloads does not help if the target queue MAXMSGL is smaller—the receiver put fails at the destination. Capacity planning must walk the full path: application buffer, source queue, each channel hop, target queue.

Setting MAXMSGL on Channels

1
2
3
4
5
6
7
DISPLAY QMGR MAXMSGL
DEFINE CHANNEL('QM1.TO.QM2') CHLTYPE(SDR) TRPTYPE(TCP) +
  CONNAME('qm2.corp(1414)') XMITQ('XMIT.QM2') MAXMSGL(4194304)
DEFINE CHANNEL('PAYMENTS.APP') CHLTYPE(SVRCONN) TRPTYPE(TCP) +
  MAXMSGL(10485760) MCAUSER('payapp')
ALTER CHANNEL('QM1.TO.QM2') CHLTYPE(SDR) MAXMSGL(8388608)
DISPLAY CHANNEL('QM1.TO.QM2') MAXMSGL

Values are in bytes. 4194304 is four megabytes—a common default tier on many installations. Raising channel MAXMSGL above queue manager MAXMSGL fails ALTER with a validation error. After changing MAXMSGL, restart or cycle channel instances per your release behavior so running agents pick up new limits. Test with a message one byte below and one byte above the limit.

Aligning Both Sides of a Pair

SDR on QM_A and RCVR on QM_B should use compatible MAXMSGL values. Mismatched pairs sometimes work for small traffic until a large message appears. Standardize “large route” channels with explicit MAXMSGL in naming standards—e.g. all channels ending in .LRG use 10485760. SVRCONN MAXMSGL must align with client expectations and with target queues the client puts to. A client sending ten-megabyte JSON needs SVRCONN MAXMSGL, queue MAXMSGL, and any intermediate SDR limits all sufficient.

Explainer: Door Frame Height on the Truck Route

Queue MAXMSGL is how tall a box may be in your warehouse. Channel MAXMSGL is how tall the truck door is on the highway between warehouses. A box that fits in warehouse A still cannot reach warehouse B if the truck door is too low—even if warehouse B accepts tall boxes when they arrive by another road.

Relationship to BATCHSZ

BATCHSZ controls how many messages or how much data the channel groups per network operation; MAXMSGL caps any single message. A batch may contain multiple messages each within MAXMSGL. One message cannot exceed MAXMSGL regardless of BATCHSZ. Tune both together on high-throughput links—see the BATCHSZ tutorial.

Common Failure Patterns

1. Test environment queue MAXMSGL raised; production channel left at default—go-live failure.
2. Hub consolidates traffic on one SVRCONN with low MAXMSGL for legacy apps—new microservice payloads fail.
3. Cluster channel MAXMSGL lower than spoke queue—cluster put succeeds locally, remote instance fails.
4. Message compression in application makes body small but headers push over limit—measure full MQ message length.

Monitoring and Standards

• Export DISPLAY CHANNEL MAXMSGL in configuration audits across environments.
• Document tier S/M/L with byte values in integration standards.
• Include boundary-size messages in channel migration test packs.
• When raising QMGR MAXMSGL, regression-test all channels and critical queues together.

Explain Like I'm Five: Channel MAXMSGL

Channel MAXMSGL is the biggest single package allowed on that truck route between two MQ computers.

Practice Exercises

Exercise 1

Queue MAXMSGL 8MB, SDR MAXMSGL 4MB. Can a 6MB message leave on that SDR? Explain.

Exercise 2

List four objects to check for a 5MB payload from client to remote queue on another QM.

Exercise 3

Why should channel pairs use the same MAXMSGL tier in documentation even if IBM allows mismatch?

Frequently Asked Questions

Test Your Knowledge