c-treeDB API for C++ - Developers Guide

Finding records

You can search for records in a table using one of the CTRecord::Find(), CTRecord::FindTarget() and CTRecord::FindRowid() methods. c-treeDB performs the find operations against the table indexes. When an index entry is found, the record data is loaded into the record buffer.

Before you can call CTRecord::Find(), you need to prepare the data you want to find:

1. Clear a record buffer
2. Set the default index with the appropriate value
3. Populate the fields that makeup the index segment
4. Call CTRecord::Find() with the appropriate find mode

// find record which product code is DISKETTE

CTRecord ARecord(ATable);

// clear the record buffer

ARecord.Clear();

// set the default index to "MyIndex"

ARecord.SetDefaultIndex("MyIndex");

// populate the 'product' field

ARecord.SetFieldAsString("product", "DISKETTE");

// find the record

try

{

if (ARecord.Find(CTFIND_EQ))

printf("Record found\n");

else

printf("Record not found\n");

}

catch (CTException &err)

{

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

}

CTRecord::Find(), CTRecord::FindTarget() and CTRecord::FindRowid() returns YES (true) if the record was found or NO (false) if the record was not found. These methods throw an exception if an error occurs.

In This Section Find Modes Building a target key Finding records by target key Finding records by ROWID

Find Modes

Use the following find modes with the record find methods:

c-treeDB Find mode	c-treeDB .NET Find Mode	Explanation
CTFIND_EQ	EQ	Find a record equal to the target
CTFIND_LT	LT	Find a record less than target
CTFIND_LE	LE	Find a record less or equal than target
CTFIND_GT	GT	Find a record greater than target
CTFIND_GE	GE	Find a record greater or equal than target

Note: The Find Mode CTFIND_EQ requires that the target contains values for all segments that compose the index and the index cannot allow duplicates.

Note: c-treeDB .NET defines this mode with the FIND_MODE enum.

Building a target key

A target key can be built using most of the steps used to find a record using CTRecord::FindTarget() method. To build a target key you must:

1. Clear a record buffer
2. Set the default index with the appropriate value
3. Populate the fields that makeup the index segment
4. Call CTRecord::BuildTargetKey() with the appropriate find mode and the buffer to receive the target key

// build a target key

CTRecord ARecord(ATable);

TEXT key[256];

VRLEN keylen = sizeof(key);

// clear the record buffer

ARecord.Clear();

// set the default index to index 0

ARecord.SetDefaultIndex(0);

// populate the 'product' field

ARecord.SetFieldAsString("product", "DISKETTE");

// build the target key

try

{

ARecord.BuildTargetKey(CTFIND_EQ, key, &keylen);

}

catch (CTException &err)

{

printf("Build target key failed with error %d\n", err.GetErrorCode());

}

Finding records by target key

A record can also be found by passing a target key already built by calling CTRecord::FindTarget() method. CTRecord::FindTarget() takes as its parameters a pointer to a target key and the find mode.

// find record with a target key

CTRecord ARecord(ATable);

TEXT key[256];

VRLEN keylen = sizeof(key);

// clear the record buffer

ARecord.Clear();

// set the default index to index 0

ARecord.SetDefaultIndex(0);

// populate the 'product' field

ARecord.SetFieldAsString("product", "DISKETTE");

// build the target key

ARecord.BuildTargetKey(CTFIND_EQ, key, &keylen);

try

{

if (ARecord.FindTarget(key, CTFIND_EQ))

printf("Record found\n");

else

printf("Record not found\n");

}

catch (CTException &err)

{

printf("Find target failed with error %d\n", err.GetErrorCode());

}

Finding records by ROWID

A record can be quickly located if the ROWID for that record is known by calling CTRecord::FindRowid(). CTRecord::FindRowid() take as its parameters the ROWID value and the find mode.

// find record with rowid of 1000

CTRecord ARecord(ATable);

try

{
if (ARecord.FindRowid(1000, CTFIND_EQ))

printf("Record found\n");

else

printf("No record found\n");

}

catch (CTException &err)

{

printf("Find Rowid failed with error %d\n", err.GetErrorCode());

}