Fuxedo logoAPI reference

the Tuxedo C API, tersely

This is the reference for the C API shared by Oracle Tuxedo and Fuxedo: the X/Open XATMI calls (tp*) and the FML32 fielded buffer calls (F*32). It is written for people who already program against the API and want exact flags, error codes, and edge behavior without page-filler.

Every page embeds a complete, compilable program from docs/api/examples, with the documented call highlighted; the whole app builds and runs with make -C docs/api/examples check TUXDIR=<install> against either Tuxedo or Fuxedo.

Conventions:

  • Error tables list the tperrno code and the condition that sets it. Only codes a real call can produce are listed.
  • A successful call does not reset tperrno; the value is meaningful only after -1. This matches Oracle Tuxedo behavior that production code depends on.
  • Where Oracle Tuxedo 12.2 and 22.1 differ, the difference is stated on the function's page; pages without such a note were cross-checked on both and behave the same.
  • Every page carries a compatibility line saying whether fuxedo implements the call and how it was verified.

Known 12.2 vs 22.1 differences

Most of the API behaves identically on Oracle Tuxedo 12.2 and 22.1. The functions below carry pinned behavioral differences; each page spells out what differs. fuxedo defaults to the 12.x behavior.

  • tpexport: Unknown flag bits are rejected with TPEINVAL on 12.2 and accepted on 22.1. TPEX_XDR64LONG only exists in the 22.x headers.
  • tpimport: 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.
  • Fboolco32: The expression language itself differs between 12.2 and 22.1. Adjacent unary operators (!!x, ~~x, - -x) are syntax errors on 22.1 and compile on 12.2. Nested ~ evaluates once on 22.1 ( ~(~1) == -2 ) but as a proper involution on 12.2 ( == 1 ). String escapes: 12.2 decodes \6E-style hex, 22.1 does not. Double-to-string comparisons format with %f on 12.2 ("1.000000") and %g on 22.1 ("1"), so '1.000000' == 1.0 is true on 12.2 and false on 22.1.
  • Fboolev32: On NULL fbfr or tree, 12.2 sets Ferror32 to FNOTFLD while 22.1 leaves it unset or sets FALIGNERR. A missing field in arithmetic counts as 0 on 12.2 (1+missing == 1); 22.1 yields 0 for the whole expression. Expression-language differences are listed on the Fboolco32 page.

    Index

    FunctionWhat it does
    tpinitjoin an application.
    tptermleave an application.
    tperrnothe ATMI error indicator.
    tpstrerrorrender a tperrno code.
    tpcallsynchronous request/response service call.
    tpacallasynchronous service call (send half).
    tpgetrplycollect the reply of an outstanding call.
    tpcancelabandon an outstanding call.
    tpforwardhand the request to another service (server only).
    tpallocallocate a typed buffer.
    tpfreerelease a typed buffer.
    tptypesinspect a typed buffer.
    tpexportrender a typed buffer in portable form.
    tpimportrebuild a typed buffer from its portable form.
    tpbeginstart a transaction.
    tpgetlevare we in transaction mode?.
    tpsuspendstash the current transaction.
    tpresumere-enter a stashed transaction.
    tpcommitcommit the current transaction.
    tpabortroll the current transaction back.
    tpsvrinitserver boot hook.
    tpsvrdoneserver shutdown hook.
    tpsvrthrinitdispatch-thread start hook.
    tpsvrthrdonedispatch-thread exit hook.
    tpreturnfinish a service call (server only).
    tpadvertiseadvertise a service at runtime (server only).
    tpadvertisexadvertise a service with placement flags.
    tpunadvertisewithdraw a service advertisement (server only).
    fml32fielded buffers: the model.
    Ferror32the FML32 error indicator.
    Fstrerror32render an FML32 error code.
    Fadd32append a field occurrence.
    Fchg32change a field occurrence (the Swiss Army knife).
    Fget32read a field occurrence.
    Fdel32delete field occurrences.
    Fnext32iterate over all fields.
    Fprint32print a buffer to stdout.
    Ffprint32print a buffer to a FILE.
    Fwrite32write a buffer to a FILE (binary).
    Fread32read a buffer from a FILE (binary).
    Fboolco32compile a boolean expression.
    Fboolev32evaluate a boolean expression over a buffer.
    Fboolpr32print a parsed boolean expression tree.
    Fmkfldid32build a field id from a type and a number.
    Fneeded32size an addition before making it.
    Fsizeof32current buffer size.
    Flen32stored length of one occurrence.