DEFINE (MQSC)

DEFINE is the MQSC verb that creates IBM MQ objects in the queue manager repository. When you type DEFINE QLOCAL('PAYMENTS.IN') in runmqsc, the command server validates the object type, name, and attributes, then stores the definition on disk so the queue manager can honor MQOPEN from applications. DEFINE does not move business data—it only declares that a named queue, channel, listener, or topic exists with specific properties. Every environment built through infrastructure-as-code depends on repeatable DEFINE scripts checked into Git. This tutorial explains DEFINE syntax, the most common object types, essential attributes beginners must understand, REPLACE for promotion pipelines, typical AMQ errors, verification with DISPLAY, and how DEFINE relates to ALTER and DELETE in the object lifecycle.

Syntax Pattern

The general form is DEFINE object_type('object_name') attribute(value) attribute(value). Object names are usually uppercase by convention but MQ accepts mixed case in quotes. String attributes use single quotes. Numeric attributes use integers without quotes. Multiple lines continue with + at end of line. Each command ends with a semicolon. The command server responds with one or more lines per command, including AMQ8006I display-style confirmations or AMQ error codes when validation fails.

1
2
3
4
5
6
7
8
9
10
11
DEFINE QLOCAL('ORDERS.IN') REPLACE +
  DESCR('Inbound order work queue') +
  MAXDEPTH(100000) MAXMSGL(4194304) +
  DEFPSIST(YES) BOTHRESH(5) +
  BOQNAME('ORDERS.DLQ') GET(ENABLED) PUT(ENABLED)
* REPLACE — create or overwrite definition (DevOps friendly)
* MAXDEPTH — max messages; PUT fails with 2053 when full
* MAXMSGL — max bytes per message
* DEFPSIST(YES) — default new messages persistent
* BOTHRESH — backouts before message to BOQNAME
* BOQNAME — dead-letter queue for poison messages

DEFINE QLOCAL — Local Queues

QLOCAL is the workhorse queue type. Applications PUT and GET here; messages are stored on this queue manager until consumed. MAXDEPTH caps backlog—critical for capacity. MAXMSGL must exceed your largest expected payload. DEFPSIST sets default persistence for messages unless the put overrides it. GET and PUT ENABLED allow applications to open for input or output; DISABLE is used for maintenance queues. SHARE determines whether multiple applications can open simultaneously. DEFBIND and CLUSTER matter when the queue participates in a cluster. Beginners should define a DLQ first, then work queues with BOQNAME pointing to it.

DEFINE CHANNEL

DEFINE CHANNEL creates a channel definition, not an active TCP session. You must specify CHLTYPE: SDR (sender), RCVR (receiver), SVRCONN (client connection), CLNTCONN, CLUSSDR, CLUSRCVR, and others per IBM documentation. Sender channels need XMITQ naming the transmission queue. Receiver channels pair with a LISTENER on a port. SVRCONN channels need MCAUSER and often SSL parameters for production. After DEFINE, START CHANNEL initiates the connection for message channels. Wrong CHLTYPE is a frequent exam and interview mistake—same channel name on both sides but different types.

1
2
3
4
5
6
DEFINE CHANNEL('HUB.TO.BRANCH') CHLTYPE(SDR) TRPTYPE(TCP) +
  CONNAME('branch.example.com(1414)') XMITQ('SYSTEM.DEAD.LETTER.QUEUE') +
  REPLACE
DEFINE CHANNEL('HUB.TO.BRANCH') CHLTYPE(RCVR) TRPTYPE(TCP) REPLACE
* SDR — outbound; needs CONNAME and XMITQ on sending QM
* RCVR — inbound; partner SDR connects to your listener

DEFINE LISTENER, TOPIC, SUB, PROCESS

LISTENER defines the TCP port that accepts inbound connections—PORT(1414) is the classic example. CONTROL(QMGR) ties listener lifecycle to queue manager start in many estates. TOPIC defines a node in the topic tree with TOPICSTR for the string hierarchy. SUB creates a subscription routing matching publications to DEST subscriber queue. PROCESS supports triggering—application name and parameters when a trigger fires. Each object type has mandatory and optional attributes; IBM Knowledge Center lists valid combinations per MQ version.

REPLACE and Like Parameters

REPLACE is the most important modifier for automation. Without it, a second run of your script fails. Some teams use DEFINE like('TEMPLATE.QUEUE') for QLOCAL to copy attributes from an existing queue—useful for standardizing hundreds of queues from one gold copy. Verify the template queue exists and is audited before cloning security-sensitive attributes.

Common DEFINE Errors

• AMQ object already exists — use REPLACE or DELETE first.
• AMQ invalid attribute — typo in attribute name or value not allowed for CHLTYPE.
• AMQ not authorized — OS user lacks MQSC authority for object class.
• BOQNAME points to non-existent queue — define DLQ before work queues.
• XMITQ missing on SDR — sender channel cannot start without transmission queue.

Explainer: Blueprint Before Building

DEFINE is the architect's blueprint: it says there will be a mailbox named ORDERS.IN with a maximum pile height (MAXDEPTH) and whether letters must be filed permanently (DEFPSIST). Workers (applications) only use the mailbox after the blueprint is approved and registered with the building (queue manager).

Step-by-Step: First Application Queue

1. runmqsc QM1 and DISPLAY QMGR to confirm connection.
2. DEFINE QLOCAL('APP.DLQ') MAXDEPTH(50000) DEFPSIST(YES) REPLACE.
3. DEFINE QLOCAL('APP.WORK') with BOQNAME('APP.DLQ') BOTHRESH(5) REPLACE.
4. DISPLAY QLOCAL('APP.WORK') ALL and archive output in ticket.
5. setmqaut grants for application group put/get on APP.WORK.
6. Smoke test with amqsput and amqsget in lab.

Explain Like I'm Five: DEFINE

DEFINE is telling the mail building to add a new mailbox with rules: how big it can get, whether letters stay even if the building restarts, and where broken letters go.

Practice Exercises

Exercise 1

Write a script defining DLQ, work queue, and SDR/RCVR pair with REPLACE.

Exercise 2

Intentionally omit MAXDEPTH; document platform default with DISPLAY.

Exercise 3

List five attributes you would never copy blindly from a template without review.

Frequently Asked Questions

Test Your Knowledge