Opening objects using the MQOPEN call

As input to the MQOPEN call, you must 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 you must 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

Note:

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 3 for an overview of the name resolution process. Note that the name you supply in ObjectQMgrName is resolved before that in ObjectName.

Table 3 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 3. Resolving queue names when using MQOPEN

Notes:

1. BaseQName is the name of the base queue from the definition of the alias queue.

2. RemoteQName is the name of the remote queue from the local definition of the remote queue.

3. RemoteQMgrName is the name of the remote queue manager from the local definition of the remote queue.

4. XmitQName is the name of the transmission queue from the local definition of the remote queue.

5. 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 3.

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, you must 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:

1. You cannot browse messages on a remote queue. Therefore you cannot 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

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 4 to see how the setting of these attributes affects the type of access you will be given when you use this option.

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

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 4 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:

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

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