Fuxedo logotpbegin()

start a transaction

Synopsis

#include <atmi.h>

int tpbegin(unsigned long timeout, long flags);

Description

tpbegin() puts the caller in transaction mode. Calls made while in transaction mode join the transaction (unless TPNOTRAN opts them out), and the transaction ends with tpcommit() or tpabort(). timeout is the limit in seconds; 0 selects the platform default. A transaction with no resource managers commits trivially, which is why demarcation can be exercised without a database.

Arguments

ArgumentDescription
timeoutSeconds before the transaction is rolled back; 0 means the platform default.
flags0; TPNOBLOCK/TPNOTIME/TPSIGRSTRT govern internal waits.

Flags

FlagDescription
TPNOBLOCK, TPNOTIME, TPSIGRSTRTWait disposition for internal operations.

Errors (tperrno)

CodeDescription
TPEINVALInvalid timeout or flags.
TPEPROTOThe caller is already in transaction mode.
TPESYSTEM, TPEOSPlatform failure.

Notes

Return value. Returns 1 on success, -1 on error, on the platform and in fuxedo. Check == -1, not truthiness: if (tpbegin(...)) treats a successful begin as failure.

Example

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

// Transaction demarcation examples: tpbegin/tpgetlev/tpsuspend/
// tpresume/tpcommit/tpabort in a client. No resource manager is
// involved, so the transaction has no participants and the commit is
// trivial on any platform.

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

static int fail(const char *what) {
  fprintf(stderr, "%s failed: %s (%d)\n", what, tpstrerror(tperrno),
          tperrno);
  return 1;
}

int main(void) {
  // tpbegin starts a transaction; the argument is the timeout in
  // seconds (0 selects the platform default)
  if (tpbegin(30, 0) == -1) {
    return fail("tpbegin");
  }

  // tpgetlev answers whether the caller is in transaction mode:
  // TP_IN_TRANSACTION or TP_NOT_IN_TRANSACTION
  int lev = tpgetlev();
  printf("after begin: %d\n", lev);

  // tpsuspend stashes the transaction in a TPTRANID so the thread can
  // leave transaction mode (another thread resumes it, or the same
  // thread resumes it later)
  TPTRANID tranid;
  if (tpsuspend(&tranid, 0) == -1) {
    return fail("tpsuspend");
  }
  printf("after suspend: %d\n", tpgetlev());

  // tpresume re-enters the stashed transaction
  if (tpresume(&tranid, 0) == -1) {
    return fail("tpresume");
  }
  printf("after resume: %d\n", tpgetlev());

  // tpcommit ends the transaction with a commit; without participants
  // this is trivial, with resource managers it runs two-phase commit
  if (tpcommit(0) == -1) {
    return fail("tpcommit");
  }
  printf("after commit: %d\n", tpgetlev());

  if (tpbegin(30, 0) == -1) {
    return fail("tpbegin");
  }
  // tpabort rolls the transaction back
  if (tpabort(0) == -1) {
    return fail("tpabort");
  }
  printf("after abort: %d\n", tpgetlev());
  return 0;
}

See also: tpcommit, tpabort, tpgetlev.

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