|
The trend history system has a master file for each trend acting
as an index. The sample data is written to numbered data files.
When a data file is filled, data will be written to another trend
data file (pointed to by the master file).
Note: For previous Citect versions, see: Q1334 (v1-v2); Q1859
(v3.3+); Q2029 (v5.0+); Q3398 (v5.31+).
File Structures
Master File
The master file (.HST) has a header followed by an array of
history file information. The history files are ordered so that the
most recent one is at the top.
|
NAME
|
SIZE
(bytes)
|
TYPE
|
DESCRIPTION
|
|
MASTERHEADER
|
|
|
HST header
|
|
HSTFILEHEADER
|
|
|
Header for most recent data file
|
|
.
|
|
|
.
|
|
.
|
|
|
.
|
|
.
|
|
|
.
|
|
HSTFILEHEADER
|
|
|
Header for oldest data file
|
NOTE: You have to read the whole master file to determine the
sequence of history files.
Data File
Each numbered data file has a header followed by recorded
samples in order from oldest to newest.
|
NAME
|
SIZE
(bytes)
|
TYPE
|
DESCRIPTION
|
|
DATAFILEHEADER
|
|
|
File header
|
|
Samples
|
|
|
Data samples
|
Structure
Definitions
MASTERHEADER
|
NAME
|
SIZE
(bytes)
|
TYPE
|
DESCRIPTION
|
|
Title
|
128
|
CHAR
|
Title of the file (ASCII). It contains information, such as file
version, type, start time and logging name
|
|
ID
|
8
|
CHAR
|
ID for Citect files. It is set to "CITECT"
|
|
Type
|
2
|
UINT
|
Type of the Citect file. 0= FILE_TYPE_TREND.
|
|
Version
|
2
|
UINT
|
Version number of the trends. (5=TwoByteV600,
6=EightByteV600)
|
|
Alignment
|
4
|
|
alignment for 16 bytes
|
|
Mode
|
4
|
UINT
|
Indicates the mode of the MASTER file. (For future use.
Currently it is set to 0.)
|
|
History
|
2
|
UINT
|
Maximum Number of history files to be created. (not including
AddOn)
|
|
nFiles
|
2
|
UINT
|
Number of history files currently created. (not including
AddOn)
|
|
Next
|
2
|
UINT
|
Next history file number according to the order of the following
headers (starting with 0)
|
|
AddOn
|
2
|
UINT
|
Shows the number of history files added onto the system through
TrnAddHistory() function
|
|
Alignment
|
20
|
|
alignment for 16 bytes
|
HSTFILEHEADER
|
NAME
|
2-BYTE SIZE
(bytes)
|
8-BYTE SIZE
(bytes)
|
TYPE
|
DESCRIPTION
|
|
Name
|
144
|
272
|
CHAR
|
History file name
|
|
HEADER
|
|
|
|
Binary file header
|
DATAFILEHEADER
|
NAME
|
SIZE
(bytes)
|
TYPE
|
DESCRIPTION
|
|
Title
|
112
|
CHAR
|
ASCII title of the file. It contains information such as file
version, type, start time and logging name
|
|
SCALES
|
|
|
Raw and engineering scales
|
|
HEADER
|
|
|
Binary file header
|
HEADER
|
NAME
|
2-BYTE SIZE
(bytes)
|
8-BYTE SIZE
(bytes)
|
TYPE
|
DESCRIPTION
|
|
ID
|
8
|
8
|
CHAR
|
ID for Citect files. It is set to "CITECT"
|
|
Type
|
2
|
2
|
UINT
|
Type of the Citect file. 0=FILE_TYPE_TREND
|
|
Version
|
2
|
2
|
UINT
|
Version number of the trends. (5=TwoByteV600,
6=EightByteV600)
|
|
StartEvNo
|
4
|
8
|
INT
|
Starting Number for events in this history file (integer). Used
for event trends only.
|
|
Alignment
|
0
|
12
|
|
For 16 bytes
|
|
LogName
|
80
|
80
|
CHAR
|
Name of the trend tag that owns the history file.
|
|
Mode
|
4
|
4
|
UINT
|
Indicates the mode of the history file. (For future use.
Currently it is set to 0)
|
|
Area
|
2
|
2
|
UINT
|
The security area to which the trend belongs
|
|
Priv
|
2
|
2
|
UINT
|
The privilege level required to view the trend
|
|
FileType
|
2
|
2
|
UINT
|
History File Type. 0=Periodic or Periodic-Event trends, 4=Event
Trends
|
|
SamplePeriod
|
4
|
4
|
UINT
|
Sample period of logging (in milliseconds)
|
|
sEngUnits
|
8
|
8
|
CHAR
|
Engineering units of data (string taken from trend tag
definition)
|
|
Format
|
4
|
4
|
UINT
|
Display format (integer taken from trend tag definition). See
Q3484, Format Field section
|
|
StartTime
|
4
|
8
|
UINT
|
Time of the first periodic or periodic-event sample, or earliest
possible time for event trend samples in this file
|
|
EndTime
|
4
|
8
|
UINT
|
Latest possible sample time for periodic or periodic-event
trends. Or, time of the newest sample for event trends. Value is
StartTime – 1 if there are no samples in the file
|
|
DataLength
|
4
|
4
|
UINT
|
Number of samples the file can hold = (file size –
DATAFILEHEADER size) / bytes-per-sample
|
|
FilePointer
|
4
|
4
|
UINT
|
The location of the newest sample in the file (integer number of
samples from the start of the data portion of the file). Only used
for periodic trends
|
|
EndEvNo
|
4
|
8
|
INT
|
The next event sample number to be used (integer). Only used for
event trends
|
|
Alignment
|
2
|
6
|
|
for 16 bytes
|
Note: 2-byte trend times use Citect time format (number of
seconds since 1/1/1970). 8-byte trend times use 64-bit time format
(number of 100 nanosecond time units since 1/1/1601).
SCALES
|
NAME
|
SIZE
(bytes)
|
TYPE
|
DESCRIPTION
|
|
RawZero
|
4
|
FLOAT
|
Minimum raw value
|
|
RawFull
|
4
|
FLOAT
|
Maximum raw value
|
|
EngZero
|
4
|
FLOAT
|
Minimum engineering (scaled) value
|
|
EngFull
|
4
|
FLOAT
|
Maximum engineering (scaled) value
|
Samples
Samples will be in one of the following formats:
Periodic or Periodic-Event trends
2-byte: 2-bytes (signed integer) per sample. Samples are in
generic units (see Q1201).
Invalid
sample value = -32001
Gated sample value
= -32002
8-byte: 8-bytes (floating point) per sample. Samples are in
engineering units.
Invalid
sample value = 4294949819 (stored as an unsigned 64-bit
integer)
Gated sample value
= 4294945450 (stored as an unsigned 64-bit integer)
Event trends
2-byte Event trends: SCALEDEVENTSAMPLE structure per
sample
8-byte Event Trends: FLOATEVENTSAMPLE structure per sample
SCALEDEVENTSAMPLE
|
NAME
|
SIZE
(bytes)
|
TYPE
|
DESCRIPTION
|
|
Value
|
4
|
INT
|
The value of the sample in generic units (see Q1201)
|
|
Time
|
4
|
UINT
|
The time of the sample
|
|
Milliseconds
|
4
|
UINT
|
The milliseconds of the time of the sample
|
Note: 2-byte trend times use Citect time format (number of seconds
since 1/1/1970).
FLOATEVENTSAMPLE
|
NAME
|
SIZE
(bytes)
|
TYPE
|
DESCRIPTION
|
|
Value
|
8
|
FLOAT
|
The value of the sample in engineering units
|
|
Time
|
8
|
UINT
|
The time of the sample
|
Note: 8-byte trend times use 64-bit time format (number of 100
nanosecond time units since 1/1/1601).
|
