dohertj2/wwtools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: Wonderware / System Platform tools and reference

Browse Source 
Five tools under one repo, all docs organized per DOCS-GUIDE.md:

- aalogcli: .NET 4.8 / x86 CliFx CLI for reading System Platform binary
  logs (*.aaLGX) for LLM debugging, built on aaOpenSource/aaLog. Commands:
  last, tail, range, unread, fields. Stable JSON envelope under --llm-json.
  Build template under lib/build/ for rebuilding aaLogReader.dll.

- aot: ArchestrA Object Toolkit 2014 v4.0 reference material. Dev guide
  (Markdown converted from CHM), API reference for the ArchestrA.Toolkit
  namespace, and the Monitor / Watchdog VS sample solutions.

- graccesscli: .NET 4.8 / x86 CliFx CLI that automates Galaxy
  configuration via the ArchestrA GRAccess COM interop. Includes session
  daemon, IPC protocol, and llm-json envelope contract.

- grdb: SQL/DDL exploration of the Galaxy Repository database. DDL
  captures, reusable queries, hierarchy / contained-name <-> tag-name
  translation notes.

- histdb: LLM-oriented reference for AVEVA Historian retrieval. INSQL
  linked-server, extension tables, every wwXxx time-domain extension,
  every retrieval mode, alarm/event SQL recipes, REST API. Distilled
  from the 243-page Historian Retrieval Guide.

Root contains:
- CLAUDE.md: thin index pointing into each tool's README.
- DOCS-GUIDE.md: doctrine for organizing docs for LLM consumption.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Joseph Doherty
2026-05-03 18:22:20 -04:00
commit 32f26272ae
411 changed files with 69973 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
histdb/03-retrieval-modes.md
+183
View File
@@ -0,0 +1,183 @@
# Retrieval modes (`wwRetrievalMode`)
Every history query has a retrieval mode. The default is **`Cyclic`** for analog tables (and analog/state summary tables) and **`Delta`** for `History`, discrete, and string tables. Set explicitly with `AND wwRetrievalMode = '<Mode>'` (case-insensitive).
## At-a-glance picker
| Want… | Use |
| --- | --- |
| Evenly spaced points across a window, fast | `Cyclic` |
| Smooth curves (analog) over a window | `Interpolated` |
| Only the *changes* — no duplicates | `Delta` |
| Every stored point, including duplicates | `Full` |
| A compromise: cyclic perf + delta accuracy | `BestFit` |
| Time-weighted average per cycle | `Average` |
| Min / max value per cycle | `Minimum` / `Maximum` |
| Area under the curve per cycle | `Integral` |
| Slope (units / time) per cycle | `Slope` |
| Throughput / accumulator (handles wraps + resets) | `Counter` |
| "How long was the tag in state X" | `ValueState` |
| "How long between consecutive entries into state X" | `RoundTrip` |
| Forecast points using simple linear regression | `Predictive` (a `wwFilter` mode, not a `wwRetrievalMode`) |
| Retrieve bracketing values just outside the window | `BoundingValue` |
## Mode catalog
Each section below covers: how the mode picks rows, which `wwXxx` options apply to it, the typical query shape, and the gotchas.
### `Cyclic` — evenly spaced cycle boundaries
- One row per cycle boundary (last value at or before the boundary).
- Number of cycles set by `wwCycleCount` *or* `wwResolution`. Default 100 cycles when neither is set.
- Fast and cheap. May *miss* spikes/gaps that fall between boundaries — for that use `BestFit`.
- Default mode for analog and analog-summary tables.
- Applies to all tag types.
- Options: `wwCycleCount`, `wwResolution`, `wwVersion`, `wwTimeStampRule`, `wwQualityRule`.
```sql
SELECT DateTime, TagName, Value
FROM History
WHERE TagName = 'ReactLevel'
AND DateTime >= '2001-03-13 13:15:00'
AND DateTime <= '2001-03-13 14:15:00'
AND wwRetrievalMode = 'Cyclic'
AND wwCycleCount = 60;
```
NULLs and initial values are returned as-is — no special handling.
### `Delta` — changes only
- Returns only physically stored points where the value (or quality) actually changed.
- If no point sits exactly on the start time, the **last value before the start** is returned with timestamp shifted to the start time and `Quality = 133` (initial-value flag).
- A NULL after a non-NULL is always returned; consecutive NULLs are suppressed.
- Default for `History`, discrete, and string tables.
- Applies to all tag types.
- Options: `wwTimeDeadband`, `wwValueDeadband`, `wwVersion`, `wwQualityRule`.
```sql
SELECT TagName, DateTime, Value, QualityDetail
FROM History
WHERE TagName = 'A001'
AND DateTime >= '2009-09-12 00:20'
AND DateTime <= '2009-09-12 00:40'
AND wwRetrievalMode = 'Delta';
```
`>=` on the start time pulls the initial value; `>` skips it. Same logic for `<` / `<=` on the end.
### `Full` — every stored point
- Returns all stored rows including duplicates.
- Best fidelity to what was actually written by the I/O server.
- Heavy — long windows × many tags = giant rowsets.
- Initial-value handling matches `Delta`.
- Applies to all tag types.
- Options: `wwVersion`, `wwQualityRule`.
### `Interpolated` — `Cyclic`, but with interpolation between actual points
- Cycle boundaries identical to `Cyclic`. At each boundary, the value is **linearly interpolated** between the surrounding stored points (or stair-stepped, if that's the tag's configured interpolation type).
- Per-tag interpolation comes from the `InterpolationType` column on the `AnalogTag` table, with system parameters `InterpolationTypeInteger` / `InterpolationTypeReal` filling in defaults. **`AND wwInterpolationType = 'Linear'`** in the query overrides everything for that query.
- A NULL preceding a cycle boundary causes a NULL at the boundary (no interpolation across NULLs).
- Useful for trend smoothness and for mixing slow + fast tags.
- Only meaningful for analog tags — others fall back to stair-step (effectively `Cyclic`).
- Options: `wwCycleCount`, `wwResolution`, `wwVersion`, `wwInterpolationType`, `wwTimeStampRule`, `wwQualityRule`.
### `BestFit` — five points per cycle, picked from real data
For each cycle returns up to **five** points: first, last, min (with its real timestamp), max (with its real timestamp), and the first non-Good-quality "exception." A point that fills two roles (e.g. last == max) is returned once. Cycles with no data return nothing. Initial and final values at the query boundaries are interpolated.
Combines cyclic-style cost with delta-style fidelity. **One week of 5-second data is ~120,960 rows in `Delta`, ~300 rows in `BestFit`.** Use it for long-window trends.
- Only applied to analog and analog-summary tags. Other tags get plain `Delta`.
- Options: `wwCycleCount`, `wwResolution`, `wwVersion`, `wwInterpolationType`, `wwQualityRule`.
- Quality detail of points returned from a cycle that contains a gap or an incomplete final cycle gets the `4096` "partial cycle" bit OR'd into `QualityDetail`.
### `Average` — time-weighted average per cycle
- One row per tag per cycle.
- For tags with **linear interpolation**, midpoints between stored points are weighted by elapsed time.
- For tags with **stair-step interpolation**, the earlier of two values carries the full interval.
- Differs from SQL `AVG()`, which is unweighted; the Historian's time-weighted average is generally more accurate for sparse data.
- Gaps (NULL ranges) are excluded from the calculation; the output column `TimeGood` reports total good time per cycle.
- Initial / final values: with `wwTimeStampRule='END'` the initial value is the average over the cycle leading up to the query start; with `START`, the final value covers the cycle after the query end.
- Only applies to analog and analog-summary tags.
- Options: `wwCycleCount`, `wwResolution`, `wwVersion`, `wwInterpolationType`, `wwTimeStampRule`, `wwQualityRule`.
### `Minimum` / `Maximum` — per-cycle extremes
- Returns the minimum (or maximum) **stored** point inside each cycle, at its real timestamp.
- Cycles with no data return nothing. Cycles containing a NULL return NULL.
- If multiple points tie, the earliest is returned.
- `QualityDetail` of returned cycle-extreme points has the `4096` "partial cycle" bit set when the cycle is incomplete.
- Only applied to analog tags; others fall back to `Delta`.
- Options: `wwCycleCount`, `wwResolution`, `wwVersion`, `wwTimeStampRule`, `wwQualityRule`.
### `Integral` — area under the curve
- Per-cycle integral of the tag value × time. Useful for things like "how many gallons" given a flow-rate tag.
- The integration uses linear or stair-step depending on the tag's configured / overridden interpolation type.
- Only applied to analog tags.
- Options: `wwCycleCount`, `wwResolution`, `wwVersion`, `wwInterpolationType`, `wwTimeStampRule`, `wwQualityRule`.
### `Slope` — units per time per cycle
- Per-cycle slope (rate of change). Linear regression across the cycle's points.
- Only analog tags.
- Options: `wwCycleCount`, `wwResolution`, `wwVersion`, `wwTimeStampRule`, `wwQualityRule`.
### `Counter` — accumulators with wrap and reset support
- For tags that monotonically increase but periodically reset (totalizers, throughput counters, manual resets).
- Returns the accumulated count per cycle, accounting for resets and configurable deadbands so brief drops aren't read as resets.
- Supports manually-reset counters and counter deadbands.
- Options: `wwCycleCount`, `wwResolution`, `wwVersion`, `wwTimeStampRule`, `wwQualityRule`.
### `ValueState` — time-in-state
- Calculates how long the tag spent in each value-state during each cycle.
- The aggregation type comes from `wwStateCalc`: `Minimum`, `Maximum`, `Average`, `Total`, `Percent` (and `*Contained` variants).
- If you specify a single value in the query (`AND Value = 'Open'`), one row per cycle. If you don't, one row per (state, cycle) — table-friendly but trend-unfriendly.
- Works for integer, discrete, string, and state-summary tags. Other types return nothing.
- NULLs are themselves a state.
- Options: `wwCycleCount`, `wwResolution`, `wwVersion`, `wwStateCalc`, `wwTimeStampRule`, `wwQualityRule`.
### `RoundTrip` — time between consecutive entries to a state
- Like `ValueState` but measures the **time between successive leading edges** of the same state — useful for cycle-time analysis ("how long between successive 'Start' events").
- `wwStateCalc` accepts `MinContained`, `MaxContained`, `AvgContained`, `TotalContained`, `PercentContained`.
- Options: `wwCycleCount`, `wwResolution`, `wwVersion`, `wwStateCalc`, `wwTimeStampRule`, `wwQualityRule`, `wwEdgeDetection`.
- Edge detection is configured via `wwEdgeDetection` (`Leading`, `Trailing`, `Both`) — see [`04-retrieval-options.md`](04-retrieval-options.md#wwedgedetection).
### `Predictive` — simple linear regression forecast
- Available from Historian 2014 R2 P01 onward.
- Implemented as a `wwFilter` mode rather than a distinct `wwRetrievalMode`. Future Historian releases are expected to add other prediction algorithms.
- Set `AND wwFilter = '<predictive expression>'` against an analog tag.
### `BoundingValue` — bracket the window
- Available from Historian 17.3.100 onward.
- Returns the **two stored points immediately surrounding the query window**, in addition to whatever falls inside it.
- Use when a chart renderer or trend client needs a value to anchor the line at the query edges without interpolation.
## Mixing modes per query
You can't. One `wwRetrievalMode` per query. To compare modes, run them as separate queries and `UNION ALL`.
## Initial-value semantics, in one place
| Mode | Initial value |
| --- | --- |
| `Cyclic`, `Full`, `Delta` | Last value before the start, timestamped at the query start. `Quality=133` if shifted; if no prior value exists, NULL with `Quality=1`, `QualityDetail=65536`. |
| `Interpolated`, `BestFit` | Linearly interpolated between the surrounding points at the start time. |
| `Average`, `Min`, `Max`, `Integral`, `Slope` | Calculated over the cycle adjacent to the boundary defined by `wwTimeStampRule`. |
| `Counter`, `ValueState`, `RoundTrip` | Result of applying the algorithm to the cycle preceding the query start. |
`>=` on the start pulls an initial value; `>` does not. Same for `<=` / `<` on the end.
## Next
- [`04-retrieval-options.md`](04-retrieval-options.md) — `wwCycleCount`, `wwResolution`, `wwInterpolationType`, deadbands, quality, value selector, and more.
- [`05-query-recipes.md`](05-query-recipes.md) — worked examples that combine modes and options.