refactor(historian): extract Driver.Historian.Sql.Common from the SQL Server backend (no behaviour change) (1a)
Moves the database-independent logic of the SQL Server historian backend into a new shared library for the upcoming QuestDB backend (#666): status codes and bits, value/column mapping, StoredSample + quality clamp, the AtTime and aggregate evaluators, BucketPlan, LiveWritePreparer and HistoryUpdatePlanner (both with a resolutionTicks parameter, default 1), tag-name rules, the bootstrap failure cache, health counters, alarm event ids, the event continuation and severity clamp. The SQL Server backend now calls it; its T-SQL, TVP builders, connection, bootstrapper and catalog stay. Tests: StatusCodeOracleTests, ValueWriterPrepareTests, the column half of SampleRowMapperTests and ProcessedReadTests.Every_enum_member_is_either_served_or_refused move to the new Sql.Common.Tests under the same names. SqlServer integration tests get mechanical renames only. Test-name set across the three projects is identical to the baseline (160 tests). Claude-Session: https://claude.ai/code/session_01Ef2ozxS7QPanGT8uoATbTe
This commit is contained in:
Joseph Doherty
@@ -0,0 +1,78 @@
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Sql.Common;
|
||||
|
||||
/// <summary>
|
||||
/// Maps one bucket's statistics (<see cref="BucketRow"/>) to the OPC UA value and status of an aggregate.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// Per interval: no samples ⇒ <c>BadNoData</c>. PercentGood / PercentBad ⇒ <c>100 × good|bad / all</c> over
|
||||
/// every sample, status Good. Otherwise no usable sample ⇒ <c>BadNoData</c>; a numeric aggregate with a usable
|
||||
/// String/DateTime sample ⇒ <c>BadAggregateInvalidInputs</c>; else the value, Good when every sample is Good,
|
||||
/// <c>UncertainDataSubNormal</c> when any is Bad or Uncertain. Every status — including <c>BadNoData</c> —
|
||||
/// carries the Calculated info bits. Timestamps are the bucket start, except Minimum/MaximumActualTime
|
||||
/// (the sample's time; ties ⇒ earliest).
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// Values: Count is <see cref="int"/>; Start/End keep the sample's type; every other aggregate is
|
||||
/// <see cref="double"/> computed over the numeric value (Boolean = 0/1). These are the simple per-sample
|
||||
/// definitions, not Part 13's interval-boundary (interpolated bound / time-weighted) semantics.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public static class AggregateEvaluator
|
||||
{
|
||||
/// <summary>Evaluates <paramref name="aggregate"/> over one non-empty bucket.</summary>
|
||||
/// <param name="aggregate">Requested aggregate.</param>
|
||||
/// <param name="r">The bucket's statistics.</param>
|
||||
/// <param name="bucketStart">The bucket's start time (the result timestamp).</param>
|
||||
/// <param name="now">Server timestamp.</param>
|
||||
/// <returns>The calculated value.</returns>
|
||||
/// <exception cref="HistoryAggregateNotSupportedException">The aggregate is not one of the thirteen served.</exception>
|
||||
public static DataValueSnapshot Evaluate(HistoryAggregateType aggregate, BucketRow r, DateTime bucketStart, DateTime now)
|
||||
{
|
||||
DataValueSnapshot Calc(object? value, uint status, DateTime? t = null) =>
|
||||
new(value, HistorianInfoBits.WithCalculated(status), t ?? bucketStart, now);
|
||||
|
||||
if (r.Total == 0) return NoData(bucketStart, now);
|
||||
switch (aggregate)
|
||||
{
|
||||
case HistoryAggregateType.PercentGood: return Calc(100d * r.Good / r.Total, HistorianStatusCodes.Good);
|
||||
case HistoryAggregateType.PercentBad: return Calc(100d * r.Bad / r.Total, HistorianStatusCodes.Good);
|
||||
}
|
||||
if (r.Usable == 0) return NoData(bucketStart, now);
|
||||
|
||||
var anyText = aggregate is HistoryAggregateType.Count or HistoryAggregateType.Start or HistoryAggregateType.End;
|
||||
if (!anyText && r.NonNumeric > 0)
|
||||
return Calc(null, HistorianStatusCodes.BadAggregateInvalidInputs);
|
||||
|
||||
var status = r.Good == r.Total ? HistorianStatusCodes.Good : HistorianStatusCodes.UncertainDataSubNormal;
|
||||
switch (aggregate)
|
||||
{
|
||||
case HistoryAggregateType.Count: return Calc(r.Usable, status);
|
||||
case HistoryAggregateType.Average: return Calc(r.Avg, status);
|
||||
case HistoryAggregateType.Minimum: return Calc(r.Min, status);
|
||||
case HistoryAggregateType.Maximum: return Calc(r.Max, status);
|
||||
case HistoryAggregateType.Total: return Calc(r.Sum, status);
|
||||
case HistoryAggregateType.Range: return Calc(r.Max - r.Min, status);
|
||||
case HistoryAggregateType.Start: return Calc(r.First.ToObject(), status);
|
||||
case HistoryAggregateType.End: return Calc(r.Last.ToObject(), status);
|
||||
case HistoryAggregateType.Delta:
|
||||
return r.First.TryGetDouble(out var a) && r.Last.TryGetDouble(out var b)
|
||||
? Calc(b - a, status)
|
||||
: Calc(null, HistorianStatusCodes.BadAggregateInvalidInputs);
|
||||
case HistoryAggregateType.MinimumActualTime:
|
||||
case HistoryAggregateType.MaximumActualTime:
|
||||
return Calc(r.Extreme, status, r.ExtremeTime);
|
||||
default:
|
||||
throw new HistoryAggregateNotSupportedException(aggregate);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>The result for a bucket with no samples (or no usable sample): <c>BadNoData</c> + Calculated.</summary>
|
||||
/// <param name="t">The bucket's start time.</param>
|
||||
/// <param name="now">Server timestamp.</param>
|
||||
/// <returns>The no-data value.</returns>
|
||||
public static DataValueSnapshot NoData(DateTime t, DateTime now) =>
|
||||
new(null, HistorianInfoBits.WithCalculated(HistorianStatusCodes.BadNoData), t, now);
|
||||
}
|
||||
@@ -0,0 +1,33 @@
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Sql.Common;
|
||||
|
||||
/// <summary>The query shape that serves an aggregate. One query per family.</summary>
|
||||
public enum AggregateFamily
|
||||
{
|
||||
/// <summary>Average / Minimum / Maximum / Total / Count / Range / PercentGood / PercentBad: one GROUP BY.</summary>
|
||||
Simple,
|
||||
|
||||
/// <summary>Start / End / Delta: first + last usable sample per bucket.</summary>
|
||||
StartEnd,
|
||||
|
||||
/// <summary>MinimumActualTime / MaximumActualTime: extreme usable sample per bucket, ties ⇒ earliest.</summary>
|
||||
ActualTime,
|
||||
}
|
||||
|
||||
/// <summary>Which aggregates the SQL historian backends serve, and by which family.</summary>
|
||||
public static class AggregateFamilies
|
||||
{
|
||||
/// <summary>The family that serves <paramref name="aggregate"/>, or null when the backends do not.</summary>
|
||||
/// <param name="aggregate">Requested aggregate.</param>
|
||||
/// <returns>The family, or null for an unsupported aggregate.</returns>
|
||||
public static AggregateFamily? FamilyOf(HistoryAggregateType aggregate) => aggregate switch
|
||||
{
|
||||
HistoryAggregateType.Average or HistoryAggregateType.Minimum or HistoryAggregateType.Maximum
|
||||
or HistoryAggregateType.Total or HistoryAggregateType.Count or HistoryAggregateType.Range
|
||||
or HistoryAggregateType.PercentGood or HistoryAggregateType.PercentBad => AggregateFamily.Simple,
|
||||
HistoryAggregateType.Start or HistoryAggregateType.End or HistoryAggregateType.Delta => AggregateFamily.StartEnd,
|
||||
HistoryAggregateType.MinimumActualTime or HistoryAggregateType.MaximumActualTime => AggregateFamily.ActualTime,
|
||||
_ => null,
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,61 @@
|
||||
using System.Security.Cryptography;
|
||||
using System.Text;
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
||||
using ZB.MOM.WW.OtOpcUa.Core.AlarmHistorian;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Sql.Common;
|
||||
|
||||
/// <summary>
|
||||
/// The deterministic alarm-event id and numeric severity the SQL historian backends store, so the store-and-forward
|
||||
/// drain's at-least-once redelivery (and both pair nodes writing the same event) converge on one row.
|
||||
/// </summary>
|
||||
public static class AlarmEventIds
|
||||
{
|
||||
/// <summary>
|
||||
/// Lowercase-hex SHA-256 over length-prefixed UTF-8 fields (little-endian int32 byte length, -1 for null):
|
||||
/// EquipmentPath, AlarmId, EventKind, TimestampUtc.Ticks (decimal), User, Comment, Message. Length-prefixing keeps
|
||||
/// field boundaries unambiguous (<c>"a|b"+"c"</c> ≠ <c>"a"+"b|c"</c>).
|
||||
/// </summary>
|
||||
/// <param name="e">The event.</param>
|
||||
/// <returns>64 hex characters.</returns>
|
||||
public static string ComputeEventId(AlarmHistorianEvent e)
|
||||
{
|
||||
using var ms = new MemoryStream();
|
||||
Field(ms, e.EquipmentPath);
|
||||
Field(ms, e.AlarmId);
|
||||
Field(ms, e.EventKind);
|
||||
Field(ms, e.TimestampUtc.Ticks.ToString(System.Globalization.CultureInfo.InvariantCulture));
|
||||
Field(ms, e.User);
|
||||
Field(ms, e.Comment);
|
||||
Field(ms, e.Message);
|
||||
return Convert.ToHexStringLower(SHA256.HashData(ms.ToArray()));
|
||||
}
|
||||
|
||||
/// <summary>The numeric Part 9 priority stored for a severity (same values the gateway path sends).</summary>
|
||||
/// <param name="s">Alarm severity.</param>
|
||||
/// <returns>200 / 500 / 700 / 900; 500 for anything else.</returns>
|
||||
public static int ToNumericSeverity(AlarmSeverity s) => s switch
|
||||
{
|
||||
AlarmSeverity.Low => 200,
|
||||
AlarmSeverity.Medium => 500,
|
||||
AlarmSeverity.High => 700,
|
||||
AlarmSeverity.Critical => 900,
|
||||
_ => 500,
|
||||
};
|
||||
|
||||
private static void Field(MemoryStream ms, string? value)
|
||||
{
|
||||
Span<byte> len = stackalloc byte[4];
|
||||
if (value is null)
|
||||
{
|
||||
System.Buffers.Binary.BinaryPrimitives.WriteInt32LittleEndian(len, -1);
|
||||
ms.Write(len);
|
||||
return;
|
||||
}
|
||||
|
||||
var bytes = Encoding.UTF8.GetBytes(value);
|
||||
System.Buffers.Binary.BinaryPrimitives.WriteInt32LittleEndian(len, bytes.Length);
|
||||
ms.Write(len);
|
||||
ms.Write(bytes);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,67 @@
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Sql.Common;
|
||||
|
||||
/// <summary>The AtTime rules, applied to one requested time and its stored neighbours.</summary>
|
||||
public static class AtTimeEvaluator
|
||||
{
|
||||
/// <summary>
|
||||
/// Applies the AtTime rules to one requested time <paramref name="t"/> (the result is stamped <c>t</c>):
|
||||
/// <list type="bullet">
|
||||
/// <item><c>prev</c> at exactly <c>t</c> ⇒ the stored value and status, unchanged.</item>
|
||||
/// <item>No <c>prev</c> ⇒ <c>BadNoData</c>, null value.</item>
|
||||
/// <item><c>prev</c> Bad (incl. an <c>Empty</c> outage marker) ⇒ <c>t</c> lies inside an outage: null value
|
||||
/// carrying <c>prev</c>'s Bad status code (info bits stripped) — never better than its source.</item>
|
||||
/// <item><c>prev</c> usable and <c>next</c> Bad ⇒ <c>prev</c>'s value held (stepped, NOT interpolated into the
|
||||
/// outage) with <c>UncertainDataSubNormal</c> + Interpolated bits.</item>
|
||||
/// <item>Double/Int64 with a usable <c>next</c> ⇒ linear interpolation (Int64 rounded to the nearest integer,
|
||||
/// ties away from zero, keeping the type); status <c>Good</c> + Interpolated when both neighbours are Good,
|
||||
/// else <c>UncertainDataSubNormal</c> + Interpolated.</item>
|
||||
/// <item>Boolean/String/DateTime, or no <c>next</c> (after the last sample) ⇒ stepped: <c>prev</c>'s value with
|
||||
/// <c>prev</c>'s status code + Interpolated bits — except that a time later than now that is stepped from the
|
||||
/// last sample is <c>UncertainDataSubNormal</c> + Interpolated.</item>
|
||||
/// </list>
|
||||
/// </summary>
|
||||
/// <param name="t">Requested time.</param>
|
||||
/// <param name="prev">The stored sample at or before <paramref name="t"/>, if any.</param>
|
||||
/// <param name="next">The stored sample after <paramref name="t"/>, if any.</param>
|
||||
/// <param name="serverTime">Server timestamp for the result.</param>
|
||||
/// <param name="now">The current time (for the beyond-now rule).</param>
|
||||
/// <returns>The value at <paramref name="t"/>.</returns>
|
||||
public static DataValueSnapshot Evaluate(DateTime t, StoredSample? prev, StoredSample? next, DateTime serverTime, DateTime now)
|
||||
{
|
||||
if (prev is not { } p)
|
||||
return new DataValueSnapshot(null, HistorianStatusCodes.BadNoData, t, serverTime);
|
||||
if (p.TimeUtc == t)
|
||||
return new DataValueSnapshot(p.Value.ToObject(), p.Status, t, serverTime);
|
||||
|
||||
// Inside an outage: report the outage's own Bad code, never an upgraded Uncertain.
|
||||
if (!p.IsUsable)
|
||||
return new DataValueSnapshot(null, p.Status & StatusBits.CodeBitsMask, t, serverTime);
|
||||
|
||||
// Usable previous, Bad next: hold the previous value up to the outage; do not interpolate into it.
|
||||
if (next is { IsUsable: false })
|
||||
return new DataValueSnapshot(p.Value.ToObject(),
|
||||
HistorianInfoBits.WithInterpolated(HistorianStatusCodes.UncertainDataSubNormal), t, serverTime);
|
||||
|
||||
if (next is { } n && p.Value.Kind is HistorianValueKind.Double or HistorianValueKind.Int64
|
||||
&& n.Value.TryGetDouble(out var nv))
|
||||
{
|
||||
var fraction = (double)(t.Ticks - p.TimeUtc.Ticks) / (n.TimeUtc.Ticks - p.TimeUtc.Ticks);
|
||||
var v = p.Value.Number + (nv - p.Value.Number) * fraction;
|
||||
object value = p.Value.Kind == HistorianValueKind.Int64
|
||||
? (long)Math.Round(v, MidpointRounding.AwayFromZero)
|
||||
: v;
|
||||
var status = p.IsGood && n.IsGood ? HistorianStatusCodes.Good : HistorianStatusCodes.UncertainDataSubNormal;
|
||||
return new DataValueSnapshot(value, HistorianInfoBits.WithInterpolated(status), t, serverTime);
|
||||
}
|
||||
|
||||
// Beyond the last sample AND beyond now: the value is held into the future, so it is not known to be Good.
|
||||
if (next is null && t > now)
|
||||
return new DataValueSnapshot(p.Value.ToObject(),
|
||||
HistorianInfoBits.WithInterpolated(HistorianStatusCodes.UncertainDataSubNormal), t, serverTime);
|
||||
|
||||
// Stepped (non-numeric kind, or after the last sample): hold the previous value and its status.
|
||||
return new DataValueSnapshot(p.Value.ToObject(), HistorianInfoBits.WithInterpolated(p.Status), t, serverTime);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,46 @@
|
||||
using System.Runtime.ExceptionServices;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Sql.Common;
|
||||
|
||||
/// <summary>
|
||||
/// The negative cache a schema bootstrapper keeps for its last failure: within the cache window the failure is
|
||||
/// re-thrown without touching the database, so a missing schema (or an outage) does not serialise every write, read
|
||||
/// and alarm event behind one semaphore and one round-trip each. A failure is NOT latched: after the window the
|
||||
/// caller retries. Not thread-safe; the caller guards it (the bootstrapper's gate).
|
||||
/// </summary>
|
||||
public sealed class BootstrapFailureCache
|
||||
{
|
||||
/// <summary>How long the last bootstrap failure is re-thrown before the database is tried again (5 s).</summary>
|
||||
public static readonly TimeSpan DefaultDuration = TimeSpan.FromSeconds(5);
|
||||
|
||||
private readonly TimeProvider _clock;
|
||||
private readonly TimeSpan _duration;
|
||||
private ExceptionDispatchInfo? _lastFailure;
|
||||
private DateTimeOffset _retryAfter;
|
||||
|
||||
/// <summary>Creates the cache.</summary>
|
||||
/// <param name="clock">Clock for the cache window.</param>
|
||||
/// <param name="duration">How long a recorded failure is re-thrown (normally <see cref="DefaultDuration"/>).</param>
|
||||
public BootstrapFailureCache(TimeProvider clock, TimeSpan duration)
|
||||
{
|
||||
_clock = clock ?? throw new ArgumentNullException(nameof(clock));
|
||||
_duration = duration;
|
||||
}
|
||||
|
||||
/// <summary>Re-throws the last recorded failure (original stack preserved) while its window is open.</summary>
|
||||
public void ThrowIfCached()
|
||||
{
|
||||
if (_lastFailure is { } cached && _clock.GetUtcNow() < _retryAfter) cached.Throw();
|
||||
}
|
||||
|
||||
/// <summary>Records a failure; it is re-thrown by <see cref="ThrowIfCached"/> for the cache window.</summary>
|
||||
/// <param name="ex">The bootstrap failure.</param>
|
||||
public void Record(Exception ex)
|
||||
{
|
||||
_lastFailure = ExceptionDispatchInfo.Capture(ex);
|
||||
_retryAfter = _clock.GetUtcNow() + _duration;
|
||||
}
|
||||
|
||||
/// <summary>Forgets any recorded failure (after a success).</summary>
|
||||
public void Clear() => _lastFailure = null;
|
||||
}
|
||||
@@ -0,0 +1,91 @@
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Sql.Common;
|
||||
|
||||
/// <summary>
|
||||
/// The bucket layout of a processed (aggregate) read. Bucket <c>i</c> = <c>[start + i·interval,
|
||||
/// start + (i+1)·interval)</c> (start-inclusive, end-exclusive to the tick; the last bucket is truncated at
|
||||
/// <c>end</c>). An interval <= 0 ⇒ one interval <c>[start, end)</c>. <c>start == end</c> ⇒ no intervals.
|
||||
/// <c>end < start</c> (reverse) ⇒ the window is swapped, computed forward, and assembled in descending bucket
|
||||
/// order (buckets stay anchored at the earlier time).
|
||||
/// </summary>
|
||||
public sealed class BucketPlan
|
||||
{
|
||||
/// <summary>Spec §9.7: a processed read covering more intervals than this is refused.</summary>
|
||||
public const int MaxBuckets = 100_000;
|
||||
|
||||
private BucketPlan(DateTime startUtc, DateTime endUtc, bool reversed, long intervalTicks, long bucketCount)
|
||||
{
|
||||
StartUtc = startUtc;
|
||||
EndUtc = endUtc;
|
||||
Reversed = reversed;
|
||||
IntervalTicks = intervalTicks;
|
||||
BucketCount = bucketCount;
|
||||
}
|
||||
|
||||
/// <summary>The earlier end of the window (the forward start).</summary>
|
||||
public DateTime StartUtc { get; }
|
||||
|
||||
/// <summary>The later end of the window (the forward, exclusive end).</summary>
|
||||
public DateTime EndUtc { get; }
|
||||
|
||||
/// <summary>True when the request came in reversed (<c>end < start</c>).</summary>
|
||||
public bool Reversed { get; }
|
||||
|
||||
/// <summary>Bucket width in 100 ns ticks (clamped to the window; 0 for an empty window).</summary>
|
||||
public long IntervalTicks { get; }
|
||||
|
||||
/// <summary>Number of buckets (0 for an empty window).</summary>
|
||||
public long BucketCount { get; }
|
||||
|
||||
/// <summary><see cref="StartUtc"/> as 100 ns ticks since the Unix epoch.</summary>
|
||||
public long StartUnixTicks => (StartUtc - DateTime.UnixEpoch).Ticks;
|
||||
|
||||
/// <summary>Plans the buckets of a processed read.</summary>
|
||||
/// <param name="startUtc">Requested start.</param>
|
||||
/// <param name="endUtc">Requested end (earlier than start for a reverse read).</param>
|
||||
/// <param name="interval">Bucket width; <= 0 means one bucket over the whole window.</param>
|
||||
/// <returns>The plan.</returns>
|
||||
/// <exception cref="ArgumentOutOfRangeException">The window holds more than <see cref="MaxBuckets"/> intervals
|
||||
/// (parameter name <c>interval</c>).</exception>
|
||||
public static BucketPlan Create(DateTime startUtc, DateTime endUtc, TimeSpan interval)
|
||||
{
|
||||
var reverse = endUtc < startUtc;
|
||||
var (start, end) = reverse ? (endUtc, startUtc) : (startUtc, endUtc);
|
||||
var windowTicks = end.Ticks - start.Ticks;
|
||||
// Everything stays in 100 ns ticks (≤ ≈3.2e18 across 0001–9999, inside a long) — no ns scaling that could
|
||||
// wrap. An interval wider than the window is one bucket, so clamp it to the window; the ceiling division
|
||||
// is written without "+ interval - 1" so a TimeSpan near MaxValue cannot overflow either.
|
||||
var intervalTicks = interval > TimeSpan.Zero ? Math.Min(interval.Ticks, windowTicks) : windowTicks;
|
||||
long bucketCount = windowTicks == 0 ? 0 : windowTicks / intervalTicks + (windowTicks % intervalTicks == 0 ? 0 : 1);
|
||||
if (bucketCount > MaxBuckets)
|
||||
throw new ArgumentOutOfRangeException(nameof(interval), bucketCount,
|
||||
$"A processed read may cover at most {MaxBuckets} intervals; this window holds {bucketCount}.");
|
||||
return new BucketPlan(start, end, reverse, intervalTicks, bucketCount);
|
||||
}
|
||||
|
||||
/// <summary>The start time of bucket <paramref name="index"/> (UTC kind).</summary>
|
||||
/// <param name="index">Zero-based bucket index.</param>
|
||||
/// <returns>The bucket start.</returns>
|
||||
public DateTime BucketStart(long index) =>
|
||||
DateTime.SpecifyKind(new DateTime(StartUtc.Ticks + index * IntervalTicks), DateTimeKind.Utc);
|
||||
|
||||
/// <summary>One snapshot per bucket in window order; missing buckets get <paramref name="empty"/>; reversed if the window was.</summary>
|
||||
/// <param name="byBucket">Evaluated snapshots of the non-empty buckets, by bucket index.</param>
|
||||
/// <param name="empty">Builds the snapshot of a bucket with no row, from its start time.</param>
|
||||
/// <returns><see cref="BucketCount"/> snapshots.</returns>
|
||||
public IReadOnlyList<DataValueSnapshot> Assemble(IReadOnlyDictionary<long, DataValueSnapshot> byBucket,
|
||||
Func<DateTime, DataValueSnapshot> empty)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(byBucket);
|
||||
ArgumentNullException.ThrowIfNull(empty);
|
||||
var result = new List<DataValueSnapshot>((int)BucketCount);
|
||||
for (long i = 0; i < BucketCount; i++)
|
||||
{
|
||||
var bucketStart = BucketStart(i);
|
||||
result.Add(byBucket.TryGetValue(i, out var v) ? v : empty(bucketStart));
|
||||
}
|
||||
if (Reversed) result.Reverse();
|
||||
return result;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,57 @@
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Sql.Common;
|
||||
|
||||
/// <summary>
|
||||
/// Per-bucket statistics one aggregate query row produces (one non-empty bucket). Every backend's SQL fills the same
|
||||
/// fields; <see cref="AggregateEvaluator"/> turns them into the OPC UA value and status.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// Sample classes: <i>usable</i> = severity Good or Uncertain AND a stored value (an Empty sample is an outage marker
|
||||
/// and counts as Bad whatever its code); <i>good</i> = usable with severity Good; <i>bad</i> = not usable.
|
||||
/// Every value field is computed over usable samples only.
|
||||
/// </remarks>
|
||||
public sealed class BucketRow
|
||||
{
|
||||
/// <summary>Zero-based bucket index within the window.</summary>
|
||||
public long Bucket { get; set; }
|
||||
|
||||
/// <summary>All samples in the bucket.</summary>
|
||||
public int Total { get; set; }
|
||||
|
||||
/// <summary>Usable samples.</summary>
|
||||
public int Usable { get; set; }
|
||||
|
||||
/// <summary>Good samples.</summary>
|
||||
public int Good { get; set; }
|
||||
|
||||
/// <summary>Bad (not usable) samples.</summary>
|
||||
public int Bad { get; set; }
|
||||
|
||||
/// <summary>Usable String / DateTime samples.</summary>
|
||||
public int NonNumeric { get; set; }
|
||||
|
||||
/// <summary>Average of the usable numeric values (null when none).</summary>
|
||||
public double? Avg { get; set; }
|
||||
|
||||
/// <summary>Minimum of the usable numeric values (null when none).</summary>
|
||||
public double? Min { get; set; }
|
||||
|
||||
/// <summary>Maximum of the usable numeric values (null when none).</summary>
|
||||
public double? Max { get; set; }
|
||||
|
||||
/// <summary>Sum of the usable numeric values (null when none).</summary>
|
||||
public double? Sum { get; set; }
|
||||
|
||||
/// <summary>First usable sample's value by time (Empty when none).</summary>
|
||||
public HistorianValue First { get; set; }
|
||||
|
||||
/// <summary>Last usable sample's value by time (Empty when none).</summary>
|
||||
public HistorianValue Last { get; set; }
|
||||
|
||||
/// <summary>Extreme (min or max) usable numeric value (null when none).</summary>
|
||||
public double? Extreme { get; set; }
|
||||
|
||||
/// <summary>Time of <see cref="Extreme"/> (ties ⇒ earliest; null when none).</summary>
|
||||
public DateTime? ExtremeTime { get; set; }
|
||||
}
|
||||
@@ -0,0 +1,11 @@
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Sql.Common;
|
||||
|
||||
/// <summary>The opaque Events continuation point of the SQL historian backends (only its presence is contractual).</summary>
|
||||
public static class EventContinuation
|
||||
{
|
||||
/// <summary>Encodes the first not-returned event as <c>"{EventTimeUtc.Ticks}|{EventId}"</c>.</summary>
|
||||
/// <param name="eventTimeUtc">The event's time.</param>
|
||||
/// <param name="eventId">The event's id.</param>
|
||||
/// <returns>The continuation text (callers send its UTF-8 bytes).</returns>
|
||||
public static string Encode(DateTime eventTimeUtc, string eventId) => $"{eventTimeUtc.Ticks}|{eventId}";
|
||||
}
|
||||
@@ -0,0 +1,27 @@
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Sql.Common;
|
||||
|
||||
/// <summary>
|
||||
/// The one place that maps value kinds to the stored tag data type (a <see cref="DriverDataType"/> byte).
|
||||
/// Used by the value writer and the updater only when they have to create a tag row on a miss; provisioning
|
||||
/// later corrects it.
|
||||
/// </summary>
|
||||
public static class HistorianDataTypes
|
||||
{
|
||||
/// <summary>Data type used when a tag is created from a batch that holds no typed value.</summary>
|
||||
public const DriverDataType DefaultForEmpty = DriverDataType.Float64;
|
||||
|
||||
/// <summary>Maps a value kind to the stored tag data-type byte (Empty ⇒ <see cref="DefaultForEmpty"/>).</summary>
|
||||
/// <param name="kind">Value kind.</param>
|
||||
/// <returns>The <see cref="DriverDataType"/> as a byte.</returns>
|
||||
public static byte FromKind(HistorianValueKind kind) => (byte)(kind switch
|
||||
{
|
||||
HistorianValueKind.Double => DriverDataType.Float64,
|
||||
HistorianValueKind.Int64 => DriverDataType.Int64,
|
||||
HistorianValueKind.Boolean => DriverDataType.Boolean,
|
||||
HistorianValueKind.String => DriverDataType.String,
|
||||
HistorianValueKind.DateTime => DriverDataType.DateTime,
|
||||
_ => DefaultForEmpty,
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,70 @@
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Sql.Common;
|
||||
|
||||
/// <summary>
|
||||
/// The read-side health counters a SQL historian data source reports through
|
||||
/// <see cref="IHistorianDataSource.GetHealthSnapshot"/>. Lock-guarded; safe to call from concurrent reads.
|
||||
/// </summary>
|
||||
public sealed class HistorianHealthCounters
|
||||
{
|
||||
private readonly object _lock = new();
|
||||
private DateTime? _lastSuccessUtc;
|
||||
private DateTime? _lastFailureUtc;
|
||||
private string? _lastError;
|
||||
private long _totalQueries;
|
||||
private long _totalSuccesses;
|
||||
private long _totalFailures;
|
||||
private int _consecutiveFailures;
|
||||
|
||||
/// <summary>Records a successful query.</summary>
|
||||
public void RecordSuccess()
|
||||
{
|
||||
lock (_lock)
|
||||
{
|
||||
_totalQueries++;
|
||||
_totalSuccesses++;
|
||||
_consecutiveFailures = 0;
|
||||
_lastSuccessUtc = DateTime.UtcNow;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>Records a failed query. An <see cref="OperationCanceledException"/> (deadline / client abort) is not a backend fault and is ignored.</summary>
|
||||
/// <param name="ex">The failure.</param>
|
||||
public void RecordFailure(Exception ex)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(ex);
|
||||
if (ex is OperationCanceledException) return;
|
||||
lock (_lock)
|
||||
{
|
||||
_totalQueries++;
|
||||
_totalFailures++;
|
||||
_consecutiveFailures++;
|
||||
_lastFailureUtc = DateTime.UtcNow;
|
||||
_lastError = $"{ex.GetType().Name}: {ex.Message}";
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>The current counters. The connection is reported open when there has been a success and no failure since.</summary>
|
||||
/// <returns>The snapshot.</returns>
|
||||
public HistorianHealthSnapshot Snapshot()
|
||||
{
|
||||
lock (_lock)
|
||||
{
|
||||
var open = _totalSuccesses > 0 && _consecutiveFailures == 0;
|
||||
return new HistorianHealthSnapshot(
|
||||
TotalQueries: _totalQueries,
|
||||
TotalSuccesses: _totalSuccesses,
|
||||
TotalFailures: _totalFailures,
|
||||
ConsecutiveFailures: _consecutiveFailures,
|
||||
LastSuccessTime: _lastSuccessUtc,
|
||||
LastFailureTime: _lastFailureUtc,
|
||||
LastError: _lastError,
|
||||
ProcessConnectionOpen: open,
|
||||
EventConnectionOpen: open,
|
||||
ActiveProcessNode: null,
|
||||
ActiveEventNode: null,
|
||||
Nodes: []);
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,32 @@
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Sql.Common;
|
||||
|
||||
/// <summary>Part 4 §7.39 historian info bits OR-ed onto a status code.</summary>
|
||||
public static class HistorianInfoBits
|
||||
{
|
||||
/// <summary>InfoType = DataValue.</summary>
|
||||
public const uint InfoTypeDataValue = 0x00000400u;
|
||||
|
||||
/// <summary>The value was produced by an aggregate calculation.</summary>
|
||||
public const uint HistorianCalculated = 0x1u;
|
||||
|
||||
/// <summary>The value was interpolated.</summary>
|
||||
public const uint HistorianInterpolated = 0x2u;
|
||||
|
||||
/// <summary>
|
||||
/// Marks <paramref name="status"/> as a Calculated data value. Any historian bits the status already carries
|
||||
/// (e.g. a stored Interpolated sample) are cleared first, so the result is never both.
|
||||
/// </summary>
|
||||
/// <param name="status">Base status code.</param>
|
||||
/// <returns>Status with InfoType and Calculated bits set.</returns>
|
||||
public static uint WithCalculated(uint status) =>
|
||||
(status & ~StatusBits.HistorianBitsMask) | InfoTypeDataValue | HistorianCalculated;
|
||||
|
||||
/// <summary>
|
||||
/// Marks <paramref name="status"/> as an Interpolated data value. Any historian bits the status already
|
||||
/// carries (e.g. a stored Calculated sample) are cleared first, so the result is never both.
|
||||
/// </summary>
|
||||
/// <param name="status">Base status code.</param>
|
||||
/// <returns>Status with InfoType and Interpolated bits set.</returns>
|
||||
public static uint WithInterpolated(uint status) =>
|
||||
(status & ~StatusBits.HistorianBitsMask) | InfoTypeDataValue | HistorianInterpolated;
|
||||
}
|
||||
@@ -0,0 +1,9 @@
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Sql.Common;
|
||||
|
||||
/// <summary>One sample bound for storage.</summary>
|
||||
/// <param name="TimeUtc">Source timestamp (UTC, at the backend's resolution).</param>
|
||||
/// <param name="Value">Typed value.</param>
|
||||
/// <param name="StatusCode">OPC UA status code (stored bit-for-bit).</param>
|
||||
public readonly record struct HistorianSampleRow(DateTime TimeUtc, HistorianValue Value, uint StatusCode);
|
||||
+9
@@ -0,0 +1,9 @@
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Sql.Common;
|
||||
|
||||
/// <summary>Thrown when <c>AutoCreateSchema=false</c> and the historian schema is absent or behind.</summary>
|
||||
public sealed class HistorianSchemaMissingException : Exception
|
||||
{
|
||||
/// <summary>Creates the exception.</summary>
|
||||
/// <param name="message">Message naming the missing version.</param>
|
||||
public HistorianSchemaMissingException(string message) : base(message) { }
|
||||
}
|
||||
@@ -0,0 +1,27 @@
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Sql.Common;
|
||||
|
||||
/// <summary>
|
||||
/// Every OPC UA status the SQL historian backends emit, as named constants (inline literals are invisible to
|
||||
/// <c>StatusCodeParityTests</c>). Values mirror <c>Opc.Ua.StatusCodes</c>.
|
||||
/// </summary>
|
||||
public static class HistorianStatusCodes
|
||||
{
|
||||
public const uint Good = 0x00000000u;
|
||||
public const uint GoodEntryInserted = 0x00A20000u;
|
||||
public const uint GoodEntryReplaced = 0x00A30000u;
|
||||
public const uint BadNoData = 0x809B0000u;
|
||||
public const uint BadEntryExists = 0x809F0000u;
|
||||
public const uint BadNoEntryExists = 0x80A00000u;
|
||||
public const uint BadInvalidTimestamp = 0x80230000u;
|
||||
public const uint BadAggregateInvalidInputs = 0x80D60000u;
|
||||
public const uint UncertainDataSubNormal = 0x40A40000u;
|
||||
|
||||
/// <summary>Stored for a non-finite Double (NaN / ±Infinity) that arrived with a non-Bad status.</summary>
|
||||
public const uint BadOutOfRange = 0x803C0000u;
|
||||
|
||||
/// <summary>
|
||||
/// A HistoryUpdate value that cannot be stored: a Double NaN / ±Infinity, an Empty (null) value with a non-Bad
|
||||
/// status, or a tag name longer than <see cref="HistorianTagNames.MaxLength"/>.
|
||||
/// </summary>
|
||||
public const uint BadInvalidArgument = 0x80AB0000u;
|
||||
}
|
||||
@@ -0,0 +1,17 @@
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Sql.Common;
|
||||
|
||||
/// <summary>
|
||||
/// Historian tag-name rules. <b>Names longer than <see cref="MaxLength"/></b> are never truncated: a sized parameter
|
||||
/// would silently cut them and resolve them onto whatever tag owns the first <see cref="MaxLength"/> characters, so
|
||||
/// they are refused (writes) or answered as not found (reads).
|
||||
/// </summary>
|
||||
public static class HistorianTagNames
|
||||
{
|
||||
/// <summary>Longest storable tag (and event source) name; longer names are refused.</summary>
|
||||
public const int MaxLength = 400;
|
||||
|
||||
/// <summary>True when <paramref name="name"/> is storable without truncation.</summary>
|
||||
/// <param name="name">Historian tag name.</param>
|
||||
/// <returns>Whether the name is non-null and at most <see cref="MaxLength"/> characters.</returns>
|
||||
public static bool IsValid(string? name) => name is not null && name.Length <= MaxLength;
|
||||
}
|
||||
@@ -0,0 +1,10 @@
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Sql.Common;
|
||||
|
||||
/// <summary>Helpers for turning stored event rows into <c>HistoricalEvent</c>s.</summary>
|
||||
public static class HistoricalEventRows
|
||||
{
|
||||
/// <summary>Clamps a stored severity into the <see cref="ushort"/> range the event carries.</summary>
|
||||
/// <param name="severity">Stored severity.</param>
|
||||
/// <returns>The severity clamped to 0..65535.</returns>
|
||||
public static ushort ClampSeverity(int severity) => (ushort)Math.Clamp(severity, 0, ushort.MaxValue);
|
||||
}
|
||||
@@ -0,0 +1,175 @@
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Sql.Common;
|
||||
|
||||
/// <summary>What the backend did with one HistoryUpdate winner row.</summary>
|
||||
public enum UpsertOutcome
|
||||
{
|
||||
/// <summary>The row was absent and was inserted.</summary>
|
||||
Inserted,
|
||||
|
||||
/// <summary>The row existed and was replaced.</summary>
|
||||
Replaced,
|
||||
}
|
||||
|
||||
/// <summary>The database-independent half of one <c>UpdateDataAsync</c> call (see <see cref="HistoryUpdatePlanner.Plan"/>).</summary>
|
||||
public sealed class UpdatePlan
|
||||
{
|
||||
internal UpdatePlan(uint?[] results, IReadOnlyList<(int Index, HistorianSampleRow Row)> winners,
|
||||
long?[] keys, IReadOnlyDictionary<long, int> winnerByTick)
|
||||
{
|
||||
Results = results;
|
||||
Winners = winners;
|
||||
Keys = keys;
|
||||
WinnerByTick = winnerByTick;
|
||||
}
|
||||
|
||||
/// <summary>Pre-decided codes (invalid ts, NaN, superseded duplicate…); null = decided by the backend.</summary>
|
||||
public uint?[] Results { get; }
|
||||
|
||||
/// <summary>Rows to send, de-duplicated per mode, in input order.</summary>
|
||||
public IReadOnlyList<(int Index, HistorianSampleRow Row)> Winners { get; }
|
||||
|
||||
/// <summary>Per input item: its (truncated) timestamp ticks, or null when the timestamp is invalid.</summary>
|
||||
internal long?[] Keys { get; }
|
||||
|
||||
/// <summary>(Truncated) tick → input index of the item actually sent.</summary>
|
||||
internal IReadOnlyDictionary<long, int> WinnerByTick { get; }
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Per-item result rules for OPC UA HistoryUpdate (spec §4 "Updates"): exactly one status per input item, in input
|
||||
/// order.
|
||||
/// <para><b>Duplicate timestamps within one request</b> (compared at the backend's resolution): Insert — the first
|
||||
/// occurrence is applied, later ones are <c>BadEntryExists</c>; Replace/Update — last wins, and every earlier
|
||||
/// occurrence of that timestamp reports the same code as the winning one. DeleteAtTime — the first occurrence
|
||||
/// reports the real outcome, later ones <c>BadNoEntryExists</c>.</para>
|
||||
/// <para><b>Invalid items.</b> A null or <see cref="DateTime.MinValue"/> timestamp is <c>BadInvalidTimestamp</c>.
|
||||
/// A Double NaN/±Infinity is rejected with <c>BadInvalidArgument</c>. An Empty (null) value is only accepted with a
|
||||
/// Bad status (an operator-authored outage marker); with a Good or Uncertain status it is <c>BadInvalidArgument</c>.
|
||||
/// Other items still proceed.</para>
|
||||
/// <para><b>Tag names over <see cref="HistorianTagNames.MaxLength"/> characters</b> are refused, never truncated:
|
||||
/// every item reports <c>BadInvalidArgument</c> and nothing is sent.</para>
|
||||
/// </summary>
|
||||
public static class HistoryUpdatePlanner
|
||||
{
|
||||
/// <summary>The pre-pass: classifies every item and picks the winner row per timestamp.</summary>
|
||||
/// <param name="tag">Historian tag name.</param>
|
||||
/// <param name="mode">Insert, Replace or Update.</param>
|
||||
/// <param name="values">Input items, in request order.</param>
|
||||
/// <param name="resolutionTicks">1 = 100 ns (SQL Server); 10 = timestamps truncated to µs BEFORE de-duplication (QuestDB).</param>
|
||||
/// <returns>The plan.</returns>
|
||||
public static UpdatePlan Plan(string tag, HistoryUpdateMode mode, IReadOnlyList<HistorizationValue> values,
|
||||
long resolutionTicks = 1)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(tag);
|
||||
ArgumentNullException.ThrowIfNull(values);
|
||||
ArgumentOutOfRangeException.ThrowIfLessThan(resolutionTicks, 1);
|
||||
var results = new uint?[values.Count];
|
||||
var winner = new Dictionary<long, int>(); // tick -> index of the item actually sent
|
||||
if (!HistorianTagNames.IsValid(tag))
|
||||
{
|
||||
Array.Fill(results, HistorianStatusCodes.BadInvalidArgument);
|
||||
return new UpdatePlan(results, [], new long?[values.Count], winner);
|
||||
}
|
||||
var times = new DateTime[values.Count];
|
||||
var keys = new long?[values.Count];
|
||||
for (var i = 0; i < values.Count; i++)
|
||||
{
|
||||
var v = values[i];
|
||||
if (v.TimestampUtc is not { } ts || ts == DateTime.MinValue)
|
||||
{
|
||||
results[i] = HistorianStatusCodes.BadInvalidTimestamp;
|
||||
continue;
|
||||
}
|
||||
times[i] = LiveWritePreparer.Truncate(ts, resolutionTicks);
|
||||
keys[i] = times[i].Ticks;
|
||||
if ((v.Value.Kind == HistorianValueKind.Double && !double.IsFinite(v.Value.Number))
|
||||
|| (v.Value.Kind == HistorianValueKind.Empty && !StatusBits.IsBad(v.StatusCode)))
|
||||
{
|
||||
results[i] = HistorianStatusCodes.BadInvalidArgument;
|
||||
continue;
|
||||
}
|
||||
var key = times[i].Ticks;
|
||||
if (!winner.TryGetValue(key, out _))
|
||||
winner[key] = i;
|
||||
else if (mode == HistoryUpdateMode.Insert)
|
||||
results[i] = HistorianStatusCodes.BadEntryExists; // first occurrence stays the winner
|
||||
else
|
||||
winner[key] = i; // last wins
|
||||
}
|
||||
|
||||
var send = winner.Values.OrderBy(i => i)
|
||||
.Select(i => (i, new HistorianSampleRow(times[i], values[i].Value, values[i].StatusCode)))
|
||||
.ToList();
|
||||
return new UpdatePlan(results, send, keys, winner);
|
||||
}
|
||||
|
||||
/// <summary>The post-pass: fills in each winner's code from what the backend wrote, then the superseded duplicates.</summary>
|
||||
/// <param name="plan">The plan from <see cref="Plan"/>.</param>
|
||||
/// <param name="mode">The same mode passed to <see cref="Plan"/>.</param>
|
||||
/// <param name="outcomeByTick">Ticks of each winner that the backend actually wrote → Inserted/Replaced; absent ⇒ not
|
||||
/// written (Insert: the row already existed ⇒ <c>BadEntryExists</c>; Replace: no row ⇒ <c>BadNoEntryExists</c>).</param>
|
||||
/// <returns>One status per input item, in input order.</returns>
|
||||
public static IReadOnlyList<uint> Complete(UpdatePlan plan, HistoryUpdateMode mode,
|
||||
IReadOnlyDictionary<long, UpsertOutcome> outcomeByTick)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(plan);
|
||||
ArgumentNullException.ThrowIfNull(outcomeByTick);
|
||||
var results = (uint?[])plan.Results.Clone();
|
||||
|
||||
// No written row means the absent branch: Insert => matched (exists); Replace => not matched.
|
||||
var absent = mode == HistoryUpdateMode.Replace
|
||||
? HistorianStatusCodes.BadNoEntryExists
|
||||
: HistorianStatusCodes.BadEntryExists;
|
||||
foreach (var (index, row) in plan.Winners)
|
||||
results[index] = outcomeByTick.TryGetValue(row.TimeUtc.Ticks, out var o)
|
||||
? o == UpsertOutcome.Inserted ? HistorianStatusCodes.GoodEntryInserted : HistorianStatusCodes.GoodEntryReplaced
|
||||
: absent;
|
||||
|
||||
var final = new uint[results.Length];
|
||||
for (var i = 0; i < results.Length; i++) final[i] = results[i] ?? 0u;
|
||||
|
||||
// Superseded earlier duplicates (Replace/Update) share the winner's code.
|
||||
if (mode != HistoryUpdateMode.Insert)
|
||||
for (var i = 0; i < results.Length; i++)
|
||||
if (plan.Keys[i] is { } key && results[i] is null
|
||||
&& plan.WinnerByTick.TryGetValue(key, out var w) && w != i)
|
||||
final[i] = final[w];
|
||||
return final;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// DeleteAtTime results: <see cref="DateTime.MinValue"/> ⇒ <c>BadInvalidTimestamp</c>; the first occurrence of a
|
||||
/// deleted time ⇒ <c>Good</c>; everything else (unknown tag, no row, later duplicate) ⇒ <c>BadNoEntryExists</c>.
|
||||
/// </summary>
|
||||
/// <param name="times">Requested times, in request order (already at the backend's resolution).</param>
|
||||
/// <param name="deletedTicks">Ticks of the rows the backend actually deleted.</param>
|
||||
/// <param name="tagKnown">Whether the tag exists.</param>
|
||||
/// <returns>One status per requested time.</returns>
|
||||
public static IReadOnlyList<uint> DeleteAtTimeResults(IReadOnlyList<DateTime> times, ISet<long> deletedTicks, bool tagKnown)
|
||||
{
|
||||
ArgumentNullException.ThrowIfNull(times);
|
||||
ArgumentNullException.ThrowIfNull(deletedTicks);
|
||||
var results = new uint[times.Count];
|
||||
var first = new Dictionary<long, int>();
|
||||
for (var i = 0; i < times.Count; i++)
|
||||
{
|
||||
results[i] = HistorianStatusCodes.BadNoEntryExists;
|
||||
if (times[i] == DateTime.MinValue) results[i] = HistorianStatusCodes.BadInvalidTimestamp;
|
||||
else first.TryAdd(times[i].Ticks, i);
|
||||
}
|
||||
if (!tagKnown) return results;
|
||||
foreach (var (ticks, idx) in first)
|
||||
if (deletedTicks.Contains(ticks))
|
||||
results[idx] = HistorianStatusCodes.Good;
|
||||
return results;
|
||||
}
|
||||
|
||||
/// <summary>DeleteRaw result: unknown tag or nothing deleted ⇒ <c>BadNoData</c>; otherwise <c>Good</c>.</summary>
|
||||
/// <param name="tagKnown">Whether the tag exists.</param>
|
||||
/// <param name="rowsAffected">Rows the backend deleted.</param>
|
||||
/// <returns>The status.</returns>
|
||||
public static uint DeleteRawResult(bool tagKnown, long rowsAffected) =>
|
||||
tagKnown && rowsAffected > 0 ? HistorianStatusCodes.Good : HistorianStatusCodes.BadNoData;
|
||||
}
|
||||
@@ -0,0 +1,54 @@
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Sql.Common;
|
||||
|
||||
/// <summary>
|
||||
/// Normalises a live-value batch for storage. <b>Non-finite doubles.</b> NaN / ±Infinity are stored as
|
||||
/// <see cref="HistorianValueKind.Empty"/> so the sample's presence survives. <b>An Empty sample is always Bad</b>:
|
||||
/// a non-finite Double whose status is not already Bad is stored with <c>BadOutOfRange</c>; any other Empty with a
|
||||
/// non-Bad status is stored with <c>BadNoData</c>; an existing Bad code is kept. <b>Duplicate timestamps</b> within
|
||||
/// a batch collapse to the first (matching insert-if-absent across batches).
|
||||
/// </summary>
|
||||
public static class LiveWritePreparer
|
||||
{
|
||||
/// <summary>
|
||||
/// Normalises a batch: null timestamp ⇒ now, timestamps truncated to <paramref name="resolutionTicks"/>,
|
||||
/// non-finite doubles ⇒ Empty, every Empty forced Bad, and duplicate (truncated) timestamps collapsed to the first.
|
||||
/// </summary>
|
||||
/// <param name="values">Input samples, in append order.</param>
|
||||
/// <param name="utcNow">Clock for null timestamps.</param>
|
||||
/// <param name="resolutionTicks">1 = keep 100 ns (SQL Server); 10 = truncate to µs BEFORE de-duplication (QuestDB).</param>
|
||||
/// <returns>Time-unique rows.</returns>
|
||||
public static List<HistorianSampleRow> Prepare(IReadOnlyList<HistorizationValue> values, Func<DateTime> utcNow,
|
||||
long resolutionTicks = 1)
|
||||
{
|
||||
ArgumentOutOfRangeException.ThrowIfLessThan(resolutionTicks, 1);
|
||||
var seen = new HashSet<long>();
|
||||
var rows = new List<HistorianSampleRow>(values.Count);
|
||||
foreach (var v in values)
|
||||
{
|
||||
var t = v.TimestampUtc ?? utcNow();
|
||||
t = t.Kind == DateTimeKind.Local ? t.ToUniversalTime() : DateTime.SpecifyKind(t, DateTimeKind.Utc);
|
||||
t = Truncate(t, resolutionTicks);
|
||||
if (!seen.Add(t.Ticks)) continue;
|
||||
var value = v.Value;
|
||||
var status = v.StatusCode;
|
||||
if (value.Kind == HistorianValueKind.Double && !double.IsFinite(value.Number))
|
||||
{
|
||||
value = HistorianValue.Empty;
|
||||
if (!StatusBits.IsBad(status)) status = HistorianStatusCodes.BadOutOfRange;
|
||||
}
|
||||
else if (value.Kind == HistorianValueKind.Empty && !StatusBits.IsBad(status))
|
||||
{
|
||||
status = HistorianStatusCodes.BadNoData;
|
||||
}
|
||||
rows.Add(new HistorianSampleRow(t, value, status));
|
||||
}
|
||||
|
||||
return rows;
|
||||
}
|
||||
|
||||
/// <summary>Truncates <paramref name="t"/> down to a multiple of <paramref name="resolutionTicks"/>, keeping its kind.</summary>
|
||||
internal static DateTime Truncate(DateTime t, long resolutionTicks) =>
|
||||
resolutionTicks == 1 ? t : t.AddTicks(-(t.Ticks % resolutionTicks));
|
||||
}
|
||||
@@ -0,0 +1,66 @@
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Sql.Common;
|
||||
|
||||
/// <summary>The (ValueKind, NumValue, IntValue, StrValue) column quad for a value.</summary>
|
||||
/// <param name="ValueKind">The <see cref="HistorianValueKind"/> as a byte.</param>
|
||||
/// <param name="NumValue">Numeric column (null = NULL).</param>
|
||||
/// <param name="IntValue">Integer column (null = NULL).</param>
|
||||
/// <param name="StrValue">String column (null = NULL).</param>
|
||||
public readonly record struct SampleColumns(byte ValueKind, double? NumValue, long? IntValue, string? StrValue);
|
||||
|
||||
/// <summary>
|
||||
/// HistorianValue ⇄ column mapping (spec §4). Mapping: Double → Num; Int64 → Int + Num(double);
|
||||
/// Boolean → Int 0/1 + Num 0/1; String → Str; DateTime → Int (ticks); Empty → all NULL.
|
||||
/// </summary>
|
||||
public static class SampleColumnMapper
|
||||
{
|
||||
/// <summary>Splits a value into its column quad.</summary>
|
||||
/// <param name="v">Typed value.</param>
|
||||
/// <returns>The columns to store.</returns>
|
||||
public static SampleColumns ToColumns(HistorianValue v) => v.Kind switch
|
||||
{
|
||||
HistorianValueKind.Double => new((byte)v.Kind, v.Number, null, null),
|
||||
HistorianValueKind.Int64 => new((byte)v.Kind, v.Number, v.Integer, null),
|
||||
HistorianValueKind.Boolean => new((byte)v.Kind, v.Integer != 0 ? 1d : 0d, v.Integer != 0 ? 1L : 0L, null),
|
||||
HistorianValueKind.String => new((byte)v.Kind, null, null, v.Text ?? ""),
|
||||
HistorianValueKind.DateTime => new((byte)v.Kind, null, v.Integer, null),
|
||||
_ => new((byte)HistorianValueKind.Empty, null, null, null),
|
||||
};
|
||||
|
||||
/// <summary>Rebuilds a value from stored columns.</summary>
|
||||
/// <param name="valueKind">ValueKind column.</param>
|
||||
/// <param name="num">NumValue column (null = NULL).</param>
|
||||
/// <param name="integer">IntValue column (null = NULL).</param>
|
||||
/// <param name="str">StrValue column (null = NULL).</param>
|
||||
/// <returns>The typed value; an unknown kind yields <see cref="HistorianValue.Empty"/>.</returns>
|
||||
public static HistorianValue FromColumns(byte valueKind, double? num, long? integer, string? str) => (HistorianValueKind)valueKind switch
|
||||
{
|
||||
HistorianValueKind.Double => HistorianValue.FromDouble(num ?? 0d),
|
||||
HistorianValueKind.Int64 => HistorianValue.FromInt64(integer ?? 0L),
|
||||
HistorianValueKind.Boolean => HistorianValue.FromBoolean((integer ?? 0L) != 0),
|
||||
HistorianValueKind.String => HistorianValue.FromString(str ?? ""),
|
||||
HistorianValueKind.DateTime => new HistorianValue(HistorianValueKind.DateTime, 0d, integer ?? 0L, null),
|
||||
_ => HistorianValue.Empty,
|
||||
};
|
||||
|
||||
/// <summary>Stores a uint status bit-for-bit in an int column.</summary>
|
||||
/// <param name="status">Status code.</param>
|
||||
/// <returns>Same bits as int.</returns>
|
||||
public static int ToDbStatus(uint status) => unchecked((int)status);
|
||||
|
||||
/// <summary>Reads an int status column back to a uint code.</summary>
|
||||
/// <param name="dbStatus">Column value.</param>
|
||||
/// <returns>Same bits as uint.</returns>
|
||||
public static uint FromDbStatus(int dbStatus) => unchecked((uint)dbStatus);
|
||||
|
||||
/// <summary>Stores a uint status in a 64-bit column (zero-extended, so it is never negative).</summary>
|
||||
/// <param name="status">Status code.</param>
|
||||
/// <returns>The status as a non-negative long.</returns>
|
||||
public static long ToLongStatus(uint status) => status;
|
||||
|
||||
/// <summary>Reads a 64-bit status column back to a uint code (low 32 bits).</summary>
|
||||
/// <param name="dbStatus">Column value.</param>
|
||||
/// <returns>The status code.</returns>
|
||||
public static uint FromLongStatus(long dbStatus) => unchecked((uint)dbStatus);
|
||||
}
|
||||
@@ -0,0 +1,33 @@
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Sql.Common;
|
||||
|
||||
/// <summary>
|
||||
/// Bit masks over a 32-bit OPC UA status code (Part 4 §7.39). These are masks, not emitted codes, so their
|
||||
/// names deliberately avoid the Good/Bad/Uncertain prefix the status-code parity scan keys on.
|
||||
/// </summary>
|
||||
public static class StatusBits
|
||||
{
|
||||
/// <summary>Severity + sub-code (top 16 bits) of a status, i.e. the code without info bits.</summary>
|
||||
public const uint CodeBitsMask = 0xFFFF0000u;
|
||||
|
||||
/// <summary>The two severity bits (Good = 00, Uncertain = 01, Bad = 10).</summary>
|
||||
public const uint SeverityMask = 0xC0000000u;
|
||||
|
||||
/// <summary>The severity bit set on every Bad code.</summary>
|
||||
public const uint SeverityBadBit = 0x80000000u;
|
||||
|
||||
/// <summary>The severity bit set on every Uncertain code (bit 30).</summary>
|
||||
public const uint SeverityUncertainBit = 0x40000000u;
|
||||
|
||||
/// <summary>The two historian info bits (Calculated, Interpolated) in the low bits of the info field.</summary>
|
||||
public const uint HistorianBitsMask = 0x3u;
|
||||
|
||||
/// <summary>True when <paramref name="status"/> has Bad severity.</summary>
|
||||
/// <param name="status">A status code.</param>
|
||||
/// <returns>Whether the Bad severity bit is set.</returns>
|
||||
public static bool IsBad(uint status) => (status & SeverityBadBit) != 0;
|
||||
|
||||
/// <summary>True when <paramref name="status"/> has Good severity.</summary>
|
||||
/// <param name="status">A status code.</param>
|
||||
/// <returns>Whether both severity bits are clear.</returns>
|
||||
public static bool IsGood(uint status) => (status & SeverityMask) == 0;
|
||||
}
|
||||
@@ -0,0 +1,32 @@
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Sql.Common;
|
||||
|
||||
/// <summary>A stored sample as read back: source time, typed value and stored status.</summary>
|
||||
/// <param name="TimeUtc">Source timestamp (UTC).</param>
|
||||
/// <param name="Value">Typed value (<see cref="HistorianValue.Empty"/> for an outage marker).</param>
|
||||
/// <param name="Status">Stored OPC UA status code.</param>
|
||||
public readonly record struct StoredSample(DateTime TimeUtc, HistorianValue Value, uint Status)
|
||||
{
|
||||
/// <summary>Severity Good or Uncertain, and a value present (an Empty sample is an outage marker).</summary>
|
||||
public bool IsUsable => !StatusBits.IsBad(Status) && Value.Kind != HistorianValueKind.Empty;
|
||||
|
||||
/// <summary>Usable with severity Good.</summary>
|
||||
public bool IsGood => IsUsable && StatusBits.IsGood(Status);
|
||||
|
||||
/// <summary>
|
||||
/// Builds a sample from stored columns, applying the quality clamp: an Empty (no-value) row whose stored status
|
||||
/// is not Bad is served as <c>BadNoData</c> — defence in depth for rows written before the writer forced every
|
||||
/// Empty sample Bad.
|
||||
/// </summary>
|
||||
/// <param name="timeUtc">Source timestamp (UTC).</param>
|
||||
/// <param name="value">Stored value.</param>
|
||||
/// <param name="status">Stored status code.</param>
|
||||
/// <returns>The sample, clamped.</returns>
|
||||
public static StoredSample FromStored(DateTime timeUtc, HistorianValue value, uint status)
|
||||
{
|
||||
if (value.Kind == HistorianValueKind.Empty && !StatusBits.IsBad(status))
|
||||
status = HistorianStatusCodes.BadNoData;
|
||||
return new StoredSample(timeUtc, value, status);
|
||||
}
|
||||
}
|
||||
+22
@@ -0,0 +1,22 @@
|
||||
<Project Sdk="Microsoft.NET.Sdk">
|
||||
|
||||
<PropertyGroup>
|
||||
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
|
||||
<GenerateDocumentationFile>true</GenerateDocumentationFile>
|
||||
<NoWarn>$(NoWarn);CS1591</NoWarn>
|
||||
<Platforms>AnyCPU;x64</Platforms>
|
||||
<RootNamespace>ZB.MOM.WW.OtOpcUa.Driver.Historian.Sql.Common</RootNamespace>
|
||||
</PropertyGroup>
|
||||
|
||||
<!--
|
||||
The database-independent core shared by the SQL historian backends (SQL Server, QuestDB): status codes and bits,
|
||||
value/column mapping, the AtTime and aggregate evaluators, bucket planning, live-write preparation, HistoryUpdate
|
||||
result planning and the bootstrap failure cache. NO database client and no I/O.
|
||||
-->
|
||||
<ItemGroup>
|
||||
<ProjectReference Include="..\..\Core\ZB.MOM.WW.OtOpcUa.Core.Abstractions\ZB.MOM.WW.OtOpcUa.Core.Abstractions.csproj"/>
|
||||
<!-- AlarmEventIds.ComputeEventId takes an AlarmHistorianEvent (same signature as the SQL Server writer had). -->
|
||||
<ProjectReference Include="..\..\Core\ZB.MOM.WW.OtOpcUa.Core.AlarmHistorian\ZB.MOM.WW.OtOpcUa.Core.AlarmHistorian.csproj"/>
|
||||
</ItemGroup>
|
||||
|
||||
</Project>
|
||||
Reference in New Issue
Block a user