Product Documentation

c-treeDB API API for C

Previous Topic

Next Topic


Enable a new record set. The target key is built from the contents of the record buffer.


CTDBRET ctdbRecordSetOn(CTHANDLE Handle, NINT siglen)


ctdbRecordSetOn() enables a new record set. The target key is built from the contents of the record buffer.

  • Handle [in] the record handle.
  • siglen [in] the number of key bytes to be used by the set.

When record set is enabled, the record operations will be substituted by the set operations. This means that, when record set is enabled, operations like ctdbFirstRecord() will search for the first record in the set instead of the first record in the entire table.

Just one record set can be enabled for each record handle. If it is necessary to have more than one record set enabled at the same time, more than one record handle will be required. To disable and free an existing record set, use ctdbRecordSetOff().

If used in conjunction with filters (ctdbFilterRecord()), may behave as a simple query.


ctdbRecordSetOn() returns CTDBRET_OK if successful, or the c-tree error code on failure. The possible errors associated with ctdbRecordSetOn() are:

  • CTDBRET_NOTRECORD (4024): Invalid record handle
  • CTDBRET_NOTACTIVE (4012): Table is not active
  • CTDBRET_NOINDEX (4048): No index in the active table
  • CTDBRET_NOMEMORY (4001): No memory to allocate the key


/* display all records in set - no error checking */

void DisplayAll(CTHANDLE pRec)


NINT count = 0;


ctdbSetDefaultIndexByName(pRec, "index_name");

ctdbSetFieldAsString(pRec, 0, "silva");

ctdbRecordSetOn(pRec, 5);

if (ctdbFirstRecord(pRec) == CTDBRET_OK)







while (ctdbNextRecord(pRec) == CTDBRET_OK);


printf("%d records in set\n", count);


See also

ctdbAllocRecord(), ctdbRecordSetOff(), ctdbFilterRecord()