Altering Objects

Production IBM MQ estates rarely stay static: capacity planning increases MAXDEPTH before Black Friday, DR exercises ALTER CHANNEL CONNAME to the secondary data center, security mandates DEFPSIST(YES) on a queue that was non-persistent in test, and partners request longer HBINT on channels crossing high-latency links. ALTER is the MQSC verb—and REST PATCH equivalent—for changing existing object definitions without delete-and-recreate. Unlike DEFINE REPLACE, ALTER typically touches only the attributes you name, which is safer when a hundred settings already exist on a channel you did not build. Beginners who ALTER MAXMSGL without checking largest message on the queue cause immediate application failures; veterans capture DISPLAY before and after in every change ticket. This tutorial explains ALTER syntax, attribute impact by object type, live alteration versus change windows, channel and listener updates, coordination with running instances, rollback strategies, Explorer and REST alter paths, and troubleshooting when ALTER succeeds but behavior does not change until restart.

ALTER Syntax and Verification

ALTER QLOCAL('ORDERS.IN') MAXDEPTH(150000) increases depth cap. Multiple attributes fit one command separated by spaces. Use DISPLAY QLOCAL('ORDERS.IN') ALL before and after; diff the output in the change record. REST PATCH sends partial JSON updates. Explorer property sheets issue ALTER under the hood. Script ALTER files for one-attribute fixes are clearer than full DEFINE REPLACE redeploys for hotfixes.

1
2
3
DISPLAY QLOCAL('ORDERS.IN') MAXDEPTH MAXMSGL DEFPSIST
ALTER QLOCAL('ORDERS.IN') MAXDEPTH(150000)
DISPLAY QLOCAL('ORDERS.IN') MAXDEPTH

Queue Attributes and Operational Impact

Altering Channels

CONNAME changes redirect TCP target—critical for DR. SSLCIPH and SSLPEER updates rotate cipher policy or certificate expectations. HBINT and DISCINT tune heartbeat and disconnect timing—alter during maintenance; running channels may need STOP CHANNEL then START. MCAUSER changes affect authorization for new bindings—coordinate with RACF or setmqaut. MAXMSGL on channel must accommodate message size. BATCHSZ and BATCHINT affect throughput—tune with measurement, not guesses. DISPLAY CHSTATUS after ALTER to confirm running instance picked up attributes that require restart.

1
2
3
4
5
ALTER CHANNEL('QM1.TO.QM2') CONNAME('dr-qm2.example.com(1414)') +
  HBINT(300)
STOP CHANNEL('QM1.TO.QM2')
START CHANNEL('QM1.TO.QM2')
DISPLAY CHSTATUS('QM1.TO.QM2')

Listeners, Authinfo, and Topics

ALTER LISTENER PORT changes require stopping and starting the listener—impacts all inbound channels on that port. AUTHINFO alterations affect CONNAUTH—test client login in lower environment; one mistake locks out all remote admins. TOPIC alterations change pub/sub routing or security scope—verify subscription DEST queues still valid. Nontrivial ALTER on cluster objects may need REFRESH CLUSTER per IBM guidance for your release.

Explainer: Adjusting Thermostat Without Rebuilding House

ALTER is turning the thermostat or relabeling a door in the message building without tearing down the whole room—DEFINE REPLACE is rebuilding the room from scratch with a new blueprint.

Live Alteration Versus Change Windows

• Safe anytime (usually) — DESCR, modest MAXDEPTH increase, HBINT within reason.
• Change window — PUT(GET) disable, MAXMSGL decrease, CONNAME DR cutover, SSL cert wholesale swap.
• Requires coordination — MCAUSER, CHLAUTH-related channel fields, cluster attributes.
• Forbidden without design — altering queue manager dead letter queue name on busy systems.

ALTER Versus DEFINE REPLACE

DEFINE QLOCAL('X') REPLACE with only two attributes shown may reset other attributes to defaults on some object types—a classic outage cause. ALTER QLOCAL('X') MAXDEPTH(5000) leaves MAXMSGL untouched. For GitOps full desired state, some pipelines use REPLACE intentionally with complete attribute files; hotfixes use ALTER. Pick consciously per ticket type.

Applications and Open Handles

Applications with long-lived MQCONN may cache queue handles. ALTER MAXDEPTH is visible immediately for new puts; some attribute changes need application restart or queue reopen. Batch jobs that open once per night pick up changes next run. CICS channels may need region refresh depending on integration. Communicate ALTER timing to application owners in the change record.

Rollback

Keep before DISPLAY output. Rollback is ALTER back to previous values, not automatic undo. For CONNAME DR tests, document primary and secondary values in runbook. If ALTER made queue unusable, emergency ALTER to restore PUT enabled before root cause meeting ends.

z/OS and Authority

ALTER on z/OS requires RACF (or ESM) authority equivalent to administrative change on the profile. CSQ commands log alterations. Queue sharing group ALTER may propagate per sharing rules—verify IBM docs before altering shared queues. Mainframe change advisory boards want RACF and MQSC in same ticket.

Troubleshooting

1. ALTER succeeded but no effect — channel needs STOP/START; app needs reconnect.
2. AMQ error on ALTER — syntax or authority; compare DISPLAY object existence.
3. Queue full after MAXDEPTH raise — CURDEPTH already at old cap; raise was correct, wait for drain or add consumers.
4. Partner still connects old IP — DNS TTL or they did not restart sender channel.

Explain Like I'm Five: Altering Objects

Altering objects is changing the rules on a mailbox—like making it taller to hold more letters—without throwing away the mailbox and building a new one.

Practice Exercises

Exercise 1

ALTER MAXDEPTH on a test queue; capture before/after DISPLAY in a change template.

Exercise 2

Plan DR CONNAME ALTER with STOP/START steps and rollback values.

Exercise 3

Explain why DEFINE REPLACE is riskier than ALTER for one-attribute hotfix.

Frequently Asked Questions

Test Your Knowledge