MAXDEPTH

MAXDEPTH is the guardrail on how many messages a queue may hold at once. Every production queue should have an explicit MAXDEPTH chosen deliberately—not left to defaults you never verified. When producers outpace consumers, depth rises until it hits MAXDEPTH; then MQPUT fails with queue full and applications must retry, shed load, or alert operations. Transmission queues with undersized MAXDEPTH can block entire integration paths during a channel outage. This page focuses on the MAXDEPTH attribute itself: how to set it in DEFINE and ALTER, how it differs from byte limits and disk capacity, sizing methods for work and XMITQ queues, and what to do when depth chronically hugs the maximum.

MAXDEPTH on the Queue Definition

DEFINE QLOCAL('ORDERS.IN') MAXDEPTH(500000) stores the limit in the object repository. DISPLAY QLOCAL('ORDERS.IN') MAXDEPTH shows the definition; DISPLAY QSTATUS CURDEPTH MAXDEPTH shows live depth against the cap. ALTER QLOCAL MAXDEPTH(750000) changes the limit for future puts—plan changes when CURDEPTH is high because lowering below current depth may fail. Model queues (QMODEL) also carry MAXDEPTH so dynamic queues inherit sensible caps when applications create temporary reply queues.

1
2
3
4
DEFINE QLOCAL('ORDERS.IN') REPLACE MAXDEPTH(500000) DESCR('Payments inbound')
DISPLAY QLOCAL('ORDERS.IN') MAXDEPTH
DISPLAY QSTATUS('ORDERS.IN') CURDEPTH MAXDEPTH
* When CURDEPTH nears MAXDEPTH, alert ops before 2053 storms

MAXDEPTH vs CURDEPTH vs Disk

CURDEPTH is runtime: how many messages are waiting now. MAXDEPTH is policy: the maximum allowed count. Disk is physical reality: even below MAXDEPTH, the queue manager can run out of log or queue file space if messages are large or persistent volume is huge. Capacity planning uses all three: count limit (MAXDEPTH), size per message (MAXMSGL), and storage monitoring on the host or z/OS page sets. A queue at CURDEPTH 100 with 4 MB messages stresses disk more than CURDEPTH 10000 with 500-byte messages.

Queue Full (Reason 2053)

When an MQPUT would increase CURDEPTH above MAXDEPTH, the queue manager rejects the put with MQRC_Q_FULL (2053 on many clients). Application design choices include: retry with backoff, route to overflow queue, return error to user, or shed non-critical traffic. Operations response includes starting more consumers, fixing stuck consumers, increasing MAXDEPTH after capacity review, or draining poison messages blocking get. Bursts of 2053 after deploy often mean a new consumer failed to start or MAXDEPTH was reduced accidentally.

Sizing MAXDEPTH for Application Queues

1. Estimate peak put rate (messages per second) during busiest window.
2. Estimate consumer rate when healthy; if unknown, use SLA recovery time.
3. Compute backlog = (put rate − get rate) × outage minutes × 60 for worst case.
4. Add safety margin (often 25–50%) for spikes and duplicate redeliveries.
5. Set MAXDEPTH to that message count; validate disk and log can hold persistent backlog.

Example: 200 msg/sec peak, consumers down 30 minutes, no drain → 200 × 1800 = 360,000 messages. Round to 500,000 MAXDEPTH with disk headroom. Batch queues may need only overnight depth; real-time payment queues may need minutes of buffer. Document the assumption in DESCR or your runbook so future teams do not shrink MAXDEPTH without analysis.

Sizing MAXDEPTH for Transmission Queues

XMITQ MAXDEPTH must cover WAN or partner outages. Multiply spoke put rate by expected longest channel downtime. Hub queue managers receiving from many spokes sum multiple feeds into one XMITQ per partner path. Monitor CURDEPTH on XMITQ as a leading indicator of channel health—flat high depth with channel RETRY means fix networking before MAXDEPTH blocks business puts on the spoke.

MAXDEPTH(0) and Platform Defaults

Some administrators use MAXDEPTH(0) to mean “use system default” on certain platforms. Behavior varies by release—DISPLAY after DEFINE shows effective limits. Relying on implicit defaults in production is risky: a default of 5000 messages may be tiny for a high-volume hub. Explicit MAXDEPTH in infrastructure-as-code (MQSC scripts, Terraform) makes promotion across Dev/Test/Prod auditable.

MAXDEPTH with Triggering

TRIGTYPE(DEPTH) with TRIGDPTH(n) fires when depth reaches n—often set below MAXDEPTH so additional consumer instances start before queue full. If TRIGDPTH equals MAXDEPTH, triggers may arrive too late. Example: MAXDEPTH 100000, TRIGDPTH 80000 starts extra workers while 20000 messages of headroom remain.

Shared Queues and Clusters

On z/OS queue sharing groups, shared queue depth may be reported differently than single queue manager CURDEPTH—consult QSG monitoring guides. Cluster queues inherit MAXDEPTH on the local queue definition publishing to the cluster; workload balancing does not bypass MAXDEPTH on the chosen target instance.

Altering MAXDEPTH in Production

• Increasing MAXDEPTH: usually low risk if disk and logs are sized; still verify.
• Decreasing MAXDEPTH: ensure CURDEPTH is below new value or drain first.
• Communicate to application teams—retry logic may assume old limits.
• Revisit alerting thresholds after change.

Explain Like I'm Five: MAXDEPTH

The queue is a line with a sign: “only 100 people allowed in line.” MAXDEPTH is the number on the sign. When 100 people are already waiting, the next person cannot join (queue full). CURDEPTH is counting how many people are in line right now.

Practice Exercises

Exercise 1

Queue accepts 50 msg/sec; consumers stop for 20 minutes. What minimum MAXDEPTH if no shedding?

Exercise 2

CURDEPTH stuck at MAXDEPTH but consumers claim they are running. List five checks.

Exercise 3

Why set TRIGDPTH lower than MAXDEPTH on a triggered work queue?

Frequently Asked Questions

Test Your Knowledge