Opening objects using the MQOPEN call

Opening objects using the MQOPEN call

As input to the MQOPEN call, supply:

A connection handle. For CICS applications on z/OS, you can specify the constant MQHC_DEF_HCONN (which has the value zero), or use the connection handle returned by the MQCONN or MQCONNX call. For other programs, always use the connection handle returned by the MQCONN or MQCONNX call.
A description of the object you want to open, using the object descriptor structure (MQOD).
One or more options that control the action of the call.

The output from MQOPEN is:

An object handle that represents your access to the object. Use this on input to any subsequent MQI calls.
A modified object-descriptor structure, if you are creating a dynamic queue (and it is supported on your platform).
A completion code.
A reason code.

Scope of an object handle

The scope of an object handle (Hobj) is the same as the scope of a connection handle (Hconn). This is covered in Scope of MQCONN or MQCONNX and Shared (thread independent) connections with MQCONNX, however there are additional considerations in some environments:

CICS

In a CICS program, you can use the handle only within the same CICS task from which you made the MQOPEN call.

IMS and z/OS batch

In the IMS and batch environments, you can use the handle within the same task, but not within any subtasks.

MQSeries for VSE/ESA

In the VSE/ESA environment, you can use the handle only within the same application transaction from which you made the MQOPEN call.

Descriptions of the parameters of the MQOPEN call are given in WebSphere MQ Application Programming Reference.
The following sections describe the information supply as input to MQOPEN.

Identifying objects (the MQOD structure)

Use the MQOD structure to identify the object you want to open. This structure is an input parameter for the MQOPEN call. (The structure is modified by the queue manager when you use the MQOPEN call to create a dynamic queue.)
For full details of the MQOD structure see WebSphere MQ Application Programming Reference.
For information about using the MQOD structure for distribution lists, see Using the MQOD structure under Distribution lists.

Name resolution

A Queue manager alias is a remote queue definition without an RNAME field.
When you open a WebSphere MQ queue, the MQOPEN call performs a name resolution function on the queue name you specify. This determines on which queue the queue manager performs subsequent operations. This means that when you specify the name of an alias queue or a remote queue in your object descriptor (MQOD), the call resolves the name either to a local queue or to a transmission queue. If a queue is opened for any type of input, browse, or set, it resolves to a local queue if there is one, and fails otherwise. It resolves to a nonlocal queue only if it is opened for output only, inquire only, or output and inquire only. See Table 2 for an overview of the name resolution process. Note that the name you supply in ObjectQMgrName is resolved before that in ObjectName.
Table 2 also shows how you can use a local definition of a remote queue to define an alias for the name of a queue manager. This allows you to select which transmission queue is used when you put messages on a remote queue, so you could, for example, use a single transmission queue for messages destined for many remote queue managers.
To use the following table, first read down the two left-hand columns, under the heading "Input to MQOD", and select the appropriate case. Then read across the corresponding row, following any instructions. Following the instructions in the "Resolved names" columns, you can either return to the "Input to MQOD" columns and insert values as directed, or you can exit the table with the results supplied. For example, you may be required to input ObjectName.

Table 2. Resolving queue names when using MQOPEN

Input to MQOD Resolved names

ObjectName ObjectName Transmission queue

HEADERS="COL1 WQ30" Blank or local queue manager HEADERS="COL1 COL2" Local queue with no CLUSTER attribute HEADERS="COL3 WQ31" Local queue manager HEADERS="COL3 COL4" Input ObjectName HEADERS="COL3 COL5" Not applicable (local queue used)

HEADERS="COL1 WQ30" Blank queue manager HEADERS="COL1 COL2" Local queue with CLUSTER attribute HEADERS="COL3 WQ31" Workload management selected cluster queue manager or specific cluster queue manager selected on PUT HEADERS="COL3 COL4" Input ObjectName HEADERS="COL3 COL5" SYSTEM.CLUSTER. TRANSMIT.QUEUE and local queue used
SYSTEM.QSG. TRANSMIT.QUEUE (see note)

HEADERS="COL1 WQ30" Local queue manager HEADERS="COL1 COL2" Local queue with CLUSTER attribute HEADERS="COL3 WQ31" Local queue manager HEADERS="COL3 COL4" Input ObjectName HEADERS="COL3 COL5" Not applicable (local queue used)

HEADERS="COL1 WQ30" Blank or local queue manager HEADERS="COL1 COL2" Model queue HEADERS="COL3 WQ31" Local queue manager HEADERS="COL3 COL4" Generated name HEADERS="COL3 COL5" Not applicable (local queue used)

HEADERS="COL1 WQ30" Blank or local queue manager HEADERS="COL1 COL2" Alias queue with or without CLUSTER attribute HEADERS="COL3 WQ31" Perform name resolution again with ObjectQMgrName unchanged, and input ObjectName set to the BaseQName in the alias queue definition object. Must not resolve to an alias queue HEADERS="COL3 COL4" HEADERS="COL3 COL5"

HEADERS="COL1 WQ30" Blank or local queue manager HEADERS="COL1 COL2" Local definition of a remote queue with or without CLUSTER attribute HEADERS="COL3 WQ31" Perform name resolution again with ObjectQMgrName set to RemoteQMgrName, and ObjectName set to RemoteQName. Must not resolve remote queues HEADERS="COL3 COL4" HEADERS="COL3 COL5" Name of XmitQName attribute, if non-blank; otherwise RemoteQMgrName in the remote queue definition object.
SYSTEM.QSG. TRANSMIT.QUEUE (see note)

HEADERS="COL1 WQ30" Blank queue manager HEADERS="COL1 COL2" No matching local object; cluster queue found HEADERS="COL3 WQ31" Workload management selected cluster queue manager or specific cluster queue manager selected on PUT HEADERS="COL3 COL4" Input ObjectName HEADERS="COL3 COL5" SYSTEM.CLUSTER. TRANSMIT.QUEUE
SYSTEM.QSG. TRANSMIT.QUEUE (see note)

HEADERS="COL1 WQ30" Blank or local queue manager HEADERS="COL1 COL2" No matching local object; cluster queue not found HEADERS="COL3 WQ31" HEADERS="COL3 COL4" Error, queue not found HEADERS="COL3 COL5" Not applicable

HEADERS="COL1 WQ30" Name of a local transmission queue HEADERS="COL1 COL2" (Not resolved) HEADERS="COL3 WQ31" Input ObjectQMgrName HEADERS="COL3 COL4" Input ObjectName HEADERS="COL3 COL5" Input ObjectQMgrName
SYSTEM.QSG. TRANSMIT.QUEUE (see note)

HEADERS="COL1 WQ30" Queue manager alias definition (RemoteQMgrName may be the local queue manager) HEADERS="COL1 COL2" (Not resolved, remote queue) HEADERS="COL3 WQ31" Perform name resolution again with ObjectQMgrName set to RemoteQMgrName. Must not resolve to remote queues HEADERS="COL3 COL4" Input ObjectName HEADERS="COL3 COL5" Name of XmitQName attribute, if non-blank; otherwise RemoteQMgrName in the remote queue definition object.
SYSTEM.QSG. TRANSMIT.QUEUE (see note)

HEADERS="COL1 WQ30" Queue manager is not the name of any local object; cluster queue managers or queue manager alias found HEADERS="COL1 COL2" (Not resolved) HEADERS="COL3 WQ31" ObjectQMgrName or specific cluster queue manager selected on PUT HEADERS="COL3 COL4" Input ObjectName HEADERS="COL3 COL5" SYSTEM.CLUSTER. TRANSMIT.QUEUE
SYSTEM.QSG. TRANSMIT.QUEUE (see note)

HEADERS="COL1 WQ30" Queue manager is not the name of any local object; no cluster objects found HEADERS="COL1 COL2" (Not resolved) HEADERS="COL3 WQ31" Input ObjectQMgrName HEADERS="COL3 COL4" Input ObjectName HEADERS="COL3 COL5" DefXmitQName attribute of the queue manager where DefXmitQName is supported.
SYSTEM.QSG. TRANSMIT.QUEUE (see note)

HEADERS="COL1 WQ30 COL2 COL3 WQ31 COL4 COL5" COLSPAN="5"
The SYSTEM.QSG.TRANSMIT.QUEUE is used if local and remote queue managers are in the same queue-sharing group, intra-group queuing is enabled, and small messages are being put.

Notes:

BaseQName is the name of the base queue from the definition of the alias queue.
RemoteQName is the name of the remote queue from the local definition of the remote queue.
RemoteQMgrName is the name of the remote queue manager from the local definition of the remote queue.
XmitQName is the name of the transmission queue from the local definition of the remote queue.
When using WebSphere MQ for z/OS queue managers that are part of a queue-sharing group (QSG), the name of the QSG can be used instead of the local queue manager name in Table 2.

Opening an alias queue also opens the base queue to which the alias resolves, and opening a remote queue also opens the transmission queue. Therefore you cannot delete either the queue you specify or the queue to which it resolves while the other one is open.
The resolved queue name and the resolved queue manager name are stored in the ResolvedQName and ResolvedQMgrName fields in the MQOD.
For more information about name resolution in a distributed queuing environment see WebSphere MQ Intercommunication.

Using the options of the MQOPEN call

In the Options parameter of the MQOPEN call, choose one or more options to control the access you are given to the object you are opening. With these options you can:

Open a queue and specify that all messages put to that queue must be directed to the same instance of it
Open a queue to allow you to put messages on it
Open a queue to allow you to browse messages on it
Open a queue to allow you to remove messages from it
Open an object to allow you to inquire about and set its attributes (but you can set the attributes of queues only)
Associate context information with a message
Nominate an alternate user identifier to be used for security checks
Control the call if the queue manager is in a quiescing state

MQOPEN option for cluster queue

To specify that all messages MQPUT to a queue are to be routed to the same queue manager by the same route use the MQOO_BIND_ON_OPEN option on the MQOPEN call. To specify that a destination is to be selected at MQPUT time, that is, on a message-by-message basis, use the MQOO_BIND_NOT_FIXED option on the MQOPEN call. If you specify neither of these options the default, MQOO_BIND_AS_Q_DEF, is used. In this case the binding used for the queue handle is taken from the DefBind queue attribute, which can take the value MQBND_BIND_ON_OPEN or MQBND_BIND_NOT_FIXED. If the queue you open is not a cluster queue the MQOO_BIND_* options are ignored. If you specify the name of the local queue manager in the MQOD the local instance of the cluster queue is selected. If the queue manager name is blank, any instance can be selected. See WebSphere MQ Queue Manager Clusters for more information.

MQOPEN option for putting messages

To open a queue in order to put messages on it, use the MQOO_OUTPUT option.

MQOPEN option for browsing messages

To open a queue so that you can browse the messages on it, use the MQOPEN call with the MQOO_BROWSE option. This creates a browse cursor that the queue manager uses to identify the next message on the queue. For more information, see Browsing messages on a queue.
Notes:

You cannot browse messages on a remote queue. Therefore you cannot open a remote queue using the MQOO_BROWSE option.
You cannot specify this option when opening a distribution list. For further information about distribution lists, see Distribution lists.

MQOPEN options for removing messages

There are three options that control the opening of a queue in order to remove messages from it. You can use only one of them in any MQOPEN call. These options define whether your program has exclusive or shared access to the queue. Exclusive access means that, until you close the queue, only you can remove messages from it. If another program attempts to open the queue to remove messages, its MQOPEN call fails. Shared access means that more than one program can remove messages from the queue.
The most advisable approach is to accept the type of access that was intended for the queue when the queue was defined. The queue definition involved the setting of the Shareability and the DefInputOpenOption attributes. To accept this access, use the MQOO_INPUT_AS_Q_DEF option. Refer to Table 3 to see how the setting of these attributes affects the type of access you will be given when you use this option.

Table 3. How queue attributes and options of the MQOPEN call affect access to queues

Queue attributes Type of access with MQOPEN options

Shareability DefInputOpenOption AS_Q_DEF SHARED EXCLUSIVE

SHAREABLE SHARED shared shared exclusive

SHAREABLE EXCLUSIVE exclusive shared exclusive

NOT_SHAREABLE* SHARED* exclusive exclusive exclusive

NOT_SHAREABLE EXCLUSIVE exclusive exclusive exclusive

HEADERS="COL1 COL3" COLSPAN="5"
* Although you can define a queue to have this combination of attributes, the default input open option is overridden by the shareability attribute.

Alternatively:

If you know that your application can work successfully even if other programs can remove messages from the queue at the same time, use the MQOO_INPUT_SHARED option. Table 3 shows how, in some cases you will be given exclusive access to the queue, even with this option.
If you know that your application can work successfully only if other programs are prevented from removing messages from the queue at the same time, use the MQOO_INPUT_EXCLUSIVE option.

Notes:

You cannot remove messages from a remote queue. Therefore you cannot open a remote queue using any of the MQOO_INPUT_* options.
You cannot specify this option when opening a distribution list. For further information, see Distribution lists.

MQOPEN options for setting and inquiring about attributes

To open a queue so that you can set its attributes, use the MQOO_SET option. You cannot set the attributes of any other type of object (see Chapter 12, Inquiring about and setting object attributes).
To open an object so that you can inquire about its attributes, use the MQOO_INQUIRE option.
You cannot specify this option when opening a distribution list.

MQOPEN options relating to message context

If you want to be able to associate context information with a message when you put it on a queue, use one of the message context options when you open the queue.
The options allow you to differentiate between context information that relates to the user who originated the message, and that which relates to the application that originated the message. Also, you can opt to set the context information when you put the message on the queue, or you can opt to have the context taken automatically from another queue handle.
For more information about the subject of message context, see Message context.

MQOPEN option for alternate user authority

When you attempt to open an object using the MQOPEN call, the queue manager checks that you have the authority to open that object. If you are not authorized, the call fails.
However, server programs may want the queue manager to check the authorization of the user on whose behalf they are working, rather than the server's own authorization. To do this, they must use the MQOO_ALTERNATE_USER_AUTHORITY option of the MQOPEN call, and specify the alternate user ID in the AlternateUserId field of the MQOD structure. Typically, the server would get the user ID from the context information in the message it is processing.

MQOPEN option for queue manager quiescing

In the CICS environment on z/OS, if you use the MQOPEN call when the queue manager is in a quiescing state, the call always fails. In other z/OS environments, OS/400, OS/2, Windows systems and in UNIX systems environments, the call fails when the queue manager is quiescing only if you use the MQOO_FAIL_IF_QUIESCING option of the MQOPEN call.

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.

Input to MQOD		Resolved names
	ObjectName		ObjectName	Transmission queue
HEADERS="COL1 WQ30" Blank or local queue manager	HEADERS="COL1 COL2" Local queue with no CLUSTER attribute	HEADERS="COL3 WQ31" Local queue manager	HEADERS="COL3 COL4" Input ObjectName	HEADERS="COL3 COL5" Not applicable (local queue used)
HEADERS="COL1 WQ30" Blank queue manager	HEADERS="COL1 COL2" Local queue with CLUSTER attribute	HEADERS="COL3 WQ31" Workload management selected cluster queue manager or specific cluster queue manager selected on PUT	HEADERS="COL3 COL4" Input ObjectName	HEADERS="COL3 COL5" SYSTEM.CLUSTER. TRANSMIT.QUEUE and local queue used SYSTEM.QSG. TRANSMIT.QUEUE (see note)
HEADERS="COL1 WQ30" Local queue manager	HEADERS="COL1 COL2" Local queue with CLUSTER attribute	HEADERS="COL3 WQ31" Local queue manager	HEADERS="COL3 COL4" Input ObjectName	HEADERS="COL3 COL5" Not applicable (local queue used)
HEADERS="COL1 WQ30" Blank or local queue manager	HEADERS="COL1 COL2" Model queue	HEADERS="COL3 WQ31" Local queue manager	HEADERS="COL3 COL4" Generated name	HEADERS="COL3 COL5" Not applicable (local queue used)
HEADERS="COL1 WQ30" Blank or local queue manager	HEADERS="COL1 COL2" Alias queue with or without CLUSTER attribute	HEADERS="COL3 WQ31" Perform name resolution again with ObjectQMgrName unchanged, and input ObjectName set to the BaseQName in the alias queue definition object. Must not resolve to an alias queue	HEADERS="COL3 COL4"	HEADERS="COL3 COL5"
HEADERS="COL1 WQ30" Blank or local queue manager	HEADERS="COL1 COL2" Local definition of a remote queue with or without CLUSTER attribute	HEADERS="COL3 WQ31" Perform name resolution again with ObjectQMgrName set to RemoteQMgrName, and ObjectName set to RemoteQName. Must not resolve remote queues	HEADERS="COL3 COL4"	HEADERS="COL3 COL5" Name of XmitQName attribute, if non-blank; otherwise RemoteQMgrName in the remote queue definition object. SYSTEM.QSG. TRANSMIT.QUEUE (see note)
HEADERS="COL1 WQ30" Blank queue manager	HEADERS="COL1 COL2" No matching local object; cluster queue found	HEADERS="COL3 WQ31" Workload management selected cluster queue manager or specific cluster queue manager selected on PUT	HEADERS="COL3 COL4" Input ObjectName	HEADERS="COL3 COL5" SYSTEM.CLUSTER. TRANSMIT.QUEUE SYSTEM.QSG. TRANSMIT.QUEUE (see note)
HEADERS="COL1 WQ30" Blank or local queue manager	HEADERS="COL1 COL2" No matching local object; cluster queue not found	HEADERS="COL3 WQ31"	HEADERS="COL3 COL4" Error, queue not found	HEADERS="COL3 COL5" Not applicable
HEADERS="COL1 WQ30" Name of a local transmission queue	HEADERS="COL1 COL2" (Not resolved)	HEADERS="COL3 WQ31" Input ObjectQMgrName	HEADERS="COL3 COL4" Input ObjectName	HEADERS="COL3 COL5" Input ObjectQMgrName SYSTEM.QSG. TRANSMIT.QUEUE (see note)
HEADERS="COL1 WQ30" Queue manager alias definition (RemoteQMgrName may be the local queue manager)	HEADERS="COL1 COL2" (Not resolved, remote queue)	HEADERS="COL3 WQ31" Perform name resolution again with ObjectQMgrName set to RemoteQMgrName. Must not resolve to remote queues	HEADERS="COL3 COL4" Input ObjectName	HEADERS="COL3 COL5" Name of XmitQName attribute, if non-blank; otherwise RemoteQMgrName in the remote queue definition object. SYSTEM.QSG. TRANSMIT.QUEUE (see note)
HEADERS="COL1 WQ30" Queue manager is not the name of any local object; cluster queue managers or queue manager alias found	HEADERS="COL1 COL2" (Not resolved)	HEADERS="COL3 WQ31" ObjectQMgrName or specific cluster queue manager selected on PUT	HEADERS="COL3 COL4" Input ObjectName	HEADERS="COL3 COL5" SYSTEM.CLUSTER. TRANSMIT.QUEUE SYSTEM.QSG. TRANSMIT.QUEUE (see note)
HEADERS="COL1 WQ30" Queue manager is not the name of any local object; no cluster objects found	HEADERS="COL1 COL2" (Not resolved)	HEADERS="COL3 WQ31" Input ObjectQMgrName	HEADERS="COL3 COL4" Input ObjectName	HEADERS="COL3 COL5" DefXmitQName attribute of the queue manager where DefXmitQName is supported. SYSTEM.QSG. TRANSMIT.QUEUE (see note)
HEADERS="COL1 WQ30 COL2 COL3 WQ31 COL4 COL5" COLSPAN="5" The SYSTEM.QSG.TRANSMIT.QUEUE is used if local and remote queue managers are in the same queue-sharing group, intra-group queuing is enabled, and small messages are being put.

Queue attributes		Type of access with MQOPEN options
Shareability	DefInputOpenOption	AS_Q_DEF	SHARED	EXCLUSIVE
SHAREABLE	SHARED	shared	shared	exclusive
SHAREABLE	EXCLUSIVE	exclusive	shared	exclusive
NOT_SHAREABLE*	SHARED*	exclusive	exclusive	exclusive
NOT_SHAREABLE	EXCLUSIVE	exclusive	exclusive	exclusive
HEADERS="COL1 COL3" COLSPAN="5" * Although you can define a queue to have this combination of attributes, the default input open option is overridden by the shareability attribute.