SaveHistory

Deprecated. Do not use in new code.

(Engine-Level Function)

Description:	This threaded function saves an array of data to a .DAT file for a certain time span.
Returns:	Nothing
Usage:	Script Only.
Function Groups:	Array, File I/O, Log
Threaded:	Yes
Related to:	SaveHistory \| HistorianDeleteRecords \| HistorianGetData \| HistorianGetInfo \| HistorianReadRecords \| HistorianWriteRecords \| Get \| GetHistory \| GetLogInfo \| Save \| TGet
Format:	SaveHistory(Array2DElem, Num, File, [Mode], [PathPrefix], [EndTIme])
Parameters:

Array2DElem

Required. Any array element giving the starting point into the two dimensional array containing the data to write to the file. The subscripts for the array may be any numeric expression, but both must be specified. The format of the array is the same as that returned by GetHistory: [column][record].

Column 0 is the timestamp in seconds since January 1, 1970, while each subsequent column is the data for that record in the same order used by the Save function that created the .DAT file.

Extra columns are ignored, but if there are fewer columns than required to specify all fields in the .DAT file then the function fails and does nothing.

Num

Required. Any numeric expression giving the number of records to write to the file.

File

Required. Any text expression giving the file name for the historical data file. If this file does not exist the SaveHistory function will create it with default format (see Comments). The file extension is optional and will default to ".DAT" if omitted.

Mode

Historical data files use an invalid record to mark discontinuities in the recorded data. Under certain circumstances, it may be desirable to manipulate these records. This optional parameter provides the mechanism to do so. The mode parameter has the following options: (Defaults to 0)

Value	Meaning
0	Add data after the previous record according to time stamp, and don’t write an invalid record (default).
1	No longer used
2	Add data according to time stamp. If previous record is invalid, overwrite it, write data, and then write an invalid record after it.
3	Perform a tidy closedown of a file which has been written with Mode = 2.
4	Specifies that SaveHistory should perform a special merge of the supplied data into the referenced data file.

The aim of the special merge is remove invalid records unless the existing and the incoming data both agree that they should exist in the file. The aim of this mode is to assist the resolution of data at primary and backup log servers.

PathPrefix

An optional text expression parameter that enables and controls the retrieval of data from across a set of files.

EndTime

Specifies the end time range for a special merge (Mode = 4). EndTime is optional but may only be specified when Mode = 4.

If omitted or if a value of zero is used, then EndTime defaults to the last time stamp in the records supplied in Array2DElem.

Comments:

Each record of data in the array will be inserted into its correct position based on its timestamp. For this reason the transfer to the file will be more efficient if the timestamps are in increasing chronological order, however, any order is allowed. Any records that have an invalid timestamp will be skipped. Because this function is threaded and runs as a background job, there is no way to tell when the data has all been written to the file other than by checking its contents, however, multiple Save or SaveHistory commands will get written to the file in correct locations based on their timestamps. If a Get or TGet statement is executed, the SaveHistory statement will write all of its data to the file prior to the data retrieval. This also occurs if the application is stopped.
If the target file does not exist, SaveHistory will create it. To do this, SaveHistory needs to determine the column structure of the file. Whereas Save has parameters allowing the format to be explicitly defined, there are no equivalent parameters to SaveHistory. Instead, SaveHistory will analyze the first record that is to be written and determine the parameter type required for each column. In order to ensure that the correct format is determined, it is advisable to make the first record a template record. A template record would have an invalid timestamp followed by column values that unambiguously identify the range of values for each column (see the Save function for a description of the data types). In the case of text values, the template string should be the same length as the maximum required length.

If Mode has the value 2, then the understanding is that a series of SaveHistory functions are to be performed on the file and that each will be written at the end of the file (if the write is not at end of file, then Mode = 0 is forced). The invalid record that is written at the end of the file identifies that the file is still (conceptually) open. Should the system suffer any form of abrupt shutdown, then this status will be preserved in the file and will be of use in learning the validity of file data. The final SaveHistory to such a file should be written with Mode = 3. This will change the invalid record to one which signifies that the file is no longer open.

If Mode has the value 4, then SaveHistory compares the data supplied in Array2dElem with the data already existing in the file, for the time range specified by the earliest record in the data and the value of EndTime.
The comparison reviews the validity of each record (a record is deemed invalid if all columns are invalid) and splits both sets of data into periods of validity and invalidity. The resulting file will contain all valid records from both data sets and those invalid records where both data sets saw an invalid.