Programmer Tasks


	BEA Home \| Events \| Solutions \| Partners \| Products \| Services \| Download \| Developer Center \| WebSUPPORT
	http://www.oracle.com/technology/documentation/index.html \| Site Map \| Search \| PDF Files \| Contact \| Glossary

Tuxedo Documentation \| Using the BEA Tuxedo System /Q Component \| Local Topics \| Previous Topic \| Next Topic \| Contents

Programmer Tasks

In steps 1 through 3 of the figure Queued Service Invocation, a client enqueues a message to the SERVICE1 queue in the APP queue space using tpenqueue(3c). Optionally, the name of a reply queue and a failure queue can be included in the call to tpenqueue(). In the example they are the queues CLIENT_REPLY1 and FAILURE_Q. The client can specify a correlation identifier value to accompany the message. This value is persistent across queues so that any reply or failure message associated with the queued message can be identified when it is read from the reply or failure queue.

The client can use the default queue ordering (for example, a time after which the message should be made available for dequeuing), or can specify an override of the default queue ordering (asking, for example, that this message be put at the top of the queue or ahead of another message on the queue). tpenqueue() sends the message to the TMQUEUE server, the message is queued, and an acknowledgment (step 3) is sent to the client; the acknowledgment is not seen directly by the client but can be assumed when the client gets a successful return. (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. It can also be used in another tpenqueue() to identify a message already on the queue that the subsequent message should be enqueued ahead of.

Before an enqueued message is made available for dequeuing, the transaction in which the message is enqueued must be committed successfully.

When using BEA Tuxedo /Q for queued service invocation, and the message reaches the top of the queue, the TMQFORWARD server dequeues the message and forwards it, via 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 the application authentication key are set to the client that caused the message to be enqueued; they accompany 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).

Sometime later (steps 8, 9 and 10 in the figure Queued Service Invocation), the client uses tpdequeue(3c) to read from the reply queue CLIENT_REPLY1 in order to get the reply message.

You can dequeue messages without removing them from the queue by using the TPQPEEK flag with tpdequeue(). Messages that have expired or have been deleted by an administrator are immediately removed from the queue.

Transaction Management

With regard to transaction management, one goal is to ensure reliability by enqueuing and dequeuing messages within global transactions. However, a conflicting goal is to reduce the execution overhead by minimizing the number of transactions that are involved.

An option is provided for the caller to enqueue a message outside any transaction in which the caller is involved (decoupling the queuing from the caller's transaction). However, a timeout in this situation leaves it unknown as to whether or not the message is enqueued.

A better approach is to enqueue the message within the caller's transaction, as is shown in the following figure.

Transaction Demarcation

In the figure, the client starts a transaction, queues the message and commits the transaction. The message is dequeued within a second transaction started by TMQFORWARD; the service is called with tpcall(3c), is executed and the reply is enqueued within the same transaction. A third transaction, started by the client, is used to dequeue the reply (and possibly enqueue another request message). In ongoing processing, the third and first transactions can meld into one since enqueuing the next request can be done in the same transaction as dequeuing the response from the previous request.

Note: The system allows you to dequeue a response from one message and enqueue the next request within the same transaction, but does not allow you to enqueue a request and dequeue the response within the same transaction. The transaction in which the request is enqueued must be successfully committed before the message is available for dequeuing.

Handling Reply Messages

A reply queue can be either specified or not by the application when calling tpenqueue(). The effect is as follows:

If a reply queue is not specified for a queued message, then no further work is required beyond processing the message.
If a message is dequeued that does specify a reply queue, then the originator of the message expects a reply to be enqueued upon successful completion of the execution of the request.
- In the case where the application explicitly dequeues the message using tpdequeue(), it is the responsibility of the application to call tpenqueue() to enqueue the reply. Normally, this would be done in the same transaction in which the request message is dequeued and executed so the entire operation is handled atomically (that is, the reply is enqueued only if the transaction succeeds).
- In the case where the message is automatically processed by a service (dequeued and passed to the application via a tpcall()) by TMQFORWARD, TMQFORWARD enqueues a reply if the application service returns successfully (that is, the service routine called tpreturn(3c) with TPSUCCESS and tpcall() did not return 1). If tpcall() receives data, then the typed buffer used is enqueued to the reply queue. If no data is received in tpcall(), then a message with no data (that is, a NULL message) is enqueued; the fact that a message is enqueued (even if NULL) is sufficient to signify that the operation has been completed.

Error Handling

Handling of errors requires both an understanding of the nature of the errors the application may encounter and careful planning and coordination between the BEA Tuxedo administrator and the application program developers. The way BEA Tuxedo /Q works, if a message is dequeued within a transaction and the transaction is rolled back, then (if the retry parameter is greater than 0) the message ends up back on the queue where it can be dequeued and executed again.

For a transient problem, it may be desirable to delay for a short period before retrying to dequeue and execute the message, allowing the transient problem to clear. For example, if there is a lot of activity against the application database, there may be occasions when all you need is a little time to allow locks in a database to be released by another transaction. Normally, a limit on the number of retries is also useful to ensure that some application flaw doesn't cause significant waste of resources. When a queue is configured by the administrator, both a retry count and a delay period (in seconds) can be specified. A retry count of 0 implies that no retries are done. After the retry count is reached, the message is moved to an error queue that can be configured by the administrator for the queue space.

There are cases where the problem is not transient. For example, the queued message may request operations on an account that does not exist. In this case, it is desirable not to waste any resources by trying again. If the application programmer or administrator determines that failures for a particular operation are never transient, then it is simply a matter of setting the retry count to zero. It is more likely the case that for the same service some problems will be transient and some problems will be permanent; the administrator and application developers need to have more than a single approach to handle errors.

Other variations come about because the application may either dequeue messages directly or use the TMQFORWARD server and because an error may cause a transaction to be rolled back and the message requeued while logic dictates that the transaction should be committed. These variations and ways to deal with them are discussed in BEA Tuxedo /Q Administration, BEA Tuxedo /Q C Language Programming, and BEA Tuxedo /Q COBOL Language Programming.

Summary

To summarize, BEA Tuxedo /Q provides the following features to BEA Tuxedo application programmers and administrators:

An application programming interface that lets you enqueue a request for subsequent processing. The system guarantees to execute the request successfully exactly once (by default, failure causes the message to be put back on the queue). An application programming interface is also provided to dequeue messages either from the top of a queue or by message identifier or correlation identifier.
The application program and/or the administrator can control the ordering of messages on the queue. Control is via the sort criteria, which may be based on message availability time, expiration time, priority, LIFO, FIFO, or a combination of these criteria. The application can override the ordering to place the message at the queue top or ahead of a specific message that is already queued.
A BEA Tuxedo server is provided to enqueue and dequeue messages on behalf of, possibly remote, clients and servers. The administrator decides how many copies of the server should be configured.
A BEA Tuxedo server is provided to dequeue queued messages and forward them to services for execution. This server allows for existing servers to handle queued requests without modification. Each forwarding server can be configured to handle one or more queues. Transactions are used to guarantee exactly-once processing. The administrator controls how many forwarding servers are configured.
The administrator can control messages stored on the queues for processing. This includes the number of times requests are retried on failure and how much time elapses between retries, reordering messages on queues, managing queue capacity and so on.

There are many application paradigms in which queued messages can be used. This feature can be used to queue requests when a machine, server, or resource is unavailable or unreliable (for example, in the case of a wide area or wireless networks). This feature can also be used for work flow provisioning where each step generates a queued request to do the next step in the process. Yet another use is for batch processing of potentially long running transactions, such that the initiator does not have to wait for completion but is assured that the message will eventually be processed. This facility may also be used to provide a data pipe between two otherwise unrelated applications in a peer-to-peer relationship.