Defining a local queue is the first hands-on task most IBM MQ administrators perform. DEFINE QLOCAL creates the named mailbox applications use for MQPUT and MQGET on that queue manager. Done well, the definition sets depth limits, persistence defaults, security-related flags, and a clear description for operations. Done poorly, you get queue full at 2 a.m., non-persistent payment messages, or 2035 errors in test. This tutorial walks through runmqsc syntax, every attribute you should consider on day one, naming standards, REPLACE for DevOps pipelines, post-define verification, and how local queue definition differs from transmission or system queues.
On distributed systems, run runmqsc QM1 (your queue manager name). The prompt shows 1 then accepts MQSC terminated by semicolons. MQ Explorer offers equivalent panels. REST admin and Terraform IBM MQ provider generate the same underlying DEFINE. Scripts pipe MQSC files: runmqsc QM1 < define_orders.mqsc. Always target the correct queue manager in multi-QM hosts.
Minimal lab definition: DEFINE QLOCAL('LAB.TEST') REPLACE. Production adds MAXDEPTH, MAXMSGL, DEFPSIST, GET, PUT, SHARE, DESCR, and sometimes TRIGGER, CLUSTER, or BOQNAME. Match attributes to the recovery tier documented in your standards catalog.
123456789DEFINE QLOCAL('ORDERS.IN') REPLACE + MAXDEPTH(500000) + MAXMSGL(4194304) + DEFPSIST(YES) + GET(ENABLED) PUT(ENABLED) + SHARE(ENABLED) + DESCR('Inbound customer orders - Payments team') DISPLAY QLOCAL('ORDERS.IN') ALL * Test put/get after granting authority to app user
| Attribute | Why set it explicitly |
|---|---|
| MAXDEPTH | Prevent unbounded backlog |
| MAXMSGL | Reject oversize messages early |
| DEFPSIST | Default durability for business data |
| GET / PUT | Document allowed operations |
| SHARE | Enable competing consumers |
| DESCR | Owner and purpose for ops |
MQSC accepts GET(YES) or GET(ENABLED) on many releases—both enable gets. Your site should pick one style in standards documents for script consistency. DISPLAY output may normalize to one form. The important outcome is applications can open for input when OAM allows.
Use uppercase on z/OS traditions; mixed case may work on distributed depending on platform case sensitivity. Common patterns: APPLICATION.FUNCTION.DIRECTION (PAYMENTS.ORDERS.IN), environment prefix (DEV.PAYMENTS.ORDERS.IN), or flat names under 48 characters. Avoid embedding passwords or PCI data in queue names. Reserve SYSTEM.* for IBM objects unless you know the implications.
USAGE(NORMAL) is default for application queues. USAGE(XMITQ) defines a transmission queue—usually created with channel configuration, not business apps. Defining XMITQ wrong blocks channel startup. Initiation queues and dead-letter queues are still QLOCAL with specific roles—see dedicated tutorials.
Add STGCLASS for page set placement, QSGDISP for queue sharing group disposition, and CFSTRUCT for shared queues. CMDSCOPE controls which QSG members execute the command. Coordinate with systems programming before QSGDISP(SHARED).
Use ALTER QLOCAL to change one attribute on an existing queue. DEFINE ... REPLACE replaces the whole definition in script style. ALTER MAXDEPTH is common during capacity events. Some attributes cannot change while queues are open—check documentation for your version.
DELETE QLOCAL requires empty queue and no open handles unless PURGE options on your platform. Never delete system queues casually. Change control should list dependent applications before delete.
DEFINE QLOCAL is installing a new mailbox in the post office with a nameplate and rules about how big it can get and whether letters must be photocopied into a safe (persistent).
Write a full DEFINE for a high-volume non-persistent metrics queue and a persistent orders queue.
Script fails: object already exists. How does REPLACE fix it?
List verification steps before telling the app team a new queue is ready.
1. DEFINE QLOCAL creates:
2. REPLACE on DEFINE means:
3. After DEFINE, verify with:
4. DESCR on DEFINE QLOCAL is: