Deprecated. Do not use in new code.
(Engine-Level Function)
| Description: | Reads an array of historical data from a file (written by Save or SaveHistory) and returns the relative file position of the file entry following the last one read, or an error code. |
| Returns: | Array or Error code |
Usage:  |
Script Only. |
| Function Groups: | File I/O, Log |
| Related to: | | HistorianDeleteRecords | HistorianGetData | HistorianGetInfo | HistorianReadRecords | HistorianWriteRecords | GetHistory | GetLogInfo | Save | SaveHistory | TGet |
| Format: |
Get(ArrayElem, N, File, FieldNum, StartDate, StartTime, TPP, Mode [, StaleTime, PathPrefix]) |
| Parameters: |
| ArrayElem | ||||||||
| Required. Any array element giving the starting point in the array in which data read from the file will be stored. The subscript for the array may be any numeric expression. If processing a multidimensional array, the usual rules apply to decide which dimension should be used. |
||||||||
| N | ||||||||
| Required. Any numeric expression giving the number of array entries to use. If this value is greater than the dimension of the array, then the array dimension is used for N. If N extends past the upper bound of the lowest array dimension, this computation will "wrap-around" and resume at element 0, until N elements have been processed. |
||||||||
| File | ||||||||
| Required. 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 that the module is contained in. |
||||||||
| FieldNum | ||||||||
| Required. Any numeric expression giving the field number to be read from the file. The value number for the actual data starts at 0 and corresponds to the columns specified in Save or SaveHistory. It is also possible to retrieve time data associated with each record by setting this parameter to a negative value. Time options are:
It is possible to retrieve more than one field in a single Get statement. To do this, pass an array of values in as the FieldNum parameter |
| StartDate | ||||||||||||||||||||||||||
| Required. Any numeric expression for the date (expressed as the number of days since January 1, 1970) to search for in the file as the starting date for the data. If less than 0, this indicates the relative file position to read rather than the date. A -1 indicates the last entry in the file, a -2 the second last, and so on. If more points are requested than exist, Invalid values will be retrieved. For example, if this parameter is -20, and there are only 5 data points, the resultant array will contain 15 Invalid values followed by 5 valid values. Note: If the Save was used with a non-negative Buffers parameter, the last entry in the file will be an Invalid value - the last valid entry will be indicated by -2, the second last by -3 and so on. |
||||||||||||||||||||||||||
| StartTime | ||||||||||||||||||||||||||
| Required. Any numeric expression giving the time of day (in number of seconds since midnight) on StartDate to search for in the file as the starting time for the data. This may be greater than one day. It may also be negative, where data will start the previous day at (86400 - StartTime) seconds after midnight. If StartDate is less than 0, StartTime is ignored. |
||||||||||||||||||||||||||
| TPP | ||||||||||||||||||||||||||
| Required. Any numeric expression giving the time span in seconds for each array entry. Each array element will contain the data that corresponds exactly to this time period, which corresponds to 0 or more data points in the file. If TPP is positive and FieldNum selects a text value, the first entry which falls in a time is read and Mode is ignored. If TPP is equal to 0, the data is read from the file and placed in the array on a one-to-one basis. If TPP is less than 0, the data is read on a one-to-one basis from the StartDate and StartTime for (negative) TPP seconds - TPP places an upper limit on the time span to read. In both of these cases the Mode parameter is ignored. |
||||||||||||||||||||||||||
| Mode | ||||||||||||||||||||||||||
Required. Any numeric expression giving the method of handling the data. If TPP is greater than 0, the values that fall in each time span will be represented as follows:
In the case of modes 5 and 6, FieldNum should still be set to indicate the field number on which the mode is to act. The return values will be times indicating the minimum or maximum in that field for each time span. In the case of mode 10, the result interpolates between values. This is primarily intended for the case where there are several TPPs per recorded value, as the time-weighted average returns a stepped curve in this case. The interpolate mode returns a smoother curve. If FieldNum is less than 0 (i.e. a time/date value is being requested), the modes listed above are still valid, although not particularly practical. A time/date will be retrieved for every time span containing a data point, even if that point is Invalid, as in the case of a Save statement whose Buffers parameter is 0 (causing an Invalid value to be written). If TPP is less than or equal to 0, Mode is ignored. If the data is text, the first entry in a given time range is used for the array entry, and Mode is ignored. |
| StaleTime |
| An optional parameter that sets a maximum validity duration for data elements that are being TPP processed. Normally, every data point is treated as remaining valid until the next data point. If a valid StaleTime parameter is given, then any data point will be treated as invalid StaleTime seconds after the recorded time. If TPP is less than or equal to 0, StaleTime is ignored. If StaleTime is not required, but PathPrefix is, then StaleTime should be given as either an Invalid value, or a constant zero. If Mode is 11, then StaleTime is the accumulator rollover value. It is possible to specify more than one stale time in a single Get statement. To do this, pass an array of values in as the StaleTime parameter. |
| PathPrefix |
| An optional text expression parameter that enables and controls the retrieval of data from across a set of files. |
| Comments: | This function will return either the relative file position of the file entry following the last entry read, or an error code. If the return value is negative, it is the file position. If it is 0, the end of the file was reached before all the data was read. If the return value is positive, one of the following errors occurred.
If StartDate is given a negative value, indicating that a particular entry is to be retrieved, it must be stressed that the file being read by the Get may or may not contain an Invalid record at the end of the file. If the Save that created the file was given a negative number for its Buffers parameter, the Invalid record would not have been written to the file, however, a zero or positive value for Buffers will mean that the last record of the file will be one whose fields are all Invalid and whose time and date stamp reflect the cessation of writing to the file by the Save. If FieldNum is an array with more than one element, then Get will retrieve multiple fields from the file. In this case, ArrayElem must represent an array with at least two dimensions. The requested values will be returned in a manner analogous to GetHistory. That is, with the data for a column in the rightmost dimension, and the column index in the previous dimension. When FieldNum is specified as an array, Mode or StaleTime, or both, may be specified as either a single value or an array of values. If a single value is specified, that value will be used for each of the fields specified in FieldNum. If an array of values is specified, the first element in the array will be applied to the first element of FieldNum, and so on. 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 that are data sources. This file should be in standard VTScada LogFile 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.
PathPrefix would normally be Invalid or the application path. If a Get is executed while a Save is still active, the save buffer will immediately be flushed to disk. That is to say, data in the buffer that may have been otherwise overlooked by this particular Get will be written to disk so that the current data set is available to the Get in its entirety. Care must be exercised when using the result from a Get function in further Get functions. This is the normal use for the return value, however, if a Save statement updates the file between Get functions, the return value will be shifted by one from its original file position. The solution to this problem is to either ensure that the Save statement is not executed by disabling the Trigger, or to keep the successive Get functions in a single script. |
Example:
If ! Valid(Exists);
[
Exists = FileFind("G:\Mixer\Trend.DAT"
{ Path and files to search },
0 { Normal file attributes },
2 { Return full path and name });
]
If Valid(exists[0]) && exists[0] == "G:\Mixer\Trend.DAT";
[
Get(Trend[0] { Destination array },
100 { Get 100 array elements from file },
"G:\Mixer\Trend" { path and file name },
0 { Read first 'column' from file },
Today() { Starting today },
Seconds() - 3600 { Starting 1 hour ago },
18 { Each element represents 18 seconds },
0 { Time weighted avg over 18 secs });
]
This tests to make sure that the file exists, and then reads a half hour of data from a file, starting 1 hour (3600 seconds) ago. Note that just after midnight, the expression Seconds( ) - 3600 may be negative. The Get statement interprets this as before midnight on the previous day (which is correct). X is set to the record following the last record read from the file. Note also that a full path name may be specified, including network drives. Also note that it is irrelevant when data were logged to the file. The Save statement trigger could have been a regular timer (such as AbsTime), or an event (such as Change as applied to a variable).
If ! Valid(FilePos);
[
FilePos = Get(array1[10]{ Start at element 10 },
25 { Read 25 array elements },
"trips" { File trips.dat (in current dir) },
1 { Read time stamp, not data },
25 { Read 25 items before EOF },
0 { Start time is ignored },
0 { Read on a point-by-point basis },
0 { Mode is ignored });
]
This reads the time stamps of the 25 most recently logged entries into elements 10 through 34 of array1. FilePos is set to the item past the last item read (in this case, the oldest record).
