MQOPEN (Open object) on IBM i

The MQOPEN call establishes access to an object.

The following types of object are valid:

Queue (including distribution lists)
Namelist
Process definition
Queue manager
Topic

Index

Syntax
Usage notes
Parameters
RPG Declaration

Syntax

MQOPEN (HCONN, OBJDSC, OPTS, HOBJ, CMPCOD, REASON)

Usage notes

The object opened is one of the following:
- A queue, in order to:
  - Get or browse messages (using the MQGET call)
  - Put messages (using the MQPUT call)
  - Inquire about the attributes of the queue (using the MQINQ call)
  - Set the attributes of the queue (using the MQSET call)
  If the queue named is a model queue, a dynamic local queue is created.
  
  A distribution list is a special type of queue object that contains a list of queues. It can be opened to put messages, but not to get or browse messages, or to inquire or set attributes. See usage note 8 for further details.
  
  A queue that has QSGDISP(GROUP) is a special type of queue definition that cannot be used with the MQOPEN or MQPUT1 calls.
- A namelist, in order to:
  - Inquire about the names of the queues in the list (using the MQINQ call).
- A process definition, in order to:
  - Inquire about the process attributes (using the MQINQ call).
- The queue manager, in order to:
  - Inquire about the attributes of the local queue manager (using the MQINQ call).
It is valid for an application to open the same object more than once. A different object handle is returned for each open. Each handle that is returned can be used for the functions for which the corresponding open was performed.
If the object being opened is a queue but not a cluster queue, all name resolution within the local queue manager takes place at the time of the MQOPEN call. This might include one or more of the following for a particular MQOPEN call:
- Alias resolution to the name of a base queue
- Resolution of the name of a local definition of a remote queue to the name of the remote queue manager, and the name by which the queue is known at the remote queue manager
- Resolution of the remote queue manager name to the name of a local transmission queue
However, be aware that subsequent MQINQ or MQSET calls for the handle relate solely to the name that has been opened, and not to the object resulting after name resolution has occurred. For example, if the object opened is an alias, the attributes returned by the MQINQ call are the attributes of the alias, not the attributes of the base queue to which the alias resolves. Name resolution checking is still carried out, however, regardless of what is specified for the OPTS parameter on the corresponding MQOPEN.
If the object being opened is a cluster queue, name resolution can occur at the time of the MQOPEN call, or be deferred until later. The point at which resolution occurs is controlled by the OOBND* options specified on the MQOPEN call:
- OOBNDO
- OOBNDN
- OOBNDQ
See Name resolution for more information about name resolution for cluster queues.
The attributes of an object can change while an application has the object open. In many cases, the application does not notice this, but for certain attributes the queue manager marks the handle as no longer valid. These are:
- Any attribute that affects the name resolution of the object. This applies regardless of the open options used, and includes the following:
  - A change to the BaseQName attribute of an alias queue that is open.
  - A change to the RemoteQName or RemoteQMgrName queue attributes, for any handle that is open for this queue, or for a queue which resolves through this definition as a queue manager alias.
  - Any change that causes a currently open handle for a remote queue to resolve to a different transmission queue, or to fail to resolve to one at all. For example, this can include:
    - A change to the XmitQName attribute of the local definition of a remote queue, whether the definition is being used for a queue, or for a queue manager alias.
    There is one exception to this, namely the creation of a new transmission queue. A handle that would have resolved to this queue had it been present when the handle was opened, but instead resolved to the default transmission queue, is not made invalid.
  - A change to the DefXmitQName queue manager attribute. In this case all open handles that resolved to the previously named queue (that resolved to it only because it was the default transmission queue) are marked as invalid. Handles that resolved to this queue for other reasons are not affected.
- The Shareability queue attribute, if there are two or more handles that are currently providing OOINPS access for this queue, or for a queue that resolves to this queue. If so, all handles that are open for this queue, or for a queue that resolves to this queue, are marked as invalid, regardless of the open options.
- The Usage queue attribute, for all handles that are open for this queue, or for a queue that resolves to this queue, regardless of the open options.
When a handle is marked as invalid, all subsequent calls (other than MQCLOSE) using this handle fail with reason code RC2041; the application should issue an MQCLOSE call (using the original handle) and then reopen the queue. Any uncommitted updates against the old handle from previous successful calls can still be committed or backed out, as required by the application logic.
If changing an attribute will cause this to happen, a special force version of the command must be used.
The queue manager performs security checks when an MQOPEN call is issued, to verify that the user identifier under which the application is running has the appropriate level of authority before access is permitted. The authority check is made on the name of the object being opened, and not on the name, or names, resulting after a name has been resolved.
If the object being opened is a model queue, the queue manager performs a full security check against both the name of the model queue and the name of the dynamic queue that is created. If the resulting dynamic queue is then opened explicitly, a further resource security check is performed against the name of the dynamic queue.
A remote queue can be specified in one of two ways in the OBJDSC parameter of this call (see the ODON and ODMN fields described in MQOD (Object descriptor) on IBM i ):
- By specifying for ODON the name of a local definition of the remote queue. In this case, ODMN refers to the local queue manager, and can be specified as blanks.
  The security validation performed by the local queue manager verifies that the user is authorized to open the local definition of the remote queue.
- By specifying for ODON the name of the remote queue as known to the remote queue manager. In this case, ODMN is the name of the remote queue manager.
  The security validation performed by the local queue manager verifies that the user is authorized to send messages to the transmission queue resulting from the name resolution process.
In either case:
- No messages are sent by the local queue manager to the remote queue manager in order to check that the user is authorized to put messages on the queue.
- When a message arrives at the remote queue manager, the remote queue manager might reject it because the user originating the message is not authorized.
An MQOPEN call with the OOBRW option establishes a browse cursor, for use with MQGET calls that specify the object handle and one of the browse options. This allows the queue to be scanned without altering its contents. A message that has been found by browsing can later be removed from the queue by using the GMMUC option.
Multiple browse cursors can be active for a single application by issuing several MQOPEN requests for the same queue.
The following notes apply to the use of distribution lists.
- Fields in the MQOD structure must be set as follows when opening a distribution list:
  - ODVER must be ODVER2 or greater.
  - ODOT must be OTQ.
  - ODON must be blank or the null string.
  - ODMN must be blank or the null string.
  - ODREC must be greater than zero.
  - One of ODORO and ODORP must be zero and the other nonzero.
  - No more than one of ODRRO and ODRRP can be nonzero.
  - There must be ODREC object records, addressed by either ODORO or ODORP. The object records must be set to the names of the destination queues to be opened.
  - If one of ODRRO and ODRRP is nonzero, there must be ODREC response records present. They are set by the queue manager if the call completes with reason code RC2136.
  A version-2 MQOD can also be used to open a single queue that is not in a distribution list, by ensuring that ODREC is zero.
- Only the following open options are valid in the OPTS parameter:
  - OOOUT
  - OOPAS*
  - OOSET*
  - OOALTU
  - OOFIQ
- The destination queues in the distribution list can be local, alias, or remote queues, but they cannot be model queues. If a model queue is specified, that queue fails to open, with reason code RC2057. However, this does not prevent other queues in the list being opened successfully.
- The completion code and reason code parameters are set as follows:
  - If the open operations for the queues in the distribution list all succeed or fail in the same way, the completion code and reason code parameters are set to describe the common result. The MQRR response records (if provided by the application) are not set in this case.
    For example, if every open succeeds, the completion code is set to CCOK and the reason code is RCNONE; if every open fails because none of the queues exists, the parameters are set to CCFAIL and RC2085.
  - If the open operations for the queues in the distribution list do not all succeed or fail in the same way:
    - The completion code parameter is set to CCWARN if at least one open succeeded, and to CCFAIL if all failed.
    - The reason code parameter is set to RC2136.
    - The response records (if provided by the application) are set to the individual completion codes and reason codes for the queues in the distribution list.
- When a distribution list has been opened successfully, the handle HOBJ returned by the call can be used on subsequent MQPUT calls to put messages to queues in the distribution list, and on an MQCLOSE call to relinquish access to the distribution list. The only valid close option for a distribution list is CONONE.
  The MQPUT1 call can also be used to put a message to a distribution list; the MQOD structure defining the queues in the list is specified as a parameter on that call.
- Each successfully opened destination in the distribution list counts as a separate handle when checking whether the application has exceeded the permitted maximum number of handles (see the MaxHandles queue manager attribute). This is true even when two or more of the destinations in the distribution list actually resolve to the same physical queue. If the MQOPEN or MQPUT1 call for a distribution list would cause the number of handles in use by the application to exceed MaxHandles, the call fails with reason code RC2017.
- Each destination that is opened successfully has the value of its OpenOutputCount attribute incremented by one. If two or more of the destinations in the distribution list actually resolve to the same physical queue, that queue has its OpenOutputCount attribute incremented by the number of destinations in the distribution list that resolve to that queue.
- Any change to the queue definitions that would have caused a handle to become invalid had the queues been opened individually (for example, a change in the resolution path), does not cause the distribution-list handle to become invalid. However, it does result in a failure for that particular queue when the distribution-list handle is used on a subsequent MQPUT call.
- It is valid for a distribution list to contain only one destination.
The following notes apply to the use of cluster queues.
- When a cluster queue is opened for the first time, and the local queue manager is not a full repository queue manager, the local queue manager obtains information about the cluster queue from a full repository queue manager. When the network is busy, it may take several seconds for the local queue manager to receive the needed information from the repository queue manager. As a result, the application issuing the MQOPEN call might have to wait for up to 10 seconds before control returns from the MQOPEN call. If the local queue manager does not receive the needed information about the cluster queue within this time, the call fails with reason code RC2189.
- When a cluster queue is opened and there are multiple instances of the queue in the cluster, the instance actually opened depends on the options specified on the MQOPEN call:
  - If the options specified include any of the following:
    - OOBRW
    - OOINPQ
    - OOINPX
    - OOINPS
    - OOSET
    the instance of the cluster queue opened is required to be the local instance. If there is no local instance of the queue, the MQOPEN call fails.
  - If the options specified include none of the above, but do include one or both of the following:
    - OOINQ
    - OOOUT
    the instance opened is the local instance if there is one, and a remote instance otherwise. The instance chosen by the queue manager can, however, be altered by a cluster workload exit (if there is one).
For more information about cluster queues, see Cluster queues.
Applications started by a trigger monitor are passed the name of the queue that is associated with the application when the application is started. This queue name can be specified in the OBJDSC parameter to open the queue. See the description of the MQTMC structure for further details.
When using the OORLOQ option, the local queue is already 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; the ResolvedQName and ResolvedQMgrName are entered with the RemoteQName and RemoteQMgrName found in the remote queue definition, or similarly with the chosen remote cluster queue. If OORLOQ is specified when opening, for example, a remote queue, ResolvedQName will now be the transmission queue which messages will be put to. The ResolvedQMgrName will be entered with the name of the local queue manager hosting the transmission queue. If a user is authorized for browse, input or output on a queue, they have the required authority to specify this flag on the MQOPEN call. No special authority is needed.

Parameters

The MQOPEN call has the following parameters:

HCONN (10-digit signed integer) - input

Connection handle.

This handle represents the connection to the queue manager. The value of HCONN was returned by a previous MQCONN or MQCONNX call.

OBJDSC (MQOD) - input/output

Object descriptor.

This is a structure that identifies the object to be opened; see MQOD (Object descriptor) on IBM i for details.

If the ODON field in the OBJDSC parameter is the name of a model queue, a dynamic local queue is created with the attributes of the model queue; this happens irrespective of the open options specified by the OPTS parameter. Subsequent operations using the HOBJ returned by the MQOPEN call are performed on the new dynamic queue, and not on the model queue. This is true even for the MQINQ and MQSET calls. The name of the model queue in the OBJDSC parameter is replaced with the name of the dynamic queue created. The type of the dynamic queue is determined by the value of the DefinitionType attribute of the model queue (see Attributes for queues ). For information about the close options applicable to dynamic queues, see the description of the MQCLOSE call.

OPTS (10-digit signed integer) - input

Options that control the action of MQOPEN.

At least one of the following options must be specified:

OOBRW
OOINP* (only one of these)
OOINQ
OOOUT
OOSET
OORLQ

Other options can be specified as required. If more than one option is required, the values can be added (do not add the same constant more than once). Combinations that are not valid are noted; all other combinations are valid. Only options that are applicable to the type of object specified by OBJDSC are allowed (see Valid MQOPEN options for each queue type ). Access options: The following options control the type of operations that can be performed on the object:

OOINPQ

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.

OOINPS

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 OOINPS, but fails with reason code RC2042 if the queue is currently open with OOINPX.

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.

OOINPX

Open queue to get messages with exclusive access.

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

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:

Only one of these options can be specified.
An MQOPEN call with one of these options can succeed even if the InhibitGet queue attribute is set to QAGETI (although subsequent MQGET calls will fail while the attribute is set to this value).
If the queue is defined as not being shareable (that is, the Shareability queue attribute has the value QANSHR), attempts to open the queue for shared access are treated as attempts to open the queue with exclusive access.
If an alias queue is opened with one of these options, the test for exclusive use (or for whether another application has exclusive use) is against the base queue to which the alias resolves.
These options are not valid if ODMN 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.

OOBRW

Open queue to browse messages. The queue is opened for use with subsequent MQGET calls with one of the following options:

GMBRWF
GMBRWN
GMBRWC

This is allowed even if the queue is currently open for OOINPX. An MQOPEN call with the OOBRW option establishes a browse cursor, and positions it logically before the first message on the queue; see the GMOPT field described in MQGMO (Get-message options) on IBM i 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 which are not queues. It is also not valid if ODMN 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.

OOOUT

Open queue to put messages, or a topic or topic string to publish 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 QAPUTI (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 and topics.

OOINQ

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

OOSET

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 ODMN 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 an instance of the cluster queue:

OOBNDO

Bind handle to destination when queue is opened.

This causes the local queue manager to bind the queue handle to an 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.

OOBNDN

Do not bind to a specific destination.

This stops the local queue manager binding the queue handle to an instance of the destination queue. As a result, successive MQPUT calls using this handle may result in the messages being sent to different instances of the destination queue, or being sent to the same instance but by different routes. It also allows the instance selected to be changed later 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 which need to exchange a series of messages in order to complete a transaction should not use OOBNDN (or OOBNDQ when DefBind has the value BNDNOT), because successive messages in the series may be sent to different instances of the server application.

If OOBRW or one of the OOINP* 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 OOBNDN is specified.

If OOINQ is specified with OOBNDN, successive MQINQ calls using that handle may inquire different instances of the cluster queue, although typically all of the instances have the same attribute values.

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

OOBNDQ

Use default binding for queue.

This causes the local queue manager to bind the queue handle in the way defined by the DefBind queue attribute. The value of this attribute is either BNDOPN or BNDNOT.

OOBNDQ is the default if OOBNDO and OOBNDN are not specified.

OOBNDQ is defined to aid program documentation. It is not intended that this option is 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:

OOSAVA

Save context when message retrieved.

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 about message context, see Message context and Control context information.

This context information can be passed to a message that is later put on a queue using the MQPUT or MQPUT1 calls. See the PMPASI and PMPASA options described in MQPMO (Put-message options) on IBM i.

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 GMBRW* browse options does not have its context information saved (although the context fields in the MSGDSC 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 which are not queues. One of the OOINP* options must be specified.

OOPASI

Allow identity context to be passed.

This allows the PMPASI option to be specified in the PMO 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 OOSAVA option. For more information about message context, see Message context and Control context information.

The OOOUT option must be specified.

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

OOPASA

Allow all context to be passed.

This allows the PMPASA option to be specified in the PMO 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 OOSAVA option. For more information about message context, see Message context and Control context information.

This option implies OOPASI, which need not therefore be specified. The OOOUT option must be specified.

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

OOSETI

Allow identity context to be set.

This allows the PMSETI option to be specified in the PMO parameter when a message is put on a queue; this gives the message the identity context information contained in the MSGDSC parameter specified on the MQPUT or MQPUT1 call. For more information about message context, see Message context and Control context information.

This option implies OOPASI, which need not therefore be specified. The OOOUT option must be specified.

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

OOSETA

Allow all context to be set.

This allows the PMSETA option to be specified in the PMO parameter when a message is put on a queue; this gives the message the identity and origin context information contained in the MSGDSC parameter specified on the MQPUT or MQPUT1 call. For more information about message context, see Message context and Control context information.

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

OOPASI
OOPASA
OOSETI

The OOOUT option must be specified.

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

Other options: The following options control authorization checking, and what happens when the queue manager is quiescing:

OOALTU

Validate with specified user identifier.

This indicates that the ODAU field in the OBJDSC parameter contains a user identifier that is to be used to validate this MQOPEN call. The call can succeed only if this ODAU 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.

OOFIQ

Fail if queue manager is quiescing.

This option forces the MQOPEN call to fail if the queue manager is in quiescing state.

This option is valid for all types of object.

OORLQ

Enter the name of local queue that was opened.

This option specifies that the ResolvedQName in the MQOD structure (if available) should be entered with the name of the local queue which was opened. The ResolvedQMgrName will similarly be entered with the name of the local queue manager hosting the local queue.

Option	Remote	Nonlocal Cluster	Distribution list	Topic
OOINPQ	-	-	-	-
OOINPS	-	-	-	-
OOINPX	-	-	-	-
OOBRW	-	-	-	-
OOOUT
OOINQ	2		-	-
OOSET	2	-	-	-
OOBNDO ( 3 )				-
OOBNDN ( 3 )				-
OOBNDQ ( 3 )				-
OOSAVA	-	-	-	-
OOPASI				5
OOPASA				5
OOSETI				5
OOSETA				5
OOALTU
OOFIQ
OORLQ			-	-

Notes:

The validity of options for aliases depends on the validity of the option for the queue to which the alias resolves.
This option is valid only for the local definition of a remote queue.
This option can be specified for any queue type, but is ignored if the queue is not a cluster queue.
This attribute is ignored for a topic.
These attributes can be used with a topic, but only affect the context set for the retained message, not the context fields sent to any subscriber.

HOBJ (10-digit signed integer) - output

Object handle.

This handle represents the access that has been established to the object. It must be specified on subsequent message queuing calls that operate on the object. It ceases to be valid when the MQCLOSE call is issued, or when the unit of processing that defines the scope of the handle terminates.

The scope of the handle is restricted to the smallest unit of parallel processing supported by the platform on which the application is running; the handle is not valid outside the unit of parallel processing from which the MQOPEN call was issued:

On IBM i, the scope of the handle is the job issuing the call.

CMPCOD (10-digit signed integer) - output

Completion code.

It is one of the following:

CCOK: Successful completion.
CCWARN: Warning (partial completion).
CCFAIL: Call failed.

RPG Declaration

     C*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     C                     CALLP     MQOPEN(HCONN : OBJDSC : OPTS :
     C                                      HOBJ : CMPCOD : REASON)

The prototype definition for the call is:

D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
DMQOPEN           PR                  EXTPROC('MQOPEN')
D* Connection handle
D HCONN                         10I 0 VALUE
D* Object descriptor
D OBJDSC                       468A
D* Options that control the action of MQOPEN
D OPTS                          10I 0 VALUE
D* Object handle
D HOBJ                          10I 0
D* Completion code
D CMPCOD                        10I 0
D* Reason code qualifying CMPCOD
D REASON                        10I 0

Parent topic: Function calls on IBM i