Fuxedo logotpinit()

join an application

Synopsis

#include <atmi.h>

int tpinit(TPINIT *tpinfo);

Description

tpinit() attaches the process to an application and must succeed before any other ATMI call (tpalloc() and the tperrno family excepted). Passing NULL joins with defaults; a TPINIT structure carries the client name, username, password, application password, and the group name requests are scoped to, plus client identification data when the application requires it.

Arguments

ArgumentDescription
tpinfoNULL for defaults, or a TPINIT with usrname, cltname, passwd, grpname, flags, and the datalen/data identification payload.

Flags

FlagDescription
TPMUTUALAUTH, TPABSOLUTE...Security-related flags from the header; rarely needed with SECURITY NONE.

Errors (tperrno)

CodeDescription
TPEINVALA TPINIT field is inconsistent (version, name lengths, datalen without data).
TPEPERMAuthentication failed.
TPELIMITThe application is full (MAXACCESSERS).
TPESYSTEM, TPEOSPlatform or operating system failure.

Notes

Servers. Server processes do not call tpinit(); the main delivered by buildserver() handles the attach and calls tpsvrinit() instead.

Example

Full source: docs/api/examples/session.c (build and run with make -C docs/api/examples check TUXDIR=<install>); the lines documenting tpinit() are highlighted.

// tpinit()/tpterm() example: explicit session control. A regular
// client can skip both; the first ATMI call joins the application with
// defaults and the detach happens at process exit.

#include <stdio.h>
#include <string.h>
#include <atmi.h>

int main(int argc, char **argv) {
  const char *input = argc > 1 ? argv[1] : "hello";

  // NULL joins with defaults; a TPINIT carries usrname, cltname,
  // passwd, grpname, and identification data for apps that require it
  if (tpinit((TPINIT *)NULL) == -1) {
    // tperrno holds the code of the last failed ATMI call; a
    // successful call does not reset it, so read it right after the
    // failure
    int code = tperrno;
    // tpstrerror renders a tperrno code as text
    fprintf(stderr, "tpinit failed: %s (%d)\n", tpstrerror(code), code);
    return 1;
  }

  char *req = tpalloc("STRING", NULL, strlen(input) + 1);
  char *rsp = tpalloc("STRING", NULL, strlen(input) + 1);
  long rlen = 0;
  int rc = 0;
  if (req == NULL || rsp == NULL) {
    fprintf(stderr, "tpalloc failed: tperrno=%d\n", tperrno);
    rc = 1;
  } else {
    strcpy(req, input);
    if (tpcall("TOUPPER", req, 0, &rsp, &rlen, 0) == -1) {
      fprintf(stderr, "tpcall failed: tperrno=%d\n", tperrno);
      rc = 1;
    } else {
      printf("%s -> %s\n", req, rsp);
    }
  }
  tpfree(req);
  tpfree(rsp);

  tpterm();
  return rc;
}

See also: tpterm, tpcall.

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