Name resolution
How the MQOPEN call resolves queue and queue manager names.
Note: A Queue manager alias is a remote queue definition without an RNAME field.When you open an IBM MQ queue, the MQOPEN call performs a name resolution function on the queue name that you specify. This determines on which queue the queue manager performs subsequent operations. This means that when you specify the name of an alias queue or a remote queue in your object descriptor (MQOD), the call resolves the name either to a local queue or to a transmission queue. If a queue is opened for any type of input, browse, or set, it resolves to a local queue if there is one, and fails if there is not one. It resolves to a nonlocal queue only if it is opened for output only, inquire only, or output and inquire only. See Table 1 for an overview of the name resolution process. The name that you supply in ObjectQMgrName is resolved before that in ObjectName.
Table 1 also shows how we can use a local definition of a remote queue to define an alias for the name of a queue manager. This allows you to select which transmission queue is used when you put messages on a remote queue, so you could, for example, use a single transmission queue for messages destined for many remote queue managers.
To use the following table, first read down the two left-hand columns, under the heading Input to MQOD, and select the appropriate case. Then read across the corresponding row, following any instructions. Following the instructions in the Resolved names columns, we can either return to the Input to MQOD columns and insert values as directed, or we can exit the table with the results supplied. For example, you might be required to input ObjectName.
| Input to MQOD | Input to MQOD | Resolved names | Resolved names | Resolved names |
|---|---|---|---|---|
| ObjectQMgrName | ObjectName | ObjectQMgrName | ObjectName | Transmission queue |
| Blank or local queue manager | Local queue with no CLUSTER attribute | Local queue manager | Input ObjectName | Not applicable (local queue used) |
| Blank queue manager | Local queue with CLUSTER attribute | Workload management selected cluster queue manager or specific cluster queue manager selected on PUT | Input ObjectName | SYSTEM.CLUSTER.TRANSMIT.QUEUE and local queue used SYSTEM.QSG.TRANSMIT.QUEUE (see note) |
| Local queue manager | Local queue with CLUSTER attribute | Local queue manager | Input ObjectName | Not applicable (local queue used) |
| Blank or local queue manager | Model queue | Local queue manager | Generated name | Not applicable (local queue used) |
| Blank or local queue manager |
Alias queue with or without CLUSTER attribute |
Perform name resolution again with ObjectQMgrName unchanged, and input ObjectName set to the BaseQName in the alias queue definition object.
Must not resolve to an alias locally defined where the ObjectQMgrName is specified, but can resolve to a clustered alias (hosted on other queue managers) where the ObjectQMgrName is blank. |
||
| Local queue manager | Alias queue with CLUSTER attribute | The alias must not resolve to a cluster queue that is not locally defined, or a cluster queue that has the same ObjectName as the alias. | ||
| Blank queue manager | Alias queue with CLUSTER attribute | The alias can resolve to a cluster queue with same ObjectName as the alias. | ||
| Blank or local queue manager |
Local definition of a remote queue |
Perform name resolution again with ObjectQMgrName set to RemoteQMgrName, and ObjectName set to RemoteQName. Must not resolve remote queues | Name of XmitQName attribute, if non-blank; otherwise
RemoteQMgrName in the remote queue definition object.
SYSTEM.QSG.TRANSMIT.QUEUE (see note) |
|
| Blank queue manager | No matching local object; cluster queue found | Workload management selected cluster queue manager or specific cluster queue manager selected on PUT | Input ObjectName | SYSTEM.CLUSTER.TRANSMIT.QUEUE SYSTEM.QSG.TRANSMIT.QUEUE (see note) |
| Blank or local queue manager | No matching local object; cluster queue not found | Error, queue not found | Not applicable | |
| Name of queue manager in same queue sharing group as local queue manager | Local shared queue | Local queue manager | Input ObjectName | Not applicable |
| Name of a local transmission queue | (Not resolved) | Input ObjectQMgrName | Input ObjectName | Input ObjectQMgrName
SYSTEM.QSG.TRANSMIT.QUEUE (see note) |
| Queue manager alias definition (RemoteQMgrName may be the local queue manager) | (Not resolved, remote queue) | Perform name resolution again with ObjectQMgrName set to RemoteQMgrName. Must not resolve to remote queues | Input ObjectName | Name of XmitQName attribute, if non-blank; otherwise
RemoteQMgrName in the remote queue definition object.
SYSTEM.QSG.TRANSMIT.QUEUE (see note) |
| Queue manager is not the name of any local object; cluster queue managers or queue manager alias found | (Not resolved) | ObjectQMgrName or specific cluster queue manager selected on PUT | Input ObjectName | SYSTEM.CLUSTER.TRANSMIT.QUEUE SYSTEM.QSG.TRANSMIT.QUEUE (see note) |
| Queue manager is not the name of any local object; no cluster objects found | (Not resolved) | Input ObjectQMgrName | Input ObjectName | DefXmitQName attribute of the queue manager where
DefXmitQName is supported. SYSTEM.QSG.TRANSMIT.QUEUE (see note) |
- BaseQName is the name of the base queue from the definition of the alias queue.
- RemoteQName is the name of the remote queue from the local definition of the remote queue.
- RemoteQMgrName is the name of the remote queue manager from the local definition of the remote queue.
- XmitQName is the name of the transmission queue from the local definition of the remote queue.
- When using IBM MQ for z/OS® queue managers that are part
of a queue sharing group (QSG), the name of the queue sharing group can be used instead of the local queue manager
name in Table 1.
If the local queue manager cannot open the target queue, or put a message to the queue, the message is transferred to the specified ObjectQMgrName through, either intra-group queuing, or an IBM MQ channel.
- In the ObjectName column of the table, CLUSTER refers to both the CLUSTER and CLUSNL attributes of the queue.
- The SYSTEM.QSG.TRANSMIT.QUEUE is used if local and remote queue managers are in the same queue sharing group; intra-group queuing is enabled.
- If we have assigned a different cluster transmission queue to each cluster-sender channel, SYSTEM.CLUSTER.TRANSMIT.QUEUE might not be the name of the cluster transmission queue. For more information about multiple cluster transmission queues, see Clustering: Planning how to configure cluster transmission queues.
- In the situation where the queue manager is not the name of any local object; cluster queue
managers, or queue manager alias found.
When we have supplied a queue manager name using ObjectQMgrName, and there are multiple cluster channels with different cluster names known by the local queue manager that would reach that destination, then any of these channels might be used to move the message, regardless of the cluster name of the destination queue.
This might be unexpected, if you were anticipating messages for that queue only to be sent through a channel that has the same cluster name as the queue.
However, the ObjectQMgrName takes precedence in this case, and cluster workload balancing takes into consideration all channels that might reach that queue manager, regardless of the cluster name they are in.
Opening an alias queue also opens the base queue to which the alias resolves, and opening a remote queue also opens the transmission queue. Therefore we cannot delete either the queue that you specify or the queue to which it resolves while the other one is open.
While an alias queue is unable to resolve to another locally defined alias queue (shared in a cluster or not), resolving to a remotely defined cluster alias queue is permitted and can therefore be specified as the base queue.
The resolved queue name and the resolved queue manager name are stored in the ResolvedQName and ResolvedQMgrName fields in the MQOD.
For more information about name resolution in a distributed queuing environment see What is queue name resolution?.