ALTER (MQSC)

ALTER is how you change IBM MQ object definitions after the initial DEFINE without deleting and recreating them. Operations teams ALTER MAXDEPTH during peak season, tune channel BATCHSZ after latency complaints, or disable PUT on a queue during maintenance. Developers rarely run ALTER in production, but they must understand which attributes affect application behavior—GET(DISABLED) stops consumers from opening for input even when depth is nonzero. ALTER only updates the attributes you list; every other attribute keeps its previous value, which is safer than re-sending a full DEFINE block when you intend to change one field. This tutorial covers ALTER syntax, common object types, production impact, comparison with DEFINE REPLACE, authorization, verification, and rollback thinking for administrators.

Syntax and Partial Updates

ALTER QLOCAL('ORDERS.IN') MAXDEPTH(200000) changes only maximum depth. DESCR, DEFPSIST, and BOQNAME remain as they were. This partial update model reduces accidental configuration drift—provided your runbook names exactly the attributes to touch. Document before and after DISPLAY output in change tickets for regulated industries.

1
2
3
4
5
6
DISPLAY QLOCAL('ORDERS.IN') MAXDEPTH CURDEPTH
ALTER QLOCAL('ORDERS.IN') MAXDEPTH(200000)
DISPLAY QLOCAL('ORDERS.IN') MAXDEPTH CURDEPTH
* First DISPLAY — baseline CURDEPTH before change
* ALTER — only MAXDEPTH changes
* Second DISPLAY — proves new limit; CURDEPTH unchanged by ALTER alone

ALTER QLOCAL — High-Impact Attributes

MAXDEPTH increases allow more backlog during consumer outage; decreases risk Q_FULL if CURDEPTH already high. MAXMSGL must accommodate largest message; lowering it blocks future large puts. DEFPSIST alters default for new puts only. BOTHRESH and BOQNAME change poison handling—coordinate with application backout behavior. GET(DISABLED) or PUT(DISABLED) are maintenance switches—applications receive 2035 or cannot put. TRIGGER and TRIGTYPE changes affect whether trigger messages fire—mis-ALTER can stop batch initiation. CLUSTER and CLWL* attributes on cluster queues affect workload routing—test in non-production cluster first.

ALTER CHANNEL

Channel tuning often uses ALTER: HBINT for heartbeat, BATCHSZ and BATCHINT for throughput versus latency, DISCINT for idle disconnect, SSLCIPH and SSLCAUTH for security upgrades. If the channel is RUNNING, some changes apply on next start; IBM documents per-attribute behavior. Standard production procedure: DISPLAY CHSTATUS, STOP CHANNEL if required, ALTER, START CHANNEL, confirm RUNNING and message flow. ALTER CONNAME on a sender redirects partner hostname—common after data center move; verify DNS and firewall before START.

1
2
3
4
5
ALTER CHANNEL('PARTNER.SDR') BATCHSZ(50) BATCHINT(100)
ALTER CHANNEL('PARTNER.SDR') HBINT(300)
* BATCHSZ — messages per network batch (higher = more throughput, more latency)
* BATCHINT — milliseconds to wait filling a batch
* HBINT — heartbeat seconds; detects dead TCP faster when low

ALTER QMGR and Security Objects

ALTER QMGR changes queue manager-wide settings—dead letter queue name, default transmission queue, logging parameters where alterable, and features like CHLAUTH(ENABLED). These are high-privilege changes with broad blast radius. ALTER AUTHINFO, ALTER SERVICE, and ALTER CHLAUTH records belong to security projects with rollback plans. REFRESH SECURITY often follows ALTER of authinfo objects—see the REFRESH tutorial in this command reference series.

ALTER Versus DEFINE REPLACE

DEFINE REPLACE replaces the whole definition and can create if missing—ideal for GitOps where the file is source of truth. ALTER suits surgical fixes: double MAXDEPTH for Black Friday without resubmitting fifty attributes. If your REPLACE script omits an attribute, REPLACE might reset it to default depending on object type—know your tooling. Some export tools generate full DEFINE REPLACE from DISPLAY output; ALTER is what humans type during incidents.

Explainer: Thermostat, Not New Room

DEFINE builds a room. ALTER adjusts the thermostat or door lock without demolishing the room. Messages already sitting in the room are not thrown out by ALTER unless you use a different command like CLEAR.

Safe Change Procedure

1. DISPLAY object ALL; save output.
2. Assess CURDEPTH, CHSTATUS, open applications.
3. Get change approval for production.
4. Run ALTER with minimal attributes.
5. DISPLAY again; compare diff.
6. Monitor application errors and depth for thirty minutes.

Explain Like I'm Five: ALTER

ALTER is changing the rules on a mailbox that already exists—like making the box bigger or saying “no more letters until tomorrow” without building a new box.

Practice Exercises

Exercise 1

ALTER MAXDEPTH up and down in lab; note when decrease is rejected.

Exercise 2

ALTER PUT(DISABLED); observe producer MQRC; restore PUT(ENABLED).

Exercise 3

Document a before/after DISPLAY pair for a channel BATCHSZ change.

Frequently Asked Questions

Test Your Knowledge