c-treeDB API API for C

Finding records

You can search for records in a table using one of the ctdbFindRecord(), ctdbFindTarget() and ctdbFindRowid() functions. c-treeDB API performs the find operations against the table indexes, when an index entry is found, the record data is loaded from disk into the record handle's record buffer.

Before you can call ctdbFindRecord(), 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 make up the index segment.
4. Call ctdbFindRecord() with the appropriate find mode.

/* find record which product code is DISKETTE */

CTHANDLE hRecord = ctdbAllocRecord(hTable);

/* clear the record buffer */

ctdbClearRecord(hRecord);

/* set the default index to index 0 */

ctdbSetDefaultIndex(hRecord, 0);

/* populate the 'product' field (field 1)*/

ctdbSetFieldAsString(hRecord, 1, "DISKETTE");

/* find the record */

if (ctdbFindRecord(hRecord, CTFIND_EQ) != CTDBRET_OK)

printf("Record not found\n");

ctdbFindRecord(), ctdbFindTarget() and ctdbFindRowid() return CTDBRET_OK if a record is found or INOT_ERR (101) if no record is found. Any other return value indicates an error condition.

Find Modes

Use the following find modes with the record find methods:

c-treeDB API Find mode	c-treeDB API .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 API .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 ctdbFindRecord(). 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 ctdbBuildTargetKey() with the appropriate find mode and the buffer to receive the target key

/* build a target key */

CTHANDLE hRecord = ctdbAllocRecord(hTable);

TEXT key[256];

VRLEN keylen = sizeof(key);

/* clear the record buffer */

ctdbClearRecord(hRecord);

/* set the default index to index 0 */

ctdbSetDefaultIndex(hRecord, 0);

/* populate the 'product' field (field 1)*/

ctdbSetFieldAsString(hRecord, 1, "DISKETTE");

/* build the target key */

if (ctdbBuildTargetKey(hRecord, CTFIND_EQ, key, &keylen) != CTDBRET_OK)

printf("Record not found\n");

Finding records by target key

A record can also be found by passing a target key already built by calling ctdbFindTargetKey(). ctdbFindTargetKey() takes as parameters the record handle, a pointer to a target key, and the find mode.

/* find record with a target key */

if (ctdbFindTargetKey(hRecord, key, CTFIND_EQ) != CTDBRET_OK)

printf("Record not found\n");

Finding records by ROWID

A record can be quickly located if the ROWID for that record is known by calling ctdbFindRowid(). ctdbFindRowid() takes as parameters the record handle, the ROWID value and the find mode.

/* find record with rowid of 1000 */

if (ctdbFindRowid(hRecord, (CTROWID)1000, CTFIND_EQ) != CTDBRET_OK)

printf("Record not found\n");