Add Calculation Function

To Create a Calculation Function:

Start the Workbench, then expand your project. Next, expand the Historical Data node to show the Hyper Historian node. Expand the Hyper Historian node to show the Calculation Functions node.
Right-click the Calculation Functions node in the navigation tree, or any of its sub-nodes, and select Add Calculation Function, as shown in the figure below.

Add Calculation Function from the Project Explorer

-OR-

Select the Calculation Functions node in the Project Explorer, or any of its sub-nodes, then click on the Add Calculation Function button, shown below, in the Edit section of the Home ribbon in the Workbench.

Add Calculation Function Button

This opens the Calculation Function properties window, shown below, beneath the Project Details section in the Workbench. Enter a name in the Hyper Historian Calculation Function Name text entry field.

Hyper Historian Calculation Function Properties

Complete the Properties tab settings.

Properties Tab

Properties

Short Description - Enter a short description of the function.
Enabled - Click this checkbox to specify that the calculation is enabled for the tag.
Description - Enter a description of the function.
Returns - Use the pulldown menu to select the return of the function, including:
- Internal data variable, i.e. {{fully_qualified_variable_name}}
- DateTime value indicating begin of the time interval to process data for
- DateTime, TimeSpan or Numeric milliseconds value indicating end of the time interval to process data for
- DateTime value to perform operation on
- Numeric value in range 0-100 indicating percentage of good samples in given time interval to return good status code for processed value
- String value representing comparison type, it can be one of the following "==", "!=", ">", ">=", "<", "<="
- Numeric value to compare with
- A boolean value representing the state to search for
Remark - Enter a remark of the function.

Parameters

This section defines the order of parameters. The first listed parameter is the first parameter of the function.

Parameter Name - Click this pulldown menu to select from variable, startTime, endTime, sourceTime, percentGood, comparisonType, comparisonValue, boolState, bool, dataValue, dateTime, string, uint, double, int, arrayPosition, array, arrayElement, pathFilter, nameFilter, or typeFilter.

- Adds the selected Parameter selected from the Parameter Name pulldown to the list in the field above.
- Edits a selected Parameter within the list.
- Moves a selected Parameter toward the top of the list.
- Moves a selected Parameter toward the top of the list.
- Removes a selected Parameter from the list.
- Deletes a selected Parameter from the list.

Parameter Description - This section is auto-filled based on the selection within the Parameter Name menu.

Complete the Expression tab settings.

Expression Tab

In the Expression Tab, you can add your selected expressions by clicking on the Arithmetic, Relational, Logical, Bitwise, Functions or Variables... button.

Arithmetic

+ - Addition

- - Subtraction

* - Multiplication

/ - Division

% - Modulus

( - Open Parenthesis

) - Close Parenthesis

sin(angleInRadians) - Sine

cos(angleInRadians) - Cosine

tan(angleInRadians) - Tangent

asin(number) - Arcsine

acos(number) - Arccosine

atan(number) - Arctangent

sqrt(number) - Square Root

pow(base, exponent) - Raise to Power

log(number) - Logarithm

ln(number) - Natural Logarithm

exp(number) - Exponential

abs(number) - Absolute Value

ceil(number) - Integer Ceiling

floor(number) - Integer Floor

round(number) - Integer Round

roundto(number, decimalPlaces) - Round to Decimal Places

min(number1, ... , number N) - Minimum

max(number1, ... , number N) - Maximum

sum(number1, ... , number N) - Sum

avg(number1, ... , number N) -Average

isan(number) - Is Not a Number

isinfinity(number) - Is Infinity

pi - Circumference/Diameter Constant

e - Natural Logarithmic Base Constant

Relational

< - Less Than

> - Greater Than

<= - Less Than or Equal

>= - Greater Than or Equal

== - Equal To

!= - Not Equal To

Logical

IF THEN ELSE - Conditional Branch

&& - And

|| - Or

! - Not

true - Boolean Constant True

false - Boolean Constant False

Bitwise

& - And

| - Or

~ - Not

^ - Xor

shl(number, shiftBy) - Shift Left

shr(number, shiftBy) - Shift Right

bittest(number, bitIndex) -Bit Test

setbit(number, bitIndex, bitValue) - Set Bit

togglebit(number, bitIndex) - Toggle Bit

0x - Hexadecimal Constant

0t - Octal Constant

0b - Binary Constant

Functions

quality(value) - Quality of Value

setvalue(variable, value) - Assign a Value to a Variable

tostring(value) - Convert to String (Invariant Culture)

tostringculture(value) - Convert to String (Current Culture)

toformat(value, stringFormat) - Convert to Formatted String (Invariant Culture)

toformatculture(value, stringFormat) - Convert to Formatted String (Current Culture)

tonumber(value) - Convert to Number (Invariant Culture)

tonumberculture(value) - Convert to Number (Current Culture)

tonumberbase(value, base) - Convert to Number from Base

toboolean(value) - Convert to Boolean (Invariant Culture)

tobooleanculture(value) - Convert to Boolean (Current Culture)

asciitochar(number) - Convert Ascii Value(s) to Character(s)

asciitowchar(number) - Convert Unicode Value(s) to Character(s)

chartoascii(string) - Convert Character(s) to Ascii Value(s)

wchartoascii(string) - Convert Character(s) to Unicode Value(s)

String Functions

like(stringSource, stringMatchPattern, booleanCaseSensitive) - Wildcard String Compare

len(string) - String Length

getat(string, index) - Get Character at Index

substring(string, startIndex, length) - Extract Substring

left(string, length) - Left Substring

right(string, length) - Right Substring

concat(string1, string2) - Concatenate Strings

indexof(stringToSearch, stringToFind, startIndex) - String Search

replace(sourceString, stringFindWhat, stringReplaceWith) - String Replace

trim(stringToTrim, charactersToRemove) - Trim Left and Right

trimleft(stringToTrim, charactersToRemove) - Trim Left

trimright(stringToTrim, charactersToRemove) - Trim Right

tolower(string) - To Lowercase

toupper(string) - To Uppercase

null - Null Value Constant

Array Functions

array(value1, ... , valueN) - Create Array

typedarray(elementType, value1, ... , valueN) - Create Typed Array

qarray(excludeBad, excludeUncertain, value1, ... , ValueN) - Create Array with Quality Options

qtypedarray(excludeBad, excludeUncertain, elementType, value1, ..., valueN) - Create Typed Array with Quality Options

len(array) - Array Length

getat(array, index) - Get Value at Array Index

indexof(arrayToSearch, valueToFind, startAt) - Array Item Search

min(array) - Minimum

max(array) - Maximum

sum(array) - Sum

avg(array) - Average

Time Span Functions

totimespan(value) - Convert to TimeSpan (Invariant Culture)

totimespanculture(value) - Convert to TimeSpan (Current Culture)

frommilliseconds(number) - TimeSpan from Milliseconds

fromseconds(number) - TimeSpan from Seconds

fromminutes(number) - TimeSpan from Minutes

fromhours(number) - TimeSpan from Hours

fromdays(number) - TimeSpan from Days

totalmilliseconds(timespan) - Total Milliseconds from TimeSpan

totalseconds(timespan) - Total Seconds from TimeSpan

totalminutes(timespan) - Total Minutes from TimeSpan

totalhours(timespan) - Total Hours from TimeSpan

totaldays(timespan) - Total Days from TimeSpan

timesincelastchange(variable, valueDelta, refreshRateTimeSpan) - Elapsed Since Value Changed

trueforduration(booleanCondition, timespanDuration) - True for Duration

Date and Time Functions

todatetime(value) - Convert to DateTime (Invariant Culture)

todatetimeculture(value) - Convert to DateTime (Current Culture)

tolocal(dateTime) - Convert to Local Time

toutc(dateTime) - Convert to UTC Time

gettimeofday(datetime) - Get Time of Day from DateTime

getdate(datetime) - Get Date from DateTime

isdst(dateTime) - Is Daylight Saving Time

millisecond(dateTime) - Millisecond Fragment

second(dateTime) - Second Fragment

minute(dateTime) - Minute Fragment

hour(dateTime) - Hour Fragment

weekday(dateTime) - Day of Week

day(dateTime) - Day of Month

yearday(dateTime) - Day of Year

month(dateTime) - Month Fragment

year(dateTime) - Year Fragment

dayseconds(dateTime) - Day Total Seconds

today() - Today

yday() - Yesterday

mintime() - Minimum Time

maxtime() - Maximum Time

noon(dateTime) - Noon Time

bday(dateTime) - Beginning of Day

bweek(dateTime) - Beginning of Week

bmonth(dateTime) - Beginning of Month

byear(dateTime) - Beginning of Year

eweek(dateTime) - End of Week

emonth(dateTime) - End of Month

eyear(dateTime) - End of Year

now() - Trigger Time (Local)

utcnow() - Trigger Time (UTC)

yday() - Yesterday Date

today() - Today Date

Array Calculation Functions

elm(array, arrayPosition) - Array Element

elmcount(array) - Array Element Count

atagnow3(variable, variable, variable) - Most Recent Data Values (3 data variables)

atagnow4(variable, variable, variable, variable) - Most Recent Data Values (4 data variables)

atagnow5(variable, variable, variable, variable, variable) - Most Recent Data Values (5 data variables)

atagnow6(variable, variable, variable, variable, variable, variable) - Most Recent Data Values (6 data variables)

atagnowf(pathFilter, nameFilter, typeFilter) - Most Recent Data Values (filtered tags)

aavg(array) - Avg

amin(array) - Min

amax(array) - Max

arange(array) - Range

asum(array) - Sum

amedian(array) - Median

astddev(array) - Standard Deviation (N - 1)

astddev2(array) - Standard Deviation (N)

avariance(array) - Variance (N - 1)

avariance2(array) - Variance (N)

Data Value Functions

tagat(variable, dateTime) - Data Value at Time

tagprev(variable, dateTime) - Previous Data Value

tagprev2(variable, dateTime) - Current or Previous Data Value

tagnext(variable, dateTime) - Next Data Value

tagnext2(variable, dateTime) - Current or Next Data Value

tagprevgood(variable, dateTime) - Previous Good Data Value

tagprevgood2(variable, dateTime) - Current or Previous Good Data Value)

tagnextgood(variable, dateTime) - Next Good Data Value

tagnextgood2(variable, dateTime) - Current or Next Good Data Value

tagprevn(variable, dateTime, int) - Previous N Data Values

tagprevn2(variable, dateTime, int) - Current and Previous N Data Values

tagnextn(variable, dateTime, int) - Next N Data Values

tagnextn2(variable, dateTime, int) - Current and Next N Data Values

tagprevngood(variable, dateTime, int) - Previous N Good Data Values

tagprevngood2(variable, dateTime, int) - Current and Previous N Good Data Values

tagnextngood(variable, dateTime, int) - Next N Good Data Values

tagnextngood2(variable, dateTime, int) - Current and Next N Good Data Values

trgnamecur() - Trigger Name

trgnameprev() - Previous Trigger Name

trgcur() - Trigger Value

calcprev() - Previous Calculated Value

val(dataValue) - Value

valsetgood(dataValue) - Value Set Good

time(dataValue) - Timestamp

qualcode(dataValue) - Quality Code

isgood(dataValue) - Is Data Value Good

isbad(dataValue) - Is Data Value Bad

isunc(dataValue) - Is Data Value Uncertain

hasval(dataValue) - Has Value

nologval() - Not Logged Value

History Functions

tagfind(variable, startTime, endTime, comparisonType, comparisonValue) - Find Timestamp

tagfindstate(variable, startTime, endTime, boolState) - Find Timestamp for given State

tagavg(variable, startTime, endTime, percentGood) - Average

tagtavg(variable, startTime, endTime, percentGood) - Time Weighted Average

tagtotalize(variable, startTime, endTime, percentGood) - Totalize

tagtotal(variable, startTime, endTime, percentGood) - Minimum

tagmax(variable, startTime, endTime, percentGood) - Maximum

tagdelta(variable, startTime, endTime) - Delta

tagrange(variable, startTime, endTime, percentGood) - Range

tagcount(variable, startTime, endTime, percentGood) - Samples Count

tagtimestate0(variable, startTime, endTime, percentGood) - Time Duration in State 0

tagtimestate1(variable, startTime, endTime, percentGood) - Time Duration in State 1

tagntrans(variable, startTime, endTime, percentGood) - Number of Transitions

tagpctgood(variable, startTime, endTime) - % of Good Values

tagpctbad(variable, startTime, endTime) - % of Bad Values

tagtimegood(variable, startTime, endTime) - Good Values Time Duration

tagtimebad(variable, startTime, endTime) - Bad Values Time Duration

tagworstqual(variable, startTime, endTime) - Worst Quality

tagtime(variable, startTime, endTime, comparisonType, comparisonValue, percentGood) - Value Based Time Duration

tagstddev(variable, startTime, endTime) - Standard Deviation (N - 1)

tagstddev2(variable, startTime, endTime) - Standard Deviation (N)

tagvariance(variable, startTime, endTime) - Variance (N - 1)

tagvariance2(variable, startTime, endTime) - Variance (N)

Metadata Functions

tagname(variable) - Name

tagdname(variable) - Display Name

tagdesc(variable) - Description

tagvaltype(variable) - Value Type

tagtype(variable) - Variable Type

tagunits(variable) - Engineering Units

taghighval(variable) - High Range

taglowval(variable) - Low Range

tagsource(variable) - Source

Calculation Functions

Variables

Clicking on the Variables... button within the Expression tab opens the ItemBrowser window, shown below. You can then navigate within the ItemBrowser to select your preferred expression.

ItemBrowser Window

- Click on the Check Syntax button to check your selected expression for errors. Once clicked, the nearby text field will show whether or not any errors were found.

Refresh - Click this button to refresh the list of expressions within the tab.

Click on Apply to save your settings. Your new Calculation Function will now appear in your selected location in the Project Explorer.