|
|
|
c-treeDB classes CTSession, CTDatabase, CTTable, CTRecord, CTField, CTIndex and CTSegment all inherit from a common base CTBase class.
All functionality and methods described in this chapter are availed when working with sessions, databases, tables, records, fields, indexes and index segments.
|
|
|
Most c-treeDB API functions return an error status to indicate if a particular function operation succeeded or not. Most c-treeDB API methods will also keep the last error status, if the function operation failed. The last error status can be manipulated with the following methods:
GetError() retrieves the last error status. If a function succeeds, the success status is not kept by the c-treeDB API.
SetError() sets the last error status, overwriting any previous error status kept by the c-treeDB API.
ClearError() clears the last error status.
// clear the error if error is INOT_ERR
// Recobj is a CTRecord object
if (Recobj.GetError() == INOT_ERR)
{
Recobj.ClearError();
}
|
|
|
The c-treeDB API implementation of transaction processing functions follows closely the c-tree Plus ISAM API definition. The basic difference between the c-treeDB and ISAM transaction processing API is the separation of locking mechanisms from transaction processing.
While the ISAM API also allows for locking modes to be specified when beginning a transaction, the c-treeDB API requires that locking functions be implicitly used after a transaction begins. The code fragment below shows an example using a c-tree Plus ISAM call to start 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 c-tree Plus code fragment above starts a transaction by invoking function TRANBEG. The mode ENABLE indicates that every c-tree Plus read record operation will lock the record for writing and the mode LK_BLOCK indicates that the thread will block until the lock is acquired.
When using the c-treeDB API, users must be aware that the transaction processing API will not start the record locking mechanism. The code fragment below shows the equivalent example using the c-treeDB API:
// Recobj is a CTRecord object
// start a transaction
Recobj.Begin();
// enable write locks
Recobj.Lock(CTLOCK_WRITE_BLOCK);
... perform some data operations ...
// release locks
Recobj.Unlock();
// commit the transaction
Recobj.Commit();
The Begin() method starts a new transaction, while Commit() terminates a transaction by committing any changes. Abort() terminates a transaction and aborts any changes done during the transaction.
SetSavePoint() sets a save point in the current transaction. Once a save point is set within the current transaction, RestoreSavePoint() will reverse only changes done in between the set save point and restore the save point, without terminating the transaction.
Please refer to "Data Integrity" in the c-tree Plus Programmer’s Reference Guide for a detailed description of transaction processing and locking.
|
|
|
Session wide locking is based on the principle that the Lock() method sets the current lock mode. When locks are activated, every record read from all active tables of all active databases associated with the session are automatically locked with the current lock mode.
// start locking
// ASession is a CTSession object
try
{
ASession.Lock(CTLOCK_WRITE_BLOCK);
}
catch (CTException &err)
{
printf("Session lock failed with error %d\n", err.GetErrorCode());
}
Unlock() releases all locks acquired since the last Lock() call and clears the current lock mode. IsLockActive() indicates if a session wide lock mode is set. GetLockMode() retrieves the current session wide lock mode. If no session wide locks are active, GetLockMode() returns CTLOCK_FREE.
// unlock if locks are active
// ARecord is a CTRecord object
try
{
if (ARecord.GetLockMode() != CTLOCK_FREE)
{
ARecord.Unlock();
}
}
catch (CTException &err)
{
printf("Unlock failed with code %d\n", err.GetErrorCode());
}
Please refer "Date Integrity" in c-tree Plus Programmer’s Reference Guide for a detailed description of transaction processing and locking.
|
|
|
The c-treeDB record manager performs automatic data type conversions when the user reads from, or writes to, a field using a data type that is different from the field data type. For most data types, the conversion is straightforward except when converting dates and times to and from strings, as there are many different conventions for displaying dates and times.
By default c-treeDB 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 with values from 01 to 12, DD represents a two digit day of the month with values 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 the ‘/’, ‘-’ and ‘.’ characters.
The c-treeDB API converts time to string, and string to time, using the standard USA convention of HH:MM AM where HH represents the hour with values from 1 to 12, MM represents the minutes with values from1 to 59 and AM represents AM or PM values.
Date Formats
SetDefDateFormat() sets a new default date format. GetDefDateFormat() retrieves the current default date format. The following date formats are supported:
Time Formats
SetDefTimeFormat() sets a new default time format. GetDefTimeFormat() retrieves the current default time format. The following time formats are supported:
Float Formats
When converting floating point type fields, such as CT_SFLOAT, CT_DFLOAT, and CT_EFLOAT, to and from strings, c-treeDB uses the float conversion format used by the C standard library functions printf() and scanf(). By default the float conversion format is set to "%f". Use SetDefFloatFormat() set a new default float conversion format. Use GetDefFloatFormat() to retrieve the current default float conversion format.
|
|
|
Every handle allocated by the c-treeDB 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 GetUserTag() to retrieve the current user tag value associated with a handle. Use SetUserTag() to set the current user tag value associated with a handle.
When a c-treeDB object is destroyed, 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.
