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

source_files, generated_at, model, schema_version, sha256

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