Available Functions of the Calculation Server (version 23)

Knowledge Base / Version 23 / System Admin Duties / Calculation Server

updated 1 yr ago
2replies

The functions available within the Calculation Server can be categorized in three different ways:

Standard OPC Foundation aggregates
NCALC functions and operators
Custom functions developed by Canary

An example of each of these functions are included at the top of this page if the user wishes to import them into their Calculation Server. Note, these examples are taken from v21.4 which also includes Events. It is recommended to upgrade to 21.4 prior to importing these calculations.

OPC Foundation Aggregates

For most aggregates, the expression syntax is simply:

FunctionName('[TagPath]','Duration')

Whenever the calculation is triggered (whether it be 'Value Change' or 'Periodic'), the interval over which the aggregate is calculated is Now - Duration.

Starting in v21.4, a new optional parameter has been added to include a start time:

FunctionName('[TagPath]','Duration', 'startTime')

In this case, the interval used is startTime + Duration.

Duration can be expressed using a relative or actual time. For example,

1second = 1s = 00:00:01
1minute = 1m = 00:01:00
1hour = 1h = 1:00:00
1day = 1d = 1.00:00:00
1week = 1w = 7.00:00:00
1month
1year = 1y

StartTimes can also use the same syntax. For example,

Maximum2('[TagName]', '1d', 'd-7d')

finds the max daily value from 7 days ago. We use 'd' to normalize to the beginning of the day, then subtract '7d' or seven days.

Function	Description	Syntax
Average	Retrieve the average value of the data over the interval.	Average('[TagName]','Duration') Average('[TagName]','Duration','startTime')
Count	Retrieve the number of raw values over the interval.	Count('[TagName]','Duration') Count('[TagName]','Duration','startTime')
CountInStateNonZero/Zero	Retrieve the number of times a Boolean or numeric was in a non-zero/zero state using Simple Bounding Values.	CountInStateNonZero('[TagName]','Duration') CountInStateZero('[TagName]','Duration','startTime')
Delta	Retrieve the difference between the Start and End value in the interval.	Delta('[TagName]','Duration') Delta('[TagName]','Duration','startTime')
DeltaBounds	Retrieve the difference between the StartBound and EndBound value in the interval.	DeltaBounds('[TagName]','Duration') DeltaBounds('[TagName]','Duration','startTime')
DurationBad/Good	Retrieve the total duration of time in the interval during which the data is Bad/Good.	DurationBad('[TagName]','Duration') DurationGood('[TagName]','Duration','startTime')
DurationInStateNonZero/Zero	Retrieve the time a Boolean or numeric was in a non-zero/zero state using Simple Bounding Values.	DurationInStateNonZero('[TagName]','Duration') DurationInStateZero('[TagName]','Duration','startTime')
EndBound	Retrieve the value at the end of the interval using Simple Bounding Values.	EndBound('[TagName]','Duration') EndBound('[TagName]','Duration','startTime')
Interpolative	At the beginning of each interval, retrieve the calculated value from the data points on either side of the requested timestamp.	Interpolative('[TagName]','Duration') Interpolative('[TagName]','Duration','startTime')
Maximum	Retrieve the maximum raw value in the interval with the timestamp of the start of the interval.	Maximum('[TagName]','Duration') Maximum('[TagName]','Duration','startTime')
Maximum2	Retrieve the maximum value in the interval including the Simple Bounding Values.	Maximum2('[TagName]','Duration') Maximum2('[TagName]','Duration','startTime')
Minimum	Retrieve the minimum raw value in the interval with the timestamp of the start of the interval.	Minimum('[TagName]','Duration') Minimum('[TagName]','Duration','startTime')
Minimum2	Retrieve the minimum value in the interval including the Simple Bounding Values.	Minimum2('[TagName]','Duration') Minimum2('[TagName]','Duration','startTime')
NumberOfTransitions	Retrieve the number of changes between zero and non-zero that a Boolean or numeric value experienced in the interval.	NumberOfTransitions('[TagName]','Duration') NumberOfTransitions('[TagName]','Duration','startTime')
PercentBad/Good	Retrieve the percentage of data (0 to 100) in the interval which has Bad/Good StatusCode.	PercentBad('[TagName]','Duration') PercentGood('[TagName]','Duration','startTime')
Range	Retrieve the difference between the minimum and maximum value over the interval.	Range('[TagName]','Duration') Range('[TagName]','Duration','startTime')
Range2	Retrieve the difference between the Minimum2 and Maximum2 value over the interval.	Range2('[TagName]','Duration') Range2('[TagName]','Duration','startTime')
StandardDeviationPopulation	Retrieve the standard deviation for the interval for a complete population (n) which includes Simple Bounding Values.	StandardDeviationPopulation('[TagName]','Duration') StandardDeviationPopulation('[TagName]','Duration','startTime')
StandardDeviationSample	Retrieve the standard deviation for the interval for a sample of the population (n-1).	StandardDeviationSample('[TagName]','Duration') StandardDeviationSample('[TagName]','Duration','startTime')
StartBound	Retrieve the value at the beginning of the interval using Simple Bounding Values.	StartBound('[TagName]','Duration') StartBound('[TagName]','Duration','startTime')
TimeAverage	Retrieve the time weighted average data over the interval using Interpolated Bounding Values.	TimeAverage('[TagName]','Duration') TimeAverage('[TagName]','Duration','startTime')
TimeAverage2	Retrieve the time weighted average data over the interval using Simple Bounding Values.	TimeAverage2('[TagName]','Duration') TimeAverage2('[TagName]','Duration','startTime')
Total	Retrieve the total (time integral) of the data over the interval using Interpolated Bounding Values.	Total('[TagName]','Duration') Total('[TagName]','Duration','startTime')
Total2	Retrieve the total (time integral in seconds) of the data over the interval using Simple Bounding Values.	Total2('[TagName]','Duration') Total2('[TagName]','Duration','startTime')
TotalPer24Hours	Retrieve the total (time integral in 24 hours) of the data over the interval using Simple Bounding Values.	TotalPer24Hours('[TagName]','Duration') TotalPer24Hours('[TagName]','Duration','startTime')
TotalPerHour	Retrieve the total (time integral in hours) of the data over the interval using Simple Bounding Values.	TotalPerHour('[TagName]','Duration') TotalPerHour('[TagName]','Duration','startTime')
TotalPerMinute	Retrieve the total (time integral in minutes) of the data over the interval using Simple Bounding Values.	TotalPerMinute('[TagName]','Duration') TotalPerMinute('[TagName]','Duration','startTime')
VariancePopulation	Retrieve the variance for the interval as calculated by the StandardDeviationPopulation which includes Simple Bounding Values.	VariancePopulation('[TagName]','Duration') VariancePopulation('[TagName]','Duration','startTime')
VarianceSample	Retrieve the variance for the interval as calculated by the StandardDeviationSample.	VarianceSample('[TagName]','Duration') VarianceSample('[TagName]','Duration','startTime')
WorstQuality	Retrieve the worst StatusCode of data in the interval.	WorstQuality('[TagName]','Duration') WorstQuality('[TagName]','Duration','startTime')
WorstQuality2	Retrieve the worst StatusCode of data in the interval including the Simple Bounding Values.	WorstQuality2('[TagName]','Duration') WorstQuality2('[TagName]','Duration','startTime')

NCalc Functions

Functions	Definition	Syntax
Absolute Value	Returns the absolute value of a specified number.	Abs(-1) Abs([TagName])
CanaryAnd	Evaluates an array of expressions and returns true if all expressions are true.	CanaryAnd([tag1] = 1, [tag2] < 10, [tagN] >= 1)
CanaryOr	Evaluates an Array of values and returns true if at least one is true.	CanaryOr([tag1] = 1, [tag2] = 1, [tagN] = 1)
Ceiling	Retrieves the smallest integer greater than or equal to the specified number.	Ceiling([TagName])
Floor	Retrieves the largest integer less than or equal to the specified number.	Floor([TagName])
Functions of Trigonometry	Returns the sin, cos, tan, arcsin, arccos, and arctan of the specified number.	Sin([TagName]) Atan([TagName])
if	Returns a value based on a condition.	if([TagName]>0, [TagName], False)
in	Returns True/False whether an element is in a set of values where the first element in the array is the value to be compared.	in(1+1, 1, 2, 3)
Log	Returns the logarithm of a specified number.	Log(1,10)
Log10	Returns the base 10 logarithm of a specified number.	Log10(1)
Pow	Returns a number raised to the specified power.	Pow(3,2)
Round	Rounds a value to the nearest integer or specified number of decimal places.	Round('3.222','2')
Sqrt	Returns the square root of a specified number.	Sqrt(4)
Switch	Select an output value based on which match contains the same value as the compare key.	Switch(compareKey, match1, value1, match2, value2...,defaultValue) Any number of matches and values are allowed, but each match needs a value and vice-versa. For each of the parameters in the function, any expression is allowed. You can use constant values, aggregates, variables, tag values, etc. Example: "Switch ([localhost.Testing.Tag1], 1,[localhost.Testing.Tag2], var1 + 2, [localhost.Testing.Tag3], [localhost.Testing.Tag4])" Where Tag2 is the output when Tag1 is equal to 1, Tag 3 is the output when Tag1 is equal to var1 + 2, and Tag4 is the default value that is output when none of the other conditions are met.
Truncate	Calculates the integral part of a number.	Truncate(1.234)

Custom Functions

The following have been built by Canary to address typical historian based analytics.

Functions	Definition	Syntax
AssetInstanceCount	Returns the total number of asset instances of the specified type under a source path.	AssetInstanceCount('sourcePath', 'assetType')
DeltaTotalCount	Retrieves the total delta (change) of values for an accumulation tag that resets periodically.	DeltaTotalCount('[TagName','Duration') DeltaTotalCount('[TagName','Duration','startTime')
DurationSinceDateTime	Retrieves the time in milliseconds since the date and/or time specified by the dateTimeString.	DurationSinceDateTime('dateTimeString') Note: Datetimes can be relative (d+6h) or actual (6:00). TagNames can also be passed in if they have a valid string type that can be parsed. For example, DurationSinceDateTime('d +'+[StringTag]) where [StringTag] = '6h'
DurationSinceLastHistorianUpdate	Retrieve the time in milliseconds since a tag received an update, regardless of whether the value or quality changed.	DurationSinceLastHistorianUpdate('[TagName]') Note: The next 'DurationSinceLastTVQ' function should be used instead of this function in most situations.
DurationSinceLastTVQ	Retrieve the time in milliseconds since a tag's value or quality changed.	DurationSinceLastTVQ ('[TagName]', optional bool ignoreBadValueChanges) If ignoreBadValueChanges is set to true, it changes the behavior of the function so that bad or NoData quality TVQs do not reset the duration and instead only set the output quality to uncertain. Additionally, it keeps the function from resetting the duration because of an uncertain quality.
IsQualityBad/Good/Uncertain	Returns True if the quality is Bad/Good/Uncertain, otherwise returns False. Typically used in conjunction with the 'Quality' function.	IsQualityBad(Quality([TagName]))
NoOutput	Does not output tag values. Typically used within an 'if' statement.	if([Tagname]>0, [TagName],NoOutput()) Starting in 21.4, the 'NoOutput' function can be utilized within the 'Quality Override' parameters of the expression. Both the 'If True' and 'If False' parameters will accept NoOutput as an input.
Property	Retrieves the value of a tag property.	Property('[TagName]', 'PropertyName')
Quality	Retrieves the latest quality for a tag.	Quality('[TagName]') Common quality codes include 192 (Good), 0 (Bad), 64 (Uncertain), 32768 (NoData).
ResettingAnchoredInterval	Calculates an aggregate with an interval that continues to grow over a length of time, and then resets after a certain duration.	ResettingAnchoredInterval('aggregateName', '[TagName]', 'resetInterval', 'optional resetOffset') Example: ResettingAnchoredInterval('Maximum2', '[TagName]', '1d', '9h') This finds the maximum value as it evaluates, periodically or by value change, throughout a 1 day interval from 9am to 9am. At 9am, it resets and starts a new interval.
Rollup	Calculates a sum, count, average, or min/max of a specified tag for all child assets of the specified parent asset type. This function can ony be used as an asset-based calculation and must run Periodically.	Rollup('sourcePath', 'operation', 'child assetType', 'child assetTag', 'optional assetFilterExpression') Operations include: SUM, COUNT, AVERAGE, MINIMUM, MAXIMUM. Example: Rollup('VirtualView.%Asset%','SUM','Pump','Pressure') where 'Pump' is a child asset of the configured 'Well' parent asset and 'Pressure' is a pump tag. The assetFilterExpression may be any valid calculation expression and will be applied to the rollup assets to determine which to use and which to skip. If the expression returns false for a particular asset, that asset will not be included in the rollup. Use %RollupAsset% to target tags relative to the asset being rolled up. Example: Rollup('VirtualView.%Asset%','SUM','Pump','Pressure',[%RollupAsset%.Running]=True) In this example, only pumps that have the Running tag equal True will be rolled up.
SetOutputQuality	Sets the output tag value quality.	SetOutputQuality(quality) Quality can be represented in its string format or decimal equivalent. Common qualities include: Good(192), Bad(0), Uncertain(64), and NoData(32768). Starting in 21.4, the 'Quality Override' parameters of the expression can be used in place of this function. Both the 'If True' and 'If False' parameters will accept the string and decimal quality format.
TagIfExists	Returns the value of the tag if it exists, otherwise returns the fallback value.	TagIfExists ('[TagName]', fallbackValue) fallbackValue can be a number or a string but can't be a tag, an aggregate, or a variable.

Calculation Server

- adand
- 3 mths ago
- Reported - view
DurationSinceLastTVQ

How should I use this Calc..
- smason
  
  3 mths ago
  
  Reported - view
  adand It outputs the amount of time (in milliseconds) since the latest value in the Historian. It only makes sense to use this for a Periodic calculation as on Value Change it will always output a 0 since no time has passed since the calc was triggered.