Transaction-Related Commands

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:

Transaction Parameter Handling

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:

  1. a valid handle;

  2. either the keyword TAC_COMMAND or the keyword TAC_SESSION;

  3. a pointer to a structure that contains the five parameter fields.

tac_commit

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).

tac_connect

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).

tac_disconnect

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).

tac_get_transaction_parameters

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 - 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.

Returns:

The predefined constant TAC_SUCCESS upon success, or a negative value upon failure.

tac_rollback

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).

tac_set_isolation_level

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 - 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.

Returns:

The predefined constant TAC_SUCCESS upon success, or a negative value upon failure.

tac_set_lock_mode

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 - 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.

Returns:

The predefined constant TAC_SUCCESS upon success, or a negative value upon failure.

tac_set_lockwait

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 - 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.

Returns:

The predefined constant TAC_SUCCESS upon success, or a negative value upon failure.

tac_set_nonactivity_timeout

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 - 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.

Returns:

The predefined constant TAC_SUCCESS upon success, or a negative value upon failure.

tac_set_transaction_timeout

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 - 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.

Returns:

The predefined constant TAC_SUCCESS upon success, or a negative value upon failure.