Classes | Typedefs | Enumerations | Functions
Handling Expressions

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...
 
SymbolSetmdlCExpression_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...
 
CTypemdlCExpression_typeArray (SymbolSet *setP, CType *madeofP, int count)
 Creates an in-memory definition of an array. More...
 
CTypemdlCExpression_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...
 
CTypemdlCExpression_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...
 
CTypemdlCExpression_typePointer (SymbolSet *setP, CType *madeofP)
 Creates a definition of a pointer type. More...
 
CTypemdlCExpression_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...
 

Detailed Description

Identifies the type of symbol that mdlCExpression_symbolPublish is publishing.

See also
CExprValue
CExprResult
CExprResultSymbolClass
CExprVisibilityMask
CExprResultClass
CExprValueType

Typedef Documentation

typedef struct cExprResult CExprResult

Provides the complete description of the result of evaluating a C-expression.

Remarks
When the C-expression evaluator evaluates an expression, it generates 2 structures that contain different representations of the result. The representation in CExprResult is the more complete. Whenever possible, the C-expression evaluator stores the location of the resulting value in the CExprResult and the actual value in the CExprValue. For example, given the expression "myVariable" the C-expression evaluator stores the address of the variable in CExprResult.value. It stores the contents of "myVariable" in CExprValue. In some cases, it does not make sense to store the address of the result. For example, given the expression "5" the C-expression evaluator stores the value 5 in the CExprResult.

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.

See also
CExprValue
typedef struct cExprValue CExprValue

Provides a simple description of the result of evaluating an expression.

See also
CExprResult
typedef struct cType CType

Describes a data type for the C-expression handling functions.

See also
CExprValue
CExprResult
CExprResultSymbolClass
CExprVisibilityMask
CExprResultClass
CExprValueType
typedef struct symbolSet SymbolSet
typedef union types_u Types_u

Enumeration Type Documentation

Describes the possible values of CExprResult.

class.

See also
CExprValue
CExprResult
CExprResultSymbolClass
CExprVisibilityMask
CExprResultClass
CExprValueType
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.

Enumerator
SYMBOL_CLASS_SOURCE 

used only by the MDL debugger.

SYMBOL_CLASS_SCOPE 

used only by the MDL debugger.

SYMBOL_CLASS_VAR 

used when publishing a variable.

SYMBOL_CLASS_STRUCT 

used when publishing a structure or union.

SYMBOL_CLASS_FUNCTION 

used when publishing an MDL function.

There is no equivalent for a native code function.

SYMBOL_CLASS_BLOCK 

used only by the MDL debugger.

describes the type of values stored in CExprValue.

val.

See also
CExprValue
CExprResult
CExprResultSymbolClass
CExprVisibilityMask
CExprResultClass
CExprValueType
Enumerator
CEXPR_TYPE_POINTER 

CExprValue.

val contains a pointer.

CEXPR_TYPE_LONG 

CExprValue.

val contains a long. When the expression evaluator generates a result that is smaller than a long, it promotes the value to a long.

CEXPR_TYPE_ULONG 

CExprValue.

val contains an unsigned long.

CEXPR_TYPE_DOUBLE 

CExprValue.

val contains a double.

CEXPR_TYPE_LONG64 

CExprValue.

val contains a 64-bit integer. It may be signed or unsigned.

Identifies the standard visiblity masks.

See also
CExprValue
CExprResult
CExprResultSymbolClass
CExprVisibilityMask
CExprResultClass
CExprValueType
Enumerator
VISIBILITY_DEBUGGER 

visibility mask used by the MDL debugger.

VISIBILITY_CALCULATOR 

visibility mask used by the calculator.

VISIBILITY_DIALOG_BOX 

visibility mask used by the Dialog Manager.

VISIBILITY_LOCAL 

not used by MicroStation.

VISIBILITY_DBASE_HOOK 

used by MicroStation database applications.

Function Documentation

void mdlCExpression_freeSet ( void *  setP)

Frees a symbol set.

Overview of C-expression Evaluator

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.

Parameters
[in]setPpointer to symbol set
Remarks
All memory used by the symbol set is freed. The symbols published in the symbol set are no longer available for C expression handling.

When an MDL application is unloaded, all symbol sets belonging to that application are freed.

Remarks
Required Library: mdlbltin.lib
StatusInt mdlCExpression_generateMessage ( WStringR  messageBuffer,
long  errorNumber 
)

Generates an error message based on the value passed in errorNumber.

Parameters
[out]messageBufferbuffer to receive message
[in]errorNumbervalue taken from mdlErrno
Returns
SUCCESS
Remarks
errorNumber should contain a value taken from mdlErrno after one of the mdlCExpression_... functions returns an error.

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 publishedInt = 1;
int status;
void *setP;
CExprValue value;
// This generates an error because the expression uses the actual name instead of the published name.
status = mdlCExpression_getValue (&value, NULL, "publishedInt", VISIBILITY_CALCULATOR);
if (status != SUCCESS)
{
WString buffer;
mdlOutput_errorUW (buffer.c_str());
}
Remarks
Required Library: mdlbltin.lib
int mdlCExpression_getArraySize ( const CType typeP)

Used to determine the size of the array specified.

Parameters
[in]typePa type definition.
Returns
An integer value indicating the number of elements in the array
Remarks
If the type is neither a pointer nor an array type, mdlCExpression_getArraySize sets mdlErrno to MDLERR_BADTYPE and returns 0. If the type is a pointer and not an array type, mdlCExpression_getArraySize return 0. If the type is an array type then mdlCExpression_getArraySize returns the number of elements that the array can hold. The actual size of the memory required to hold the entire array is this count times the size of an array element.

Use mdlCExpression_isArray to verify that the type is an array.

int i, count;
int publishedArray [10] = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9};
void *setP;
CType *typeP;
CExprValue value;
typeP = mdlCExpression_typeArray (setP, typeP, 10);
mdlCExpression_symbolPublish (setP, "publishedArray", SYMBOL_CLASS_VAR, typeP, publishedArray);
for (i = 0; i < count; i++)
{
char expression [80]; // CHAR_OK
sprintf (expression, "publishedArray [%d]", i);
printf ("the result is %d\n", value.val.valLong);
}
Remarks
Required Library: mdlbltin.lib
CType* mdlCExpression_getType ( MdlTypecodes  typeCode)

Gets a pointer to a type definition appropriate for the typecode passed in.

Parameters
[in]typeCodeis one of the TYPECODE_ constants found in typecode.h.
Returns
pointer to a CType.
Remarks
The returned pointer points to a static structure in memory. Since it is not dynamically allocated, do not try to free it.

mdlCExpression_getType (TYPECODE_INT) and mdlCExpression_getType (TYPECODE_LONG) return the same thing. The C-expression logic does not distinguish between long and int.

Remarks
In an MDL program, the expressions &longType and mdlCExpression_getType (TYPECODE_LONG); are identical. A C program must use mdlCExpression_getType (TYPECODE_LONG);.
Required Library: mdlbltin.lib
StatusInt mdlCExpression_getValue ( CExprValue valueP,
CExprResult resultP,
char const *  expressionP,
UInt32  visibilityFlag 
)

Evaluates the expression specified by expressionP.

Parameters
[out]valuePgets an easy-to-use representation of the value.
[out]resultPgets a detailed description of the expression result. resultP may be NULL.
[in]expressionPexpression to be evaluated
[in]visibilityFlagdetermines 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.
Remarks
Most applications that use mdlCExpression_getValue use the result returned in valueP.
An MDL application that is considered rights compliant should never call mdlCExpression_getValueForApp or mdlCExpression_getValue with an expression that the user entered. The MDL application should use mdlCExpression_restrictedGetValue and mdlCExpression_restrictedGetValueForApp. These functions prohibit use of pointers and dangerous functions when digital rights enforcement in effect.
Returns
Returns SUCCESS if no errors are encountered. Otherwise, it returns a non-zero value and stores more specific information in mdlErrno. Use mdlCExpression_generateMessage to generate an error message based on the result of mdlCExpression_getValue.
See also
mdlCExpression_setValue
CExpressionVisibilityMask
Remarks
Required Library: mdlbltin.lib
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.

Parameters
[out]valuePgets an easy-to-use representation of the value.
[out]resultPgets a detailed description of the expression result. resultP may be NULL.
[in]expressionPexpression to be evaluated
[in]visibilityFlagdetermines 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]mdlDescPidentifies an MDL application. mdlCExpression_getValueForApp will not use a private symbol set if it was created by another MDL applicatin.
Remarks
Most applications that use mdlCExpression_getValueForApp use the result returned in valueP.

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 ()).

Remarks
An MDL application that is considered rights compliant should never call mdlCExpression_getValueForApp or mdlCExpression_getValue with an expression that the user entered. The MDL application should use mdlCExpression_restrictedGetValue and mdlCExpression_restrictedGetValueForApp. These functions prohibit use of pointers and dangerous functions when digital rights enforcement in effect.
Returns
Returns SUCCESS if no errors are encountered. Otherwise, it returns a non-zero value and stores more specific information in mdlErrno. Use mdlCExpression_generateMessage to generate an error message based on the result of mdlCExpression_getValueForApp.
See also
mdlCExpression_setValueForApp
Remarks
Required Library: mdlbltin.lib
SymbolSet* mdlCExpression_initializeSet ( ULong  visibility,
int  sizeHashTable,
int  global 
)

Initializes a symbol set.

Parameters
[in]visibilityis 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]sizeHashTablespecifies the number of buckets used by a symbol set. Typically, this number is 0 to specify the default size.
[in]globalcan 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.
Returns
Returns a pointer to the symbol set. If NULL is returned, more specific error information is provided in mdlErrno.
Remarks
To prevent other applications from unintentionally accessing the symbol set, specify false for global; otherwise, specify true. Other MDL applications can intentionally access another application's symbol set using mdlCExpression_getValueForApp or mdlCExpression_setValueForApp.
Required Library: mdlbltin.lib
bool mdlCExpression_isArray ( const CType typeP)

Determines whether the type specified by typeP is an array.

Parameters
[in]typePpoints to a type definition
Returns
The mdlCExpression_isArray returns true if the type is an array type. It returns false if the type does not specify an array.
Remarks
Required Library: mdlbltin.lib
bool mdlCExpression_isCharPointer ( const CType typeP)

Determines if the type specified by typeP is a character pointer.

Parameters
[in]typePpoints to a type definition
Returns
The mdlCExpression_isCharPointer returns true if the type is a character pointer type. It returns true regardless of whether it points to signed or unsigned characters and whether the type is an array type. It returns false if the type does not specify a character pointer.
Remarks
Required Library: mdlbltin.lib
bool mdlCExpression_isStructUnion ( const CType typeP)

Determines whether the type specified by typeP is a structure or union.

Parameters
[in]typePpoints to a type definition
Returns
mdlCExpression_isStructUnion returns true if the type is a structure or union type. It returns false if the type does not specify a structure or union.
Remarks
Required Library: mdlbltin.lib
bool mdlCExpression_isWCharPointer ( const CType typeP)

Determines if the type specified by typeP is a wide character pointer.

Parameters
[in]typePpoints to a type definition
Returns
true if the type is a wide character pointer type. In other words, it returns true if te type is a pointer or array type and the component type is unsigned char. It returns false if the type does not specify a wide character pointer.
Remarks
Required Library: mdlbltin.lib
StatusInt mdlCExpression_publishFunction ( void *  setP,
char *  nameP,
char *  argumentsP,
CType returnTypeP,
void *  functionP 
)

Publishes a function so the expression evaluator can use it.

Parameters
[in]setPspecifies the symbol set to use. The symbol set must be previously initialized with mdlCExpression_initializeSet.
[in]namePspecifies the name to be published.
[in]argumentsPa 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]returnTypePDescribes the function's return type.
[in]functionPaddress of the function. It can point to an MDL function or a native code function.
Remarks
mdlCExpression_publishFunction can be used to publish native code functions and MDL functions. When used to publish an MDL function, it ignores the argumentsP parameter. Instead, it uses the argument description that MCOMP embeds in the MDL function.
Use an expression like:
mdlCExpression_publishFunction (pSet, "getResult", "DPDI", mdlCExpression_getType (TYPECODE_DOUBLE), getResult);
to publish the function
double getResult (double d, char *pString, double d2, int i)
Returns
Returns SUCCESS if no errors are encountered. Otherwise, it returns a non-zero value and stores more specific information in mdlErrno. To generate an error message based on the result of mdlCExpression_publishFunction, use mdlCExpression_generateMessage.
Remarks
Required Library: mdlbltin.lib
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.

Remarks
When digital rights are being enforced, the expresson evaluator refuses to call methods published via mdlCExpression_symbolPublish or via mdlCExpression_publishFunction.
Parameters
[in]setPspecifies the symbol set to use. The symbol set must be previously initialized with mdlCExpression_initializeSet.
[in]namePspecifies the name to be published.
[in]argumentsPa 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]returnTypePDescribes the function's return type.
[in]functionPaddress of the function. It can point to an MDL function or a native code function.
Remarks
Use mdlCExpression_publishTrustedFunction to publish functions that should be allowed when digital rights enforcement is in effect. Normally, this is only used for functions that do not have side effects. It is okay to use mdlCExpression_publishTrustedFunction to publish a function like sin since it is a computation with no side effects. It is not okay to publish a function like memcpy since that is a step towards making it possible for an expression to move memory.
mdlCExpression_publishTrustedFunction can be used to publish native code functions and MDL functions. When used to publish an MDL function, it ignores the argumentsP parameter. Instead, it uses the argument description that MCOMP embeds in the MDL function.
Use an expression like:
to publish the function
double getResult (double d, char *pString, double d2, int i)
Returns
Returns SUCCESS if no errors are encountered. Otherwise, it returns a non-zero value and stores more specific information in mdlErrno. To generate an error message based on the result of mdlCExpression_publishFunction, use mdlCExpression_generateMessage.
Remarks
Required Library: mdlbltin.lib
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.

Parameters
[out]valuePgets an easy-to-use representation of the value.
[out]resultPgets a detailed description of the expression result. resultP may be NULL.
[in]expressionPexpression to be evaluated
[in]visibilityFlagdetermines 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]enforceUnconditionallyIf 1, then mdlCExpression_restrictedGetValue prohibits unsafe expressions regardless of wheter digital rights encforcement is in effect.
Remarks
An expression is considered unsafe if it may compromise digital rights enforcement. Generally, an expression is considered unsafe if it uses pointers or calls a function that was not published with mdlCExpression_publishTrustedFunction.
An MDL application that is considered rights compliant should never call mdlCExpression_getValueForApp or mdlCExpression_getValue with an expression that the user entered. The MDL application should use mdlCExpression_restrictedGetValue and mdlCExpression_restrictedGetValueForApp.
It may be necessary for a rights compliant application to call one of the functions that does not detect unsafe expressions. That is okay if the expression is hardcoded and the programmer knows that it is a safe expression.
An MDL application that is considered rights compliant should never call mdlCExpression_getValueForApp or mdlCExpression_getValue with an expression that the user entered. The MDL application should use mdlCExpression_restrictedGetValue and mdlCExpression_restrictedGetValueForApp. These functions prohibit use of pointers and dangerous functions when digital rights enforcement is in effect.
Returns
Returns SUCCESS if no errors are encountered. Otherwise, it returns a non-zero value and stores more specific information in mdlErrno. Use mdlCExpression_generateMessage to generate an error message based on the result of mdlCExpression_restrictedGetValue.
See also
mdlCExpression_setValueForApp
Remarks
Required Library: mdlbltin.lib
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.

Parameters
[out]valuePgets an easy-to-use representation of the value.
[out]resultPgets a detailed description of the expression result. resultP may be NULL.
[in]expressionPexpression to be evaluated
[in]visibilityFlagdetermines 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]mdlDescPidentifies an MDL application. mdlCExpression_restrictedGetValueForApp will not use a private symbol set if it was created by another MDL applicatin.
[in]enforceUnconditionallyIf 1, then mdlCExpression_restrictedGetValue prohibits unsafe expressions regardless of whether digital rights encforcement is in effect.
Remarks
An expression is considered unsafe if it may compromise digital rights enforcement. Generally, an expression is considered unsafe if it uses pointers or calls a function that was not published with mdlCExpression_publishTrustedFunction.
An MDL application that is considered rights compliant should never call mdlCExpression_getValueForApp or mdlCExpression_getValue with an expression that the user entered. The MDL application should use mdlCExpression_restrictedGetValue and mdlCExpression_restrictedGetValueForApp.
It may be necessary for a rights compliant application to call one of the functions that does not detect unsafe expressions. That is okay if the expression is hardcoded and the programmer knows that it is a safe expression.
Most applications that use mdlCExpression_restrictedGetValueForApp use the result returned in valueP.
Returns
Returns SUCCESS if no errors are encountered. Otherwise, it returns a non-zero value and stores more specific information in mdlErrno. Use mdlCExpression_generateMessage to generate an error message based on the result of mdlCExpression_restrictedGetValueForApp.
See also
mdlCExpression_setValueForApp
Remarks
Required Library: mdlbltin.lib
StatusInt mdlCExpression_setValue ( CExprValue valueP,
CExprResult resultP,
char *  expressionP,
UInt32  visibilityFlag 
)

Stores the value specified by the structure valueP points to.

Parameters
[in,out]valuePexpression value
[in]resultPprevious result or NULL
[in]expressionPexpression or NULL
[in]visibilityFlagdetermines 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.
Remarks
The location to receive the value is specified as resultP if resultP is not NULL, or by expressionP if resultP is NULL. Generally, if resultP is not NULL, it is the result of a call to mdlCExpression_getValue.

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.

Returns
Returns SUCCESS if no errors are encountered. Otherwise, it returns a non-zero value and stores more specific information in mdlErrno. To generate an error message based on the result of mdlCExpression_setValue, use ~!mmdlCExpression_generateMessage.
See also
mdlCExpression_getValue
Remarks
Required Library: mdlbltin.lib
StatusInt mdlCExpression_setValueForApp ( CExprValue valueP,
CExprResult resultP,
char *  expressionP,
UInt32  visibilityFlag,
MdlDesc mdlDescP 
)

Stores the value specified by the structure valueP points to.

Parameters
[in,out]valuePValue of the expression
[in,out]resultPResult of the expression
[in]expressionPthe expression or NULL
[in]visibilityFlagdetermines 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]mdlDescPspecifies the mdl application the value is stored for.
Remarks
The location to receive the value is specified as resultP if resultP is not NULL, or by expressionP if resultP is NULL. Generally, if resultP is not NULL, it is the result of a call to mdlCExpression_getValue.

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.

Returns
Returns SUCCESS if no errors are encountered, otherwise, it returns a non-zero value and stores more specific information in mdlErrno. To generate an error message based on the result of mdlCExpression_setValueForApp, use mdlCExpression_generateMessage.
See also
mdlCExpression_getValueForApp
Remarks
Required Library: mdlbltin.lib
StatusInt mdlCExpression_symbolPublish ( SymbolSet setP,
char *  nameP,
int  symbolClass,
CType typeP,
void *  dataP 
)

Publishes a symbol so the expression evaluator can use it.

Parameters
[in]setPspecifies the symbol set to use. The symbol set must be previously initialized with mdlCExpression_initializeSet.
[in]namePspecifies the name to be published.
[in]symbolClasscan be SYMBOL_CLASS_FUNCTION, SYMBOL_CLASS_STRUCT or SYMBOL_CLASS_VAR.
[in]typePcan 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]dataPlocation of data or function
Remarks
If SYMBOL_CLASS_FUNCTION is used, dataP must be the address of an MDL function. It cannot be the address of a native code function. If dataP is the address of a native code function, then mdlCExpression_symbolPublish sets mdlErrno to MDLERR_NOTFUNCTION and returns 1.

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.

Remarks
Use mdlCExpression_publishFunction to publish a native code function. There is no need to publish MDL built-in functions since they are automatically published.
If SYMBOL_CLASS_STRUCT is used, typeP must point to the definition of a structure or union. SYMBOL_CLASS_STRUCT makes a structure or union available in casts in expressions. dataP is ignored for SYMBOL_CLASS_STRUCT.
If SYMBOL_CLASS_VAR is used, typeP defines the type of the variable. dataP must define the location of the variable.
From native code, use mdlCExpression_getType instead of the built-in variables to get a pointer to the type definition for one of the primitive types.
Do not use this function to publish a native code function. Use mdlCExpression_publishFunction instead.
Returns
Returns SUCCESS if no errors are encountered. Otherwise, it returns a non-zero value and stores more specific information in mdlErrno. To generate an error message based on the result of mdlCExpression_symbolPublish, use mdlCExpression_generateMessage.
Remarks
Required Library: mdlbltin.lib
CType* mdlCExpression_typeArray ( SymbolSet setP,
CType madeofP,
int  count 
)

Creates an in-memory definition of an array.

Parameters
[in]setPspecifies the symbol set that the array will be associated with.
[in]madeofPthe 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]countthe number of elements to be stored in the array
Returns
a pointer to the type definition in memory, or NULL if an error occurs.
Remarks
mdlCExpression_typeArray allocates memory that is associated with the symbol set setP. The memory for the type is freed when the set is freed Therefore, the memory is freed when the MDL application is unloaded, or when the MDL application calls mdlCExpression_freeSet.
Required Library: mdlbltin.lib
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.

Parameters
[in]setPspecifies the symbol set that the type will be associated with. When this symbol set is freed, the type definition is also freed.
[in]namePname of the structure or union
[in]rfHandlespecifies 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.
Returns
Returns a pointer to the type definition. If an error occurs, it returns NULL; more information is available in mdlErrno.
Remarks
To define a type in a resource file, use RSCTYPE to compile a .mt file, and then use RCOMP to compile the .r file that RSCTYPE generates.
The name parameter refers to the structure or union tag. It does not refer to the specified via a typedef. Given the following declaration, the name argument would have to be "pointtag". It could not be "Point".
typedef struct pointtag
{
double x;
double y;
double z;
}
See also
mdlCExpression_typeFromRsc1
Remarks
Required Library: mdlbltin.lib
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.

Parameters
[in]setPspecifies the symbol set that the type will be associated with. When this symbol set is freed, the type definition is also freed.
[in]namePname of the structure or union
[in]rfHandlespecifies 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]rscIdthe 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.
Returns
a pointer to the type definition, or NULL if an error occurs
See also
mdlCExpression_typeFromRsc
Remarks
Required Library: mdlbltin.lib
CType* mdlCExpression_typePointer ( SymbolSet setP,
CType madeofP 
)

Creates a definition of a pointer type.

Parameters
[in]setPspecifies the symbol set the type will be associated with. When this symbol set is freed, the type definition is also freed.
[in]madeofPspecifies 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.
Returns
Returns a pointer to the type definition. If an error occurs, it returns NULL; more information is available in mdlErrno.
See also
mdlCExpression_typeFromRsc mdlCExpression_typeArray
Remarks
Required Library: mdlbltin.lib

Copyright © 2017 Bentley Systems, Incorporated. All rights reserved.