Fuxedo logotpcall()

synchronous request/response service call

Synopsis

#include <atmi.h>

int tpcall(char *svc, char *idata, long ilen,
           char **odata, long *olen, long flags);

Description

tpcall() sends the request buffer idata to the service named by svc and waits for the reply. It is exactly tpacall() followed by tpgetrply() on the returned call descriptor, so argument handling, flags, and errors are the ones documented for those calls.

On return, *odata points to the reply buffer and *olen holds the reply length. The caller allocates *odata with tpalloc(); the library may reallocate it in place, so keep only the returned pointer.

If the service finishes with tpreturn(TPFAIL, code, ...), tpcall() returns -1 with tperrno set to TPESVCFAIL, the reply data is delivered in *odata as usual, and code is available in tpurcode.

Arguments

ArgumentDescription
svcName of the advertised service. Empty or NULL names fail with TPEINVAL; a name longer than the service name limit fails as well.
idata, ilenRequest buffer and length. For self-describing types (STRING, FML32, VIEW32) pass the buffer with ilen 0; for CARRAY pass the exact byte count. NULL idata with ilen 0 sends an empty request.
odata, olenAddress of the reply buffer pointer and reply length. The buffer must come from tpalloc(); it is freed and replaced if the library resizes it.
flagsSee below.

Flags

FlagDescription
TPNOTRANThe call does not join the current transaction, even if one is active.
TPNOCHANGEForce the reply buffer type and subtype to match the request; otherwise a type mismatch fails with TPEOTYPE.
TPBLOCKDefault. If the service request queue is full, wait for space.
TPNOTIMEIgnore the call timeout while waiting for the reply; wait indefinitely.
TPSIGRSTRTRestart an interrupted wait instead of returning TPGOTSIG when a caught signal arrives mid-call.

Any other flag, including TPNOREPLY, fails with TPEINVAL; use tpacall() for those.

Errors (tperrno)

CodeDescription
TPEINVALsvc is NULL or empty, flags are invalid, or the arguments are inconsistent (for example a NULL idata with a nonzero ilen).
TPENOENTNo server advertises svc in this application. With no application attached at all, the platform may answer TPEPROTO, TPELIMIT, or TPESYSTEM instead.
TPETIMEThe reply did not arrive within the call timeout.
TPESVCFAILThe service ran and returned TPFAIL; the reply data is still returned and tpurcode carries the service's code.
TPESVCERRThe service terminated without returning (for example the server process died mid-call).
TPEOTYPEReply type differs from the request type while TPNOCHANGE is set.
TPETRANThe call runs under a transaction routed to a server group that has no transaction manager; retry with TPNOTRAN.
TPGOTSIGA signal interrupted the wait and TPSIGRSTRT was not set.
TPEOS, TPESYSTEMOperating system or platform internal failure.

Notes

tperrno. A successful call does not reset tperrno. Read it only when the return value is -1; this matches Oracle Tuxedo, where applications routinely rely on the value surviving successful calls.

Timeout. A late reply that arrives after TPETIME is discarded by the client library on a later call; a warning may land in the application log (ULOG).

Example

Full source: docs/api/examples/tpcall.c (build and run with make -C docs/api/examples check TUXDIR=<install>); the whole program demonstrates tpcall().

// tpcall() example: a synchronous request/response call. With one
// argument it calls TOUPPER; with two, the first is the service name
// (used to exercise the FORWARD service from apisvr.c).

#include <stdio.h>
#include <string.h>
#include <atmi.h>

int main(int argc, char **argv) {
  const char *svc = argc > 2 ? argv[1] : "TOUPPER";
  const char *input = argc > 2 ? argv[2] : (argc > 1 ? argv[1] : "hello");
  char *req = tpalloc("STRING", NULL, strlen(input) + 1);
  char *rsp = tpalloc("STRING", NULL, strlen(input) + 1);
  long rlen = 0;
  if (req == NULL || rsp == NULL) {
    fprintf(stderr, "tpalloc failed: tperrno=%d\n", tperrno);
    tpfree(req);
    tpfree(rsp);
    return 1;
  }
  strcpy(req, input);
  if (tpcall((char *)svc, req, 0, &rsp, &rlen, 0) == -1) {
    fprintf(stderr, "tpcall failed: tperrno=%d\n", tperrno);
    tpfree(req);
    tpfree(rsp);
    return 1;
  }
  printf("%s -> %s\n", req, rsp);
  tpfree(req);
  tpfree(rsp);
  return 0;
}

See also: tpacall, tpgetrply, tpbegin, Fchg32.

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