Previous Topic

Next Topic

c-tree Data Record Filter Callback Dynamic Library Support

The SetDataFilter() function 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#params

causes the c-tree Server to load the DLL named mycallback.dll and to call the function mycallback_function() when reading records for the specified file.

Note: It is not valid for mycallback_function to contain a #, and params is just the remainder of the expression, so it can contain any characters.

The function prototype for the callback function is:

NINT ctfiltercbEval(pCBDLL pcbdll, COUNT datno, pVOID Recptr,
	pConvMap Schema, VRLEN fixlen, VRLEN datlen);

Where:

  • pcbdll pointer to a CBDLL structure (see definition below) that contains the callback filter state variables.
  • datno data file number by which that connection has opened the data file that is being read.
  • Recptr the record image of the record for which the filter is being evaluated.
  • Schema the record schema.
  • fixlen the size of the fixed-length portion of the record.
  • datlen the full size of the record.

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        cblibhandle;  /* user-defined library handle   */
} CBDLL;

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() shared object (.dll, .so, or .dylib). The CTUSER() shared object exports the functions ctfiltercbEval(), ctfiltercbLoadLib(), and ctfiltercbUnloadLib(). The c-treeACE SDK source code to these functions is contained in the file ctuserx.c.

Calling c-tree API functions From a Filter Callback Function

A data record filter callback shared object can call c-tree API functions by including the header file ctreep.h, using the c-treeACE Server ctoptn.h file, and linking with the import library for ctreedbs.dll (or libctreedbs.so, .sl or .dylib) For example, a filter callback function could call the c-tree resource API calls to read resources such as the DODA.

Note that any c-tree functions you call are executed in the context of the database connection in which you called the record read operation that called the filter function, thus there could be potential limits on what operations may be expected.

If you allocate resources and want multiple threads to share these resources then you will need to remain cognizant of reentrant threading issues. As part of the c-tree API are thread synchronization primitives such as ctThrdMutexGet() that can be used for this purpose.

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.