Defining Queues

An application cannot open a queue that does not exist. DEFINE is the MQSC command that adds the name to the queue manager. Pick the object type from how the program will use the name: store messages here, route them to another queue manager, publish a second name, or hand the application a template for a short-lived reply queue. Reason code 2085, MQRC_UNKNOWN_OBJECT_NAME, is what you get when that DEFINE never landed on the queue manager the program connected to.

Choose the DEFINE type

QLOCAL is the only one of these that holds application messages on this queue manager. A transmission queue is still a local queue, with USAGE(XMITQ), waiting for a sender channel. The dedicated local-queue page covers MAXDEPTH, DEFPSIST, and z/OS storage class in detail.

Where the command runs

On distributed queue managers, runmqsc QM1 reads MQSC until you end the session. A change script is usually a file piped in: runmqsc QM1 < define-pay-in.mqsc. MQ Explorer and the REST admin API write the same objects. On z/OS, CSQUTIL (or the MQ ISPF panels) submits the same MQSC. STEPLIB must point at your site MQ load library. SYSPRINT is where you read the CSQ message for success or failure.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
//MQDEF   JOB (ACCT),'DEFINE PAY.IN',CLASS=A,MSGCLASS=X,
//             NOTIFY=&SYSUID
//* PARM is the target queue manager. STEPLIB DSNs follow your HLQ.
//MQUTIL  EXEC PGM=CSQUTIL,PARM='CSQ1',REGION=0M
//STEPLIB  DD DSN=MQHLQ.SCSQAUTH,DISP=SHR
//         DD DSN=MQHLQ.SCSQANLE,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
DEFINE QLOCAL('PAY.IN') REPLACE +
       MAXDEPTH(100000) DEFPSIST(YES) +
       DESCR('Payroll inbound - nightly load')
DISPLAY QLOCAL('PAY.IN')
/*
//

Local queue

DEFINE QLOCAL creates the mailbox. Set depth, default persistence, and a DESCR that names the owning team. GET(ENABLED) and PUT(ENABLED) record that applications may open the queue; OAM or RACF still has to allow the user. REPLACE keeps the script safe to rerun.

1
2
3
4
5
6
DEFINE QLOCAL('PAY.IN') REPLACE +
  MAXDEPTH(100000) +
  MAXMSGL(4194304) +
  DEFPSIST(YES) +
  GET(ENABLED) PUT(ENABLED) +
  DESCR('Payroll inbound - nightly load')

Alias queue

DEFINE QALIAS adds a name that resolves to TARGTYPE and TARGET. Applications open PAY.IN. The physical queue can be renamed later by altering the alias, without a code change. The alias itself must exist. Opening an old physical name that you deleted still returns 2085.

1
2
3
DEFINE QALIAS('PAY.IN') REPLACE +
  TARGET('PAY.IN.QL') +
  DESCR('Stable name for the payroll loader')

Remote queue

DEFINE QREMOTE does not store the messages on this queue manager. RNAME is the queue name on the remote queue manager, RQMNAME is that queue manager, and XMITQ is the local transmission queue the sender channel drains. Put to ORDERS.OUT on QM1 and the message waits on the transmission queue until the channel to QM2 is running. A missing QREMOTE is a common 2085 when a developer types the remote queue's physical name on the wrong queue manager.

1
2
3
4
5
DEFINE QREMOTE('ORDERS.OUT') REPLACE +
  RNAME('ORDERS.IN') +
  RQMNAME('QM2') +
  XMITQ('QM2') +
  DESCR('Route orders from QM1 to QM2')

Model queue

DEFINE QMODEL stores a template. When an application opens the model, MQ creates a dynamic queue and returns its generated name, often used as a reply-to queue. DEFTYPE(TEMPDYN) drops the queue when the last input handle closes. You do not DEFINE each reply queue by hand. If the reply arrives after the dynamic queue is gone, the server's put can fail with 2085.

1
2
3
4
DEFINE QMODEL('PAY.REPLY.MODEL') REPLACE +
  DEFTYPE(TEMPDYN) +
  MAXDEPTH(5000) +
  DESCR('Template for payroll reply queues')

After the command succeeds

1. DISPLAY the object on the queue manager the application will connect to.
2. Grant authority to the application user (setmqaut or RACF).
3. Put and get one test message with that user.
4. Store the MQSC in the same change record as the application promote.

Names are case-sensitive on distributed MQ. PAY.IN and pay.in are different objects. z/OS shops usually stay in uppercase. A definition on QM_TEST does nothing for a job that connects to QM_PROD.

ALTER and DELETE

ALTER QLOCAL(name) MAXDEPTH(200000) changes one attribute. DEFINE ... REPLACE rewrites the definition from the script. DELETE QLOCAL requires the queue to be empty and not open, unless your platform's PURGE option applies. Leave SYSTEM.* queues alone unless the operations guide for your version says to change that specific object.

Explain it like I'm five

A queue is a named mailbox. DEFINE QLOCAL builds the mailbox. DEFINE QALIAS is a second sticker on the same box. DEFINE QREMOTE is a note that says "forward this to the mailbox in the other building." DEFINE QMODEL is a stencil: each time someone asks, the post office cuts a small temporary mailbox from the stencil and throws it away when they leave.

Practice exercises

Exercise 1

Write DEFINE commands for a local inbound queue, an alias in front of it, and a remote queue that forwards to another queue manager.

Exercise 2

MQOPEN returns 2085 for PAY.IN. List the DISPLAY commands you would run, and which queue manager they must target.

Exercise 3

A request-reply program uses a model queue. Explain why the reply put can return 2085 even though DEFINE QMODEL succeeded.

Frequently Asked Questions

Test Your Knowledge