FairCom — Conditional Expression Function Reference

cndxeval

Evaluates an expression tree produced by cndxeval().

Declaration

COUNT cndxeval( PTREE Tree, pVOID Recptr, pConvMap Schema, VRLEN fixlen, VRLEN datlen )

Description

Where:

Tree - parse tree generated by cndxparse()
Recptr - pointer to a record handle
Schema - record schema
fixlen - Fixed record length
datlen - total record length

Evaluating your expression involves three steps:

Allocate a run-time stack for the expression analyzer (first time only).
Set up a buffer containing the field data used in the expression.
Evaluate the expression.

If you wish, you can repeat steps b) and c) multiple times. Sample code to perform these steps is shown below. It is assumed the Get_Buffer() routine allocates a record buffer and initializes it with data conforming to the field definitions specified in the DODA.

Return Values

Value	Symbolic Constant	Explanation
1	YES	Expression evaluated as true
0	NO	Expression evaluated as false

Example

COUNT retcidx;  /* Result of expression evaluation. */
pTEXT recbuf;   /* Record buffer. */

/* Allocate a run-time stack for the expression analyzer (first time only). */
if (!ctcidxStk)  {
    ctcidxStk = (pVOID) getcndxmem(CNDX_MAX_STACK * ctSIZE(PLEAF));
    if (!ctcidxStk)  {
        printf("Unable to allocate memory for run-time stack.\n");
        ctrt_exit(1);
    }
}

/* Set up a buffer containing the field data used in the expression. */
Get_Buffer(&recbuf);

/* Evaluate the expression. */
retcidx = cndxeval(ptree, recbuf, (pConvMap)schema);
if (retcidx < 0)
    printf("The expression cannot be evaluated for this record
           - error %d.\n", uerr_cod);
else if (retcidx)
    printf("The expression evaluates to TRUE for this record.\n");
else
    printf("The expression evaluates to FALSE for this record.\n");

See also

cndxfree, cndxparse, ctparsedoda, cndxrun, getcndxmem, putcndxmem

cndxfree

Frees an expression tree generated by cndxparse().

Declaration

cndxfree ( PTREE Tree );

Description

cndxfree() releases en entire PTREE structure.

Return Values

Value	Symbolic Constant	Explanation
0	CTDBRET_OK	Successful operation.

See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

PTREE ptree;   /* Expression tree.    */
....

ptree = cndxparse(schema, names, expr, strlen(expr));
if (!ptree)
    printf("Error: Unable to parse expression.\n");
else
    printf("Successfully parsed expression.\n");
....

if ( ptree )
	cndxfree (ptree);

See also

cndxeval, cndxparse, ctparsedoda, cndxrun, getcndxmem, putcndxmem

cndxparse

Creates an expression tree for later evaluation.

Declaration

PTREE cndxparse( pConvMap Schema, pTEXT Names, pTEXT InputText, NINT InputTextSize )

Description

You can use the FairCom DB expression parser/analyzer to evaluate expressions. For a complete sample program, see ctexpr.c in the ctree/source directory.

Where:

Schema - DODA
Names - List of names of fields
InputText - Text of conditional expression
InputTextSize - Length of text for conditional expression

Using the FairCom DB expression parser/analyzer involves two steps:

Calling cndxparse() to parse your expression, producing an expression tree the expression analyzer can evaluate. This involves three steps:
1. Define a DODA structure.
2. Parse the DODA into a record schema and field name list.
3. Parse your expression to produce an expression tree.
Calling cndxeval() to evaluate the expression tree using data from a buffer in memory.

Return Values

Returns a PTREE parse tree on success. NULL if error.

Example

#include "ctcndx.h"  /* For PTREE type */

/* Define a DODA structure. */
DATOBJ doda[] = {
  {"CustomerNumber", 0,  CT_INT4U},
  {"ZipCode",        4,  CT_FSTRING,  9},
  {"State",         13,  CT_FSTRING,  2},
  {"LastName",      15,  CT_STRING,  37},
  {"FirstName",     52,  CT_STRING,  37},
  {"Address",       89,  CT_STRING,  49},
  {"City",         138,  CT_STRING,  37}
};

COUNT retval;  /* Return code.        */
pTEXT schema;  /* Record schema.      */
pTEXT names;   /* Field name list.    */
PTREE ptree;   /* Expression tree.    */
pTEXT expr;    /* Expression string.  */

/* Parse the DODA into a record schema and field name list. */
if ((retval = ctparsedoda(doda, 7, &schema, &names)) != 0)
    printf("Error %d parsing DODA.\n", retval);

/* Parse your expression to produce an expression tree. */
expr  = "stricmp(LastName, \"Smith\") == 0
        && CustomerNumber > 10000";
ptree = cndxparse(schema, names, expr, strlen(expr));
if (!ptree)
    printf("Error: Unable to parse expression.\n");
else
    printf("Successfully parsed expression.\n");
...

if ( ptree )
	cndxfree (ptree);

See also

cndxeval, cndxfree, ctparsedoda, cndxrun, getcndxmem, putcndxmem

cndxrun

Executes the parse tree evaluating an expression in a parse tree. The result of the expression is left on top of the stack.

Declaration

COUNT cndxrun( PTREE Tree, pVOID Recptr, pConvMap Schema, VRLEN fixlen, VRLEN datlen );

Description

Where:

Tree - Parser tree generated by the expression parser
Recptr - pointer to a record buffer with data
Schema - c-tree DODA schema for the data file
fixlen - record fixed length size
datlen - total size of record

Return Values

Value	Symbolic Constant	Explanation
	ERY_NONE	SUCCESS

See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

if ( ( retcidx = cndxrun( (PTREE)expr->expr_tree, 
	pRecord->recbuf,
	(pConvMap)pTable->schemaptr,
	(VRLEN)pRecord->fixrec_len,
	(VRLEN)pRecord->recbuf_len inHan) ) == ERY_NONE && ctcidxStkPtr == 0 )
{
	retval = CTDBRET_INTERNAL;
	goto Exit;
}

See also

cndxeval, cndxfree, cndxparse, ctparsedoda, getcndxmem, putcndxmem

ctparsedoda

Parses a DODA object into a record schema and field name list.

Declaration

COUNT ctparsedoda(pDATOBJ doda, UCOUNT numfld, ppTEXT ppschema, ppTEXT ppnames)

Description

One of the most useful features of the FairCom DB expression parser is its ability to associate symbolic names in expressions with data in a buffer in memory. To use this ability, you must define a record schema, known as a DODA (Data Object Definition Array). A DODA is an array of field specifications, each of which contains a field name, field offset, field type, and a field length. By providing the expression parser with a DODA, you may include references to DODA field names in your expressions. See the sample code shown later in this section for an example of a DODA definition.

While a DODA is conveniently defined in your application using an array of DATOBJ structures, cndxparse() does not take a DODA in DATOBJ form, but instead accepts a record schema and a list of the field names from the DODA. To simplify converting your DODA into the required record schema and field name list, FairCom has written a utility function, ctparsedoda(). This function can be found in the sample file ctexpr.c.

Return Values

Value	Symbolic Constant	Explanation
0	CTDBRET_OK	Successful operation.

See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

#include "ctcndx.h"  /* For PTREE type */

/* Define a DODA structure. */
DATOBJ doda[] = {
  {"CustomerNumber", 0,  CT_INT4U},
  {"ZipCode",        4,  CT_FSTRING,  9},
  {"State",         13,  CT_FSTRING,  2},
  {"LastName",      15,  CT_STRING,  37},
  {"FirstName",     52,  CT_STRING,  37},
  {"Address",       89,  CT_STRING,  49},
  {"City",         138,  CT_STRING,  37}
};

COUNT retval;  /* Return code.        */
pTEXT schema;  /* Record schema.      */
pTEXT names;   /* Field name list.    */

/* Parse the DODA into a record schema and field name list. */
if ((retval = ctparsedoda(doda, 7, &schema, &names)) != 0)
    printf("Error %d parsing DODA.\n", retval);

See also

cndxeval, cndxparse, cndxfree, ctparsedoda, getcndxmem, mbfree

getcndxmem

Get memory required to process and store conditional index expressions (allows the proper memory allocation routines to be used on the client and server sides).

Declaration

pTEXT getcndxmem( UINT sizobj );

Description

The macros getcndxmem() and putcndxmem(), used to get and put memory required to process and store conditional index expressions, allow the proper memory allocation routines to be used on the client and server sides. (These substitute for the internal mballc() and mbfree() calls.)

Return Values

getcndxmem() returns a pointer to the newly allocated object on success. A NULL pointer is returned if memory could not be allocated.

Example

/* Allocate a run-time stack for the expression analyzer (first time only). */
if (!ctcidxStk)  {
    ctcidxStk = (pVOID) getcndxmem(CNDX_MAX_STACK * ctSIZE(PLEAF));
    if (!ctcidxStk)  {
        printf("Unable to allocate memory for run-time stack.\n");
        ctrt_exit(1);
    }
}

if (ctcidxStk)
	putcndxmem(ctcidxStk);

See also

cndxeval(), cndxfree(), cndxparse(), ctparsedoda(), cndxrun(), putcndxmem()

putcndxmem

Frees memory from expression parser tree.

Declaration

VOID putcndxmem( pVOID objptr );

Description

Example

/* Allocate a run-time stack for the expression analyzer (first time only). */
if (!ctcidxStk)  {
    ctcidxStk = (pVOID) getcndxmem(CNDX_MAX_STACK * ctSIZE(PLEAF));
    if (!ctcidxStk)  {
        printf("Unable to allocate memory for run-time stack.\n");
        ctrt_exit(1);
    }
}

if (ctcidxStk)
	putcndxmem(ctcidxStk);

See also

cndxeval(), cndxfree(), cndxparse(), ctparsedoda(), cndxrun(), putcndxmem()

Conditional Expression Function Reference

cndxeval

cndxfree

cndxparse

cndxrun

ctparsedoda

getcndxmem

putcndxmem

Was this article helpful?

Related Articles

Transform method concepts

JavaScript transform concepts

FairCom DB Expression Parser and Grammar