HistorianGetData

Optional 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:

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:

• Rollovers are counted when a new value is smaller than the last valid value.
• The RolloverValue is passed to the function in the parameter StaleTime.
• LastValidValue starts with the last valid value in the previous time interval (if any), and is updated with each new valid value within the time interval.
• FirstValidValue starts with the last valid value in the previous time interval (if any), and is updated with only the first valid value found in the current time span.

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.

In the case of modes 5 and 6, FieldName should still be set to indicate the field 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 GetTagHistory statement. To do this, pass an array of values in as the Mode parameter.

A value in which the error code (if any) will be returned.

Defined error codes are provided in the reference chapter. See: Historian Error Codes