|
|
|
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 @.
