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.
- 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.
Do not use double-quotes:
If you do not use a Historical tag ID, but use either
a point ID or GetHistTagID(P)
.
- 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. |