DP44/docs/ai/Common/DTS.Common.Serialization/TDMS.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common.Serialization/TDMS/TDMS.File.cs Common/DTS.Common.Serialization/TDMS/TDMS.File.Writer.cs	2026-04-17T15:42:11.798940+00:00	zai-org/GLM-5-FP8	1	a50ccb16d11e1148

TDMS Serialization Module Documentation

1. Purpose

This module provides TDMS (Technical Data Management Streaming) file format serialization for test data. It implements a writer that serializes DTS.Serialization.Test objects to disk in the NI TDMS format, capturing channel metadata, test properties, and raw measurement data. The module serves as an export mechanism for test results within the DTS serialization framework.

2. Public Interface

DTS.Serialization.TDMS.File (partial class)

Inheritance: Serialization.File, IWritable<Test>

public File(Common.ISO.TestPlan plan)

Constructor that initializes a TDMS file instance with the specified test plan. Sets the file format to "TDMS".

public static string Extension => ".tdms"

Static property returning the file extension for TDMS files.

public bool UseZeroForUnfiltered { get; set; }
public bool FilteredExport { get; set; }

Configuration properties for export behavior (default false).

public override void SetEUData(string channelId, FilteredData fd)
public override FilteredData GetEUData(string channelId)

Methods for storing and retrieving engineering unit data for linearized channels via an internal dictionary.

public IWriter<Test> Exporter { get; }

Property that lazily initializes and returns a Writer instance. Sets WriterParent on each access.

---

DTS.Serialization.TDMS.File.Writer (nested class)

Inheritance: Writer<File>, IWriter<Test>

internal Writer(File fileType, int encoding)

Internal constructor accepting the parent File object and encoding value.

public File WriterParent { get; set; }
public Common.ISO.TestPlan TestPlan { get; set; }
public string ExtensionPrefix { get; set; }

Public properties for writer configuration.

public void Write(string pathname, string id, Test test, bool bFiltering, bool includeGroupNameInISOExport, double minStartTime, int dataCollectionLength)

Simplified write method that delegates to the full overload with null parameters for unused event handlers.

public 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)

Full write method that creates the output directory, writes the TDMS file with lead-in, metadata, and raw data. Invokes progress event handlers.

public void Initialize(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)

Note: Empty implementation in source.

---

Private Enums and Constants

private enum ToCMaskFields { TocMetaData, TocNewObjList, TocRawData, TocInterleavedData, TocBigEndian, TocDAQmxRawData }
private enum DataTypes { Void, I8, I16, I32, I64, U8, U16, U32, U64, SingleFloat, DoubleFloat, ExtendedFloat, SingleFloatWithUnit = 0x19, DoubleFloatWithUnit, ExtendedFloatWithUnit, String = 0x20, Boolean = 0x21, TimeStamp = 0x44, FixedPoint = 0x4F, ComplexSingleFloat = 0x08000c, ComplexDoubleFloat = 0x10000d }
private enum GroupProperties { TestId, Description, TestDate, TestTime }
private enum ChannelProperties { SensorSerialNo, ChannelDescriptionString, ChannelName, ModuleSerialNumber, SampleRate, NumberOfSamples, AAFilterRateHz, BridgeType, BridgeResistanceOhms, DesiredRange, Sensitivity, SensitivityUnits, ScaleFactorMV, ScaleFactorEU, LinearizationFormula, ZeroMethod, ZeroAverageWindowBegin, ZeroAverageWindowEnd, EU, InitialEU, InitialOffset, MeasuredShuntDeflectionMV, FactoryExcitationVoltage, MeasuredExcitationVoltage, SensorCalibrationDate, wf_xName, wf_xunit_string, wf_start_offset, wf_increment, wf_samples }

Key constants:

• TDSmTag = "TDSm"
• ToCMask = 14 (TocMetaData | TocNewObjList | TocRawData)
• Version = 4713
• NoRawDataAssigned = 0xFFFFFFFF
• ChannelObjectDataType = DataTypes.I16

3. Invariants

• File Format Version: Always 4713 per TDMS specification.
• Table of Contents Mask: Fixed at 14 (combining TocMetaData, TocNewObjList, TocRawData).
• Channel Data Type: All channel data written as I16 (16-bit signed integer).
• File Object Structure: TDMS files contain exactly 1 file object, 1 group object, plus N channel objects (where N = test.Channels.Count).
• Raw Data Index: File and Group objects always have NoRawDataAssigned (0xFFFFFFFF); channels have data index information.
• Channel Path Format: /{groupId}/'{channelName}:{channelDescription}'
• Group Path Format: '/{testId}' (test.Id is used as the group identifier).

4. Dependencies

This module depends on:

• System, System.IO, System.Linq, System.Collections.Generic (BCL)
• DTS.Common.Utilities.Logging.APILogger for error logging
• Serialization.File (base class)
• IWritable<Test>, IWriter<Test> interfaces
• Common.ISO.TestPlan
• DTS.Serialization.Test and nested types:
  • Test.Module.Channel
  • Test.Module.AnalogInputChannel
  • Test.Channels
• FilteredData type
• Delegate types: BeginEventHandler, CancelEventHandler, EndEventHandler, TickEventHandler, ErrorEventHandler, CancelRequested

Consumers:

• Unclear from source alone; this module appears to be a plugin format within a larger serialization framework.

5. Gotchas

1. Empty Initialize method: The Initialize method has a signature matching Write but contains no implementation. It is unclear if this is intentional or incomplete.

2. Unused parameters in Write overload: The full Write method accepts parameters dataFolder, fd, tmChannel, channelNumber, cancelEventHandler, and cancelRequested that are not referenced in the method body.

3. Exporter property side effect: Every access to Exporter sets WriterParent on the cached writer instance, potentially overwriting previous values.

4. Channel casting assumption: All channels are cast to Test.Module.AnalogInputChannel without type checking. If test.Channels contains non-AnalogInputChannel types, this will throw at runtime.

5. Superscript byte handling: GetSuperScriptBytes calculates extra bytes for Unicode superscript characters in linearization formulas, which affects property length calculations.

6. ScaleFactorEU calculation complexity: The scale factor calculation branches on ProportionalToExcitation and IsInverted flags, and applies a Multiplier—logic that may not be obvious from the property name alone.

7. Conditional excitation/shunt values: MeasuredShuntDeflectionMv and excitation voltage properties are written as 0D if their respective Valid flags are false, rather than omitting the property.