c-treeDB API for C++ - Developers Guide

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, suppose 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 a record set function, with a target of "DISK" and a target length of 4, c-treeDB 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 a record set function. To work with multiple record sets at once, use more than one record handle.

Record sets allow a faster search for records, particularly in client/server mode since fewer records may be retrieved and less traffic on the network will be generated. When used in conjunction with filters (see below), one can create 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

In This Section Creating a record set Terminating a record 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 CTRecord::RecordSetOn() to create a record set

// create a new record object

CTRecord ARecord(ATable);

// clear the record buffer

ARecord.Clear();

// populate the fields

ARecord.SetFieldAsString(0, "DISK");

// create the record set

try

{

ARecord.RecordSetOn(4);

}

catch (CTException &err)

{

printf("Record set on failed with error %d\n", err.GetErrorCode());

}

Once the record set is created, CTRecord::First(), CTRecord::Next(), CTRecord::Last() and CTRecord::Prev() 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 CTRecord::RecordSetOff().

// terminate the record set

try

{

ARecord.RecordSetOff();

}

catch (CTException &err)

{

printf("Record set off failed with error %d\n", err.GetErrorCode());

}

Once the record set is terminated, CTRecord::First(), CTRecord::Next(), CTRecord::Last() and CTRecord::Prev() will return all records of a table.