|
|
|
There is a group of functions that are generic enough to operate with any one of the FairCom DB API API handles. Although these functions require a handle to operate on, they accept any one of the FairCom DB API session, database, table, record, field, index and segment handles.
|
|
|
Most FairCom DB API API functions return an error status to indicate if a particular function operation succeeded or not. Most FairCom DB API API functions will also keep the last error status, if the function operation failed. The last error status can be manipulated with the following functions:
/* clear error if error is INOT_ERR */
if (ctdbGetError(AnyHandle) == INOT_ERR)
{
ctdbClearError(AnyHandle);
}
|
|
|
The FairCom DB API API implementation of its transaction processing functions closely follows the existing FairCom DB ISAM API. The basic difference between the two transaction processing APIs is the separation of locking from the "begin transaction" functions. While the FairCom DB ISAM "begin transaction" function also turns on locking, the FairCom DB API "begin transaction" function does not.
Note that the FairCom DB API functions to END a transaction (ctdbCommit() and ctdbAbort()) do include unlocking behavior. They turn off session-wide locking AND release all locks (both locks automatically acquired via the session-wide locking mechanism and locks manually acquired by calling ctdbLockRecord()).
The code fragment below shows an example using the FairCom DB ISAM calls to process a transaction with locking:
/* start transaction enabling write locks */
TRANBEG(TRNLOG | ENABLE | LK_BLOCK);
... perform some data operations ...
/* commit the transaction and release locks */
TRANEND(FREE);
The FairCom DB ISAM code fragment above starts a transaction by invoking TRANBEG(). The mode ENABLE indicates that every FairCom DB read record operation will lock the record for writing. The mode LK_BLOCK indicates that the thread will block until the lock is acquired.
When using the FairCom DB API API on the other hand, the call that starts transaction processing will not start the session-wide record-locking mechanism. The code fragment below shows the equivalent example using the FairCom DB API API:
/* start a transaction */
ctdbBegin(AnyHandle);
/* enable blocking write locks */
ctdbLock(AnyHandle, CTLOCK_WRITE_BLOCK);
... perform some data operations ...
/* commit transaction, release locks, turn off session-wide record locking */
ctdbCommit(AnyHandle);
ctdbBegin() starts a new transaction.
ctdbLock() turns on session-wide record WRITE locking, in "blocking" mode. (See Session-Wide Record Locking.) After that, any attempts to read, change, or delete a record will automatically lock that record with a write lock. If the write lock cannot be obtained for that record (because another client application / thread already has a conflicting lock on that record, for example), then ctdbLock() will block until the lock can be obtained (as specified by the word "_BLOCK" in "CTLOCK_WRITE_BLOCK").
ctdbCommit() terminates the transaction by committing any changes. Note that ctdbCommit() also turns off session-wide record locking, and releases all of the record locks. Here are some other functions that you might use in this context:
ctdbAbort() terminates a transaction and aborts any changes done during the transaction (and turns off session-wide record locking, and releases all of the record locks).
ctdbSetSavePoint() and ctdbSetSingleSavePoint() set a savepoint in the current transaction. Once a save point is set within the current transaction, ctdbRestoreSavePoint() will reverse only the changes done between the set save point call and the restore save point call without terminating the transaction.
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.
Refer to Data Integrity for detailed description of FairCom DB API API for transaction processing, save points, and locking.
|
|
|
Locking is a useful mechanism that can be used to promote data integrity when you have a situation where multiple clients or multiple client threads are accessing the same tables simultaneously.
Session-wide record locking is based on the principle that ctdbLock() sets the current session-wide lock mode (but does not actually lock any records when it is called). When locking is activated this way, every record read, write, or delete of all active tables of all active databases associated with the session are automatically locked with the current session-wide lock mode (as set by the ctdbLock() call).
ctdbUnlock() releases all locks automatically acquired since session-wide record locking was turned on and clears the current session-wide lock mode, with certain exceptions – see the ctdbUnlock() function). Notice that ctdbCommit() and ctdbAbort() release all locks and clear the current session-wide lock mode.
ctdbIsLockActive() indicates if a session-wide lock mode is set. (In other words, if record reads, writes, and deletes will automatically be locked or not).
ctdbGetLockMode() retrieves the current session-wide lock mode. If the session-wide lock system is turned off, ctdbGetLockMode() returns CTLOCK_FREE.
Refer to Data Integrity for detailed description of the FairCom DB API API for transaction processing and locking.
|
|
|
The FairCom DB API record manager performs automatic data type conversions when the user reads from, or writes to, a field using a data type different from the field data type. For most data types, the conversion is straight forward except when converting dates and times from and to strings, since there are many different conventions for displaying dates and times.
By default the FairCom DB API API converts date to string, and from string to date, using the standard USA convention of MM/DD/CCYY, where MM represents a two-digit month value from 01 to 12, DD represents a two-digit day of the month value from 01 to 31 (depending on the number of days in the month), CC represents a two-digit century, and YY represents a two-digit year. A date separator may be one of the following characters: '/', '-', or '.'.
The FairCom DB API API also converts time to string, and string to time, using the standard USA convention of HH:MM AM where HH represents the hour value from 1 to 12, MM represents the minutes value from 1 to 59, and AM represents AM or PM values.
ctdbSetDefDateType() sets a new default date format. ctdbGetDefDateType() retrieves the current default date format. The following date formats are supported:
CTDATE_MDCY |
Date format is MM/DD/CCYY where MM represents a two-digit month, DD represents a two-digit day of the month, CC represents a two-digit century, and YY represents a two-digit year. The date separator may be one of the following characters: '/', '-', or '.'. This is the default date format. Example: 12/01/2002. |
CTDATE_MDY |
Date format is MM/DD/YY where MM represents a two-digit month, DD represents a two-digit day of the month, and YY represents a two-digit year. The date separator may be one of the following characters: '/', '-', or '.'. Example: 12/01/02 |
CTDATE_DMCY |
Date format is DD/MM/CCYY where DD represents a two-digit day, MM represents a two-digit month , CC represents a two-digit century, and YY represents a two-digit year. The date separator may be one of the following characters: '/', '-', or '.'. Example: 01/12/2002. |
CTDATE_DMY |
Date format is DD/MM/YY where DD represents a two-digit day, MM represents a two-digit month, and YY represents a two-digit year. The date separator may be one of the following characters: '/', '-', or '.'. Example: 01/12/02. |
CTDATE_CYMD |
Date format is CCYYMMDD where CC is a two-digit century, YY is a two-digit date, MM is a two-digit month, and DD is a two-digit day of the month. This date format has no separators. Example: 20021201. |
CTDATE_YMD |
The date format is YYMMDD where YY represents a two-digit year, MM represents a two-digit month, and DD represents a two-digit day of the month. This date format has no separators. Example: 021201 |
ctdbSetDefTimeType() sets a new default time format. ctdbGetDefTimeType() retrieves the current default time format. The following time formats are supported:
CTTIME_HMSP |
Time format is HH:MM:SS AP where HH represents the hour with values between 1 and 12, MM represents a two-digit minute value between 00 and 59, SS represents a two-digit second value between 00 and 59 and AP is either AM or PM. The time separator may be ':' or '.'. Example: 1:35:45 AM. |
CTTIME_HMP |
Time format is HH:MM AP where HH represents the hour with values between 1 and 12, MM represents a two-digit minute value between 00 and 59 and AP is either AM or PM. The time separator may be either ':' or '.'. Example: 1:35 AM. |
CTTIME_HMS |
Time format is HH:MM:SS where HH represents an hour value between 0 and 23, MM represents a two-digit minute value between 00 and 59, and SS represents a two-digit second value between 00 and 59. The time separator may be either ':' or '.'. Example: 1:35:45 |
CTTIME_HM |
Time format is HH:MM where HH represents an hour value between 0 and 23, MM represents a two-digit minute value between 00 and 59. The time separator may be either ':' or '.'. Example: 1:35. |
CTTIME_MIL |
Time format is HHMM (military format). HH represents a two-digit hour value between 00 and 23 and MM represents a two-digit minute value between 00 and 59. This time format has no separator. Example: 0135. |
When converting floating point type fields, such as CT_SFLOAT, CT_DFLOAT and CT_EFLOAT to and from strings, FairCom DB API uses the same float conversion format used by the C standard library functions printf() and scanf(). By default the float conversion format is set to "%f". Use ctdbSetDefFloatFormat() to set a new default float conversion format. Use ctdbGetDefFloatFormat() to retrieve the current default float conversion format.
|
|
|
Every handle allocated by the FairCom DB API API has a space called user tag value reserved for holding an arbitrary user value. The user tag has no predefined meaning and is provided for the convenience of developers. It can be used for storing an additional void pointer or it can be typecast to any 32-bit value (or 64-bit value on 64-bit platforms).
Use ctdbGetUserTag() to retrieve the current user tag value associated with a handle. Use ctdbSetUserTag() to set the current user tag value associated with a handle. Both ctdbGetUserTag() and ctdbSetUserTag() accept any handle allocated by the ctdbAllocXXX() functions of the FairCom DB API API.
When a FairCom DB API handle is released by calling one of the ctdbFree ...() functions, the user tag value is not automatically released. The user is responsible for releasing any dynamic memory controlled by pointers stored in the handle user tag space.
