Section 3c - C Functions

ATMI C Function Reference

tpreturn(3c)

Name

tpreturn()—Returns from a BEA Tuxedo ATMI system service routine.

Synopsis

void tpreturn(int rval, long rcode, char *data, long len, long \flags)

Description

tpreturn() indicates that a service routine has completed. tpreturn() acts like a return statement in the C language (that is, when tpreturn() is called, the service routine returns to the BEA Tuxedo ATMI system dispatcher). It is recommended that tpreturn() be called from within the service routine dispatched to ensure correct return of control to the BEA Tuxedo ATMI system dispatcher.

tpreturn() is used to send a service's reply message. If the program receiving the reply is waiting in either tpcall(), tpgetrply(), or tprecv(), then after a successful call to tpreturn(), the reply is available in the receiver's buffer.

For conversational services, tpreturn() also tears down the connection. That is, the service routine cannot call tpdiscon() directly. To ensure correct results, the program that connected to the conversational service should not call tpdiscon(); rather, it should wait for notification that the conversational service has completed (that is, it should wait for one of the events, like TPEV_SVCSUCC or TPEV_SVCFAIL, sent by tpreturn()).

If the service routine was in transaction mode, tpreturn() places the service's portion of the transaction in a state from which it may be either committed or rolled back when the transaction is completed. A service may be invoked multiple times as part of the same transaction so it is not necessarily fully committed or rolled back until either tpcommit() or tpabort() is called by the originator of the transaction.

tpreturn() should be called after receiving all replies expected from service requests initiated by the service routine. Otherwise, depending on the nature of the service, either a TPESVCERR status or a TPEV_SVCERR event will be returned to the program that initiated communication with the service routine. Any outstanding replies that are not received will automatically be dropped by the communication manager. In addition, the descriptors for those replies become invalid.

tpreturn() should be called after closing all connections initiated by the service. Otherwise, depending on the nature of the service, either a TPESVCERR or a TPEV_SVCERR event will be returned to the program that initiated communication with the service routine. Also, an immediate disconnect event (that is, TPEV_DISCONIMM) is sent over all open connections to subordinates.

Since a conversational service has only one open connection which it did not initiate, the communication manager knows over which descriptor data (and any event) should be sent. For this reason, a descriptor is not passed to tpreturn().

The following is a description of the arguments for tpreturn(). rval can be set to one of the following:

TPSUCCESS

The service has terminated successfully. If data is present, then it will be sent (barring any failures processing the return). If the caller is in transaction mode, then tpreturn() places the caller's portion of the transaction in a state such that it can be committed when the transaction ultimately commits. Note that a call to tpreturn() does not necessarily finalize an entire transaction. Also, even though the caller indicates success, if there are any outstanding replies or open connections, if any work done within the service caused its transaction to be marked rollback-only, then a failed message is sent (that is, the recipient of the reply receives a TPESVCERR indication or a TPEV_SVCERR event). Note that if a transaction becomes rollback-only while in the service routine for any reason, then rval should be set to TPFAIL. If TPSUCCESS is specified for a conversational service, a TPEV_SVCSUCC event is generated.

TPFAIL

The service has terminated unsuccessfully from an application standpoint. An error will be reported to the program receiving the reply. That is, the call to get the reply will fail and the recipient receives a TPSVCFAIL indication or a TPEV_SVCFAIL event. If the caller is in transaction mode, then tpreturn() marks the transaction as rollback-only (note that the transaction may already be marked rollback-only). Barring any failures in processing the return, the caller's data is sent, if present. One reason for not sending the caller's data is that a transaction timeout has occurred. In this case, the program waiting for the reply will receive an error of TPETIME. If TPFAIL is specified for a conversational service, a TPEV_SVCFAIL event is generated.

TPEXIT

This value behaves the same as TPFAIL with respect to completing the service, but when TPEXIT is returned, the server exits after the transaction is rolled back and the reply is sent back to the requester.

When specified for a multithreaded process, TPEXIT indicates that an entire process (not only a single thread within that process) will be killed.

If the server is restartable, then the server is restarted automatically.

If rval is not set to one of these three values, then it defaults to TPFAIL.

An application defined return code, rcode, may be sent to the program receiving the service reply. This code is sent regardless of the setting of rval as long as a reply can be successfully sent (that is, as long as the receiving call returns success or TPESVCFAIL). In addition, for conversational services, this code can be sent only if the service routine has control of the connection when it issues tpreturn(). The value of rcode is available in the receiver in the variable, tpurcode().

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 tpreturn() is not the same one with which the service is invoked, then tpreturn() frees that buffer. Although the main buffer is freed, any buffers referenced by embedded fields within that buffer are not freed. 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. In this case, if a reply is expected by the program that invoked the service, then a reply is sent with no data. If no reply is expected, then tpreturn() frees data as necessary and returns sending no reply.

Currently, flags is reserved for future use and must be set to 0 (if set to a non-zero value, the recipient of the reply receives a TPESVCERR indication or a TPEV_SVCERR event).

If the service is conversational, there are two cases where the caller's return code and the data portion are not transmitted:

If the connection has already been torn down when the call is made (that is, the caller has received TPEV_DISCONIMM on the connection), then this call simply ends the service routine and rolls back the current transaction, if one exists.
If the caller does not have control of the connection, either TPEV_SVCFAIL or TPEV_SVCERR is sent to the originator of the connection as described above. Regardless of which event the originator receives, no data is transmitted; however, if the originator receives the TPEV_SVCFAIL event, the return code is available in the originator's tpurcode() variable.

Return Values

A service routine does not return any value to its caller, the BEA Tuxedo ATMI system dispatcher; thus, it is declared as a void. Service routines, however, are expected to terminate using either tpreturn() or tpforward(). A conversational service routine must use tpreturn(), and cannot use tpforward(). If a service routine returns without using either tpreturn() or tpforward() (that is, it uses the C language return statement or just simply "falls out of the function") or tpforward() is called from a conversational server, the server will print a warning message in the log and return a service error to the service requester. In addition, all open connections to subordinates will be disconnected immediately, and any outstanding asynchronous replies will be dropped. If the server was in transaction mode at the time of failure, the transaction is marked rollback-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.

Errors

Since tpreturn() ends the service routine, any errors encountered either in handling arguments or in processing cannot be indicated to the function's caller. Such errors cause tperrno to be set to TPESVCERR for a program receiving the service's outcome via either tpcall() or tpgetrply(), and cause the event, TPEV_SVCERR, to be sent over the conversation to a program using tpsend() or tprecv().

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.

tperrordetail() and tpstrerrordetail() can be used to get additional information about an error produced by the last BEA Tuxedo ATMI system routine called in the current thread. If an error occurred, tperrordetail() returns a numeric value that can be used as an argument to trstrerrordetail() to retrieve the text of the error detail.