Using the Calculation Collector

Workflow for Using the Calculation Collector

After you have added an instance of the Calculation collector, to perform a calculation using the collector, you must perform the following steps:
Step Number Description Notes
1 Create a tag administrative security group. In addition to defining the iH Tag Admins who have the power to create, modify, and remove tags, you can also define individual tag level security to protect sensitive tags. This step is required to prevent a user from intentionally or unintentionally launching malicious VBScript code. For example, if a user connected to the data archiver created a calculation tag to file system object, that user could potentially delete all the files on your hard drive. To prevent this, implement tag-level security.
1 Configure the Calculation collector. This step is required only if you want to change the default values for collector-specific parameters.
2 Create the source and destination tags. To do so, you can add a tag manually using Historian Administrator or the Web Admin console. Or, you can copy a tag.
Note: You cannot browse a Calculation collector through the Add Tags From Collector window in Historian Administrator.
 This step is required.
3 Assign a trigger to the destination tag. This step is required only if the tag is unsolicited (that is, event-based).
4 Define the calculation formula. This step is required.

Configure the Calculation Collector

Procedure

  1. Access Historian Administrator.
  2. On the Main page, in the Collectors section, double-click the collector that you want to configure. Alternatively, you can select Collectors, and then select the collector from the Collectors pane.
    The General section of the collector appears, displaying the properties of the collector.
  3. Select Configuration, and then enter values as described in the following table.
    Field Description
    Calculation Timeout (sec) The maximum time a calculation must be performed before being terminated. The default value is 10 seconds. If the calculation takes longer, it is canceled, and a bad data quality sample is stored in the destination tag with a subquality, calculation error.
    Max Recovery Time (hr) The maximum time, in hours till now, that the collector will attempt to restore data. This is applicable only to event-based tags. The default value is 4 hours.

    If you want to disable automatic calculation of the tag, set the value of this field to 0.
  4. Pause and resume the data collection. Or restart the collector.
    The Calculation collector is configured.

Recalculate Tag Values Manually

About this task

One instance when you might want to recalculate data would be after the Historian server restores a lost connection. During the period of connection loss, the collector buffers data. When the connection is restored, the buffered data is forwarded to the Historian Server.

When the buffered data arrives, the timestamps are earlier than the most recent calculation timestamp. Since the timestamp is earlier, polled calculations are not performed again with the new data unlike the unsolicited calculations. Hence, it is possible that calculations performed for tags during and after the connection loss might not be entirely accurate. Therefore, you can recalculate tag data for the time period during and after the connection loss. The recalculated data will use the most accurate values in calculations.
Note: You can still use manual recalculation without automatic recalculation by disabling the automatic recalculation feature. To disable the automatic recalculation, set the Max Recovery Time to 0 in the Configuration section of the Collector Maintenance page of the collector.

Procedure

  1. Access Historian Administrator.
  2. On the Main page, in the Collectors section, double-click the collector whose tag values you want to recalculate. Alternatively, you can select Collectors, and then select the collector from the Collectors pane.
    The General section of the collector appears, displaying the properties of the collector.
  3. Select Recalculate.
    The Recalculate Tags For <collector name> window appears.

  4. Provide values as described in the following table.
    Field Description
    Start Time Enter the start date and time. Tag values calculated after this date and time will be recalculated.
    End Time Enter the end date and time. Tag values calculated until this date and time will be recalculated.
    Tags to Recalculate Specify whether you want to recalculate values for all the tags added in the collector or just the selected tags. If you select Recalculate Selected Tags Only, the Tag Name and Description fields are enabled.
    Tag Name and Description Enter the search criteria to filter out the tags whose values you want to recalculate. These fields are enabled only if you select Recalculate Selected Tags Only. After you select Browse, the search results appear in the Browse Results section.
  5. Select Recalculate.
    A message appears, asking you to confirm that you want to recalculate the data.
  6. Select OK.
    The tags values are recalculated.

Write Data to an Arbitrary Tag

Before you begin

If the tags that you want to specify are also used as trigger tags or source tags of a calculation, ensure that the Calculation collector does not read the tag data before you add the tag. To do so:
  1. Access the ShouldPreReadData registry key under HKEY_LOCAL_MACHINE\Software\Intellution, Inc.\iHistorian\Services\CalculationCollector\.
  2. Create a DWORD named ShouldPreReadData, and set its value to zero.
  3. Restart the collector.

About this task

You can write data to an arbitrary tag in the Historian archive through the AddData function. This function is used in a calculation formula to write values, errors, time stamps and qualities of one or more tags to the Historian archive.

Procedure

Use the following syntax to write data to an arbitrary tag: 
errs = AddData(TagNames, Values, Timestamps, Qualities)
The following table provides information on the parameters.
Parameter Description
TagNames Identifies the names of the tags. A value is required, and must exist in the archive to which you want to send the tag data. You can provide a single tag name or an array of tag names, enclosed in double quotation marks.
Values Identifies the values of the tags. A value is required, and must be a single value or an array of values, depending on whether the tag name is a single name or an array. Values must be enclosed in double quotation marks. You can enter only a single value for each tag name.
Timestamp Identifies the timestamp of the tag data. Enter an absolute time value, enclosed in double quotation marks ("24/12/20242:32:15 PM"). If you do not want to enter a value, enter NULL, and the current time will be considered. Do not enter a future timestamp.
Qualities Identifies the quality of the tag data. Enter an integer from 0 to 100, with 0 indicating bad quality and 100 indicating good quality.
Tip: You can refer to Examples of Using the AddData Function. For information on the status codes and their descriptions, refer to Status Codes of the AddData Function.

Examples of Using the AddData Function

This topic provides examples of using the AddData function.

Writing a Single Tag Value

The following example is used to write a single value, the current time, and a good quality value to a single tag.
errs = AddData("Bucket Brigade.UInt4", 9, "Now", 100)

Writing an Array of Tags

The following example is used to write an array of tags and their values.
Dim Tags(3)
Tags(0) = "Bucket Brigade.Boolean" 
Tags(1) = "Bucket Brigade.Int4" 
Tags(2) = "Bucket Brigade.Real8" 
Tags(3) = "Bucket Brigade.String"

Dim Values(3) 
Values(0) = True 
Values(1) = 5
Values(2) = 172.3
Values(3) = "Hello, World"

errs = AddData(Tags, Values, Null, Null)

Writing Timestamps and Qualities

The following example is used to write an array of tags and their values in addition to timestamp and quality values.
Dim Tags(3)
Tags(0) = "Bucket Brigade.Boolean" 
Tags(1) = "Bucket Brigade.Int4" 
Tags(2) = "Bucket Brigade.Real8" 
Tags(3) = "Bucket Brigade.String"

Dim Values(3) 
Values(0) = True 
Values(1) = 5
Values(2) = 172.3
Values(3) = "Hello, World"

Dim Timestamps(3) 
Timestamps(0) = "Today" 
Timestamps(1) = "Now" 
Timestamps(2) = "Yesterday"
Timestamps(3) = "24/12/2004 2:32:15 PM"

Dim Qualities(3) 
Qualities(0) = 100
Qualities(1) = 0
Qualities(2) = 100
Qualities(3) = 0

Dim errs

errs = AddData(Tags, Values, Timestamps, Qualities)

Status Codes of the AddData Function

This topic describes the status codes that appear when you use the AddData function. These status codes are stored in the Errs output variable as an array of status codes, one for each tag. The following table describes the status codes.
Status Code String Description
0 ihSTATUS_OK The values have been successfully written to the tags.
-1 ihSTATUS_FAILED The operation has failed.
-2 ihSTATUS_API_ TIMEOUT The operation has timed out while connecting to Historian.
-3 ihSTATUS_NOT_ CONNECTED The Calculation collector cannot connect to Historian.
-4 ihSTATUS_INTERFACE_ NOT_FOUND You cannot connect to the Calculation collector.
-5 ihSTATUS_NOT_ SUPPORTED The write operation is not supported.
-6 ihSTATUS_DUPLICATE_ DATA The write operation has created duplicate data in the archive.
-7 ihSTATUS_NOT_VALID_ USER The username used to connect to the Historian archive is not valid.
-8 ihSTATUS_ACCESS_ DENIED The username used to connect to Historian does not have write access to the archive.
-9 ihSTATUS_WRITE_IN_ FUTURE The timestamp that you have entered is set to a time in future.
-10 ihSTATUS_WRITE_ ARCH_OFFLINE The archive is currently offline.
-11 ihSTATUS_ARCH_ READONLY The archive is set to read-only.
-12 ihSTATUS_WRITE_ OUTSIDE_ACTIVE An attempt has been made to write data to a time before the archive has been created.
-13 ihSTATUS_WRITE_NO_ ARCH_AVAIL No archive is available for writing.
-14 ihSTATUS_INVALID_ TAGNAME The tag names that you have entered do not exist in the archive.
-15 ihSTATUS_LIC_TOO_MANY_TAGS You have attempted to add more tags than the current license allows.
-16 ihSTATUS_LIC_TOO_ MANY_USERS There are currently too many users connected to the archive.
-17 ihSTATUS_LIC_ INVALID_LIC_DLL The Historian license is expired or invalid.
-18 ihSTATUS_NO_VALUE You have not entered a tag value.
-19 ihSTATUS_DUPLICATE_ INTERFACE Two collectors with the same name exist.
-20 ihSTATUS_NOT_ LICENSED The Historian license is not activated.
-21 ihSTATUS_CALC_CIRC_ REFERENCE A circular reference has been entered in the calculation formula.
-22 ihSTATUS_BACKUP_ EXCEEDED_SPACE The archive has reached the Minimum Hard Drive Space setting, and no new archives are being created.
-23 ihSTATUS_INVALID_ SERVER_VERSION The archive is not compatible with the Calculation collector.
-24 ihSTATUS_DATA_ RETRIEVAL_COUNT_ EXCEEDED There are too many data points to retrieve.