IExpressionEval::Eval Method [C++]

Article
11/12/2009

Use this method to evaluate an expression.

Definition

[C++]

HRESULT IExpressionEval::Eval(longnExprID,
 IDictionary*pDictObjs,
VARIANT* pvResult);

[Visual Basic]

Function Eval(nExprID As Long,
 pDictObjs As Object) As Variant

Parameters

nExprID[C++]
[in] A long that contains the unique identifier for the expression in the expression store.
nExprID[Visual Basic]
[in] A Long that contains the unique identifier for the expression in the expression store.
pDictObjs[C++]
[in] A pointer to the IDictionary interface of a Dictionary object that contains a set of profiles.
pDictObjs[Visual Basic]
[in] A Dictionary object that contains a set of profiles.
pvResult[C++]
[out, retval] A pointer to a VARIANT indicating the result of evaluating the expression in the given context.

Return Values

[C++] This method returns an HRESULT indicating whether the method completed successfully. See the Error Values section for more details. The result of evaluating the expression is contained in the pvResult parameter. The result may be TRUE, FALSE, or NULL. NULL indicates the expression could not be evaluated.

[Visual Basic] This method returns a Variant indicating the result of evaluating the expression in the specified context. The result may be True, False, or Nothing. Nothing indicates the expression could not be evaluated.

Error Values

[C++] This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

[Visual Basic] This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors, and the standard COM errors with special meanings, that this method can return.

Constant	Value	Description
E_EXPR_BADCONNECTION	[C++] 0x8110001F [Visual Basic] &H8110001F	Invalid connection
E_EXPR_BADEXPRID	[C++] 0x8110000A [Visual Basic] &H8110000A	Invalid expression ID specified
E_EXPR_NOCONNECTIONSTRING	[C++] 0x8110000D [Visual Basic] &H8110000D	No connection string specified
E_EXPR_NOTFOUND	[C++] 0x81100012 [Visual Basic] &H81100012	Could not find the specified expression ID, nExprID, in the expression store

[C++] Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[Visual Basic] Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Expressions must be pre-compiled and loaded into the expression cache before being evaluated. The Eval method first checks the expression cache for the expression, and if not found, loads the expression from the expression store. Use the LoadExpr or LoadAll method to preload an expression into the expression cache and improve evaluation performance.

An expression is evaluated against data contained in a set of profiles. This set of profiles is referred to as an evaluation context. A new evaluation context is generated by the Eval method using the Dictionary object. The Eval method discards the new context after completing the evaluation. This process is not efficient if many expressions must be evaluated against the same context.

If an evaluation context will be used across multiple expressions, create a context in the context cache using the CreateEvalContext method. Use the EvalInContext method to evaluate expressions in this new common context.

The Connect method must be called before using the Eval method.

[C++]

The pvResult parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.