synchronous request/response service call
#include <atmi.h>
int tpcall(char *svc, char *idata, long ilen,
char **odata, long *olen, long flags);
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.
| Argument | Description |
|---|---|
| svc | Name of the advertised service. Empty or NULL names fail with TPEINVAL; a name longer than the service name limit fails as well. |
| idata, ilen | Request 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, olen | Address of the reply buffer pointer and reply length. The buffer must come from tpalloc(); it is freed and replaced if the library resizes it. |
| flags | See below. |
| Flag | Description |
|---|---|
| TPNOTRAN | The call does not join the current transaction, even if one is active. |
| TPNOCHANGE | Force the reply buffer type and subtype to match the request; otherwise a type mismatch fails with TPEOTYPE. |
| TPBLOCK | Default. If the service request queue is full, wait for space. |
| TPNOTIME | Ignore the call timeout while waiting for the reply; wait indefinitely. |
| TPSIGRSTRT | Restart 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.
| Code | Description |
|---|---|
| TPEINVAL | svc is NULL or empty, flags are invalid, or the arguments are inconsistent (for example a NULL idata with a nonzero ilen). |
| TPENOENT | No server advertises svc in this application. With no application attached at all, the platform may answer TPEPROTO, TPELIMIT, or TPESYSTEM instead. |
| TPETIME | The reply did not arrive within the call timeout. |
| TPESVCFAIL | The service ran and returned TPFAIL; the reply data is still returned and tpurcode carries the service's code. |
| TPESVCERR | The service terminated without returning (for example the server process died mid-call). |
| TPEOTYPE | Reply type differs from the request type while TPNOCHANGE is set. |
| TPETRAN | The call runs under a transaction routed to a server group that has no transaction manager; retry with TPNOTRAN. |
| TPGOTSIG | A signal interrupted the wait and TPSIGRSTRT was not set. |
| TPEOS, TPESYSTEM | Operating system or platform internal failure. |
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).
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.