Built-in Functions

In the following table, tagname refers to any Historian tag. Time refers to the actual time; this time can include absolute and relative time shortcuts. See the Date/Time Shortcuts and Relative Date/Time Shortcuts sections for more information.

See the following table for the built-in function names and descriptions.


Function Name	Description
`CurrentValue(tagname)`	The value of `tagname` interpolated to the calculation execution time. The `CurrentValue` function returns 0 if the quality is 0 (bad). This is true if you initialized it to 0, or if a previous call failed, which would also set it to 0.
`CurrentQuality(tagname)`	The current quality (0=bad or 100=good) of `tagname`.
`CurrentTime`	The calculation execution time, which becomes the timestamp of the stored value. For real time processing of polled tags, the calculation execution time is the time that the trigger fired. For unsolicited tags, the calculation execution time is the timestamp delivered with the subscription. Note: When a calculation tag runs and a result is assigned, the timestamp of the result is the time that the calculation began running, not the time that it finished. For recovery of polled or unsolicited tags, the calculation execution time is the time that the calculation would have fired if the collector was running.
`PreviousValue(tagname, Time)`	The value of the raw sample prior to `Time` for `tagname`. This is similar to performing a `RawByNumber` query with a count of 1 and direction of backward. A less than (not less than or equal to) on the timestamp is used to get the sample.
`PreviousQuality(tagname, Time)`	The quality (0=bad or 100=good) of the raw sample before `Time` for `tagname`. This is similar to performing a `RawByNumber` query with a count of 1 and direction of backward. A less than (not less than or equal to) on the timestamp is used to get the sample.
`PreviousGoodValue(tagname, Time)`	The good value of the raw sample prior to `Time` for `tagname`. This is similar to performing a `RawByNumber` query with a count of 1 and direction of backward. A less than (not less than or equal to) on the timestamp is used to get the sample.
`PreviousGoodQuality(tagname, Time)`	The good quality (0=bad or 100=good) of the raw sample before `Time` for `tagname`. This is similar to performing a `RawByNumber` query with a count of 1 and direction of backward. A less than (not less than or equal to) on the timestamp is used to get the sample.
`PreviousTime(tagname, Time)`	The timestamp of the raw sample before `Time` for `tagname`. This is similar to performing a `RawByNumber` query with a count of 1 and direction of backward. A less than (not less than or equal to) on the timestamp is used to get the sample.
`PreviousGoodTime(tagname, Time)`	The good timestamp of the raw sample before `Time` for `tagname`. This is similar to performing a `RawByNumber` query with a count of 1 and direction of backward. A less than (not less than or equal to) on the timestamp is used to get the sample.
`NextValue(tagname, Time)`	The value of the raw sample after `Time` for `tagname`. This is similar to performing a `RawByNumber` query with a count of 1 and direction of forward. A greater than (not greater than or equal to) on the timestamp is used to get the sample.
`NextQuality(tagname, Time)`	The quality (0=bad or 100=good) of the raw sample after `Time` for `tagname`. This is similar to performing a `RawByNumber` query with a count of 1 and direction of forward. A greater than (not greater than or equal to) on the timestamp is used to get the sample.
`NextTime(tagname, Time)`	The timestamp of the raw sample after `Time` for `tagname`. This is similar to performing a `RawByNumber` query with a count of 1 and direction of forward. A greater than (not greater than or equal to) on the timestamp is used to get the sample.
`NextGoodValue(tagname, Time)`	The value of the good raw sample after `Time` for `tagname`. This is similar to performing a `RawByNumber` query with a count of 1 and direction of forward. A greater than (not greater than or equal to) on the timestamp is used to get the sample.
`NextGoodQuality(tagname, Time)`	The quality (100=good) of the raw sample after `Time` for `tagname`. This is similar to performing a `RawByNumber` query with a count of 1 and direction of forward. A greater than (not greater than or equal to) on the timestamp is used to get the sample.
`NextGoodTime(tagname, Time)`	The timestamp of the good raw sample after Time for tagname. This is similar to performing a `RawByNumber` query with a count of 1 and direction of forward. A greater than (not greater than or equal to) on the timestamp is used to get the sample.
`InterpolatedValue(tagname, Time)`	The value of `tagname`, interpolated to the `Time` passed in.
`Calculation`	Non-filtered calculated data query that returns a single value, similar to the Excel Add-In. For a list of the calculation mode, refer to Calculation Modes section in the Getting Started with Historian guide.
`AdvancedCalculation`	Non-filtered calculated data query that returns a single value, similar to the Excel Add-In. For a list of the calculation mode, refer to Calculation Modes in the Getting Started with Historian guide.
`AdvancedFilteredCalculation`	Advanced Filtered calculated data query that returns a single value, similar to the Excel Add-In.
`FilteredCalculation`	Filtered calculated data query that returns a single value, similar to the Excel Add-In.
`LogMessage(string_message)`	Allows you to write messages to the Calculation or Server-to-Server Collector log file for debugging purposes. The collector log files are located in the Historian\LogFiles folder. Note: The `LogMessage` function is the only function that does not appear in the wizard.
`GetMultiFieldValue(Variable, FieldName)`	Returns the value of the field identified by the `FieldName`. The variable holds the current value of all the fields of a multi-field tag. You must read the tag into a variable before using this function. The `CurrentValue()` function is used to read all fields into the variable. You can then use the `GetMultiFieldValue` function to access the value one field. The value of the `FieldName` entered should be the same as the name of the field in the user defined type. If the field name is not found, then a NULL value is returned.
`GetMultiFieldQuality(Variable, FieldName)`	Returns the quality (0=bad or 100=good) of the field identified by the `Fieldname`. The variable holds the current value of all the fields of a multi-field tag. You must read the tag into a variable before using this function. The `CurrentValue()` function is used to read all fields into the variable. You can then use the `GetMultiFieldQuality` function to access the field quality. If the user defined type has a "Store Individual Quality" specified, then you get the field quality. Otherwise, you get the sample quality. The value of the `FieldName` entered should be the same as the name of the field specified. If the field name is not available or does not match, then a NULL value is returned.
`SetMultiFieldValue(Variable, FieldName, Value, Quality)`	Sets the value and the quality for a field identified by the `FieldName`. You can use this function to construct a multifield value containing values for each field, then use "result=syntax to store the value in Historian.

Note: You cannot control the timestamp of the stored sample. It is determined by the triggering tag or polling schedule.

You cannot use microseconds for any of the built-in calculation functions.