finish a service call (server only)
#include <atmi.h>
void tpreturn(int rval, long rcode, char *data, long len, long flags);
tpreturn() ends the current service call and never returns to the
service. With rval TPSUCCESS the data is delivered as the reply; with
TPFAIL the caller sees TPESVCFAIL and rcode arrives in
tpurcode either way. TPEXIT additionally takes the server
down after the reply, which is how a service asks for a restart.
| Argument | Description |
|---|---|
| rval | TPSUCCESS, TPFAIL, or TPEXIT. |
| rcode | Application code; surfaced as tpurcode on the client. |
| data, len | Reply buffer and length; len 0 means the buffer length for self-describing types. |
| flags | 0, or TPSOFTTIMEOUT to mark the reply as a soft timeout result. |
| Flag | Description |
|---|---|
| TPSOFTTIMEOUT | The reply carries a soft-timeout indication (service deadline facilities). |
A service that falls off the end without calling tpreturn() is an
error path; always end services with tpreturn() or
tpforward().
C++. tpreturn() does not return: the service frame
is torn down without running destructors, so RAII guards,
std::strings and locks declared in the service body never
clean up (a frequent source of leaks and deadlocks). Release resources
explicitly before the call, keep short-lived objects in inner scopes
that close earlier, or end the service with C-style cleanup and a
single tpreturn at the bottom.
Full source: docs/api/examples/advsvr.c
(build and run with make -C docs/api/examples check
TUXDIR=<install>); the lines documenting tpreturn() are highlighted.
// Server lifecycle examples: tpsvrinit/tpsvrdone, the per-dispatch
// thread pair, runtime advertising, and tpreturn. Booted without -s
// advertisements; everything is advertised from tpsvrinit().
#include <stdio.h>
#include <string.h>
#include <atmi.h>
#include <userlog.h>
void GREET(TPSVCINFO *svcinfo) {
// tpreturn ends the call: TPSUCCESS delivers data as the reply,
// TPFAIL reports an application failure (tpurcode carries rcode),
// TPEXIT ends the call and takes the server down
tpreturn(TPSUCCESS, 0, svcinfo->data, 0, 0);
}
int tpsvrthrinit(int argc, char **argv) {
// called once per dispatch thread, before it takes requests
return 0;
}
void tpsvrthrdone() {
// called when a dispatch thread exits
}
int tpsvrinit(int argc, char **argv) {
// called once at boot, before the server takes requests: advertise
// the services this server implements. Functions must be declared at
// buildserver time; runtime advertising binds names to them
if (tpadvertise((char *)"GREETX", GREET) == -1) {
return -1;
}
// tpadvertisex (re)binds a name to a function with extended
// placement flags (0 = plain); here it takes over the buildserver
// -s advertisement of GREET
if (tpadvertisex((char *)"GREET", GREET, 0) == -1) {
return -1;
}
return 0;
}
void tpsvrdone() {
// called once at orderly shutdown; withdraw the extra advertisement
tpunadvertise((char *)"GREETX");
userlog("advsvr done");
}
See also: tpforward, tpsvrinit.
fuxedo: supported. Cross-checked against Oracle Tuxedo 12.2.2 and 22.1 with the API hardening suite.