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

---
source_files:
  - Common/DTS.Common.Serialization/TDAS/TDAS.File.Reader.BadCrcException.cs
  - Common/DTS.Common.Serialization/TDAS/TDAS.File.Reader.MissingFileException.cs
  - Common/DTS.Common.Serialization/TDAS/TDAS.File.Reader.TooManyFilesException.cs
  - Common/DTS.Common.Serialization/TDAS/TDAS.File.IChannelHeader.cs
  - Common/DTS.Common.Serialization/TDAS/TDAS.File.PersistentChannel.NotInitializedException.cs
  - Common/DTS.Common.Serialization/TDAS/TDAS.File.PersistentChannel.DataTooBigForArrayException.cs
  - Common/DTS.Common.Serialization/TDAS/TDAS.File.cs
  - Common/DTS.Common.Serialization/TDAS/TDAS.File.BinaryChannelHeader.cs
  - Common/DTS.Common.Serialization/TDAS/TDAS.File.Writer.cs
  - Common/DTS.Common.Serialization/TDAS/TLFBin.cs
generated_at: "2026-04-17T15:31:04.374981+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "6096e17ba8eed1d1"
---

# TDAS File Serialization Module Documentation

## 1. Purpose

This module provides TDAS (Test Data Acquisition System) file serialization and deserialization capabilities for the DTS framework. It handles reading and writing TDAS-specific file formats including `.tlf` test files, `.BIN` binary channel data files, and `.cchn` calculated channel files. The module implements binary channel header structures with CRC validation, supports multiple sensor types including digital input modes, and provides comprehensive exception handling for file I/O operations specific to the TDAS data acquisition workflow.

---

## 2. Public Interface

### `DTS.Serialization.TDAS.File` (partial class)

**Constructor:**
- `File()` — Initializes a new instance with format identifier "TDAS".

**Static Properties:**
- `string Extension` — Returns `".tlf"`, the file format extension.
- `string TestFileExtension` — Gets/sets the test file extension (default: `".tlf"`).
- `string ChannelFileExtension` — Gets/sets the channel file extension (default: `".BIN"`).
- `string CalculatedChannelFileExtension` — Gets/sets the calculated channel extension (default: `".cchn"`).

**Instance Properties:**
- `IWriter<Test> Exporter` — Gets the file writer instance (lazy-initialized).
- `IReader<Test> Importer` — Gets the file reader instance (lazy-initialized).

**Methods:**
- `int GetChannelNumberFromChannelFileName(string channelFileName)` — Extracts the 3-digit channel number from a channel filename by parsing before the extension.

---

### `DTS.Serialization.TDAS.File.Reader` (nested partial class)

**Nested Exception Types:**

#### `BadCrcException : Exception`
Represents a bad CRC file event.

| Constructor | Description |
|-------------|-------------|
| `BadCrcException()` | Default constructor. |
| `BadCrcException(string msg)` | Initializes with message. |
| `BadCrcException(string msg, System.Exception innerEx)` | Initializes with message and inner exception. |

#### `MissingFileException : Exception`
Represents a missing-file event.

| Constructor | Description |
|-------------|-------------|
| `MissingFileException()` | Default constructor. |
| `MissingFileException(string msg)` | Initializes with message. |
| `MissingFileException(string msg, System.Exception innerEx)` | Initializes with message and inner exception. |

#### `TooManyFilesException : Exception`
Represents a too-many-files event.

| Constructor | Description |
|-------------|-------------|
| `TooManyFilesException()` | Default constructor. |
| `TooManyFilesException(string msg)` | Initializes with message. |
| `TooManyFilesException(string msg, System.Exception innerEx)` | Initializes with message and inner exception. |

---

### `DTS.Serialization.TDAS.File.PersistentChannel` (nested partial class)

**Nested Exception Types:**

#### `NotInitializedException : ApplicationException`
Thrown when attempting to access a property that has not been initialized.

| Constructor | Description |
|-------------|-------------|
| `NotInitializedException()` | Default constructor. |
| `NotInitializedException(string msg)` | Initializes with message. |
| `NotInitializedException(string msg, System.Exception innerEx)` | Initializes with message and inner exception. |

#### `DataTooBigForArrayException : ApplicationException`
Thrown when attempting to convert a large dataset to an array that exceeds safe handling limits.

| Constructor | Description |
|-------------|-------------|
| `DataTooBigForArrayException()` | Default constructor. |
| `DataTooBigForArrayException(string msg)` | Initializes with message. |
| `DataTooBigForArrayException(string msg, System.Exception innerEx)` | Initializes with message and inner exception. |

---

### `DTS.Serialization.TDAS.IChannelHeader` (interface)

Defines the contract for channel header data.

| Property | Type | Description |
|----------|------|-------------|
| `AcquisitionRate` | `Double` | Get/set acquisition rate value. |
| `NumberOfPreT0DataPoints` | `int` | Get/set number of pre-T0 data points. |
| `NumberOfPostT0DataPoints` | `int` | Get/set number of post-T0 data points. |
| `PreZeroLevelInCnts` | `int` | Get/set pre-zero level in counts. |
| `PreCalLevelInCnts` | `int` | Get/set pre-calibration level in counts. |
| `SignalToNoiseRatioInDb` | `Double` | Get/set signal-to-noise ratio in dB. |
| `PostZeroLevelInCnts` | `int` | Get/set post-zero level in counts. |
| `PostCalLevelInCnts` | `int` | Get/set post-calibration level in counts. |
| `DataZeroLevelInCnts` | `int` | Get/set data zero level in counts. |
| `ScaleFactorMVPerCnt` | `Double` | Get/set scale factor (mV per count). |
| `ScaleFactorEUPerCnt` | `Double` | Get/set scale factor (EU per count). |

---

### `DTS.Serialization.TDAS.File.TDASBinaryChannelHeader` (nested class)

Implements `IChannelHeader` and `Exceptional`. Represents binary channel header information.

**Properties (in addition to `IChannelHeader`):**
- `UInt32 Crc32` — Gets the CRC for the current header state.
- `UInt32 UnpaddedEuCrc32` — Gets the CRC with EU padding automatically stripped.
- `UInt32 UnpaddedEuStringPaddedEuLengthCrc32` — Gets the CRC with unpadded EU string but padded EU length.

**Private Methods:**
- `UInt32 CalculateCrc32(bool stripEuPadding, bool bKeepEuLength)` — Calculates CRC16 for the binary channel header.

---

### `DTS.Serialization.TDAS.File.Writer` (nested class)

Implements `IWriter<Test>`. Serializes `Test` objects to TDAS format.

**Constructor:**
- `Writer(File fileType, int encoding)` — Internal constructor.

**Methods:**
- `void Write(string pathname, string id, Test test, bool bFiltering, bool includeGroupNameInISOExport, double minStartTime, int dataCollectionLength)` — **Throws `NotSupportedException`**.
- `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 the test to TDAS format files.
- `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)` — Empty implementation.

---

### `DTS.Serialization.TDAS.TLFBin`

Helper class for binary channel file serialization.

**Constructor:**
- `TLFBin(Test.Module.Channel channel, double superSampleRate)` — Initializes header values from channel data.

**Properties:**
| Property | Type |
|----------|------|
| `AcquisitionRate` | `double` |
| `PreTriggerDataPoints` | `int` |
| `PostTriggerDataPoints` | `int` |
| `PreZeroLevel` | `int` |
| `PreCalLevel` | `int` |
| `SignalToNoiseRatio` | `double` |
| `PostZeroLevel` | `int` |
| `PostCalLevel` | `int` |
| `SuperSampleRate` | `double` |

**Methods:**
- `void Serialize(System.IO.BinaryWriter bw, Test.Module.Channel channel)` — Serializes channel data to binary format, handling digital inputs and linearization formulas.

---

## 3. Invariants

1. **Channel Number Format**: Channel numbers are extracted from filenames using a fixed 3-character format (e.g., `"001"`, `"901"`).

2. **Squib Channel Numbering**: Squib channels always start numbering at `901` and increment; regular channels start at `LastChannelNumber + 1`.

3. **CRC Algorithm**: Binary channel headers use CRC16 with initial value `0xFFFF`, processing data in 2-byte steps.

4. **Exception Pattern**: All custom exceptions provide three standard constructors: parameterless, message-only, and message-with-inner-exception.

5. **File Extension Consistency**: The `ChannelFileExtension` lookup is case-insensitive (checks both `".BIN"` and `".bin"`).

6. **Binary Data Alignment**: CRC calculation pads data to even byte count (`if (data.Count % 2 > 0) data.Add(0x0)`).

---

## 4. Dependencies

### This Module Depends On:
- `DTS.Common.Utilities.DotNetProgrammingConstructs` — `Property<T>` class
- `DTS.Common.Utilities` — `Exceptional` interface
- `DTS.Common.Utils` — `Math_DoCRC16Step` for CRC calculation
- `DTS.Common.Utilities.Logging` — `APILogger` for error logging
- `DTS.Common.Constant` — `SensorConstants.BridgeType`
- `DTS.Common.Enums` — `DigitalInputModes` enum
- `DTS.Common.Enums.Sensors` — Sensor-related constants
- `DTS.Serialization.Test` — `Test`, `Test.Module.Channel`, `Test.Module.AnalogInputChannel`
- `SliceRaw.File.Reader` — `GetDataScaler()` method
- `System.IO` — `BinaryWriter`, `StreamWriter`, `FileStream`
- `System.Linq` — Channel queries

### External References (Inferred):
- `Serialization.File` — Base class for `File`
- `IWritable<Test>`, `IWriter<Test>`, `IReader<Test>` — Serialization interfaces
- `FilteredData`, `BeginEventHandler`, `CancelEventHandler`, `EndEventHandler`, `TickEventHandler`, `ErrorEventHandler`, `CancelRequested` — Event/delegate types
- `TLF` — TLF file format handler

---

## 5. Gotchas

1. **Unsupported Write Overload**: The `Write(pathname, id, test, bFiltering, ...)` overload with fewer parameters throws `NotSupportedException`. Use the full parameter version instead.

2. **Hardcoded Post-Test Values**: In `TLFBin`, `PostZeroLevel` and `PostCalLevel` are hardcoded to `0` with a `@TODO` comment indicating this information is not currently available.

3. **PreCalLevel Derivation**: `PreCalLevel` is set to `70%` of `short.MaxValue` (`0.7D * short.MaxValue`) rather than being read from actual calibration data.

4.