Performance Calculation Functions

The following functions are available to expressions created for performance calculation tags and calculation triggers in Hyper Historian. Expressions for calculating a calculated tag are defined for the calculated tag itself, as described in the Configuring a Calculated Tag topic.

The functions listed in this topic are supplemental to all Expression Editor functions described in the Expression Editor topic. Click on one of the following hyperlinks to go directly to descriptions of the functions.

  • Date and Time functions - ClosedClick here to see Date and Time functions in the Expression Editor's Functions menu

    Date and Time Functions for Use with Calculated Tags

  • Data value functions - ClosedClick here to see Data Value functions in the Expression Editor's Functions menu

    Data Value Functions for Use with Calculated Tags

  • Historical functions (including standard deviation and variance functions) - ClosedClick here to see Historical functions in the Expression Editor's Functions menu

    Historical Functions for Use with Calculated Tags

  • Metadata functions - ClosedClick here to see Metadata functions in the Expression Editor's Functions menu

    Metadata Functions for Use with Calculated Tags

Date and Time Functions

The date and time functions that you can use in expressions for calculated tags are listed here and are described in more detail below.

  • now - Trigger time (Local time) of the trigger that invoked this calculation

  • utcnow - Trigger time (UTC time) of the trigger that invoked this calculation

  • yday - Returns a timestamp based on current trigger time with time portion rounded to 12:00:00 AM and date moved to preceding day

  • today - Returns a timestamp based on current trigger time with time portion rounded to 12:00:00 AM

  • mintime - Returns the smallest possible value of DateTime type

  • maxtime - Returns the largest possible value of DateTime type

  • tolocal - Converts to Local time

  • toutc - Converts to UTC time

  • isdst - Returns true when given timestamp is within the Daylight Savings Time range for the current time zone; returns false when given timestamp is in UTC

  • noon - Returns a timestamp with the date portion taken from the given time and the time portion rounded to 12:00:00 PM

  • bday - Returns a timestamp with the date portion taken from the given time and the time portion rounded to 12:00:00 AM

  • bmonth - Returns a timestamp with the month and year taken from the given time and the time portion rounded to 12:00:00 AM

  • byear - Returns a timestamp with year taken from given time and time portion rounded to 12:00:00 AM

  • second - Seconds part of a given timestamp (0-59)

  • minute - Minutes part of a given timestamp (0-59)

  • hour - Hour part of a given timestamp (0-23)

  • day - Day part of a given timestamp (1-31)

  • month - Month part of a given timestamp (1-12)

  • year - Year part of a given timestamp (4-digit year)

  • yearday - Returns an Integer between 1 and 366 representing the day of the year for a given timestamp

  • weekday - Returns an Integer between 0 and 6 representing the day of the week for a given timestamp (0=Sunday, 6=Saturday)

  • dayseconds - Returns an Integer between 0 and 86399 representing the seconds of the day for a given timestamp

now (Trigger Time (Local))

Returns the local time of the trigger that invoked this calculation.

Format: now()

Returns: DateTime Value

utcnow (Trigger Time (UTC))

Returns the UTC time of the trigger that invoked this calculation.

Format: utcnow()

Returns: DateTime Value

yday (Yesterday Date)

Returns the time based on the current trigger time with the time rounded to 12:00:00 AM and the date moved to the preceding day.

Format: yday()

Returns: DateTime Value

today (Today Date)

Returns the time based on the current trigger time with the time rounded to 12:00:00 AM.

Format: today()

Returns: DateTime Value

mintime (Minimum Time)

Returns the smallest possible value of the DateTime type.

Format: mintime()

Returns: DateTime Value

maxtime (Maximum Time)

Returns the largest possible value of the DateTime type.

Format: maxtime()

Returns: DateTime Value

tolocal (Convert To Local Time)

Returns the local time for the given UTC time. When the given time is local, it does nothing.

Format: tolocal(sourceTime)

Parameters:

sourceTime: DateTime value to perform operation on

Returns: DateTime Value

toutc (Convert To UTC Time)

Returns the UTC time for the given local time. When the given time is UTC, it does nothing.

Format: toutc(sourceTime)

Parameters:

sourceTime: DateTime value to perform operation on

Returns: DateTime Value

isdst (Is Daylight Saving Time)

Returns true when the given timestamp is within the Daylight Saving Time range for the current time zone; returns false when the given timestamp is in UTC.

Format: isdst(sourceTime)

Parameters:

sourceTime: DateTime value to perform operation on

Returns: Boolean (true/false) Value

noon (Noon Time)

Returns the time with the date portion taken from the given time and the time portion rounded to 12:00:00 PM.

Format: noon(sourceTime)

Parameters:

sourceTime: DateTime value to perform operation on

Returns: DateTime Value

bday (Begining of Day)

Returns the time with the date portion taken from the given time and the time portion rounded to 12:00:00 AM.

Format: bday(sourceTime)

Parameters:

sourceTime: DateTime value to perform operation on

Returns: DateTime Value

bmonth (Begining of Month)

Returns the time with the month and year taken from the given time and the time portion rounded to 12:00:00 AM.

Format: bmonth(sourceTime)

Parameters:

sourceTime: DateTime value to perform operation on

Returns: DateTime Value

byear (Begining of Year)

Returns the time with the year taken from the given time and the time portion rounded to 12:00:00 AM.

Format: byear(sourceTime)

Parameters:

sourceTime: DateTime value to perform operation on

Returns: DateTime Value

second (Second Fragment)

Returns an integer number between 0 and 59 representing the second fragment of the given time.

Format: second(sourceTime)

Parameters:

sourceTime: DateTime value to perform operation on

Returns: Integer (4 bytes) Value

minute (Minute Fragment)

Returns an integer number between 0 and 59 representing the minute fragment of the given time.

Format: minute(sourceTime)

Parameters:

sourceTime: DateTime value to perform operation on

Returns: Integer (4 bytes) Value

hour (Hour Fragment)

Returns an integer number between 0 and 23 representing the hour fragment of the given time.

Format: hour(sourceTime)

Parameters:

sourceTime: DateTime value to perform operation on

Returns: Integer (4 bytes) Value

day (Day Fragment)

Returns an integer number between 1 and 31 representing the day from the date of the given time.

Format: day(sourceTime)

Parameters:

sourceTime: DateTime value to perform operation on

Returns: Integer (4 bytes) Value

month (Month Fragment)

Returns an integer number between 1 and 12 representing the month from the date of the given time.

Format: month(sourceTime)

Parameters:

sourceTime: DateTime value to perform operation on

Returns: Integer (4 bytes) Value

year (Year Fragment)

Returns an integer number between 1 and 9999 representing the year from the date of the given time.

Format: year(sourceTime)

Parameters:

sourceTime: DateTime value to perform operation on

Returns: Integer (4 bytes) Value

yearday (Day of Year)

Returns an integer number between 1 and 366 representing the day of the year for the given time.

Format: yearday(sourceTime)

Parameters:

sourceTime: DateTime value to perform operation on

Returns: Integer (4 bytes) Value

weekday (Day of Week)

Returns an integer number between 0 and 6 representing day of the week for the given time. Values are:

  • 0 - Sunday
  • 1 - Monday
  • 2 - Tuesday
  • 3 - Wednesday
  • 4 - Thursday
  • 5 - Friday
  • 6 - Saturday

Format: weekday(sourceTime)

Parameters:

sourceTime: DateTime value to perform operation on

Returns: Integer (4 bytes) Value

dayseconds (Day Total Seconds)

Returns an integer number between 0 and 86399 representing the second of the day for the given time.

Format: dayseconds(sourceTime)

Parameters:

sourceTime: DateTime value to perform operation on

Returns: Integer (4 bytes) Value

Back to top

Data Value Functions

Data Value functions that you can use in expressions for calculated tags are listed here and are described in more detail below.

  • tagat - Returns the data value at a given time
  • tagprev - Returns the first data value preceding the given timestamp
  • tagprev2- Returns the first data value preceding the given timestamp or at the given time
  • tagnext - Returns the next data value following the given timestamp
  • tagnext2- Returns the next data value following the given timestamp or at the given time
  • tagprevgood - Returns the first good quality data value preceding the given timestamp
  • tagprevgood2- Returns the first good quality data value preceding the given timestamp or at the given time
  • tagnextgood - Returns the next good quality data value following the given timestamp
  • tagnextgood2- Returns the next good quality data value following the given timestamp or at the given time
  • tagprevn - Returns an array of previous 'n' data values
  • tagprevn2- Returns an array of previous and current 'n' data values
  • tagnextn - Returns an array of next 'n' data values
  • tagnextn2- Returns an array of current and next 'n' data values
  • tagprevngood - Returns an array of previous 'n' good quality data values
  • tagprevngood2- Returns an array of previous and current 'n' good quality data values
  • tagnextngood - Returns an array of next 'n' good quality data values
  • tagnextngood2- Returns an array of current and next 'n' good quality data values
  • trgnamecur - Returns the name of the trigger that invoked this calculation
  • trgnameprev - Returns the name of the trigger that invoked the previous calculation
  • trgcur - Returns the data value of the trigger that invoked this calculation
  • calcprev - Returns the last known calculated value
  • elm - Returns a specified array element
  • val - Returns the value part of a given data variable
  • valsetgood- Returns the value part of a given data variable and sets the expression quality to "Good"
  • time - Returns the timestamp part of a given data variable
  • qualcode - Returns the quality code part of a given data variable
  • isgood - Returns true when the given data value has good quality
  • isbad - Returns true when the given data value has bad quality
  • isunc - Returns true when the given data value has uncertain quality
  • hasval - Returns true when the given data value contains a valid value
  • nologval - Returns this value as the result and nothing will be logged

tagat (Data Value at Time)

Returns the data value at the given timestamp. The data value can be either a raw value or an interpolated value. Note that this function may be slow as it accesses historical data.

Format:  tagat(variable,dateTime)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

dateTime: DateTime Value

Returns: DataValue, a set of Timestamp, Value and Quality code

tagprev (Previous Data Value)

Returns the data value preceding the given timestamp. Note that this function may be slow as it accesses historical data.

Format: tagprev(variable,dateTime)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

dateTime: DateTime Value

Returns: DataValue, a set of Timestamp, Value and Quality code

tagprev2 (Previous or Current Data Value)

Returns the data value preceding or including the given timestamp. Note that this function may be slow as it accesses historical data.

Format: tagprev2(variable,dateTime)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

dateTime: DateTime Value

Returns: DataValue, a set of Timestamp, Value and Quality code

tagnext (Next Data Value)

Returns the data value following the given timestamp. Note that this function may be slow as it accesses historical data.

Format: tagnext(variable,dateTime)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

dateTime: DateTime Value

Returns: DataValue, a set of Timestamp, Value and Quality code

tagnext2 (Next or Current Data Value)

Returns the data value following or including the given timestamp. Note that this function may be slow as it accesses historical data.

Format: tagnext2(variable,dateTime)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

dateTime: DateTime Value

Returns: DataValue, a set of Timestamp, Value and Quality code

tagprevgood (Previous Good Data Value)

Returns the first good quality data value that precedes the given timestamp. Note that this function may be slow as it accesses historical data.

Format: tagprevgood(variable,dateTime)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

dateTime: DateTime Value

Returns: DataValue, a set of Timestamp, Value and Quality code

tagprevgood2 (Previous or Current Good Data Value)

Returns the first good quality data value that precedes the given timestamp or occurs at the given time. Note that this function may be slow as it accesses historical data.

Format: tagprevgood2(variable,dateTime)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

dateTime: DateTime Value

Returns: DataValue, a set of Timestamp, Value and Quality code

tagnextgood (Next Good Data Value)

Returns the first good quality data value that follows the given timestamp. Note that this function may be slow as it accesses historical data.

Format: tagnextgood(variable,dateTime)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

dateTime: DateTime Value

Returns: DataValue, a set of Timestamp, Value and Quality code

tagnextgood2 (Next or Current Good Data Value)

Returns the first good quality data value that follows the given timestamp or occurs at the given time. Note that this function may be slow as it accesses historical data.

Format: tagnextgood2(variable,dateTime)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

dateTime: DateTime Value

Returns: DataValue, a set of Timestamp, Value and Quality code

tagprevn (Previous N Data Values)

Returns the given number of data values preceding the given timestamp. Note that this function may be slow as it accesses historical data.

Format: tagprev(variable,dateTime,int)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

dateTime: DateTime Value

int: Integer indicating the number of values to return

Returns: (n) DataValue, a set of Timestamp, Value and Quality code

tagprevn2 (Previous and Current N Data Values)

Returns the given number of data values preceding and including the given timestamp. Note that this function may be slow as it accesses historical data.

Format: tagprevn2(variable,dateTime,int)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

dateTime: DateTime Value

int: Integer indicating the number of values to return

Returns: (n) DataValue, a set of Timestamp, Value and Quality code

tagnextn (Next N Data Values)

Returns the given number of data values following the given timestamp. Note that this function may be slow as it accesses historical data.

Format: tagnext(variable,dateTime,int)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

dateTime: DateTime Value

int: Integer indicating the number of values to return

Returns: (n) DataValue, a set of Timestamp, Value and Quality code

tagnextn2 (Next and Current N Data Values)

Returns the given number of data values following and including the given timestamp. Note that this function may be slow as it accesses historical data.

Format: tagnext2(variable,dateTime,int)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

dateTime: DateTime Value

int: Integer indicating the number of values to return

Returns: (n) DataValue, a set of Timestamp, Value and Quality code

tagprevngood (Previous N Good Data Values)

Returns the given number of good quality data values preceding the given timestamp. Note that this function may be slow as it accesses historical data.

Format: tagprevgood(variable,dateTime,int)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

dateTime: DateTime Value

int: Integer indicating the number of values to return

Returns: (n) DataValue, a set of Timestamp, Value and Quality code

tagprevngood2 (Previous and Current N Good Data Values)

Returns the given number of good quality data values preceding and including the given timestamp. Note that this function may be slow as it accesses historical data.

Format: tagprevgood2(variable,dateTime,int)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

dateTime: DateTime Value

int: Integer indicating the number of values to return

Returns: (n) DataValue, a set of Timestamp, Value and Quality code

tagnextngood (Next N Good Data Values)

Returns the given number of good quality data values following the given timestamp. Note that this function may be slow as it accesses historical data.

Format: tagnextgood(variable,dateTime,int)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

dateTime: DateTime Value

int: Integer indicating the number of values to return

Returns: (n) DataValue, a set of Timestamp, Value and Quality code

tagnextngood2 (Next and Current N Good Data Values)

Returns the given number of good quality data values following and including the given timestamp. Note that this function may be slow as it accesses historical data.

Format: tagnextgood2(variable,dateTime,int)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

dateTime: DateTime Value

int: Integer indicating the number of values to return

Returns: (n) DataValue, a set of Timestamp, Value and Quality code

trgnamecur (Current Trigger Name)

Returns the name of the trigger that invoked this calculation.

Format: trgnamecur()

Returns: String Value

trgnameprev (Previous Trigger Name)

Returns the name of the trigger that invoked the previous calculation.

Format: trgnameprev()

Returns: String Value

trgcur (Current Trigger Value)

Returns the data value of the trigger that invoked this calculation.

Format: trgcur()

Returns: DataValue, a set of Timestamp, Value and Quality code

calcprev (Previous Calculated Value)

Returns the last known calculated value.

Format: calcprev()

Returns: DataValue, a set of Timestamp, Value and Quality code

elm (Array Element)

Returns an element of the given array at the given position.

Format: elm(array, arrayPosition)

Parameters:

arrayPosition:

Returns: The array element as a generic value

val (Value)

Returns the value fragment of the given Data Value.

Format: val(dataValue)

Parameters:

dataValue: DataValue, a set of Timestamp, Value and Quality code

Returns: Raw DataValue type

valsetgood (Value)

Returns the value fragment of the given Data Value and sets the quality of the expression to "Good."

Format: val(dataValue)

Parameters:

dataValue: DataValue, a set of Timestamp, Value and Quality code

Returns: Raw DataValue type

time (Timestamp)

Returns the timestamp fragment of the given Data Value.

Format: time(dataValue)

Parameters:

dataValue: DataValue, a set of Timestamp, Value and Quality code

Returns: DateTime Value

qualcode (Quality Code)

Returns the quality code fragment of the given Data Value.

Format: qualcode(dataValue)

Parameters:

dataValue: DataValue, a set of Timestamp, Value and Quality code

Returns: Unsigned Integer (4 bytes) Value

isgood (Is Data Value Good)

Returns true when the given data value is of good quality.

Format: isgood(dataValue)

Parameters:

dataValue: DataValue, a set of Timestamp, Value and Quality code

Returns: Boolean (true/false) Value

isbad (Is Data Value Bad)

Returns true when the given data value is of bad quality.

Format: isbad(dataValue)

Parameters:

dataValue: DataValue, a set of Timestamp, Value and Quality code

Returns: Boolean (true/false) Value

isunc (Is Data Value Uncertain)

Returns true when the given data value is of uncertain quality.

Format: isunc(dataValue)

Parameters:

dataValue: DataValue, a set of Timestamp, Value and Quality code

Returns: Boolean (true/false) Value

hasval (Has Value)

Returns true when the given data value contains a valid value.

Format: hasval(dataValue)

Parameters:

dataValue: DataValue, a set of Timestamp, Value and Quality code

Returns: Boolean (true/false) Value

nologval (Not Logged Value)

Returns this value as the result; nothing will be logged.

Format: nologval()

Returns: DataValue, a set of Timestamp, Value and Quality code

Back to top

Historical Functions

The historical functions that you can use in expressions for calculated tags are listed here and are described in more detail below. These functions may be slower than expected as they access historical data.

  • tagfind - The first timestamp of the value that matches the given filtering criteria within the specified time interval

  • tagfindstate - The first timestamp of the value that matches the given state value within the specified time interval

  • tagavg - Average

  • tagtavg - Time Weighted Average

  • tagtotalize - Totalize

  • tagtotal - Total

  • tagmin - Minimum

  • tagmax - Maximum

  • tagdelta - Difference between the first and last good raw values for the given data variable and time range

  • tagrange - Difference between the maximum and minimum good raw values for the given data variable and time range

  • tagcount - Number of samples for the given data variable and time range

  • tagtimestate0 - Duration in State 0 for the given data variable and time range

  • tagtimestate1 - Duration in State 1 for the given data variable and time range

  • tagntrans - Number of Transitions between zero and non-zero state for the given data variable and time range

  • tagpctgood - Percent of the time for which data value had good quality in the given time interval

  • tagpctbad - Percent of the time for which data value had bad quality in the given time interval

  • tagtimegood - Duration of time for which the data value had good quality in the given time interval

  • tagtimebad - Duration of time for which the data value had bad quality in the given time interval

  • tagworstqual - Returns the worst value quality for the given data variable and time range

  • tagtime - Returns the time for which data values matched the given filter criteria, within the specified time interval

  • tagstddev - Standard deviation using 1/(N-1) calculation

  • tagstddev2 - Standard deviation using 1/N calculation

  • tagvariance - Variance using 1/(N-1) calculation

  • tagvariance2 - Variance using 1/N calculation

tagfind (Find Timestamp)

Returns the first timestamp of the value that matches the given filter criteria within the specified time interval. Note that this function may be slow as it accesses historical data.

Format: tagfind(variable,startTime,endTime,comparisonType,comparisonValue)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

startTime: DateTime value indicating begin of the time interval to process data for

endTime: DateTime, TimeSpan or Numeric milliseconds value indicating end of the time interval to process data for

comparisonType: String value representing comparison type, it can be one of the following:

==    !=    >    >=    <    <=

comparisonValue: Numeric value to compare with

Returns: DateTime Value

tagfindstate (Find Timestamp for given State)

Returns the first timestamp of the value that matches the given state value, within the specified time interval. Note that this function may be slow as it accesses historical data.

Format: tagfindstate(variable,startTime,endTime,boolState)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

startTime: DateTime value indicating begin of the time interval to process data for

endTime: DateTime, TimeSpan or Numeric milliseconds value indicating end of the time interval to process data for

boolState: a boolean value representing the state to search for

Returns: DateTime Value

tagavg (Average)

Returns the average value for the given data variable and time range. Note that this function may be slow as it accesses historical data.

Format: tagavg(variable,startTime,endTime,percentGood)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

startTime: DateTime value indicating begin of the time interval to process data for

endTime: DateTime, TimeSpan or Numeric milliseconds value indicating end of the time interval to process data for

percentGood: Numeric value in the range 0 to 100 indicating percentage of good samples in given time interval to return good status code for processed value

Returns: DataValue, a set of Timestamp, Value and Quality code

tagtavg (Time Weighted Average)

Returns the time weighted average value for the given data variable and time range. Note that this function may be slow as it accesses historical data.

Format: tagtavg(variable,startTime,endTime,percentGood)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

startTime: DateTime value indicating begin of the time interval to process data for

endTime: DateTime, TimeSpan or Numeric milliseconds value indicating end of the time interval to process data for

percentGood: Numeric value in range 0-100 indicating percentage of good samples in given time interval to return good status code for processed value

Returns: DataValue, a set of Timestamp, Value and Quality code

tagtotalize (Totalize)

Returns the totalized value for the given data variable and time range. Note that this function may be slow as it accesses historical data.

Format: tagtotalize(variable,startTime,endTime,percentGood)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

startTime: DateTime value indicating begin of the time interval to process data for

endTime: DateTime, TimeSpan or Numeric milliseconds value indicating end of the time interval to process data for

percentGood: Numeric value in range 0-100 indicating percentage of good samples in given time interval to return good status code for processed value

Returns: DataValue, a set of Timestamp, Value and Quality code

tagtotal (Total - sum)

Returns the total (sum) value for the given data variable and time range. Note that this function may be slow as it accesses historical data.

Format: tagtotal(variable,startTime,endTime,percentGood)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

startTime: DateTime value indicating begin of the time interval to process data for

endTime: DateTime, TimeSpan or Numeric milliseconds value indicating end of the time interval to process data for

percentGood: Numeric value in range 0-100 indicating percentage of good samples in given time interval to return good status code for processed value

Returns: DataValue, a set of Timestamp, Value and Quality code

tagmin (Minimum)

Returns the minimum value for the given data variable and time range. Note that this function may be slow as it accesses historical data.

Format: tagmin(variable,startTime,endTime,percentGood)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

startTime: DateTime value indicating begin of the time interval to process data for

endTime: DateTime, TimeSpan or Numeric milliseconds value indicating end of the time interval to process data for

percentGood: Numeric value in range 0-100 indicating percentage of good samples in given time interval to return good status code for processed value

Returns: DataValue, a set of Timestamp, Value and Quality code

tagmax (Maximum)

Returns the maximum value for the given data variable and time range. Note that this function may be slow as it accesses historical data.

Format: tagmax(variable,startTime,endTime,percentGood)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

startTime: DateTime value indicating begin of the time interval to process data for

endTime: DateTime, TimeSpan or Numeric milliseconds value indicating end of the time interval to process data for

percentGood: Numeric value in range 0-100 indicating percentage of good samples in given time interval to return good status code for processed value

Returns: DataValue, a set of Timestamp, Value and Quality code

tagdelta (Delta)

Returns the difference between the first and last good raw values for the given data variable and time range. Note that this function may be slow as it accesses historical data.

Format: tagdelta(variable,startTime,endTime,percentGood)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

startTime: DateTime value indicating begin of the time interval to process data for

endTime: DateTime, TimeSpan or Numeric milliseconds value indicating end of the time interval to process data for

percentGood: Numeric value in range 0-100 indicating percentage of good samples in given time interval to return good status code for processed value

Returns: DataValue, a set of Timestamp, Value and Quality code

tagrange (Range)

Returns the difference between the maximum and minimum good raw values for the given data variable and time range. Note that this function may be slow as it accesses historical data.

Format: tagrange(variable,startTime,endTime,percentGood)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

startTime: DateTime value indicating begin of the time interval to process data for

endTime: DateTime, TimeSpan or Numeric milliseconds value indicating end of the time interval to process data for

percentGood: Numeric value in range 0-100 indicating percentage of good samples in given time interval to return good status code for processed value

Returns: DataValue, a set of Timestamp, Value and Quality code

tagcount (Samples Count)

Returns the number of all samples for the given data variable and time range. Note that this function may be slow as it accesses historical data.

Format: tagcount(variable,startTime,endTime,percentGood)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

startTime: DateTime value indicating begin of the time interval to process data for

endTime: DateTime, TimeSpan or Numeric milliseconds value indicating end of the time interval to process data for

percentGood: Numeric value in range 0-100 indicating percentage of good samples in given time interval to return good status code for processed value

Returns: DataValue, a set of Timestamp, Value and Quality code

tagtimestate0 (Time Duration in State 0)

Returns how long the value was in the zero state for the given data variable and time range. Note that this function may be slow as it accesses historical data.

Format: tagtimestate0(variable,startTime,endTime,percentGood)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

startTime: DateTime value indicating begin of the time interval to process data for

endTime: DateTime, TimeSpan or Numeric milliseconds value indicating end of the time interval to process data for

percentGood: Numeric value in range 0-100 indicating percentage of good samples in given time interval to return good status code for processed value

Returns: DataValue, a set of Timestamp, Value and Quality code

tagtimestate1 (Time Duration in State 1)

Returns how long the value was in the not-zero state for the given data variable and time range. Note that this function may be slow as it accesses historical data.

Format: tagtimestate1(variable,startTime,endTime,percentGood)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

startTime: DateTime value indicating begin of the time interval to process data for

endTime: DateTime, TimeSpan or Numeric milliseconds value indicating end of the time interval to process data for

percentGood: Numeric value in range 0-100 indicating percentage of good samples in given time interval to return good status code for processed value

Returns: DataValue, a set of Timestamp, Value and Quality code

tagntrans (Number of Transitions)

Returns the number of transitions between zero and not zero state for the given data variable and time range. Note that this function may be slow as it accesses historical data.

Format: tagntrans(variable,startTime,endTime,percentGood)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

startTime: DateTime value indicating begin of the time interval to process data for

endTime: DateTime, TimeSpan or Numeric milliseconds value indicating end of the time interval to process data for

percentGood: Numeric value in range 0-100 indicating percentage of good samples in given time interval to return good status code for processed value

Returns: DataValue, a set of Timestamp, Value and Quality code

tagpctgood (% of Good Values)

Returns the percentage of time over the given time interval that the data value had good quality. Note that this function may be slow as it accesses historical data.

Format: tagpctgood(variable,startTime,endTime)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

startTime: DateTime value indicating begin of the time interval to process data for

endTime: DateTime, TimeSpan or Numeric milliseconds value indicating end of the time interval to process data for

Returns: DataValue, a set of Timestamp, Value and Quality code

tagpctbad (% of Bad Values)

Returns the percentage of the time over the given time interval that the data value had bad quality. Note that this function may be slow as it accesses historical data.

Format: tagpctbad(variable,startTime,endTime)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

startTime: DateTime value indicating begin of the time interval to process data for

endTime: DateTime, TimeSpan or Numeric milliseconds value indicating end of the time interval to process data for

Returns: DataValue, a set of Timestamp, Value and Quality code

tagtimegood (Good Values Time Duration)

Returns the time over which the data value had good quality in the given time interval. Note that this function may be slow as it accesses historical data.

Format: tagtimegood(variable,startTime,endTime)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

startTime: DateTime value indicating begin of the time interval to process data for

endTime: DateTime, TimeSpan or Numeric milliseconds value indicating end of the time interval to process data for

Returns: DataValue, a set of Timestamp, Value and Quality code

tagtimebad (Bad Values Time Duration)

Returns the time over which the data value had bad quality in the given time interval. Note that this function may be slow as it accesses historical data.

Format: tagtimebad(variable,startTime,endTime)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

startTime: DateTime value indicating begin of the time interval to process data for

endTime: DateTime, TimeSpan or Numeric milliseconds value indicating end of the time interval to process data for

Returns: DataValue, a set of Timestamp, Value and Quality code

tagworstqual (Worst Quality)

Returns the worst value quality for the given data variable and time range. Note that this function may be slow as it accesses historical data.

Format: tagworstqual(variable,startTime,endTime)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

startTime: DateTime value indicating begin of the time interval to process data for

endTime: DateTime, TimeSpan or Numeric milliseconds value indicating end of the time interval to process data for

Returns: DataValue, a set of Timestamp, Value and Quality code

tagtime (Value based Time Duration)

Returns the time over the specified time interval that data values match the given filter criteria. Note that this function may be slow as it accesses historical data.

Format: tagtime(variable,startTime,endTime,comparisonType,comparisonValue,percentGood)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

startTime: DateTime value indicating begin of the time interval to process data for

endTime: DateTime, TimeSpan or Numeric milliseconds value indicating end of the time interval to process data for

comparisonType: String value representing comparison type, it can be one of the following:

==    !=    >    >=    <    <=

comparisonValue: Numeric value to compare with

percentGood: Numeric value in range 0-100 indicating percentage of good samples in given time interval to return good status code for processed value

Returns: DataValue, a set of Timestamp, Value and Quality code

tagstddev (Standard Deviation (N − 1))

Returns the Standard Deviation (with Bessel's correction) for the given data variable and time range. Note that this function may be slow as it accesses historical data.

Format: tagstddev(variable,startTime,endTime)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

startTime: DateTime value indicating begin of the time interval to process data for

endTime: DateTime, TimeSpan or Numeric milliseconds value indicating end of the time interval to process data for

Returns: DataValue, a set of Timestamp, Value and Quality code

tagstddev2 (Standard Deviation (N))

Returns the Standard Deviation for the given data variable and time range. Note that this function may be slow as it accesses historical data.

Format: tagstddev2(variable,startTime,endTime)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

startTime: DateTime value indicating begin of the time interval to process data for

endTime: DateTime, TimeSpan or Numeric milliseconds value indicating end of the time interval to process data for

Returns: DataValue, a set of Timestamp, Value and Quality code

tagvariance (Variance (N − 1))

Returns the Variance (with Bessel's correction) for the given data variable and time range. Note that this function may be slow as it accesses historical data.

Format: tagvariance(variable,startTime,endTime)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

startTime: DateTime value indicating begin of the time interval to process data for

endTime: DateTime, TimeSpan or Numeric milliseconds value indicating end of the time interval to process data for

Returns: DataValue, a set of Timestamp, Value and Quality code

tagvariance2 (Variance (N))

Return the Variance for the given data variable and time range. Note that this function may be slow as it accesses historical data.

Format: tagvariance2(variable,startTime,endTime)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

startTime: DateTime value indicating begin of the time interval to process data for

endTime: DateTime, TimeSpan or Numeric milliseconds value indicating end of the time interval to process data for

Returns: DataValue, a set of Timestamp, Value and Quality code

Back to top

Metadata Functions

The metadata functions that you can use in expressions for calculated tags are listed here and are described in more detail below.

  • tagname - Name of the given data variable

  • tagdname - Display name of the given data variable

  • tagdesc - Description of the given data variable

  • tagvaltype - Value type for the given data variable. The returned values are: 0-Native, 1-Double, 2-Single, 3-SByte, 4-Int16, 5-Int32, 6-Int64, 7-Byte, 8-UInt16, 9-UInt32, 10-UInt64, 11-String, 13-Bool, 16-Duration

  • tagtype - Variable type for the given data variable. The returned values are: 0-Base, 1-Analog, 2-Decimal Analog, 3-Digital

  • tagunits - Engineering units for the given data variable

  • taghighval - High value from value range for the given data variable

  • taglowval - Low value from value range for the given data variable

  • tagsource - Source data point name for the given data variable

tagname (Name)

Returns the configured name for the given data variable.

Format: tagname(variable)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

Returns: String Value

tagdname (Display Name)

Returns the configured display name for the given data variable.

Format: tagdname(variable)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

Returns: String Value

tagdesc (Description)

Returns the configured description for the given data variable.

Format: tagdesc(variable)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

Returns: String Value

tagvaltype (Value Type)

Returns an integer value that represents the data value type. Valid values are:

0 - Native

7 - Byte

1 - Double

8 - UInt16

2 - Single

9 - UInt32

3 - SByte

10 - UInt64

4 - Int16

11 - String

5 - Int32

13 - Bool

6 - Int64

16 - Duration

Format: tagvaltype(variable)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

Returns: Integer (4 bytes) Value

tagtype (Variable Type)

Return integer value representing data variable type. Valid values are:

  • 0 - Base
  • 1 - Analog
  • 2 - Decimal Analog
  • 3 - Digital

Format: tagtype(variable)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

Returns: Integer (4 bytes) Value

tagunits (Engineering Units)

Returns the configured engineering units for the given data variable.

Format: tagunits(variable)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

Returns: String Value

taghighval (High Range)

Returns the configured high value from value range for the given data variable.

Format: taghighval(variable)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

Returns: Double Value

taglowval (Low Range)

Returns the configured low value from value range for the given data variable.

Format: taglowval(variable)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

Returns: Double Value

tagsource (Source)

Returns the configured source data point name for the given data variable.

Format: tagsource(variable)

Parameters:

variable: Internal data variable, i.e. {{fully_qualified_variable_name}}

Returns: String Value

Back to top

See also:

Calculated Tags

Configuring a Calculated Tag

Creating a Calculation Trigger

Scheduling Recalculation Tasks

Performance Calculation Enhancements