FairCom DB API for C

ctdbResultSetOnOff

Attaches or detaches a result set from a record handle.

Declaration

CTDBRET ctdbResultSetOnOff(CTHANDLE Handle, CTHANDLE RecordHandle,
CTBOOL OnOffFlag, CTBOOL AutoSortFlag, CTLOC_MODE LocateMode)

Parameters:

Handle [IN] - Result Set handle.
RecordHandle [IN] - Record handle.
OnOffFlag [IN] - YES, if it is turning ON; or NO, if it is turning OFF.
AutoSortFlag [IN] - YES, if FairCom DB API can choose the best index, or NO, if the current index must be kept.
LocateMode [IN] - The find modes are: CTLOC_NONE, CTLOC_CASEIN, CTLOC_PARTIAL, and CTLOC_CASEIN_PARTIAL.

Description

ctdbResultSetOnOff() attaches or detaches a given CTResultSet handle to a given record handle. It checks if the result set's table is the of the record and also checks if there isn't any existing filter applied to the record. If there is any, it is not possible to set the result set ON.

The result set handle is allocated (ctdbAllocateResultSet()) for a specific table handle, and then it is possible to add one or more criteria (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 (ctdbResultSetOnOff()) for any record handle that is allocated for the same table handle that owns the result set.

Limitations

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..

Returns

Return CTDBRET_OK on success. CTDBRET code for failure.

Example

CTHANDLE hResSet;

CTHANDLE hResSetCri;

/* 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 */

Display_Records(hRecord);

/* Release Result Set handle */

ctdbFreeResultSet( hResSet );