DELETE (MQSC)

DELETE removes IBM MQ object definitions from the queue manager repository. It is destructive: after DELETE QLOCAL('ORDERS.IN'), applications receive MQRC 2085 (unknown object name) when they MQOPEN that queue until someone DEFINEs it again. DELETE is appropriate when decommissioning applications, cleaning lab queue managers, or reversing a failed promotion—but production DELETE commands belong in change windows with backups and stakeholder sign-off. This tutorial explains DELETE prerequisites for queues and channels, the difference between DELETE and CLEAR, STOP before DELETE patterns, cluster and alias dependencies, authorization requirements, and how to recover with DEFINE from exported scripts when a delete was mistaken.

DELETE QLOCAL Prerequisites

The queue must have CURDEPTH zero—no messages waiting. No application may hold the queue open (IPPROCS and OPPROCS zero on DISPLAY QSTATUS). Stop consumers and producers or wait for drain. If messages remain, either process them with GET or use CLEAR QLOCAL in controlled circumstances—CLEAR is destructive to data and needs its own approval. Dynamic queues created by applications disappear when closed; DELETE applies to permanent definitions.

1
2
3
4
5
DISPLAY QSTATUS('ORDERS.IN') CURDEPTH IPPROCS OPPROCS
* Confirm CURDEPTH(0) and no open handles
DELETE QLOCAL('ORDERS.IN')
DISPLAY QLOCAL('ORDERS.IN')
* Final DISPLAY should report object not found

DELETE CHANNEL, LISTENER, TOPIC, SUB

STOP CHANNEL before DELETE when the channel is active. DELETE LISTENER stops accepting inbound connections on that port definition—coordinate with network team. DELETE SUB removes a subscription; publishers may still send but no subscriber queue receives until SUB is recreated. DELETE TOPIC removes a topic object; verify no dependent subscriptions remain. Cluster objects need extra care—deleting cluster queues or channels can break routing for many queue managers.

DELETE Versus CLEAR

CLEAR QLOCAL('X') removes all messages but leaves the definition—applications can still connect. Use CLEAR for emergency space recovery when message content has no value. DELETE removes the definition entirely. Never tell operations to CLEAR when you meant DELETE or vice versa in a ticket.

Dependencies and Order

Delete in dependency order: subscriptions before topics, aliases before base queues they point to, channels before transmission queues they use (if decommissioning). Applications referencing REMOTE queue names need config updates before DELETE on hub objects. Document alias and cluster names in CMDB so DELETE does not surprise downstream teams.

Authorization and Audit

DELETE requires elevated MQSC authority—often restricted to administrator groups. Log commands through runmqsc echo to files or privileged access management. Pair DELETE tickets with dmpmqcfg export taken before change. Regulated environments may prohibit DELETE on production entirely, allowing only REPLACE to retired naming conventions.

Recovery After Mistaken DELETE

Restore DEFINE from Git script or dmpmqcfg export. Messages that were on the queue before mistaken DELETE are not recoverable from MQ unless backups or replay from upstream systems exist—DELETE is not undo. Incident response: recreate definition quickly, replay from DLQ or source system if architecture supports it.

Explainer: Removing the Mailbox Label

DELETE removes the mailbox from the building directory. Mail cannot be delivered to that name anymore. Letters already inside must be removed first (empty queue); people holding the mailbox door open must let go (close applications).

Explain Like I'm Five: DELETE

DELETE is throwing away the empty mailbox and erasing its name from the mail room list. If letters are still inside or someone is holding the slot, the building manager says no.

Practice Exercises

Exercise 1

Try DELETE on non-empty queue; note AMQ error; drain and succeed.

Exercise 2

DELETE and DEFINE REPLACE the same queue in a script; time recovery.

Exercise 3

Write deletion checklist for decommissioning one application.

Frequently Asked Questions

Test Your Knowledge