|
|
|
|
|
|
Creating Queue Spaces and Queues
This topic covers three of the qmadmin(1) commands that are used to establish the resources of the BEA Tuxedo /Q component. The APPQ_MIB Management Information Base provides an alternative method of administering BEA Tuxedo /Q programmatically. See the APPQ_MIB(5) reference page for more information on the MIB.
Working with qmadmin Commands
Most of the key commands of qmadmin have positional parameters. If the positional parameters (those not specified with a dash (-) preceding the option) are not specified on the command line when the command is invoked, qmadmin prompts you for the required information.
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 the queued message facility is installed as part of a new BEA Tuxedo installation, 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 must be the same pathname specified in TUXCONFIG. Once you have invoked qmadmin, it is recommend that 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. (You can also use the T_APPQSPACE class of the APPQ_MIB(5) to create a queue space.) 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, n [default=n]):
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 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 permanently lost.
The program does not prompt you to specify the size of the area to reserve in shared memory for storing non-persistent messages for all queues in the queue space. When you require non-persistent (memory-based) messages, you must specify the size of the memory area on the qspacecreate command line with the -n option.
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.
To calculate the number of concurrent transactions, count each of the following as one transaction:
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. The worst case is that all clients access the queue space at the same time.
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. (You can also use the T_APPQ class of the APPQ_MIB(5) to create a queue.)
The prompt sequence for qcreate looks like this.
> qcreate
Queue name: service1
Queue order (priority, time, fifo, lifo): fifo
Out-of-ordering enqueuing (top, msgid, [default=none]): none
Retries [default=0]: 2
Retry delay in seconds [default=0]: 30
High limit for queue capacity warning (b for bytes used, B for blocks used,
% for percent used, m for messages [default=100%]): 80%
Reset (low) limit for queue capacity warning [default=0%]: 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.
The program does not prompt you for a default delivery policy and memory threshold options. The default delivery policy option allows you to specify whether messages with no specified delivery mode are delivered to persistent (disk-based) or non-persistent (memory-based) storage. The memory threshold option allows you to specify values used to trigger command execution when a non-persistent memory threshold is reached. To use these options, you must specify them on the qcreate command line with -d and -n, respectively.
Specifying Queue Order
Messages are put into the queue based on the order specified by this parameter and dequeued from the top of the queue unless selection criteria are applied to the dequeuing operation. If priority, expiration, and/or time are chosen as queue order criteria, then messages are inserted into the queue according to values in the TPQCTL structure. A combination of sort criteria may be specified with the most significant criteria specified first. Separate multiple criteria with commas (,). If fifo or lifo (which are mutually exclusive) are specified, they must be the last value specified. The sequence in which parameters are specified 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 specified 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. During this time, the message is unavailable for any dequeuing operation.
The default for the number of retries is 0, which means that no retries are attempted. When the retry limit is reached, the system moves the message to the error queue for the 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 CPU 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 bytes, blocks, messages or percent of queue capacity) and allow you to specify 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 until the low threshold is reached first prior to the high threshold.)
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 [default=100%]): 80%
Reset (low) limit for queue capacity warning [default=0%]: 10%
Queue capacity command: /usr/app/bin/mailme myqueuespace service1
This sequence sets the upper threshold at 80% of disk-based 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 do not get the warning message again unless the queue load drops to 10% of capacity or below, and then rises again to 80%. You can also set thresholds and specify commands for the management of non-persistent (memory-based) queue capacity using the -n option of the qcreate command.
Note: If you are working on an NT machine, see Windows NT Standard I/O for additional information about configuring commands within a qmadmin() session.
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 [default=100%]): 90%
Reset (low) limit for queue capacity warning [default=0%]: 0%
Queue capacity command: tmboot -i 1002
This sequence assumes that you have configured a reserve TMQFORWARD server for the queue in question with SRVID=1002 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 to be processed by a service of the same name. A queue may also be used for other purposes as well, such as peer-to-peer communication. The parameters for creating a queue are the same regardless of its use. The TPQCTL structure used when a message is enqueued to a service queue includes fields to specify a reply queue and a failure queue. TMQFORWARD detects the success or failure of the tpacall(3c) it makes to the requested service and, if these queues have been created by the administrator, enqueues 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 of the outcome.
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. In this case, fifo is probably sufficient. 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, and the recommended usage is to alert the administrator so that he or she can intervene.
Error Queues
An error queue is a system queue. One of the qspacecreate prompts asks for the name of the error queue for the queue space. When you have actually created an error queue of the name specified, 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 handle the messages manually through commands of qmadmin or can set up an automated way of handling them through the APPQ_MIB MIB. The queue capacity parameters can be used, but all of the other qcreate parameters, with the exception of qname, are not useful for the error queue.
Note: We recommend against using the same queue as both an error queue and a service failure queue; doing so makes it more difficult to cleanly manage the application and could lead to clients trying to access the administrator's area.
|
|
|
|
|
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|