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.
- Takes Parameters:
handle - a valid handle obtained from
tac_init()
.- Returns:
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.
- Takes Parameters:
handle - a valid handle obtained from
tac_init()
.- Returns:
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.
- Takes Parameters:
handle - a valid handle obtained from
tac_init()
.- Returns:
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.
- Takes Parameters:
handle - a valid handle obtained from
tac_init()
.
mode - eitherTAC_SESSION
orTAC_COMMAND
For more information, see Transaction Parameter Handling.
trans - a pointer to the predefined structureTAC_TRANSACTION_T
containing the five current transaction parameters for the specified mode.- Returns:
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.
- Takes Parameters:
handle - a valid handle obtained from
tac_init()
.- Returns:
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.
- Takes Parameters:
handle - a valid handle obtained from
tac_init()
.
mode - eitherTAC_SESSION
orTAC_COMMAND
For more information, see Transaction Parameter Handling.
isolation_level - one of the predefined constantsTAC_DEFAULT
,TAC_ISOLATIONLEVEL_NONE
,TAC_ISOLATIONLEVEL_UNCOMMITTED
,TAC_ISOLATIONLEVEL_COMMITTED
,TAC_ISOLATIONLEVEL_CURSOR
,TAC_ISOLATIONLEVEL_DOCUMENT
orTAC_ISOLATIONLEVEL_SERIALIZABLE
.- Returns:
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.
- Takes Parameters:
handle - a valid handle obtained from
tac_init()
.
mode - eitherTAC_SESSION
orTAC_COMMAND
. For more information, see Transaction Parameter Handling.
lock_mode - one of the predefined constantsTAC_DEFAULT
,TAC_LOCKMODE_SHARED
,TAC_LOCKMODE_PROTECTED
orTAC_LOCKMODE_UNPROTECTED
.- Returns:
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.
- Takes Parameters:
handle - a valid handle obtained from
tac_init()
.
mode - eitherTAC_SESSION
orTAC_COMMAND
. For more information, see Transaction Parameter Handling.
lockwait - one of the predefined constantsTAC_DEFAULT
,TAC_LOCKWAIT_YES
orTAC_LOCKWAIT_NO
.- Returns:
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.
- Takes Parameters:
handle - a valid handle obtained from
tac_init()
.
mode - eitherTAC_SESSION
orTAC_COMMAND
. For more information, see Transaction Parameter Handling.
timeout - the desired non-activity timeout in seconds. The predefined constantTAC_DEFAULT
, which is set to zero, can also be used.- Returns:
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.
- Takes Parameters:
handle - a valid handle obtained from
tac_init()
.
mode - eitherTAC_SESSION
orTAC_COMMAND
. For more information, see Transaction Parameter Handling.
timeout - the desired maximum transaction duration in seconds. The predefined constantTAC_DEFAULT
, which is set to zero, can also be used.- Returns:
The predefined constant
TAC_SUCCESS
upon success, or a negative value upon failure.