Caché MultiValue Query Language (CMQL) Reference
EVAL clause
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

Returns an evaluated expression value as an item.
Synopsis
EVAL "expression" [AS colname]
Description
The EVAL clause evaluates expression and returns the result as a separate item. An expression can be an expression involving numeric and string literals, variables, MVBasic functions, or field values. An expression must be enclosed in double quotes. If expression contains the name of a column, that column name is truncated to the first 50 characters.
An EVAL expression that contains a field returns the contents of the field’s itype attribute. Note that in Caché MultiValue if the value of field is a number, it is treated as a literal number and not an attribute name. For example, the itype expression "@DATE-1" evaluates 1 as a numeric literal, and thus returns yesterday's date.
You can specify a string literal as expression by enclosing it in single quotes, for example EVAL "'OK'". You can concatenate a string literal to an expression, for example EVAL "@DATE-1:' Yesterday'".
This evaluation of quoted numerics is consistent with most MultiValue implementation, with the exception of jBASE. jBASE evaluates a quoted number as an itype attribute name, and attempts to return the attribute contents.
Postfix Operators
An EVAL expression can contain postfix operators, such as the substring extraction operator [n,m]. The following example extracts a substring consisting of the first 3 characters of the specified @ID values:
LIST VOC "BASIC" "ASSOC" EVAL "@ID[1,3]"
It returns BAS and ASS.
You can specify multiple postfix operators. They are evaluated in the order specified. The following example uses two postfix operators. The first ([1,3]) extracts a substring consisting of the first 3 characters of the specified @ID values; the second ([2,99]) extracts a substring from that substring consisting of the second through 99th characters:
LIST VOC "BASIC" "ASSOC" EVAL "@ID[1,3][2,99]"
It returns AS and SS.
The number of sequential postfix operators is unlimited.
AS clause
The optional AS clause lets you assign a column name to the resulting column. This colname may be supplied with quote delimiters ("my text"), which permits the column heading to contain blank spaces or other special characters. If no special characters are included, colname delimiters are not required. Column headings are case-sensitive.
If you do not specify an AS clause, the expression is used as the column header. The AS clause cannot specify a blank column heading. To display an EVAL column with no column heading, use DISPLAY.NAME "\", instead of the AS keyword. To display a column heading that contains literal quote characters, use a DISPLAY.NAME clause such as the following (DISPLAY.NAME \survey "yes" answers\), instead of the AS keyword.
Examples
The following example evaluates an arithmetic operation on a variable value. EVAL returns a date one week from the current date. It uses the AS clause to assign a name to this calculated date column:
LIST VOC WITH @ID LIKE Q... EVAL "@DATE+7" AS "Next Week"
returns:
VOC......... Next Week.
 
Q            15513
QSELECT      15513
QUIT         15513
 
3 Items listed.
The following example uses EVAL to specify a dictionary entry by position (rather than name) using the @RECORD variable. The following two statements are equivalent:
LIST VOC EVAL "@RECORD<4>" AS "Field4" WITH EVAL "@RECORD<4>"
LIST VOC F4 DISPLAY.NAME "Field4" WITH F4
Note the use of the AS keyword and the DISPLAY.NAME clause to assign a column heading to the specified field for each statement.
The following example uses EVAL to return the length of each field’s @ID name, using the MVBasic SUBR function to call the LENS (length) system function:
LIST VOC EVAL "SUBR('-LENS',@ID)" AS "NameLength"