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

---
source_files:
  - Common/DTS.Common.Serialization/FIAT_ASC/FIAT_Asc.File.cs
  - Common/DTS.Common.Serialization/FIAT_ASC/FIAT_Asc.File.Writer.cs
generated_at: "2026-04-17T15:42:04.516508+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "89485aa6a1ed05a2"
---

# Documentation: DTS.Serialization.FIAT_ASC

## 1. Purpose

This module provides serialization support for exporting `DTS.Serialization.Test` objects to FIAT `.asc` file format. It creates one `.asc` file per channel, writing time-series data with headers containing start time, sample interval, and data collection length. The module handles data scaling (ADC to Engineering Units), optional subsampling, filtering, and provides progress reporting events for long-running export operations.

---

## 2. Public Interface

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

**Inheritance:** `Serialization.File`, implements `IWritable<Test>`

| Member | Signature | Description |
|--------|-----------|-------------|
| `Extension` | `public static string Extension => ".asc"` | Static property returning the file extension for this format. |
| `UseFlatExportFolders` | `public bool UseFlatExportFolders { get; set; }` | Controls whether exports use flat folder structure. Defaults to `false`. |
| `File()` | `public File()` | Constructor initializing the file type with identifier "ASC". |
| `Exporter` | `public IWriter<Test> Exporter { get; }` | Lazily initializes and returns a `Writer` instance for exporting tests. Creates the writer with `DefaultEncoding` and propagates `UseFlatExportFolders`. |

---

### `DTS.Serialization.FIAT_ASC.File.Writer` (nested partial class)

**Inheritance:** `Writer<File>`, implements `IWriter<Test>`

| Member | Signature | Description |
|--------|-----------|-------------|
| `OnBegin` | `public event BeginEventHandler OnBegin` | Event raised when writing starts. |
| `OnEnd` | `public event EndEventHandler OnEnd` | Event raised when writing completes. |
| `OnTick` | `public event TickEventHandler OnTick` | Event raised for progress updates (every 1000 data samples). |
| `OnCancel` | `public event CancelEventHandler OnCancel` | Event raised if the write is cancelled. |
| `OnError` | `public event ErrorEventHandler OnError` | Event raised if a fatal error occurs during writing. |
| `FilteredChannelData` | `public Dictionary<string, FilteredData> FilteredChannelData { get; set; }` | Dictionary mapping channel IDs to filtered data. Used when `Filtered` is `true`. |
| `UseFlatExportFolder` | `public bool UseFlatExportFolder { get; set; }` | Controls flat folder export behavior. Defaults to `false`. |
| `Start` | `public double Start { get; set; }` | Start time for export range. Defaults to `0D`. |
| `Stop` | `public double Stop { get; set; }` | Stop time for export range. Defaults to `0D`. |
| `SubSampleInterval` | `public ushort SubSampleInterval { get; set; }` | Interval for subsampling data. Defaults to `1` (no subsampling). |
| `Filtered` | `public bool Filtered { get; set; }` | Whether to use filtered channel data. Defaults to `true`. |
| `Write` (overload 1) | `public void Write(string pathname, string id, Test test, bool bFiltering, bool includeGroupNameInISOExport, double minStartTime, int dataCollectionLength)` | Simplified write method delegating to the full overload with null parameters. |
| `Write` (overload 2) | `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 exports all channels to individual `.asc` files. Creates one file per channel named after the channel. |
| `Initialize` | `public void Initialize(...)` | Empty implementation (no-op). |

---

## 3. Invariants

1. **One file per channel:** The `Write` method creates a separate `.asc` file for each channel in `test.Channels`, named using the channel name (sanitized for filesystem compatibility).

2. **Progress tick granularity:** Progress events are dispatched every `DataSamplesPerTick` (1000) samples written.

3. **File format structure:** Each `.asc` file contains:
   - Line 1: `{minStartTime} {1/sampleRate}` (both formatted as `F8`)
   - Line 2: `{dataCollectionLength}` (integer)
   - Subsequent lines: Data values, one per sample

4. **Channel name resolution:** For `AnalogInputChannel`, the channel name is taken from `Description` property; otherwise `ChannelName2` is used.

5. **Encoding fallback:** If `GetEncoding(DefaultEncoding)` fails, the writer falls back to `Encoding.Default`.

6. **Subsampling only applies when `SubSampleInterval > 1`:** When this condition is met, data is subsampled using `NHTSASubSample<T>`.

---

## 4. Dependencies

### This module depends on:
- `DTS.Common.DAS.Concepts` - For channel types and DAS concepts
- `DTS.Common.Enums.Sensors` - For `SensorConstants.BridgeType`, `ZeroMethodType`, `IsoViewMode`
- `DTS.Common.Utilities` - For `DiskUtility`, `DataScaler`
- `DTS.Common.Utilities.DotNetProgrammingConstructs` - For `Property<T>` wrapper
- `DTS.Common.Utilities.Logging` - For `APILogger`
- `DTS.Serialization.Test` - The `Test` object model being serialized
- `System.Windows.Forms` - For `Application.DoEvents()` during progress reporting

### What depends on this module:
- Not determinable from source alone; consumers would reference `DTS.Serialization.FIAT_ASC` namespace and use `File.Exporter.Write(...)`.

---

## 5. Gotchas

1. **`Initialize` is a no-op:** The `Initialize` method has an empty body despite accepting many parameters. It is unclear if this is intentional or incomplete.

2. **UI thread coupling:** The `WriteChannelInfo` method calls `System.Windows.Forms.Application.DoEvents()` during the write loop, creating a dependency on Windows Forms and potentially causing reentrancy issues.

3. **Unused parameters in `Write` overload 2:** Several parameters (`dataFolder`, `fd`, `tmChannel`, `channelNumber`) are passed to the full `Write` method but never used in the implementation.

4. **Channel name fallback logic:** The `OriginalChannelName` fallback for `AnalogInputChannel` depends on `ISOViewMode`, but the source of `WriterParent.ISOViewMode` is not defined in these files (likely defined in another partial file).

5. **Exception swallowed in `SetWindowAverageADC`:** The `WriteChannelInfo` method catches and silently ignores any exception from `scaler.SetWindowAverageADC(channel.WindowAverageADC)`.

6. **Hardcoded number format:** All numeric output uses `"F8"` format (8 decimal places), defined as a private constant `NUMBER_FORMAT`.

7. **Disk space check may silently fail:** If `GetDiskFreeSpaceEx` returns a non-zero error code, the method logs the error but proceeds with the write without validating available space.