System Administration Guide

Creating a local definition of a remote queue

A local definition of a remote queue is a definition on a local queue manager that refers to a queue on a remote queue manager.

You do not have to define a remote queue from a local position, but the advantage of doing so is that applications can refer to the remote queue by its locally-defined name instead of having to specify a name that is qualified by the ID of the queue manager on which the remote queue is located.

Understanding how local definitions of remote queues work

An application connects to a local queue manager and then issues an MQOPEN call. In the open call, the queue name specified is that of a remote queue definition on the local queue manager. The remote queue definition supplies the names of the target queue, the target queue manager, and optionally, a transmission queue. To put a message on the remote queue, the application issues an MQPUT call, specifying the handle returned from the MQOPEN call. The queue manager uses the remote queue name and the remote queue manager name in a transmission header at the start of the message. This information is used to route the message to its correct destination in the network.

As administrator, you can control the destination of the message by altering the remote queue definition.

Example

Purpose

An application needs to put a message on a queue owned by a remote queue manager.

How it works

The application connects to a queue manager, for example, saturn.queue.manager. The target queue is owned by another queue manager.

On the MQOPEN call, the application specifies these fields:

Field value	Description
`ObjectName`	Specifies the local name of the remote queue object. This defines the target queue and the target queue manager.
`ObjectType`	Identifies this object as a queue.
`ObjectQmgrName`	This field is optional. If blank, the name of the local queue manager is assumed. (This is the queue manager on which the remote queue definition exists.)

After this, the application issues an MQPUT call to put a message onto this queue.

On the local queue manager, you can create a local definition of a remote queue using the following MQSC commands:

  DEFINE QREMOTE (CYAN.REMOTE.QUEUE) +
         DESCR ('Queue for auto insurance requests from the branches') +
         RNAME (AUTOMOBILE.INSURANCE.QUOTE.QUEUE) +
         RQMNAME (jupiter.queue.manager) +
         XMITQ (INQUOTE.XMIT.QUEUE)

where:

QREMOTE (CYAN.REMOTE.QUEUE): Specifies the local name of the remote queue object. This is the name that applications connected to this queue manager must specify in the MQOPEN call to open the queue AUTOMOBILE.INSURANCE.QUOTE.QUEUE on the remote queue manager jupiter.queue.manager.
DESCR ('Queue for auto insurance requests from the branches'): Provides additional text that describes the use of the queue.
RNAME (AUTOMOBILE.INSURANCE.QUOTE.QUEUE): Specifies the name of the target queue on the remote queue manager. This is the real target queue for messages sent by applications that specify the queue name CYAN.REMOTE.QUEUE. The queue AUTOMOBILE.INSURANCE.QUOTE.QUEUE must be defined as a local queue on the remote queue manager.
RQMNAME (jupiter.queue.manager): Specifies the name of the remote queue manager that owns the target queue AUTOMOBILE.INSURANCE.QUOTE.QUEUE.
XMITQ (INQUOTE.XMIT.QUEUE): Specifies the name of the transmission queue. This is optional; if the name of a transmission queue is not specified, a queue with the same name as the remote queue manager is used.
In either case, the appropriate transmission queue must be defined as a local queue with a Usage attribute specifying that it is a transmission queue (USAGE(XMITQ) in MQSC commands).

An alternative way of putting messages on a remote queue

Using a local definition of a remote queue is not the only way of putting messages on a remote queue. Applications can specify the full queue name, including the remote queue manager name, as part of the MQOPEN call. In this case, you do not need a local definition of a remote queue. However, this means that applications must either know, or have access to, the name of the remote queue manager at run time.

Using other commands with remote queues

You can use MQSC commands to display or alter the attributes of a remote queue object, or you can delete the remote queue object. For example:

To display the remote queue's attributes:
```
DISPLAY QUEUE (CYAN.REMOTE.QUEUE)
```
To change the remote queue to enable puts. This does not affect the target queue, only applications that specify this remote queue:
```
ALTER QREMOTE (CYAN.REMOTE.QUEUE) PUT(ENABLED)
```
To delete this remote queue. This does not affect the target queue, only its local definition:
```
  DELETE QREMOTE (CYAN.REMOTE.QUEUE)
```

Note:

When you delete a remote queue, you delete only the local representation of the remote queue. You do not delete the remote queue itself or any messages on it.

Defining a transmission queue

A transmission queue is a local queue that is used when a queue manager forwards messages to a remote queue manager through a message channel.

The channel provides a one-way link to the remote queue manager. Messages are queued at the transmission queue until the channel can accept them. When you define a channel, you must specify a transmission queue name at the sending end of the message channel.

The MQSC command attribute USAGE defines whether a queue is a transmission queue or a normal queue.

Default transmission queues

When a queue manager sends messages to a remote queue manager, it identifies the transmission queue using the following sequence:

The transmission queue named on the XMITQ attribute of the local definition of a remote queue.
A transmission queue with the same name as the target queue manager. (This value is the default value on XMITQ of the local definition of a remote queue.)
The transmission queue named on the DEFXMITQ attribute of the local queue manager.

For example, the following MQSC command creates a default transmission queue on source.queue.manager for messages going to target.queue.manager:

  DEFINE QLOCAL ('target.queue.manager') +
         DESCR ('Default transmission queue for target qm') +
         USAGE (XMITQ)

Applications can put messages directly on a transmission queue, or indirectly through a remote queue definition. See also Creating a local definition of a remote queue.