- The object opened is one of the following:
- A queue 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.
See the ObjDesc parameter described in MQOPEN - Open object.
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 to inquire about the names of the queues in the list (using
the MQINQ call).
- A process definition to inquire about the process attributes (using the MQINQ call).
- The queue manager to inquire about the attributes of the local queue manager
(using the MQINQ call).
- An application can 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 other than a cluster queue, all
name resolution within the local queue manager takes place at the time of
the MQOPEN call. This can include one or more of the
following for a given 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
- (z/OS only) Resolution of the remote queue-manager name to the name
of the shared transmission queue used by the IGQ agent (applies only if the
local and remote queue managers belong to the same queue-sharing group)
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 Options 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 MQOO_BIND_*
options specified on the MQOPEN call:
- MQOO_BIND_ON_OPEN
- MQOO_BIND_NOT_FIXED
- MQOO_BIND_AS_Q_DEF
Refer to WebSphere MQ Queue Manager Clusters 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:
When a handle is marked as invalid, all subsequent calls (other than MQCLOSE) using this handle fail with reason code MQRC_OBJECT_CHANGED.
The application must 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 causes
this to happen, use a special force version of the
command.
- 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 subsequently opened
explicitly, a further resource security check is performed against the name
of the dynamic queue.
On z/OS, the queue manager performs security
checks only if security is enabled. For more information on security checking,
see the WebSphere MQ for z/OS System Setup Guide.
- A remote queue can be specified in one of two ways in the ObjDesc parameter of this call (see the ObjectName and ObjectQMgrName fields described in MQOD - Object descriptor):
- By specifying for ObjectName the name of a local definition
of the remote queue. In this case, ObjectQMgrName refers
to the local queue manager, and can be specified as blanks or (in the C programming
language) a null string.
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 ObjectName the name of the remote
queue as known to the remote queue manager. In this case, ObjectQMgrName 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
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 MQOO_BROWSE 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 subsequently be removed from the queue by using the MQGMO_MSG_UNDER_CURSOR
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.
Distribution lists are supported in the following environments: AIX, HP-UX, i5/OS, Solaris, Linux, Windows,
plus WebSphere MQ clients connected to these systems.
- Fields in the MQOD structure must be set as follows when opening a distribution
list:
- Version must be MQOD_VERSION_2 or greater.
- ObjectType must be MQOT_Q.
- ObjectName must be blank or the null string.
- ObjectQMgrName must be blank or the null string.
- RecsPresent must be greater than zero.
- One of ObjectRecOffset and ObjectRecPtr must
be zero and the other nonzero.
- No more than one of ResponseRecOffset and ResponseRecPtr can be nonzero.
- There must be RecsPresent object records, addressed
by either ObjectRecOffset or ObjectRecPtr.
The object records must be set to the names of the destination queues to be
opened.
- If one of ResponseRecOffset and ResponseRecPtr is nonzero, there must be RecsPresent response
records present. They are set by the queue manager if the call completes with
reason code MQRC_MULTIPLE_REASONS.
A version-2 MQOD can also be used to open a single queue that is
not in a distribution list, by ensuring that RecsPresent is
zero.
- Only the following open options are valid in the Options parameter:
- MQOO_OUTPUT
- MQOO_PASS_*_CONTEXT
- MQOO_SET_*_CONTEXT
- MQOO_ALTERNATE_USER_AUTHORITY
- MQOO_FAIL_IF_QUIESCING
- 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 MQRC_Q_TYPE_ERROR. 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 and reason code are set to MQCC_OK and MQRC_NONE
respectively; if every open fails because none of the queues exists, the parameters
are set to MQCC_FAILED and MQRC_UNKNOWN_OBJECT_NAME.
- 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 MQCC_WARNING if at least one open
succeeded, and to MQCC_FAILED if all failed.
- The reason code parameter is set to MQRC_MULTIPLE_REASONS.
- 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 MQCO_NONE.
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 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
MQRC_HANDLE_NOT_AVAILABLE.
- 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 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.
- A distribution list can 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 can 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 MQRC_CLUSTER_RESOLUTION_ERROR.
- When a cluster queue is opened and there are multiple instances of the
queue in the cluster, the instance opened depends on the options specified
on the MQOPEN call:
- If the options specified include any of the following:
- MQOO_BROWSE
- MQOO_INPUT_AS_Q_DEF
- MQOO_INPUT_EXCLUSIVE
- MQOO_INPUT_SHARED
- MQOO_SET
the instance of the cluster queue opened must 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 include
one or both of the following:
the instance opened is the local instance if there is one, and a remote
instance otherwise (if using the CLWLUSEQ defaults). The instance chosen by
the queue manager can, however, be altered by a cluster workload exit (if
there is one).
- If there is a subscription for the queue, but it is not acknowledged
by a full repository, the object is not present in the cluster and the call
fails with reason code MQRC_OBJECT_NAME.
For more information about cluster queues, refer to WebSphere MQ Queue Manager Clusters.
- 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 ObjDesc parameter to
open the queue. See MQTMC2 - Trigger message 2 (character format) for further details.
- On i5/OS, applications running in compatibility mode are connected
automatically to the queue manager by the first MQOPEN call
issued by the application (if the application has not already connected to
the queue manager by using the MQCONN call).
Applications
not running in compatibility mode must issue the MQCONN or MQCONNX call to connect to the queue manager explicitly,
before using the MQOPEN call to open an object.