FairCom DB API for C

ctdbSetKeepLock

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

DECLARATION

CTDBRET ctdbSetKeepLock(CTHANDLE Handle, CTKEEP_MODE mode);

DESCRIPTION

When a transaction is terminated by calling either the ctdbCommit() or ctdbAbort() function, all locks are automatically freed — both session-wide record locks (automatically acquired as a result of calling ctdbLock() and then reading a record from a table file), and manually locked records (acquired by calling ctdbLockRecord() on an individual record). Locks acquired both inside and outside the transaction are released. Not only that, ctdbCommit() and ctdbAbort() also disable (turn off) session-wide record locking. This is the default behavior. However, an application might want to control which locks are kept when the transaction ends, and whether the session-wide record locking mode is turned off or not. To support this ability, FairCom DB API introduced a function to control how locks and the session-wide record locking mode are handled when a transaction terminates.

By default, the FairCom DB API 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, FairCom DB API’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 FairCom DB API commit or abort transaction functions, ctdbCommit() and ctdbAbort(), call the appropriate c-tree ISAM functions to terminate the transaction and free all locks.

ctdbSetKeepLock() sets the extended keep lock mode applied when an active transaction is committed or aborted by calling ctdbCommit() or ctdbAbort().

Handle is a session handle and 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.

RETURN

Value	Symbolic Constant	Explanation
0	CTDBRET_OK	No error occurred.

See Appendix A for a complete listing of valid c-tree Plus error values.

EXAMPLE

/* set the keep lock */

if (ctdbSetKeepLock(hSession, CTKEEP_LOCK) != CTDBRET_OK)

printf("ctdbSetKeepLock failed\n");

/* begin the transaction */

ctdbBegin(hSession);

/* do some operations and commit transaction */

ctdbCommit(hSession);

/* do some other operations and release the locks *.

ctdbUnlock(hSession);