|
|
|
A record handle is required before any record operations can take place. A record handle is instantiated with ctdbAllocRecord() and freed with ctdbFreeRecord().
When allocating a record handle you need to provide a properly-allocated table handle. The table associated with the record handle must be opened before any record operations can take place.
/* allocate a record handle */
CTHANDLE hRecord = ctdbAllocRecord(hTable);
if (!hRecord)
printf("Record allocation failed\n");
|
|
|
Every time a record handle is allocated with ctdbAllocRecord(), the record buffer acquires its own context, which means that each record buffer operates independently. Record operations that move the current record position of one record buffer will not interfere with any others.
There are situations where it may be necessary to have several different record buffers sharing the same record context. In this case the developer can allocate the first record buffer using ctdbAllocRecord() to acquire a new context. Calling ctdbDuplicateRecord() can then duplicate the initial record. The duplicated records will share the same context of the original record buffer, but the duplicated record handle will not share the same memory buffer for holding the record data.
/* Create two records sharing the same context */
CTHANDLE hRecord1 = ctdbAllocRecord(hTable);
CTHANDLE hRecord2 = NULL;
if (hRecord1) {
hRecord2 = ctdbDuplicateRecord(hRecord1);
if (!hRecord2)
printf("Duplicate record failed\n");
}
|
|
|
Based on the fields added by the user, FairCom DB API will organize the record buffer as follows:
$DELFLD$ |
$NULFLD$ |
$ROWID$ |
field 0 |
field 1 |
... |
field n |
The user fields are stored in the table record in the same order in which they were added.. To initiate the operation on the records, a record handle must be declared and instantiated. Once the table associated with the record handle is opened, the record handle can be used to store the information that come from or go to the fields in the table.
|
|
|
A record handle may be reset to its initial state, i.e. to the same state it had just after being allocated, by calling ctdbResetRecord(), which performs the following actions on a record handle:
/* reset a record */
if (ctdbResetRecord(hRecord) != CTDBRET_OK)
printf("Reset record failed\n");
All records associated with a table can be reset in one ctdbResetAll() call.
/* reset all records */
if (ctdbResetAll(hTable) != CTDBRET_OK)
printf("Reset all records failed\n");
When a table is closed, all records associated with that table are automatically reset by ctdbCloseTable().
|
|
|
When a record handle is no longer needed, release it with ctdbFreeRecord(), which releases any context associated with the record, turns off record sets, and releases all resources associated with the record handle. The released record handle is automatically removed from the associated table's list of active record handles.
/* release the record handle */
ctdbFreeRecord(hRecord);
