General Guidelines for Designing a Calculation Formula
This section describes guidelines you should follow when building your calculation formulas.
Identify Time Intensive Calculations
Use the Calculation Execution Time
property of each tag to identify time-intensive queries. In the Historian Administrator, look for the Execution Time on the Calculation tab for an estimate of how long, on average, it takes the calculation for a tag to execute (since the time the collector was started or restarted).
You can also include that column when you export tags to Excel using the Excel Add-In. For more information on exporting tags with the Excel Add-In, refer to the Exporting Tags section of the Using the Historian Excel Add-In manual.
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 Calculation Collector has stopped working. It is possible that the Calculation 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 1-2 minutes and review the newest raw sample again. If the Calculation Collector really stopped, the newest raw sample will be unchanged. If it did change, then the engine is still running, but is lagging behind.
If the collector overrun count is increasing, then the collector is dropping samples and the load needs to be decreased.
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, see Examples of Calculation Formulas.
Unsupported VBScript Functions
MsgBox
InputBox
Milliseconds not Supported in VBScript
The CDate()
function does not support the conversion of a time string with milliseconds in it. Anytime 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 quote that appears 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