Administration of managed resources

As described in previous sections, WebSphere MQ Everyplace has a set of resources that can be administered with administration messages. These resources are known as managed resources. The following sections provide information on how to manage some of these resources. For detailed description of the application programming interface for each resource see the WebSphere MQ Everyplace Java Programming Reference.

Queue managers

The complete management life-cycle for most managed resources can be controlled with administration messages. This means that the managed resource can be brought into existence, managed and then deleted with administration messages. This is not the case for queue managers. Before a queue manager can be managed it must be created and started. See Creating and deleting queue managers for information on creating and starting a queue manager.

The queue manager has very few characteristics itself, but it controls other WebSphere MQ Everyplace resources. When you inquire on a queue manager, you can obtain a list of connections to other queue managers and a list of queues that the queue manager can work with. Each list item is the name of either a connection or a queue. Once you know the name of a resource, you can use the appropriate message to manage the resource. For instance you use an MQeConnectionAdminMessage to manage connections.

Connections

Connections define how to connect one queue manager to another queue manager. Once a connection has been defined, it is possible for a queue manager to put messages to queues on the remote queue manager. The following diagram shows the constituent parts that are required for a remote queue on one queue manager to communicate with a queue on a different queue manager:

Figure 15. Queue manager connections

top

Communication happens at different levels:

Transporter:
Logical connection between two queues

Connection:
Logical connection between two systems

Adapter:
Protocol specific communication

The connection and adapter are specified as part of a connection definition. The transporter is specified as part of a remote queue definition.

To create a suitable Connection Admin Msg, use the primeAdminMsg function shown in the Example files Admin-Ex1. Set the Remote Queue Manager name, using the mqeAdminMsg_setName function, and then call the mqeConnectionAdminMsg_create function.

To add a connection :

  1. Create a new MQeConnectionAdminMsg
  2. Prime the admin message
  3. Set the remote queuemanager name
  4. Call mqeConnectionAdminMsg_create

WebSphere MQ Everyplace provides a choice of connection and adapter types. Depending on the selection, queue managers can be connected in the following ways:

Client to server

In a client to server configuration, one queue manager acts as a client and the other runs in a server environment. A server allows multiple simultaneous incoming connections. To accomplish this the server must have components that can handle multiple incoming requests. See Server queue managers for a description of how to run a queue manager in a server environment.

Figure 16 shows the typical connection components in a client to server configuration.

Figure 16. Client to server connections

top

You use MQeConnectionAdminMsg to configure the client portion of a connection. The connection type is com.ibm.mqe.MQeChannel. Normally an alias of DefaultChannel is configured for MQeChannel.

Create a connection, as described previously and then use the standard putMessage calls to send the message to the administration queue.

Peer to peer

In a peer to peer configuration, a queue manager running as a peer can talk to many other peers simultaneously but can only have one other peer talk to it at any time. One peer is configured as a master or initiator, the other as a slave or receiver.

You configure the master in much the same way as a client connection definition, the only difference being the type of connection to use. The connection type must be set to com.ibm.mqe.adapters.MQePeerChannel (or an alias).

Figure 17. Peer to peer connections

top

You configure the slave or receiver in a similar way but with the following differences:

Create a connection, as described previously and then use the standard putMessage calls to send the message to the administration queue.

The following table shows the connection definition parameters for a receiver on PeerQM1 and for any other peer queue manager that would like to communicate with it.

Table 9. Peer-to-peer connection definitions


Master (Initiator) Slave (Receiver)
Queue Manager Any "PeerQM1"
Connection name "PeerQM1" "PeerQM1"
Channel com.ibm.mqe.MQePeerChannel com.ibm.mqe.MQePeerChannel
Adapter Network:192.168.0.10:8082 Network::8082

Routing connections

You can set up a connection so that a queue manager routes messages through an intermediate queue manager. This requires two connections:

  1. A connection to the intermediate queue manager
  2. A connection to the target queue manager

The first connection is created by the functions described earlier in this section, either as a client or as a peer connection. For the second connection, the name of the intermediate queue manager is specified in place of the network adapter name. With this configuration an application can put messages to the target queue manager but route them through one or more intermediate queue managers.

Aliases

You can assign multiple names or aliases to a connection (see Class Aliases). When an application calls functions on the MQeQueueManager class that require a queue manager name be specified, it can also use an alias.

You can alias both local and remote queue managers. To alias a local queue manager, you must first establish a connection definition with the same name as the local queue manager. This is a logical connection that can have all parameters set to null.

To add and remove aliases use the MQE_ADMIN_ACTION_ADDALIAS and MQE_ADMIN_ACTION_REMOVEALIAS actions of the MQeConnectionAdminMsg class. You can add or remove multiple aliases in one message. Put the aliases that you want to manipulated directly into the message by setting the ascii array field Con_Aliases. Alternatively you can use the two functions addAlias() or removeAlias(). Each of these functions takes one alias name but you can call the function repeatedly to add multiple aliases to a message.

Queues

The queue types provided by WebSphere MQ Everyplace are described briefly in WebSphere MQ Everyplace queues. The simplest of these is a local queue that is implemented in class MQeQueue and is managed by class MQeQueueAdminMsg. All other types of queue inherit from MQeQueue. For each type of queue there is a corresponding administration message that inherits from MQeQueueAdminMsg. The following sections describe the administration of the various types of queues.

Local queue

You can create, update, delete and inquire on local queues and their descendents using administration actions provided in WebSphere MQ Everyplace. The basic administration mechanism is inherited from MQeAdminMsg.

The name of a queue is formed from the target queue manager name (for a local queue this is the name of the queue manager that owns the queue) and a unique name for the queue on that queue manager. Two fields in the administration message are used to uniquely identify the queue, these are the ascii fields MQE_ADMIN_NAME and MQE_QUEUE_QMGRNAME. You can use the setName( queueManagerName, queueName) function to set these two fields in the administration message.

The diagram below shows an example of a queue manager configured with a local queue. Queue manager qm1 has a local queue named invQ. The queue manager name characteristic of the queue is qm1, which matches the queue manager name.

Figure 18. Local queue

top

Message Store

Local queues require a message store to store their messages. Each queue can specify what type of store to use, and where it is located. Use the queue characteristic Queue_FileDesc to specify the type of message store and to provide parameters for it. The field type is ascii and the value must be a file descriptor of the form:
adapter class:adapter parameters
or
adapter alias:adapter parameters

For example:

MsgLog:d:\QueueManager\ServerQM12\Queues

WebSphere MQ Everyplace Version 2.0 provides two adapters, one for writing messages to disk and one for storing them in memory. By creating an appropriate adapter, messages can be stored in any suitable place or medium (such as DB2 database or writable CDs).

The choice of adapter determines the persistence and resilience of messages. For instance if a memory adapter is used then the messages are only as resilient as the memory. Memory may be a much faster medium than disk but is highly volatile compared to disk. Hence the choice of adapter is an important one.

If you do not provide message store information when creating a queue, it defaults to the message store that was specified when the queue manager was created. See Queue managers, messages, and queues for more details.

The following should be taken into consideration when setting the Queue_FileDesc field:

Creating a local queue

To create a local queue:

  1. Create a new MQeQueueAdminMsg
  2. Prime the administration message
  3. Call mqeQueueAdminMsg_setName() function to set the queue and queue manager name
  4. Create an MQeFields object containing entries for the characteristics. Typical entries would be:
  5. Call the mqeAdminMsg_create function
  6. Put the message to the administration queue

Queue security

Access and security are owned by the queue and may be granted for use by a remote queue manager (when connected to a network), allowing these other queue managers to send or receive messages to the queue. The following characteristics are used in setting up queue security:

For more detailed information on setting up queue based security see Security.

Other queue characteristics

You can configure queues with many other characteristics such as the maximum number of messages that are permitted on the queue. For a description of these, see the MQeQueueAdminMsg section of the WebSphere MQ Everyplace Java Programming Reference.

Aliases

Queue names can have aliases similar to those described for connections in Aliases. The code fragment in the connections section alias example shows how to setup aliases on a connection, setting up aliases on a queue is the same except that an MQeQueueAdminMsg is used instead of an MQeConnectionAdminMsg.

Action restrictions

Certain administrative actions can only be performed when the queue is in a predefined state, as follows:

Action_Update

Action_Delete
The queue cannot be deleted if the queue is in use or if there are messages on the queue

If the request requires that the queue is not in use, or that it has zero messages, the administration request can be retried, either when the queue manager restarts or at regular time intervals. See The basic administration request message for details on setting up an administration request retry.

Remote queue

Remote queues are implemented by the MQeRemoteQueue class and are managed with the MQeRemoteQueueAdminMsg class which is a subclass of MQeAdminMsg.

The name of a queue is formed from the target queue manager name (for a remote queue this is the name of the queue manager where the queue is local) and the real name of the queue on that queue manager. Two fields in the administration message are used to uniquely identify the queue, these are the ascii fields MQE_ADMIN_NAME and MQE_QUEUE_QMGRNAME. You can use the setName( queueManagerName, queueName) function to set these two fields in the administration message. For a remote queue definition, the queue manager name of the queue never matches the name of the queue manager where the definition resides.

The remote definition of the queue should, in most cases, match that of the real queue. If this is not the case different results may be seen when interacting with the queue. For instance:

Setting the operation mode

To set a queue for synchronous operation, set the MQE_QUEUE_MODE field to MQE_QUEUE_SYNCHRONOUS.

Asynchronous queues require a message store to temporarily store messages. Definition of this message store is the same as for local queues (see Message Store).

To set a queue for asynchronous operation, set the MQE_QUEUE_MODE field to MQE_QUEUE_ASYNCHRONOUS.

Figure 19 shows an example of a remote queue set up for synchronous operation and a remote queue setup for asynchronous operation.

Figure 19. Remote queue

top

Creating a remote queue

To create a remote queue:

  1. Create a new MQeRemoteQueueAdminMsg
  2. Prime this administration message
  3. Set the queue and queue manager names
  4. Create an MQeFields object to hold the characteristics (Typically, description, queue mode, and queue store)
  5. Call the create function
  6. Put the message to administration queue

For synchronous operation, the queue characteristics for inclusion in the remote queue definition can be obtained using queue discovery which is explained on page ***.

Store-and-forward queue

This type of queue is normally defined on a server and can be configured in the following ways:

Store-and-forward queues are implemented by the MQeStoreAndForwardQueue class. They are managed with the MQeStoreAndForwardQueueAdminMsg class, which is a subclass of MQeRemoteQueueAdminMsg. The main addition in the subclass is the ability to add and remove the names of queue managers for which the store-and-forward queue can hold messages. You can add and delete queue manager names with the MQE_ACTION_ADD_QMGR and MQE_ACTION_REMOVE_QMGR actions. You can add or remove multiple queue manager names with one administration message. You can put the names directly into the message by setting the ascii array field MQE_QUEUE_QMGRNAMELIST. Alternatively you can use the addQueueManager() and removeQueueManager() functions. Each of these functions takes one queue manager name but you can call the function repeatedly to add multiple queue managers to a message.

To add a queue manager:

  1. Create a new MQeStoreAndForwardQueueAdminMsg object
  2. Prime the administration message
  3. Set queue and queue manager names
  4. Call the mqeStoreAndForwardQueueAdminMsg_addQueueManager function

Figure 20. Store-and-forward queue

top

Each store-and-forward queue has to be configured to handle messages for any queue managers for which it can hold messages. Use the MQE_ACTION_ADD_QMGR action, described earlier in this section, to add the queue manager information to each queue.

If you want the store-and-forward queue to push messages to the next queue manager, the queue manager name attribute of the store-and-forward queue must be the name of the next queue manager. A connection with the same name as the next queue manager must also be configured. The store-and-forward queue uses this connection as the transport mechanism for pushing messages to the next hop.

If you want the store-and-forward queue to wait for messages to be collected (pulled), the queue manager name attribute of the store-and-forward queue has no meaning (but it must still be configured). The only restriction on the queue manager attribute of the queue name is that there must not be a connection with the same name. If there is such a connection, the queue tries use the connection to forward messages.

Figure 20 shows an example of two store and forward queues on different queue managers, one setup to push messages to the next queue manager, the other setup to wait for messages to be collected:

If a queue manager wants to send a message to another queue manager using a store-and-forward queue on an intermediate queue manager, the initiating queue manager must have:

When these conditions are fulfilled, an application can put a message to the target queue on the target queue manager without having any knowledge of the layout of the queue manager network. This means that changes to the underlying queue manager network do not affect application programs.

In Figure 20 queue manager qm1 has been configured to allow messages to be put to queue invQ on queue manager qma. The configuration consists of:

If an application program uses queue manager qm1 to put a message to queue invQ on queue manager qma the message flows as follows:

  1. The application puts the message to asynchronous queue qma.invQ. The message is stored locally on qm1 until transmission rules allow the message to be moved to the next hop
  2. When transmission rules allow, the message is moved. Based on the connection definition for qma, the message is routed to queue manager qm2
  3. The only queue configured to handle messages for queue invQ on queue manager qma is store-and-forward queue qm3.SFQ on qm2. The message is temporarily stored in this queue
  4. The stored and forward queue has a connection that allows it to push messages to its next hop which is queue manager qm3
  5. Queue manager qm3 has a store-and-forward queue qm3.SFQ that can hold messages destined for queue manager qma so the message is stored on that queue
  6. Messages for qma remain on the store-and-forward queue until they are collected by queue manager qma. See Home-server queue for how to set this up.

Home-server queue

Home-server queues are implemented by the MQeHomeServerQueue class. They are managed with the MQeHomeServerQueueAdminMsg class which is a subclass of MQeRemoteQueueAdminMsg. The only addition in the subclass is the MQE_QUEUE_QTIMERINTERVAL characteristic. This field is of type int and is set to a millisecond timer interval. If you set this field to a value greater than zero, the home-server queue checks the home server every n milliseconds to see if there are any messages waiting for collection. Any messages that are waiting are delivered to the target queue. A value of 0 for this field means that the home-server is only polled when the mqeQueueManager_triggerTransmission function is called

Note:
If a home-server queue fails to connect to its store-and-forward queue (for instance if the store-and-forward queue is unavailable when the home server queue starts) it will stop trying until a trigger transmit call is made.

Figure 21. Home-server queue

top

The name of the home-server queue is set as follows:

The queue manager where the home-server queue resides must have a connection configured to the home-server queue manager.

Figure 21 shows an example of a queue manager qm3 that has a home-server queue SFQ configured to collect messages from its home-server queue manager qm2.

The configuration consists of:

Any messages that are directed to queue manager qm3 through qm2 are stored on the store-and-forward queue SFQ on qm2 until the home-server queue on qm3 collects them.

WebSphere MQ-bridge queue

A WebSphere MQ-bridge queue is a remote queue definition that refers to a queue residing on a WebSphere MQ queue manager. The queue holding the messages resides on the WebSphere MQ queue manager, not on the local queue manager.

Figure 22. WebSphere MQ-bridge queue

Diagrammatic representation of use of an WebSphere MQ-bridge queue described in detail below.

The definition of the bridge queue requires that bridge, WebSphere MQ queue manager proxy, and client connection names are specified to uniquely identify a client connection object in the bridge object hierarchy (see Figure 23). This information identifies how the WebSphere MQ-bridge accesses the WebSphere MQ queue manager, to manipulate a WebSphere MQ queue.

The WebSphere MQ-bridge queue provides the facility to put to a queue on a queue manager that is not directly connected to the WebSphere MQ-bridge. This allows a message to be sent to a WebSphere MQ queue manager (the target) routed through another WebSphere MQ queue manager. The WebSphere MQ-bridge queue takes the name of the target queue manager and the intermediate queue manager is named by the WebSphere MQ queue manager proxy.

For a complete list of the characteristics used by the WebSphere MQ-bridge queue, see the WebSphere MQ-bridge section of the WebSphere MQ Everyplace C Programming Reference..

Table 10 details the list of operations supported by the WebSphere MQ-bridge queue, once it has been configured:

Table 10. Message operations supported by WebSphere MQ--bridge queue

Type of operation Supported by WebSphere MQ-bridge queue
getMessage() yes*
putMessage() yes
browseMessage() Yes*
browseAndLockMessage no
Note: * These functions have restrictions on their use. See Getting and browsing messages from the WebSphere MQ-bridge queue

If an application attempts to use one of the unsupported operations, an MQeException of Except_NotSupported is returned.

When an application puts a message to the bridge queue, the bridge queue takes a logical connection to the WebSphere MQ queue manager from the pool of connections maintained by the bridge's client connection object. The logical connection to WebSphere MQ is supplied by either the WebSphere MQ Java Bindings classes, or the WebSphere MQ Classes for Java. The choice of classes depends on the value of the hostname field in the WebSphere MQ queue manager proxy settings. Once the WebSphere MQ-bridge queue has a connection to the WebSphere MQ queue manager, it attempts to put the message to the WebSphere MQ queue.

An WebSphere MQ-bridge queue must always have an access mode of synchronous and cannot be configured as an asynchronous queue. This means that, if your put operation is directly manipulating an WebSphere MQ-bridge queue and returns success, your message has passed to the WebSphere MQ system while your process was waiting for the put operation to complete.

If you do not wish to use synchronous operations against the WebSphere MQ-bridge queue, you may set up an asynchronous remote queue definition (see Asynchronous messaging) that refers to the WebSphere MQ-bridge queue. Alternatively you can set up a store-and-forward queue, and home-server queue. These two alternative configurations provide the application with an asynchronous queue to which it can put messages. With these configurations, when your putMessage() function returns, the message may not necessarily have passed to the WebSphere MQ queue manager.

An example of WebSphere MQ-bridge queue usage is described in Configuration example.

Administration queue

The administration queue is implemented in class MQeAdminQueue and is a subclass of MQeQueue so it has the same features as a local queue. It is managed using administration class MQeAdminQueueAdminMsg.

If a message fails because the resource to be administered is in use, it is possible to request that the message be retried. The basic administration request message provides details on setting up the maximum number attempts count. If the message fails due to the managed resource not being available and the maximum number of attempts has not been reached, the message is left on the queue for processing at a later date. If the maximum number of attempts has been reached, the request fails with an MQeException. By default the message is retried the next time the queue manager is started. Alternatively a timer can be set on the queue that processes messages on the queue at specified intervals. The timer interval is specified by setting the long field MQE_QUEUE_QTIMERINTERVAL field in the administration message. The interval value is specified in milliseconds.



© IBM Corporation 2002. All Rights Reserved