MQOPEN

After MQCONN gives you a connection handle, MQOPEN selects which mailbox you will use: ORDERS.IN for outbound work, PAYMENTS.REPLY for responses, or a topic object for publish. MQOPEN fills an object descriptor (MQOD) with the queue or topic name, sets open options describing intent (put, get, browse, inquire), and returns Hobj—the handle passed to every subsequent put or get on that object. Open options are not hints; the queue manager enforces them. Opening with MQOO_OUTPUT when your user lacks put authority fails with 2035 even if the queue exists. Opening for input on a transmission queue may be wrong architecturally even when authority allows it. This tutorial explains MQOD fields, open option combinations, alias and model queues, dynamic queues, inquire attributes, failure reason codes, MQCLOSE pairing, and how open interacts with PUT(DISABLED) queue attributes and OAM profiles.

Object Descriptor (MQOD)

The ObjectName field holds the queue name up to 48 characters (platform limits documented by IBM). ObjectType is usually MQOT_Q for queues or MQOT_TOPIC for publish. For dynamic queues, set ObjectType MQOT_Q and DynamicQName pattern; the queue manager creates a temporary queue name returned in MQOD. Compare static opens where the name is fixed in configuration versus model-driven reply queues created per request. ObjectQMgrName is blank when the object is on the connected queue manager; cluster and federated scenarios may populate it for queue manager resolution.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
MQOD od = {MQOD_DEFAULT};
MQLONG openOptions = MQOO_OUTPUT | MQOO_FAIL_IF_QUIESCING;
MQHOBJ Hobj;
 
strncpy(od.ObjectName, "ORDERS.IN", MQ_Q_NAME_LENGTH);
 
MQOPEN(Hconn,
       &od,
       openOptions,
       &Hobj,
       &compCode,
       &reason);
 
if (compCode != MQCC_OK) {
  /* 2085 unknown name, 2035 not authorized */
}

Authority and Object Attributes

OAM grants dsp, put, and get on queue profiles. MQOPEN checks the combination you request: MQOO_OUTPUT needs put authority. PUT(DISABLED) on the queue rejects application puts even when authority exists—open may succeed but MQPUT fails later, or open fails depending on options; verify behavior on your release. INHIBIT(GET) blocks consumers similarly. Transmission queues and system queues have restricted patterns—applications should not open SYSTEM.ADMIN queues casually.

Alias, Remote, and Cluster Queues

Applications open ALIAS.ORDERS which resolves to QLOCAL on another queue manager via QREMOTE and channel path. The open succeeds on the local name; routing happens on put. Cluster queues may resolve via cluster repository to different physical queues—open still uses the cluster queue name presented to the application. Misconfigured alias targets produce 2085 or put-time 2082/2085 family errors. Beginners should trace DISPLAY QALIAS and DISPLAY QREMOTE when open fails on a familiar name.

Explainer: Opening Your PO Box Door

MQOPEN is unlocking a specific PO box inside the post office you already entered with MQCONN. You tell the clerk whether you need to drop letters in (OUTPUT), pick letters out (INPUT), or only peek through the glass (BROWSE).

Dynamic and Model Queues

Request/reply patterns open a model queue definition with MQOO_INPUT_SHARED or exclusive as designed; the queue manager creates a dynamic queue name like AMQ.*.GUID. Your application must read DynamicQName from MQOD after open and pass that name to the partner in ReplyToQ. Close dynamic queues with MQCLOSE options that delete them when done—otherwise temporary queues leak until queue manager restart policies clean them.

Inquire Without Consuming

Monitoring tools open with MQOO_INQUIRE and call MQINQ for CURDEPTH, MAXDEPTH, and IPPROCS. Adding MQOO_BROWSE supports sampling first message length without removal. Avoid MQOO_INPUT on production backlog queues for monitors—accidental get removes messages. Separate read-only service accounts with browse authority only.

Multiple Opens and Handles

One connection may hold many Hobj values simultaneously—input queue and reply queue in the same program. Each requires MQCLOSE. Reusing one Hobj after close without reopening causes 2019 handle errors. Some frameworks pool opens; understand lifecycle in Spring JmsTemplate or message-driven beans where sessions hide repeated MQOPEN.

Topics and MQOPEN

Publish/subscribe uses topic objects or topic strings with different open patterns in modern MQ. MQOPEN on a topic with appropriate options establishes publication handle. Durable subscribers use subscription objects—often created administratively rather than per message. Distinct from classic QLOCAL depth queues but same Hconn/Hobj discipline applies.

Troubleshooting

1. 2085 — DISPLAY QLOCAL(name) exists? Typo case sensitivity?
2. 2035 — setmqaut or AUTHREC put/get on profile.
3. 2042 — Object type wrong in MQOD ObjectType.
4. 2016 — QMgr quiescing; use FAIL_IF_QUIESCING and retry policy.
5. Handle leak — count DISPLAY CONN for your APPNAME.

Explain Like I'm Five: MQOPEN

MQOPEN is choosing which mailbox slot you want to use after you already got into the post office building.

Practice Exercises

Exercise 1

Write open options for a consumer that only gets and never puts.

Exercise 2

Explain alias queue resolution in three sentences for ORDERS.ALIAS.

Exercise 3

List differences between MQOO_BROWSE and MQOO_INPUT for audit tooling.

Frequently Asked Questions

Test Your Knowledge