c-treeDB API for C++ - Developers Guide

CTBase::SetKeepLock

Set the current keep lock mode when a transaction is committed or aborted.

Syntax

void CTBase::SetKeepLock(CTKEEP_MODE mode);

Description

When a transaction is terminated by calling either the CTBase::Commit() or CTBase::Abort() function, all locks are automatically freed, including the locks acquired outside the transaction. An application might want to control which locks are kept when the transaction ends. To support this ability, c-treeDB introduced a function to control how locks are handled when a transaction terminates.

By default, the c-treeDB begin transaction function, ctdbBegin(), will begin a transaction by invoking c-tree’s TRANBEG function with the ctTRNLOG and ctENABLE_BLK modes set. If the TRANBEG function succeeds, c-treeDB’s ctdbBegin() function automatically calls LKISAM() to suspend locks enabled by TRANBEG, allowing users to enable any locks they wish: read locks, write locks, blocking or non-blocking. In this case, the c-treeDB commit or abort transaction functions, ctdbCommit() and ctdbAbort(), call the appropriate c-tree ISAM functions to terminate the transaction and free all locks.

CTBase::SetKeepLock() set the extended keep lock mode applied when an active transaction is committed or aborted.

The keep lock mode is one of the following pre-defined constants:

Value	Symbolic Constant	Explanation
0	CTKEEP_FREE	Release all locks. Clear LKISAM state, turning off session-wide record locking. This is the default mode.
1	CTKEEP_LOCK	Keep all locks acquired before and during transaction, leaving session-wide record locking as it was. The LKISAM state is not cleared.
2	CTKEEP_OUT	Release only locks obtained within transaction and/or locks on records updated within transaction. The LKISAM state is not cleared, leaving session-wide record locking as it was.
3	CTKEEP_OUTALL	Unconditionally keep all locks acquired before transaction began. Free locks obtained within the transaction. The LKISAM state is not cleared, leaving session-wide record locking as it was.

Once the keep lock mode is set, it remains active until another keep mode is set or the keep mode is cleared by calling SetKeepLock() with mode CTKEEP_FREE.

Return

void

Example

// set the keep lock

hSession.SetKeepLock(CTKEEP_LOCK);

// begin a new transaction

hSession.Begin();

// do some operations and commit transaction

hSession.Commit();

// do some more operations and free all locks

hSession.Unlock();