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

---
source_files:
  - Common/DTS.Common.Serialization/HDF/HDF.File.cs
  - Common/DTS.Common.Serialization/HDF/HDF.File.Writer.cs
generated_at: "2026-04-17T15:42:12.245646+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "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
```csharp
public File()
```
Initializes a new HDF file instance, passing `"HDF"` to the base class.

#### Property: `Exporter`
```csharp
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
```csharp
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)
```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)
```
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)
```csharp
public void Write(string pathname, string id, Test test, bool bFiltering, bool includeGroupNameInISOExport, double minStartTime, int dataCollectionLength)
```
Empty implementation—does nothing.

#### Method: `Initialize`
```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)
```
Empty implementation—does nothing.

#### Property: `ExtensionPrefix`
```csharp
public string ExtensionPrefix { get; set; } = string.Empty
```
Optional prefix appended before `.h5` extension in output filename.

#### Enum: `ErrorLocation`
```csharp
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.