c-treeACE V10.0 Update Guide

EvaluateFilter

Function prototype for the filter callback function.

Declaration

NINT EvaluateFilter(pCBDLL pcbdll, FILNO datno, pVOID Recptr,
pConvMap Schema, VRLEN fixlen, VRLEN datlen);

Description

This function is defined in the ctuserx.c module used to build a filter callback function.

Where:

pcbdll is a pointer to a CBDLL structure (see definition below) that contains the callback filter state variables.
datno is the data file number by which that connection has opened the data file that is being read. 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
Recptr is the record image of the record for which the filter is being evaluated.
Schema is the record schema.
fixlen is the size of the fixed-length portion of the record.
datlen is the length of the available data. For variable length records it may be smaller than the length entire record if the buffer is smaller than the complete record length.

CBDLL Structure

typedef struct cbdll_t {

NINT cbinst; /* callback instance count */

pTEXT cbdll; /* name of callback DLL */

pTEXT cbfnc; /* name of callback function */

pTEXT cbprm; /* callback function parameters */

pVOID cbdllhnd; /* handle to callback DLL */

pCBFNC cbfncptr; /* pointer to callback function */

pCBFNCload cbload; /* ctfiltercbLoadLib ptr */

pCBFNCunload cbunload; /* ctfiltercbUnloadLib ptr */

pVOID cbfilterhandle; /* user-defined library handle */

TEXT cbfilnam[MAX_NAME]; /* data file name */

} CBDLL;

SetDataFilter() can register a data record filter callback function that resides in a DLL or shared library. Calling SetDataFilter() with a filter expression of the form:

@#mycallback.dll#mycallback_function#my_params

then libname is “mycallback.dll”, funcname is “mycallback_function”, and params is “my_params”.

You can use c-tree API functions to open other c-tree files on that FairCom Server and you can read and write the files. All operations are done in the context of the database connection in which you called the record read operation that called the filter function.

Building a Filter Callback DLL

A simple way to build a data record filter callback DLL is to use the mtmake utility to create a makefile that builds a CTUSER DLL. The CTUSER DLL exports the functions EvaluateFilter(), LoadFilter(), and UnloadFilter(). The source code for these functions is located in the file ctuserx.c.

Additional Callback Functions

In addition to the data record filter callback function, a data record filter callback DLL can optionally implement the following functions. These functions are optional and included for extended capabilities within the callback.

LoadFilter()
UnloadFilter()

Errors logged to CTSTATUS.FCS when failing to load a filter callback DLL begin with the text

"FILTER_CALLBACK_LOAD: ".

A callback DLL that is loaded by a call to SETFLTR() is unloaded when the filter is disabled, which is done either by a call to SETFLTR() to establish a different filter (or with an empty string to disable the filter), or when the file it closed.

A callback DLL can also be specified in an expression that is passed to UPDCIDX(). In that case, the DLL is loaded when the file is physically opened, and the DLL remains loaded until the file is physically closed. Note that if the expression passed to UPDCIDX() specifies the name of a filter callback DLL, then every time the data file is opened the DLL must be able to be loaded and the callback function must exist in the DLL. Otherwise the attempt to open the data file will fail with error 867 or 868.

Return Values

Value	Symbolic Constant	Description
0	NO_ERROR	No error.
867	CBKD_ERR	Failed to load the filter callback library. See CTSTATUS.FCS for details.
868	CBKF_ERR	Failed to resolve the filter callback function in the filter callback DLL. See CTSTATUS.FCS for details.

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

Example

Example Code