Filters

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.

• Handle [in] the table or record handle.
• expr [in] the filtering expression. The valid expressions are described in the section titled FairCom DB Conditional Expression Parser.

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()

ctdbGetFilter

Retrieve the filter from the table.

Declaration

pTEXT ctdbGetFilter(CTHANDLE Handle)

Description

ctdbGetFilter() retrieves the current filter expression for the table.

To insert a filter, use ctdbFilterRecord(). To verify if there is a filter active in the table, use ctdbIsFilteredRecord().

• Handle [in] the Table or record handle.

Returns

ctdbGetFilter() returns a pointer to a string with the filter expression. If no filters are active, return NULL.

Example

/* print the expression */

if (ctdbGetFilterType(hRecord) == CTFILTER_TEXT)

printf("Filter expression: %s\n", ctdbGetFilter(hRecord));

See also

ctdbFilterRecord(), ctdbIsFilteredRecord()

ctdbIsFilteredRecord

Indicate if the record is being filtered or not.

Declaration

CTBOOL ctdbIsFilteredRecord(CTHANDLE Handle)

Description

ctdbIsFilteredRecord() indicates if the records are being filtered or not. To insert filtering logic to the record retrieval, use ctdbFilterRecord().

• Handle [in] the Record or Table Handle.

Returns

ctdbIsFilteredRecord() returns YES if the record has been filtered, and NO otherwise.

Example

/* if record filter is active, turn it off */

if (ctdbIsFilteredRecord(hRecord))

ctdbSetFilter(hRecord, NULL, CTFILTER_NONE);

See also

ctdbFilterRecord(), ctdbGetFilter(), ctdbGetFilterType(), ctdbIsFilteredRecord(), ctdbSetFilter()

ctdbSystemFilterOff

Deletes a permanent system-wide record filter.

DECLARATION

CTDBRET ctdbDECL ctdbSystemFilterOff(CTHANDLE Handle, CTSYSFILTER mode);

DESCRIPTION

Deletes a permanent system-wide record filter. The table must be opened exclusive and the user must have file definition permission for the table. Handle is a table handle or any FairCom DB API handle that can produce a table handle, such as a record, field, index or segment handle.

For the parameter mode you must specify one of the following:

RETURN

See Appendix A for a complete listing of valid c-tree Plus error values.

EXAMPLE

/* delete a system wide filter */

if (ctdbSystemFilterOff(hTable, CTSYSFILTER_READ | CTSYSFILTER_WRITE)) != CTDBRET_OK)

printf("ctdbSystemFilterOff failed\n");

SEE ALSO

ctdbSystemFilterOn()

ctdbSystemFilterOn

Establishes a permanent system-wide data record filter.

DECLARATION

CTDBRET ctdbDECL ctdbSystemFilterOn(CTHANDLE Handle, CTSYSFILTER mode);

DESCRIPTION

Establishes a permanent system-wide data record filter, that is, the filter applies to all users, read and/or write record filter. Depending on the server file security setting, the table must be opened exclusive and the user must have file definition permission for the table. A table may have at most one read and one write system wide filter. A write filter will be called when data records are added, updated or deleted. Once a read or a write filter is established, it can only be deleted by calling the function ctdbSystemFilterOff().

Handle is a table handle or any FairCom DB API handle that can produce a table handle, such as a record, field, index or segment handle. For the mode parameter, you must specify one of the following:

System-wide filters must be callback filters. The actual callback evaluation takes place in a new callback function ctfiltercb_rowl() located in module ctclbk.c.

There different levels of security settings when users modify data file definition resources such as IFIL and DODA. The c-tree Server can be configured for three different levels of data file resource security:

RETURN

See Appendix A for a complete listing of valid c-tree Plus error values.

EXAMPLE

/* establish a new system wide filter */

if (ctdbSystemFilterOn(hTable, CTSYSFILTER_READ | CTSYSFILTER_WRITE)) != CTDBRET_OK)

printf("ctdbSystemFilterOn failed\n");

SEE ALSO

ctdbSystemFilterOff()