Fuxedo logotpimport()

rebuild a typed buffer from its portable form

Synopsis

#include <atmi.h>

int tpimport(char *istr, long ilen,
             char **obuf, long *olen, long flags);

Description

tpimport() rebuilds a buffer stored by tpexport(). *obuf addresses the target buffer pointer and *olen its size on entry; on return the buffer pointer and the rebuilt length are updated. When the target is too small, 22.x grows it with tprealloc and updates *obuf, so the caller should always use the returned pointer and release it with tpfree().

Arguments

ArgumentDescription
istr, ilenThe exported form and its length.
obuf, olenAddress of the target buffer pointer; *olen carries the buffer size on entry.
flags0, or TPEX_STRING when the source uses the text form.

Flags

FlagDescription
TPEX_STRINGRead the text form.

Errors (tperrno)

CodeDescription
TPEINVALBad input, sizes, or flags.
TPEOS, TPESYSTEMPlatform failure, including malformed input (22.x reports TPESYSTEM).

12.2 vs 22.1

Four pinned differences. A NULL *obuf fails with TPEINVAL on 12.2; 22.x allocates the buffer (free it with tpfree). Malformed input reports TPEPROTO on 12.2 and TPESYSTEM on 22.x. An undersized target is grown via tprealloc on 22.x, while 12.2 fails or, with a binary FML export, writes past the buffer; size the target generously on 12.2. Unknown flag bits are rejected on 12.2 and accepted on 22.x. fuxedo follows the 22.x behavior throughout.

Example

Full source: docs/api/examples/buffers.c (build and run with make -C docs/api/examples check TUXDIR=<install>); the lines documenting tpimport() 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: tpexport, tpalloc.

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