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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common.Serialization/SoMat/SoMat.File.cs Common/DTS.Common.Serialization/SoMat/SoMatTestHeader.cs Common/DTS.Common.Serialization/SoMat/SoMatChannel.cs Common/DTS.Common.Serialization/SoMat/SoMat.File.Writer.cs	2026-04-16T03:38:52.973808+00:00	Qwen/Qwen3-Coder-Next-FP8	1	75e43dc7ec17e504

SoMat

SoMat Serialization Module Documentation

---

1. Purpose

This module implements serialization of Test objects (from DTS.Serialization.Test) into a proprietary text-based format compatible with Diadem (a data analysis and reporting tool from National Instruments). It generates a single .txt file containing structured metadata (test header, channel definitions) followed by tab-delimited numeric data arrays. The module is part of the DTS.Serialization.SoMat namespace and serves as a concrete implementation of a file writer for SoMat-formatted output, primarily used for exporting test data for post-processing or reporting.

---

2. Public Interface

DTS.Serialization.SoMat.File

• File()
  Parameterless constructor. Initializes the base Serialization.File with the string "SoMat" as the format name.

• static string Extension
  Returns the file extension for SoMat files: ".txt".

• IWriter<Test> Exporter
  Lazily-initialized property that returns an IWriter<Test> instance (SoMat.File.Writer) using DefaultEncoding. Throws an Exception with inner exception if writer instantiation fails.

DTS.Serialization.SoMat.File.Writer

• internal Writer(File fileType, int encoding)
  Internal constructor; initializes the base Writer<File> with the provided fileType and encoding.

• void Write(string pathname, string id, Test test, bool bFiltering, bool includeGroupNameInISOExport, double minStartTime, int dataCollectionLength)
  Throws NotSupportedException — this overload is explicitly unsupported.

• void Write(string pathname, string id, string dataFolder, Test test, bool bFiltering, bool includeGroupNameInISOExport, FilteredData fd, Test.Module.Channel tmChannel, int channelNumber, BeginEventHandler beginEventHandler, CancelEventHandler cancelEventHandler, EndEventHandler endEventHandler, TickEventHandler tickEventHandler, ErrorEventHandler errorEventHandler, CancelRequested cancelRequested, double minStartTime, int dataCollectionLength)
  Writes a SoMat file to pathname.

  • Constructs a SoMatTestHeader using test and FilteredData[] (from FilteredData property).
  • Serializes header and channel metadata to the file.
  • Writes "DM_Start=\r\n" as a data section marker.
  • Iterates over sample indices up to maxSamples (max across all modules), writing one row per sample with tab-separated values (formatted as "0.00000E+00"), one column per channel.
  • Invokes event handlers (beginEventHandler, tickEventHandler, endEventHandler, errorEventHandler) for progress and error reporting.
  • Logs exceptions via APILogger.Log.
  • Throws exceptions if no errorEventHandler is provided.

• FilteredData[] FilteredData
  Property to set/get the FilteredData[] array used during serialization. Required before calling the multi-parameter Write method.

DTS.Serialization.SoMat.SoMatTestHeader

• SoMatTestHeader(Test test, FilteredData[] filteredData)
  Constructor that populates header fields from test and filteredData.

  • TestTitle ← test.Id
  • RunDateTime ← formatted test.InceptionDate
  • Operator ← current Windows user name (falls back to empty string on failure)
  • NumLogChannels ← test.Channels.Count (capped by filteredData.Length)
  • NumDataModes ← 1 (hardcoded)
  • Populates _channels list by constructing SoMatChannel objects.

• void Serialize(StreamWriter sw)
  Writes header fields in DM_-prefixed key=value format to sw, followed by a blank line.

DTS.Serialization.SoMat.SoMatChannel

• SoMatChannel(Test.Module.Channel channel, int logicalChannel, FilteredData filteredData, int moduleArrayIndex, int numChannelsPerModule, DateTime inceptionDateTime)
  Constructor that initializes channel metadata from channel, filteredData, and test context.

  • LogicalChannel ← logicalChannel
  • ChanName ← channel.ChannelDescriptionString (via AnalogInputChannel)
  • NumDataPoints ← channel.ParentModule.NumberOfSamples
  • SampleRate, TimeBase, MaxValue, MinValue, UserMax, UserMin, ElapsedTime, AcquisitionRate, RTCStart, RTCEnd, PhysicalChannelNumber computed from module/channel/test data.
  • AxisUnitsDim2 ← engineeringUnits.TrimEnd()
  • AxisLabelDim2, DescDim2 ← channel.SerialNumber

• void Serialize(StreamWriter sw)
  Writes channel metadata in DM_-prefixed key=value format (plus legacy 2100_ and HDWParams/CALParams/DGParams keys) to sw, followed by a blank line.

---

3. Invariants

• File extension: All output files use .txt.
• Data format: Data section begins with "DM_Start=\r\n" and consists of rows of tab-separated floating-point values in scientific notation ("0.00000E+00").
• Channel ordering: Channels are serialized in the order of test.Channels, with index i mapped to filteredData[i].
• Physical channel numbering: PhysicalChannelNumber = 1 + moduleArrayIndex * numChannelsPerModule + aic.Number, where numChannelsPerModule = 3 (hardcoded in SoMatChannel constructor).
• Header consistency: NumLogChannels in SoMatTestHeader matches the number of SoMatChannel objects serialized.
• Time base: If TimeOfFirstSampleValid is false, TimeBase is computed as (StartRecordSampleNumber - TriggerSampleNumbers[0]) / SampleRateHz.
• Data mode: NumDataModes is always 1; DataModeType is always "TIMHIS".

---

4. Dependencies

Internal Dependencies (from source):

• DTS.Serialization.Test (namespace DTS.Serialization) — core test model.
• DTS.Serialization.SoMat.FilteredData — assumed to be a type with a double[] Data property (used in SoMatChannel and Writer.Write).
• DTS.Serialization.SoMat.Test.Module.Channel, Test.Module.AnalogInputChannel, Test.Module — test model subtypes.
• DTS.Common.Utilities.Logging.APILogger — for logging exceptions.
• System.IO.StreamWriter, System.Text.Encoding, System.Security.Principal.WindowsIdentity, System.Linq, System.Windows.Forms.Application (for DoEvents()).

External Dependencies:

• Diadem compatibility: Output format is designed for consumption by Diadem (per Writer summary).
• Windows-specific: Uses WindowsIdentity.GetCurrent() for operator name.

Dependencies on this module:

• DTS.Serialization.Test consumers (e.g., test export pipelines) likely depend on SoMat.File.Exporter to generate .txt files.

---

5. Gotchas

• Unsupported Write overload: The 7-parameter Write method throws NotSupportedException. Only the 17-parameter overload is functional.
• Hardcoded numChannelsPerModule = 3: In SoMatChannel constructor, numChannelsPerModule is passed as 3. This may be incorrect if modules have varying channel counts.
• FilteredData must be set manually: The Writer.FilteredData property must be assigned before calling Write; otherwise, FilteredData is null, causing a NullReferenceException during header construction.
• TimeBase fallback logic: When TimeOfFirstSampleValid is false, TriggerSampleNumbers[0] is used. If TriggerSampleNumbers is empty or StartRecordSampleNumber is invalid, this may produce incorrect or NaN values.
• Encoding: Uses Encoding.Default (ANSI code page) for file writing — may cause issues with non-ASCII characters.
• Event handler requirements: If errorEventHandler is null and an exception occurs, the exception is rethrown. Otherwise, it is suppressed and only passed to errorEventHandler.
• DM_Start marker: The "DM_Start=\r\n" line is written before data rows, but no corresponding "DM_Stop" or end marker is present.
• NumDataModes hardcoded: Always 1, regardless of actual data modes in the test.
• PhysicalChannelNumber assumes fixed numChannelsPerModule: Calculation may be incorrect if numChannelsPerModule differs from 3 in practice.
• No validation of filteredData.Length vs test.Channels.Count: The SoMatTestHeader constructor silently truncates to the smaller of the two counts.

None identified beyond these.