retrieval XML element

The retrieval element represents a retrieval type, that is, a set of retrieval options for a certain type of tag.

You can have multiple retrieval elements in a duration range. However, you should order them from the most specific to the least specific one. This is because the Trend application uses the first suitable retrieval type that it finds, that is, the first retrieval type with a matching tag type and available history source.

For example, assume that you have three retrieval types defined in the following order:

• Analog tags, Summary data

• Analog tags, History data

• All tags, History data

For an analog tag, the Trend application first tries to retrieve summary data according to the first retrieval type. If no summary data is available, it retrieves history data according to the second retrieval type. Now assume the retrieval types are ordered like this:

• Analog tags, History data

• Analog tags, Summary data

• All tags, History data

In this case, the Trend application never tries to retrieve summary data for an analog tag; it never considers the second retrieval type because it has already found a suitable retrieval type in the first one.

You should always define a retrieval type with a tag type of "All" and a history source of "History." This serves as a "catch-all" for tags that aren’t covered by any other retrieval style.

The retrieval element has seven required attributes:

• tagType: Specifies the tag type for which the retrieval type should be used. Valid values are All, Analog, Discrete, and String.

• source: Specifies the history source from which to retrieve data. Valid values are History to retrieve data from history tables and Summary to retrieve data from summary tables. When using Summary, you must specify the summary frequency in the resolution attribute.

• retrievalMode: Specifies which retrieval mode to use. Valid values are Cyclic, Delta, Full, Interpolated, BestFit, Average, Min, Max, Integral, Slope, Counter,ValueState, and RoundTrip. Make sure that you specify a retrieval mode that is supported for the specified tag type. For example, Counter retrieval does not work with string tags. Therefore, if you try to retrieve data for a string tag in Counter mode, the Historian does not return any data.

  For information on each mode, see Understanding Retrieval Modes.

• stateCalc: Specifies which state calculation to use in ValueState and RoundTrip retrieval. Valid values are Min, Max, Average, Total, and Percent. For more information, see State Calculation (wwStateCalc). If you are not using ValueState retrieval, specify an asterisk (*).

• resolution: Specifies the retrieval resolution in milliseconds when retrieving history data in cycle-based retrieval modes, or the summary frequency in seconds when retrieving summary data. For more information, see Resolution (Values Spaced Every X ms) (wwResolution)

  Alternatively, you can set this attribute to 0 and specify a retrieval resolution using the pixels attribute.

• pixels: Specifies the retrieval resolution for cycle-based retrieval modes as the number of pixels per cycle. The number of cycles is the width of the trend chart divided by the value of this attribute. For example, if the chart is 500 pixels wide and the pixels attribute is set to 5, then 100 cycles are used.

  Alternatively, you can set this attribute to 0 and specify a retrieval resolution using the resolution attribute. If you specify non-zero values for both the pixels and the resolution attributes, resolution takes precedence.

• movingAverageValues: Specifies whether to calculate moving averages when retrieving history data. If set to 0, no moving averages are calculated. Otherwise, moving averages are calculated using the number of values specified in this attribute.