Using Calculation Collector

Important: You do not have the latest version of Historian! You are missing out on the newest capabilities and enhanced security. For information on all the latest features, see the Historian product page. For more information on upgrades, contact your GE Digital sales agent or e-mail GE Digital Sales Support. For the most up-to-date documentation, go here.

Using the Calculation Collector to Define and Execute Calculations

There are four basic steps to defining and executing a calculation formula:
  1. Start the Calculation Collector.
    The Calculation Collector should automatically start when you start your system. If the Calculation Collector is not running, refer to Configuring an Historian Data Collector for Automatic Startup.
    Optionally, you can use the Calculation Collector tab to configure Calculation Collector-specific fields. See Configuring Calculation Collector Tab.
  2. Create the calculation tag (also referred to as destination tag). See Creating a Calculation Tag.
  3. Build the calculation formula. See About Calculation Formulas.
  4. If the tag is unsolicited, assign a trigger to the calculation tag.

Configuring Calculation Collector Tab

To display the Configuration Tab for a Calculation Collector:
  1. Select a Calculation Collector that you want to configure from the list on the left, and click Configuration Tab.
    The Collector Specific Configuration (Calculation) dialog appears.
  2. The Collector specific configuration field settings are explained below:
    Field Description
    Calculation Timeout (sec)
    The maximum time allowed for an individual calculation to execute before being terminated. The default is 10 seconds. If you exceed this, the calculation is canceled and a bad data quality sample is stored in the Destination tag with a subquality calculation error.
    Note: If you update, the Calculation Timeout (sec) for a Server-to-Server or Calculation Collector, you must pause and resume or stop and restart the collector executable to apply the changes.
    Max Recovery Time (hr) Applies only to event-based tags. The maximum time, in hours before now, that the collector will attempt to restore data during recovery logic.

    The default is 4 hours.

Creating a Calculation Tag

Prior to building your calculation formula, you must manually add or copy a calculation tag (using Excel Add-in, SDK, File Collector, or the Copy Tag command).
  1. To add a new tag manually, see Using the Non-Web Admin to Add a New Tag Manually.
  2. To copy a tag, see Using the Non-Web Admin to Copy a Tag.
    Note: You cannot browse a Calculation Collector through the Add Tags From Collector dialog box in the Historian Administrator.

Manual Recalculation of Tags

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 do not execute again with the new data but unsolicited calculations will retrigger. Hence, it is possible that calculations performed for tags during and after the connection loss might not be entirely accurate.

With the recalculate feature, you can recalculate all tags for time period during and after the connection loss. The recalculated tags 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 on the Configuration tab of the Collector Maintenance screen for the specified Calculation or Server-to-Server Collector.

S2S/S2C collector Backfill procedure

With the Recalculate feature you can recalculate all tags for the time period during and after the connection loss. The recalculated tags will use the most accurate values in calculations.

During the period of connection loss, the collector buffers the data. When the connection is restored, the buffered data is forwarded to the Historian Server. When the buffered data arrives, the timestamps show earlier time than the most recent calculation timestamp.

Since the timestamp is earlier, the polled calculations will not execute again with the new data but the unsolicited calculations will re-trigger. Therefore, it is possible that calculations performed for tags during and after the connection loss might be not be entirely accurate.

Run S2C Backfill via Command line
ihServerToServerCollector.exe RELOADFILENAME=[file location] 
RELOADUSERNAME=[Username] <start time> <end time>

Example: C:\Program Files\Proficy\Proficy Historian\x86\Server>ihServerToServerCollector.exe RELOADFILENAME=c:\taglist.txt RELOADUSERNAME=\Administrator 1516875659 1516875785

See the following information about the parameters:
  • RELOADFILENAME: This is an optional parameter. File name should be absolute path, this file consists of the tag names, for which Backfill should be performed, each tag should be separated by new line. Any discrepancies in the file/no file exists/parameter not provided leads to Backfill all the tags related to the collector at the current time. After the Backfill, file gets deleted.
  • RELOADUSERNAME: This is an optional parameter. This username is used only when destination server is Historian for auditing purpose, and gets ignored when the destination is cloud.
  • TIMESTAMP: This parameter accepts Start and end time in seconds in epoch format for which Backfill should happen. https://www.epochconverter.com/

Using the Manual Recalculation Feature

Note: If you perform a server-to-server recalculation on source and destination servers whose clocks are not synchronized, extra data points may appear and original data points may not be recalculated. To ensure this does not occur, ensure the time is synchronized on both source and destination servers.
  1. From the Historian Administrator, click the Collectors link to display the Collector Maintenance screen.
  2. Select the Calculation Collector.
  3. Click the Recalculate button.
    The Recalculate Tags for Collector dialog box appears.
  4. Enter a start date and time and end date and time.
  5. Select a recalculation option:
    • Select the Recalculate All Tags for Collector option if you want to recalculate all tags for the specified time period.
    • Select the Recalculate Selected Tags Only option if you want to recalculate only specific tags during a time period.
  6. If you selected the Recalculate Selected Tags Only option, enter tag browse criteria, click Browse, and select the desired tags (or all tags).
  7. Click Recalculate.
    A message box appears.
  8. Click OK.
    The recalculation runs and you return to the Collector Maintenance screen.

Performing Calculations on Migrated Data

After you migrate data to Historian, you may want to perform some calculations on that migrated data.

Before performing calculations on migrated data, make sure that you take into account how you manage your archives. Ideally, you should have an archive already created for the time of the calculated data.

For unsolicited calculation tags, migration of data will cause the calculation tags to fire automatically for the time associated with the migrated data points. Archives will potentially grow beyond the configured default size.

Note: Adjust the value for the DataIsReadOnlyAfter field on the Security tab of the Data Store Maintenance screen (or the ActiveHours property) so that the value is large enough to contain the calculated data. By default, this value is 1 month.

Using the AddData Function to Write Data to an Arbitrary Tag

The Calculation Collector supports writing 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.

The syntax of the AddData function is as follows:

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

All parameters are required. TagNames can be either a single tag name, or an array of tag names in double quotes. Values can be a single value, or an array of values matched to an array of tag names. Only one value can be passed for each tag name. String values entered into the Values parameter must be enclosed in double quotes (for example, "value"). If you do not want to pass a value to the Timestamp or Quality parameter, replace the value with NULL.

Tip: If the TimeStamp parameter is left empty (for example, errs = AddData ("FIX.Sine", 33, null,100), the current time will be used as a timestamp.

Timestamp and Qualities Parameters

The Timestamp and Qualities parameters are optional.

Timestamp

The Timestamp parameter takes an absolute time value enclosed within two quotes ("). This value must be a timestamp in the past, for example: "24/12/20042:32:15 PM".

Quality

The Quality parameter takes an integer value from 0 to 100 (0 being bad quality, 100 being good quality).

Errs is an output variable, which receives an array of status codes, one for each tag written to. The following table describes the status codes.

Error Code String Description
0 ihSTATUS_OK The values were successfully written to the tags.
-1 ihSTATUS_FAILED The operation failed.
-2 ihSTATUS_API_ TIMEOUT The operation timed out while connecting to Historian.
-3 ihSTATUS_NOT_ CONNECTED The Calculation Collector could not connect to the Historian archive.
-4 ihSTATUS_INTERFACE_ NOT_FOUND The collector could not be contacted or connected to.
-5 ihSTATUS_NOT_ SUPPORTED The write operation was not supported.
-6 ihSTATUS_DUPLICATE_ DATA The write operation would have created duplicate data in the archive.
-7 ihSTATUS_NOT_VALID_ USER The user name used to connect to the Historian archive is not valid.
-8 ihSTATUS_ACCESS_ DENIED The user name used to connect to the Historian archive does not have write access to the Historian archive.
-9 ihSTATUS_WRITE_IN_ FUTURE The timestamp supplied with the function call is set to a time in the future.
-10 ihSTATUS_WRITE_ ARCH_OFFLINE The Historian archive is currently offline.
-11 ihSTATUS_ARCH_ READONLY The Historian archive is set to read-only.
-12 ihSTATUS_WRITE_ OUTSIDE_ACTIVE An attempt was made to write data to a time before the archive was created.
-13 ihSTATUS_WRITE_NO_ ARCH_AVAIL No Historian archive is available for writing.
-14 ihSTATUS_INVALID_ TAGNAME The tag name or tag names supplied do not exist in the Historian archive.
-15 ihSTATUS_LIC_TOO_MANY_TAGS The function has 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 Historian archive.
-17 ihSTATUS_LIC_ INVALID_LIC_DLL The Historian license is expired or invalid.
-18 ihSTATUS_NO_VALUE No value was supplied for the tag.
-19 ihSTATUS_DUPLICATE_ INTERFACE Two collectors exist with the same name.
-20 ihSTATUS_NOT_ LICENSED The Historian license is not installed.
-21 ihSTATUS_CALC_CIRC_ REFERENCE A circular reference has been entered in the Calculation formula.
-22 ihSTATUS_BACKUP_ EXCEEDED_SPACE The Historian archive being written to has reached the Minimum Hard Drive Space setting, and no new archives are being created.
-23 ihSTATUS_INVALID_ SERVER_VERSION The Historian archive being written to is not compatible with the calculation collector.
-24 ihSTATUS_DATA_ RETRIEVAL_COUNT_ EXCEEDED Indicates there were too many data points to retrieve.

Examples

The following examples show sample usage of the AddData function.

Simple data write
This example writes a single value, the current time, and a good quality value to a single tag.
errs = AddData("Bucket Brigade.UInt4", 9, "Now", 100)
Writing array data
This example uses arrays to write several values to several tags.
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
This extends the previous example, including time stamps and qualities for the 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)

Using a ShouldPreReadData Registry Key

Use a ShouldPreReadData registry key when your calculation tags use AddData to write to tags that are also used as trigger tags or used in calculation formulas such as CurrentValue("MyTag")+5.

If you want to skip the pre-read of data and have Calculation Collector query data at tag processing time instead, you have to make a registry key on the machine running the Calculation Collector.

Use the following steps to create a value as a DWORD for ShouldPreReadData registry key.

Note: This registry key cannot be performed on a Server to Server collector scenario.
  1. From the Start menu, select Run and enter Regedit.
  2. Open the following key folder HKEY_LOCAL_MACHINE\Software\Intellution, Inc.\iHistorian\Services\CalculationCollector\.
  3. Create a value as DWORD called ShouldPreReadData and set it to zero value (to have the calculation collector skip pre-reading of data, set this value to 0).
  4. Click OK, and close the Registry Editor.
  5. Restart Calculation Collector for the changes to take effect.