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.
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 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
Communication happens at different levels:
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 :
WebSphere MQ Everyplace provides a choice of connection and adapter types. Depending on the selection, queue managers can be connected in the following ways:
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
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.
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
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 |
You can set up a connection so that a queue manager routes messages through an intermediate queue manager. This requires two connections:
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.
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.
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.
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.
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:
To create a local queue:
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.
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.
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.
Certain administrative actions can only be performed when the queue is in a predefined state, as follows:
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 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:
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.
An application using queue manager qm1 and putting messages to queue qm2.invQ establishes a network connection to queue manager qm2 (if it does not already exist) and the message is immediately put on the real queue. If the network connection cannot be established then the application receives an exception that it must handle.
An application using queue manager qm1 and putting messages to queue qm2.invQ stores messages temporarily on the remote queue on qm1. When the transmission rules allow, the message is moved to the real queue on queue manager qm2. The message remains on the remote queue until the transmission is successful.
To create a remote 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 ***.
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:
Figure 20. Store-and-forward queue
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:
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
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.
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
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.
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.