Product Documentation

VCL/CLX Developers Guide

Previous Topic

Next Topic

Methods

Create

constructor Create(AOwner : TComponent);

The constructor for the TCtTable component.

Destroy

destructor Destroy();

The destructor for the TCtTable component. Do not call Destroy directly. The object has to be destroyed with the inherited (TObject) Free() method.

AbortTransaction

procedure AbortTransaction();

Abort the current transaction.

AddField

function AddField(FieldName : String; FieldType : CTDBTYPE; FieldLength : Integer) : TCtField;

Add a new field to a table. The field is added to the end of the table. Available field types are described in “c-treeVCL/CLX Definitions”.

AddIndex

function AddIndex(IndexName : String; KeyType : CTDBKEY; AllowDuplicates : Boolean; NulFlag : Boolean) : TCtIndex;

Add a new index to the table.

AddSegment

function AddSegment(IndexName : String; Field : String; Mode : CTSEG_MODE) : TCtSegment;

function AddSegment(Index : Integer; Field : String; Mode : CTSEG_MODE) : TCtSegment;

Add index segment. An index is composed by one or more segments. Available segment modes are described in “TCtTable Component”.

AddTable

procedure AddTable();

Add an existing table to the database.

AlterTable

procedure AlterTable();

procedure AlterTable(Action : Integer);

Commit table field, index, or index segment changes. This function should only be used to modify an existing table. If the overloaded procedure with the parameter Action is used, Action may have three values:

  • CTDB_ALTER_NORMAL (= 0), to check for changes before altering;
  • CTDB_ALTER_INDEX (= 1), to force rebuild of all indexes;
  • CTDB_ALTER_FULL (= 3), to force full table rebuild.

If no parameter is used, CTDB_ALTER_NORMAL is the default, resulting in checking before altering the table.

BeginTransaction

procedure BeginTransation();

Start a new transaction.

ClearError

procedure ClearError();

Clear the error code.

CommitTransaction

procedure CommitTransaction();

Commit the current transaction.

CreateTable

procedure CreateTable();

Create a new table. Before creating the table, its fields and indexes (if any) must be defined, and the Directory(), Password(), CreateMode(), and GroupID() properties should be set

DeleteField

procedure DeleteField(FieldName : String);

Delete a table field. If the table was already created and the field deletion is supposed to be posted to the table, use AlterTable().

DeleteIndex

procedure DeleteIndex(IndexName : String);

procedure DeleteIndex(IndexNumber : Integer);

Delete index from table. If the table was already created and the index deletion is supposed to be posted to the table, use AlterTable().

DeleteSegment

procedure DeleteSegment(IndexName : String; Segment : Integer);

procedure DeleteSegment(Index : Integer; Segment : Integer);

Delete an index segment. If the table was already created and the segment deletion is supposed to be posted to the table, use AlterTable().

DeleteTable

procedure DeleteTable();

Drop a table from a database and delete the table data and index files. To avoid an unintentional table delete, set the table Password() property.

DropTable

procedure DropTable();

Drop a table from a database. Only the entry for the table in the database dictionary is removed. The table and index files are not deleted or removed.

GetField

function GetField(Index : Integer) : TCtField;

function GetField(Name : String) : TCtField;

Retrieve a field object.

GetIndex

function GetIndex(Name : String) : TCtIndex;

function GetIndex(Index : Integer) : TCtIndex;

Retrieve an index object.

GetLockMode

function GetLockMode() : TCtLockMode;

Retrieve the current lock mode.

GetSegment

function GetSegment(IndexNumber : SegmentNumber : Integer) : TCtSegment;

function GetSegment(IndexName : String; SegmentNumber : Integer) : TCtSegment;

Retrieve an index segment object from table.

InsertField

function InsertField(BeforeField : String; FieldName : String; FieldType : CTDBTYPE; FieldLength : Integer) : TCtField;

Insert a new field into a table. Inserted fields may be placed anywhere in the table.

InsertSegment

function InsertSegment(IndexName : String; BeforeSegment : Integer; Field : String; Mode : CTSEG_MODE) : TCtSegment;

function InsertSegment(Index : Integer; BeforeSegment : Integer; Field : String; Mode : CTSEG_MODE) : TCtSegment;

Insert a new segment into a table.

IsLockActive

function IsLockActive() : Boolean;

Verify the lock state, returning true if session wide locks are enabled.

IsTransActive

function IsTransActive() : Boolean;

Verify the transaction state, if active or not. A transaction is activated by a call to BeginTransaction(), and deactivated with a call to CommitTransaction or AbortTransaction().

Lock

procedure Lock(LockMode : CTLOCK_MODE);

Enable session lock. After a call to Lock, every record visited by Find(), First(), Last(), Next(), Prev() and Seek() will be locked. The valid lock modes are given in “c-treeVCL/CLX Definitions”.

Note: At the moment Lock is called, no file or record is locked. Instead, a flag is set internally to indicate that all new record reads will lock the records, with the given lock mode.

A READ lock on a record allows an unlimited number of READ locks on that record, but prevents WRITE locks. A WRITE lock prevents any other locks on that record.

Call Unlock or Lock with mode set to CTLOCK_FREE, to free all session locks. Notice that, if called inside a transaction, this free operation will result in the suspension of the locks, and not in their release. The locks will only be released when the transaction is finished with a call to CommitTransaction() or AbortTransaction(). If the locks are suspended, it means that new records read won't be locked. To restore the suspended locks, use Lock with one of the READ or WRITE lock modes (or the RESTORE options). If, for any special reason, the unused locks from a particular table must be released inside a transaction, the TCtTable procedure UnlockTable() may be used. Unused locks are records that where locked but not updated/deleted/added.

Note: Mixing LockRecord() and Lock 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. In the example above, a locked record can't be re-locked.

Notification

procedure Notification(AComponent : TComponent; Operation: TOperation);

Overload the default notification event handler.

ResetAll

procedure ResetAll();

Reset all record buffers associated with the table.

RestoreSavePoint

procedure RestoreSavePoint(ASavePoint : TCtSavePoint);

Restore a transaction save point, given by ASavePoint(). If ASavePoint() is 0, the last save point is returned. If -1, the previous and so on.

SetSavePoint

function SetSavePoint() : TCtSavePoint;

Establish a transaction save point. The return of the function is the save point number that can be used to restore the save point.

Unlock

procedure Unlock();

Release all locks acquired by Lock.

Notice that, if called inside a transaction, this free operation will result in the suspension of the locks, and not in their release. The locks will only be released when the transaction is finished with a call to CommitTransaction() or AbortTransaction(). If the locks are suspended, it means that new records read won't be locked. To restore the suspended locks, use Lock() with one of the READ or WRITE lock modes (or the RESTORE options). If, for any special reason, the unused locks from a particular table must be released inside a transaction, the TCtTable procedure UnlockTable() may be used. Unused locks are records that where locked but not updated/deleted/added.

UnlockTable

procedure UnlockTable();

Unlock all locked records in a table. It doesn't matter if the lock is a session lock obtained with the TCtSession Lock function, or a record lock obtained with the TCtRecord LockRecord() function.

If UnlockTable() is used inside a transaction, the lock mode is changed to CTLOCK_SUSPEND, and new locks aren't acquired until a new call to Lock or to LockRecord() restore the locks. All unused locks from this particular table are released. Unused locks are records that where locked but not updated/deleted/added.

UpdateCreateMode

procedure UpdateCreateMode(mode : CTCREATE_MODE);

UpdateCreateMode() changes critical file mode attributes such as the level of transaction control. No check is done to determine if the mode change will damage data. No check is done to assure the new mode is valid. Use this method with caution as data may be lost. For instance, changing a data file from transaction processing to no transaction processing makes automatic recovery unavailable.

mode represents the new table create mode, and the possible values are described in “c-treeVCL/CLX Definitions”.

TOCIndex