Section 3c - C Functions

ATMI C Function Reference

tpforward(3c)

Name

tpforward()—Routine for forwarding a service request to another service routine.

Synopsis

#include <atmi.h>
void tpforward(char *svc, char *data, long len, long flags)

Description

tpforward() allows a service routine to forward a client's request to another service routine for further processing. tpforward() acts like tpreturn() in that it is the last call made in a service routine. Like tpreturn(), tpforward() should be called from within the service routine dispatched to ensure correct return of control to the BEA Tuxedo ATMI system dispatcher. tpforward() cannot be called from within a conversational service.

This function forwards a request to the service named by svc using data pointed to by data. The service name must not begin with a dot. A service routine forwarding a request receives no reply. After the request is forwarded, the service routine returns to the communication manager dispatcher and the server is free to do other work. Note that because no reply is expected from a forwarded request, the request may be forwarded without error to any service routine in the same executable as the service that forwarded the request.

If the service routine is in transaction mode, tpforward() puts the caller's portion of the transaction in a state where it may be completed when the originator of the transaction issues either tpcommit() or tpabort(). If a transaction was explicitly started with tpbegin() while in a service routine, the transaction must be ended with either tpcommit() or tpabort() before calling tpforward(). Thus, all services in a "forward chain" are either all started in transaction mode or none are.

The last server in a forward chain sends a reply back to the originator of the request using tpreturn(). In essence, tpforward() transfers to another server the responsibility of sending a reply back to the awaiting requester.

tpforward() should be called after receiving all replies expected from service requests initiated by the service routine. Any outstanding replies which are not received will automatically be dropped by the communication manager dispatcher upon receipt. In addition, the descriptors for those replies become invalid and the request is not forwarded to svc.

data points to the data portion of a reply to be sent. If data is non-NULL, it must point to a buffer previously obtained by a call to tpalloc(). If this is the same buffer passed to the service routine upon its invocation, then its disposition is up to the BEA Tuxedo ATMI system dispatcher; the service routine writer does not have to worry about whether it is freed or not. In fact, any attempt by the user to free this buffer will fail. However, if the buffer passed to tpforward() is not the same one with which the service is invoked, then tpforward() will free that buffer. len specifies the amount of the data buffer to be sent. If data points to a buffer which does not require a length to be specified, (for example, an FML fielded buffer), then len is ignored (and can be 0). If data is NULL, then len is ignored and a request with zero length data is sent.

The flags argument is reserved for future use and should be set to 0 (zero) for Tuxedo 9.1 rolling patches earlier than RP073. For RP073 and later rolling patches, the flags argument can be set to 0 (zero) or TPENOBLOCK.

When 0 (zero) is specified and a blocking condition exists, the call is blocked until the condition subsides or a timeout occurs (for example, a transaction or blocking timeout). When TPENOBLOCK is specified and a blocking condition exists, the call is returned immediately with TPESVCERR.

Return Values

A service routine does not return any value to its caller, the communication manager dispatcher. Thus, tpforward() is declared as a void. See tpreturn(3c) for a more extensive discussion.

Errors

If any errors occur either in the handling of the parameters passed to the function or in its processing, a "failed" message is sent back to the original requester (unless no reply is to be sent). The existence of outstanding replies or subordinate connections, or the caller's transaction being marked abort-only, qualify as failures which generate failed messages.

If either SVCTIMEOUT in the UBBCONFIG file or TA_SVCTIMEOUT in the TM_MIB is non-zero, the event, TPEV_SVCERR is returned when a service timeout occurs.

Failed messages are detected by the requester with the TPESVCERR error indication. When such an error occurs, the caller's data is not sent. Also, this error causes the caller's current transaction to be marked abort-only.

If a transaction timeout occurs, either during the service routine or while the request is being forwarded, the requester waiting for a reply with either tpcall() or tpgetrply() will get a TPETIME error return. When a service fails inside a transaction, the transaction times out and is put into the TX_ROLLBACK_ONLY state. All further ATMI calls for that transaction will fail with TPETIME. The waiting requester will not receive any data. Service routines, however, are expected to terminate using either tpreturn() or tpforward(). A conversational service routine must use tpreturn(); it cannot use tpforward().

If a service routine returns without using either tpreturn() or tpforward() (that is, if it uses the C language return statement or simply "falls out of the function") or if tpforward() is called from a conversational server, the server will print a warning message in a log file and return a service error to the original requester. All open connections to subordinates will be disconnected immediately, and any outstanding asynchronous replies will be marked stale. If the server was in transaction mode at the time of failure, the transaction is marked abort-only. Note also that if either tpreturn() or tpforward() are used outside of a service routine (for example, in clients, or in tpsvrinit() or tpsvrdone()), then these routines simply return having no effect.