hand the request to another service (server only)
#include <atmi.h>
void tpforward(char *svc, char *data, long len, long flags);
tpforward() is called from a service and hands the current request to another service. It does not return: the forwarding service terminates, and the reply produced by the target service goes to the original caller with the forwarding service's return code semantics cleared. The caller cannot tell the request was forwarded.
The target service name must be advertised; otherwise the caller receives an error reply (TPENOENT) instead of a normal result.
| Argument | Description |
|---|---|
| svc | The service that will produce the reply. |
| data, len | The (possibly rewritten) request. As usual, len 0 means the buffer length for self-describing types. |
| flags | Currently no forward-specific flags; pass 0. |
| Code | Description |
|---|---|
| TPENOENT | svc is not advertised; reported to the caller as an error reply. |
Transactions. A forward keeps the request inside the caller's transaction; the target service joins it like any participant. tpforward, not tpcall, is the right way to chain services within one transactional call.
C++. tpforward() never returns, and the service
frame is discarded without running destructors (the same mechanics as
tpreturn()): objects with non-trivial destructors declared
in the service body leak or stay locked. Free resources before the
forward, or keep the forward as the last statement after plain
C-style cleanup.
Full source: docs/api/examples/apisvr.c
(build and run with make -C docs/api/examples check
TUXDIR=<install>); the lines documenting tpforward() are highlighted.
// Sample server for the API reference examples. TOUPPER does the work;
// FORWARD exists to demonstrate tpforward().
#include <stdio.h>
#include <string.h>
#include <ctype.h>
#include <atmi.h>
void TOUPPER(TPSVCINFO *svcinfo) {
for (char *p = svcinfo->data; *p != '\0'; p++) {
*p = (char)toupper((unsigned char)*p);
}
tpreturn(TPSUCCESS, 0, svcinfo->data, 0, 0);
}
void FORWARD(TPSVCINFO *svcinfo) {
// hand the request to TOUPPER; tpforward does not return
tpforward((char *)"TOUPPER", svcinfo->data, svcinfo->len, 0);
}
fuxedo: supported. Cross-checked against Oracle Tuxedo 12.2.2 and 22.1 with the API hardening suite.