GetHistory

Description: Get History from a File written by Save or SaveHistory. This threaded function retrieves an array of data from a .DAT file for a certain time span. If the parameters to GetHistory are valid and an attempt is made to get the data, the return value is 0, otherwise, if no attempt is made to get the data, the return value is 1.

Returns: Numeric (see discussion of the first parameter)

Usage: Script

Format: GetHistory(Array, File, StartTime, EndTime [, Error, PathPrefix])

Parameters: Array { numeric } { required } { no default }

A variable that will be set to an array upon completion of the data retrieval. The format of the array is [column][record]; column 0 is the timestamp in seconds since January 1, 1970. Each subsequent column is the data for that record. Array is not set if there is no data for the requested period.

File { text } { required } { no default }

Any text expression giving the file name for the historical data file. The file extension should not be added to the name since the default of ".DAT" is automatically added. If the file name is prefixed with a period, the path will be to the directory in which the module is contained.

StartTime { Timestamp } { required } { no default }

Any numeric expression giving the start time of the period for which data is requested in seconds since January 1, 1970.

EndTime { Timestamp } { required } { no default }

Any numeric expression giving the end time of the period for which data is requested in seconds since January 1, 1970.

Error { numeric } { optional } { no default }

An optional variable that will always be set to a valid value upon completion of the GetHistory. Its meaning is as follows:

Error	Error Description
0	No error
1	Parameter values out of described range
2	File could not be opened
3	Corrupted .DAT file
4	Field requested could not be found

If Error is not required, but PathPrefix is, then Error should be given as an Invalid value.

PathPrefix { text } { optional } { no default }

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

Comments: This function is threaded - that is to say, it starts its own thread and VTS will continue executing. When it is finished executing, it will set the data in Array. Note that Array will not be initially invalidated upon execution of this statement, so if Array already contained data when the GetHistory was executed, that data will remain untouched until all of the data requested by GetHistory has been amassed, at which time Array will be set to its new value.

Since Array could conceivably remain invalid indefinitely (i.e. there was no data in the requested time span), Error will always be set to a valid value to indicate completion of execution.

There is a return value for this function that indicates if any of its parameters are invalid. The function will immediately return a value of false (0) unless a parameter was invalid, in which case it will return true (1). Note that the return value only signals completion of the function's execution if it is true, otherwise the function will continue executing in its thread.

If PathPrefix is specified, then this changes the interpretation of the File parameter. In this case, the referenced file is not the source of the data, but a file containing references to other files which are the data sources. This file should be in standard VTS log file format and should contain a file reference as the first text value of each record (other values are ignored). The records should be in the correct time order with respect to the data files. The value of the PathPrefix is a string, which when prefixed to one of the file references, will yield a full pathname to the target file. If no prefix is required, but expansion of the dataset is required, then PathPrefix should be an empty string.

• If a filename entry does NOT begin with a "\" or "<drive letter>:\", then the PathPrefix will be prepended to the filename.

• If a filename entry DOES begin with "<drive letter>:\", then the PathPrefix will NOT be prepended to the filename.

• If a filename entry does begin with a "\", then the "<drive letter>:" from the PathPrefix will be prepended to the filename. If there is no "<drive letter>:" in the PathPrefix then the "<drive letter>:" from the path of the File parameter will be used instead.

PathPrefix would normally be Invalid or the application path.