Fuxedo logotpalloc()

allocate a typed buffer

Synopsis

#include <atmi.h>

char *tpalloc(char *type, char *subtype, long size);

Description

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).

Arguments

ArgumentDescription
typeSTRING, CARRAY, FML32, or VIEW32.
subtypeView name for VIEW32; NULL otherwise.
sizeInitial size in the type's units; 0 where the definition decides.

Errors (tperrno)

CodeDescription
TPEINVALUnknown type or subtype.
TPESYSTEM, TPEOSPlatform or operating system failure, including allocation failure.

Example

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.