Deleting Objects

Deleting IBM MQ objects removes definitions from the queue manager repository: the queue name disappears from administration views, channels no longer start, and listeners no longer bind ports when their definitions are gone. DELETE is irreversible in the sense that the object no longer exists—you recreate it with DEFINE and must restore every attribute from backup scripts or exports. Beginners who DELETE QLOCAL during an active production cutover without draining messages cause data loss and partner outages; veterans capture DISPLAY ALL, export MQSC, stop applications, CLEAR or move messages, then DELETE in change windows. This tutorial covers DELETE syntax for major object types, dependency order (what must be deleted before what), handling open objects, distributed versus z/OS commands, coordination with partners on channels, automation safeguards, and recovery when the wrong object was deleted.

DELETE Command Basics

DELETE QLOCAL('ORDERS.IN') removes the local queue definition. DELETE CHANNEL('TO.PARTNER') removes a channel. DELETE LISTENER, TOPIC, SUB, PROCESS, NAMELIST, AUTHINFO, and other types follow the same pattern with object-specific names. Successful DELETE returns informational AMQ messages; failures cite reason such as object in use or not found. Always DISPLAY after DELETE to confirm absence. REST admin uses DELETE HTTP verb; Explorer offers Delete context menu—same command server outcome.

1
2
3
4
DISPLAY QLOCAL('OLD.TEST') CURDEPTH
CLEAR QLOCAL('OLD.TEST')
DELETE QLOCAL('OLD.TEST')
DISPLAY QLOCAL('OLD.TEST')

Queues: Messages, Open Handles, and CLEAR

CURDEPTH greater than zero means messages remain. Policy may require archiving before CLEAR. CLEAR QLOCAL removes all messages destructively—irreversible. Applications with MQOPEN prevent DELETE until they disconnect. Batch jobs scheduled overnight may hold handles—check DISPLAY QSTATUS for OPENINPUT and OPENOUTPUT. Inhibit get/put with ALTER before drain if you need controlled consumption. Remote queue definitions (QREMOTE) delete without local message storage; QLOCAL on partner side is separate.

Dependency Order for Deletion

1. Stop channels using the object or pointing to the queue.
2. Stop applications or wait for batch completion.
3. Clear or move messages on local queues.
4. Delete subscriptions and aliases pointing to target.
5. Delete channels, then remote queues, then local queues.
6. Delete listeners only when no channels need that port.

Deleting a transmission queue while a sender channel still references it causes channel failures. Deleting SVRCONN used by production Java clients disconnects all clients immediately.

Channels and Partners

Coordinate DELETE CHANNEL with partner operations. Their sender may enter retry if your receiver vanishes. Document interface retirement in governance forums. Prefer disabling with ALTER PUT(DISABLED) or stopping traffic before DELETE during phased decommission. Keep MQSC export of old definition until partner confirms they removed their side.

Explainer: Removing a Mailbox From the Directory

DELETE removes the mailbox label from the building directory and dismantles the box—it does not send leftover letters to another room unless you moved them first with CLEAR or consumer drain.

Cluster and Repository Objects

Cluster queues and channels may recreate automatically if cluster policies still demand them—understand automatic cluster definition before DELETE. Full repositories versus partial repositories affect DELETE impact on cluster-wide knowledge. REFRESH CLUSTER may follow cluster object removal per IBM guidance. Test cluster DELETE in isolation, never first in production.

z/OS Considerations

CSQ DELETE commands require RACF authority. Shared queues in queue sharing groups need sysplex change control. Deleting objects referenced by CICS or IMS definitions breaks runtime until those definitions update. Mainframe change records attach RACF and MQ DELETE in one ticket.

Automation Safeguards

• Never run unreviewed DELETE * patterns.
• Require human approval in pipeline for production DELETE steps.
• Gate on environment variable CONFIRM_PROD_DELETE=true.
• Keep pre-delete DISPLAY snapshot in artifact storage.
• Prefer soft decommission (stop traffic) before hard DELETE.

Recovery After Mistaken DELETE

Recreate from exported MQSC or Git script with DEFINE REPLACE. Messages cleared are not recoverable without backup media. Channel DELETE may need partner sequence number reset if recreated with same name—coordinate. Incident review: who ran DELETE, was export current, time to restore service.

Troubleshooting

1. Object in use — find open handles; stop apps.
2. Object not found — typo or already deleted.
3. Not authorized — admin role or RACF.
4. Channel running — STOP CHANNEL retry DELETE.
5. Queue has messages — CLEAR or drain first.

Explain Like I'm Five: Deleting Objects

Deleting objects is removing a mailbox from the post office catalog after you emptied it and told everyone not to send mail there anymore.

Practice Exercises

Exercise 1

Write ordered steps to retire TEST.QUEUE in lab including DISPLAY, CLEAR, DELETE.

Exercise 2

List partner notifications required before DELETE CHANNEL on a production route.

Exercise 3

Draft pipeline guardrails that block DELETE without backup artifact.

Frequently Asked Questions

Test Your Knowledge