(VTScada-Layer function. Must be called with a leading backslash.)
| Description: | This launched module returns an array of logged data. GetTagHistory should be considered for use in new code. |
| Returns: | An array, stored in the first parameter (see comments) |
Usage:  |
Script Only. |
| Function Groups: | File I/O, Log |
| Related to: | GetTagHistory |
| Format: |
\GetLog(&Result, Tag, Name, Start, End, TPP, Size, Mode, Obsolete [, StaleTime] [, TimeZoneBias] [, EnableDownTimeOverride]) |
| Parameters: |
| Result | ||||||||||||||||||||||||||||||
| Required. A pointer to the array retrieved from file. The array may be multidimensional as described in the Comments section. Please review the information carefully. | ||||||||||||||||||||||||||||||
| Tag | ||||||||||||||||||||||||||||||
| Required. The object value of the tag from which to get the logged data. | ||||||||||||||||||||||||||||||
| Name | ||||||||||||||||||||||||||||||
| Required. The name of the logged value in the tag. If Invalid or a valid empty string, a timestamp is used. It is possible to retrieve more than one field in a single GetLog statement. To do this, pass an array of values in as the Name parameter. Typically "Value" for most tag values, or "Value!" for tag attribute data. (Value! was introduced with VTScada version 12 and is not available in legacy data. It cannot be retrieved by SQL queries.) |
||||||||||||||||||||||||||||||
| Start | ||||||||||||||||||||||||||||||
| Required. The start time in seconds since January 1, 1970. | ||||||||||||||||||||||||||||||
| End | ||||||||||||||||||||||||||||||
| Required. The end time in seconds since January 1, 1970. If invalid, Size limits the number of tags retrieved. | ||||||||||||||||||||||||||||||
| TPP | ||||||||||||||||||||||||||||||
| Required. The time span per tag. If Invalid, Size limits the number of tags retrieved. | ||||||||||||||||||||||||||||||
| Size | ||||||||||||||||||||||||||||||
| Required. The maximum number of tags to get. If greater than 0, data is accessed one at a time from file, rather than at equal time intervals. If TPP is valid, Size is ignored. | ||||||||||||||||||||||||||||||
| Mode | ||||||||||||||||||||||||||||||
| Required. Indicates the mode of data collection. Note: The mode is useful only when the TPP parameter is valid and greater than 0. Mode may be one of: It is possible to retrieve more than one mode in a single GetLog statement. To do this, pass an array of values in as the Mode parameter.
Mode 11: This is for hardware that can count to a limited number, then rolls over to start a fresh count. For example, a tag that counts equipment starts, but which can only count from 0 to 15 before wrapping around to start again. This gives a value of sixteen per roll-over since there must be one more start after fifteen to have the roll-over occur. A graph of a very simple case where there is a start every second would look like the following:
(Each rollover must be followed by a fresh start, not a gradually declining value. If there are a series of declining values then, because each is less than the previous, each counts as another rollover.) The formula used is (RolloverCount * RolloverValue) + (LastValidValue - FirstValidValue). Where, for any given time interval:
Given this example, suppose that you want a count of starts in each thirty-second interval. In the first interval there is no previous valid value, one wrap-around and a last valid value of 12. (1*16) + (12 - 0) = 28. This is an idealized case. Consider a more realistic case where not all values are logged. (This may be due to factors such as polling intervals, deadbands, hardware, etc.) The following graph shows the same data where the orange dots represent values obtained and logged and the gray line represents what really happened:
In the first 30 seconds there is one roll-over when the value drops from 13 to 2. The first value is 0 and the last is 11. The Historian will return 27: (1*16) + (11-0) = 27. The Historian will return 30 for the period from 30 to 60. The first valid value (carried from the previous period) is 11. The last valid value is 9 and there are two roll-overs. (2*16) + (9-11) = 30. Modes 12 and 13: These are intended to provide a summary of the bit-wise Historian value attributes within a query. (Value attributes were added in VTScada version 11.5 / 12.0) With mode 12, the first value is OR'd with zero, and each successive value in the time period is OR'd with result of the last comparison. From the result you will know whether any particular attribute bit was set on any values within the period. With mode 13, the first value is AND'd with a value having all bits set to 1 and each successive value is AND'd with the result of the last comparison. From the result you will know whether any particular attribute bit was set on all values within the period. |
| Obsolete n/a |
| No longer used - maintained for backward compatibility. |
| StaleTime |
| The meaning of StaleTime depends on the selected Mode. For all Modes but 11, StaleTime sets the maximum time to propagate an old value. For Mode 11, this is the maximum value of a range. (See comments in the Mode parameter.) It is possible to specify more than one stale time in a single GetLog statement. To do this, pass an array of values in as the StaleTime parameter. |
| TimeZoneBias |
| Used with time zone aware reports. If included, it should be the number of seconds that your time zone differs from UTC, specified in time stamps. This is the value that would be returned from TimeZone(0). |
| EnableDownTimeOverride |
| TRUE to return Invalid for down time. Defaults to the Historian's EnableDownTime value. |
| Comments: |
When the value of the Result parameter becomes valid, all of the data has been retrieved. If Name is an array with more than one element, then GetLog will retrieve multiple fields from the tag. In this case, Result will be a two-dimensional array. 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 Name 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 Name. If an array of values is specified, the first element in the array will be applied to the first element of Name, and so on. Version 12 of VTScada introduced value attributes. These can be queried using "Value!" rather than "Value" for the field name or array of field names. Value! stores bitwise values according the following table. Attributes flagged with a star (*) apply only if the I/O tag is attached to a DNP3 driver or a custom driver supporting this feature. Refer to the constant, #NUM_DATA_ATTR_BITS, to discover the number of bits in data attributes for your version of VTScada.
|
This module executes in parallel to the launching code. Watch for the return array to be filled with valid data to determine when it has finished.
Example:
If 1 Loop;
[
{ Setup the TimeZone Bias }
TZBias = \IsTimeZoneAware ? TimeZone(0) : Invalid;
{ Set up the fieldnames, modes & staletime arrays for Getlog }
FieldNames = New(5);
FieldNames[0] = Invalid { Timestamps };
FieldNames[1] = "Quality";
FieldNames[2] = "SuccessCount";
FieldNames[3] = "ErrorValue";
FieldNames[4] = "ErrorAddress";
Modes = New(5);
Modes[0] =
Modes[1] =
Modes[2] =
Modes[3] =
Modes[4] = Invalid;
{ Retrieve Data for the first tag }
\GetLog(&TagData,
Scope(Code, Tags[TagIndex]) { Point object value },
FieldNames { Read data },
Start { Start time },
End { End time },
Invalid { Time per point },
#NUMRECLIMIT { No max number of recs },
Modes { Modes },
Invalid { Obsolete },
Invalid { Stale Time },
TZBias { TimeZone Bias });
