MQOPEN - Open object

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

Syntax

MQOPEN (Hconn, ObjDesc, Options, Hobj, CompCode, Reason)

Parameters

Hconn
Type: MQHCONN - input

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

[z/OS]On z/OS® for CICS® applications the MQCONN call can be omitted, and the following value specified for Hconn :
MQHC_DEF_HCONN
Default connection handle.
ObjDesc
Type: MQOD - input/output

This is a structure that identifies the object to be opened; see MQOD - Object descriptor for details.

If the ObjectName field in the ObjDesc parameter is the name of a model queue, a dynamic local queue is created with the attributes of the model queue; this happens whatever options you specify on the Options 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 ObjDesc 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.

Options
Type: MQLONG - input
You must specify at least one of the following options:
  • MQOO_BROWSE
  • MQOO_INPUT_* (only one of these)
  • MQOO_INQUIRE
  • MQOO_OUTPUT
  • MQOO_SET
  • MQOO_BIND_* (only one of these)
See the following table for details of these options; other options can be specified as required. To specify more than one option, either add the values together (do not add the same constant more than once), or combine the values using the bitwise OR operation (if the programming language supports bit operations). 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.
Table 1. Valid MQOPEN options for queues and topics
Option Alias 1 Local and Model Remote Nonlocal Cluster Distribution list Topic
MQOO_INPUT_AS_Q_DEF Yes Yes No No No No
MQOO_INPUT_SHARED Yes Yes No No No No
MQOO_INPUT_EXCLUSIVE Yes Yes No No No No
MQOO_OUTPUT Yes Yes Yes Yes Yes Yes
MQOO_BROWSE Yes Yes No No No No
MQOO_CO_OP Yes Yes No No No No
MQOO_INQUIRE Yes Yes 2 Yes No No
MQOO_SET Yes Yes 2 No No No
MQOO_BIND_ON_OPEN 3 Yes Yes Yes Yes Yes No
MQOO_BIND_NOT_FIXED 3 Yes Yes Yes Yes Yes No
MQOO_BIND_ON_GROUP 3 Yes Yes Yes Yes Yes No
MQOO_BIND_AS_Q_DEF 3 Yes Yes Yes Yes Yes No
MQOO_SAVE_ALL_CONTEXT Yes Yes No No No No
MQOO_PASS_IDENTITY_CONTEXT Yes Yes Yes Yes Yes 4
MQOO_PASS_ALL_CONTEXT Yes Yes Yes Yes Yes Yes
MQOO_SET_IDENTITY_CONTEXT Yes Yes Yes Yes Yes 4
MQOO_SET_ALL_CONTEXT Yes Yes Yes Yes Yes Yes
MQOO_NO_READ_AHEAD Yes Yes No No No No
MQOO_READ_AHEAD Yes Yes No No No No
MQOO_READ_AHEAD_AS_Q_DEF Yes Yes No No No No
MQOO_ALTERNATE_USER_AUTHORITY Yes Yes Yes Yes Yes Yes
MQOO_FAIL_IF_QUIESCING Yes Yes Yes Yes Yes Yes
MQOO_RESOLVE_LOCAL_Q Yes Yes Yes Yes No No
MQOO_RESOLVE_LOCAL_TOPIC No No No No No Yes
MQOO_NO_MULTICAST No No No No No Yes
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. However, the DefBind queue attribute overrides the base queue even when the alias queue is not in a cluster.
  4. These attributes can be used with a topic, but affect only the context set for the retained message, not the context fields sent to any subscriber.
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.

MQOO_OUTPUT

Open queue to put messages, or a topic or topic string to publish messages.

The queue or topic 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 fail while the attribute is set to this value).

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

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 MQQA_GET_INHIBITED (although subsequent MQGET calls 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 MQQA_NOT_SHAREABLE), 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 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_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_CO_OP
Open as a cooperating member of the set of handles.

This option is valid only with the MQOO_BROWSE option. If it is specified without MQOO_BROWSE, MQOPEN returns with MQRC_OPTIONS_ERROR.

The handle returned is considered to be a member of a cooperating set of handles for subsequent MQGET calls with one of the following options:
  • MQGMO_MARK_BROWSE_CO_OP
  • MQGMO_UNMARKED_BROWSE_MSG
  • MQGMO_UNMARK_BROWSE_CO_OP

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_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 an instance of the cluster queue:
MQOO_BIND_ON_OPEN
The local queue manager binds 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.

MQOO_BIND_NOT_FIXED
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 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 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 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 typically 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_ON_GROUP
Allows an application to request that a group of messages are all allocated to the same destination instance.

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_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, MQBND_BIND_NOT_FIXED, or MQBND_BIND_ON_GROUP.

MQOO_BIND_AS_Q_DEF is the default when MQOO_BIND_ON_OPEN, MQOO_BIND_NOT_FIXED, or MQOO_BIND_ON_GROUP is not specified.

MQOO_BIND_AS_Q_DEF aids 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:
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 about message context, see Message context and Controlling context information.

This context information can be passed to a message that is then 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 about message context, see Message context and Controlling context information.

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

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

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

Read ahead options:

When you call MQOPEN with MQOO_READ_AHEAD, the IBM® MQ client only enables read-ahead if certain conditions are met. These conditions include:
  • Both the client and remote queue manager must be at IBM WebSphere® MQ 7.0 or later.
  • The client application must be compiled and linked against the threaded IBM MQ MQI client libraries.
  • The client channel must be using TCP/IP protocol
  • The channel must have a non-zero SharingConversations (SHARECNV) setting in both the client and server channel definitions.
The following options control whether non-persistent messages are sent to the client before an application requests them. The following notes apply to the read ahead options:
  • Only one of these options can be specified.
  • These options are valid only for local, alias, and model queues. They are not valid for remote queues, distribution lists, topics or queue managers.
  • These options are only applicable when one of MQOO_BROWSE, MQOO_INPUT_SHARED and MQOO_INPUT_EXCLUSIVE are also specified although it is not an error to specify these options with MQOO_INQUIRE or MQOO_SET.
  • If the application is not running as an IBM MQ client, these options are ignored.
MQOO_NO_READ_AHEAD
Non-persistent messages are not sent the client before an application requests them.
MQOO_READ_AHEAD
Non-persistent messages are sent to the client before an application requests them.
MQOO_READ_AHEAD_AS_Q_DEF
Read ahead behavior is determined by the default read ahead attribute of the queue being opened. This is the default value.
Other options: The following options control authorization checking, what happens when the queue manager is quiescing, whether to resolve the local queue name, and multicast:
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 fails if the queue manager is in quiescing state.

[z/OS]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 Overview of IBM MQ MQI clients.

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 Version 3, 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 are 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.

MQOO_RESOLVE_LOCAL_TOPIC
Fill the ResolvedQName in the MQOD structure with the name of the administrative topic opened.
MQOO_NO_MULTICAST
Publication messages are not sent using multicast.

This option is valid only with the MQOO_OUTPUT option. If it is specified without MQOO_OUTPUT, MQOPEN returns with MQRC_OPTIONS_ERROR.

This option is valid only for a topic.

Hobj
Type: MQHOBJ - output

This handle represents the access that has been established to the object. It must be specified on subsequent IBM MQ 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 object handle returned is the same as the scope of the connection handle specified on the call. See MQCONN - Hconn parameter for information about handle scope.

CompCode
Type: MQLONG - output
The completion code; it is one of the following:
MQCC_OK
Successful completion.
MQCC_WARNING
Warning (partial completion).
MQCC_FAILED
Call failed.
Reason
Type: MQLONG - output

The reason code qualifying CompCode.

If CompCode is MQCC_OK:
MQRC_NONE
(0, X'000') No reason to report.
If CompCode is MQCC_WARNING:
MQRC_MULTIPLE_REASONS
(2136, X'858') Multiple reason codes returned.
If CompCode is MQCC_FAILED:
MQRC_ADAPTER_NOT_AVAILABLE
(2204, X'89C') Adapter not available.
MQRC_ADAPTER_SERV_LOAD_ERROR
(2130, X'852') Unable to load adapter service module.
MQRC_ALIAS_BASE_Q_TYPE_ERROR
(2001, X'7D1') Alias base queue not a valid type.
MQRC_API_EXIT_ERROR
(2374, X'946') API exit failed.
MQRC_API_EXIT_LOAD_ERROR
(2183, X'887') Unable to load API exit.
MQRC_ASID_MISMATCH
(2157, X'86D') Primary and home ASIDs differ.
MQRC_CALL_IN_PROGRESS
(2219, X'8AB') MQI call entered before previous call complete.
MQRC_CF_NOT_AVAILABLE
(2345, X'929') Coupling facility not available.
MQRC_CF_STRUC_AUTH_FAILED
(2348, X'92C') Coupling-facility structure authorization check failed.
MQRC_CF_STRUC_ERROR
(2349, X'92D') Coupling-facility structure not valid.
MQRC_CF_STRUC_FAILED
(2373, X'945') Coupling-facility structure failed.
MQRC_CF_STRUC_IN_USE
(2346, X'92A') Coupling-facility structure in use.
MQRC_CF_STRUC_LIST_HDR_IN_USE
(2347, X'92B') Coupling-facility structure list-header in use.
MQRC_CICS_WAIT_FAILED
(2140, X'85C') Wait request rejected by CICS.
MQRC_CLUSTER_EXIT_ERROR
(2266, X'8DA') Cluster workload exit failed.
MQRC_CLUSTER_PUT_INHIBITED
(2268, X'8DC') Put calls inhibited for all queues in cluster.
MQRC_CLUSTER_RESOLUTION_ERROR
(2189, X'88D') Cluster name resolution failed.
MQRC_CLUSTER_RESOURCE_ERROR
(2269, X'8DD') Cluster resource error.
MQRC_CONNECTION_BROKEN
(2009, X'7D9') Connection to queue manager lost.
MQRC_CONNECTION_NOT_AUTHORIZED
(2217, X'8A9') Not authorized for connection.
MQRC_CONNECTION_QUIESCING
(2202, X'89A') Connection quiescing.
MQRC_CONNECTION_STOPPING
(2203, X'89B') Connection shutting down.
MQRC_DB2_NOT_AVAILABLE
(2342, X'926') Db2® subsystem not available.
MQRC_DEF_XMIT_Q_TYPE_ERROR
(2198, X'896') Default transmission queue not local.
MQRC_DEF_XMIT_Q_USAGE_ERROR
(2199, X'897') Default transmission queue usage error.
MQRC_DYNAMIC_Q_NAME_ERROR
(2011, X'7DB') Name of dynamic queue not valid.
MQRC_HANDLE_NOT_AVAILABLE
(2017, X'7E1') No more handles available.
MQRC_HCONN_ERROR
(2018, X'7E2') Connection handle not valid.
MQRC_HOBJ_ERROR
(2019, X'7E3') Object handle not valid.
MQRC_MULTIPLE_REASONS
(2136, X'858') Multiple reason codes returned.
MQRC_NAME_IN_USE
(2201, X'899') Name in use.
MQRC_NAME_NOT_VALID_FOR_TYPE
(2194, X'892') Object name not valid for object type.
MQRC_NOT_AUTHORIZED
(2035, X'7F3') Not authorized for access.
MQRC_OBJECT_ALREADY_EXISTS
(2100, X'834') Object exists.
MQRC_OBJECT_DAMAGED
(2101, X'835') Object damaged.
MQRC_OBJECT_IN_USE
(2042, X'7FA') Object already open with conflicting options.
MQRC_OBJECT_LEVEL_INCOMPATIBLE
(2360, X'938') Object level not compatible.
MQRC_OBJECT_NAME_ERROR
(2152, X'868') Object name not valid.
MQRC_OBJECT_NOT_UNIQUE
(2343, X'927') Object not unique.
MQRC_OBJECT_Q_MGR_NAME_ERROR
(2153, X'869') Object queue manager name not valid.
MQRC_OBJECT_RECORDS_ERROR
(2155, X'86B') Object records not valid.
MQRC_OBJECT_STRING_ERROR
(2441, X'0989') Objectstring field not valid
MQRC_OBJECT_TYPE_ERROR
(2043, X'7FB') Object type not valid.
MQRC_OD_ERROR
(2044, X'7FC') Object descriptor structure not valid.
MQRC_OPTION_NOT_VALID_FOR_TYPE
(2045, X'7FD') Option not valid for object type.
MQRC_OPTIONS_ERROR
(2046, X'7FE') Options not valid or not consistent.
MQRC_PAGESET_ERROR
(2193, X'891') Error accessing page-set data set.
MQRC_PAGESET_FULL
(2192, X'890') External storage medium is full.
MQRC_Q_DELETED
(2052, X'804') Queue has been deleted.
MQRC_Q_MGR_NAME_ERROR
(2058, X'80A') Queue manager name not valid or not known.
MQRC_Q_MGR_NOT_AVAILABLE
(2059, X'80B') Queue manager not available for connection.
MQRC_Q_MGR_QUIESCING
(2161, X'871') Queue manager quiescing.
MQRC_Q_MGR_STOPPING
(2162, X'872') Queue manager shutting down.
MQRC_Q_TYPE_ERROR
(2057, X'809') Queue type not valid.
MQRC_RECS_PRESENT_ERROR
(2154, X'86A') Number of records present not valid.
MQRC_REMOTE_Q_NAME_ERROR
(2184, X'888') Remote queue name not valid.
MQRC_RESOURCE_PROBLEM
(2102, X'836') Insufficient system resources available.
MQRC_RESPONSE_RECORDS_ERROR
(2156, X'86C') Response records not valid.
MQRC_SECURITY_ERROR
(2063, X'80F') Security error occurred.
MQRC_SELECTOR_SYNTAX_ERROR
2459 (X'099B') An MQOPEN, MQPUT1 or MQSUB call was issued but a selection string was specified which contained a syntax error.
MQRC_STOPPED_BY_CLUSTER_EXIT
(2188, X'88C') Call rejected by cluster workload exit.
MQRC_STORAGE_MEDIUM_FULL
(2192, X'890') External storage medium is full.
MQRC_STORAGE_NOT_AVAILABLE
(2071, X'817') Insufficient storage available.
MQRC_SUPPRESSED_BY_EXIT
(2109, X'83D') Call suppressed by exit program.
MQRC_UNEXPECTED_ERROR
(2195, X'893') Unexpected error occurred.
MQRC_UNKNOWN_ALIAS_BASE_Q
(2082, X'822') Unknown alias base queue.
MQRC_UNKNOWN_DEF_XMIT_Q
(2197, X'895') Unknown default transmission queue.
MQRC_UNKNOWN_OBJECT_NAME
(2085, X'825') Unknown object name.
MQRC_UNKNOWN_OBJECT_Q_MGR
(2086, X'826') Unknown object queue manager.
MQRC_UNKNOWN_REMOTE_Q_MGR
(2087, X'827') Unknown remote queue manager.
MQRC_UNKNOWN_XMIT_Q
(2196, X'894') Unknown transmission queue.
MQRC_WRONG_CF_LEVEL
(2366, X'93E') Coupling-facility structure is wrong level.
MQRC_XMIT_Q_TYPE_ERROR
(2091, X'82B') Transmission queue not local.
MQRC_XMIT_Q_USAGE_ERROR
(2092, X'82C') Transmission queue with wrong usage.

For detailed information about these codes, see Messages and reason codes.

General usage notes

  1. 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).
    • A topic to publish a message (using the MQPUT call)
  2. 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.
  3. 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:
    • 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]On 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)
    • Alias resolution to the name of a base queue or a topic object.

    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 or a topic object to which the alias resolves.

    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
    • MQOO_BIND_ON_GROUP

    See Name resolution for more information about name resolution for cluster queues.

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

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

Read ahead options

When you call MQOPEN with MQOO_READ_AHEAD, the IBM MQ client only enables read-ahead if certain conditions are met. These conditions include:
  • Both the client and remote queue manager must be at IBM WebSphere MQ 7.0 or later.
  • The client application must be compiled and linked against the threaded IBM MQ MQI client libraries.
  • The client channel must be using TCP/IP protocol
  • The channel must have a non-zero SharingConversations (SHARECNV) setting in both the client and server channel definitions.

The following notes apply to the use of read ahead options.

  1. The read ahead options are applicable only when one, and only one, of the MQOO_BROWSE, MQOO_INPUT_SHARED and MQOO_INPUT_EXCLUSIVE options are also specified. An error is not thrown if a read ahead options are specified with the MQOO_ INQUIRE or MQOO_SET options.
  2. Read ahead is not enabled when requested if the options used on the first MQGET call are not supported for use with read ahead. Also, read ahead is disabled when the client is connecting to a queue manager that does not support read ahead.
  3. If the application is not running as an IBM MQ client, read ahead options are ignored.

Cluster queues

The following notes apply to the use of cluster queues.

  1. 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.
  2. 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 options described previously, but include one or both of the following:
      • MQOO_INQUIRE
      • MQOO_OUTPUT
      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).
  3. 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, see Cluster queues.

Distribution lists

The following notes apply to the use of distribution lists.

Distribution lists are supported in the following environments:
  • [AIX]AIX®
  • [IBM i]IBM i
  • [Linux]Linux®
  • [Windows]Windows
and for IBM MQ MQI clients connected to these systems.
  1. 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.

  2. 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
  3. 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.
  4. 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 MQCC_OK and the reason code is set to MQRC_NONE; 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.
  5. 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.

  6. 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.
  7. 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.
  8. 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.
  9. A distribution list can contain only one destination.

Remote queues

The following notes apply to the use of remote queues.

A remote queue can be specified in one of two ways in the ObjDesc parameter of this call.

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

See the ObjectName and ObjectQMgrName fields described in MQOD - Object descriptor for more information.

Objects

Security

The following notes relate to the security aspects of using MQOPEN.

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 an alias queue which points at a topic object, the queue manager performs a security check on the alias queue name, before performing a security check for the topic as if the topic object had been used directly.

If the object being opened is a topic object, whether with ObjectName alone or by using the ObjectString (with or without a basing ObjectName), the queue manager performs the security check by using the resultant topic string, taken from within the topic object specified in ObjectName, and if required concatenating it with that provided in ObjectString, and then finding the closest topic object at or above that point in the topic tree to perform the security check against. This might not be the same topic object that was specified in ObjectName.

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.

[z/OS]On z/OS, the queue manager performs security checks only if security is enabled. For more information about security checking, see Setting up security on z/OS .

Attributes

The following notes relate to attributes.

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 attributes 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 TargetType 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 that 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.
      • [z/OS]On z/OS only, a change to the value of the IntraGroupqueuing queue manager attribute, or a change in the definition of the shared transmission queue (SYSTEM.QSG.TRANSMIT.QUEUE) used by the IGQ agent.

      There is one exception to this: 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 MQOO_INPUT_SHARED 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.

    [z/OS]On z/OS, the handles previously described are marked as invalid if one or more handles is currently providing MQOO_INPUT_SHARED or MQOO_INPUT_EXCLUSIVE access to the queue.

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

C invocation


MQOPEN (Hconn, &ObjDesc, Options, &Hobj, &CompCode,
       &Reason);
Declare the parameters as follows: 

MQHCONN  Hconn;     /* Connection handle */
MQOD     ObjDesc;   /* Object descriptor */
MQLONG   Options;   /* Options that control the action of MQOPEN */
MQHOBJ   Hobj;      /* Object handle */
MQLONG   CompCode;  /* Completion code */
MQLONG   Reason;    /* Reason code qualifying CompCode */

COBOL invocation


CALL 'MQOPEN' USING HCONN, OBJDESC, OPTIONS, HOBJ, COMPCODE, REASON
Declare the parameters as follows: 

**   Connection handle
 01  HCONN     PIC S9(9) BINARY.
**   Object descriptor
 01  OBJDESC.
     COPY CMQODV.
**   Options that control the action of MQOPEN
 01  OPTIONS   PIC S9(9) BINARY.
**   Object handle
 01  HOBJ      PIC S9(9) BINARY.
**   Completion code
 01  COMPCODE  PIC S9(9) BINARY.
**   Reason code qualifying COMPCODE
 01  REASON    PIC S9(9) BINARY.

PL/I invocation


call MQOPEN (Hconn, ObjDesc, Options, Hobj, CompCode, Reason);
Declare the parameters as follows: 

dcl Hconn     fixed bin(31);  /* Connection handle */
dcl ObjDesc   like MQOD;      /* Object descriptor */
dcl Options   fixed bin(31);  /* Options that control the action of
                                 MQOPEN */
dcl Hobj      fixed bin(31);  /* Object handle */
dcl CompCode  fixed bin(31);  /* Completion code */
dcl Reason    fixed bin(31);  /* Reason code qualifying CompCode */

High Level Assembler invocation


CALL MQOPEN,(HCONN,OBJDESC,OPTIONS,HOBJ,COMPCODE,REASON)
Declare the parameters as follows: 

HCONN     DS      F  Connection handle
OBJDESC   CMQODA  ,  Object descriptor
OPTIONS   DS      F  Options that control the action of MQOPEN
HOBJ      DS      F  Object handle
COMPCODE  DS      F  Completion code
REASON    DS      F  Reason code qualifying COMPCODE
[Windows]

Visual Basic invocation


MQOPEN Hconn, ObjDesc, Options, Hobj, CompCode, Reason
Declare the parameters as follows: 

Dim Hconn    As Long 'Connection handle'
Dim ObjDesc  As MQOD 'Object descriptor'
Dim Options  As Long 'Options that control the action of MQOPEN'
Dim Hobj     As Long 'Object handle'
Dim CompCode As Long 'Completion code'
Dim Reason   As Long 'Reason code qualifying CompCode'