Hyper Historian supports performance calculations based on ICONICS' expressions infrastructure. The expression infrastructure has been mainly designed for real-time data processing while the performance equations are for working with historical data (collections of data values, etc.). Historical calculations are usually very complex and are often not easily human-readable expressions. As an easier approach to performance calculation support, the concept of external .NET based libraries has been developed.
This application note intends to get the user started with function libraries. Basic knowledge of programming in .NET is expected. For more information refer to the help documentation or contact ICONICS Technical Support.
A function library is represented by a public .NET class where all public methods can be used as “calculation methods” inside Hyper Historian. A single assembly can contain one or more function libraries (public .NET classes).
Library functions have to follow simple rules given by the Hyper Historian infrastructure:
Functions have to be declared as public.
Functions have to have unique names within library class.
Functions can be declared as static.
Functions have to return a value – this value is then either logged or used by other functions.
Functions can be invoked by multiple threads at the same time. Do not lock functions – it may decrease overall calculation performance. Instead consider the use of separate contexts for each function call, if needed.
Some functions can be created without internal access to historical data. This approach assumes that all necessary historical data is passed to this function as parameters, thus no direct historical access is required. These functions can be defined as static functions. The following example code shows the simplest function for addition of two double values:
Figure 1 - Simple Summary Function
All necessary .NET types should be available in the following assemblies:
HHPlugIn.dll
HHCommon.dll
Though very simple libraries may not need to refer to any Hyper Historian specific assemblies, typical function libraries will require referencing both of the above mentioned assemblies. Simply go into Project settings and select Add Reference – here you can add/remove or check all available .NET types.
If you need to know some context information such as the execution time, trigger name or previous value add a context parameter to the library function. This parameter must be specified as the first parameter and has to be type of IEvaluatorContext:
Figure 2 - Example Context Parameter
If the user wants to get a complete logged value for further processing then the given parameter has to be the type of LoggerDataValue.
Figure 3 - Example Logger Data Value Parameter
Similarly, to get an array of logged valuesspecify parameter as IList<LoggerDataValue>.
Figure 4 - Example IList<LoggerDataValue> Parameter
These functions have internal historical access similar to standard “History Functions” defined in Hyper Historian for the expression engine. Their parameters should only contain data point identifications, and the function should take care of data reading and processing. The “Function Library” base class has been developed to simplify the historical access.
Figure 5 - Creating a New Function Library
The Function Library base class implements miscellaneous methods for reading data from the historical storage. Data points are identified in all methods by a parameter of type IDataVariableNode. As an example,a method processing time weighted average of logged data samples may look like the following:
Figure 6 - Time-weighted Average Example
Sometimes it is advantageous to dynamically construct a point object of type IDataVariableNode, perhaps based on a string or numeric parameter. Then in the function we would need to try to get or construct the object (IDataVariableNode) before reading its data. To accomplish this, the following method is available, where “XXX” presents the Hyper Historian data point:
Figure 7 - Get a Data Variable Node
The new function library needs to be built in Visual Studio, then the created .dll file needs to be copied to the ICONICS Component folder.
To enable a particular method for use in Hyper Historian a new Calculation Function has to be added in the Hyper Historian configuration in the “Calculation Function” section. The parameters of the calculation function should be specified. The number of parameters has to match the number of arguments declared in the .NET method with one exception – if the very first parameter is of type IEvaluatorContext it will be set by the Hyper Historian infrastructure and should not be defined in the custom function.
Once all parameters are configured, the Expression tab of the Calculation Function should specify the custom function using the following syntax:
{{lib:Assembly_name!Class_name:Function_name}}
Where:
- Assembly_name is the actual assemblyname (example: MyLibrary.dll). If the name doesn’t contain directory info then Hyper Historianassumes this library is stored in ICONICS Component folder.
- Class_name is a class name including namespace (example:MyLibrary.MyClass). The class must be public.
- Function_name is the actualfunction name inside specified class (example: MyFunction).
Figure 8 - New Calculation Function with Parameters
Figure 9 - Special Expression Test
All calculation functions created according to the steps above can be reused for value logging.
Simply create new Calculated Tag or Calculation Function and browse for the newly created Calculation Function under Functions à Calculation Functions.
Figure 10 - Browsing Calculation Functions
Figure 11 - Parameters Definition
The easiest way to debug any custom library is to use Visual Studio2010 or higher and attach it to the logger process. To simplify development, a developer can select the function library as the startup project and in the project’s properties à debugging select “external program” and browse for HHLoggerHost.exe (which is located by default in the Components folder). Make sure to copy the function library into the Component folder (or the folder which contains the Hyper Historian assemblies). This can be done in post-build steps.
Function library should be deployed as set of required assemblies plus header files, exported from the Hyper Historian configuration. The header (descriptor) files can be exported from the Hyper Historian configuration in Workbench. Go to Calculation Functions, select a Calculation Folder, right click it and select Export Library.
To deploy it on a different PC, first copy all the assemblies to the ICONICS Components folder and then import the library header files. Once the import is completed all library functions should be available for use in calculated tags.
See Also:
Performance Settings for Calculation Tags