ON THIS PAGE:
Calculation Editor
A calculation editor is available in both P2 Server Management and P2 Explorer, to make constructing, testing, and debugging calculations easier.
How To Call Functions
All functions take the following form: FunctionName(arguments)
All functions must be called using the () even if the function takes no arguments. E.g. Time(). This is a change from v2.6.
Note that function names and arguments are not case sensitive.
Input arguments are separated with commas, and all have a dimension, data type, and behaviour - these are described below and are listed separately in each function specification.
In the function specification, square brackets [ ] are used to indicate an optional input. The comma associate with the optional argument is included inside the square brackets.
The calculation engine evaluates the arguments first and then calls the function.
Example: For Abs(2-5), the calculation engine will evaluate 2-5 to calculate -3, and then call the Abs() function with the first argument as -3. To override this behaviour, use the Sampling() or the Xyz_Sampled() functions.
A function is only executed if the supplied input arguments match the expected parameter specifications. E.g. If a function expects an Integer but a String is supplied, the function will return an error and it will not be executed.
Comments in Calculations
To add a comment to a calculation, use // at the start of each line containing a comment.
Comments can be used to add notes about a calculation and are not parsed by the calculation engine.
Note that these are not the same as standard comments entered in Server and Explorer, and are only visible in the calculation editor.
Tag and Entity Name Syntax { }
In 2.6, the TAG, TAGNAME, ENTITY, and SAMPLING functions were used to denote tags in expressions.
Curly braces { } allow tags and datasets to be used without requiring a function call. This syntax also supports specifying overriding parameters which can modify the sampling parameters on the dataset/tag fetch.
Note: Whenever you use a tag or entity name as a parameter within a function call, the tag or entity name must be wrapped in curly braces i.e. {tagname}
Here are some examples:
| 2.6 | 4.4 |
| TAG(tagname)[samplemethod=average,sampleinterval=20] | {tagname,sampleMethod="average",sampleInterval={du'00:00:20'}} |
| SAMPLING(tagname,"Average",20) | {tagname,sampleMethod="average",sampleInterval={du'00:00:20'}} |
| SAMPLING(tagname*1200) | {tagname}*1200 |
Entity and Attribute Names
When specifying a full entity-attribute pair, the following standard syntax applies everywhere in Server and Explorer:
EntityName[TemplateName]:AttributeName!AttributeValueName
| [ ] | Template names are enclosed in square brackets. |
| : | Attribute names are preceded with a colon. |
| ! | Attribute value names are preceded with an exclamation mark. |
Remember that within calculations, the name must be enclosed within curly brackets:
{EntityName[TemplateName]:AttributeName!AttributeValueName}
Example: {Archer[Oil Producing Well]:Status!Actual}
Data Type
All function parameters, results, and context variables are strongly-typed values, meaning they represent a value of a specific data type. The type indicates what operations are allowed to be performed on a value. The available data types are:
| Data Type | Options/Format/Usage | Example |
| Boolean | The options are: true, false | true |
| DateTime |
The following formats are accepted: {utc'yyyy-MM-dd'} The "utc" prefix must be used in all cases. |
{utc'2016-02-17 16:52'} |
| Decimal | [+|-][digits][.[digits]] There must always be a decimal point and at least 1 decimal place specified. |
-1.2 |
| Duration |
Duration format. The following formats are accepted: {du'[-]hh:mm'} Note: Some functions (e.g. Sampling()) will accept duration expressed in other formats. This is described in the relevant function, where applicable. For most functions, however, this notation has changed from expressing duration in seconds. E.g. Previously, where sample interval was expressed as sampleinterval=20, it is now expressed as sampleInterval={du'00:00:20'}. |
{du'01:00'} {du'-01:02:03.456'} |
| Error | This cannot be written by the calculation author, but rather is passed to the function by the data itself. | |
| Expression | Anything that can be parsed by the calculation engine, including tag names, mathematical expressions, and other calculations. Note: This is not strictly a data type, but it returns one of the other data types listed here. |
2+2 tagname |
| Integer | [+|-][digits] Must not contain a decimal point. |
1 |
| Null | No value | null |
| String |
There are 3 ways of expressing strings as they sometimes need to be nested. These are:
Note: Escape sequences are not supported. IMPORTANT: When copy-pasting examples, sometimes " and ' may be substituted with curly quotes. In these cases, you will have to manually change them to straight quotes to get them to work in places such as the P2 Explorer trend. |
"my string" 'my string' Str(my string) |
Dimension
An argument passed in to a function can be of the following types:
| Dimension | Definition | Example |
| Collection | A collection of Variable Values. Usually fetched tag values are expressed this way. | |
| MultiCollection | A list of Collections, which can be returned by DDxyz() functions. | |
| Error | This means that the argument does not contain a value; rather the argument itself is an error that is returned from the datasource. E.g. For a tag fetch, it is possible that a historian will return 1, 2, error, 4. In the calculation engine, this could be represented as a Collection which contains 4 data types: 1 (Integer), 2 (Integer), (Error), 4 (Integer). However, if the tag doesn’t exist at all then we won’t get any values for it, and in this case an adaptor could return an Error dimension to indicate that the tag is completely missing. | |
| Expression | Anything that can be parsed by the calculation engine, including tag names, mathematical expressions, and other calculations. Note: This is not strictly a dimension, but it returns one of the other dimensions listed here. |
2 + 2 {tagname} |
| Matrix | A group of values in a tabular format, organized in rows and columns. Datasets are expressed this way. | |
| SingleValue | The smallest discrete datum. Hardcoded values are usually expressed as a SingleValue. E.g. In the expression "{myTag} + 5", 5 would be parsed as a SingleValue which contains an Integer argument value type with a value of 5. |
Behaviour
Arguments in a function call exhibit one of the following behaviours:
| Behaviour | Definition |
| Required | The argument is mandatory. If not supplied, the function call will return an error. |
| Optional (0..1) | The argument is not mandatory. It may be left out of a function call, however a blank space is not acceptable and will produce an error. If supplied, only 1 value is acceptable. |
| Optional (0..n) | An argument is not mandatory. It may be left out of a function call, however a blank space is not acceptable and will produce an error. If supplied, 1 or more values are acceptable, depending on the specification of the function. |
Context Parameters
A context parameter is a reserved parameter designed to allow a function to retrieve a certain type of data. Context parameters are so-called because the parameter available to a function depends on the function's context. E.g. The SampleMethod parameter is required for tag fetches but not for datasets.
Context parameters in expressions can be accessed the following way: param[parameterName].
For example, you can go to P2 Explorer, create a new trend and add the following expression to it: Integer(param[sampleInterval])
This will return the value of the sample interval parameter from the context (which is of type duration) and then convert it to an integer so that Explorer can trend it. In a default trend that has the sampleInterval of 1 day, this expression would give you a flat trend with a constant value of 86,400.
Tag Fetches
These context parameters are supplied by the consuming application (e.g. P2 Explorer).
| Context Parameter | Format/Options | To get the current value, use... |
| Start Time | Specified as a DateTime (see Data Type above) | param[startTime] |
| End Time | Specified as a DateTime (see Data Type above) | param[endTime] |
| Sample Method | One of the following strings: Raw, Average, LastKnownValue, LinearInterpolate | param[sampleMethod] |
| Sample Interval | Specified as a duration (see Data Type above) | param[sampleInterval] |
Dataset Fetches
The context parameters available to dataset fetches depend on the query being used to create the dataset. You can usually find these parameters when adding a dataset in P2 Explorer.
Overriding Context Parameters
You can override context parameters in the following ways:
| Override using... | Description |
| Sampling() | This function is a shortcut that allows you to override only the sampleMethod and sampleInterval context parameters. E.g. Sampling(…, "LastKnownValue", {du'01:00'}) |
| { } | The custom {} syntax allows you to override any context parameter and to add new ones, but these context parameters will always apply only to the tag that is being fetched. See above for details on how to use this. For example, this will make a single-point fetch: {myTag, startTime = param[endTime]} |
Changes from version 2.6
Some changes have been made from v 2.6 to standardise and simplify the functions and keywords.
Renamed Functions and Keywords
| In v2.6: | Renamed in v4 to: |
| ACCUM() | Sum_Sampled() |
| AVG() | Average() |
| HIST_AVERAGE() | Average_Sampled() |
| HIST_CONTINUOUSMAX() | ContinuousMax_Sampled() |
| Hist_ContinuousMin() | ContinuousMin_Sampled() |
| HIST_MAX() | Max_Sampled() |
| HIST_Min() | Min_Sampled() |
| HIST_TIMEWEIGHTEDAVERAGE() | TimeWeightedAverage_Sampled() |
| INTEGRAL() | Integral_Sampled() |
| NUMSAMPLES() | Count_Sampled() |
| VALUEAT() | ValueAt_Sampled() |
| TIME | Time() |
| THIS | Entity |
Deprecated Functions
| 2.6 | From v4.3.2, use this: |
| MOD | % |
| POWER | ** |
| TAG() TAGNAME TAGNAME[] ENTITY() |
(See Tag Syntax above) |
Deprecated Keywords
| 2.6 | Note |
| EP_ATTRIBUTENAME | N/A (this is now obsolete - underlying value is already resolved) |
| EP_PROPERTY | N/A (this is now obsolete - underlying value is already resolved) |
| EP_TEMPLATE | |
| EP_SESSIONVAR | |
| EP_USERVAR |
Release History
- Calculation Overview and Syntax 4.6.5
- Added "MultiCollection" to the list of Dimensions.
- Calculation Overview and Syntax 4.0
- Initial version