Using the options of the MQOPEN call

In the options parameter of the MQOPEN call, you must choose one or more options to control the access that you are given to the object that you are opening.

MQOPEN option for cluster queue

Open a queue and specify that all messages put to that queue must be directed to the same instance of it.

The binding that is used for the queue handle is taken from the DefBind queue attribute, which can take the value MQBND_BIND_ON_OPEN, MQBND_BIND_NOT_FIXED, or MQBND_BIND_ON_GROUP.

To route all messages put to a queue using MQPUT 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.

To specify that all messages in a message groups put to a queue using MQPUT are allocated to the same destination instance, use the MQOO_BIND_ON_GROUP option on the MQOPEN call.

Either MQOO_BIND_ON_OPEN or MQOO_BIND_ON_GROUP must be specified when using message groups with clusters to ensure that all messages in the group are processed at the same destination.

If you do not specify any of these options the default MQOO_BIND_AS_Q_DEF is used.

If you specify the name of a queue manager in the MQOD, the queue at that queue manager is selected. If the queue manager name is blank, any instance can be selected. See MQOPEN and clusters for more information.

If you open a cluster queue using a QALIAS definition, some queue attributes are defined by the alias queue, and not the base queue. Cluster attributes are among the attributes of the base queue definition that are overridden by the alias queue. For example, in the following snippet, the cluster queue is opened with MQOO_BIND_NOT FIXED and not MQOO_BIND_ON_OPEN. The cluster queue definition is advertised throughout the cluster and the alias queue definition is local to the queue manager.

DEFINE QLOCAL(CLQ1) CLUSTER(MYCLUSTER) DEFBIND(OPEN) REPLACE
DEFINE QALIAS(ACLQ1) TARGET(CLQ1) DEFBIND(NOTFIXED) REPLACE

MQOPEN option for putting messages

To open a queue or topic so that you can 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.

Note:

You cannot browse messages on a remote queue; do not 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.
Use the MQOO_CO_OP in conjunction with MQOO_BROWSE if you are using cooperative browsing; see Options

MQOPEN options for removing messages

Three options control the opening of a queue 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 1 to see how the setting of these attributes affects the type of access that you will be given when you use this option.

Table 1. 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

Note: * 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 1 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.

Note:

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 Inquiring about and setting object attributes ).

To open an object so that you can inquire about its attributes, use the MQOO_INQUIRE option.

Note: You cannot specify this option when opening a distribution list.

MQOPEN options relating to message context

To be able to associate context information with a message when you put it on a queue, you must 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, see Message context and Controlling message context information.

MQOPEN option for alternative 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 might want the queue manager to check the authorization of the user they are working for, 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 alternative 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

If you use the MQOPEN call when the queue manager is in a quiescing state, the call might fail, depending on which environment you are using.

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 and Multiplatforms environments, the call fails when the queue manager is quiescing only if you use the MQOO_FAIL_IF_QUIESCING option of the MQOPEN call.

MQOPEN option for resolving local queue names

When you open a local, alias or model queue, the local queue is returned.

However, when you open a remote queue or cluster queue, the ResolvedQName and ResolvedQMgrName fields of the MQOD structure are filled with the names of the remote queue and remote queue manager found in the remote queue definition, or with the chosen remote cluster queue.

Use the MQOO_RESOLVE_LOCAL_Q option of the MQOPEN call to fill the ResolvedQName in the MQOD structure with the name of the local queue that was opened. The ResolvedQMgrName is similarly filled with the name of the local queue manager hosting the local queue. This field is available only with Version 3 of the MQOD structure; if the structure is less than Version 3, MQOO_RESOLVE_LOCAL_Q is ignored without an error being returned.

If you specify MQOO_RESOLVE_LOCAL_Q when opening, for example, a remote queue, ResolvedQName is the name of the transmission queue to which messages will be put. ResolvedQMgrName is the name of the local queue manager hosting the transmission queue.