|
|
|
|
|
|
Managing Queued Messages (BEA Tuxedo System)
This chapter, which is specific to the BEA Tuxedo system, describes how to configure the BEA Tuxedo Queued Message Facility for your application, and how to manage the facility when the application goes into production.
This topic includes the following sections:
Terms and Definitions
The following terms are used in this chapter.
Overview of the BEA Tuxedo Queued Message Facility
The BEA Tuxedo Queued Message Facilityallows messages to be queued to stable storage for later processing. Primitives are added to the BEA Tuxedo system application-transaction manager interface (ATMI), that provide for messages to be added to or read from stable-storage queues. Reply messages and error messages can be queued for later return to client programs. An administrative command interpreter is provided for creating, listing, and modifying the queues. Prewritten servers are included to accept requests to enqueue and dequeue messages, to forward messages from the queue for processing, and to manage the transactions that involve the queues.
Administrative Tasks
The BEA Tuxedo system administrator is responsible for defining servers and creating queue space and queues like those shown between the vertical dashed lines in Figure 13-1.
The administrator must define at least one queue server group with TMS_QM as the transaction manager server for the group.
Two additional system-provided servers need to be defined in the configuration file. These servers perform the following functions:
Also, the administrator must create a queue space using the queue administration program, qmadmin(1). The queue space contains a collection of queues. In Figure 13-1, for example, four queues are present within the queue space named APP. There is a one-to-one mapping of queue space to queue server group since each queue space is a resource manager (RM) instance and only a single RM can exist in a group.
The notion of queue space allows for reducing the administrative overhead associated with a queue by sharing the overhead among a collection of queues in the following ways:
Figure 13-1 shows how the BEA Tuxedo Queued Message Facility works. The queue spaces and queues shown between the vertical dashed lines must be defined by the system administrator.
Figure 13-1 Overview of the Queued Message Facility
In Figure 13-1 (Steps 1, 2, and 3), a client enqueues a message to the SERVICE1 queue in the APP queue space using tpenqueue(). Optionally, the names of a reply queue and a failure queue can be included in the call to tpenqueue(). In Figure 13-1 they are the queues CLIENT_REPLY1 and FAILURE_Q. The client can specify a "correlation identifier" value to accompany the message. This value is persistent across queues so that any reply or failure message associated with the queued message can be identified when it is read from the reply or the failure queue.
The client can use the default queue ordering (for example, a time after which the message should be dequeued), or can specify an override of the default queue ordering (asking, for example, that this message be put at the top of the queue or ahead of another message on the queue). The call to tpenqueue() sends the message to the TMQUEUE server, the message is queued to stable storage, and an acknowledgment (step 3) is sent to the client. The acknowledgment is not seen directly by the client, but can be assumed when the client gets a successful return. (A failure return includes information about the nature of the failure.)
A message identifier assigned by the queue manager is returned to the application. The identifier can be used to dequeue a specific message. It can also be used in another tpenqueue() to identify a message already on the queue that the subsequent message should be enqueued ahead of.
Before an enqueued message is made available for dequeuing, the transaction in which the message is enqueued must be committed successfully.
When the message reaches the top of the queue, the TMQFORWARD server dequeues the message and forwards it, via tpcall(), to a service with the same name as the queue name. In Figure 13-1 the queue and the service are both named SERVICE1; steps 4, 5, and 6 show the transfer and return of the message. The client identifier and the application authentication key are set to the client that caused the message to be enqueued; they accompany the dequeued message as it is sent to the service.
When the service returns a reply, TMQFORWARD enqueues the reply (with an optional user-return code) to the reply queue (step 7 in Figure 13-1). Sometime later, the client uses tpdequeue() to read from the reply queue (CLIENT_REPLY1), and to get the reply message (steps 8, 9, and 10 in Figure 13-1). Messages on the reply queue are not automatically cleaned up; they must be dequeued, either by an application client or server, or by a TMQFORWARD server.
Part of the task of defining a queue is specifying the order for messages on the queue. Queue ordering can be time-based, priority based, FIFO or LIFO, or a combination of these sort criteria. The administrator specifies one or more of these criteria for the queue, listing the most significant criteria first. FIFO or LIFO can be specified only as the least significant sort criteria. Messages are put on the queue according to the specified sort criteria, and dequeued from the top of the queue.
The administrator can configure as many message queuing servers as are needed to keep up with the requests generated by clients for the stable queues.
Data-dependent routing can be used to route between multiple server groups with servers offering the same service.
For housekeeping purposes, the administrator can set up a command to be executed when a threshold is reached for a queue that does not routinely get drained. The threshold can be based on the bytes, blocks, or percentage of the queue space used by the queue, or the number of messages on the queue. The command set up by the administrator might boot a TMQFORWARD server to drain the queue or send mail to the administrator for manual handling.
Setting the QMCONFIG Environment Variable
The environment variable QMCONFIG must be set and exported before work can be done to create a queue space. A BEA Tuxedo system application uses a Universal Device List (UDL). The QMCONFIG variable must contain the full pathname of the device list, such as the path shown in the following example.
$ QMCONFIG = /dev/rawfs; export QMCONFIG
The commands provided by qmadmin, (the /Q administrative interface), will not work unless this location is defined. The information can be furnished on the command line as well as in the environment variable. If it is specified in both places, the information on the command line takes precedence.
Using qmadmin, the /Q Administrative Interface
/Q has an administrative program, qmadmin(1), that is used to create and administer queues. The following sections include a sampling of the available commands. For a complete list of qmadmin commands, refer to the qmadmin(1) reference page in the BEA Tuxedo Reference Manual.
Creating an Application Queue Space and Queues
Complete the following four steps to create an application queue space and queues.
qmadmin # to start the qmadmin command
crdl device offset size
where device is the same device named in the QMCONFIG variable; offset is the block number within the UDL where space may begin to be allocated (the first entry must have an offset of 0), and size is the number of blocks to allocate. To make the example more realistic, it might be like the following:
crdl /dev/rawfs 500 500
which says create an entry on the device /dev/rawfs 500 blocks from the start of the UDL and allocate 500 blocks. Implicit in this request is the presence of an existing entry, since the offset 0 is not specified. If you enter crdl without arguments, the software prompts you for information. You can create up to 25 entries on a device list.
qspacecreate queue_space_name ipckey pages queues trans procs\ messages errorq inityn
If you enter qspacecreate without arguments, the software prompts you for information. This is probably the better choice for this command because the prompts explain the information you need to provide. The following is an example from the qmadmin(1) reference page.
> qspacecreate
Queue space name: myqueuespace
IPC Key for queue space: 42000
Size of queue space in disk pages: 50000
Number of queues in queue space: 30
Number of concurrent transactions in queue space: 20
Number of concurrent processes in queue space: 30
Number of messages in queue space: 20000
Error queue name: ERRORQ
Initialize extents (y, n [default=n]): y
Blocking factor [default=16]: 16
The IPC key value must be unique and different from the value specified in the RESOURCES section. The number of disk pages specified as the size of the queue space varies from application to application and depends on the number of queues, the number of messages to be handled and the size of the messages. The specification for the number of concurrent processes in the queue space must be large enough to include four or five possible BEA Tuxedo system processes.
qopen queue_space_name
The queue space has to be open for you to proceed.
qcreate queue_name qorder out-of-order retries delay high low
This is another command where it is better to allow the software to prompt you for information. The following is an example from qmadmin(1) (using mostly default values where available).
>qcreate Queue name: service1 queue order (priority, time, fifo, lifo): fifo out-of-ordering enqueuing (top, msgid, [default=none]):none retries [default=0]: 0 retry delay in seconds [default=0]: 0 High limit for queue capacity warning (b for bytes used, B for blocks used, % for percent used, m for messages [default=100%]): 100% Reset (low) limit for queue capacity warning [default=0%]: 50% queue capacity command: /usr/app/bin/mailadmin myqueuespace service1
Retries specifies the number of times the system attempts to enqueue the message.
We recommend that you read the qmadmin(1) reference page in the BEA Tuxedo Reference Manual carefully and that you also read the "Administration" chapter of the BEA Tuxedo System /Q Guide. The parameters that you enter for the qcreate command control the way the queue operates for your application. Of particular importance is the choice for the order in which messages are placed on the queue (they are always removed from the top).
Modifying the Configuration File
In addition to creating a queue space and queues, the system administrator needs to associate these resources with the BEA Tuxedo Queued Message Facilityapplication by editing the configuration file as described in the remaining sections of this chapter.
The configuration changes involve making an entry in the GROUPS section for the group that owns the queue and the transaction server (TMS_QM), and listing (in the SERVERS section) the two servers (TMQUEUE and TMQFORWARD).
Note: The chronological order of these specifications is not critical. The configuration file can be created either before or after the queue space is defined. The important thing is that the configuration must be defined and queue space and queues must be created before the facility can be used.
Associating a Queue with a Group
A server group must be defined for each queue space the application expects to use. In addition to the standard requirements of a group name tag and a value for GRPNO, the TMSNAME and OPENINFO parameters need to be set, as shown in the following example.
TMSNAME=TMS_QM
and
OPENINFO="TUXEDO/QM:device_name:queue_space_name"
(See the ubbconfig(5) reference page in the BEA Tuxedo Reference Manual for details.)
TMS_QM is the name for the transaction manager server for the BEA Tuxedo Queued Message Facility. In the OPENINFO parameter, TUXEDO/QM is the literal name for the resource manager as it appears in $TUXDIR/udataobj/RM. The values for device_name and queue_space_name are instance-specific and must be set to the path name for the universal device list and the name associated with the queue space, respectively.
The following example includes some of the detail.
*GROUPS
QUE1
LMID = SITE1 GRPNO = 2
TMSNAME = TMS_QM TMSCOUNT = 2
OPENINFO = "TUXEDO/QM:/dev/rawfs:myqueuespace"
Note the use of quotation marks around the information for OPENINFO. We recommend using quotation marks in this way to protect your entries in the configuration file.
Listing the /Q Servers in the SERVERS Section
Three servers are provided with the BEA Tuxedo Queued Message Facility. One is the TMS server, TMS_QM, that is the transaction manager server for the /Q resource manager. TMS_QM is defined in the GROUPS section of the configuration file.
The other two, TMQUEUE(5) and TMQFORWARD(5), provide services to users. They must be defined in the SERVERS section of the configuration file, as follows.
*SERVERS
TMQUEUE SRVGRP=QUE1 SRVID=1 CLOPT="-s QSPACENAME:TMQUEUE - - "
TMQFORWARD SRVGRP=QUE1 SRVID=5 CLOPT="- - -I 2 -q STRING"
The application can also create its own queue servers. If the functionality of TMQFORWARD, for example, does not fully meet the needs of the application, you might want to have a special server written. You might, for example, create a server that dequeues messages moved to the error queue, which TMQFORWARD does not do.
|
|
|
|
|
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|