The historian has a configurable data directory. All historian variables that use file storage write the data in this directory. It can be changed in <install directory>/Historian/bin/Historian.Settings, key "HistorianFilePath".
Below this directory, each historian variable has its own sub-directory (name is the variable name). Each directory contains these files:
Var.ini
: is a copy of the variable configuration. This allows reconstructing the variable settings and file formats, even if the variable itself has been deleted from the historian.Structs.ini
: exists only for variables that have a structure type. It contains all required structure definitions.data_*.bin
: are the data files.Var.ini
contentsThe Var.ini
file is an ini-File with one section. The section name is "[Var.<variable name>]
". In this section, the following keys can exist:
Active
yes
enables the variable in the runtime system.AggregateAvg
yes
enables calculation of AverageAggregateCalcOffset
AggregateCalcDataType
AggregateCount
yes
enables calculation of CountAggregateMax
yes
enables calculation of MaximumAggregateMin
yes
enables calculation of MinimumAggregateStddev
yes
enables calculation of Standard DerivationArrayLength
DataType
ElementLength
FileResolution
FileSave
yes
to enable file saveMaxFileCount
MaxMem
MinimumFreeDiskSpace
OPCActive
yes
to enable automatic data acquisation of OPC dataOPCConnName
OPCGroupName
OPCVarName
ReadResolution
Structs.ini
contentsThe Structs.ini
is an ini-file with multiple sections. Each section describes one data structure used in the data files. The section name is equal to the structure name, some characters with special meaning are replaced by <xx>
where xx
is the hex-code of the character. The sequence of section entries describes the sequence of structure elements. Valid keys are:
Structure Name
>,<Flags
>Structure Name
> - the structure name (repeated, for historical reasons)Flags
> - hexadecimal encoded flag bits; internal use only; not required for decoding<Element Name>
,<Data Type>
,<Data Type Flags>
,<Element Flags>
,<Array Size>
,<Original Type>
Element Name
> - the element name; some characters with special meaning are replaced by <xx>
where xx is the hex-code of the character.Data Type
> - data type of the structure element; see Data Types; for structures and enumerations, a : and the structure/enumeration name is appended; for strings, a : and the maximum string length is appendedData Type Flags
> - hexadecimal encoded flag bits; internal use only; not required for decodingElement Flags
> - hexadecimal encoded flag bits; valid values from the following list are OR'ed tokether:
0x0010
- PACKED - if set, no bit padding exists before this element0x0020
- PADDING - if set, this element is a padding element and can be ignored or hidden by user application0x0040
- VARIABLE_ARRAY_LENGTH - if set, the array length is given by another structure element instead of the ArrayLength field0x0080
- VARIABLE_STRING_LENGTH - if set, the string length is dynamic, instead of a fixed string length with padding0x0100
- OPTIONAL - if set, the element is optional; its presence is determined by another structure element<Array Size>
- the array length in elememnts
<Original Type> - a protocol specific "original type" for imported structs; may be safely ignored<Length Element>
,<Switch Element>
,<Switch Value>
; this line is present only if at least one of these settings are required<Length Element>
- used if VARIABLE_ARRAY_LENGTH is set; the name of a structure element that gives the array length of this element; some characters with special meaning are replaced by <xx>
where xx is the hex-code of the character.<Switch Element>
- used if OPTIONAL is set; the name of a structure element that determines if this element is present or not; some characters with special meaning are replaced by <xx>
where xx is the hex-code of the character.<Switch Value>
- used if OPTIONAL is set; if the <Switch Element> has this value, then this element is present, otherwise it is absent<xx>
where xx is the hex-code of the character.The data files contain the stored values in a binary format.
File name rules: data_
<resolution>_
<timestamp>.bin
. <resolution> is a number (0 to 7) that specifies the resolution of the data contained in this file; see Resolution. <timestamp> is the start time of this file. The timestamp format is "yyyymmddhhmm" (4 digits for year, 2 digits each for month, day, hour and minute).
All values are stored in the little-endian format (least significant byte first). Each file contains a number of records. The length of each record is determined by the settings in Var.ini.
Each entry has a 16-byte header with the following fields:
unsigned int64
; Timestamp, given as seconds since 1970-01-01 00:00 UTCunsigned int32
; Timestamp, nanoseconds in the second given by tv_secunsigned int32
; Quality for the stored valueAfter the header follow the user data. After the user data (without any padding) follows the next header.
These are the unmodified values as given by OPC or written by an application. Data length is given by the DataType entry in Var.ini, multiplied by the ArrayLength entry (1 if not present).
DataType=string
: Each string has a 4-byte header (giving the really used number of bytes) followed by the data bytes (always ElementLength bytes).
DataType=struct
: Each structure has a length as given in ElementLength
"bit"
elements occupy 1 bit."string"
elements have a 4-byte length element followed by the character data (usually UTF-8 encoded).
If a maximum string length is given, the character data are padded to this length with "\x00" bytes to ensure a fixed structure layout. Othweise no implicit padding exists."time"
elements occupy 12 bytes: 8 byte UNIX-Timestamp (seconds since 1970-01-01 00:00:00 UTC) and 4 byte Nanoseconds"struct"
elements occupy as many bytes as required for their encoding"bit"
elements start at a byte boundary if:
"bit"
elements are packed in one byte if:
These are aggregated values calculated during data recording. Data length is determined by the selected aggregate functions. The following fields may be present (in the given sequence):
Field | Min | Max | Count | Avg | StdDev | Type | Description |
---|---|---|---|---|---|---|---|
Minimum | X | - | - | - | - | DataType AggregateCalcDataType if DataType=struct | The minimal value in the interval. |
Maximum | - | X | - | - | - | DataType AggregateCalcDataType if DataType=struct | The maximal value in the interval. |
Count | - | - | X | - | - | always unsigned int64 | The number of data changes in the interval. |
Sum | - | - | - | X | X | always double | The weighted sum of all data in the interval. |
tv_sec | - | - | - | X | X | always unsigned int64 | The number of seconds of data recorded in the interval. |
tv_nsec | - | - | - | X | X | always unsigned int32 | The number of nanoseconds after the last second of data recorded in the interval. |
SumSq | - | - | - | - | X | always double | The sum of all squared weighted data values in the interval. |
To calculate the average value in the interval: Avg = Sum / (tv_sec + tv_nsec / 1000000000)
To calculate the standard derivation in the interval: StdDev = sqrt(SumSq / (tv_sec + tv_nsec / 1000000000) - Avg * Avg)
Name | Size | Description |
---|---|---|
bit | 1 Bit | truth value (false or true) |
u8, u16, u32, u64 | 1-8 bytes | unsigned integral types with 8-64 bit (1-8 bytes) |
i8, i16, i32, i64 | 1-8 bytes | signed integral types with 8-64 bit (1-8 bytes) |
f32, f64 | 4 or 8 bytes | IEEE-floating-point values with 32 or 64 bit (4 or 8 bytes) |
string | variable | character string, UTF-8 encoded |
time | 12 byte | UNIX timestamp, with resolution 1 nanosecond |
struct | variable | structured data type, encoded according to this rules |
enum | 4 byte | enumeration, always encoded as u32 |
The following resolutions are available for data acquisation:
Fastest
Second
Minute
Hour
Day
The following resolutions are available for file rotation:
Hour
Day
Week
Month
Year