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 umpteen 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

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

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

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