DP44/enriched-partialglm/Common/DTS.Common.SerializationPlus.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common.SerializationPlus/EventInfoAggregate.cs	2026-04-16T11:34:44.427048+00:00	zai-org/GLM-5-FP8	1	342395eec4a038a1

Documentation: EventInfoAggregate

1. Purpose

EventInfoAggregate is an aggregation class that consolidates event information from multiple Data Acquisition System (DAS) units into a single unified view. It implements IEventInfoAggregate and serves to merge data from distributed recording modules that participate in the same test event, tracking metadata such as duration, sample counts, channel counts, and fault status across all participating units.

---

2. Public Interface

Properties

Property	Type	Description
EventId	string	Test/event identifier
EventDescription	string	Human-readable event description
DurationSeconds	double	Event duration in seconds
GUID	string	Unique test identifier (string representation of GUID)
HasBeenDownloaded	bool	Indicates whether event data has been downloaded
WasTriggered	bool	Indicates whether the event was triggered
NumberOfChannels	int	Cumulative channel count across all modules
NumberOfSamples	ulong	Sample count per channel
NumberOfBytes	ulong	Total data size in bytes
Faulted	bool	Indicates any fault condition across aggregated units
EventNumber	int	Sequential event number

Constructor

public EventInfoAggregate(DownloadReport.EventInfo newEvent)

Initializes the aggregate with the first event. Handles empty Modules collections gracefully by setting DurationSeconds and NumberOfSamples to 0. Registers the owning DAS unit in the internal index map.

Methods

public Slice.Control.Event GetEvent(bool bClear)

Returns the cached Slice.Control.Event instance. If bClear is true, clears the cached instance before returning (forcing recreation on next call).

public Slice.Control.Event GetEvent()

Returns the cached Slice.Control.Event instance, creating it lazily if null.

public int GetEventIndex(IDASCommunication idas)

Returns the event index associated with the specified DAS unit. Returns -1 and logs an error if the DAS unit is not found in the index map.

public List<IDASCommunication> GetDasList()

Returns the list of DAS units associated with this event. Lazily populated from the internal index dictionary keys.

public void Add(IEventInfo newEvent)

Merges another event into this aggregate. Accumulates channel counts, ORs fault status, and takes minimum values for mismatched durations and sample counts. Logs warnings for any data mismatches but does not throw exceptions.

---

3. Invariants

• Byte Calculation: NumberOfBytes is always calculated as 2 * NumberOfChannels * NumberOfSamples (assumes 2 bytes per sample per channel).
• Channel Accumulation: NumberOfChannels is cumulative; each Add() call sums the new module's channel count.
• Fault Aggregation: Faulted is the logical OR of all aggregated events' fault status.
• Mismatch Handling: When durations or sample counts differ between aggregated events, the minimum value is retained.
• Empty Modules Safety: Constructor handles empty Modules collections without throwing (sets DurationSeconds and NumberOfSamples to 0).
• Index Uniqueness: _eventIndices uses indexer assignment to handle potential duplicate keys gracefully.

---

4. Dependencies

This Module Depends On

• DTS.Common.Interface.DASFactory — IDASCommunication interface
• DTS.Common.Interface.DASFactory.Download — IEventInfo, DownloadReport.EventInfo, DASModule
• DTS.Common.Utilities.Logging — APILogger for diagnostic logging
• DTS.DASLib.Service — Slice.Control.Event class

Implementations

• Implements IEventInfoAggregate (interface not shown in source)

---

5. Gotchas

1. Add() lacks empty Modules guard: Unlike the constructor, Add() accesses newEvent.Modules[0] without checking if Modules is empty, which will throw ArgumentOutOfRangeException.

2. Mismatches are logged, not enforced: The Add() method logs warnings for TestID, Description, GUID, EventNumber, and other mismatches but continues processing. Callers cannot detect mismatches programmatically.

3. Silent data loss on mismatch: When durations or sample counts don't match, the minimum is silently taken. The original values are lost and only a warning is logged.

4. GetEventIndex returns -1 for missing keys: Callers must check for -1 return value; no exception is thrown for unknown DAS units.

5. Lazy initialization side effects: GetDasList() and GetEvent() cache their results. The GetEvent(bool bClear) overload is the only way to reset the Slice.Control.Event cache.

6. Historical bug fixes embedded:

   • Empty modules handling added for case 15575 (cable disconnect during download)
   • Indexer assignment used instead of .Add() for case 44357 (duplicate key prevention)