The Oracle Tuxedo /Q component enables messages to be queued for processing or retrieval after they have been stored on persistent disk or non-persistent memory. The Oracle Tuxedo Application-to-Transaction Monitor Interface (ATMI) provides functions that enable messages to be added to or read from queues. A reply message and an error message can be queued for later retrieval by the client program. The administrative command interpreter enables the creation, listing, and modification of servers. Message queue servers accept requests to enqueue and dequeue messages, forward messages from the queue for processing, and manage transactions that involve queues.

The following figure illustrates the components of the queued message facility.

Figure 1-1 Queued Service Invocation

The figure illustrates how each component of the queuing system operates during the invocation of queued services. This discussion utilizes the figure to illustrate how administrators and programmers interact with Oracle Tuxedo /Q. A queued message is queued for processing and a reply is returned to the sender. You can also use the queuing service for peer-to-peer communication by integrating a subset of the components illustrated in the figure. A queue space is a resource. Access to the resource is provided by an X/OPEN XA-compliant resource manager interface. A two-phase committed transaction involving this interface enables enqueuing and dequeuing to be performed in coordination with other XA-compliant resource managers.

The Oracle Tuxedo administrator is responsible for defining servers and creating queue spaces and queues like those shown between the vertical dashed lines in the figure Queued Service Invocation. 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 must be defined in the configuration file. These servers perform the following functions:

• The message queue server,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 a message-forwarding server that dequeues and forwards messages to application servers. Oracle Tuxedo provides the main() function for servers, which handles initialization and termination of the server, allocates buffers to receive and dispatch incoming requests, and routes replies appropriately. All of this processing is transparent to the application. Existing servers do not dequeue their messages or enqueue replies. Oracle Tuxedo /Q is designed to enable existing servers to serve queued messages without requiring any modification. The TMQFORWARD server dequeues a message from one or more queues in the queue space, forwards the message to a server with a service that is named the same as the queue, waits for the reply, and queues the successful reply or failure reply on the associated reply or failure queues, respectively, as specified by the originator of the message (if the originator specified a reply or failure queue).

The administrator must also create a queue space by using either the queue administration program, qmadmin(1), or the APPQ_MIB(5) Management Information Base (MIB). The queue space contains a collection of queues. In the figure Queued Service Invocation, for example, the APP queue space contains four queues. Each queue space corresponds to a single resource manager (RM), and a group can only have one RM.

The notion of queue space enables reducing the administrative overhead associated with a queue by sharing the overhead among a collection of queues in the following ways:

• The queues in a queue space share persistent and non-persistent storage areas for messages.
• A single message queue server, TMQUEUE in the figure Queued Service Invocation, can be used to enqueue and dequeue messages for multiple queues within a single queue space.
• A single message forwarding server, TMQFORWARD in the figure Queued Service Invocation, can be used to dequeue and forward messages to services from multiple queues within a single queue space.
• In the figure Queued Service Invocation, two instances of the transaction manager server, TMS_QM, are shown. This enables transactions to be completed across multiple queues within the same queue space. The first transaction manager server instance is reserved for non-blocking transactions in order to ensure that they are processed as quickly as possible without being slowed down by blocking transactions. The second instance of the transaction manager server is responsible for handling blocking transactions.

The administrator can define a single server group in the application configuration for the queue space by specifying the group in UBBCONFIG or by using tmconfig(1) to add the group dynamically.

• Finally, when the administrator moves messages between queues within a queue space, the overhead is less than if the messages were in different stable storage areas, because a one-phase commit can be done.

Part of the task of defining a queue is specifying the order for messages on the queue. Queue ordering can be determined by message availability time, expiration time, priority, FIFO, LIFO, or a combination of these criteria.

The administrator specifies one or more of these sort criteria for the queue, listing the most significant criteria first. The FIFO and LIFO values must be 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 required to keep up with the requests generated by clients for the stable queues.

A data-dependent routing approach can enable routing between servers in multiple groups 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. This 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 might boot a TMQFORWARD server to drain the queue or send mail to the administrator for manual handling.

The Oracle Tuxedo system uses the Queuing Services component of the Oracle Tuxedo infrastructure for some operations. (The Oracle Tuxedo infrastructure provides services such as security, scalability, message queuing, and transactions.) For example, administrative operations for shared memory are provided by the Queuing Services component. Some functions are not currently applicable to Oracle Tuxedo applications; this is noted in descriptions of these functions.

You can also use the queued message facility for peer-to-peer communication between clients, such that a client communicates with other clients without using any forwarding server. The peer-to-peer communication model is depicted in the following figure.

Figure 1-2 Peer-to-Peer Communication

Following the instructions in steps 1 to 3 of the figure Queued Service Invocation, a client enqueues a message to the SERVICE1 queue in the APP queue space using tpenqueue(3c). An optional reply queue and failure queue can also be specified in the call to tpenqueue (). The example illustrates the queues CLIENT_REPLY1 and FAILURE_Q. The client can specify a correlation identifier value to accompany the message. The value is persistent across queues so that it can be used to identify any reply or failure messages associated with a queued message. It is read from the reply or failure queue during this process.

There are two types of queue ordering available to the client: standard queue ordering (for example, a time after which a message should be available for dequeuing), or override the default queue ordering (requesting, for example, that this message be placed at the top or ahead of another message)).tpenqueue() sends the message to the TMQUEUE server, queues the message, and sends an acknowledgment (step 3) to the client; the acknowledgment is not visible to the client, however it can be assumed when the client receives a successful response. (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. In addition to this, tpenqueue() can also be used to identify a message already enqueued ahead of a subsequent message.

The transaction in which a message is enqueued must be successfully completed before the message can be dequeued.

When using Oracle Tuxedo /Q for queued service invocation, and the message reaches the top of the queue, the TMQFORWARD server dequeues the message and forwards it, through tpcall(3c), to a service with the same name as the queue name. In the figure Queued Service Invocation, the queue and the service are named SERVICE1, and steps 4, 5, and 6 in the figure show this. The client identifier and application authentication key are provided to the client responsible for enqueuing the message and accompanying 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 the figure Queued Service Invocation).

Later (steps 8, 9 and 10 in the figure Queued Service Invocation), the client uses tpdequeue(3c) to retrieve the reply message from the reply queue CLIENT_REPLY1.

You can dequeue messages without removing them from the queue, by using the TPQPEEK flag with tpdequeue(). A message that has expired or has been deleted by an administrator is immediately removed from the queue.

• Transaction Management
  
• Handling Reply Messages
  
• Error Handling
  
• Summary