B.6 Querying Values

Before the values of variables can be queried the stored expression trees have to be evaluated first. The basic functions to evaluate an expression of a variable are ipdEvalIterator and ipdEvalByName. The function ipdEvalIterator evaluates the variable represented by the iterator and ipdEvalByName evaluates the item referred to by its name. The declarations are given below. Both functions return an item of type ipdTreeNode_t which contains the result or 0 in case of an error.

ipdTreeNode_t *ipdEvalIterator(ipdIterator_t *iNode);
ipdTreeNode_t *ipdEvalByName  (const char    *name,
                               bool           doFindAuxiliaries);

Since the datatype of an expression is determined during evaluation the datatype has to be checked before the value can be extracted. This is can be accomplished by a call to the function ipdGetValueType.

ipdType_t ipdGetValueType(const ipdTreeNode_t *tn)

The value returned may be one of ipdINTEGER, ipdREAL, ipdCOMPLEX, ipdREALQUANTITY, ipdCOMPLEXQUANTITY, ipdBOOLEAN, ipdSTRING, and ipdARRAYVAL. Using this type the value can be extracted from the structure. Alternatively to the functions shown above the application interface provides functions specialized for certain data types. They can be used when the application strongly expects certain data types for variables. The declarations of these functions are

bool ipdGetIntegerByName           (const char  *name,
                                    long        *integer_p);
bool ipdGetRealByName              (const char  *name,
                                    double      *re_p);
bool ipdGetSloppyRealByName        (const char  *name,
                                    double      *re_p);
bool ipdGetRealQuantityByName      (const char  *name,
                                    double      *re_p,
                                    char       **unit_p);
bool ipdGetSloppyRealQuantityByName(const char  *name,
                                    double      *re_p,
                                    char       **unit_p);
bool ipdGetComplexByName           (const char  *name,
                                    double      *re_p,
                                    double      *im_p);
bool ipdGetComplexQuantityByName   (const char  *name,
                                    double      *re_p,
                                    double      *im_p,
                                    char       **unit_p);
bool ipdGetStringByName            (const char  *name,
                                    char       **string_p);
bool ipdGetBooleanByName           (const char  *name,
                                    bool        *boolean_p);

The function declarations are widely self-explaining. The function ipdGetSloppyRealByName not only returns real values but integer values, too, converting them to real. The function ipdGetSloppyRealQuantityByName even allows to read quantities. The first parameter is always the name of the variable to be queried. The expression of the variable is calculated and the value is returned through pointer arguments. All functions return true on success and false on error.

These functions are implemented for ipdTreeNode_t structures as well.