Identifies the type of symbol that mdlCExpression_symbolPublish is publishing. More...
Classes | |
struct | cType |
Describes a data type for the C-expression handling functions. More... | |
union | types_u |
struct | cExprResult |
struct | cExprValue |
Typedefs | |
typedef struct cType | CType |
Describes a data type for the C-expression handling functions. More... | |
typedef union types_u | Types_u |
typedef struct cExprResult | CExprResult |
Provides the complete description of the result of evaluating a C-expression. More... | |
typedef struct cExprValue | CExprValue |
Provides a simple description of the result of evaluating an expression. More... | |
typedef struct symbolSet | SymbolSet |
Enumerations | |
enum | CExprSymbolClass { SYMBOL_CLASS_SOURCE = 0x01, SYMBOL_CLASS_SCOPE = 0x02, SYMBOL_CLASS_VAR = 0x04, SYMBOL_CLASS_STRUCT = 0x08, SYMBOL_CLASS_FUNCTION = 0x20, SYMBOL_CLASS_BLOCK = 0x40 } |
enum | CExprVisibilityMask { VISIBILITY_DEBUGGER = 1, VISIBILITY_CALCULATOR = 2, VISIBILITY_DIALOG_BOX = 4, VISIBILITY_LOCAL = 8, VISIBILITY_DBASE_HOOK = 16 } |
Identifies the standard visiblity masks. More... | |
enum | CExprResultClass { CL_VALUE = 1, CL_LVALUE = 2, CL_ERROR = 3 } |
Describes the possible values of CExprResult. More... | |
enum | CExprValueType { CEXPR_TYPE_POINTER = 1, CEXPR_TYPE_LONG = 2, CEXPR_TYPE_ULONG = 3, CEXPR_TYPE_DOUBLE = 4, CEXPR_TYPE_LONG64 = 5 } |
describes the type of values stored in CExprValue. More... | |
Functions | |
void | mdlCExpression_freeSet (void *setP) |
Frees a symbol set. More... | |
StatusInt | mdlCExpression_generateMessage (WStringR messageBuffer, long errorNumber) |
Generates an error message based on the value passed in errorNumber. More... | |
int | mdlCExpression_getArraySize (const CType *typeP) |
Used to determine the size of the array specified. More... | |
StatusInt | mdlCExpression_getValue (CExprValue *valueP, CExprResult *resultP, char const *expressionP, UInt32 visibilityFlag) |
Evaluates the expression specified by expressionP. More... | |
StatusInt | mdlCExpression_getValueForApp (CExprValue *valueP, CExprResult *resultP, char const *expressionP, UInt32 visibilityFlag, MdlDesc *mdlDescP) |
Evaluates the expression specified and stores the result in both *valueP and *resultP. More... | |
StatusInt | mdlCExpression_setValueForApp (CExprValue *valueP, CExprResult *resultP, char *expressionP, UInt32 visibilityFlag, MdlDesc *mdlDescP) |
Stores the value specified by the structure valueP points to. More... | |
SymbolSet * | mdlCExpression_initializeSet (ULong visibility, int sizeHashTable, int global) |
Initializes a symbol set. More... | |
bool | mdlCExpression_isArray (const CType *typeP) |
Determines whether the type specified by typeP is an array. More... | |
bool | mdlCExpression_isCharPointer (const CType *typeP) |
Determines if the type specified by typeP is a character pointer. More... | |
bool | mdlCExpression_isWCharPointer (const CType *typeP) |
Determines if the type specified by typeP is a wide character pointer. More... | |
bool | mdlCExpression_isStructUnion (const CType *typeP) |
Determines whether the type specified by typeP is a structure or union. More... | |
StatusInt | mdlCExpression_setValue (CExprValue *valueP, CExprResult *resultP, char *expressionP, UInt32 visibilityFlag) |
Stores the value specified by the structure valueP points to. More... | |
StatusInt | mdlCExpression_symbolPublish (SymbolSet *setP, char *nameP, int symbolClass, CType *typeP, void *dataP) |
Publishes a symbol so the expression evaluator can use it. More... | |
StatusInt | mdlCExpression_publishFunction (void *setP, char *nameP, char *argumentsP, CType *returnTypeP, void *functionP) |
Publishes a function so the expression evaluator can use it. More... | |
CType * | mdlCExpression_typeArray (SymbolSet *setP, CType *madeofP, int count) |
Creates an in-memory definition of an array. More... | |
CType * | mdlCExpression_typeFromRsc (SymbolSet *setP, char *nameP, RscFileHandle rfHandle) |
Creates an in-memory definition of a structure or union based on the definition contained in a resource file. More... | |
CType * | mdlCExpression_typeFromRsc1 (SymbolSet *setP, char *nameP, RscFileHandle rfHandle, UInt32 rscId) |
Creates an in-memory definition of a structure or union based on the definition contained in a resource file, and the resource ID. More... | |
CType * | mdlCExpression_typePointer (SymbolSet *setP, CType *madeofP) |
Creates a definition of a pointer type. More... | |
CType * | mdlCExpression_getType (MdlTypecodes typeCode) |
Gets a pointer to a type definition appropriate for the typecode passed in. More... | |
StatusInt | mdlCExpression_restrictedGetValue (CExprValue *valueP, CExprResult *resultP, char const *expressionP, unsigned long visibilityFlag, bool enforceUnconditionally) |
Evaluates the expression specified by expressionP. More... | |
StatusInt | mdlCExpression_restrictedGetValueForApp (CExprValue *valueP, CExprResult *resultP, char const *expressionP, unsigned long visibilityFlag, MdlDesc *mdlDescP, bool enforceUnconditionally) |
Evaluates the expression specified by expressionP. More... | |
StatusInt | mdlCExpression_publishTrustedFunction (void *setP, char *nameP, char *argumentsP, CType *returnTypeP, void *functionP) |
Publishes a function so the expression evaluator can use it even when digital rights is enforced. More... | |
Identifies the type of symbol that mdlCExpression_symbolPublish is publishing.
typedef struct cExprResult CExprResult |
Provides the complete description of the result of evaluating a C-expression.
If class contains CL_VALUE, then value contains the actual result from executing the expression. If class contains CL_LVALUE, then value contains the address of the actual result. If class contains CL_ERROR, then value does not contain a valid result.
Most users only use the result in CExprValue.
typedef struct cExprValue CExprValue |
Provides a simple description of the result of evaluating an expression.
Describes a data type for the C-expression handling functions.
typedef struct symbolSet SymbolSet |
enum CExprResultClass |
Describes the possible values of CExprResult.
class.
Enumerator | |
---|---|
CL_VALUE |
indicates that CExprResult. value contains the actual value of the result. |
CL_LVALUE |
indicates that CExprResult. value contains a pointer to the actual value of the result. |
CL_ERROR |
indicates that CExprResult. value are invalid and should not be used. |
enum CExprSymbolClass |
enum CExprValueType |
describes the type of values stored in CExprValue.
val.
enum CExprVisibilityMask |
Identifies the standard visiblity masks.
void mdlCExpression_freeSet | ( | void * | setP | ) |
Frees a symbol set.
The C-Expression Handling functions parse and evaluate C expressions at runtime. These functions let programs establish a context for executing the expressions, and then executing the expressions when necessary.
MicroStation's Dialog Manager uses these functions to evaluate access strings, setting and retrieving the values of items. The MDL debugger uses these functions to evaluate the expressions entered at the debugger's prompt.
An expression evaluated by one of the C-expression functions can contain variable and function references. For a variable or function name to be available to the expression evaluator, the name must be published as a symbol using mdlCExpression_symbolPublish.
Symbols are managed in symbol sets. An MDL program must create a symbol set before it can publish a symbol. Publishing a symbol adds it to a symbol set. When a symbol set is freed, the definitions of all of the set's published symbols are removed. A symbol set is associated with the MDL application that creates it. When an MDL application is unloaded, all of the MDL application's symbol sets are freed.
Every symbol set has a visibility flag. The visibility flag is a bit mask that the C-expression evaluator uses to determine if a symbol set can be used to resolve a symbol from an expression. Every C-expression function that evaluates expressions takes a visibility flag argument. Before searching for a symbol in a symbol set, the C-expression evaluator AND's this argument with a symbol-set's visibility flag. If the result is non-zero, then the C-expression evaluator can use that symbol set to resolve symbols for the expression. If the result is zero, then the C-expression evaluator skips that symbol set and moves on to the next one.
The call to mdlCExpression_initializeSet designates whether the symbol set is global or private. If the symbol set is global, then other MDL applications can use symbols from that set.
When trying to resolve a symbol, the C-expression evaluator first searches private symbol sets that are associated with the MDL application and have an appropriate visibility flag. If none of those sets contains the symbol, then it searches the global symbol sets that have a matching visibility flag. If that also fails to provide a match, then it searches the list of MicroStation built-in functions.
A symbol set should be private unless it is to be shared between MDL applications. If the symbol set is global, then the MDL application should only publish names that are unlikely to be the same as names published by other MDL applications.
Since most symbol sets are used to make symbols available to the Dialog Manager's access strings, most symbol sets have visibility VISIBILITY_DIALOG_BOX.
To make a symbol set available to MicroStation's key-in preprocessor, make it global and specify VISIBILITY_CALCULATOR visibility. You can specify that a symbol set is available to both MicroStation's key-in preprocessor and to the Dialog Manager by specifying (VISIBILITY_CALCULATOR | VISIBILITY_DIALOG_BOX). The key-in preprocessor can only use global symbol sets. The Dialog Manager can use private and global symbol sets.
The MDL debugger's DISPLAY command uses the C-expression logic to evaluate expressions. Since the DISPLAY command logic specifies VISIBILITY_DEBUGGER whenever it calls a C-expression function, an MDL application can create a symbol set with VISIBILITY_DEBUGGER to make symbols available to the MDL debugger. You may want to do this as a way of extending the debugger. You should never evaluate an expression using VISIBILITY_DEBUGGER. If your code contains an expression like mdlCExpression_getValue (&value, &result, expressionP, VISIBILITY_DEBUGGER)
then it may function differently depending on whether the MDL debugger is active.
Any parser must have a description of a symbol's data type to know how to interpret the symbols in an expression. MicroStation C-expression evaluator is no exception. Consequently, when a program publishes a symbol it must specify the data type. If the type definition is large, the type definition is generally contained in a resource file. To generate a type definition in a resource file use the RSCTYPE utility. The input to RSCTYPE is a list of structure and union definitions. The output is a resource manager source file that must be compiled with RCOMP.
The C-expression evaluator divides integers differently than C does. If the result of integer division produces a floating point result, C converts it to integer by truncating. The C-expression evaluator treats the result as a floating point value. For example, in C the result of 1/4 is 0. With MicroStation's C-expression evaluator the result is 0.25.
[in] | setP | pointer to symbol set |
When an MDL application is unloaded, all symbol sets belonging to that application are freed.
StatusInt mdlCExpression_generateMessage | ( | WStringR | messageBuffer, |
long | errorNumber | ||
) |
Generates an error message based on the value passed in errorNumber.
[out] | messageBuffer | buffer to receive message |
[in] | errorNumber | value taken from mdlErrno |
The following code fragment shows how to use mdlCExpression_generateMessage. This code calls mdlCExpression_getValue using the actual name of the variable instead of the published name. mdlCExpression_generateMessage generates the error message symbol "publishedInt" not defined.
int mdlCExpression_getArraySize | ( | const CType * | typeP | ) |
Used to determine the size of the array specified.
[in] | typeP | a type definition. |
Use mdlCExpression_isArray to verify that the type is an array.
CType* mdlCExpression_getType | ( | MdlTypecodes | typeCode | ) |
Gets a pointer to a type definition appropriate for the typecode passed in.
[in] | typeCode | is one of the TYPECODE_ constants found in typecode.h. |
mdlCExpression_getType (TYPECODE_INT)
and mdlCExpression_getType (TYPECODE_LONG)
return the same thing. The C-expression logic does not distinguish between long and int.
&longType
and mdlCExpression_getType (TYPECODE_LONG);
are identical. A C program must use mdlCExpression_getType (TYPECODE_LONG);
. StatusInt mdlCExpression_getValue | ( | CExprValue * | valueP, |
CExprResult * | resultP, | ||
char const * | expressionP, | ||
UInt32 | visibilityFlag | ||
) |
Evaluates the expression specified by expressionP.
[out] | valueP | gets an easy-to-use representation of the value. |
[out] | resultP | gets a detailed description of the expression result. resultP may be NULL. |
[in] | expressionP | expression to be evaluated |
[in] | visibilityFlag | determines the symbol sets used in evaluating the expression. When searching for symbols, MicroStation examines each symbol set performing a bitwise AND of visibilityFlag and the symbol set's visibility flag. If the result is not zero, MicroStation looks for a definition of the symbol in that symbol set. See CExprVisibilityMask for a list of common values. |
StatusInt mdlCExpression_getValueForApp | ( | CExprValue * | valueP, |
CExprResult * | resultP, | ||
char const * | expressionP, | ||
UInt32 | visibilityFlag, | ||
MdlDesc * | mdlDescP | ||
) |
Evaluates the expression specified and stores the result in
both *valueP and *resultP.
[out] | valueP | gets an easy-to-use representation of the value. |
[out] | resultP | gets a detailed description of the expression result. resultP may be NULL. |
[in] | expressionP | expression to be evaluated |
[in] | visibilityFlag | determines the symbol sets used in evaluating the expression. When searching for symbols, MicroStation examines each symbol set performing a bitwise AND of visibilityFlag and the symbol set's visibility flag. If the result is not zero, MicroStation looks for a definition of the symbol in that symbol set. See CExprVisibilityMask for a list of common values. |
[in] | mdlDescP | identifies an MDL application. mdlCExpression_getValueForApp will not use a private symbol set if it was created by another MDL applicatin. |
mdlCExpression_getValue is identical to mdlCExpression_getValueForApp, except that it uses the current MDL descriptor. It is implemented as: mmdlCExpression_getValueForApp (valueP, resultP, expressionP, visibilityFlag, mdlSystem_getCurrMdlDesc ())
.
Initializes a symbol set.
[in] | visibility | is a bitmask. If the symbols in a symbol set are used for dialog boxes, specify VISIBILITY_DIALOG_BOX. If the symbols in a symbol set are used for the calculator/preprocessor, specify VISIBILITY_CALCULATOR. If the symbols in a symbol set are used for both dialog boxes and the preprocessor, specify (VISIBILITY_DIALOG_BOX | VISIBILITY_CALCULATOR). See CExprVisibilityMask for a list of common values. |
[in] | sizeHashTable | specifies the number of buckets used by a symbol set. Typically, this number is 0 to specify the default size. |
[in] | global | can be true or false for a symbol set being created for symbols being made available to the Dialog Manager. It should be true for a symbol set being created for symbols being made available to the calculator/preprocessor. |
bool mdlCExpression_isArray | ( | const CType * | typeP | ) |
Determines whether the type specified by typeP is an array.
[in] | typeP | points to a type definition |
bool mdlCExpression_isCharPointer | ( | const CType * | typeP | ) |
Determines if the type specified by typeP is a character pointer.
[in] | typeP | points to a type definition |
bool mdlCExpression_isStructUnion | ( | const CType * | typeP | ) |
Determines whether the type specified by typeP is a structure or union.
[in] | typeP | points to a type definition |
bool mdlCExpression_isWCharPointer | ( | const CType * | typeP | ) |
Determines if the type specified by typeP is a wide character pointer.
[in] | typeP | points to a type definition |
StatusInt mdlCExpression_publishFunction | ( | void * | setP, |
char * | nameP, | ||
char * | argumentsP, | ||
CType * | returnTypeP, | ||
void * | functionP | ||
) |
Publishes a function so the expression evaluator can use it.
[in] | setP | specifies the symbol set to use. The symbol set must be previously initialized with mdlCExpression_initializeSet. |
[in] | nameP | specifies the name to be published. |
[in] | argumentsP | a list of argument descriptions. 'D' represents a double, 'J' represents a 64-bit int, 'I' represents an integer or long, and 'P' represents a pointer. For example, specify "PDIP" if the arguments are a pointer, a double, an integer, and another pointer. |
[in] | returnTypeP | Describes the function's return type. |
[in] | functionP | address of the function. It can point to an MDL function or a native code function. |
StatusInt mdlCExpression_publishTrustedFunction | ( | void * | setP, |
char * | nameP, | ||
char * | argumentsP, | ||
CType * | returnTypeP, | ||
void * | functionP | ||
) |
Publishes a function so the expression evaluator can use it even when digital rights is enforced.
[in] | setP | specifies the symbol set to use. The symbol set must be previously initialized with mdlCExpression_initializeSet. |
[in] | nameP | specifies the name to be published. |
[in] | argumentsP | a list of argument descriptions. 'D' represents a double, 'J' represents a 64-bit int, 'I' represents an integer or long, and 'P' represents a pointer. For example, specify "PDIP" if the arguments are a pointer, a double, an integer, and another pointer. |
[in] | returnTypeP | Describes the function's return type. |
[in] | functionP | address of the function. It can point to an MDL function or a native code function. |
StatusInt mdlCExpression_restrictedGetValue | ( | CExprValue * | valueP, |
CExprResult * | resultP, | ||
char const * | expressionP, | ||
unsigned long | visibilityFlag, | ||
bool | enforceUnconditionally | ||
) |
Evaluates the expression specified by expressionP.
Similar to mdlCExpression_getValue, but it detects unsafe expressions.
[out] | valueP | gets an easy-to-use representation of the value. |
[out] | resultP | gets a detailed description of the expression result. resultP may be NULL. |
[in] | expressionP | expression to be evaluated |
[in] | visibilityFlag | determines the symbol sets used in evaluating the expression. When searching for symbols, MicroStation examines each symbol set performing a bitwise AND of visibilityFlag and the symbol set's visibility flag. If the result is not zero, MicroStation looks for a definition of the symbol in that symbol set. See CExprVisibilityMask for a list of common values. |
[in] | enforceUnconditionally | If 1, then mdlCExpression_restrictedGetValue prohibits unsafe expressions regardless of wheter digital rights encforcement is in effect. |
StatusInt mdlCExpression_restrictedGetValueForApp | ( | CExprValue * | valueP, |
CExprResult * | resultP, | ||
char const * | expressionP, | ||
unsigned long | visibilityFlag, | ||
MdlDesc * | mdlDescP, | ||
bool | enforceUnconditionally | ||
) |
Evaluates the expression specified by expressionP.
Similar to mdlCExpression_getValueForApp, but it detects unsafe expressions.
[out] | valueP | gets an easy-to-use representation of the value. |
[out] | resultP | gets a detailed description of the expression result. resultP may be NULL. |
[in] | expressionP | expression to be evaluated |
[in] | visibilityFlag | determines the symbol sets used in evaluating the expression. When searching for symbols, MicroStation examines each symbol set performing a bitwise AND of visibilityFlag and the symbol set's visibility flag. If the result is not zero, MicroStation looks for a definition of the symbol in that symbol set. See CExprVisibilityMask for a list of common values. |
[in] | mdlDescP | identifies an MDL application. mdlCExpression_restrictedGetValueForApp will not use a private symbol set if it was created by another MDL applicatin. |
[in] | enforceUnconditionally | If 1, then mdlCExpression_restrictedGetValue prohibits unsafe expressions regardless of whether digital rights encforcement is in effect. |
StatusInt mdlCExpression_setValue | ( | CExprValue * | valueP, |
CExprResult * | resultP, | ||
char * | expressionP, | ||
UInt32 | visibilityFlag | ||
) |
Stores the value specified by the structure valueP points to.
[in,out] | valueP | expression value |
[in] | resultP | previous result or NULL |
[in] | expressionP | expression or NULL |
[in] | visibilityFlag | determines the symbol sets used in evaluating the expression. When searching for symbols, MicroStation examines each symbol set performing a bitwise AND of visibilityFlag and the symbol set's visibility flag. If the result is not zero, MicroStation looks for a symbol definition in that symbol set. See CExprVisibilityMask for a list of common values. |
valueP->type is CEXPR_TYPE_POINTER, CEXPR_TYPE_DOUBLE or CEXPR_TYPE_LONG. If the result of the operation is smaller than a long, the result is promoted to a long. resultP->val contains the value resulting from evaluating the expression.
StatusInt mdlCExpression_setValueForApp | ( | CExprValue * | valueP, |
CExprResult * | resultP, | ||
char * | expressionP, | ||
UInt32 | visibilityFlag, | ||
MdlDesc * | mdlDescP | ||
) |
Stores the value specified by the structure valueP points to.
[in,out] | valueP | Value of the expression |
[in,out] | resultP | Result of the expression |
[in] | expressionP | the expression or NULL |
[in] | visibilityFlag | determines the symbol sets used in evaluating the expression. When searching for symbols, MicroStation examines each symbol set performing a bitwise AND of visibilityFlag and the symbol set's visibility flag. If the result is not zero, MicroStation looks for a symbol definition in that symbol set. See CExprVisibilityMask for a list of common values. |
[in] | mdlDescP | specifies the mdl application the value is stored for. |
valueP->type is CEXPR_TYPE_POINTER, CEXPR_TYPE_DOUBLE or CEXPR_TYPE_LONG. If the result of the operation is smaller than a long, the result is promoted to a long. resultP->val contains the value resulting from evaluating the expression.
StatusInt mdlCExpression_symbolPublish | ( | SymbolSet * | setP, |
char * | nameP, | ||
int | symbolClass, | ||
CType * | typeP, | ||
void * | dataP | ||
) |
Publishes a symbol so the expression evaluator can use it.
[in] | setP | specifies the symbol set to use. The symbol set must be previously initialized with mdlCExpression_initializeSet. |
[in] | nameP | specifies the name to be published. |
[in] | symbolClass | can be SYMBOL_CLASS_FUNCTION, SYMBOL_CLASS_STRUCT or SYMBOL_CLASS_VAR. |
[in] | typeP | can point to a type definition obtained from mdlCExpression_typeFromRsc, mdlCExpression_typePointer, mdlCExpression_typeArray, or mdlCExpression_getType. It can also point to one of the built-in variables that specify types: longType, shortType, charType, ulongType, ucharType, doubleType and voidType. |
[in] | dataP | location of data or function |
For MDL functions, the typeP parameter describes the return type of the function. It is only important if the return type is a pointer type. Otherwise, the evaluator ignores this and determines the return type by examining the MDL function itself. Therefore, typeP can be NULL when publishing a function.
Creates an in-memory definition of an array.
[in] | setP | specifies the symbol set that the array will be associated with. |
[in] | madeofP | the type of the objects to be stored in the array, this should be one of the built-in variables that specify types: longType, shortType, charType, ulongType, ucharType, doubleType and voidType. |
[in] | count | the number of elements to be stored in the array |
CType* mdlCExpression_typeFromRsc | ( | SymbolSet * | setP, |
char * | nameP, | ||
RscFileHandle | rfHandle | ||
) |
Creates an in-memory definition of a structure or union based on the definition contained in a resource file.
The definition in memory does not contain information on the members of the structure. It contains only enough information for MicroStation to find the members quickly.
[in] | setP | specifies the symbol set that the type will be associated with. When this symbol set is freed, the type definition is also freed. |
[in] | nameP | name of the structure or union |
[in] | rfHandle | specifies the resource file handle for the resource file that contains the definition. If rfHandle is 0, mdlCExpression_typeFromRsc searches the resource files the application has open. The resource file must remain open the entire time the type could be accessed. |
CType* mdlCExpression_typeFromRsc1 | ( | SymbolSet * | setP, |
char * | nameP, | ||
RscFileHandle | rfHandle, | ||
UInt32 | rscId | ||
) |
Creates an in-memory definition of a structure or union based on the definition contained in a resource file, and the resource ID.
The definition in memory does not contain information on the members of the structure. It contains only enough information for MicroStation to find the members quickly.
[in] | setP | specifies the symbol set that the type will be associated with. When this symbol set is freed, the type definition is also freed. |
[in] | nameP | name of the structure or union |
[in] | rfHandle | specifies the resource file handle for the resource file that contains the definition. If rfHandle is 0, mdlCExpression_typeFromRsc searches the resource files the application has open. The resource file must remain open the entire time the type could be accessed. |
[in] | rscId | the resource ID of a CexprNamedStructures resource. In nearly every case, the rscId is 1. The only difference between mdlCExpression_typeFromRsc1 and mdlCExpression_typeFromRsc is that mdlCExpression_typeFromRsc always uses a resoource ID value of 1. |
Creates a definition of a pointer type.
[in] | setP | specifies the symbol set the type will be associated with. When this symbol set is freed, the type definition is also freed. |
[in] | madeofP | specifies a type created by mdlCExpression_typeFromRsc, mdlCExpression_typePointer, mdlCExpression_typeArray or a built-in type that the new type points to. This type can be created with one of the mdlCExpression_type... functions, or one of the built-in types. |