c-treeDB API API for C

Record Sets

An alternative and more efficient way to retrieve records is the use of Record Sets. A record set contains part of a table, representing a group of records that have keys that match a certain target. For example, an index contains the following keys:

CASE DISKCASE DISKDRIVE DISKETTE KEY KEYBOARD KEYCAP

When scanning through the index looking for records, record navigation functions work on the entire index file. Navigating to the first record obtains the first key in the index, CASE, and moving to the next record obtains each of the following keys in turn, on through KEYCAP.

When creating a record set using ctdbRecordSetOn(), with a target of "DISK" and a target length of 4, c-treeDB API returns only the records in which the first 4 bytes of the key start with "DISK".

The record navigation functions will operate only on the records that match the set until the record set operation is terminated with a call to ctdbRecordSetOff(). To work with multiple record sets at once, use more than one record handle.

Record sets allow a faster search for records, in particular in the client/server mode since fewer records may be retrieved and less traffic on the network will be generated. When worked in conjunction with filters (see below), record sets allow for simple queries.

To use record sets, follow the steps below:

1. Clear the record buffer
2. Set the index you want to use
3. Populate the index segments you would like to participate in the set
4. Establish the Set

Creating a record set

To create a record set, perform the following steps

1. Clear a record handle
2. Select the default index
3. Populate the field, or fields, that form the partial index
4. Call ctdbRecordSetOn() to create a record set

/* start the record set */

ctdbClearRecord(hRecord);

ctdbSetFieldAsString(hRecord, 0, "DISK");

if (ctdbRecordSetOn(hRecord, 4) != CTDBRET_OK)

printf("Starting record set failed\n");

Once the record set is created, ctdbFirstRecord(), ctdbNextRecord(), ctdbLastRecord() and ctdbPrevRecord() will return only the records that match the record set criteria.

Terminating a record set

Once the record set is no longer necessary, you can turn it off by calling ctdbRecordSetOff().

/* terminate the record set */

if (ctdbRecordSetOff(hRecord) != CTDBRET_OK)

printf("Terminating record set failed\n");

Once the record set is terminated, ctdbFirstRecord(), ctdbNextRecord(), ctdbLastRecord() and ctdbPrevRecord() will operate again will all records of a table.