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

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

enum CExprResultClass

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.

enum CExprSymbolClass

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.

enum CExprValueType

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.

enum CExprVisibilityMask

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]

setP

pointer 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]	messageBuffer	buffer to receive message
[in]	errorNumber	value 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;

setP = mdlCExpression_initializeSet (VISIBILITY_CALCULATOR, 0, true);

mdlCExpression_symbolPublish (setP, "publishedName", SYMBOL_CLASS_VAR,
                        mdlCExpression_getType (TYPECODE_LONG), &publishedInt);

//  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;

    mdlCExpression_generateMessage (buffer, mdlErrno);
    mdlOutput_errorUW (buffer.c_str());
    }

mdlCExpression_freeSet (setP);

Remarks

Required Library: mdlbltin.lib

int mdlCExpression_getArraySize

(

const CType *

typeP

)

Used to determine the size of the array specified.

Parameters

[in]

typeP

a 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;

setP = mdlCExpression_initializeSet (VISIBILITY_CALCULATOR, 0, true);
typeP = mdlCExpression_getType (TYPECODE_INT);
typeP = mdlCExpression_typeArray (setP, typeP, 10);

mdlCExpression_symbolPublish (setP, "publishedArray", SYMBOL_CLASS_VAR, typeP, publishedArray);

count = mdlCExpression_getArraySize (typeP);
for (i = 0; i < count; i++)
    {
    char         expression [80];       // CHAR_OK

    sprintf (expression, "publishedArray [%d]", i);
    mdlCExpression_getValue (&value, NULL, expression, VISIBILITY_CALCULATOR);
    printf ("the result is %d\n", value.val.valLong);
    }

mdlCExpression_freeSet (setP);

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]

typeCode

is 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]	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.

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

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

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]

typeP

points 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]

typeP

points 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]

typeP

points 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]

typeP

points 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]	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.

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

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:

mdlCExpression_publishTrustedFunction (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_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]	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.

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

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

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

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]	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

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]	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

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

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;
    }
Point;

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

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

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