DP44/enriched-qwen3-coder-next/Common/DTS.Common.Serialization/Control/Event.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common.Serialization/Control/Event/DasModuleAccessor.cs Common/DTS.Common.Serialization/Control/Event/DasChannelAccessor.cs Common/DTS.Common.Serialization/Control/Event/ChannelAccessor.cs Common/DTS.Common.Serialization/Control/Event/ModuleChannelAccessor.cs Common/DTS.Common.Serialization/Control/Event/DasModuleChannelAccessor.cs Common/DTS.Common.Serialization/Control/Event/TestInformation.cs Common/DTS.Common.Serialization/Control/Event/Event.cs	2026-04-16T03:41:53.208866+00:00	Qwen/Qwen3-Coder-Next-FP8	1	e1ba9340d986b9b2

Documentation: DTS.Slice.Control.Event Accessor Classes and Related Types

1. Purpose

This module provides accessor objects and supporting infrastructure for navigating and manipulating event data within the DTS Slice Control system. Specifically, it defines hierarchical dictionary-based accessors (DasModuleAccessor, DasChannelAccessor, DasModuleChannelAccessor, ChannelAccessor, ModuleChannelAccessor) that enable lookup of modules and channels by DAS ID, module number, and channel number combinations. It also includes the core Event class (a partial class with multiple files), which serves as the in-memory representation of a DAS event—encapsulating test metadata, modules, channels, and derived properties such as validation flags and serialization support. The module bridges low-level DAS serialization data (e.g., DTS.Serialization.Test) and higher-level control logic by offering structured, type-safe access to event components.

2. Public Interface

All accessor classes and the Event class reside in the DTS.Slice.Control namespace and are declared as public partial class Event.

Event Class

• Event()
  Default constructor. Initializes all properties to their default values.

• Event(string id, string description)
  Initializes an Event with the given id and description. Throws a wrapped exception on failure.

• Event(Test test, Test.ReportErrors reportErrors)
  Initializes an Event by converting from a DTS.Serialization.Test object via FromDtsSerializationTest. Rethrows exceptions directly.

• Event(string id, string description, List<Module> modules)
  Initializes an Event with id, description, and a list of Modules.

• Event(List<IDASCommunication> dases, EventInfoAggregate info)
  Initializes an Event by aggregating configuration and channel data from a list of DAS devices (IDASCommunication) and EventInfoAggregate. Populates Modules, DasModules, DasChannels, and DasModuleChannels. Throws UserException for missing DAS info or configuration. Validates test ID consistency across DAS units.

• string Id { get; set; }
  Gets/sets the event’s test ID.

• string Description { get; set; }
  Gets/sets the event’s description.

• Guid Guid { get; set; }
  Gets/sets the globally unique identifier for the event. Default is Guid.Empty.

• UInt16 FaultFlags { get; set; }
  Gets/sets the global fault flags for the event.

• DateTime InceptionDate { get; private set; }
  Gets the creation date of the event (set during construction). Defaults to DateTime.Now.

• List<Module> Modules { get; set; }
  Gets/sets the list of Module objects associated with this event.

• List<Module.Channel> CalculatedChannels { get; set; }
  Gets/sets the list of calculated channels.

• DasModuleAccessor DasModules { get; private set; }
  Returns a DasModuleAccessor keyed by DAS ID (Common.DAS.Concepts.DAS.Id), mapping to a List<Module>.

• DasChannelAccessor DasChannels { get; private set; }
  Returns a DasChannelAccessor keyed by DAS ID, mapping to a List<Module.Channel>.

• DasModuleChannelAccessor DasModuleChannels { get; private set; }
  Returns a DasModuleChannelAccessor keyed by DAS ID, mapping to a ModuleChannelAccessor.

• int LastAbsoluteChannelNumberInEvent { get; }
  Returns the highest absolute channel number across all modules and channels.

• bool IsTooLargeFor32BitVisualization { get; }
  Returns true if the total data volume (based on TooLargeFor32BitVisualizationBytesPerSampleThreshold) exceeds 2GB (0x7FFFFFFF bytes).

• double TooLargeFor32BitVisualizationBytesPerSampleThreshold { get; private set; }
  Threshold in bytes per sample used for 32-bit visualization size checks. Default: 2.0.

• bool ContainsChannelsActiveInvalidZeroingWindows { get; }
  Returns true if any channel has ZeroMethod == AverageOverTime and an invalid averaging window.

• List<Module.Channel> ChannelsWithActiveInvalidZeroingWindows { get; }
  Returns the list of channels with active but invalid zeroing windows (e.g., window outside data range or negative indices).

• static string BaseSerializationDirectory { get; set; }
  Gets/sets the base directory path for event serialization.

• static string GetEventSerializationDirectory(string eventId)
  Returns the full path for the serialization directory of the given eventId.

• bool Equals(object obj)
  Overrides Equals to compare Id, Description, Guid, Modules, and FaultFlags.

• int GetHashCode()
  Overrides GetHashCode.

• Test ToDtsSerializationTest()
  Converts this Event to a DTS.Serialization.Test. Removes unconfigured/dummy channels before serialization.

• void FromDtsSerializationTest(Test that, Test.ReportErrors reportErrors)
  Populates this Event from a DTS.Serialization.Test. Re-throws InvalidDataException directly; wraps others.

• static implicit operator Test(Event sliceControlEvent)
  Implicit conversion operator to DTS.Serialization.Test.

• static bool IsG5(IDASCommunication idas)
  Returns true if the DAS serial number starts with "5M".

• static bool IsSlice6DBModule(Module module)
  Returns true if module.Description.ToLower() == "slice6db module".

Accessor Classes

• DasModuleAccessor : ExceptionalDictionary<Common.DAS.Concepts.DAS.Id, List<Module>>
  Keyed by DAS ID, maps to list of Modules. Used to retrieve modules by DAS.

• DasChannelAccessor : ExceptionalDictionary<Common.DAS.Concepts.DAS.Id, List<Module.Channel>>
  Keyed by DAS ID, maps to list of Module.Channels. Used to retrieve channels by DAS.

• DasModuleChannelAccessor : ExceptionalDictionary<Common.DAS.Concepts.DAS.Id, ModuleChannelAccessor>
  Keyed by DAS ID, maps to a ModuleChannelAccessor. Enables 3-level lookup: DAS ID → module index → channel index.

• ChannelAccessor : ExceptionalDictionary<int, Module.Channel>
  Keyed by int (module channel number), maps to a Module.Channel. Used as the innermost accessor.

• ModuleChannelAccessor : ExceptionalDictionary<int, ChannelAccessor>
  Keyed by int (module array index), maps to a ChannelAccessor. Enables lookup of channels by module number.

• TestInformation : Exceptional (private)
  Holds test metadata (Id, Description) per DAS. Used internally during event construction.

Helper Methods (in Event)

• bool IsDummyChannel(Module.Channel channel)
  Returns true if channel.ChannelDescriptionString.ToLower() == "dummy arm channel".

• bool IsTom(DASModule module)
  Returns true if module is a TOM (based on serial number or channel type).

• void PurgeUnconfiguredChannels()
  Removes unconfigured or dummy channels from all modules.

• bool IsEmptyModule(Module module)
  Returns true if module has no configured/non-dummy channels.

3. Invariants

• DasModules, DasChannels, DasModuleChannels are always initialized
  These properties are initialized in the Property<T> declaration with new accessor instances and are marked readonly/true (immutable reference after construction).

• Module array indices must match list positions
  The constructor for Event(List<IDASCommunication>, EventInfoAggregate) asserts:
  Debug.Assert(DasModules[das.SerialNumber].Count - 1 == dasModule.ModuleArrayIndex);
  This implies modules are inserted in order, and empty slots are filled with placeholder Module instances.

• Test ID must be consistent across all DAS units
  During construction, if any DAS reports a different TestID, an exception is thrown.

• Channel absolute numbers are assigned sequentially
  absoluteChannelNumber is incremented per channel added, and Module.Channel.AbsoluteNumber is set during Channel.CreateChannel.

• InceptionDate is set once at construction
  The setter is private, and the property is initialized with DateTime.Now or the serialization date.

• TooLargeFor32BitVisualizationBytesPerSampleThreshold is immutable after construction
  Marked readonly and true in Property<T>.

• IsSlice6DBModule check is case-insensitive
  Compares module.Description.ToLower() to "slice6db module".

• InvalidWindowAverage is short.MinValue
  Used to detect uninitialized or invalid window averages in zeroing logic.

4. Dependencies

Internal Dependencies (within this module)

• DTS.Slice.Control.Event.Module and nested types (Module.Channel, Module.AnalogInputChannel, etc.)
• DTS.Common.Utilities.ExceptionalDictionary<TKey, TValue>
• DTS.Common.Utilities.DotNetProgrammingConstructs.Property<T>
• DTS.Slice.Control.Event.TestInformation (private helper)

External Dependencies

• DTS.Serialization.Test (from DTS.Serialization namespace)
• DTS.DASLib.Service.IDASCommunication, DASModule, DASChannel, EthernetTDAS
• DTS.Common.Utilities.Logging.APILogger
• System.Collections.Generic.List<T>, System.Guid, System.DateTime, System.Diagnostics.Debug
• DTS.Serialization.StringResources.Strings (for error messages)

Inferred Usage

• EventInfoAggregate is required for Event(List<IDASCommunication>, EventInfoAggregate) constructor.
• Test.ReportErrors delegate is used in FromDtsSerializationTest.
• Serialization infrastructure (DTS.Serialization) is used for round-trip conversion (ToDtsSerializationTest, FromDtsSerializationTest).

5. Gotchas

• DasModuleChannels property key is "DTS.Slice.Control.Event.DasModules" (typo)
  In the Event constructor, the Property<DasModuleChannelAccessor> for DasModuleChannels is initialized with the key "DTS.Slice.Control.Event.DasModules" instead of "DTS.Slice.Control.Event.DasModuleChannels". This is likely a copy-paste bug.

• DasModuleChannelAccessor uses int keys for module/channel indices, not typed IDs
  Both ModuleChannelAccessor and ChannelAccessor use int keys (for module number and channel number, respectively), not strongly-typed IDs (see xxx comments in source). This risks confusion or errors if indices are misaligned.

• InceptionDate defaults to DateTime.Now
  If constructed via the default constructor, InceptionDate reflects the current time—not the serialization time. Only the Event(Test, ...) constructor sets it from the Test.InceptionDate.

• IsSlice6DBModule is case-sensitive on "slice6db module"
  Uses ToLower() for comparison, but the literal string is lowercase. If the source description varies in casing (e.g., "Slice6DB Module"), it may not match.

• Zeroing window validation is complex and fragile
  ChannelsWithActiveInvalidZeroingWindows performs multiple checks (negative indices, window outside data range). Edge cases (e.g., empty TriggerSampleNumbers, zero sample rate) are not explicitly handled beyond defaulting to 0.

• PurgeUnconfiguredChannels modifies Modules in-place
  Called during ToDtsSerializationTest, this permanently removes channels. If the Event object is reused, data may be lost.

• IsDummyChannel and IsSlice6DBModule use string comparisons
  Relies on literal string matching ("dummy arm channel", "slice6db module"). No constants or enums are defined for these.

• IsG5 checks only serial number prefix
  Assumes "5M" prefix is sufficient to identify G5 devices. May be brittle if serial number formats change.

• No thread safety
  Comments in Event.cs explicitly note: "Also need to add thread protection." and "Can we set locks in the property accessors..." — no synchronization is present.

• TestInformation is private and not exposed
  While used internally, it is not part of the public API. Its properties (Id, Description) are not validated beyond assignment.

• TooLargeFor32BitVisualizationBytesPerSampleThreshold is hardcoded to 2.0
  The justification in comments is detailed, but the value is not configurable at runtime (only via reflection or subclassing).