DP44/enriched-qwen3-coder-next/DataPRO/SensorDB/TDCINI.md

---
source_files:
  - DataPRO/SensorDB/TDCINI/INIDataZeroTimeWindowSeconds.cs
  - DataPRO/SensorDB/TDCINI/INISmartBatteryThresholds.cs
  - DataPRO/SensorDB/TDCINI/INIViewerROI.cs
  - DataPRO/SensorDB/TDCINI/TSFINIRegionOfInterest.cs
  - DataPRO/SensorDB/TDCINI/TDCINIRS232Info.cs
  - DataPRO/SensorDB/TDCINI/INIIIHSExport.cs
  - DataPRO/SensorDB/TDCINI/INIRackInventory.cs
  - DataPRO/SensorDB/TDCINI/TDCINIError.cs
  - DataPRO/SensorDB/TDCINI/INIISOExportParameters.cs
generated_at: "2026-04-16T04:03:50.006519+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "e52e76ad1c9cbddd"
---

# INI File Parsing Helpers – Documentation

## 1. Purpose

This module provides a set of helper classes for parsing structured sections from INI configuration files used by the SensorDB/TDCINI subsystem. Each class corresponds to a specific INI section (e.g., `DataZeroTimeWindow`, `SmartBatteryThresholds`, `ViewerROI`, `RS232`, `ROI`, `RackInventory`, `IIHSExport`, `ISOExportParameters`) and encapsulates the logic to deserialize a line (or multiple lines for `INIRackInventory`) into strongly-typed properties. These helpers are used during INI file loading to validate and populate configuration data, returning structured results and collecting errors via a shared `TDCINIError` mechanism.

## 2. Public Interface

### `INIDataZeroTimeWindowSeconds`
- **`double Start { get; set; }`**  
  Start time (in seconds) of the data zero window.
- **`double End { get; set; }`**  
  End time (in seconds) of the data zero window.
- **`bool ReadFrom(string line, ref List<TDCINIError> errors, int iCurrentLine)`**  
  Parses a comma-separated line (e.g., `"1.2,3.4"`) into `Start` and `End`. Returns `false` and adds an `INI_DataZeroTimeWindow_INVALID` error if the line does not contain exactly two valid doubles.

### `INISmartBatteryThresholds`
- **`int Yellow { get; set; }`**  
  Time in minutes for the yellow battery warning threshold.
- **`int Red { get; set; }`**  
  Time in minutes for the red battery warning threshold.
- **`bool ReadFrom(string line, int curLine, ref List<TDCINIError> errors)`**  
  Parses a comma-separated line (e.g., `"30,10"`) into `Yellow` and `Red`. Returns `false` and adds an `INI_SmartBatteryStatusThresholds` error if the line does not contain exactly two valid integers.

### `INIViewerROI`
- **`double XMin { get; set; }`**  
  Minimum X value (e.g., time or position) for the viewer region of interest.
- **`double XMax { get; set; }`**  
  Maximum X value for the viewer region of interest.
- **`bool ReadFrom(string line, int curLine, ref List<TDCINIError> errors)`**  
  Parses a comma-separated line (e.g., `"0.5,2.0"`) into `XMin` and `XMax`. Returns `false` and adds an `INI_ViewerROI_INVALID` error if parsing fails or the line does not contain exactly two values.

### `TSFINIRegionOfInterest`
- **`double StartSeconds { get; set; }`**  
  Start time (in seconds) of the ROI relative to T0.
- **`double EndSeconds { get; set; }`**  
  End time (in seconds) of the ROI relative to T0.
- **`bool ReadFrom(string line, int currentLine, ref List<TDCINIError> errors)`**  
  Parses a comma-separated line (e.g., `"0.0,10.5"`) into `StartSeconds` and `EndSeconds`. Returns `false` and adds an `INI_ROI_INVALID` error if parsing fails or the line does not contain exactly two values.

### `TDCINIRS232Info`
- **`int ComPortNumber { get; set; }`**  
  Communication port number.
- **`int MaxComSpeed { get; set; }`**  
  Maximum speed (e.g., baud rate) of the COM port.
- **`int MaxComPorts { get; set; }`**  
  Maximum number of COM ports supported.
- **`bool ReadFrom(string line, ref List<TDCINIError> errors)`**  
  Parses a comma-separated line (e.g., `"3,115200,4"`) into `ComPortNumber`, `MaxComSpeed`, and `MaxComPorts`. Returns `false` and adds an `INI_COMINFO_INVALID` error if parsing fails or the line does not contain exactly three values. Note: `curLine` is not passed in this method.

### `INIIIHSExport`
- **`bool ApplyROI { get; set; }`**  
  Whether to apply the ROI during IIHS export.
- **`double ROIStartSeconds { get; set; }`**  
  Start time (in seconds) of the ROI for IIHS export.
- **`double ROIEndSeconds { get; set; }`**  
  End time (in seconds) of the ROI for IIHS export.
- **`bool ReadFrom(string line, int curLine, ref List<TDCINIError> errors)`**  
  Parses a comma-separated line (e.g., `"Y,0.0,5.0"`) into `ApplyROI`, `ROIStartSeconds`, and `ROIEndSeconds`. `ApplyROI` is set based on tokens `"0"/"F"/"N"` (false) or `"1"/"T"/"Y"` (true). Returns `false` and adds an `INI_IIHSExport_INVALID` error on parse failure or invalid boolean token.

### `INIRackInventory`
- **`INIRackInfo[] Racks { get; set; }`**  
  Array of parsed rack entries.
- **`class INIRackInfo`**  
  Inner class representing a single rack entry:
  - **`int Number { get; set; }`**  
    Rack number.
  - **`string SerialNumber { get; set; }`**  
    Rack serial number.
  - **`int Size { get; set; }`**  
    Rack size (e.g., U height).
  - **`string IPAddress { get; set; }`**  
    Rack IP address.
  - **`bool ReadFrom(string line, ref List<TDCINIError> errors)`**  
    Parses a comma-separated line (e.g., `"1,SN123,12,192.168.1.10"`) into the four fields. Returns `false` and adds `INI_RACKINVENTORY_INVALID` on failure.
  - **`TSFRackDescription ToTSFRackDescription()`**  
    Converts the `INIRackInfo` to a `TSFRackDescription` object, trimming `SerialNumber`.
- **`bool ReadFrom(string[] lines, ref int iCurLine, ref List<TDCINIError> errors)`**  
  Parses multiple lines until a line starting with `"----"` is encountered. Populates the `Racks` array. Returns `false` on error or if `TDCINIFile.GetNextLine` returns `null`. Decrements `iCurLine` on successful completion.

### `INIISOExportParameters`
- **`bool AutomaticISOExportOnDownload { get; set; }`**  
  Whether to automatically export ISO on download.
- **`string MMEHeaderTemplateFilename { get; set; }`**  
  Filename for MME header template (may be empty).
- **`bool PromptUserForMMETemplateFilename { get; set; }`**  
  Whether to prompt user for MME template.
- **`string ChannelHeaderTemplateFilename { get; set; }`**  
  Filename for channel header template (may be empty).
- **`bool PromptUserForChannelHeaderFilename { get; set; }`**  
  Whether to prompt user for channel header template.
- **`FilterOutputOptions FilterOutput { get; set; }`**  
  Output filter option (`UnFiltered`, `Filtered`, or `PromptUser`).
- **`bool SuppressExportCompletionDialog { get; set; }`**  
  Whether to suppress the export completion dialog.
- **`string DummyTemplateFilename { get; set; }`**  
  Filename for dummy template (may be empty).
- **`bool PromptUserForDummyTemplateFilename { get; set; }`**  
  Whether to prompt user for dummy template.
- **`enum FilterOutputOptions`**  
  - `UnFiltered = 0`
  - `Filtered = 1`
  - `PromptUser = 2`
- **`bool ReadFrom(string line, int curLine, ref List<TDCINIError> errors)`**  
  Parses a comma-separated line with 9 tokens. Tokens 0, 2, 4, 6, and 8 are boolean-like (`"0"/"F"/"N"` → false, `"1"/"T"/"Y"` → true). Token 5 selects `FilterOutput`. Tokens 1, 3, and 7 are string filenames. Returns `false` and adds `INI_ISOEXPORTPARAMETERS_INVALID` on failure.

### `TDCINIError`
- **`enum INIErrors`**  
  Contains over 70 specific error codes (e.g., `INI_DataZeroTimeWindow_INVALID`, `INI_ROI_INVALID`, `INI_ISOEXPORTPARAMETERS_INVALID`). Full list provided in source.
- **`INIErrors Error { get; }`**  
  The error type.
- **`int Line { get; set; }`**  
  Line number in the INI file where the error occurred (default `-1` if not applicable).
- **`string ExtraInfo { get; }`**  
  Additional context (e.g., the invalid token or full line).
- **Constructors**  
  - `TDCINIError(INIErrors error)`  
  - `TDCINIError(INIErrors error, string extraInfo)`  
  - `TDCINIError(INIErrors error, string extraInfo, int currentLine)`  
  All initialize the respective fields.

## 3. Invariants

- **Line Format**: All `ReadFrom(string line, ...)` methods expect exactly the number of comma-separated tokens required for their respective sections (e.g., 2 for ROI sections, 3 for `TDCINIRS232Info`, 9 for `INIISOExportParameters`). Any deviation results in an error and `false` return.
- **Numeric Parsing**: All numeric fields are parsed using `double.TryParse(..., NumberStyles.Any, CultureInfo.InvariantCulture, ...)`. Parsing failures result in an error and `false` return.
- **Boolean Parsing**: Boolean values are parsed using a case-insensitive token check: `"0"`, `"F"`, `"N"` → `false`; `"1"`, `"T"`, `"Y"` → `true`. Any other token is invalid.
- **Error Accumulation**: Errors are appended to the caller-provided `List<TDCINIError> errors` and never thrown as exceptions. Parsing failure does not throw; it returns `false`.
- **RackInventory Termination**: `INIRackInventory.ReadFrom(string[] lines, ...)` stops parsing when encountering a line starting with `"----"`. This is a hard delimiter.
- **Line Number Handling**: For single-line parsers, `curLine` is passed to `TDCINIError` constructors. For multi-line `INIRackInventory`, `iCurLine` is decremented after parsing to account for the final `"----"` line.

## 4. Dependencies

- **Internal Dependencies**:
  - `TDCINIError` (defined in same namespace) – used for error reporting.
  - `TSFRackDescription` – referenced only in `INIRackInfo.ToTSFRackDescription()`; assumed to be defined elsewhere in the codebase.
  - `TDCINIFile.GetNextLine(...)` – used by `INIRackInventory.ReadFrom(string[] lines, ...)` to iterate over lines and report errors.

- **External Dependencies**:
  - `System.Collections.Generic.List<T>`
  - `System.Globalization.NumberStyles`
  - `System.Globalization.CultureInfo`
  - `System` core types (`string`, `int`, `double`, `bool`, `enum`)

- **Depended Upon**:
  - These classes are likely consumed by a higher-level INI file parser (e.g., `TDCINIFile`) to populate configuration objects. The exact caller is not visible in the provided source.

## 5. Gotchas

- **Inconsistent `curLine` parameter**:  
  `TDCINIRS232Info.ReadFrom(...)` does **not** accept a `curLine` parameter, while all other `ReadFrom` methods do. This may lead to inconsistent error reporting (line number omitted for `TDCINIRS232Info` errors).
  
- **`INIRackInventory` mutates `iCurLine`**:  
  The `ReadFrom(string[] lines, ref int iCurLine, ...)` method decrements `iCurLine` at the end. Callers must be aware that after a successful call, `iCurLine` points to the line *before* the `"----"` delimiter, not after it.

- **Boolean token ambiguity**:  
  Boolean parsing accepts `"F"` and `"N"` for `false`, which may be non-intuitive (e.g., `"N"` for "No" vs `"F"` for "False"). Ensure INI files use consistent values.

- **No validation of logical constraints**:  
  None of the classes validate semantic constraints (e.g., `Start < End`, `Yellow > Red`, `XMin < XMax`). It is the caller’s responsibility to enforce such invariants.

- **`INIRackInfo.SerialNumber` is trimmed only in `ToTSFRackDescription()`**:  
  The raw `SerialNumber` property retains leading/trailing whitespace; trimming occurs only during conversion to `TSFRackDescription`. This may cause inconsistency if the property is used directly.

- **`ExtraInfo` in `TDCINIError` may contain partial tokens**:  
  For `INI_ViewerROI_INVALID` and `INI_ISOEXPORTPARAMETERS_INVALID`, the `ExtraInfo` field may be set to a single invalid token (e.g., `tokens[0]`) rather than the full line, while other errors use the full line. This inconsistency may complicate debugging.

- **No default values**:  
  Properties are uninitialized until `ReadFrom` succeeds. If `ReadFrom` fails, properties retain their default values (`0`, `false`, `null`, etc.), which may be misleading. Callers should not assume valid state on failure.

- **`INIRackInventory.Racks` setter creates a new list**:  
  The `Racks` property setter replaces the internal `_racks` list with a new `List<INIRackInfo>` constructed from the array. This may have performance implications for large rack lists and could break reference equality expectations.

None identified beyond the above.