Fuxedo logotpacall()

asynchronous service call (send half)

Synopsis

#include <atmi.h>

int tpacall(char *svc, char *data, long len, long flags);

Description

tpacall() sends a request to a service without waiting for the reply. It returns a call descriptor; the reply is picked up later with tpgetrply() (or abandoned with tpcancel()). With TPNOREPLY no descriptor is returned and no reply is expected.

Argument handling matches tpcall(): self-describing buffers pass len 0, CARRAY passes the byte count, and the buffer may not be touched until the reply has been received (the library reads it at send time; it is copied into the message).

Arguments

ArgumentDescription
svcAdvertised service name; same validation as tpcall().
data, lenRequest buffer and length, as for tpcall().
flagsSee below.

Flags

FlagDescription
TPNOREPLYNo reply is expected; tpacall() returns 0 on success. Forbidden inside a transaction (TPEPROTO).
TPNOTRANThe call does not join the current transaction.
TPNOBLOCKFail the send with TPEBLOCK immediately if the service queue is full, instead of waiting for space.
TPNOTIMENo timeout while waiting for the queue; the reply wait is governed by the flags handed to tpgetrply().
TPSIGRSTRTRestart interrupted waits instead of failing with TPGOTSIG.

Errors (tperrno)

CodeDescription
TPEINVALBad service name, flags, or arguments.
TPENOENTThe service is not advertised.
TPEPROTOTPNOREPLY was requested in transaction mode.
TPEBLOCKTPNOBLOCK was set and the request queue is full.
TPELIMITNo free call descriptors; replies must be collected to release them.
TPESYSTEM, TPEOSPlatform or operating system failure.

Notes

Send behavior on a full queue. Without TPNOBLOCK the send waits for queue space at a one-second retry cadence; payloads that would exceed the kernel per-message limit, and blocking payloads above 500 bytes, spill to a /tmp file while only a small control message waits for space. With TPNOBLOCK the send fails with TPEBLOCK instead, without spilling.

Example

Full source: docs/api/examples/acall.c (build and run with make -C docs/api/examples check TUXDIR=<install>); the lines documenting tpacall() 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: tpcall, tpgetrply, tpcancel.

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