Fuxedo logotpgetrply()

collect the reply of an outstanding call

Synopsis

#include <atmi.h>

int tpgetrply(int *cd, char **data, long *len, long flags);

Description

tpgetrply() waits for the reply of a call started with tpacall(). Without TPGETANY it waits for the descriptor held in *cd; with TPGETANY it returns the first reply that arrives and stores its descriptor in *cd.

*data must point at a buffer allocated with tpalloc(); the library may reallocate it to fit the reply, and *len receives the reply length.

Arguments

ArgumentDescription
cdAddress of the call descriptor. Replaced with the replied descriptor when TPGETANY is set.
data, lenReply buffer pointer and returned length.
flagsSee below.

Flags

FlagDescription
TPGETANYReturn the next reply for any outstanding call.
TPNOBLOCKReturn TPEBLOCK immediately when no reply is ready instead of waiting.
TPNOTIMEWait without a deadline; the reaper never fires for this wait.
TPSIGRSTRTRestart interrupted waits.

Errors (tperrno)

CodeDescription
TPEBADDESC*cd is not an outstanding call descriptor.
TPETIMEThe reply did not arrive within the call timeout. The descriptor stays outstanding and can be waited on again; a reply arriving after the timeout is discarded on a later call.
TPEBLOCKTPNOBLOCK was set and no reply is ready.
TPEINVALdata is NULL or *data is not a typed buffer.
TPGOTSIGA signal interrupted the wait and TPSIGRSTRT was not set.
TPESYSTEM, TPEOSPlatform or operating system failure.

Notes

Scatter/gather. The usual high-throughput shape is a fixed window of tpacall()s with tpgetrply(TPGETANY): whenever a reply arrives, issue the next request so the window stays full.

Example

Full source: docs/api/examples/acall.c (build and run with make -C docs/api/examples check TUXDIR=<install>); the lines documenting tpgetrply() are highlighted.

// tpacall()/tpgetrply() example: the two halves of an asynchronous
// call against the TOUPPER service from apisvr.c.

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

int main(int argc, char **argv) {
  const char *input = 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);

  int cd = tpacall("TOUPPER", req, 0, 0);
  if (cd == -1) {
    fprintf(stderr, "tpacall failed: tperrno=%d\n", tperrno);
    tpfree(req);
    tpfree(rsp);
    return 1;
  }

  if (tpgetrply(&cd, &rsp, &rlen, 0) == -1) {
    fprintf(stderr, "tpgetrply 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, tpcall, tpcancel.

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