Product Documentation

c-treeDB API for C++ - Developers Guide

Previous Topic

Next Topic

Conditional Expression Callback Function

FairCom DB provides a developer-defined callback function to perform additional advanced custom data filtering and conditional index evaluation. Instead of calling c-tree’s internal expression evaluator to analyze criteria, a user-defined function is called, allowing advanced filtering and control with application specific code.

Callback Functions

The module ctclbk.c contains the routines declared below. ctfiltercb() is called when a user-defined filter must be evaluated. Whenever a file open retrieves stored conditional index callback expressions, when a conditional index callback expression is created, or when a SetDataFilter() callback expression is created, the ctfiltercb_init() routine is called with a pointer to the callback expression. Whenever a file is closed, or a SetDataFilter() is cleared, the ctfiltercb_uninit() routine is called for each callback expression.

NINT ctfiltercb_init(pTEXT Clbk pinHan)

NINT ctfiltercb(pTEXT Clbk, pVOID Recptr, pConvMap Schema,

VRLEN fixlen, VRLEN datlen pinHan)

NINT ctfiltercb_uninit(pTEXT Clbk pinHan)
 

Parameter

Description

pTEXT Clbk

Pointer to a NULL terminated ASCII string beginning with the ctCNDXclbkCHR (@) character. Presumably, the string starting in the 2nd position (i.e., Cblk + 1) points to a callback function designator.

pVOID Recptr

Pointer to a record image

pConvMap Schema

Pointer to a record schema

VRLEN fixlen

Fixed length of the record image

VRLEN datlen

Full length of the record image

pinHan

A macro the converts to ctWNGV for standalone or client libraries defining ctNOGLOBALS or lctgv for Server or Bound Server code.

ctfiltercb_init() is expected to return zero (0) on error and non-zero on initialization, though at this point the error return is ignored. ctfiltercb_init() should set a state variable so the ctfiltercb_uninit() knows whether the init was called for this particular callback filter.

ctfiltercb_uninit() is expected to return zero (0) on error and non-zero on uninitialization, though at this point the error return is ignored. ctfiltercb_uninit() should check a state variable to determine whether or not ctfiltercb_init() was called for this particular callback filter.

Stub functions with simple debug print statements are part of the base distribution. A developer taking advantage of expression callback routines must adapt these callback functions to their particular requirements.

Callback Expression String

As described above, Clbk points to an ASCII string beginning with the "at" sign ‘@’. The string following ‘@’ is completely arbitrary, and is interpreted to determine what type of callback routine is intended, assuming more than one type of callback is required by the application. A simple scheme would use callback strings with a unique character in the second position (following ‘@’). This permits a simple switch statement routing callbacks to desired code, as shown in the following pseudo-code:

/*

** my callback strings are: @CustomerNumber

** @ZeroBalance

** @TotalFunds

*/

switch (*(Clbk + 1)) {

case 'C':

do the Customer Number check

break;

case 'Z':

do the Zero Balance check

break;

case 'T':

do the Total Funds check

break;

default:

set the return code to -CVAL_ERR to indicate the

filter could not be evaluated

break;

}

In this example scheme, the only significant portion of the callback designator is the first character after the @.

TOCIndex