General Guidelines for Defining a Calculation Formula

This section provides guidelines that you must follow when defining a calculation formula.

Identify Time Intensive Calculations

Use the Calculation Execution Time property of each tag to identify time-intensive queries. In Historian Administrator, look for the Execution Time on the Calculation section for an estimate of how long, on average, it takes for the calculation per tag (starting from the time the collector was started).

You can also include that column when you export tags to Excel using the Excel Add-In feature. For information, refer to Exporting Tags.

You can also include that column (AverageCollectionTime) when you query the ihTags table using the Historian OLE DB Provider. Sorting by this column will let you find them fast.

Troubleshoot Issues with Large Configurations

If the timestamps of your raw samples appear slightly old, do not assume that the collector has stopped working. It is possible that the collector is just running behind.

For instance, if you have a report rate of 15,000, but the newest raw sample that you see is 20-30 minutes old, wait for 1-2 minutes, and review the newest raw sample again. If the collector stopped, the newest raw sample will be unchanged. If it did change, then the engine is still running, but is lagging behind. If that happens, check if the collector overrun count is increasing. If yes, the collector is dropping samples, and you must decrease the load.

Error Handling in VBScript

Start each script with the On Error Resume Next statement so that errors are trapped. If you use this statement, the script runs even if a run-time error occurs. You can then implement error handling in your VBScript.

It is a good practice to include statements in your VBScript that catch errors when you run the script. If there is an unhandled error, a value of 0 with a bad data quality is stored. When you catch an error in the VBScript, consider including a statement in your calculation that sets the Quality=0 when the error occurs. (The 0 value means that the quality is bad.) If you do not specifically include this setting in your script, Historian stores a good data quality point (Quality=100), even if an error has occurred in your formula. If Quality=100 is not appropriate for your application, consider setting the quality to 0.

You cannot use the On Error GoTo Label statement for error handling, as it is not supported in VBScript. As a workaround, you can write code in the full Visual Basic language and then place it in a .DLL so that you can call it from within your VBScript using the CreateObject function. For examples of calculations that use the CreateObject function, refer to Examples of Calculation Formulas.

Unsupported VBScript Functions

Milliseconds not Supported in VBScript

The CDate() function does not support the conversion of a time string with milliseconds in it. Whenever you use the CDate() function, a literal time string, or a time string with a shortcut, do not specify milliseconds in the time criteria. Milliseconds are not supported in VBScript.

You cannot use milliseconds in times passed into built-in functions such as the PreviousTime and NextValue functions. For example, you cannot loop through raw samples with millisecond precision.

Notes on VBScript Time Functions

Using the VBScript time functions such as Now, Date, or Time can lead to unexpected results, especially in recalculation or recovery scenarios. To avoid these issues, use the CurrentTime built-in function provided by Historian, instead of Now, Date, or Time. For example, the VBScript Now is always the clock time of the computer and is likely not useful when recalculating or recovering data for times in the past. However, the "Now" time shortcut is equivalent to CurrentTime and can be used as input to the other built in functions.

Using Quotation Marks in VBScript

Result = CurrentValue("TagCost""s")

In this example, note the double quotation marks that appear before the letter s in the TagCost"s name in the formula.

Avoiding Circular References in VBScript

Do not use circular references in calculation formulas. For instance, if the tag name is Calc1, a formula with a circular reference would be Result=CurrentValue("Calc1"). Whether the tag is polled or unsolicited, you get a bad value back using the circular reference.

Uninterrupted Object Method Calls

Object method calls are not interrupted. It is possible to exceed the Calculation Timeout setting if you have a method call that takes a long time to execute. The Calculation Timeout error still occurs, but only after the method completes.

Help for VBScript

You can get detailed Help for VBScript by referencing the Microsoft documentation on the MSDN web site. A VBScript User's Guide and Language Reference is available here: http://msdn.microsoft.com/en-us/library/t0aew7h6.aspx

Avoiding Deleted Tags

You can reference a deleted tag in a calculation formula, without an error appearing. For instance, you could enter a formula such as Result=CurrentValue("DeletedTag"), where DeletedTag is the name of the deleted tag. You can do this because when you delete a tag, Historian removes deleted tags from the Tag Database (so you cannot browse for it), but it retains the data for that tag in the archive.

However, it is recommended that you do not reference deleted tag names in your calculation formulas, because if the archive files are removed with the data for the deleted tag, the calculation will not work properly.