1.2. Expression Editor Operations

Edit expression operations are available in the Edit Expression window.

  • Arithmetic operations.
  • Bitwise operations.
  • Alarm functions.
  • Conversion operations.
  • Historian calls.
  • Logical operations.
  • Quality operations.
  • Relational operations.
  • Scientific operations.
  • String functions
  • Timestamp operations.
  • Other operations.

Arithmetic Operations

Operation Expression Result
- Returns Difference between X and Y.
Format <expr1>-<expr2>
* Returns Product of X and Y.
Format <expr1>*<expr2>
/ Returns Quotient of X and Y.
Format <expr1>/<expr2>
Note: The result of dividing two integers in an expression will be an integer. If you want the result to be a floating point, multiply the numerator by 1.0 before dividing. Example POINTA is set to 6. POINTB is set to 4. Results: POINTA/POINTB = 1 (POINTA*1.0)/POINTB = 1.5
^ Returns Value of X raised to the power of Y.
Format <expr1>^<expr2>
| Will be substituted by double quotes in an expression.
+ Returns Sum of X and Y.
Format <expr1>+<expr2>
ABS Returns Absolute value of X.
Format ABS(expr) Example ABS(-2.6) returns 2.6
CEIL Returns Nearest integer greater than or equal to X.
Format CEIL (expr) Example CEIL(2.3) returns 3 CEIL(-2.3) returns -2
FLR Returns Nearest integer less than or equal to X.
Format FLR(expr) Examples FLR(2.6) returns 2 FLR(-2.6) returns -3
MAX Returns Maximum comparing X and Y.
Format <expr1> MAX <expr2> Example 3 MAX 4 returns 4
MIN Returns Minimum comparing X and Y.
Format <expr1> MIN <expr2> Example 3 MIN 4 returns 3.
MOD Returns Value of X modulo Y.
Format <expr1> MOD <expr2> Example 9 MOD 8 returns 1
RND Returns Integer nearest to X.
Format RND(expr) Example RND(2.6) returns 3 RND(-2.6) returns -3
SQR Returns Square root of X.
Format SQR(<expr>)
TRUNC Returns Value of X with the fractional part removed; the result is its integer value.
Format TRUNC(expr) Examples TRUNC(2.6) returns 2 TRUNC(-2.6) returns -2

Bitwise Operations

Operation Expression Result
BAND Performs Bitwise AND of X and Y.
Format <expr1>AND<expr2>
BOR Performs Bitwise OR of X and Y.
Format <expr1>OR<expr2>
BNOT Performs Bitwise NOT of X and Y.
Format NOT<expr>
BXOR Performs Bitwise XOR of X and Y.
Format <expr1>XOR<expr2>
SHL Returns Value of X shifted left by Y bits.
Format <expr1>SHL<expr2> Example 2 SHL 1 returns  4 Note: When SHL goes out of range the: Point becomes unavailable. Point Control Pane is starred. Core status log notes that it is unavailable.
SHR Returns  Value of X shifted right by Y bits.
Format <expr1>SHR<expr2> Example 2 SHR 1 returns 1 Note: When SHR goes out of range the: Point becomes unavailable. Point Control Pane is starred. Core status log notes that it is unavailable.

Alarm functions

Function Type Expression Result
AL Returns TRUE if the point is in any Alarm or Warning state.
Format  AL(<point id>)
A1 WARNING Returns TRUE if the point is in a Warning High or Warning Low state.
Format A1(<point id>)
A2 ALARM Returns TRUE if the point is in an Alarm High or Alarm Low state.
Format A2(<point id>)
AH1 WARNING_HIGH Returns TRUE if the point is in a Warning High state.
Format AH1(<point id>)
AH2 ALARM_HIGH Returns TRUE if the point is in an Alarm High state.
Format AH2(<point id>)
AL1 WARNING_LOW Returns TRUE if the point is in a Warning Low state.
Format AL1(<point id>)
AL2 ALARM_LOW Returns TRUE if the point is in an Alarm Low state.
Format AL2(<point id>)
ANA ALARM_NOT_ACKED Returns TRUE if the point is in alarm and the alarm has not been acknowledged. Note: The ANA behavior was changed in CIMPLICITY V.6.1. Prior to V.6.1 it behaved as NACK. The global parameter PTEXP_ANA_EQ_NACK_AND_AL is available to revert ANA behavior to pre-version 6.
Format ANA(<point id>) Important: ANA is not supported for Enterprise points.
NACK Returns TRUE if the alarm has not been acknowledged, whether or not the point is in an alarm state.
Format NACK (<point id>)

Conversion operations

Function Type Expression Result
AL Returns TRUE if the point is in any Alarm or Warning state.
Format  AL(<point id>)
A1 WARNING Returns TRUE if the point is in a Warning High or Warning Low state.
Format A1(<point id>)
A2 ALARM Returns TRUE if the point is in an Alarm High or Alarm Low state.
Format A2(<point id>)
AH1 WARNING_HIGH Returns TRUE if the point is in a Warning High state.
Format AH1(<point id>)
AH2 ALARM_HIGH Returns TRUE if the point is in an Alarm High state.
Format AH2(<point id>)
AL1 WARNING_LOW Returns TRUE if the point is in a Warning Low state.
Format AL1(<point id>)
AL2 ALARM_LOW Returns TRUE if the point is in an Alarm Low state.
Format AL2(<point id>)
ANA ALARM_NOT_ACKED Returns TRUE if the point is in alarm and the alarm has not been acknowledged. Note: The ANA behavior was changed in CIMPLICITY V.6.1. Prior to V.6.1 it behaved as NACK. The global parameter PTEXP_ANA_EQ_NACK_AND_AL is available to revert ANA behavior to pre-version 6.
Format ANA(<point id>) Important: ANA is not supported for Enterprise points.
NACK Returns TRUE if the alarm has not been acknowledged, whether or not the point is in an alarm state.
Format NACK (<point id>)
VAL Returns Note: VAL converts a variable that consists of numbers in text string format to a numeric format that can be included in calculations.
Format VAL(expr)
EU_CONV Returns Converts the default raw value of a device point ID in an expression for virtual points to the engineering units value.
Format EU_CONV(Point_ID)

Historian Calls

Historian data calls and special functions that retrieve data can be used inside standard expressions.

Note:
  • If you are using the local Historian server, you can enter \\\ instead of the server name.

However, the Historian API only connects to the default server if it is on the local machine. The server name must be entered if the default server is not the local machine.

Example

\\\PROFCIMP.LEVELTSOUTH

Where

\\\ indicates the local Historian server, which would be entered as \\<local server>\ if the abbreviation was not used.

ProfCIMP.LEVELTSOUTH is a Historian tag that will be included in the expression.

  • When or when not to use double-quotes in a Historian expression is as follows.

Use double-quotes:

When Historian tags are used in the expression.

Note: Because Historian tags will be used most frequently, CIMPLICITY automatically includes double-quotes when you select a Historian function in the Expression Editor.

Do not use double-quotes:

If you do not use a Historical tag ID, but use either a point ID or GetHistTagID(P).

Note: You must remove the double quotes that are added automatically.
  • A global parameter, EXPRESSION_TRACE_LEVEL , is available to trace Historian related problems with connections and expressions
Operation Expression Result
GetHistTagID Returns A string that may be used to look up a Historian tag from the inputted point symbol.
Format GetHistTagID(P) Where P is a CIMPLICITY point ID that has a corresponding tag ID in Historian.
HistAv Retrieves Average numeric value of a Historian tab at or before the specified timestamp over the specified previous span.
Format HistAv("\\<Historian connection ID>\<TagID>",<Timestamp>,<Span>)
HistCom Retrieves Comment (String) of a Historian tag.
Format HistCom("\\<Historian connection ID>\<TagID>",<Timestamp>)
HistCount Retrieves Count value of a Historian tag at or before the specified timestamp over the specified previous span.
Format HistCount("\\<Historian connection ID>\<TagID>",<Timestamp>,<Span>)
HistDesc Retrieves Description (string) of a Historian tag.
Format HistDesc("\\<Historian connection ID>\<TagID>",<Timestamp>)
HistEU Retrieves Engineering Unit (string) of a Historian tag.
Format HistEU("\\<Historian connection ID>\<TagID>",<Timestamp>)
HistHightEU Retrieves High engineering Unit (string) of a Historian tag.
Format HistHightEU("\\<Historian connection ID>\<TagID>",<Timestamp>)
HistI Retrieves 64-bit integer value of a Historian tag at or before the specified timestamp.
Format HistI("\\<Historian connection ID>\<TagID>",<Timestamp>)
HistLowEU Retrieves Low engineering Unit (string) of a Historian tag.
Format HistLowEU("\\<Historian connection ID>\<TagID>",<Timestamp>)
HistMax Retrieves Max numeric value of a Historian tag at or before the specified timestamp over the specified previous span.
Format HistMax("\\<Historian connection ID>\<TagID>",<Timestamp>,<Span>)
HistMin Retrieves Min numeric value of a Historian tag at or before the specified timestamp over the specified previous span.
Format HistMin("\\<Historian connection ID>\<TagID>",<Timestamp>,<Span>)
HistN Retrieves Raw numeric value (double float) of a Historian tag at or before the specified timestamp.
Important: Historian batches and writes values.  HISTN reports the value whenever it sees it. Due to the batch writing, an update may not be there at the time of the request from the HISTN function. Example $LOCAL.DATETIME)INTERVAL is set to 10 causing $LOCAL.DATETIME_VARUPDATE to update 10 times per second. The HistN expression updates when it sees a reported value from Historian, which is one time every two seconds. Several $LOCAL.DATETIME_VARUPDATE updates can be missed. You can avoid seeing this behavior if you change the request by deferring for a specified amount of time, e.g. 5 seconds. Example HistN("\\\Simulation00001", $LOCAL.DATETIME_VARUPDATE - CalcSpan(0,0,0,5,0))
Format HistN("\\<Historian connection ID>\<TagID>",<Timestamp>)
HistRawAv Retrieves Raw average numeric value of a Historian tag at or before the specified timestamp over the specified previous span.
Format HistRawAv("\\<Historian connection ID>\<TagID>",<Timestamp>,<Span>)
HistRawStandDev Retrieves Standard deviation raw  numeric value of a Historian tag at or before the specified timestamp over the specified previous span.
Format HistRawStandDev("\\<Historian connection ID>\<TagID>",<Timestamp>,<Span>)
HistRawTot Retrieves Total numeric value of a Historian tag at or before the specified timestamp over the specified previous span.
Format HistRawTot("\\<Historian connection ID>\<TagID>",<Timestamp>,<Span>)
HistS Retrieves String value of a Historian tag at or before the specified timestamp.
Format HistS("\\<Historian connection ID>\<TagID>",<Timestamp>)
HistStandDev Retrieves Standard deviation numeric value of a Historian tag at or before the specified timestamp over the specified previous span.
Format HistStandDev("\\<Historian connection ID>\<TagID>",<Timestamp>,<Span>)
HistTot Retrieves Raw total numeric value of a Historian tag at or before the specified timestamp over the specified previous span.
Format HistTot("\\<Historian connection ID>\<TagID>",<Timestamp>,<Span>)

Logical operators

You can use Boolean, integer or floating point numbers for logical operations. If an expression has a non-zero value, it is TRUE; if the value is zero, it is FALSE.

Operation Expression Result
AND Performs Logical AND of X and Y.
Format <expr1>AND<expr2>
NOT Performs Logical NOT of X.
Format NOT<expr>
OR Performs Logical OR of X and Y.
Format <expr1>OR<expr2>
XOR Performs Logical XOR of X and Y.
Format <expr1>XOR<expr2>

Quality Operations

Operation Expression Result
GetQualityBit Gets Quality Bit for the specified bit index. Note: GetQualityBit retrieves the quality of the specified expression for a given bit number. The bit number ranges from 0 to 31.
Format GetQualityBit(<expression>,<bit index>)
IsAvailable Returns If expression is available.
Format IsAvailable(<expression>)
QL Retrieves The quality (64 bit integer) returned for the wrapped expression
Format QL[<expr>]

Relational operations

Operation Expression Result
EQ Returns True if X is equal to Y.
Format <expr1>EQ<expr2>
GE Returns True if X is greater than or equal to Y.
Format <expr1>GE<expr2>
GT Returns True if X is greater than Y.
Format True if X is greater than Y.
LE Returns True if X is less than or equal to Y.
Format <expr1>LE<expr2>
LT Returns True if X is less than or below Y.
Format <expr1>LT<expr2>
NE Returns True if X is not equal to Y.
Format <expr1>NE<expr2>

Scientific operations

Operation Expression Result
ACOS Returns Arc cosine (angle in radians) of  X radians.
Format ACOS(<expr>)
ASIN Returns Arc sine (angle in radians) of  X radians.
Format ASIN(<expr>)
ATAN Returns Arc tangent (angle in radians) of  X radians.
Format ATAN(<expr>)
COS Returns Cosine (angle in radians) of X radians.
Format COS(<expr>)
EXP Returns Value of e raised to the power of X. Note: EXP is the exponential (ex) value of an expression where X is the expression.
Format EXP(<expr>)
LOG Returns Natural logarithm (base e) of X.
Format LOG(<expr>)
LOG10 Returns Base 10 logarithm of X.
Format LOG10(<expr>)
SIN Returns Sine (angle in radians) of X radians.
Format SIN(<expr>)
TAN Returns Tangent (angle in radians) of  X radians.
Format TAN(<expr>)

String Functions

Operation Expression Result
InStr Returns An integer that is the  one based character position of a searched for substring's first occurrence (after the start search position) in the source string.
Comparison
Inputs Name
<Start_Pos>
<Source_String>
<Search_SubStr>
Format InStr(<Search_SubStr>, <Source_String>, <Search_SubStr>)
InStrCS Returns An integer that is the  one based character position of a searched for substring's first occurrence (after the start search position) in the source string.
Comparison
Inputs Name
<Start_Pos>
<Source_String>
<Search_SubStr>
Format InStr(<Search_SubStr>, <Source_String>, <Search_SubStr>)
Left Returns Extracts the first <Count> characters from the source strings and returns a copy of the extracted substring.
Inputs Name
<Source_String>
<Count>
Format Left(<Source_String>, <Count>)
Right Returns Extracts the last <Count> characters from the source string and returns a copy of the extracted substring.
Inputs Name
<Source_String>
<Count>
Format Right(<Source_String>,<Count>)
Mid Returns The substring that is the specified number (<Count>) of characters long and starts at the one based character position in the source string.
Inputs Name
<Source_String>
<StartPos>
<Count>
Format Mid(<Source_String>, <StartPos>, <Count>)
Trim Returns A string with the leading and trailing white space removed.
Inputs Name
<string>
Format Trim(<string>)
GetToken Returns A substring that is the 0 based token element in the string
Inputs Name
<Source_String>
<Token_Separators>
<TokenIndex0Based>
Format GetToken(<source_string>, <Token_Separators>, <TokenIndex0Based>) Example GetToken("Green.Red,Black.White",",.",2) Where Black or black is retrieved.
ToUpper Returns The string in upper case.
Inputs Name
<Source_String>
Format ToUpper(<Source_String>)
ToLower Returns The string in lower case.
Inputs Name
<Source_String>
Format ToLower(<Source_String>)
FindToken Returns Substring that is at the 1 based token index. If the token indicated is not found then the function returns 0.  
Comparison
Inputs Name
<Source_String>
<Token_Separators>
<Token_To_Find>
Format FindToken(<Source_String>,  <Token_Separators>, <Token_To_Find>) Example GetToken("Green.Red,Black.White",",.",2) Where Black or black is found.
FindTokenCS Returns Substring that is at  the 1 based token index If the token indicated is not found then the function returns 0.  
Comparison
Name
Inputs <Source_String>
<Token_Separators>
<Token_To_Find>
Format FindTokenCS(<Source_String>,  <Token_Separators>, <Token_To_Find>) Example GetToken("Green.Red,Black.White",",.",2) Where Black is found; black is not.
StrLen Returns The length of the string
Name
Inputs <Source_String>
Format StrLen(<Source_String>) Note: If a string literal is used as an argument, the trailing spaces (if any) will not be included in the string length. Example StrLen(“ABC “) will return 3, not 4.
StrArrayCat Returns The concatenation of the elements of the string array point into a single string.
Name
Inputs <Point_ID>
Format StrArrayCat(<Point_ID>) Example If MYSTR is a string array point, where MYSTR[0] = "abc", MYSTR [1] = "de", and MYSTR [2] = "fgh", StrArrayCat(MYSTR) will return abcdefgh.

Timestamp Operations

Operation Expression Result
CalcSpan Returns An unsigned 64-bit integer containing a timestamp (in decimicroseconds) that represents the span of that duration.
Format CalcSpan[<days>,<hours>,<minutes>,<seconds>,<fracsec>]
CalcStamp Returns An unsigned 64-bit integer containing the timestamp (in decimicroseconds) that represents them.
Format CalcStamp[<year>,<month>,<day>,<hour>,<minute>,<second>,<fracsec>]
TS Retrieves Timestamp returned for the wrapped expression
Format TS(<expr>)

Other Operations

Operation Expression Result
? Description Provides the ability to create an expression similar to the Basic Control Engine IIF(function).
Format "(B EQ N)" ? N:N1 Where
Explained If B equals N then use N as the resulting value, else if B is not equal to N then use N1 as the resulting value. Note: An expression setpoint procedure may contain: A complicated logical branching expression instead of a single mathematical one. Two expressions, which will be selected by the result of that logical term.
Example Create an empty project Create 2 BOOLEAN points: A, B. Do a configuration update. Start the project. Create a new CimEdit screen. Create a button. Open the button's Properties - Object dialog box. Create a Mouse Up event. Create a new procedure. Configure the new procedure as follows. Click OK. The Properties - Object dialog box closes. Save the screen. Test the screen. Result: The button will do a setpoint action based on the B point value.