Home

 

Options (MQLONG) - input

You must specify at least one of the following options:

See below for details of these options; other options can be specified as required. If more than one option is required, the values can be:

Combinations that are not valid are noted; all other combinations are valid. Only options that are applicable to the type of object specified by ObjDesc are allowed (see Table 80).

Access options: The following options control the type of operations that can be performed on the object:

MQOO_INPUT_AS_Q_DEF

Open queue to get messages using queue-defined default.

The queue is opened for use with subsequent MQGET calls. The type of access is either shared or exclusive, depending on the value of the DefInputOpenOption queue attribute; see Attributes for queues for details.

This option is valid only for local, alias, and model queues; it is not valid for remote queues, distribution lists, and objects that are not queues.

MQOO_INPUT_SHARED

Open queue to get messages with shared access.

The queue is opened for use with subsequent MQGET calls. The call can succeed if the queue is currently open by this or another application with MQOO_INPUT_SHARED, but fails with reason code MQRC_OBJECT_IN_USE if the queue is currently open with MQOO_INPUT_EXCLUSIVE.

This option is valid only for local, alias, and model queues; it is not valid for remote queues, distribution lists, and objects that are not queues.

MQOO_INPUT_EXCLUSIVE

Open queue to get messages with exclusive access.

The queue is opened for use with subsequent MQGET calls. The call fails with reason code MQRC_OBJECT_IN_USE if the queue is currently open by this or another application for input of any type (MQOO_INPUT_SHARED or MQOO_INPUT_EXCLUSIVE).

This option is valid only for local, alias, and model queues; it is not valid for remote queues, distribution lists, and objects that are not queues.

The following notes apply to these options:

MQOO_BROWSE

Open queue to browse messages.

The queue is opened for use with subsequent MQGET calls with one of the following options:

  • MQGMO_BROWSE_FIRST

  • MQGMO_BROWSE_NEXT

  • MQGMO_BROWSE_MSG_UNDER_CURSOR

This is allowed even if the queue is currently open for MQOO_INPUT_EXCLUSIVE. An MQOPEN call with the MQOO_BROWSE option establishes a browse cursor, and positions it logically before the first message on the queue; see MQGMO - Options field for further information.

This option is valid only for local, alias, and model queues; it is not valid for remote queues, distribution lists, and objects that are not queues. It is also not valid if ObjectQMgrName is the name of a queue manager alias; this is true even if the value of the RemoteQMgrName attribute in the local definition of a remote queue used for queue-manager aliasing is the name of the local queue manager.

MQOO_OUTPUT

Open queue to put messages.

The queue is opened for use with subsequent MQPUT calls.

An MQOPEN call with this option can succeed even if the InhibitPut queue attribute is set to MQQA_PUT_INHIBITED (although subsequent MQPUT calls will fail while the attribute is set to this value).

This option is valid for all types of queue, including distribution lists.

MQOO_INQUIRE

Open object to inquire attributes.

The queue, namelist, process definition, or queue manager is opened for use with subsequent MQINQ calls.

This option is valid for all types of object other than distribution lists. It is not valid if ObjectQMgrName is the name of a queue manager alias; this is true even if the value of the RemoteQMgrName attribute in the local definition of a remote queue used for queue-manager aliasing is the name of the local queue manager.

MQOO_SET

Open queue to set attributes.

The queue is opened for use with subsequent MQSET calls.

This option is valid for all types of queue other than distribution lists. It is not valid if ObjectQMgrName is the name of a local definition of a remote queue; this is true even if the value of the RemoteQMgrName attribute in the local definition of a remote queue used for queue-manager aliasing is the name of the local queue manager.

Binding options: The following options apply when the object being opened is a cluster queue; these options control the binding of the queue handle to a particular instance of the cluster queue:

MQOO_BIND_ON_OPEN

The local queue manager binds the queue handle to a particular instance of the destination queue when the queue is opened. As a result, all messages put using this handle are sent to the same instance of the destination queue, and by the same route.

This option is valid only for queues, and affects only cluster queues. If specified for a queue that is not a cluster queue, the option is ignored.

MQOO_BIND_NOT_FIXED

This stops the local queue manager binding the queue handle to a particular instance of the destination queue. As a result, successive MQPUT calls using this handle send the messages to different instances of the destination queue, or to the same instance but by different routes. It also allows the instance selected to be changed subsequently by the local queue manager, by a remote queue manager, or by a message channel agent (MCA), according to network conditions.
Note:
Client and server applications that need to exchange a series of messages to complete a transaction must not use MQOO_BIND_NOT_FIXED (or MQOO_BIND_AS_Q_DEF when DefBind has the value MQBND_BIND_NOT_FIXED), because successive messages in the series might be sent to different instances of the server application.

If MQOO_BROWSE or one of the MQOO_INPUT_* options is specified for a cluster queue, the queue manager is forced to select the local instance of the cluster queue. As a result, the binding of the queue handle is fixed, even if MQOO_BIND_NOT_FIXED is specified.

If MQOO_INQUIRE is specified with MQOO_BIND_NOT_FIXED, successive MQINQ calls using that handle might inquire different instances of the cluster queue, although usually all the instances have the same attribute values.

MQOO_BIND_NOT_FIXED is valid only for queues, and affects only cluster queues. If specified for a queue that is not a cluster queue, the option is ignored.

MQOO_BIND_AS_Q_DEF

The local queue manager binds the queue handle in the way defined by the DefBind queue attribute. The value of this attribute is either MQBND_BIND_ON_OPEN or MQBND_BIND_NOT_FIXED.

MQOO_BIND_AS_Q_DEF is the default if neither MQOO_BIND_ON_OPEN nor MQOO_BIND_NOT_FIXED is specified.

MQOO_BIND_AS_Q_DEF aids program documentation. It is not intended that this option be used with either of the other two bind options, but because its value is zero such use cannot be detected.

Context options: The following options control the processing of message context:

MQOO_SAVE_ALL_CONTEXT

Context information is associated with this queue handle. This information is set from the context of any message retrieved using this handle. For more information on message context, see the WebSphere MQ Application Programming Guide.

This context information can be passed to a message that is subsequently put on a queue using the MQPUT or MQPUT1 calls. See the MQPMO_PASS_IDENTITY_CONTEXT and MQPMO_PASS_ALL_CONTEXT options described in MQPMO - Put-message options.

Until a message has been successfully retrieved, context cannot be passed to a message being put on a queue.

A message retrieved using one of the MQGMO_BROWSE_* browse options does not have its context information saved (although the context fields in the MsgDesc parameter are set after a browse).

This option is valid only for local, alias, and model queues; it is not valid for remote queues, distribution lists, and objects that are not queues. One of the MQOO_INPUT_* options must be specified.

MQOO_PASS_IDENTITY_CONTEXT

This allows the MQPMO_PASS_IDENTITY_CONTEXT option to be specified in the PutMsgOpts parameter when a message is put on a queue; this gives the message the identity context information from an input queue that was opened with the MQOO_SAVE_ALL_CONTEXT option. For more information on message context, see the WebSphere MQ Application Programming Guide.

The MQOO_OUTPUT option must be specified.

This option is valid for all types of queue, including distribution lists.

MQOO_PASS_ALL_CONTEXT

This allows the MQPMO_PASS_ALL_CONTEXT option to be specified in the PutMsgOpts parameter when a message is put on a queue; this gives the message the identity and origin context information from an input queue that was opened with the MQOO_SAVE_ALL_CONTEXT option. For more information on message context, see the WebSphere MQ Application Programming Guide.

This option implies MQOO_PASS_IDENTITY_CONTEXT, which need not therefore be specified. The MQOO_OUTPUT option must be specified.

This option is valid for all types of queue, including distribution lists.

MQOO_SET_IDENTITY_CONTEXT

This allows the MQPMO_SET_IDENTITY_CONTEXT option to be specified in the PutMsgOpts parameter when a message is put on a queue; this gives the message the identity context information contained in the MsgDesc parameter specified on the MQPUT or MQPUT1 call. For more information on message context, see the WebSphere MQ Application Programming Guide.

This option implies MQOO_PASS_IDENTITY_CONTEXT, which need not therefore be specified. The MQOO_OUTPUT option must be specified.

This option is valid for all types of queue, including distribution lists.

MQOO_SET_ALL_CONTEXT

This allows the MQPMO_SET_ALL_CONTEXT option to be specified in the PutMsgOpts parameter when a message is put on a queue; this gives the message the identity and origin context information contained in the MsgDesc parameter specified on the MQPUT or MQPUT1 call. For more information on message context, see the WebSphere MQ Application Programming Guide.

This option implies the following options, which need not therefore be specified:

  • MQOO_PASS_IDENTITY_CONTEXT

  • MQOO_PASS_ALL_CONTEXT

  • MQOO_SET_IDENTITY_CONTEXT

The MQOO_OUTPUT option must be specified.

This option is valid for all types of queue, including distribution lists.

Other options: The following options control authorization checking, what happens when the queue manager is quiescing, and whether to resolve the local queue name:

MQOO_ALTERNATE_USER_AUTHORITY

The AlternateUserId field in the ObjDesc parameter contains a user identifier to use to validate this MQOPEN call. The call can succeed only if this AlternateUserId is authorized to open the object with the specified access options, regardless of whether the user identifier under which the application is running is authorized to do so. This does not apply to any context options specified, however, which are always checked against the user identifier under which the application is running.

This option is valid for all types of object.

MQOO_FAIL_IF_QUIESCING

The MQOPEN call failsif the queue manager is in quiescing state.

On z/OS, for a CICS or IMS application, this option also forces the MQOPEN call to fail if the connection is in quiescing state.

This option is valid for all types of object.

For information about client channels see the WebSphere MQ Clients book.

MQOO_RESOLVE_LOCAL_Q

Fill the ResolvedQName in the MQOD structure with the name of the local queue that was opened. Similarly, the ResolvedQMgrName is filled with the name of the local queue manager hosting the local queue. If the MQOD structure is less than V3, MQOO_RESOLVE_LOCAL_Q is ignored with no error being returned.

The local queue is always returned when either a local, alias, or model queue is opened, but this is not the case when, for example, a remote queue or a non-local cluster queue is opened without the MQOO_RESOLVE_LOCAL_Q option; the ResolvedQName and ResolvedQMgrName are filled with the RemoteQName and RemoteQMgrName found in the remote queue definition, or similarly with the chosen remote cluster queue.

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

If you are authorized for browse, input, or output on a queue, you have the required authority to specify this flag on the MQOPEN call. No special authority is needed.

This option is valid only for queues and queue managers.

Table 80. Valid MQOPEN options for each queue type
Option Alias
(note 1) 		Local and Model Remote Nonlocal Cluster Distribution list
MQOO_INPUT_AS_Q_DEF Yes Yes No No No
MQOO_INPUT_SHARED Yes Yes No No No
MQOO_INPUT_EXCLUSIVE Yes Yes No No No
MQOO_BROWSE Yes Yes No No No
MQOO_OUTPUT Yes Yes Yes Yes Yes
MQOO_INQUIRE Yes Yes Note 2 Yes No
MQOO_SET Yes Yes Note 2 No No
MQOO_BIND_ON_OPEN (note 3) Yes Yes Yes Yes Yes
MQOO_BIND_NOT_FIXED (note 3) Yes Yes Yes Yes Yes
MQOO_BIND_AS_Q_DEF (note 3) Yes Yes Yes Yes Yes
MQOO_SAVE_ALL_CONTEXT Yes Yes No No No
MQOO_PASS_IDENTITY_CONTEXT Yes Yes Yes Yes Yes
MQOO_PASS_ALL_CONTEXT Yes Yes Yes Yes Yes
MQOO_SET_IDENTITY_CONTEXT Yes Yes Yes Yes Yes
MQOO_SET_ALL_CONTEXT Yes Yes Yes Yes Yes
MQOO_ALTERNATE_USER_AUTHORITY Yes Yes Yes Yes Yes
MQOO_FAIL_IF_QUIESCING Yes Yes Yes Yes Yes
MQOO_RESOLVE_LOCAL_Q Yes Yes Yes Yes No
Notes:

  1. The validity of options for aliases depends on the validity of the option for the queue to which the alias resolves.

  2. This option is valid only for the local definition of a remote queue.

  3. This option can be specified for any queue type, but is ignored if the queue is not a cluster queue.



 

Home