Fuxedo logotpforward()

hand the request to another service (server only)

Synopsis

#include <atmi.h>

void tpforward(char *svc, char *data, long len, long flags);

Description

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.

Arguments

ArgumentDescription
svcThe service that will produce the reply.
data, lenThe (possibly rewritten) request. As usual, len 0 means the buffer length for self-describing types.
flagsCurrently no forward-specific flags; pass 0.

Errors (tperrno)

CodeDescription
TPENOENTsvc is not advertised; reported to the caller as an error reply.

Notes

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.

Example

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);
}

See also: tpcall, tpreturn.

fuxedo: supported. Cross-checked against Oracle Tuxedo 12.2.2 and 22.1 with the API hardening suite.