Product Documentation

c-treeDB API API for C

Previous Topic

Next Topic



CTHANDLE ctdbAllocateResultSet(CTHANDLE Handle, pTEXT ResSetName);


  • Handle [IN] - Table handle
  • ResSetName [IN] - Result Set name


Allocates a result set for a specific table handle. It is also added to the table result set list for later searching.

After allocating, it is then possible to add one or more criteria using ctdbAddCriteria(). The criteria have a field to be checked against the table handle that owns the result set, one or two values (depending on the comparison operator) and the operator to be used. The operator can be on of: CTIX_EQ, CTIX_NE, CTIX_GT, CTIX_GE, CTIX_LE, CTIX_LT, CTIX_BET, CTIX_BET_IE, CTIX_BET_EI, CTIX_BET_EE or CTIX_NOTBET. When the result set has all the criteria added, it can be turned on or off with ctdbResultSetOnOff() for any record handle that is allocated for the same table handle that owns the result set.


  • A result set can't be turned on for a record that is already filtered. And when a record has a result set turned on, it is not possible to add any other filter. This limitation may be relaxed in the future.
  • When a result set is changed (ctdbAddCriteria(), ctdbRemoveCriteria() and ctdbUpdateCriteria()), it must be re-applied to the record handle (ctdbResultSetOnOff()) to have these changed take effect.


Return a CTResultSet handle on success, or NULL on error.




/* Allocate a Result Set for Table */

if (!(hResSet = ctdbAllocateResultSet( hTable, "resSet1" )))

Handle_Error("Test_ResultSet1(); ctdbAllocateResultSet()");

/* Add a new criteria for the Result Set just allocated */

if (!(hResSetCri = ctdbAddCriteria( hResSet, hField0, "1002", NULL, CTIX_EQ )))

Handle_Error("Test_ResultSet1(); ctdbAddCriteria()");

/* Turn on the Result Set for the current record handle */

if (ctdbResultSetOnOff( hResSet, hRecord, YES, YES, CTLOC_NONE ) != CTDBRET_OK)

Handle_Error("Test_ResultSet1(); ctdbResultSetOnOff()");

/* Display records on the Result Set */


/* Release Result Set handle */

ctdbFreeResultSet( hResSet );

See also