{"id":9383,"date":"2016-02-16T15:19:38","date_gmt":"2016-02-16T07:19:38","guid":{"rendered":"http:\/\/localhost\/help\/?page_id=9383"},"modified":"2026-01-29T16:43:26","modified_gmt":"2026-01-29T08:43:26","slug":"calculation-syntax","status":"publish","type":"page","link":"https:\/\/oihelp.corporate.ifs.com\/help\/p2-server\/calculations\/calculation-syntax\/","title":{"rendered":"Calculation Overview and Syntax"},"content":{"rendered":"\n

Note<\/strong>: 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 IFS OI Explorer trend.\u00a0<\/p>\n

Calculation Editor<\/h2>\n

A calculation editor is available in both IFS OI Server Management and IFS OI Explorer, to make constructing, testing, and debugging calculations easier.<\/p>\n

Read more: Using the Calculation Editor<\/a>\u00a0<\/p>\n

How To Call Functions<\/h2>\n

All functions take\u00a0the following form: FunctionName(arguments)<\/strong><\/p>\n

All functions must be called using the () even if the function takes no arguments. E.g. Time<\/a>(). This is a change from v2.6.<\/p>\n

Note that function names and arguments are not case sensitive.<\/p>\n

Input arguments are separated with commas, and all have a dimension<\/a>, <\/em>data type<\/a>, <\/em>and behaviour <\/a>- these are described below and are listed separately in each function specification.\u00a0<\/p>\n

In the function specification, square brackets [ ] \u00a0are used to indicate an optional input. The comma associate with the optional argument is included inside the square brackets.<\/p>\n

\"\"<\/a><\/p>\n

The calculation engine evaluates the arguments\u00a0first and then calls the function.
\nExample: For\u00a0Abs(2-5)<\/strong>, the calculation engine\u00a0will evaluate 2-5<\/em> to calculate -3<\/em>, and then call the Abs()<\/a> function with the first argument\u00a0as -3<\/em>. \u00a0To override this behaviour, use the\u00a0Sampling<\/a>() or the Xyz_Sampled() functions.<\/p>\n

A\u00a0function is only executed if the supplied input arguments\u00a0match the expected parameter specifications. E.g.\u00a0If a function expects an Integer but a String is supplied, the function will return an error and it will not be executed.\u00a0<\/p>\n

Comments in Calculations<\/h2>\n

To add a comment to a calculation, use \/\/<\/strong><\/span>\u00a0at the start of each line containing a comment.
\nComments can be used to add notes about a calculation and are not parsed by the calculation engine.
\nNote that these are not the same as standard comments<\/a> entered in Server and Explorer, and are only visible in the calculation editor.\u00a0<\/p>\n

Tag and Entity Name Syntax\u00a0{ }<\/h2>\n

In 2.6, the TAG, TAGNAME, ENTITY, and SAMPLING functions were used to denote tags in expressions.\u00a0<\/p>\n

Curly braces { } allow tags and datasets to be used without requiring a function call. This syntax also\u00a0supports specifying overriding parameters which can modify the sampling parameters\u00a0on the dataset\/tag fetch.<\/p>\n

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}<\/strong><\/p>\n

Here are some examples:<\/p>\n\n\n\n\n\n\n
2.6<\/strong><\/td>\n4.4<\/strong><\/td>\n<\/tr>\n
TAG(tagname)[samplemethod=average,sampleinterval=20]<\/td>\n{tagname,sampleMethod=\"average\",sampleInterval={du'00:00:20'}}<\/td>\n<\/tr>\n
SAMPLING(tagname,\"Average\",20)<\/td>\n{tagname,sampleMethod=\"average\",sampleInterval={du'00:00:20'}}<\/td>\n<\/tr>\n
SAMPLING(tagname*1200)<\/td>\n{tagname}*1200<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Entity and Attribute Names<\/strong><\/p>\n

When specifying a full entity-attribute pair, the following standard syntax applies everywhere in Server and Explorer:<\/p>\n

EntityName[<\/strong>TemplateName]:<\/strong>AttributeName!<\/strong>AttributeValueName<\/span><\/p>\n\n\n\n\n\n
[ ]<\/strong><\/td>\nTemplate names<\/em> are enclosed in square brackets.<\/td>\n<\/tr>\n
:<\/strong><\/td>\nAttribute names<\/em> are preceded with a colon.<\/td>\n<\/tr>\n
!<\/strong><\/td>\nAttribute value names<\/em> are preceded with an exclamation mark.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Remember that within calculations, the name must be enclosed within curly brackets:<\/p>\n

{<\/strong>EntityName[<\/strong>TemplateName]:<\/strong>AttributeName!<\/strong>AttributeValueName}<\/strong><\/span><\/p>\n

Example:\u00a0{<\/strong>Archer[<\/strong>Oil Producing Well]:<\/strong>Status!Actual}<\/strong><\/span><\/p>\n

Data Type<\/h2>\n

All function parameters, results, and context variables are strongly-typed values, meaning they represent a value of a specific data type<\/a>. The type indicates what operations are allowed to be performed on a value. The available data\u00a0types are:<\/p>\n\n\n\n\n\n\n\n\n\n\n\n\n
Data\u00a0Type<\/b><\/span><\/td>\nOptions\/Format\/Usage<\/b><\/span><\/td>\nExample<\/b><\/span><\/td>\n<\/tr>\n
Boolean<\/td>\nThe options are: true, false<\/td>\n\u00a0true<\/td>\n<\/tr>\n
DateTime<\/td>\n\n

The following formats are accepted:<\/p>\n

{utc'yyyy-MM-dd'}
\n{utc'yyyy-MM-dd HH:mm'}
\n{utc'yyyy-MM-dd HH:mm:ss'}
\n{utc'yyyy-MM-dd HH:mm:ss.fff'}<\/p>\n

The \"utc\" prefix must be used in all cases.<\/p>\n<\/td>\n

\n

{utc'2016-02-17 16:52'}<\/p>\n<\/td>\n<\/tr>\n

Decimal<\/td>\n[+|-][digits][.[digits]]
\nThere must always be a decimal point and at least 1 decimal place specified.\u00a0<\/td>\n		-1.2<\/td>\n<\/tr>\n
Duration<\/td>\n\n

Duration format. The following formats are accepted:\u00a0<\/p>\n

{du'[-]hh:mm'}
\n{du'[-]hh:mm:ss'}
\n{du'[-]hh:mm:ss.fff'}
\n{du'D.HH:MM:SS'}<\/p>\n

Note<\/strong>: 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\u00a0sampleinterval=20, it is now expressed as\u00a0sampleInterval={du'00:00:20'}<\/strong>.<\/p>\n<\/td>\n

\n

{du'01:00'}<\/p>\n

{du'-01:02:03'}<\/p>\n

{du'-01:02:03.456'}<\/p>\n

{du'5.12:30:00'}<\/p>\n<\/td>\n<\/tr>\n

Error<\/td>\n\u00a0This cannot be written by the calculation author, but rather is passed to the function by the data itself.<\/td>\n\u00a0<\/td>\n<\/tr>\n
Expression<\/td>\nAnything that can be parsed by the calculation engine, including tag names, mathematical expressions, and other calculations.
\nNote<\/strong>: This is not strictly a data type, but it returns one of the other data types listed here.<\/td>\n		2+2
\ntagname<\/td>\n<\/tr>\n
Integer<\/td>\n[+|-][digits]
\nMust not contain a decimal point.<\/td>\n		1<\/td>\n<\/tr>\n
Null<\/td>\nNo value<\/td>\n\u00a0null<\/td>\n<\/tr>\n
String<\/td>\n\n

There are 3 ways of expressing strings as they sometimes need to be nested. These are:<\/p>\n

    \n
  • Surrounded by (straight) quotation marks \" \"<\/li>\n
  • Surrounded by (straight) single quotes ' '\u00a0<\/li>\n
  • Str()<\/li>\n<\/ul>\n

    Note<\/strong>: Escape sequences are not supported.<\/p>\n

    IMPORTANT<\/strong><\/span>: 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 IFS OI Explorer trend.\u00a0<\/p>\n<\/td>\n

\"my\u00a0string\"
\n'my string'
\nStr(my string)<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Dimension<\/h2>\n

An argument passed in to a function can be of the following types:<\/p>\n\n\n\n\n\n\n\n\n\n
Dimension<\/b><\/span><\/td>\nDefinition<\/b><\/span><\/td>\nExample<\/b><\/span><\/td>\n<\/tr>\n
Collection<\/td>\nA collection of Variable Values. Usually fetched tag values are expressed this way.<\/td>\n\u00a0<\/td>\n<\/tr>\n
MultiCollection<\/td>\nA list of Collections, which can be returned by DDxyz() functions.<\/td>\n\u00a0<\/td>\n<\/tr>\n
Error<\/td>\nThis means that the argument does not contain a value; rather the argument\u00a0itself is an error that is returned from the datasource. E.g. For\u00a0a tag fetch, it is possible that a historian will return 1, 2, error, 4. In the calculation engine,\u00a0this could be represented as a Collection which contains 4 data\u00a0types: 1 (Integer), 2 (Integer), (Error), 4 (Integer). However, if the tag doesn\u2019t exist at all then we won\u2019t get any values for it, and in this case an adaptor could return an Error dimension to indicate that the tag is completely missing.<\/td>\n\u00a0<\/td>\n<\/tr>\n
Expression<\/td>\nAnything that can be parsed by the calculation engine, including tag names, mathematical expressions, and other calculations.
\nNote<\/strong>: This is not strictly a dimension, but it returns one of the other dimensions listed here.<\/td>\n		2 + 2
\n{tagname}<\/td>\n<\/tr>\n
Matrix<\/td>\nA group\u00a0of values in a tabular format, organized in rows and columns. Datasets are expressed this way.<\/td>\n\u00a0<\/td>\n<\/tr>\n
SingleValue<\/td>\nThe 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.<\/td>\n\u00a0<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Behaviour<\/h2>\n

Arguments in a function call exhibit one of the following behaviours:<\/p>\n\n\n\n\n\n\n
Behaviour<\/strong><\/td>\nDefinition<\/strong><\/td>\n<\/tr>\n
Required<\/td>\nThe argument is mandatory. If not supplied, the function call will return an error.<\/td>\n<\/tr>\n
Optional (0..1)<\/td>\nThe\u00a0argument 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.<\/td>\n<\/tr>\n
Optional (0..n)<\/td>\nAn\u00a0argument 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 \u00a0acceptable, depending on the specification of the function.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Context Parameters<\/h2>\n

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.\u00a0<\/p>\n

Context parameters in expressions can be accessed the following way: param[parameterName]<\/strong>.\u00a0<\/p>\n

For example, you can go to IFS OI Explorer, create a new trend and add the following expression to it: Integer(param[sampleInterval])<\/strong><\/p>\n

This will return the value of the sample interval parameter from the context (which is of type duration<\/em>) and then convert it to an integer<\/em> so that Explorer can trend it. In a default trend that has the sampleInterval of 1 day,\u00a0this expression would give you\u00a0a flat trend with a constant value of 86,400.<\/p>\n

Tag Fetches<\/h3>\n

These context parameters are supplied by the consuming application (e.g. IFS OI Explorer).<\/p>\n\n\n\n\n\n\n\n
Context Parameter<\/b><\/td>\nFormat\/Options<\/b><\/td>\nTo get the current value, use...<\/b><\/td>\n<\/tr>\n
Start Time<\/td>\nSpecified as a DateTime\u00a0(see Data\u00a0Type<\/a> above)<\/td>\nparam[startTime]<\/td>\n<\/tr>\n
End Time<\/td>\nSpecified as a DateTime\u00a0(see Data\u00a0Type<\/a> above)<\/td>\nparam[endTime]<\/td>\n<\/tr>\n
Sample Method<\/td>\nOne of the following strings: Raw, Average, LastKnownValue, LinearInterpolate<\/td>\nparam[sampleMethod]<\/td>\n<\/tr>\n
Sample Interval<\/td>\nSpecified as a duration (see Data\u00a0Type<\/a> above)<\/td>\nparam[sampleInterval]<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Dataset\u00a0Fetches<\/h3>\n

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 IFS OI Explorer.<\/p>\n

Overriding Context Parameters<\/h3>\n

You can override context parameters in the following ways:<\/p>\n\n\n\n\n\n
Override using...<\/b><\/td>\nDescription<\/b><\/span><\/td>\n<\/tr>\n
Sampling<\/a>()<\/td>\nThis function is a shortcut that allows you to override only the sampleMethod and sampleInterval context parameters.
\nE.g. \u00a0Sampling(\u2026, \"LastKnownValue\", {du'01:00'})<\/span><\/td>\n<\/tr>\n
{ }<\/td>\nThe 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:
\n{myTag, startTime = param[endTime]}<\/span><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

 <\/p>\n

\n

Changes from version 2.6<\/h2>\n

Some changes have been made from v 2.6 to standardise and simplify the functions and keywords.\u00a0<\/p>\n

Renamed Functions and Keywords<\/h3>\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
In v2.6:<\/strong><\/td>\nRenamed in\u00a0v4 to:<\/strong><\/td>\n<\/tr>\n<\/thead>\n
ACCUM()<\/td>\nSum_Sampled<\/a>()<\/td>\n<\/tr>\n
AVG()<\/td>\nAverage<\/a>()<\/td>\n<\/tr>\n
HIST_AVERAGE()<\/td>\nAverage_Sampled<\/a>()<\/td>\n<\/tr>\n
HIST_CONTINUOUSMAX()<\/td>\nContinuousMax_Sampled<\/a>()<\/td>\n<\/tr>\n
Hist_ContinuousMin()<\/td>\nContinuousMin_Sampled<\/a>()<\/td>\n<\/tr>\n
HIST_MAX()<\/td>\nMax_Sampled<\/a>()<\/td>\n<\/tr>\n
HIST_Min()<\/td>\nMin_Sampled<\/a>()<\/td>\n<\/tr>\n
HIST_TIMEWEIGHTEDAVERAGE()<\/td>\nTimeWeightedAverage_Sampled<\/a>()<\/td>\n<\/tr>\n
INTEGRAL()<\/td>\nIntegral_Sampled<\/a>()<\/td>\n<\/tr>\n
NUMSAMPLES()<\/td>\nCount_Sampled<\/a>()<\/td>\n<\/tr>\n
VALUEAT()<\/td>\nValueAt_Sampled<\/a>()<\/td>\n<\/tr>\n
TIME<\/td>\nTime<\/a>()<\/td>\n<\/tr>\n
THIS<\/td>\nEntity<\/a><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Deprecated Functions<\/h3>\n\n\n\n\n\n\n
2.6<\/strong><\/td>\nFrom v4.3.2, use this:<\/strong><\/td>\n<\/tr>\n
MOD<\/td>\n%<\/a><\/td>\n<\/tr>\n
POWER<\/td>\n**<\/a><\/td>\n<\/tr>\n
TAG()
\nTAGNAME
\nTAGNAME[]
\nENTITY()<\/td>\n		\n

{ }<\/a>\u00a0<\/p>\n

(See Tag Syntax<\/a> above)<\/p>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Deprecated Keywords<\/h3>\n\n\n\n\n\n\n\n\n
2.6<\/strong><\/td>\nNote<\/strong><\/td>\n<\/tr>\n
EP_ATTRIBUTENAME<\/td>\nN\/A (this is now obsolete - underlying value is already resolved)<\/td>\n<\/tr>\n
EP_PROPERTY<\/td>\nN\/A (this is now obsolete - underlying value is already resolved)<\/td>\n<\/tr>\n
EP_TEMPLATE<\/td>\n\u00a0<\/td>\n<\/tr>\n
EP_SESSIONVAR<\/td>\n\u00a0<\/td>\n<\/tr>\n
EP_USERVAR<\/td>\n\u00a0<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Release History<\/h2>\n