ctdbAbort

Abort a transaction.

Declaration

CTDBRET ctdbAbort(CTHANDLE Handle)

• Handle [in] the session handle. Any handle will work, but you save a tiny bit of CPU by using the session handle.

Description

ctdbAbort() aborts a transaction initiated with ctdbBegin() and releases all locks, 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. This function also disables (turns off) session-wide record locking. Note that these lock-related behaviors can be changed from the default by calling ctdbSetKeepLock().

Returns

ctdbAbort() returns CTDBRET_OK if successful, or the c-tree error code on failure. Common causes of abort errors are calling ctdbAbort() twice in a row or calling ctdbAbort() after a successful call to ctdbCommit() or calling ctdbAbort() without calling ctdbBegin() first to start a transaction. Extreme circumstances, like the failure of computer hardware, can cause calls to ctdbCommit() and ctdbAbort() to fail. In situations like this, a common approach is to log an error and exit.

Example

ctdbBegin(pSession);

if (ctdbCreateTable(tHandle1,"table1",CTCREATE_NORMAL) == CTDBRET_OK)

       ctdbCommit(pSession);

else

       ctdbAbort(pSession);

See also

ctdbBegin(), ctdbClearSavePoint(), ctdbCommit(), ctdbRestoreSavePoint(), ctdbSetKeepLock(), ctdbSetSingleSavePoint(), Locking

ctdbBegin

Start a transaction.

Declaration

CTDBRET ctdbBegin(CTHANDLE Handle)

Description

ctdbBegin() marks the beginning of a transaction. All file updates done after this call will be held until they are committed with a matching call to ctdbCommit(), or aborted with a matching call to ctdbAbort(). Notice that the record locks still must be manually acquired with a call to ctdbLockRecord(), or, even better, automatically acquired via the session-wide locking mechanism (see ctdbLock()). If for any reason the transaction cannot be committed, it can be finished (by discarding it) with a call to ctdbAbort(). This function can be used to perform transaction-controlled file creates.

It is important to realize that FairCom DB API transactions are session-wide, and since FairCom DB API does not support nested transactions, you can only have one transaction "open" at a time. If you call ctdbBegin() twice in a row, the second call will return an error. You can use save points to mimic nested transactions, though (see ctdbSetSavePoint() and ctdbSetSingleSavePoint()). Transactions only affect certain types of tables; see the Creating tables for transaction processing section in Transactions under Data Integrity.

• Handle [in] - the session handle. Any handle will work, but you save a tiny bit of CPU by using the session handle.

Returns

ctdbBegin() returns CTDBRET_OK if successful, or the c-tree error code on failure.

Example

ctdbBegin(pSession);

if (ctdbCreateTable(tHandle1,"table1",CTCREATE_NORMAL) == CTDBRET_OK)

       ctdbCommit(pSession);

else

       ctdbAbort(pSession);

See also

ctdbAbort(), ctdbClearSavePoint(), ctdbCommit(), ctdbRestoreSavePoint(), ctdbSetSavePoint(), ctdbSetSingleSavePoint()

ctdbAddCriteria

Adds a new criteria to the given CTResultSet handle

Declaration

CTHANDLE ctdbAddCriteria(CTHANDLE Handle, CTHANDLE FieldHandle,
    pTEXT LowValue, pTEXT HighValue, NINT CriteriaOp)

Parameters:

• Handle [IN] - Result Set handle.
• FieldHandle [IN] - Field handle.
• LowValue [IN] - Low Criteria Value.
• HighValue [IN] - High Criteria Value. If operator requires only one criteria value, only the LowValue will be used (this one will be ignored).
• CriteriaOp [IN] - Criteria Operator. Can be CTIX_EQ, CTIX_NE, CTIX_GT, CTIX_GE, CTIX_LE, CTIX_LT, CTIX_BET, CTIX_BET_IE, CTIX_BET_EI, CTIX_BET_EE, or CTIX_NOTBET.

Description

The result set handle is allocated with ctdbAllocateResultSet() for a specific table handle, and then it is possible to add one or more criteria with ctdbAddCriteria(). The criteria have a field to be checked against the table handle that owns the result set, one or two values (depending on the comparison operator) and the operator to be used. The operator can be on of: CTIX_EQ, CTIX_NE, CTIX_GT, CTIX_GE, CTIX_LE, CTIX_LT, CTIX_BET, CTIX_BET_IE, CTIX_BET_EI, CTIX_BET_EE or CTIX_NOTBET. When the result set has all the criteria added, it can be turned on or off (ctdbResultSetOnOff()) for any record handle that is allocated for the same table handle that owns the result set.

Limitations

• A result set can't be turned on for a record that is already filtered. And when a record has a result set turned on, it is not possible to add any other filter. This limitation may be relaxed in the future.
• When a result set is changed (ctdbAddCriteria(), ctdbRemoveCriteria() and ctdbUpdateCriteria()), it must be re-applied to the record handle (ctdbResultSetOnOff()) to have these changed take effect..

Returns

A CTResultSetCri handle. NULL otherwise.

Example

   CTHANDLE hResSet;

   CTHANDLE hResSetCri;

/* Allocate a Result Set for Table */

if (!(hResSet = ctdbAllocateResultSet( hTable, "resSet1" )))

    Handle_Error("Test_ResultSet1(); ctdbAllocateResultSet()");

/* Add a new criteria for the Result Set just allocated */

if (!(hResSetCri = ctdbAddCriteria( hResSet, hField0, "1002", NULL, CTIX_EQ )))

    Handle_Error("Test_ResultSet1(); ctdbAddCriteria()");

/* Turn on the Result Set for the current record handle */

if (ctdbResultSetOnOff( hResSet, hRecord, YES, YES, CTLOC_NONE ) != CTDBRET_OK)

    Handle_Error("Test_ResultSet1(); ctdbResultSetOnOff()");

/* Display records on the Result Set */

Display_Records(hRecord);

/* Release Result Set handle */

ctdbFreeResultSet( hResSet );

See also

• ctdbGetResultSetHandle, ctdbAllocateResultSet, ctdbFreeResultSet, ctdbResultSetOnOff, ctdbGetResultSetByName, ctdbGetResultSetCriHandle, ctdbAddCriteria, ctdbRemoveCriteria, ctdbUpdateCriteria, ctdbGetActiveResultSet

ctdbClearSavePoint

Clears the last transaction save point.

Declaration

NINT ctdbClearSavePoint(CTHANDLE Handle)

Description

• Handle [in] the session handle.

Returns

ctdbClearSavePoint() returns CTDBRET_OK on success and a c-tree error code to indicate failure. uerr_cod contains the c-tree error code.

ctdbClearSavePoint() cannot clear a special save point returns a SPCL_ERR (753) error in this case.

See also

ctdbAbort(), ctdbBegin(), ctdbCommit(), ctdbRestoreSavePoint(), ctdbSetSingleSavePoint()

ctdbCommit

Commit a transaction.

Declaration

CTDBRET ctdbCommit(CTHANDLE Handle)

• Handle [in] the session handle. Any handle will work, but you save a tiny bit of CPU by using the session handle.

Description

ctdbCommit() commits a transaction initiated with ctdbBegin() and releases all locks — 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. This function also disables (turns off) session-wide record locking. Note that these lock-related behaviors can be changed from the default by calling ctdbSetKeepLock().

Returns

ctdbCommit() returns CTDBRET_OK if successful, or the c-tree error code on failure. Common causes of commit errors are calling ctdbCommit() twice in a row, or calling ctdbCommit() without calling ctdbBegin() first to start a transaction. Note that if ctdbCommit() fails (and there is an open transaction), then the transaction can be rolled back to a previous set point, if any were saved, by calling ctdbRestoreSavePoint(); or the transaction can be aborted (rolled back to the beginning) by calling ctdbAbort(). Extreme circumstances, like the failure of computer hardware, can cause calls to ctdbCommit() and ctdbAbort() to fail. In situations like this, a common approach is to log an error and exit.

Example

ctdbBegin(pSession);

if (ctdbCreateTable(tHandle1,"table1",CTCREATE_NORMAL) == CTDBRET_OK)

       ctdbCommit(pSession);

else

       ctdbAbort(pSession);

See also

ctdbAbort(), ctdbBegin(), ctdbClearSavePoint(), ctdbRestoreSavePoint(), ctdbSetSingleSavePoint()

ctdbGetAutoCommit

Declaration

CTBOOL ctdbDECL ctdbGetAutoCommit(CTHANDLE Handle);

Description

ctdbGetAutoCommit() retrieves the FairCom DB API auto commit mode. The auto commit of transactions are invoked automatically when records are added or updated by ctdbWriteRecord() call.

• Handle must be a session handle.

Return Values

See Also

ctdbSetAutoCommit() ctdbSetOperationState() ctdbGetOperationState()

ctdbGetKeepLock

Retrieves the current extended keep lock mode.

DECLARATION

CTKEEP_MODE ctdbDECL ctdbGetKeepLock(CTHANDLE Handle);

DESCRIPTION

ctdbGetKeepLock() retrieves the current state of how the transaction commit and abort will handle locks acquired before and during the transaction.

• Handle is a session handle.

RETURN

One of the following keep lock modes is returned:

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

EXAMPLE

/* make sure the current keep lock mode is CTKEEP_LOCK */

if (ctdbGetKeepLock(hSession) != CTKEEP_LOCK)

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

printf("ctdbSetKeepLock failed\n");

SEE ALSO

ctdbAbort ctdbBegin(), ctdbCommit(), ctdbSetKeepLock()

ctdbGetRebuildProgress

Retrieves the table’s rebuild progress counter.

DECLARATION

NINT ctdbGetRebuildProgress(CTHANDLE Handle);

DESCRIPTION

When a full alter table rebuild is in progress, the table handle keeps a counter of the progress. The progress is kept in terms of percent completed with values from 0% to 100%.

You can use this function with a CTDB_ON_TABLE_REBUILD callback to retrieve the progress indicator. CTDB_ON_TABLE_REBUILD is called for each percentage point. Before any records are processed, CTDB_ON_TABLE_REBUILD callback is called with a percentage value of zero to indicate that the operation is about to start. After all records are processed, CTDB_ON_TABLE_REBUILD is called again, this time with a percentage value of 100 to indicate the end of rebuild.

RETURN

A progress counter value from 0 to 100.

EXAMPLE

CTDBRET ctdbDECL OnTableRebuild(CTHANDLE Handle)

{

/* display a dot for every 5% rebuild completed */

NINT perc = ctdbGetREbuildProgress(Handle);

if (perc > 0 && (perc % 5) == 0)

printf(".");

return CTDBRET_OK;

}

SEE ALSO

ctdbClearAllCallback(), ctdbClearCallback(), ctdbGetCallback(), ctdbSetCallback()

ctdbGetRecordLock

Return the record lock status.

Declaration

CTLOCK_MODE ctdbGetRecordLock(CTHANDLE Handle)

Description

ctdbGetRecordLock() retrieves the record lock status.

• Handle [in] the record handle.

Returns

ctdbGetRecordLock() returns the lock mode of a single record, in particular, CTLOCK_FREE if the record is not locked, CTLOCK_READ if the record has a read lock or CTLOCK_WRITE if the record has a write lock. This works both for records automatically locked with session-wide record locking (see ctdbLock()), and for records manually locked via calls to ctdbLockRecord().

See also

ctdbAllocRecord(), ctdbLockRecord(), ctdbUnlockRecord(), Locking

ctdbGetTransactionMode

Declaration

CTBEGIN_MODE ctdbDECL ctdbGetTransactionMode(CTHANDLE Handle);

Description

Returns the transaction mode used when starting a transaction.

c-tree Plus offers a rich array of data integrity options. Full transaction processing offers the safest and best performance of all the available options. There are times when other c-tree Plus options, such as PREIMG, might be advantageous.

Return Values

ctdbGetTransactionMode() returns one of the following values:

See Also

ctdbGetTransactionMode()

ctdbIsLockActive

Indicates if session-wide record locking is currently active.

Declaration

CTBOOL ctdbIsLockActive(CTHANDLE Handle)

Description

ctdbIsLockActive() indicates if session-wide record locking is currently active. Session-wide record locking is active/enabled if a call to ctdbLock(), with one of the READ or WRITE segment mode variations, has been made. The lock active flag is cleared with a call to ctdbUnlock() or with a call to ctdbLock() with the lock mode set to CTLOCK_FREE or CTLOCK_SUSPEND. Ending a transaction via calls to ctdbCommit() or ctdbUnlock() will also clear the lock active flag. This function does not verify if a call to ctdbLockRecord() was made because ctdbIsLockActive() does not check the lock status of individual records. To do that, use ctdbGetRecordLock().

• Handle [in] the Session or any other Handle.

Returns

ctdbIsLockActive() returns YES if the session-wide record locking mode is one of the READ or WRITE variations, NO otherwise.

Example

if (ctdbIsLockActive(pSession))

ctdbUnlock(pSession);

See also

ctdbLock(), ctdbUnlock(), ctdbGetLockMode(), ctdbLockRecord(), Locking

ctdbIsTransActive

Check whether a transaction commit or abort is pending.

Declaration

CTBOOL ctdbIsTransActive(CTHANDLE Handle)

Description

ctdbIsTransActive() checks whether a transaction commit or abort is pending. An active transaction is one that has been initiated with a ctdbBegin() call.

• Handle [in] the session handle.

Returns

ctdbIsTransActive() returns YES if the transaction is active, NO otherwise.

See also

ctdbBegin(), ctdbCommit(), ctdbAbort()

ctdbLock

Turn the automatic session-wide record locking mechanism on or off.

Declaration

CTDBRET ctdbLock(CTHANDLE Handle, CTLOCK_MODE mode)

Description

ctdbLock adjusts the current session-wide record lock mode used by the lock manager. Session-wide record locking is one of the two methods provided by the FairCom DB API API to lock records. This method (session-wide locking) is the recommended method of locking records, because this method automatically locks the record as it is read from the table file, as opposed to manually locking the record AFTER it has been read, which leaves a window of opportunity for another thread to modify or delete the record after you read it and before you locked it. This function is used to turn the session-wide locking system on and off, suspend and un-suspend it, etc. This function is NOT used to manipulate the lock status of individual records.

After a call to ctdbLock with a mode other than CTLOCK_FREE or CTLOCK_SUSPEND, all operations involving file reads will be automatically locked. For example, all records read (ctdbFirstRecord, ctdbNextRecord, ctdbLastRecord, ctdbFindRecord, etc.) after a call to ctdbLock, will be automatically locked as they are read in from the table file on disk.

To manually lock only the current record using the other record locking mechanism provided by the FairCom DB API API, use ctdbLockRecord.

Note: Calling ctdbLock() does not actually lock any files or records. Instead, it sets an internal flag to indicate that all new record reads will automatically lock the records with the given lock mode.

• Handle [in] the Session or other internal Handle.
• mode [in] one of the valid FairCom DB API session-wide lock modes. The valid lock modes are listed in Session-Wide Lock Modes.

A READ lock (also called a "shared" lock) on a record allows an unlimited number of READ locks on that record, but prevents WRITE locks. A WRITE lock (also called an "exclusive" lock) prevents any other locks on that record.

Note that if the specified lock (READ or WRITE) cannot be obtained (because another client application or thread already has a conflicting lock on that record, for example), then the record read will either block (the "_BLOCK" locking modes), or fail with an error (the locking modes that do not end with the word "_BLOCK").

To turn off session-wide record locking and release the locks on some records, call ctdbUnlock(), or call ctdbLock() with the mode set to CTLOCK_FREE. There are various subtlties about how this works and which locks get released and which do not. For the details, please see the writeup for the ctdbUnlock() function. For more details about how session-wide locking is used, see the section titled Locking.

Note: Mixing ctdbLockRecord() and ctdbLock() may result in DLOK_ERR (42) returns when an automatic lock is attempted on a manually locked record, or vice versa. DLOK_ERR (42) simply means a lock could not be obtained. Check sysiocod for the system-level error to determine why the record could not be locked. In the example above, a locked record cannot be re-locked.

Returns

ctdbLock() returns CTDBRET_OK on success, or FairCom DB API C API error code on failure. Related common errors to are:

• CTDBRET_INVLOCKMODE (4055): Invalid lock mode.
• CTDBRET_NOTSESSION (4003): Invalid handle - use a Session handle.

See Also

ctdbCommit(), ctdbAbort(), ctdbIsLockActive(), ctdbUnlock(), ctdbGetLockMode(), ctdbLockRecord(), ctdbSetKeepLock(), ctdbUnlockTable(), Session-Wide Lock Modes, Locking

ctdbLockRecord

Lock the current record using the manual record locking system.

Declaration

CTDBRET ctdbLockRecord(CTHANDLE Handle, CTLOCK_MODE Mode)

Description

ctdbLockRecord() manually locks the current record with the specified record lock mode.

This function can also be used to demote a WRITE lock currently held by a record (as long as that record has not been modified) by specifying one of the READ lock modes.

This function can also be used to release a lock currently held by a record by specifying the CTLOCK_FREE lock mode. Doing this is equivalent to calling ctdbUnlockRecord(), and since certain exceptions apply to record unlocking, the documentation for ctdbUnlockRecord() should be consulted. A list of the available record lock modes is in Record Lock Modes.

When using ctdbLockRecord() to demote or release a record lock, it does not matter if the record lock was originally acquired manually (by calling ctdbLockRecord()) or acquired automatically (via the session-wide record locking mechanism).

• Handle [in] the record handle.

Mode [in] the new locking mode for the record.

A READ lock (also called a "shared" lock) on a record allows an unlimited number of READ locks on that record, but prevents WRITE locks. A WRITE lock (also called an "exclusive" lock) prevents any other locks on that record.

Note that if the specified lock (READ or WRITE) cannot be obtained (because another client application or thread already has a conflicting lock on that record, for example), then the record read will either block (the "_BLOCK" locking modes), or fail with an error (the locking modes that do not end with the word "_BLOCK").

Usage Note:

Although the current record is locked after calling ctdbLockRecord(), the buffered record data could have been modified by another user before the ctdbLockRecord() call was made. Call ctdbReadRecord() to re-read the locked record to avoid this potential for stale data.

In most cases it is more efficient to use the other record locking mechanism provided by the FairCom DB API API (session-wide record locking), which is not subject to this problem. With session-wide record locking, you first call ctdbLock() to turn on session-wide record locking, and then, each time you make a call that reads, writes, or deletes a record, the record is automatically locked before it is read from disk / written to disk. See the ctdbLock() function for more details.

Note: Manual record locking should NOT be used in situations where a given table is open / active more than once at the same time, in the same session, using two different table handles, because unexpected locking / unlocking behavior can result. For more details, in client/server situations, see FairCom Server enhanced locking control for files opened multiple times in the same connection. If you need to have the same table open more than once at the same time, please use session-wide record locking (see ctdbLock()).

Returns

ctdbLockRecord() returns CTDBRET_OK on success, or FairCom DB API C API error code on failure. If there is no current record, ctdbLockRecord() returns CTDBRET_NOTACTIVE (4012).

See also

ctdbUnlockRecord(), ctdbLock(), ctdbBegin(), ctdbSetKeepLock(), ctdbUnlockTable(), Record Lock Modes, Locking, Record Lock Modes

ctdbRestoreSavePoint

Restore a transaction save point.

Declaration

CTDBRET ctdbRestoreSavePoint(CTHANDLE Handle, NINT SavePoint)

Description

ctdbRestoreSavePoint() restores a transaction save point.

• Handle [in] the session handle.
• SavePoint [in] the save point number returned by ctdbSetSavePoint(). SavePoint can be set to -1 to back up to most current save point, can be set to -2 to back up one more, -3 more....etc. If SavePoint is 0, the most current save point is restored.

Returns

ctdbRestoreSavePoint() returns CTDBRET_OK if successful, or the c-tree error code on failure.

See also

ctdbAbort(), ctdbBegin(), ctdbClearSavePoint(), ctdbCommit(), ctdbSetSingleSavePoint()

ctdbSetAutoCommit

Sets the FairCom DB API auto commit mode.

Declaration

CTDBRET ctdbDECL ctdbSetAutoCommit(CTHANDLE Handle, CTBOOL flag);

Description

ctdbSetAutoCommit() sets the FairCom DB API auto commit mode. The auto commit of transactions are invoked automatically when records are added or updated by a ctdbWriteRecord() call. Automatic transactions may increase performance by reducing network traffic for single record updates since this is equivalent of performing the following functions:

ctdbBegin();

if (ctdbWriteRecord() == CTDBRET_OK)

ctdbCommit();

else

ctdbAbort();

• Handle is a session handle.
• flag indicates if auto commit mode should be enabled or not.

The following apply when an automatic transaction is performed:

• An automatic transaction will only free locks acquired by the ctdbWriteRecord() function.
• If an automatic transaction is aborted because of errors detected by ctdbWriteRecord(), all locks acquired by ctdbWriteRecord() are released.
• If locks are active, by calling ctdbLock() function, an automatic transaction will not release any locks when it commits or aborts the ctdbWriteRecord() operation.
• If OPS_UNLOCK_UPD is on, both commits and aborts on automatic transactions release only locks obtained within trans and/or locks on records updated within transaction, regardless if the FairCom DB API session lock state is active or not.

Return Values

See Also

ctdbGetAutoCommit() ctdbSetOperationState() ctdbGetOperationState()

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:

RETURN

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

SEE ALSO

ctdbAbort, ctdbBegin(), ctdbCommit(), ctdbGetKeepLock()

ctdbSetSavePoint

Establish a transaction save point.

Declaration

NINT ctdbSetSavePoint(CTHANDLE Handle)

Description

ctdbSetSavePoint() establishes a transaction save point.

• Handle [in] the session handle.

Returns

ctdbSetSavePoint() returns the save point number, or 0 on failure.

See also

ctdbBegin(), ctdbCommit(), ctdbAbort(), ctdbRestoreSavePoint()

ctdbSetSingleSavePoint

A wrapper function for ReplaceSavePoint. 

ctdbSetTransactionMode

OR-ed in to form the transaction mode used when a c-tree transaction is started.

Declaration

CTDBRET ctdbDECL ctdbSetTransactionMode(CTHANDLE Handle, CTBEGIN_MODE mode);

Description

• Handle is a session handle.
• mode is a combination of possible mode values:

This mode will be OR-ed in to form the transaction mode used when a c-tree transaction is started. If the transaction mode is CTBEGIN_NONE, the ctTRNLOG mode is used to start a new transaction.

Return Values

See Also

ctdbGetTransactionMode()

ctdbUnlock

Disables or suspends session-wide record locking and releases some record locks.

Declaration

CTDBRET ctdbUnlock(CTHANDLE Handle)

Description

ctdbUnlock() disables or suspends session-wide record locking, so any records read after calling this function will NOT be automatically locked. Also, ctdbUnlock() releases some (but not all) of the record locks, as described below. Calling this function is the same as calling ctdbLock() with the lock mode CTLOCK_FREE.

• Handle [in] a Session or any other Handle.

This function behaves differently if called inside or outside of a transaction. ("Inside a transaction" means that ctdbBegin() was called, but ctdbCommit() / ctdbAbort() was NOT called.)

Inside a Transaction - Session-wide record locking is suspended. All currently-locked records remain locked. This means both records automatically locked via the session-wide record locking mechanism (call ctdbLock() and then read a record), and records manually locked by calling ctdbLockRecord() on an individual record. Later, when the transaction is finished (by calling ctdbCommit() or ctdbAbort()), the locks on these records will be released. To restore session-wide locking (un-suspend it), call ctdbLock() with one of the READ or WRITE lock modes (or one of the RESTORE options).

Outside a Transaction - Session-wide record locking is turned off. All records that were automatically locked via the session-wide record locking mechanism (call ctdbLock() and then read a record) are unlocked. All records that were manually locked by calling ctdbLockRecord() on an individual record remain locked, EXCEPT for records from a CTCREATE_NORMAL table that were modified and then written before this function was called; those records are unlocked.

To release record locks that were manually obtained with ctdbLockRecord(), use ctdbUnlockRecord().

If the unused locks from a particular table must be released inside a transaction, ctdbUnlockTable() may be used. Unused locks are records that where locked but not updated/deleted/added.

Returns

ctdbUnlock() returns CTDBRET_OK on success, or FairCom DB API C API error code on failure.

Example

if (ctdbIsLockActive(pSession))

ctdbUnlock(pSession);

See also

ctdbLock(), ctdbIsLockActive(), ctdbGetLockMode(), ctdbUnlockRecord(), ctdbUnlockTable(), Locking

ctdbUnlockRecord

Unlock the current record.

Declaration

CTDBRET ctdbUnlockRecord(CTHANDLE Handle)

Description

ctdbUnlockRecord() unlocks the current record, regardless of whether the record was automatically locked via the session-wide record locking mechanism (call ctdbLock() and then read a record), or manually locked by calling ctdbLockRecord() on an individual record. There is one exception to this - any new/modified/deleted records that were locked (via either of the locking methods) in a transaction, in a CTCREATE_TRNLOG / CTCREATE_PREIMG table, are NOT unlocked by this function. (But locks on records in a CTCREATE_NORMAL table ARE unlocked.) Later, when the transaction is finished (by calling ctdbCommit() or ctdbAbort()), the locks on those still-locked records will be released. This function has no effect on the session-wide record locking mode (it does not turn it on or off, or suspend it, etc.) Use ctdbUnlockTable() to unlock ALL the locked records (with certain exceptions) in a given table.

• Handle [in] the record handle.

Returns

ctdbUnlockRecord() returns CTDBRET_OK on success, or FairCom DB API C API error code on failure.

See also

ctdbLockRecord(), ctdbUnlock(), Locking

ctdbUnlockTable

Releases all record locks associated with a table.

Declaration

CTDBRET ctdbUnlockTable(CTHANDLE Handle)

Description

ctdbUnlockTable() releases all record locks associated with the specified table, regardless of whether the records were automatically locked via the session-wide record locking mechanism (call ctdbLock() and then read a record), or manually locked by calling ctdbLockRecord() on an individual record. There is one exception to this - any new/modified/deleted records that were locked (via either of the locking methods) in a transaction, in a CTCREATE_TRNLOG / CTCREATE_PREIMG table, are NOT unlocked by this function. (But locks on records in a CTCREATE_NORMAL table ARE unlocked.) Later, when the transaction is finished (by calling ctdbCommit() or ctdbAbort()), the locks on those still-locked records will be released. This function has no effect on the session-wide record locking mode (it does not turn it on or off, or suspend it, etc.) Use ctdbUnlockRecord() to unlock just one record (with certain exceptions).

• Handle [in] the Table, Record, Field, Index or Segment Handle.

Returns

ctdbUnlockTable() returns CTDBRET_OK on success, or FairCom DB API C API error code on failure.

See also

ctdbLockRecord(), ctdbUnlockRecord(), Locking