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. With these options you can:

MQOPEN option for cluster queue

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. 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 that 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 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:
  1. You cannot browse messages on a remote queue; do not open a remote queue using the MQOO_BROWSE option.
  2. You cannot specify this option when opening a distribution list. For further information about distribution lists, see Distribution lists.

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 3 to see how the setting of these attributes affects the type of access that 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
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:

Notes:
  1. You cannot remove messages from a remote queue. Therefore you cannot open a remote queue using any of the MQOO_INPUT_* options.
  2. 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

If you want 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 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 might 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(R) environment on z/OS(TM), if you use the MQOPEN call when the queue manager is in a quiescing state, the call always fails. In other z/OS environments, i5/OS, Windows systems and in UNIX(R) 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.

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 manger 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. ResolvedQMgrNameis the name of the local queue manager hosting the transmission queue.