The TrnAddHistory() function is designed to allow you to keep a reasonable amount of current trend history on your trend server, while maintaining offline archives of past data. These archives may be kept on a file server, backup system, recordable CD, or other location. Then, at any time you may call the TrnAddHistory() function to temporarily attach one of these old trend data files to the trend system. This allows you to scroll back into history on your trend page and see the data from the old file seamlessly connected to the latest data from that trend tag. The Trend Archive feature automates this process (see KB Article Q2030). This is not the same as backing up and restoring trends (see the heading "Backing Up and Restoring", below).

Since TrnAddHistory() is only attaching an extra data file to the trend tag, it does not overwrite any existing data. This means that TrnAddHistory() will fail and return error 374 (Date/Time Conflict) if you try to attach a file that has data from the same period of time as the current data files.

Knowing the number of files, time, and period defined in the trend tag, you can calculate the range of dates covered by the current set of data files. For example:

This trend tag will have a total of 3 months of data. If today is December 3^rd, the latest file will cover December 1-31, the previous file will cover November 1-30, and the oldest will contain October 1-31. This means you could only use TrnAddHistory() to add a file(s) from September and previous months.

In some cases the data files may not be consecutive. For example, if Citect was shut down for the entire month of November, the data files would cover September, October, and December. So, you could only add files from before September. You can use the Citect Trend Reader utility from the MyCitect Downloads Toolbox area of www.citect.com to see the start and end date/time of your individual data files or the entire list of data files recorded in the HST (index) file for each trend tag. The following is a more technical explanation of how to understand these files in relation to TrnAddHistory().

Trend History & Data Files

Each trend tag consists of three parts:

The HST file acts as an index for the trend. This allows Citect to quickly find the correct data file without having to open each one to see if it contains the requested data. Here is the information contained in a sample HST file for a 2-byte trend with 2 files and a 24-hour period, as displayed by the Citect Trend Reader utility:

Master Header
Title CITECT<CR><LF>VERSION 2<CR><LF>TREND MASTER<CR><LF>CPU<CR><LF>Fri Jan 13 14:42:07 2006<LF><CR><LF><SUB>
ID CITECT
File Type 0 [Trend file]
Version 5 [2-byte v6.00+]
Mode 0
Max Files 2
# Files 2
Next 0
Add On 0

File Header 0
Name C:\Citect\Data\cpu.000
ID CITECT
File Type 0 [Trend file]
Version 5 [2-byte v6.00+]
Start Event # 1
Log Name CPU
Mode 0
Area 0
Privilege 0
History Type 0 [Periodic Trend]
Sample Period 2000 [2 sec]
Eng Units %
Format 261 [###.#]
Start Time 1137110400 [01/13/2006 00:00:00 GMT]
End Time 1137196798 [01/13/2006 23:59:58 GMT]
Data Length 43200
File Pointer 35520
End Event # -2

File Header 1
Name C:\Citect\Data\cpu.001
ID CITECT
File Type 0 [Trend file]
Version 5 [2-byte v6.00+]
Start Event # -2
Log Name CPU
Mode 0
Area 0
Privilege 0
History Type 0 [Periodic Trend]
Sample Period 2000 [2 sec]
Eng Units %
Format 261 [###.#]
Start Time 1137024000 [01/12/2006 00:00:00 GMT]
End Time 1137110398 [01/12/2006 23:59:58 GMT]
Data Length 43200
File Pointer 0
End Event # -2

The Max Files value shows the maximum number of data files, as defined in the trend tag. The # Files value shows how many of those data files have been created (see KB Article Q3469). Once all the history files have been created and filled with data, Citect will roll over and begin overwriting the data files, starting with the oldest one.

When you call TrnAddHistory() and pass the name of the old data file you want to add, Citect reads the header information from the data file, which looks like this:

2-Byte Data Header
Title CITECT<LF><CR>VERSION 2<LF><CR>TREND HISTORY<LF><CR>CPU2<LF><CR> Tue Jan 10 19:00:00 2006 2003<LF><LF><CR><SUB>
Raw Zero 0.
Raw Full 100.
Eng Zero 0.
Eng Full 100.
ID CITECT
File Type 0 [Trend file]
Version 5 [2-byte v6.00+]
Start Event # 1
Log Name CPU2
Mode 0
Area 0
Privilege 0
History Type 0 [Periodic Trend]
Sample Period 500 [0.5 sec]
Eng Units %
Format 261 [###.#]
Start Time 1136937600 [01/11/2006 00:00:00 GMT]
End Time 1137023998 [01/11/2006 23:59:58 GMT]
Data Length 172800
File Pointer 142079
End Event # -2

Citect reads the Log Name to find out which trend tag this file belongs to. It then looks through the HST file for that trend tag to make sure the Start Time and End Time do not conflict with any existing file for that trend tag (including current and add-on files). If that condition is met, another file header is added to the HST file, and the Add On count in the HST is increased by 1. The HST file now looks like this:

Master Header
Title CITECT<CR><LF>VERSION 2<CR><LF>TREND MASTER<CR><LF>CPU<CR><LF>Fri Jan 13 14:42:07 2006<LF><CR><LF><SUB>
ID CITECT
File Type 0 [Trend file]
Version 5 [2-byte v6.00+]
Mode 0
Max Files 2
# Files 2
Next 0
Add On 1

2-Byte File Header 0
.
.
.

2-Byte File Header 1
.
.
.

2-Byte File Header 2
Name F:\Archive\cpu.000
ID CITECT
File Type 0 [Trend file]
Version 5 [2-byte v6.00+]
Start Event # -2
Log Name CPU
Mode 0
Area 0
Privilege 0
History Type 0 [Periodic Trend]
Sample Period 2000 [2 sec]
Eng Units %
Format 261 [###.#]
Start Time 1136937600 [01/11/2006 00:00:00 GMT]
End Time 1137023998 [01/11/2006 23:59:58 GMT]
Data Length 43200
File Pointer 37003
End Event # -2

When the trend rolls over again Citect will not overwrite this data file, even though it is the oldest file in the list. This file is considered to be an add-on, and is not part of the normal history file rotation.

The header for the add-on file will stay in the HST file until it is removed by calling the TrnDeleteHistory() function.

Backing Up and Restoring

TrnAddHistory() does not remove the need for backing up and restoring the entire set of trend data files. If the trend data or HST files get corrupted (e.g. by a hard drive crash) and there is no redundant trend server with good data, it will be necessary to completely restore a backup of the trend data files. Since TrnAddHistory() will not overwrite the current files, you will have to shut down the trend server(s) and manually restore a complete set of trend data and HST files.

If you back up the data and HST files together, you will be able to either attach individual data files with TrnAddHistory() or restore the entire set in case of emergency. See KB Article Q3723 for details about backing up and restoring trends. If you need to restore trends but the backup does not contain the HST files, you will need to download the Trend HST Rebuilder utility from the MyCitect Downloads Toolbox on www.citect.com