[Top]
[Previous Page] [Next Page] [Bottom]
This chapter 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:
The following terms are used in this chapter.
QMCONFIG
TMQUEUE
tpenqueue()
call and places them on
a /Q queue. TMQFORWARD
TMS_QM
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 provides 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.
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 10-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:
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. 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. TMQFORWARD
server, for example: Also, the administrator must create a queue space using the queue administration
program, qmadmin
(1). The
queue space contains a collection of queues. In
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:
TMQUEUE
in TMQFORWARD
in TMS_QM
in UBBCONFIG
or by using tmconfig
(1) to add the group dynamically. Figure 10-1 Overview of the Queued Message Facility
In
Figure 10-1 (Steps 1, 2, and 3), a client enqueues a message to theSERVICE1
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 10-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
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
tpdequeue()
to read from the reply
queue (CLIENT_REPLY1
),
and to get the reply message (steps 8, 9, and 10 in Figure
10-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.
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.
/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.
Complete the following four steps to create an application queue space and queues.
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
crdldevice
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.
qmadmin
qspacecreate
command. qspacecreatequeue_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.
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.
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.
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.
[Top] [Previous Page] [Next Page] [Bottom]