|
|
|
ctdbFilterRecord
Set the filtering logic for the table.
Declaration
CTDBRET ctdbFilterRecord(CTHANDLE Handle, pTEXT expr)
Description
ctdbFilterRecord() sets the filtering for a table. When set, all records retrieved from the table are filtered against the expression and only records matching this criteria will be returned. This feature is temporary and the effect is limited to the user who sets the filter. The filter is turned off when the table is closed, or when ctdbFilterRecord() is called with the record or table handle and NULL in the parameter expr. If a new expression is set to a table with a current filter, the old filter is replaced with the new one. Just one filter may be active per table per user.
When used in the client/server model, this feature has the potential to increase the performance since only records matching the criteria will be returned, reducing the network traffic.
The first time you include a "tableFilter" string in a "getRecords..." action, the server processes the string to produce an optimized filter. The server automatically reuses the optimized filter in subsequent calls to eliminate the initial processing overhead.
ctdbGetFilter() may be used to retrieve the filter and ctdbIsFilteredRecord() to verify if there is a filter in the table.
If the functionality described in the FairCom DB Conditional Expression Parser does not provide the necessary filtering logic, a user-defined expression may be used. This so-called "callback routine" is passed to the filter with an "at" sign (@) in the beginning of the expression. What follows the @ is going to be the identifier to the user to handle in the routine ctfiltercb() (located in ctclbk.c). Notice that this is considered an advanced feature because it requires editing a c-tree source file to insert the call to the user-defined routine(s).
Returns
ctdbFilterRecord() returns CTDBRET_OK on success, or the c-tree error code on failure.
See also
ctdbGetFilter(), ctdbIsFilteredRecord(), ctdbRecordSetOn()
