Built-in Functions

This topic describes the built-in functions that you can use to create a calculation formula. You can also create your own calculation function.

Note:

In this table, 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.
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.

For all the functions that retrieve previous values, it is similar to performing a RawByNumber query with a count of 1 and direction of backward. A less-than operation (not less-than-or-equal-to) is used on the timestamp to get the sample. Similarly, for all the functions that retrieve next values, it is similar to performing a RawByNumber query with a count of 1 and direction of forward. A greater-than operation (not greater-than-or-equal-to) is used on the timestamp to get the sample.


Function Name	Description
`CurrentValue(<tag name>)`	The value of the tag, interpolated to the calculation execution time. The `CurrentValue` function returns 0 if the quality is 0 (bad quality). This occurs if you initialized it to 0, or if a previous call failed.
`CurrentQuality(<tag name>)`	The current quality of the tag (0 for bad quality and 100 for good quality).
`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 when the calculation is triggered. For unsolicited tags, the calculation execution time is the timestamp delivered with the subscription. Note: When a calculation is performed, the timestamp of the result is the time that the calculation has begun, not the time that it completed. For recovery of polled or unsolicited tags, the calculation execution time is the time when the calculation would have been performed if the collector were running.
`PreviousValue(<tag name>, Time)`	The tag value of the raw sample prior to the current time.
`PreviousQuality(<tag name>, Time)`	The quality of the tag (0 for bad quality and 100 for good quality) prior to the current time.
`PreviousGoodValue(<tag name>, Time)`	The latest good value of the raw sample prior to the current time.
`PreviousGoodQuality(<tag name>, Time)`	The good quality of the raw sample prior to the current time.
`PreviousTime(<tag name>, Time)`	The timestamp of the raw sample prior to the current time.
`PreviousGoodTime(<tag name>, Time)`	The timestamp of the latest good quality of the raw sample prior to the current time.
`NextValue(<tag name>, Time)`	The value of the raw sample after the current timestamp.
`NextQuality(<tag name>, Time)`	The quality of the tag (0 for bad quality and 100 for good quality) after the current time.
`NextTime(<tag name>, Time)`	The timestamp of the raw sample after the current timestamp.
`NextGoodValue(<tag name>, Time)`	The value of the good raw sample after the current time.
`NextGoodQuality(<tag name>, Time)`	The good quality of the raw sample after the current time.
`NextGoodTime(<tag name>, Time)`	The timestamp of the good raw sample after the current time.
`InterpolatedValue(<tag name>, Time)`	The tag value, interpolated to the time that you enter.
`Calculation`	Unfiltered calculated data query that returns a single value, similar to the Excel Add-In feature. For a list of the calculation mode, refer to Calculation Modes.
`AdvancedCalculation`	Unfiltered calculated data query that returns a single value, similar to the Excel Add-In feature. For a list of the calculation mode, refer to Calculation Modes.
`AdvancedFilteredCalculation`	Advanced Filtered calculated data query that returns a single value, similar to the Excel Add-In feature.
`FilteredCalculation`	Filtered calculated data query that returns a single value, similar to the Excel Add-In feature.
`LogMessage(string_message)`	Allows you to write messages to the Calculation collector or the 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, <field name>)`	Returns the value of the field that you have specified. The variable contains the current value of all the fields of a multi-field tag. Before using this function, you must read the tag into a variable, using the `CurrentValue()` function. You can then use the `GetMultiFieldValue` function to access the value of the field. The value of the field that you enter must be the same as the name of the field in the user defined type. If the field name is not found, a null value is returned.
`GetMultiFieldQuality(Variable, <field name>)`	Returns the quality (0 for bad quality and 100 for good quality) of the field that you have specified. The variable contains the current value of all the fields of a multi-field tag. Before using this function, you must read the tag into a variable, using the `CurrentValue()` function. You can then use the `GetMultiFieldValue` function to access the value of the field. The value of the field that you enter must be the same as the name of the field in the user-defined type. If the field name is not found, a null value is returned. If the user-defined type can store individual quality, you get the field quality. Otherwise, you get the sample quality.
`SetMultiFieldValue(Variable, <field name>, Value, Quality)`	Sets the value and the quality for the field that you have specified. You can use this function to construct a multifield value containing values for each field, and then use the `result=` syntax to store the value in Historian.