![]() |
![]() |
|
|
tpreturn(3c)
Name
tpreturn() - returns from a BEA Tuxedo 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 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 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.
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 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:
A service routine does not return any value to its caller, the BEA Tuxedo 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 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.
See Also
tpalloc(3c), tpcall(3c), tpconnect(3c), tpforward(3c), tprecv(3c), tpsend(3c), tpservice(3c)
![]() |
![]() |
![]() |
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|