2. BEA TUXEDO System /Q Administration

Introduction

The BEA TUXEDO System/Q administrator has three primary areas of responsibility that are discussed in the three main sections of this chapter:

Configuration of resources
Creation of the queue space and queues
Monitoring and maintenance of the facility

Close cooperation with the application developers and programmers is a must; the configuration and the queue attributes must reflect the requirements of the application.

Sample Program in Appendix A

A brief example of the use of the queued message facility is distributed with the software and is described in Appendix A, "A Sample Application."

Configuration

Three servers are provided with the BEA TUXEDO System/Q. One is the TMS server, TMS_QM, that is the transaction manager server for the BEA TUXEDO System/Q resource manager. That is, it manages global transactions for the queued message facility. It must be 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.

The application can also create its own queue servers, if the functionality of TMQFORWARD does not fully meet the needs of the application. For example, the administrator might want to have a special server to dequeue messages moved to the error queue.

Specifying the QM Server Group

There must be a server group defined for each queue space the application will use. In addition to the standard requirements of a group name tag and a value for GRPNO (see ubbconfig(5) for details). The TMSNAME and OPENINFO parameters need to be set. Here are examples:

TMSNAME=TMS_QM

and

OPENINFO="TUXEDO/QM:<device_name:<queue_space_name>"

TMS_QM is the name for the transaction manager server for TUXEDO System/Q. 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 pathname for the universal device list and the name associated with the queue space, respectively. These values are specified by the BEA TUXEDO administrator using qmadmin(1).

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 created before the facility can be used.

There can be only one queue space per GROUPS section entry. The CLOSEINFO parameter is not used.

The following example is taken from the manual page for TMQUEUE(5).

*GROUPS
TMQUEUEGRP1 GRPNO=1 TMSNAME=TMS_QM
        OPENINFO="TUXEDO/QM:/dev/device1:myqueuespace"
TMQUEUEGRP2 GRPNO=2 TMSNAME=TMS_QM
        OPENINFO="TUXEDO/QM:/dev/device2:myqueuespace"

# The following two specifications are equivalent:
 
*SERVERS
TMQUEUE SRVGRP="TMQUEUEGRP1" SRVID=1000 RESTART=Y GRACE=0 \
        CLOPT="-s myqueuespace:TMQUEUE"
and
 
buildserver -o TMQUEUE -s myqueuespace:TMQUEUE -r TUXEDO/QM \
        -f ${TUXDIR}/lib/TMQUEUE.o
followed by
 ..
 ..
 ..
TMQUEUE SRVGRP="TMQUEUEGRP1" SRVID=1000 RESTART=Y GRACE=0 \
        CLOPT="-A"

Data-Dependent Routing

The section above described the specification of services (that is, queue space names) in the message queue server. This capability can be used to bring about data-dependent routing of queued messages such that the message is queued for processing by a service within a specific group depending on a value in a field of the message buffer. To do this the same queue space name is specified in two different groups and a routing specification is made part of the configuration file to govern the group where the message is queued. Here is an example taken from the TMQUEUE(5) manual page (the queue space name has been changed):

*GROUPS
TMQUEUEGRP1 GRPNO=1 TMSNAME=TMS_QM
        OPENINFO="TUXEDO/QM:/dev/device1:myqueuespace"
TMQUEUEGRP2 GRPNO=2 TMSNAME=TMS_QM
        OPENINFO="TUXEDO/QM:/dev/device2:myqueuespace"
*SERVERS
TMQUEUE SRVGRP="TMQUEUEGRP1" SRVID=1000 RESTART=Y GRACE=0 \
        CLOPT="-s ACCOUNTING:TMQUEUE"
TMQUEUE SRVGRP="TMQUEUEGRP2" SRVID=1000 RESTART=Y GRACE=0 \
        CLOPT="-s ACCOUNTING:TMQUEUE"
*SERVICES
ACCOUNTING  ROUTING="MYROUTING"
*ROUTING
MYROUTING  FIELD=ACCOUNT BUFTYPE="FML" \
        RANGES="MIN-60000:TMQUEUEGRP1,60001-MAX:TMQUEUEGRP2"

Customized Buffer Types

TMQUEUE supports all of the standard BEA TUXEDO buffer types. If your application needs to add other types, it can be done by copying $TUXDIR/tuxedo/tuxlib/types/tmsypesw.c, adding an entry for your special buffer types, making sure to leave the final line null, and using the revised file as input to a buildserver(1) command. An example of the buildserver command is shown on the TMQUEUE(5) reference page.

You can also use the -s option of the buildserver command to associate additional service names with TMQUEUE as an alternative to specifying them in the server CLOPT parameter (see above).

Specifying the Message Forwarding Server

The third system-supplied server included with the BEA TUXEDO System/Q is TMQFORWARD(5). This is the server that takes messages from specified queues, passes them along to BEA TUXEDO servers via tpcall(3c), and handles associated reply messages. The full description of how the server is defined in the configuration file can be found on the manual page, but the sections that follow bring out some points that are worth additional emphasis.

TMQFORWARD is referred to as a server and each instance used by an application must be defined in the SERVERS section of the configuration file, but it has characteristics that set it apart from ordinary servers. For example:

It is wrong to specify services for TMQFORWARD.
A client process cannot post a message for TMQFORWARD as you would expect in a normal request/response relationship.
TMQFORWARD should not be defined as a member of an MSSQ set.
TMQFORWARD should never have a reply queue.

An instance of TMQFORWARD is tied to a queue space through the server group with which it is associated, specifically through the third field in the OPENINFO statement for the group. In the sections that follow we will examine other key parameters, especially CLOPT parameters that come after the double dash.

Queue Names and Service Names: the -q option

A required parameter is -q queuename,queuename. . . This parameter specifies the queue(s) to be checked by this instance of the server. queuename is a NULL-terminated string of up to 15 characters; it is the same as the name of the application service that will process the message once it has been taken off the queue by TMQFORWARD. It is also the name that a programmer specifies as the second argument of tpenqueue(3c) or tpdequeue(3c) when preparing to call the message queue server, TMQUEUE.

Controlling Transaction Timeout: the -t option

TMQFORWARD does its work within a transaction that it begins and ends. The -t trantime option is available to specify the length of time in seconds before the transaction is timed out. The transaction is begun when TMQFORWARD finds a message on the queue it is checking; it is committed after a reply has been enqueued either to the reply queue or the failure queue, so the transaction encompasses calling the service that processes the message and receiving a reply. The default is 60 seconds.

Controlling Idle Time: the -i option

Once TMQFORWARD is booted it constantly checks the queue to which it is assigned. If it finds the queue empty, it pauses for -i idletime seconds before checking again. If a value is not specified, the default is 30 seconds; a value of 0 says to keep checking the queue constantly, which can be wasteful if the queue is frequently empty.

Controlling Server Exit: the -e option

If the -e option is specified, the server will shut itself down gracefully (sending a message to the userlog) when it finds the queue empty. This behavior may be used to your advantage in connection with the threshold command that you can specify for a queue. There is a more complete discussion of this in the section on qmadmin(1).

Delete Message after Service Failure: the -d option

When a service request fails after being called by TMQFORWARD the transaction is rolled back and the message is put back on the queue for a later retry (up to a limit of retries specified for the queue). The -d option adds the following refinement: if the failed service returns a non-NULL reply, the reply (and its associated tpurcode) are put on a failure queue (if one is associated with the message and the queue exists) and the original request is deleted. The rationale behind this option is that rather than blindly retrying, the originating client can be coded to examine the failure message and determine whether further attempts are reasonable. It provides a way of handling a failure that is due to some inherently reasonable condition (for example, a record is not found because the account does not exist).

Customized Buffer Types

Customized application buffer types can be added to the type switch and incorporated into TMQFORWARD with the buildserver(1) command. It should be noted, however, that when you customize TMQFORWARD it is an error to specify service names with a -s option.

Dynamic Configuration

We have described configuration parameters in terms of UBBCONFIG parameters. However, it should be noted that the specifications in the GROUPS and SERVERS sections can also be added to the TUXCONFIG file of a running application by using tmconfig(1). Of course, the group and the servers will have to be booted once they have been defined.

Creating Queue Space and Queues

This section covers three of the qmadmin(1) commands that are used to establish the resources of the BEA TUXEDO System/Q facility.

Working with qmadmin Commands

Several of the key commands of qmadmin have positional parameters; we refer to qspacecreate, qcreate, qspacechange, and crdl. The program prompts for values for parameters, so it probably makes life easier to just enter the command and let the program take over.

Creating an Entry in the Universal Device List: crdl

The universal device list (UDL) is a VTOC file under the control of the BEA TUXEDO system. It maps the physical storage space on a machine where the BEA TUXEDO system is run. An entry in the UDL points to the disk space where the queues and messages of a queue space are stored; the BEA TUXEDO system manages the input and output for that space. If you have an existing BEA TUXEDO application, you are probably already familiar with the UDL and how it is created. If the creation of the queued message facility is part of a new BEA TUXEDO installation, then be informed that the UDL is created by tmloadcf(1) when the configuration file is first loaded.

Before you create a queue space, you must create an entry for it in the UDL. Here is an example of the commands:

# First invoke the /Q administrative interface, qmadmin
# The QMCONFIG variable points to an existing device where the UDL
# either resides or will reside.
QMCONFIG=/dev/rawfs qmadmin
# Next create the device list entry
crdl /dev/rawfs 50 500
# The above command sets aside 500 physical pages beginning at block 50
# If the UDL has no previous entries, offset (block number) 0 must be used

If you are going to add an entry to an existing BEA TUXEDO UDL, the value for the QMCONFIG variable will be the same pathname specified in TUXCONFIG. Once you have invoked qmadmin, we recommend you run a lidl command to see where space is available before creating your new entry.

Creating a Queue Space: qspacecreate

A queue space makes use of IPC resources; when you define a queue space you are allocating a shared memory segment and a semaphore. As noted above, the easiest way to use the command is to let it prompt you. The sequence looks like this:

> qspacecreate
Queue space name: myqueuespace
IPC Key for queue space: 230458
Size of queue space in disk pages: 200
Number of queues in queue space: 3
Number of concurrent transactions in queue space: 3
Number of concurrent processes in queue space: 3
Number of messages in queue space: 12
Error queue name: errq
Initialize extents (y or n - default no):
Blocking factor (default 16): 16

The program insists that you provide values for all prompts except the final three. As you can see, there are defaults for the last two; while you will almost certainly want to name an error queue, you are not required to. If you provide a name here, you still must create the error queue with the qcreate command. If you choose not to name an error queue, bear in mind that messages that normally would be moved to the error queue (for example, when a retry limit is reached), are dropped.

The value for the IPC key should be picked so as not to conflict with your other requirements for IPC resources. It should be a value greater than 32,768 and less than 262,143.

The size of the queue space, the number of queues, and the number of messages that can be queued at one time all depend on the needs of your application. Of course, you cannot specify a size greater than the number of pages specified in your UDL entry. In connection with these parameters, you also need to look ahead to the queue capacity parameters for an individual queue within the queue space. Those parameters allow you to (a) set a limit on the number of messages that can be put on a queue, and (b) name a command to be executed when the number of enqueued messages on the queue reaches the threshold. If you specify a low number of concurrent messages for the queue space, you may create a situation where your threshold on a queue will never be reached.

For the number of concurrent transactions count one for each TMS_QM server in the group that uses this queue space, one for each TMQUEUE or TMQFORWARD server in the group that uses this queue space and one for qmadmin. If your client programs begin transactions before they call tpenqueue, increase the count by the number of clients that might access the queue space concurrently; worst case is all of them.

For the number of concurrent processes count one for each TMS_QM, TMQUEUE or TMQFORWARD server in the group that uses this queue space and one for a fudge factor.

You can choose to initialize the queue space as you use the qspacecreate command, or you can let it be done by the qopen command when you first open the queue space.

Creating a Queue: qcreate

Each queue that you intend to use must be created with the qmadmin qcreate command. You first have to open the queue space with the qopen command. If you do not provide a queue space name, qopen will prompt for it.

The prompt sequence for qcreate looks like this:

> qcreate
Queue name: service1
Queue order (fifo, lifo, priority, time): fifo
Out-of-ordering enqueuing (none, top, msgid): none
Retries: 2
Retry delay in seconds: 30
High limit for queue capacity warning (b for bytes used,
B for blocks used, % for percent used, m for messages): 80%
Reset (low) limit for queue capacity warning: 0%
Queue capacity command:
No default queue capacity command
Queue 'service1' created

You can skip all of these prompts (except the prompt for the queue name); if you do not provide a name for the queue, the program displays a warning message and prompts again. For the other parameters the program provides a default and displays a message that specifies the default.

Specifying Queue Order

Messages are enqueued in the order specified by this parameter and dequeued from the top of the queue. The queue order parameter defines how the application wants queue order to be determined. If priority and/or time are chosen, messages are inserted into the queue according to values in the TPQCTL structure or, in the case of priority, to the value set by the /Q administrator. If specified, fifo or lifo (which are mutually exclusive), must be the last parameter selected. The sequence in which parameters are selected determines the sort criteria for the queue. In other words, a specification of priority, fifo would say that the queue should be arranged by message priority and that within messages of equal priority they should be dequeued on a first in, first out basis.

Enabling Out-of-order Enqueuing

If the administrator enables out-of-order enqueues; that is, if top and/or msgid are selected at the prompt, programmers can specify (via values in the TPQCTL structure of a tpenqueue call) that a message is to be put at the top of the queue or ahead of the message identified by msgid. Give this option some thought; once the choice is made you have to destroy and recreate the queue to change it.

Specifying Retry Parameters

Normal behavior for a queued message facility is to put a message back on the queue if the transaction that dequeues it is rolled back. It will be dequeued again when it reaches the top of the queue. You can specify the number of retries that should be attempted and also a time delay between retries. Note that when a dequeued message is put back on the queue for retry, queue order specifications are, in effect, suspended for Retry delay seconds.

The default for the number of retries is 0, which means that no retries are attempted. When the retry limit is reached (zero or whatever), the system moves the message to the error queue for this queue space, assuming an error queue has been named and created. If the error queue does not exist the message is discarded.

The delay time is expressed in seconds. When message queues are lightly populated so that a message restored to the queue reaches the top almost immediately, you can save cycles by building in a delay factor. Your general policy on retries should be based on the experience of your particular application. If you have a fair amount of contention for the service associated with a given queue, you may get a lot of transient problems. One way to deal with them is to specify a large number of retries. (The number is strictly subjective, as is the time between retries.) If the nature of your application is such that any rolled back transaction signals a failure that is never going to go away, you might want to specify 0 retries and move the message immediately to the error queue. (This is very much like what happens when you specify the -d option for TMQFORWARD; the only difference is that a non-zero length failure message must be received for TMQFORWARD automatically to drop the message from the queue.)

Using Queue Capacity Limits

There are three parameters of the qcreate command that can be used to partially automate the management of a queue. The parameters set a high and low threshold figure (it can be expressed as blocks, messages or per cent of queue capacity) and allow you to name a command that is executed when the high threshold is reached. (Actually, the command is executed once when the high threshold is reached, but not again unless the low threshold is reached first.)

Here are two examples of ways the parameters can be used:

High limit for queue capacity warning (b for bytes used,
B for blocks used, % for percent used, m for messages): 80%
Reset (low) limit for queue capacity warning: 10%
Queue capacity command: /usr/app/bin/mailme myqueuespace service1

This sequence sets the upper threshold at 80% of queue capacity and specifies a command to be executed when the queue is 80% full. The command is a script you have created that sends you a mail message when the threshold is reached (myqueuespace and service1 are hypothetical arguments to your command). Presumably, once you have been informed that the queue is filling up you can take action to ease the situation. You will not get the warning message again unless the queue load drops to 10% of capacity or below, and then rises again to 80%.

The second example is somewhat more automated and takes advantage of the -e option of the TMQFORWARD server.

High limit for queue capacity warning (b for bytes used,
B for blocks used, % for percent used, m for messages): 90%
Reset (low) limit for queue capacity warning: 0%
Queue capacity command: tmboot -i 1002

This sequence assumes that you have configured a reserve TMQFORWARD server for the queue in question with a SRVID=1002 number and have included the -e option in its CLOPT parameter. (It also assumes that the server is not booted or, if booted, has shut itself down as a result of finding the queue empty.) When the queue reaches 90% capacity the tmboot command is executed to boot the reserve server. The -e option causes the server to shut itself down when the queue is empty. You have set the low threshold to 0% so as not to kick off unnecessary tmboot commands for a server that is already booted.

The default values for the three options are 100%, 0%, and no command.

Reply and Failure Queues

The discussion above about creating a queue and providing parameters for its operation was written from the viewpoint of creating a queue for messages waiting to be processed by a service of the same name, although the parameters for creating a queue are the same regardless of its use. Other queues are possible and indeed highly useful. Included in the TPQCTL structure when a message is enqueued to a service queue are fields that can name a reply queue and a failure queue. TMQFORWARD detects the success or failure of the tpcall(3c) it makes to the requested service and, if these queues have been created by the administrator, queues the reply accordingly. If no reply or failure queue exists, the success or failure response message from the service is dropped leaving the originating client with no information about the outcome of the queued request. Even if there is no reply message from the service, if a reply queue exists, a zero-length message is enqueued there by TMQFORWARD to inform the originating client.

When creating a reply or a failure queue, bear in mind that in most cases messages are dequeued from these queues by a client process looking for information about an earlier enqueued request. Since the most common way of dequeuing such messages is by the msgid (message identifier) or corrid (correlation identifier) associated with the message-as opposed to taking a message off the top of the queue-the queue ordering criteria are less significant; you might just as well settle for fifo. However, the out-of-order parameter must be configured to permit access by msgid. The retries and retry delay parameters have no significance for reply queues; just take the defaults. The queue capacity thresholds and commands are likely to be useful on reply queues, but we recommend using them to alert the administrator so that he or she can intervene.

Error Queues

An error queue is a system queue. If you remember, one of the prompts when you use qspacecreate asks for the name of the error queue for this queue space. When you have actually created an error queue of that name, the system uses it as a place to move messages from the service queue that have reached their retry limit. The management of the error queue is up to the administrator who can either deal with the messages manually through commands of qmadmin or can set up an automated way of handling them. The queue capacity parameters can be used, but all of the other qcreate parameters, with the exception of qname, do not apply.

Note: We recommend against using the same queue as both an error queue and a service failure queue; doing so would make it more difficult to manage cleanly and could lead to clients trying to access the administrator's area.

Maintenance of the BEA TUXEDO System/Q Feature

This section covers some things the queue administrator may have to do from time to time to keep a queue space operating efficiently.

Adding Extents to a Queue Space

If you find you need more disk storage for a queue space, you can add it with the qaddext command of qmadmin(1). The command takes the queue space name and a number of pages as arguments. The pages come from extents defined in the UDL for the device in your QMCONFIG variable. The queue space must be inactive; you can use the exclamation point to execute a command outside of qmadmin to shut down the associated server group. For example:

> !tmshutdown -g TMQUEUEGRP1

followed by

> qclose
> qaddext myqueue 100

The queue space must be closed; qmadmin will close it for you if you try to add extents to an open queue space.

Backing Up or Moving Queue Space

A convenient command to use to back up a queue space is the UNIX command dd. Shut down the associated server group first. The command lines would look like this:

tmshutdown -g TMQUEUEGRP1
dd if=<qspace_device_file> of=<output_device_filename>

For other options, see dd(1) in a UNIX system reference manual.

This same command can be used to migrate the queue space to a machine of the same architecture, although you may need to start the command sequence with a qmadmin chdl command to provide a new device name if the present name does not exist on the target machine.

Moving the Queue Space to a Different Type of Machine

If you need to move a queue space to a machine with a different architecture (primarily byte order), the procedure is more complex. Create and run an application program to dequeue all messages from all queues in the queue space and write them out in machine-independent format. Then enqueue the messages in the new queue space.

TMQFORWARD and Non-Global Transactions

Messages dequeued and forwarded using TMQFORWARD are executed within a global transaction because the operation crosses group boundaries. If the messages are executed by servers that are not associated with an RM or that do not run within a global transaction, they should have a server group with TMSNAME=TMS (for the NULL XA interface).

TMQFORWARD and Commit Control

The global transaction begun by TMQFORWARD when it dequeues a message for execution is terminated by a tpcommit(). The administrator can set the CMTRET parameter in the configuration file to control whether the transaction commits when it is logged or when it is complete. (See the discussion of CMTRET in the RESOURCES section of the ubbconfig(5) reference page.)

Handling Transaction Timeout

Handling transaction timeout requires cooperation between the queue administrator and the programmer developing client programs that dequeue messages. When tpdequeue(3c) is called with the flags argument set to TPQWAIT, the TMQUEUE server may be blocked waiting for a message to come onto a queue. The number of seconds before it times out is up to:

The timeout flag in the tpdequeue call (if the transaction is started in the client)
The -t number flag of the TMQUEUE server (if the client has not started the transaction)

To get around blocking operations using the TMQUEUE server it might help to configure two TMQUEUE servers (or MSSQ sets of multiple TMQUEUE servers) that offer different service names for the same queue space. tpenqueue and non-waiting tpdequeue operations can go to one set of servers; waiting tpdequeue operations, to a second set.

TMQFORWARD and Retries for an Unavailable Service

When a TMQFORWARD server attempts to forward messages to a service that is not available the situation can develop where the retry limit for the queue may be reached. The message is then moved to the error queue (if one exists). To avoid this situation the administrator should either shut the TMQFORWARD server down or set the retry count higher.

When a message is moved to the error queue it is no longer associated with the original queue. If errors are going to be dealt with by the administrator moving the message back to the service queue when the service is known to be available, then the queue name should be stored as part of the corrid in the TPQCTL structure so the queue name is associated with the message.

[Top] [Prev] [Next] [Bottom]

2. BEA TUXEDO System /Q Administration

Specifying the Message Queue Server

Data-Dependent Routing

Customized Buffer Types