Data Value Functions

Data value functions are used in calculated tag expressions to retrieve, inspect, and manipulate data values, timestamps, quality information, and trigger-related context. These functions can access historical data, return collections of values, evaluate data quality, and extract specific elements from DataValue objects.

The functions that evaluate quality operate on the status code carried by a DataValue. For the codes and their meanings, see Data Historian Status Codes.

Function Reference:

Function	Name	Description	Format	Returned Value
tagat	Data Value at Time	Returns the data value at the specified timestamp. The returned value can be raw or interpolated.	`tagat(variable, dateTime)` variable: Specifies the internal data variable to evaluate. dateTime: Specifies the timestamp to retrieve.	DataValue (timestamp, value, and quality code)
tagprev	Previous Data Value	Returns the data value immediately preceding the specified timestamp.	`tagprev(variable, dateTime)` variable: Specifies the internal data variable to evaluate. dateTime: Specifies the timestamp to evaluate.	DataValue
tagprev2	Previous or Current Data Value	Returns the data value preceding or occurring at the specified timestamp.	`tagprev2(variable, dateTime)` variable: Specifies the internal data variable to evaluate. dateTime: Specifies the timestamp to evaluate.	DataValue
tagnext	Next Data Value	Returns the data value immediately following the specified timestamp.	`tagnext(variable, dateTime)` variable: Specifies the internal data variable to evaluate. dateTime: Specifies the timestamp to evaluate.	DataValue
tagnext2	Next or Current Data Value	Returns the data value following or occurring at the specified timestamp.	`tagnext2(variable, dateTime)` variable: Specifies the internal data variable to evaluate. dateTime: Specifies the timestamp to evaluate.	DataValue
tagprevgood	Previous Good Data Value	Returns the first good-quality data value preceding the specified timestamp.	`tagprevgood(variable, dateTime)` variable: Specifies the internal data variable to evaluate. dateTime: Specifies the timestamp to evaluate.	DataValue
tagprevgood2	Previous or Current Good Data Value	Returns the first good-quality data value preceding or occurring at the specified timestamp.	`tagprevgood2(variable, dateTime)` variable: Specifies the internal data variable to evaluate. dateTime: Specifies the timestamp to evaluate.	DataValue
tagnextgood	Next Good Data Value	Returns the first good-quality data value following the specified timestamp.	`tagnextgood(variable, dateTime)` variable: Specifies the internal data variable to evaluate. dateTime: Specifies the timestamp to evaluate.	DataValue
tagnextgood2	Next or Current Good Data Value	Returns the first good-quality data value following or occurring at the specified timestamp.	`tagnextgood2(variable, dateTime)` variable: Specifies the internal data variable to evaluate. dateTime: Specifies the timestamp to evaluate.	DataValue
tagprevn	Previous N Data Values	Returns the specified number of data values preceding the timestamp.	`tagprevn(variable, dateTime, count)` variable: Specifies the internal data variable to evaluate. dateTime: Specifies the timestamp to evaluate. count: Specifies the number of values to return.	Array of DataValue objects
tagprevn2	Previous and Current N Data Values	Returns the specified number of data values preceding and including the timestamp.	`tagprevn2(variable, dateTime, count)` variable: Specifies the internal data variable to evaluate. dateTime: Specifies the timestamp to evaluate. count: Specifies the number of values to return.	Array of DataValue objects
tagnextn	Next N Data Values	Returns the specified number of data values following the timestamp.	`tagnextn(variable, dateTime, count)` variable: Specifies the internal data variable to evaluate. dateTime: Specifies the timestamp to evaluate. count: Specifies the number of values to return.	Array of DataValue objects
tagnextn2	Next and Current N Data Values	Returns the specified number of data values following and including the timestamp.	`tagnextn2(variable, dateTime, count)` variable: Specifies the internal data variable to evaluate. dateTime: Specifies the timestamp to evaluate. count: Specifies the number of values to return.	Array of DataValue objects
tagprevngood	Previous N Good Data Values	Returns the specified number of good-quality data values preceding the timestamp.	`tagprevngood(variable, dateTime, count)` variable: Specifies the internal data variable to evaluate. dateTime: Specifies the timestamp to evaluate. count: Specifies the number of values to return.	Array of DataValue objects
tagprevngood2	Previous and Current N Good Data Values	Returns the specified number of good-quality data values preceding and including the timestamp.	`tagprevngood2(variable, dateTime, count)` variable: Specifies the internal data variable to evaluate. dateTime: Specifies the timestamp to evaluate. count: Specifies the number of values to return.	Array of DataValue objects
tagnextngood	Next N Good Data Values	Returns the specified number of good-quality data values following the timestamp.	`tagnextngood(variable, dateTime, count)` variable: Specifies the internal data variable to evaluate. dateTime: Specifies the timestamp to evaluate. count: Specifies the number of values to return.	Array of DataValue objects
tagnextngood2	Next and Current N Good Data Values	Returns the specified number of good-quality data values following and including the timestamp.	`tagnextngood2(variable, dateTime, count)` variable: Specifies the internal data variable to evaluate. dateTime: Specifies the timestamp to evaluate. count: Specifies the number of values to return.	Array of DataValue objects
trgnamecur	Current Trigger Name	Returns the name of the trigger that invoked the current calculation.	`trgnamecur()`	String
trgnameprev	Previous Trigger Name	Returns the name of the trigger that invoked the previous calculation.	`trgnameprev()`	String
trgcur	Current Trigger Value	Returns the data value of the trigger that invoked the current calculation.	`trgcur()`	DataValue
calcprev	Previous Calculated Value	Returns the most recently calculated value.	`calcprev()`	DataValue
elm	Array Element	Returns the array element at the specified position.	`elm(array, arrayPosition)` array: Specifies the source array. arrayPosition: Specifies the zero-based array position.	Generic value
val	Value	Returns the value portion of a DataValue object.	`val(dataValue)` dataValue: Specifies the DataValue object to evaluate.	Raw value
valsetgood	Value and Set Good Quality	Returns the value portion of a DataValue object and sets expression quality to Good.	`valsetgood(dataValue)` dataValue: Specifies the DataValue object to evaluate.	Raw value
time	Timestamp	Returns the timestamp portion of a DataValue object.	`time(dataValue)` dataValue: Specifies the DataValue object to evaluate.	DateTime
qualcode	Quality Code	Returns the quality code portion of a DataValue object.	`qualcode(dataValue)` dataValue: Specifies the DataValue object to evaluate.	Unsigned Integer
isgood	Is Data Value Good	Returns whether the specified data value has good quality.	`isgood(dataValue)` dataValue: Specifies the DataValue object to evaluate.	Boolean
isbad	Is Data Value Bad	Returns whether the specified data value has bad quality.	`isbad(dataValue)` dataValue: Specifies the DataValue object to evaluate.	Boolean
isunc	Is Data Value Uncertain	Returns whether the specified data value has uncertain quality.	`isunc(dataValue)` dataValue: Specifies the DataValue object to evaluate.	Boolean
hasval	Has Value	Returns whether the specified data value contains a valid value.	`hasval(dataValue)` dataValue: Specifies the DataValue object to evaluate.	Boolean
nologval	Not Logged Value	Returns the specified value without logging it.	`nologval()`	DataValue