The transaction processing mechanisms using the Tamino API for C as described in this document allow a transaction to relate to a single database only. They provide the same functionality as the X-Machine commands, see Requests using X-Machine Commands for more details.
This document describes the following functions and commands:
We distinguish two modes:
A session context identified by the predefined constant
TAC_SESSION. This mode is initiated by
tac_connect() and
terminated by tac_disconnect().
A single command context. This could be a command issued in a
non-session context (sometimes called autocommit mode), but it can also refer
to a single command issued in a session. This single command context is
identified by the predefined constant TAC_COMMAND.
Each context has its own set of transaction parameters. These can be set via the functions:
tac_set_isolation_level()
tac_set_lock_mode()
tac_set_lockwait()
tac_set_nonactivity_timeout()
tac_set_transaction_timeout()
Each of these functions takes as its first parameter a valid handle,
and as its second parameter either the keyword
TAC_SESSION or the keyword
TAC_COMMAND. The appropriate Tamino default parameter
will be used if TAC_DEFAULT is specified as the third
argument of any of these functions.
If mode TAC_SESSION is used, the newly-set
values will be used in the next tac_connect() call,
and also in the first request after a tac_commit() or
tac_rollback() call i.e. at the beginning of the next
transaction.
If the keyword TAC_COMMAND is used to set a
value to a non-default value, these transaction parameters will be submitted
along with each subsequent request. A call to
tac_connect() is an exception: the values set via the
TAC_SESSION keyword will be transmitted.
The current value of the transaction parameters can be obtained by
calling tac_get_transaction_parameters() with the
following arguments:
a valid handle;
either the keyword TAC_COMMAND or the keyword
TAC_SESSION;
a pointer to a structure that contains the five parameter fields.
int tac_commit(TAC_HANDLE
handle)
Commits a transaction within a Tamino session and starts a new transaction.
handle - a valid handle obtained
from tac_init().
The predefined constant TAC_SUCCESS upon
success, or an error code upon failure (see Return and Error
Codes).
int tac_connect(TAC_HANDLE
handle)
Starts a Tamino session and switches from autocommit mode to local mode. The Tamino session ID and session key are handled automatically as well.
handle - a valid handle obtained
from tac_init().
The predefined constant TAC_SUCCESS upon
success, or an error code upon failure (see Return and Error
Codes).
int tac_disconnect(TAC_HANDLE
handle)
Closes a Tamino session and switches back from local mode to autocommit mode.
handle - a valid handle obtained
from tac_init().
The predefined constant TAC_SUCCESS upon
success, or an error code upon failure (see Return and Error
Codes).
int tac_get_transaction_parameters(TAC_HANDLE
handle, int mode,
TAC_TRANSACTION_T *trans)
Gets the current values for the transaction parameters used in Tamino requests.
handle - a valid handle obtained
from tac_init().
mode - either
TAC_SESSION or TAC_COMMAND For
more information, see Transaction
Parameter Handling.
trans - a pointer to the predefined
structure TAC_TRANSACTION_T containing the five current
transaction parameters for the specified mode.
The predefined constant TAC_SUCCESS upon
success, or a negative value upon failure.
int tac_rollback(TAC_HANDLE
handle)
Discards all changes made during the current transaction within a Tamino session.
handle - a valid handle obtained
from tac_init().
The predefined constant TAC_SUCCESS
upon success, or an error code upon failure (see Return and Error
Codes).
int tac_set_isolation_level(TAC_HANDLE
handle, int mode, int
isolation_level)
Sets the isolationLevel parameter for Tamino
requests.
handle - a valid handle obtained
from tac_init().
mode - either
TAC_SESSION or TAC_COMMAND For
more information, see Transaction
Parameter Handling.
isolation_level - one of the
predefined constants TAC_DEFAULT,
TAC_ISOLATIONLEVEL_NONE,
TAC_ISOLATIONLEVEL_UNCOMMITTED,
TAC_ISOLATIONLEVEL_COMMITTED,
TAC_ISOLATIONLEVEL_CURSOR,
TAC_ISOLATIONLEVEL_DOCUMENT or
TAC_ISOLATIONLEVEL_SERIALIZABLE.
The predefined constant TAC_SUCCESS upon
success, or a negative value upon failure.
int tac_set_lock_mode(TAC_HANDLE
handle, int mode, int
lock_mode)
Sets the lockMode parameter for Tamino
requests.
handle - a valid handle obtained
from tac_init().
mode - either
TAC_SESSION or TAC_COMMAND. For
more information, see Transaction
Parameter Handling.
lock_mode - one of the predefined
constants TAC_DEFAULT,
TAC_LOCKMODE_SHARED,
TAC_LOCKMODE_PROTECTED or
TAC_LOCKMODE_UNPROTECTED.
The predefined constant TAC_SUCCESS
upon success, or a negative value upon failure.
int tac_set_lockwait(TAC_HANDLE
handle, int mode, int
lockwait)
Sets the lockwait parameter for Tamino
requests.
handle - a valid handle obtained
from tac_init().
mode - either
TAC_SESSION or TAC_COMMAND. For
more information, see Transaction
Parameter Handling.
lockwait - one of the predefined
constants TAC_DEFAULT,
TAC_LOCKWAIT_YES or
TAC_LOCKWAIT_NO.
The predefined constant TAC_SUCCESS upon
success, or a negative value upon failure.
int tac_set_nonactivity_timeout(TAC_HANDLE
handle, int mode, int
timeout)
Sets the nonactivityTimeout parameter for Tamino
requests.
handle - a valid handle obtained
from tac_init().
mode - either
TAC_SESSION or TAC_COMMAND. For
more information, see Transaction
Parameter Handling.
timeout - the desired non-activity
timeout in seconds. The predefined constant TAC_DEFAULT,
which is set to zero, can also be used.
The predefined constant TAC_SUCCESS upon
success, or a negative value upon failure.
int tac_set_transaction_timeout(TAC_HANDLE
handle, int mode, int
timeout)
Sets the transactionTimeout parameter for Tamino
requests.
handle - a valid handle obtained
from tac_init().
mode - either
TAC_SESSION or TAC_COMMAND. For
more information, see Transaction
Parameter Handling.
timeout - the desired maximum
transaction duration in seconds. The predefined constant
TAC_DEFAULT, which is set to zero, can also be
used.
The predefined constant TAC_SUCCESS upon
success, or a negative value upon failure.
