Creating and deleting queue managers

A queue manager requires at least the following:

Once these definitions are in place you can run the queue manager and use the administration interface to perform further configuration, such as adding more queues.

Functions to create these initial objects are supplied in the MQeQueueManagerConfigure class.

This section provides more information to help you to use the MQeQueueManagerConfigure class.

Queue manager names

WebSphere MQ Everyplace queue manager names can contain the following characters:

Queue manager names cannot have a leading or trailing '.' character.

There are no inherent name length limitations in WebSphere MQ Everyplace.

For additional naming recommendations when interacting with WebSphere MQ networks, see Naming recommendations for inter-operability with a WebSphere MQ network.

Creating a queue manager

The basic steps required to create a queue manager are:

  1. Create and activate an instance of MQeQueueManagerConfigure
  2. Set queue manager properties and create the queue manager definition
  3. Create definitions for the default queues
  4. Close the MQeQueueManagerConfigure instance

1. Create and activate an instance of MQeQueueManagerConfigure

You create the MQeQueueManagerConfigure object by calling the mqeQueueManagerConfigure_new function. Apart from the ExceptionBlock and the new MQeQueueManagerConfigure Handle, this function takes two additional parameters.

The method of operation depends on these parameters. 'NULL' can be passed for these parameters, in which case mqeQueueManagerConfigure_activate is called immediately after mqeQueueManagerConfigure_new. Alternatively startup parameters can be passed.

The first parameter is an MQeFields object that contains initialization parameters for the queue manager. These must contain at least the following:

The directory name is stored as part of the queue manager definition and is used as a default value for the queue store in any future queue definitions. The directory does not have to exist and will be created when needed.

The example code includes creating an instance of MQeQueueManagerConfigure.

2. Set queue manager properties and create the queue manager definition

When you have activated MQeQueueManagerConfigure, but before you create the queue manager definition, you can set some or all of the following queue manager properties:

Call mqeQueueManagerConfigure_defineQueueManager( ) to create the queue manager definition. This creates a registry definition for the queue manager that includes any of the properties that you set previously.

At this point you can close() and free() MQeQueueManagerConfigure and run the queue manager, however, it cannot do much because it has no queues. You cannot add queues using the administration interface, because the queue manager does not have an administration queue to service the administration messages.

The following sections show how to create queues and make the queue manager useful.

3. Create definitions for the default queues

MQeQueueManagerConfigure allows you to define the following four standard queues for the queue manager:

All these functions return an error if the queue already exists.

The administration queue and administration reply queue are needed to allow the queue manager to respond to administration messages, for example to create new connection definitions and queues.

The dead letter queue can be used to store messages that cannot be delivered to their correct destination.

The default local queue, SYSTEM.DEFAULT.LOCAL.QUEUE, has no special significance within WebSphere MQ Everyplace itself, but it is useful when WebSphere MQ Everyplace is used with WebSphere MQ messaging because it exists on every WebSphere MQ messaging queue manager.

4. Close the MQeQueueManagerConfigure instance

When you have defined the queue manager and the required queues, you can close() MQeQueueManagerConfigure and run the queue manager. Once the close() function has been completed, the handle to the MQeQueueManagerCondigure must to be freed by calling the free() function

The registry definitions for the queue manager and the required queues are created immediately. The queues are not created until they are activated.

Deleting a queue manager

The basic steps required to delete a queue manager are:

  1. Use the administration interface to delete any definitions
  2. Create and activate an instance of MQeQueueManagerConfigure
  3. Delete the standard queue and queue manager definitions
  4. Close the MQeQueueManagerConfigure instance

When these steps are complete, the queue manager is deleted and can no longer be run. The queue definitions are deleted, but the queues themselves are not deleted. Any messages remaining on the queues are inaccessible.

Note:
If there are messages on the queues they are not automatically deleted. Your application programs should include code to check for, and handle, remaining messages before deleting the queue manager.

1. Delete any definitions

You can use MQeQueueManagerConfigure to delete the standard queues that you created with it. You should use the administration interface to delete any other queues before you call MQeQueueManagerConfigure.

2. Create and activate an instance of MQeQueueManagerConfigure

This process is the same as when creating a queue manager. See 1. Create and activate an instance of MQeQueueManagerConfigure.

3. Delete the standard queue and queue manager definitions

Delete the default queues by calling:

These functions work successfully even if the queues do not exist.

Delete the queue manager definition by calling mqeQueueManagerConfigure_deleteQueueManagerDefinition()

You can delete the default queue and queue manager definitions together by calling mqeQueueManagerConfigure_deleteStandardQMDefinitions(). This function is provided for convenience and is equivalent to:

4. Close the MQeQueueManagerConfigure instance

When you have deleted the queue and queue manager definitions, you can close the MQeQueueManagerConfigure instance.

Using queue manager aliases

Aliases can be used for WebSphere MQ Everyplace queue managers, and can be used by application programs, to provide a level of indirection between the application and the real object. Hence the attributes of a queue manager that an alias relates to can be changed without the application needing to change.

The following examples illustrate some of the ways that aliasing can be used with queue managers.

Examples of queue manager aliasing

Addressing a queue manager with several different names

Suppose you have a queue manager SERVER23QM on the server SAMPLEHOST, listening on port 8082. You have an application SERVICEX that accesses this queue manager, and wants to refer to the queue manager as SERVICEXQM. This can be achieved using an alias for the queue manager as follows:

An WebSphere MQ Everyplace application running within the server's JVM can now put messages to the SERVICEXQ on either the SERVER23QM queue manager, or the SERVICEXQM queue manager. In either case, the message will arrive on the SERVICEXQ.

Figure 4. Addressing a queue manager with two different names

Diagrammatic representation of description above

If the SERVICEXQ queue is moved to another queue manager, the connection alias can be set up on the new queue manager, and the applications do not need to be changed.

Different routings from one queue manager to another
Using the scenario just described, an WebSphere MQ Everyplace queue manager on a mobile device (MOBILE0058QM) can now access the SERVICEXQ queue in a number of different ways. Two examples are described here:


© IBM Corporation 2002. All Rights Reserved