Deprecated. Do not use in new code.
(Engine-Level Function)
| Description: | This threaded function reads an array of historical data from a file (written by Save or SaveHistory) and returns an indication of parameter errors. |
| Returns: | Numeric |
Usage:  |
Script Only. |
| Function Groups: | Log, File I/O |
| Threaded: | Yes |
| Related to: | TGet | HistorianDeleteRecords | HistorianGetData | HistorianGetInfo | HistorianReadRecords | HistorianWriteRecords | Get | GetHistory | GetLogInfo | Save | SaveHistory |
| Format: |
TGet(Array, N, File, FieldNum, StartDate, StartTime, TPP, Mode [, ErrorCode, StaleTime, PathPrefix]) |
| Parameters: |
| Array | ||||||||
| Required. A variable which will be set to an array upon completion of the data retrieval. | ||||||||
| N | ||||||||
| Required. Any numeric expression giving the number of array entries to create. | ||||||||
| 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 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 TGet statement. To do this, pass an array of values in as the FieldNum parameter. |
| StartDate | ||||||||||||||||||||||||
| Required. Any numeric expression giving the date to search for in the file as the starting date for the data. This date is expressed as the number of days since January 1, 1970. If StartDate is less than zero, it 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. It is important to note that in cases where Save has been used with a non-negative Buffers parameter, the last entry in the file will be invalid (a fact that is useful in data logging). In cases such as this, the first valid entry will be indicated by -2, the second by -3 and so on. |
||||||||||||||||||||||||
| StartTime | ||||||||||||||||||||||||
| Required. Any numeric expression giving the time of day on StartDate to search for in the file as the starting time for the data. This time is expressed as the number of seconds since midnight on StartDate. It is legal for StartTime to be greater than one day. It is legal for StartTime to be negative, where data will start the previous day at (86400 - StartTime) seconds after midnight. If StartDate is less than zero, 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 which correspond 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 maximum or minimum in that field for each time span. 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. It is possible to retrieve more than one mode in a single TGet statement. To do this, pass an array of values in as the Mode parameter. |
| ErrorCode | ||||||||||||
An optional parameter that is any variable which will be set to a valid value upon completion of the TGet. Its meaning is as follows:
If ErrorCode is not required but either StaleTime or PathPrefix is, then ErrorCode should be given as an Invalid value. |
| 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. It is possible to specify more than one stale time in a single TGet 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. No default. |
| Comments: | This function is similar to Get except that it runs in its own thread - it is typically used when a large amount of data is being read. When the TGet is executed in its script, it starts its own thread and VTScada 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. This means that if Array already contained data when the TGet was executed, that data will remain untouched until all of the data requested by TGet has been amassed, at which time Array will be set to its new value. 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 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 TGet 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 TGet 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, 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 which are the 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. 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 the application path. |
Example:
Init [
If 1 Main;
[
TGet(trend { Destination array },
100 { Get 100 array elements fr file },
"G:\mix\mixtrend" { path and file name },
0 { Read first 'column' from file },
Today() { Starting today },
Seconds() - 3600 { Starting 1 hour ago },
18 { Each element covers 18 secs },
0 { Time weighted average });
]
]
Main [
If Valid(trend) DoneReading;
ZText(10, 20, "Reading Data", 10, 0);
]
This reads a half hour of data from a file, starting one hour ago. Note that just after midnight, the expression Seconds( ) - 3600 may be negative; the TGet 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(level, 1)).
