start a transaction
#include <atmi.h>
int tpbegin(unsigned long timeout, long flags);
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.
| Argument | Description |
|---|---|
| timeout | Seconds before the transaction is rolled back; 0 means the platform default. |
| flags | 0; TPNOBLOCK/TPNOTIME/TPSIGRSTRT govern internal waits. |
| Flag | Description |
|---|---|
| TPNOBLOCK, TPNOTIME, TPSIGRSTRT | Wait disposition for internal operations. |
| Code | Description |
|---|---|
| TPEINVAL | Invalid timeout or flags. |
| TPEPROTO | The caller is already in transaction mode. |
| TPESYSTEM, TPEOS | Platform failure. |
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.
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.