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

---
source_files:
  - Common/DTS.Common.Serialization/TDMS/TDMS.File.cs
  - Common/DTS.Common.Serialization/TDMS/TDMS.File.Writer.cs
generated_at: "2026-04-17T15:42:11.798940+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "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>`

```csharp
public File(Common.ISO.TestPlan plan)
```
Constructor that initializes a TDMS file instance with the specified test plan. Sets the file format to "TDMS".

```csharp
public static string Extension => ".tdms"
```
Static property returning the file extension for TDMS files.

```csharp
public bool UseZeroForUnfiltered { get; set; }
public bool FilteredExport { get; set; }
```
Configuration properties for export behavior (default `false`).

```csharp
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.

```csharp
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>`

```csharp
internal Writer(File fileType, int encoding)
```
Internal constructor accepting the parent `File` object and encoding value.

```csharp
public File WriterParent { get; set; }
public Common.ISO.TestPlan TestPlan { get; set; }
public string ExtensionPrefix { get; set; }
```
Public properties for writer configuration.

```csharp
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.

```csharp
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.

```csharp
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

```csharp
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.