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

source_files, generated_at, model, schema_version, sha256

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

Documentation: DTS.Serialization.HDF.File

1. Purpose

This module provides HDF5 (Hierarchical Data Format) file export functionality for test data. It implements the Serialization.File abstraction for HDF5 format, enabling the serialization of Test objects—including channel data (ADC, mV, EU), metadata, and auxiliary files (logs, reports, setup files)—into .h5 files. The module serves as the export layer for DTS data acquisition systems, supporting both standard and WIAMan-compliant output formats.

---

2. Public Interface

Class: DTS.Serialization.HDF.File

Inheritance: Serialization.File, IWritable<Test>

Constructor

public File()

Initializes a new HDF file instance, passing "HDF" to the base class.

Property: Exporter

public IWriter<Test> Exporter { get; }

Lazy-initialized property that returns the IWriter<Test> implementation. Creates and caches a new Writer instance on first access. Throws Exception wrapping any underlying failure.

Set-Only Properties (delegate to internal Writer)

Property	Type	Description
ExportADC	bool	Controls whether ADC (raw) data is exported
ExportEU	bool	Controls whether Engineering Units data is exported
ExportMV	bool	Controls whether millivolt data is exported
ExportLogs	bool	Controls whether log files are included
ExportReports	bool	Controls whether report files are included
ExportSetup	bool	Controls whether setup files are included
ExportDTSFile	bool	Controls whether .dts files are included
CustomerName	string	Customer metadata for export
TestEngineerName	string	Test engineer metadata for export
LabName	string	Lab name metadata for export
IsWiamanData	bool	Flag for WIAMan-format data
ISOToFineLocation3	Dictionary<string, string>	ISO code to fine location mapping
ISOToPhysicalDimension	Dictionary<string, string>	ISO code to physical dimension mapping
ISOToPosition	Dictionary<string, string>	ISO code to position mapping
ISOToTransducerMainLocation	Dictionary<string, string>	ISO code to transducer location mapping

---

Nested Class: DTS.Serialization.HDF.File.Writer

Inheritance: Writer<File>, IWriter<Test>

Constructor

internal Writer(File fileType, int encoding)

Internal constructor. Initializes all export flags to true by default and stores reference to parent File.

Method: Write (primary overload)

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)

Main export method. Creates an HDF5 file at {pathname}/{id}_{LabName}_1of1{ExtensionPrefix}.h5, writes channel data (ADC/MV/EU based on export flags), includes auxiliary files, and invokes progress/event handlers throughout.

Method: Write (secondary overload)

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

Empty implementation—does nothing.

Method: Initialize

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)

Empty implementation—does nothing.

Property: ExtensionPrefix

public string ExtensionPrefix { get; set; } = string.Empty

Optional prefix appended before .h5 extension in output filename.

Enum: ErrorLocation

public enum ErrorLocation { File, Group, SubGroup, DataSpace, DataSet, Write }

Identifies where HDF API calls fail for error reporting.

---

3. Invariants

1. Exporter Lazy Initialization: The _exporter field is lazily initialized; once set, the same instance is returned on subsequent accesses.

2. Default Export Flags: All export flags (ExportADC, ExportEU, ExportMV, ExportLogs, ExportReports, ExportSetup) default to true in the Writer constructor.

3. Attribute Storage Format: All attributes are stored as HDF5 string attributes when ATTRIBUTE_STRING_DATATYPE_ONLY is true (which is constant true). Integer, ulong, and double values are converted to strings via ToString() before storage.

4. Channel Ordering: Channels are sorted by AbsoluteDisplayOrder before export.

5. Thread Safety: The H5WriteLock object is used to synchronize HDF5 API calls for string attribute creation. The _updateProgressLock object synchronizes progress updates.

6. HDF Export Version: All exports include attribute HDFExportVersion set to 7.0D.

7. Dataset Group Names:

   • EU data: /Datasets_EU
   • ADC data: /Datasets
   • MV data: /Datasets_MV

---

4. Dependencies

This Module Depends On:

• System (core .NET)
• System.Collections.Generic
• System.IO
• System.Linq
• System.Runtime.InteropServices
• System.Threading.Tasks
• DTS.Common.Enums.Sensors - SensorConstants.BridgeType.IEPE
• DTS.Common.Utilities.Logging - APILogger.Log() for error logging
• HDF.PInvoke - Low-level HDF5 API (H5F, H5G, H5S, H5D, H5A, H5T, H5P)
• DTS.Common.DAS.Concepts - DataScaler, Test, Test.Module, Test.Module.AnalogInputChannel, Test.Module.Channel.Sensor

Base Class:

• DTS.Serialization.File (inferred from inheritance)
• DTS.Serialization.Writer<File> (inferred from Writer inheritance)
• DTS.Serialization.IWriter<Test> (interface implementation)

---

5. Gotchas

1. Set-Only Properties Cast to Concrete Type: Properties like ExportADC, ExportEU, etc. on the File class cast Exporter to (Writer) on every set. This will throw if _exporter is somehow a different implementation.

2. Empty Method Implementations: The Write overload with fewer parameters and Initialize method are empty stubs. Calling them has no effect.

3. WIAMan Dictionary Access Without Null Check: In CreateDataset(), the code accesses ISO mapping dictionaries (e.g., ISOToFineLocation3[aic.IsoCode]) without null checks. If these dictionaries are not set or lack the key, a KeyNotFoundException or NullReferenceException will occur.

4. Hardcoded Directory Traversal: AddDirectoryIfExists() navigates up three parent directories from the binary path to find the root directory. This assumes a specific directory structure depth.

5. Progress Update Threading: Progress updates use a lock but the _curProg field is read outside the lock in UpdateProgress() before the comparison.

6. Unused Parameters: Several parameters in Write() are unused: bFiltering, includeGroupNameInISOExport, fd, tmChannel, channelNumber, cancelEventHandler, cancelRequested, minStartTime, dataCollectionLength.

7. File Overwrite: The HDF5 file is created with H5F.ACC_TRUNC which truncates (overwrites) any existing file with the same name.

8. Channel Type Filtering: Only Test.Module.AnalogInputChannel types are processed; other channel types are silently skipped in the Parallel.ForEach loop.