FairCom ISAM for C

SetDataFilter

Specify a data filter for a given data file.

Short Name

SETFLTR()

Type

Low-Level Data Manipulation

Declaration

COUNT SetDataFilter(FILNO datno, pTEXT condexpr)

Description

In V12 the file number typedef was formally changed from COUNT, a two-byte value to FILNO, a four-byte value. Refer to this link for compatibility details. Four Byte File Numbering

SetDataFilter() specifies that the data filter condexpr should be used for reads from data file datno until a new filter is set or the file is closed. To “turn off” a filter without closing the file, simply call SetDataFilter() with an empty string ("") for the conditional expression.

A Low-Level data record read returns FFLT_ERR (739) if the data record exists but does not satisfy the filter. ISAM level record requests, including sets and batches, skip over records failing the filter transparently to the user. In client/server, this may substantially reduce network traffic.

For partitioned files, call SetDataFilter() for the host data file and the filter automatically applies to each partition member file.

The condexpr string is similar to those used for conditional index support: it may be a logical expression involving field names from the record schema or a callback designator (e.g., “@mycallback”). See FairCom DB EXPRESSION PARSER AND GRAMMAR.

Row Level Permanent Callback Filters

Introduction

The c-tree API function SetDataFilter() can be used to establish a temporary, user-specific, filter for data record access (please see the section “Data Filters and Conditional Indexes” in the c-tree Plus Programmer’s Reference Guide). SetDataFilter() now supports establishing a new type of permanent system-wide filter.

Consider the case of requiring a customized security audit trail. Individual record reads and writes can be monitored and logged with these permanent filters in place. An application could also use this feature to restrict a user’s ability to read and/or write records based on the row from the table of interest. thereby enabling a row level security mechanism. The username, table, and operation attempted, including the record image, are all data available to your application.

System Level Callback Functions

If the conditional expression in the call to SetDataFilter() begins with either “@@?” or “@@!” then a permanent, system-wide (i.e., applies to all users) read or write filter, respectively, will be added to the file. Calling SetDataFilter() with a conditional expression that exactly matches “@@?” or “@@!” will cause the permanent read or write filter, respectively, to be deleted from the file.

To add or delete one of these filters, the file must be opened exclusively, and the calling user must have file definition permissions.

These filters are call-back filters. This is ensured with the leading ‘@’ character. A file may have at most one read and one write permanent filter.

ctfiltercb_rowl() is a new callback function located in module ctclbk.c where the actual callback evaluation takes place.

Two existing callback functions are also called during filter initialization and de-initialization:

ctfiltercb_init() - called each time a new filter is established or when a table with a permanent system wide filter is opened.
ctfiltercb_uninit() - called each time a new filter is deleted, or when a table with a permanent system wide filter is closed.

c-tree stores these callback expressions in a c-tree file resource. It is important that the developer take care to restrict the ability to delete or otherwise modify these important file resources. Please see the features available regarding File Definition Resource (FCRES) Security in FILEDEF_SECURITY_LEVEL in the FairCom DB Administrator's Guide.

Return

Value	Symbolic Constant	Explanation
0	NO_ERROR	Filter applied.
48	FMOD_ERR	Must be called for a data file.
596	CMIS_ERR	No record schema defined for datno.
597	CINI_ERR	Could not parse conditional expression.
598	CVAL_ERR	Insufficient data: Condition outside of read data portion.
739	FFLT_ERR	Low-Level: Data record exists but does not satisfy filter.

See c-tree Error Codes for a complete listing of valid c-tree error values.