MACRO API

Evaluating Arezzo expressions with the MACRO API

An Arezzo expression may have an associated context (a particular MACRO subject, visit, eForm or question), which determines how terms are interpreted.  For example, the Arezzo keywords "visit", "form", "question" can only be evaluated in the context of a particular visit, eForm or question. Similarly, study terms such as "person:trialsite" or "person:personid" can only be evaluated in the context of a particular MACRO subject.

Some Arezzo expressions can be evaluated without an associated context, because they are not dependent on subject data, for example:

·       2 + 3

·       len( 'sausages' )

·       datenow + 5 years

The ArezzoEvaluateSubject method evaluates a list of expressions at the subject level for a specified MACRO subject.

The ArezzoEvaluate method can be called with XML that can contain expressions within any specified MACRO context (subject, visit, eForm or question), as well as expressions to be evaluated with no context.

Evaluate a list of Arezzo expressions for a specified MACRO subject.

Input

Output

·       True or False indicating overall success or failure

·       results - list of evaluation results and whether each succeeded or failed.

The ArezzoResult object contains two properties:

·       Success - boolean, True if expression evaluated successfully, or false otherwise

·       Result – string, the value of the evaluated expression (may be empty string if evaluation failed)

There will be one ArezzoResult object in the returned list corresponding to each expression in the input list.

The returned value of the ArezzoEvaluateSubject() call will be False if any of the Study name, Site or Subject ID parameters is invalid, or if the subject does not exist, or if an unexpected error occurred.

Return to top

Evaluate Arezzo expressions at any level of a specified MACRO subject.

Input

Output

·       Return code indicating success or nature of failure

·       results - XML string containing list of evaluation results, and details of any errors that occurred

Return to top

ArezzoEvaluate return codes

The ArezzoEvaluate routine returns an integer code as type ArezzoEvaluateResult indicating the result, as listed in the table below:

Note that even with a result of "Success", some errors may occur during evaluation, but these are listed separately in the output XML, as described below.

Return to top

Arezzo Expressions XML

A group of expressions is represented by a top level <ArezzoExpressions> tag, with an <ArezzoExpr> tag for each expression. Each Arezzo expression has an optional identifying code, to enable easier matching with the list of evaluation results.

Special Characters

Note that if an expression contains no "special" XML characters, it can be represented as the value of the "Expr" attribute. Otherwise, if it contains characters such as &, <, > etc., it must be written as CDATA.

No Context

The following XML will evaluate three expressions with no MACRO context, i.e. with no MACRO subject loaded:

The output will be as follows:

Return to top

MACRO Context

Expression context may be added by specifying a MACRO subject, optionally with visits, eForms and questions, as for the InputSubjectData and GetSubjectData calls. Arezzo expressions will be evaluated at the level at which they appear. For example:

If an Arezzo expression is at the question level, the term me:value automatically refers to the current stored value of the question.

The expressions will be evaluated as follows:

·       A1 – No context

·       SubjID, SubjDetails – At subject level for subject Demostudy40/london/1

·       VName – At visit level, for the visit Screening

·       FName, Age – At eForm level, with the eForm's responses loaded, for the eForm Cover in the Screening visit

·       Abn – At question level, where me:value refers to current question value

The output XML will be as follows:

Evaluation errors

In ArezzoEvaluate(), if an expression cannot be evaluated (e.g. invalid syntax or missing data), the returned Value will be empty, the same as in MACRO Web DE. For example, for this input XML:

The output will be:

MACRO subject errors

If errors occur while loading a subject or its eForms, the errors will be reported in a separate "Errors" section. For example, for this input XML:

The output will be:

If the Id is changed to a valid identifier, the output would be as follows:

Return to top

Check the syntax of a single Arezzo expression.

Input

Output

·       True if input string represents a syntactically correct Arezzo expression, or False otherwise

This routine parses the specified Arezzo expression and returns True if it parses successfully. This is a basic syntax check – there is no semantic checking, nor are there any checks on referenced visit, eForm or question names.

This API call uses the Arezzo 7 parser used in Web Data Entry, so the result returned here may be slightly different from the syntax checker in the Study Definition module, which uses the Arezzo 5 parser.

Return to top