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.

The following topics are presented:

• Terms and Definitions

• Overview of the BEA TUXEDO Queued Message Facility

• Administrative Tasks

• Setting the QMCONFIG Environment Variable

• Using qmadmin, the /Q Administrative Interface

• Creating an Application Queue Space and Queues

• Modifying the Configuration File

Terms and Definitions

The following terms are used in this chapter.

/Q

A short name for the BEA TUXEDO Queued Message Facility

QMCONFIG

An environment variable that holds the name of the device (file) where /Q queue space is located.

Queue

A named stable storage area where service requests from client processes or responses from application servers are stored.

Queue Space

A collection of queues that can be administered as a unit.

Request Queue

A space associated with an application server where service requests are placed for processing by the server.

TMQUEUE

A BEA TUXEDO system server that accepts messages from a tpenqueue() call and places them on a /Q queue.

TMQFORWARD

A BEA TUXEDO system server that dequeues a message from a /Q queue and forwards the message to an application server.

TMS_QM

A BEA TUXEDO system server that manages transactions for /Q.

The BEA TUXEDO Queued Message Facility allows 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:

• The message queue server, TMQUEUE(5), is used to enqueue and dequeue messages. This provides a surrogate server for doing message operations for clients and servers, whether or not they are local to the queue.

• The message forwarding server, TMQFORWARD(5), is used to dequeue and forward messages to application servers. The BEA TUXEDO system provides routines for servers that handle server initialization and termination, allocate buffers to receive and dispatch incoming requests to service routines, and route replies to the correct destination. All of this processing is transparent to the application.

• Existing servers do not dequeue their own messages or enqueue replies. One goal of /Q is to be able to use existing servers to service queued messages without change. The TMQFORWARD server, for example:

  • Dequeues a message from one or more queues in the queue space

  • Forwards the message to a server that has a service with the same name as the queue

  • Waits for the reply

  • Queues the success reply or failure reply on the associated reply or failure queues (assuming the originator specified a reply or failure queue)

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:

• The queues in a queue space share the stable storage area for messages.

• A single message queue server, such as TMQUEUE in Figure 13-1, can be used to enqueue and dequeue messages for multiple queues within a single queue space.

• A single message forwarding server, such as TMQFORWARD in Figure 13-1, can be used to dequeue and forward messages for multiple queues within a single queue space.

• A single transaction manager server, such as TMS_QM in Figure 13-1, can be used to complete transactions for multiple queues within a single queue space.

• The administrator can define a single server group in the application configuration for the queue space by specifying the group in UBBCONFIG or by using tmconfig(1) to add the group dynamically.

• Finally, when the administrator moves messages between queues within a queue space, the overhead is less than if the messages were in different stable storage areas, because a one-phase commit can be done.

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 path name 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.

1. Create an entry in the UDL with the qmadmin crdl command. The device may be created on a raw slice or in a UNIX file. For example:

   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.

2. Create a queue space on the device. This will be a space on the device that will contain a collection of queues. Space is created with the qmadmin qspacecreate command.

   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.

3. Open the queue space.

   qopen queue_space_name

   The queue space has to be open for you to proceed.

4. Create individual queues within the queue space. Queues are created with the qmadmin qcreate command, as follows.

   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).

In addition to creating a queue space and queues, the system administrator needs to associate these resources with the BEA TUXEDO Queued Message Facility application 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.