allocate a typed buffer
#include <atmi.h>
char *tpalloc(char *type, char *subtype, long size);
tpalloc() allocates a typed buffer. type is one of STRING, CARRAY, FML32, or VIEW32; subtype names the view for VIEW32 and is NULL otherwise. All ATMI calls take tpalloc'd buffers, and every buffer passed across the API must come from tpalloc().
The size meaning depends on the type: bytes for CARRAY (the exact length sent), the maximum string length including the terminator for STRING, the initial fielded-buffer size for FML32 (it grows as needed), and ignored for VIEW32 (the view definition decides).
| Argument | Description |
|---|---|
| type | STRING, CARRAY, FML32, or VIEW32. |
| subtype | View name for VIEW32; NULL otherwise. |
| size | Initial size in the type's units; 0 where the definition decides. |
| Code | Description |
|---|---|
| TPEINVAL | Unknown type or subtype. |
| TPESYSTEM, TPEOS | Platform or operating system failure, including allocation failure. |
Full source: docs/api/examples/buffers.c
(build and run with make -C docs/api/examples check
TUXDIR=<install>); the lines documenting tpalloc() are highlighted.
// tpalloc()/tptypes()/tpfree() example: typed buffer lifecycle.
#include <stdio.h>
#include <string.h>
#include <atmi.h>
int main(void) {
char *buf = tpalloc("STRING", NULL, 64);
if (buf == NULL) {
fprintf(stderr, "tpalloc failed: tperrno=%d\n", tperrno);
return 1;
}
char type[8] = {0};
char subtype[16] = {0};
long len = tptypes(buf, type, subtype);
if (len == -1) {
fprintf(stderr, "tptypes failed: tperrno=%d\n", tperrno);
tpfree(buf);
return 1;
}
printf("type=%s subtype=%s len=%ld\n", type, subtype, len);
strcpy(buf, "hello");
// tpexport renders a typed buffer into a portable form that
// tpimport rebuilds
char exported[256];
long elen = sizeof(exported);
if (tpexport(buf, 0, exported, &elen, 0) == -1) {
fprintf(stderr, "tpexport failed: tperrno=%d\n", tperrno);
tpfree(buf);
return 1;
}
// tpimport rebuilds the buffer; *obuf points at the target buffer
// and *olen carries its size (22.x grows the buffer when the data
// does not fit)
char *back = tpalloc("STRING", NULL, 128);
long blen = 128;
if (back == NULL || tpimport(exported, elen, &back, &blen, 0) == -1) {
fprintf(stderr, "tpimport failed: tperrno=%d\n", tperrno);
tpfree(buf);
tpfree(back);
return 1;
}
printf("roundtrip: %s\n", back);
tpfree(back);
tpfree(buf);
return 0;
}
See also: tpfree, tptypes, Fchg32.
fuxedo: supported. Cross-checked against Oracle Tuxedo 12.2.2 and 22.1 with the API hardening suite.