In addition to the standard requirements of a group name tag and a value for GRPNO, there must be a server group defined for each queue space the application will use. 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 Oracle Tuxedo /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 Oracle Tuxedo administrator using qmadmin(1).

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

The following example is taken from the reference 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 TMQUEUE(5) reference page gives a full description of the SERVERS section of the configuration file, but there are some points worth additional emphasis here.

• Operation Timeout
  

There is potential confusion among queue space names, queue names, and service names. The first place you are apt to encounter the confusion is in the specification of the message queue server: TMQUEUE. When specifying this server in the configuration file you can use the -s flag of the CLOPT parameter to name the queue space served by a given instance of the server, which is the same as saying it is a service advertised by the function: TMQUEUE. In an application that uses only one queue space, it is not necessary to specify the CLOPT -s option; it will default to -s TMQUEUE:TMQUEUE. If the application requires more than a single queue space, the names of the queue spaces are included as arguments to the -s option in the SERVERS section entry for the queued message server.

An alternative way of making this specification is to rebuild the message queue server, using buildserver(1), and name the queue spaces with the similar sounding -s option. This has the result of fixing, or hardcoding, the service names in the server executable.

# 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
  
• Customized Buffer Types
  
• Buffer Subtypes
  

The third system-supplied server included with the Oracle Tuxedo /Q component is TMQFORWARD(5). This is the server that takes messages from specified queues, passes them along to Oracle Tuxedo servers through 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 TMQFORWARD(5) reference page, but the topics 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 incorrect 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 topics 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
  
• Controlling Transaction Timeout: The -t option
  
• Controlling Idle Time: The -i option
  
• Controlling Server Exit: The -e option
  
• Delete Message After Service Failure: The -d option
  
• Customized Buffer Types
  

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.

The universal device list (UDL) is a VTOC file under the control of the Oracle Tuxedo system. It maps the physical storage space on a machine where the Oracle 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 Oracle Tuxedo system manages the input and output for that space. If the queued message facility is installed as part of a new Oracle 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. The following 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 Oracle 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.

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:

• Each TMS_QM server in the group that uses this queue space
• Each TMQUEUE or TMQFORWARD server in the group that uses this queue space
• 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. 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.

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 the following:

         > 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, s% 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
  
• Enabling Out-of-Order Enqueuing
  
• Specifying Retry Parameters
  
• Using Queue Capacity Limits
  
• Reply and Failure Queues
  
• Error Queues
  

If you find you need more disk storage for a queue space, you can add it with the qaddext command of qmadmin(1). (You can also use the TA_MAXPAGES attribute of the T_APPQSPACE class of APPQ_MIB(5) to add extents.) The qmadmin 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 

> qclose 

> qaddext myqueue 100

The queue space must be closed; qmadmin closes it for you if you try to add extents to it while it is open. All non-persistent messages currently in the queue space are lost when the qaddext command is issued and completes successfully.

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

Similar archival techniques are available on server platforms that do not have the dd command. First, shut down the group containing the queue space you want to back up or migrate. Then, use an archival tool to save the queue space device to a file or other medium that may then be used as a backup or used to move the queue space to another server.

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.

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

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 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 include TPQWAIT, the TMQUEUE server will wait for a message to arrive on a queue before returning to the caller. The number of seconds before it times out is based on the following:

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

If a message is not immediately available when using TPQWAIT, TMQUEUE requires an action resource so that TMQUEUE may service other requests. You may want to increase the number of actions the queue space may handle concurrently. Use the -A actions option to the qspacecreate or qspacechange commands. This option specifies the number of additional actions that can be handled concurrently. When a waiting operation is encountered and additional actions are available, the blocking operation is set aside until it can be satisfied. If no actions are available, the call to tpdequeue fails.

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 handled by the administrator moving the message back to the service queue when the service is known to be available, then the queue name may be stored as part of the corrid in the TPQCTL structure so the queue name is associated with the message.