asynchronous service call (send half)
#include <atmi.h>
int tpacall(char *svc, char *data, long len, long flags);
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).
| Argument | Description |
|---|---|
| svc | Advertised service name; same validation as tpcall(). |
| data, len | Request buffer and length, as for tpcall(). |
| flags | See below. |
| Flag | Description |
|---|---|
| TPNOREPLY | No reply is expected; tpacall() returns 0 on success. Forbidden inside a transaction (TPEPROTO). |
| TPNOTRAN | The call does not join the current transaction. |
| TPNOBLOCK | Fail the send with TPEBLOCK immediately if the service queue is full, instead of waiting for space. |
| TPNOTIME | No timeout while waiting for the queue; the reply wait is governed by the flags handed to tpgetrply(). |
| TPSIGRSTRT | Restart interrupted waits instead of failing with TPGOTSIG. |
| Code | Description |
|---|---|
| TPEINVAL | Bad service name, flags, or arguments. |
| TPENOENT | The service is not advertised. |
| TPEPROTO | TPNOREPLY was requested in transaction mode. |
| TPEBLOCK | TPNOBLOCK was set and the request queue is full. |
| TPELIMIT | No free call descriptors; replies must be collected to release them. |
| TPESYSTEM, TPEOS | Platform or operating system failure. |
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.
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.