Usage notes

  1. The object opened is one of the following:
  2. 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.
  3. 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 may include one or more of the following for a given MQOPEN call:

    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:

    Refer to the WebSphere MQ Queue Manager Clusters book for more information about name resolution for cluster queues.

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

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

  6. 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): In either case:
  7. 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 subsequently 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.

  8. The following notes apply to the use of distribution lists.
    1. 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.

    2. Only the following open options are valid in the OPTS parameter:
      • OOOUT
      • OOPAS*
      • OOSET*
      • OOALTU
      • OOFIQ
    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 RC2057. 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 and reason code are set to CCOK and RCNONE respectively; 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.
    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 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.

    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 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.
    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 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.
    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. It is valid for a distribution list to contain only one destination.
  9. 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 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 may 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.
    2. 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, refer to the WebSphere MQ Queue Manager Clusters book.

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

  12. When using the MQOO_RESOLVE_LOCAL_QUEUE 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 filled in with the RemoteQName and RemoteQMgrName found in the remote queue definition, or similarly with the chosen remote cluster queue. If MQOO_RESOLVE_LOCAL_QUEUE is specified when opening, for example, a remote queue, ResolvedQName will now be the transmission queue which messages will be actually put to. The ResolvedQMgrName will be filled in 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.