Calculation Formulas

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.

The following table outlines the date/time shortcuts that you can use in calculation formulas. If Historian accepts an abbreviation for the shortcut, in addition to the full shortcut, the abbreviation appears in bold in the following table.

Relative Date/Time Shortcuts

Optionally, you can add or subtract relative times to the absolute times listed in the following table. The following table outlines the relative time shortcuts. If Historian accepts an abbreviation for the shortcut, in addition to the full shortcut, the abbreviation appears in bold in the following table.

Example 1: Counting the Number of Bad Quality Samples

This example shows how to loop through samples of tag named C2 to count the number of bad quality samples.

Dim count, starttime, endtime, tagquality count=0
StartTime=CurrentTime EndTime=DateAdd("n",-1,StartTime) Do while StartTime>EndTime
TagQuality=PreviousQuality("C2",StartTime)
startTime=PreviousTime("C2",StartTime) IF TagQuality=0 THEN
count=count + 1
END IF loop Result=count

Example 2: Counting the Number of Collected Digital 1s For a Tag

The following example counts the number of collected digital 1s for a tag so that, for instance, you can determine how many times a pump is turned ON and OFF.

Dim count, starttime, endtime,tagquality,TagValue 
count=0
StartTime=CurrentTime 
EndTime=DateAdd("h",-1,StartTime) 
On error resume next
Do while StartTime>=EndTime 
TagValue=PreviousValue("FIX.DI.F_CV",StartTime) 
TagQuality=PreviousQuality("FIX.DI.F_CV",StartTime) 
startTime=PreviousTime("FIX.DI.F_CV",StartTime)
IF TagQuality=100 AND TagValue=1 then 
count=count + 1
END IF
loop
Result=count

Example3: Determining the Trigger When Using Multiple Trigger Tags

The following example shows how to determine which tag triggered the calculation, from a list of two possible trigger tags. The example compares the two trigger tags and determines which one has the newest raw sample. This method of getting the newest raw sample can also be used determine if a remote collector is sending data or is disconnected from the server.

In the example that follows, archive compression is disabled for both of these tags.

dim timetag1 
dim timetag2 
dim tag1
dim tag2

tag1 = "BRAHMS.AI1.F_CV" 
tag2 = "BRAHMS.AI2.F_CV"

' Get the timestamp of the newest raw sample for tag1:
timetag1 = previousTime(tag1, CurrentTime)

' Get the timestamp of the newest raw sample for tag2:
timetag2 = previousTime(tag2, CurrentTime)

if timetag1 > timetag2 then
' If tag1 triggered me, then:
result = 1 else
' If tag2 triggered me, then:
result = 2 
end if

Example 4: Using Array or Multifield data in Calculation

You can create tags of arrays and multifield types and use the Calculation collector and Server to Server Collector and Distributor with these tags.

Arrays

To use the Array data as input to a calculation formula you can use the name of the array tag like "Array1" or the individual element of the array like "Array1[4]". For example, if you have an array tag "Array1" of floating point values and a calculation tag "FloatCalc1" of float data type, then you can use the array as input to calculate a float value.

result = currentvalue("Array1[4]")+5

Youcan use Calculation() function to read the array tag as shown in the following code.

Result = Calculation("Array1","Average","Now 1Minute","Now",Quality)

In this example, the calculation tag should be an array tag because the average of an array is an array, not a single value. Each element is averaged over the time range. Since an average of an integer or float array is a floating point value, the calculation tag must be a single or double float array.

If you want to find the minimum of array elements in a given time, then use vbscript code to compute and store the result in a Float tag as shown.

if CurrentValue("Array1[0]") < CurrentValue("Array1[1]") then
    Result = CurrentValue("Array1[0]")
else
    Result = CurrentValue("Array1[1]")
end if

Multifield

If you have a user-defined type "MySample" with fields "r;FloatVal" and "r;IntVal" you can create Tag1 and use the value of one field in an Integer Calc Tag. The destination tag is not a multifield tag.

result = currentvalue("Tag1.IntVal")+5

Example 5: Storing Array or Multifield data in Calculation tags

Array

If your calculation tag is an array tag, then you can copy the entire array values into it. For example, you can copy the entire values from Array1 into Array2 using the given code.

result = CurrentValue("Array1")

You can take an array value collected from a field device and adjust the values before storing it in another array tag Array2 using this code:

dim x
x=CurrentValue("Array1")
x(1) = x(1)+10
result = x

You can simply construct an array value inside your formula and store it in Array2, for example:

dim MyArray(2)' The 2 is the max index not the size
MyArray(0)=1
MyArray(1)=2
MyArray(2)=3 result = MyArray

Multifield

You can have the Calculation Collector combine collected data into a multifield tag. Create a calculation Tag1 using the user-defined Type "MySample," then use this formula to fill in the fields:

Dim InputValue, myval,x,y

' get the current value of another multifield tag
InputValue = CurrentValue("tag1")

' get the values of each of the fields
x = GetMultiFieldValue(InputValue, "IntVal")
y = GetMultiFieldValue(InputValue, "floatval")

' store the field values in this tag
SetMultiFieldValue myval,"IntVal",x,100
SetMultiFieldValue myval,"floatval",y,100
Result = myval

Example 6: Using Array or Multifield data to trigger calculation

Array

You can use the array tag as a trigger tag for your float or array calculation tags. For example, you can use Array1 as a trigger so that when it changes, the "CalcArray1" tag will be updated. You cannot use an individual array element such as "Array1[3]" as a trigger, you must use the entire array tag as the trigger tag.

Multifield

You can use a multifield tag as a trigger tag by either using the tagname "Tag1" or tagname with the field name "Tag1.FloatVal".

Example 7: Sending Array or Multifield data to a Remote Historian

Array

You can use the Server to Server Collector or Server to Server Distributor to send array data to a destination Historian. If the destination Historian is version 6.0 or later, you can simply browse the tags and add them.

You cannot send an array to the older versions of archiver (Pre 6.0 versions) as these archivers will store the array tags as a blob data type in the destination and you will not be able to read them. However, you can send individual elements of an array to these archivers, for example, result = currentvalue("Array1 [4]").

Multifield

The destination needs to be Historian 6.0 or above to store a multifield tag but you can send individual fields to a pre Historian 6.0 archiver.

For multifield tags, you must create the User Defined Type manually at the destination

You can write an entire multified tag data sample in one write or you can create multiple tags in the destination, one for each field you want to copy. For example, if you have one tag "Tag1" with two fields "FloatVal" and "IntVal" on a source archiver, then you can create two tags ("Tag1.FloatVal" and "Tag1.IntVal") on the destination.

Note: If you change a field name or add or remove fields you must update your collection and your destination tags.

Example 8: Reading and writing a Multifield tag using MultiField functions

The following example shows how to read an entire multifield tag, using the GetMultiFieldValue function and to write the value to a field in another tag using the SetMultiFieldValue function.

Dim CurrMultifieldValue

' Read the value of a multi field tag into a variable
CurrMultifieldValue = CurrentValue("MyMultifieldTag")

' Read the field value of multifield tag into the temporary variable
F1 = GetMultiFieldValue(CurrMultifieldValue, "Temperature Field")

' Perform a calculation on the value
Celcius = (F1 32)/ 9* 5

' Set the calculated value to another field of the multifield tag 
SetMultiFieldValue(CurrMultifieldValue, "Temperature Field Celcius", Celcius, 100) 
result = CurrMultifieldValue

The following table describes the types of actions supported by the Wizard.