FairCom DB API for C

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:

Permanent Filter Symbolic Constant	Explanation
CTSYSFILTER_READ	Indicates you are setting a system-wide read record filter.
CTSYSFILTER_WRITE	Indicates you are setting a system-wide write record filter.
CTSYSFILTER_READ \| CTSYSFILTER_WRITE	Indicates you are setting both a system-wide read record filter and a system-wide write record filter.

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:

FILEDEF_SECURITY_LEVEL	Explanation
LOW	Lowest security setting. There is no protection as any user may add or delete data file definition resources. This setting may be used to keep the c-tree Server data compatible with legacy applications.
MEDIUM	Default security setting. Any user may add or delete data file definition resources, but the file must be opened exclusive. This default setting may be enough to keep the c-tree Server data compatible with most legacy applications.
HIGH	Highest security setting. A user must have file definition permission before a definition resource is added or deleted. The file must be opened exclusive. This setting is appropriate for applications that require the highest level of security and may cause compatibility problems with existing legacy applications.

RETURN

Value	Symbolic Constant	Explanation
0	CTDBRET_OK	No error occurred.

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");