enriched-qwen3-coder-next/DataPRO/DASFactoryDb/Diagnostics.md

---
source_files:
  - DataPRO/DASFactoryDb/Diagnostics/Diagnostics.cs
generated_at: "2026-04-16T03:52:56.599244+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "435708341e9b9055"
---

# Diagnostics

## Documentation: `DASFactoryDb.Diagnostics.Diagnostics` Module

---

### 1. **Purpose**

This module provides a set of static methods to interact with diagnostic-related database operations for DAS (Data Acquisition System) communication records. It serves as the primary interface for inserting, clearing, and managing diagnostic *actions* (configured test parameters) and diagnostic *results* (observed test outcomes) across channels and events. The module abstracts low-level ADO.NET database calls into higher-level operations, delegating actual data persistence to stored procedures in the DASFactory database.

---

### 2. **Public Interface**

All methods are `public static` and reside in the `DASFactoryDb.Diagnostics.Diagnostics` class.

#### `ClearDiagnosticActionsAllChannels(int idasRecordId)`
- **Behavior**: Clears *all* diagnostic action configurations for *all channels* associated with the given `idasRecordId`. Uses the stored procedure `sp_DiagnosticActionsClear`.
- **Parameters**:
  - `idasRecordId`: ID of the DAS communication record to clear actions for.
- **Note**: Passes `null` for `@DASChannelNumber` to indicate “all channels”.

#### `InsertDiagnosticAction(...)`
- **Behavior**: Inserts a new diagnostic action configuration for a specific DAS channel. Uses the stored procedure `sp_DiagnosticsActionsInsert`.
- **Parameters**:
  - `dasRecordId`: ID of the DAS communication record.
  - `dasChannelNumber`: Channel number (0-based or 1-based? — not specified in source).
  - Boolean flags indicating which diagnostic tests to perform (e.g., `measureExcitation`, `measureOffset`, `squibFireCheck`, etc.).
- **Returns**: Output parameter `@new_id` (ID of inserted record) is captured but *not returned* by this method.

#### `ClearExistingDiagnosticsAllChannels(int idasRecordId = -1)`
- **Behavior**: Clears *all* diagnostic *results* for a given DAS communication record (or *all records* if `idasRecordId == -1`). Uses the stored procedure `sp_DiagnosticsResultsClear`.
- **Parameters**:
  - `idasRecordId`: Optional; defaults to `-1` (clear all records). If non-negative, clears only for that record.
- **Note**: Passes `null` for both `@DASChannelNumber` and `@EventNumber`, indicating “all channels and events”.

#### `InsertAnalogDiagnosticResult(...)`
- **Behavior**: Inserts a full analog diagnostic result record for a specific channel and event. Uses the stored procedure `sp_DiagnosticsResultsAnalogInsert`.
- **Parameters**:
  - `iDASRecordId`, `dasChannelNumber`, `eventNumber`: Identifiers for the diagnostic result context.
  - Numerous `double`, `short?`, `bool?` parameters representing measured/calculated values (e.g., excitation, offset, noise, gain, shunt deflection, bridge resistance).
- **Returns**: Output parameter `@new_id` is captured but *not returned*.

#### `InsertSquibDiagnosticResult(...)`
- **Behavior**: Inserts a squib (pyro) fire diagnostic result, including raw time-series data (current, voltage, time axis) as binary blobs. Uses the stored procedure `sp_DiagnosticsResultsSquibInsert`.
- **Parameters**:
  - `iDASRecordId`, `dasChannelNumber`, `eventNumber`: Identifiers.
  - `squibFireCurrentData`, `squibFireVoltageData`, `squibFireTimeAxis`: Arrays of `double` representing raw waveform data.
  - Optional metrics: `measuredDurationMS`, `measuredDelayMS`, pass/fail flags.
  - Calibration/scaling parameters: `squibThreshold`, `squibVoltageScaler`, `squibCurrentScaler`.
- **Special Behavior**:
  - **Early return** if `squibFireCurrentData == null` (prevents exception in `BitConverter.GetBytes`).
  - Converts `double[]` arrays to `byte[]` via `BitConverter.GetBytes` before storing in `VARBINARY` parameters.

#### `InsertDigitalDiagnosticResult(...)`
- **Behavior**: Inserts a digital diagnostic result (e.g., for digital input state verification). Uses the stored procedure `sp_DiagnosticsResultsDigitalInsert`.
- **Parameters**:
  - `iDASRecordId`, `dasChannelNumber`, `eventNumber`: Identifiers.
  - `digitalInputActiveState`: Boolean indicating whether the digital input was in its active state.

---

### 3. **Invariants**

- **Database Connection Check**: Every method first checks `DbWrapper.Connected`. If `false`, the method returns early *without* executing any DB operation or raising an exception.
- **Stored Procedure Execution**: All methods use `CommandType.StoredProcedure` and call `DbWrapper.ProcessReturn(errorNumber, errorMessage)` after execution. This implies:
  - Stored procedures are expected to set `@errorNumber` and `@errorMessage` output parameters.
  - `DbWrapper.ProcessReturn(...)` likely throws or logs on non-zero `@errorNumber`.
- **Connection Disposal**: All `SqlCommand` objects are wrapped in `using` blocks, and `cmd.Connection.Dispose()` is called explicitly in `finally` blocks — ensuring connections are released even on failure.
- **Null Handling for Parameters**: Parameters with nullable types (e.g., `double?`) are passed directly as `Value = nullableValue`. ADO.NET treats `null` as SQL `NULL`, which is consistent with the stored procedure expectations (e.g., `@EventNumber` can be `null` in `ClearExistingDiagnosticsAllChannels`).
- **No Return of Output Values**: While `@new_id` and error parameters are declared and populated, only errors are processed via `DbWrapper.ProcessReturn(...)`. The `@new_id` values are *not* exposed to callers.

---

### 4. **Dependencies**

#### **Internal Dependencies**
- `DASFactoryDb.Diagnostics.Diagnostics` depends on:
  - `DbWrapper` (static class, not shown here) — provides:
    - `Connected` property
    - `GetDASFactoryCommand()` method (returns `SqlCommand`)
    - `ProcessReturn(SqlParameter errorNumber, SqlParameter errorMessage)` method
- `System.Data`, `System.Data.SqlClient` — standard ADO.NET types.

#### **External Dependencies**
- **Database**:
  - Stored procedures:
    - `sp_DiagnosticActionsClear`
    - `sp_DiagnosticsActionsInsert`
    - `sp_DiagnosticsResultsClear`
    - `sp_DiagnosticsResultsAnalogInsert`
    - `sp_DiagnosticsResultsSquibInsert`
    - `sp_DiagnosticsResultsDigitalInsert`
  - Tables implied by the procedures (not visible in source).
- **Assumed Schema**:
  - Tables likely include `IDASCommunicationRecordId`, `DASChannelNumber`, `EventNumber` as composite keys or foreign keys.
  - Analog/digital/squib results stored in separate tables (based on procedure names).

#### **Dependents**
- Unknown — not visible in this file. Likely consumed by higher-level diagnostic orchestration or test execution modules.

---

### 5. **Gotchas**

- **Silent Failures on Disconnected State**: If `DbWrapper.Connected` is `false`, *all* methods return immediately with no indication of failure (no exception, no log). This may mask configuration or runtime issues.
- **Missing Return of Inserted IDs**: The `@new_id` output parameter is declared and populated by the stored procedure but *never returned* to the caller. Callers cannot reference newly inserted records.
- **Squib Data Null Guard is Incomplete**: While `squibFireCurrentData == null` triggers early return, `squibFireVoltageData` or `squibFireTimeAxis` being `null` would cause a `NullReferenceException` in the `foreach` loop. This is inconsistent and risky.
- **Typo in Parameter Name**: In `InsertAnalogDiagnosticResult`, the parameter `@AutoZeroPercentDeviation ` has a trailing space in the name (`"AutoZeroPercentDeviation "`), which may cause a mismatch with the stored procedure definition if not also defined with a trailing space.
- **No Validation on Channel/Event Numbers**: No checks for negative or out-of-range `dasChannelNumber` or `eventNumber`. Relies on DB constraints or stored procedure logic.
- **Binary Data Conversion**: `double[]` → `byte[]` conversion assumes little-endian architecture (standard on .NET on Windows), but may differ on other platforms (though DAS systems are typically Windows-based).
- **Ambiguous Channel Numbering**: Source does not clarify whether `dasChannelNumber` is 0-based or 1-based — critical for correct usage.

> **None identified from source alone** for other potential issues (e.g., transactional consistency, concurrency, error logging behavior beyond `ProcessReturn`).
init 2026-04-17 14:55:32 -04:00			`---`
			`source_files:`
			`- DataPRO/DASFactoryDb/Diagnostics/Diagnostics.cs`
			`generated_at: "2026-04-16T03:52:56.599244+00:00"`
			`model: "Qwen/Qwen3-Coder-Next-FP8"`
			`schema_version: 1`
			`sha256: "435708341e9b9055"`
			`---`

			`# Diagnostics`

			## Documentation: `DASFactoryDb.Diagnostics.Diagnostics` Module

			`---`

			`### 1. Purpose`

			This module provides a set of static methods to interact with diagnostic-related database operations for DAS (Data Acquisition System) communication records. It serves as the primary interface for inserting, clearing, and managing diagnostic actions (configured test parameters) and diagnostic results (observed test outcomes) across channels and events. The module abstracts low-level ADO.NET database calls into higher-level operations, delegating actual data persistence to stored procedures in the DASFactory database.

			`---`

			`### 2. Public Interface`

			All methods are `public static` and reside in the `DASFactoryDb.Diagnostics.Diagnostics` class.

			#### `ClearDiagnosticActionsAllChannels(int idasRecordId)`
			- Behavior: Clears all diagnostic action configurations for all channels associated with the given `idasRecordId`. Uses the stored procedure `sp_DiagnosticActionsClear`.
			`- Parameters:`
			- `idasRecordId`: ID of the DAS communication record to clear actions for.
			- Note: Passes `null` for `@DASChannelNumber` to indicate “all channels”.

			#### `InsertDiagnosticAction(...)`
			- Behavior: Inserts a new diagnostic action configuration for a specific DAS channel. Uses the stored procedure `sp_DiagnosticsActionsInsert`.
			`- Parameters:`
			- `dasRecordId`: ID of the DAS communication record.
			- `dasChannelNumber`: Channel number (0-based or 1-based? — not specified in source).
			- Boolean flags indicating which diagnostic tests to perform (e.g., `measureExcitation`, `measureOffset`, `squibFireCheck`, etc.).
			- Returns: Output parameter `@new_id` (ID of inserted record) is captured but not returned by this method.

			#### `ClearExistingDiagnosticsAllChannels(int idasRecordId = -1)`
			- Behavior: Clears all diagnostic results for a given DAS communication record (or all records if `idasRecordId == -1`). Uses the stored procedure `sp_DiagnosticsResultsClear`.
			`- Parameters:`
			- `idasRecordId`: Optional; defaults to `-1` (clear all records). If non-negative, clears only for that record.
			- Note: Passes `null` for both `@DASChannelNumber` and `@EventNumber`, indicating “all channels and events”.

			#### `InsertAnalogDiagnosticResult(...)`
			- Behavior: Inserts a full analog diagnostic result record for a specific channel and event. Uses the stored procedure `sp_DiagnosticsResultsAnalogInsert`.
			`- Parameters:`
			- `iDASRecordId`, `dasChannelNumber`, `eventNumber`: Identifiers for the diagnostic result context.
			- Numerous `double`, `short?`, `bool?` parameters representing measured/calculated values (e.g., excitation, offset, noise, gain, shunt deflection, bridge resistance).
			- Returns: Output parameter `@new_id` is captured but not returned.

			#### `InsertSquibDiagnosticResult(...)`
			- Behavior: Inserts a squib (pyro) fire diagnostic result, including raw time-series data (current, voltage, time axis) as binary blobs. Uses the stored procedure `sp_DiagnosticsResultsSquibInsert`.
			`- Parameters:`
			- `iDASRecordId`, `dasChannelNumber`, `eventNumber`: Identifiers.
			- `squibFireCurrentData`, `squibFireVoltageData`, `squibFireTimeAxis`: Arrays of `double` representing raw waveform data.
			- Optional metrics: `measuredDurationMS`, `measuredDelayMS`, pass/fail flags.
			- Calibration/scaling parameters: `squibThreshold`, `squibVoltageScaler`, `squibCurrentScaler`.
			`- Special Behavior:`
			- Early return if `squibFireCurrentData == null` (prevents exception in `BitConverter.GetBytes`).
			- Converts `double[]` arrays to `byte[]` via `BitConverter.GetBytes` before storing in `VARBINARY` parameters.

			#### `InsertDigitalDiagnosticResult(...)`
			- Behavior: Inserts a digital diagnostic result (e.g., for digital input state verification). Uses the stored procedure `sp_DiagnosticsResultsDigitalInsert`.
			`- Parameters:`
			- `iDASRecordId`, `dasChannelNumber`, `eventNumber`: Identifiers.
			- `digitalInputActiveState`: Boolean indicating whether the digital input was in its active state.

			`---`

			`### 3. Invariants`

			- Database Connection Check: Every method first checks `DbWrapper.Connected`. If `false`, the method returns early without executing any DB operation or raising an exception.
			- Stored Procedure Execution: All methods use `CommandType.StoredProcedure` and call `DbWrapper.ProcessReturn(errorNumber, errorMessage)` after execution. This implies:
			- Stored procedures are expected to set `@errorNumber` and `@errorMessage` output parameters.
			- `DbWrapper.ProcessReturn(...)` likely throws or logs on non-zero `@errorNumber`.
			- Connection Disposal: All `SqlCommand` objects are wrapped in `using` blocks, and `cmd.Connection.Dispose()` is called explicitly in `finally` blocks — ensuring connections are released even on failure.
			- Null Handling for Parameters: Parameters with nullable types (e.g., `double?`) are passed directly as `Value = nullableValue`. ADO.NET treats `null` as SQL `NULL`, which is consistent with the stored procedure expectations (e.g., `@EventNumber` can be `null` in `ClearExistingDiagnosticsAllChannels`).
			- No Return of Output Values: While `@new_id` and error parameters are declared and populated, only errors are processed via `DbWrapper.ProcessReturn(...)`. The `@new_id` values are not exposed to callers.

			`---`

			`### 4. Dependencies`

			`#### Internal Dependencies`
			- `DASFactoryDb.Diagnostics.Diagnostics` depends on:
			- `DbWrapper` (static class, not shown here) — provides:
			- `Connected` property
			- `GetDASFactoryCommand()` method (returns `SqlCommand`)
			- `ProcessReturn(SqlParameter errorNumber, SqlParameter errorMessage)` method
			- `System.Data`, `System.Data.SqlClient` — standard ADO.NET types.

			`#### External Dependencies`
			`- Database:`
			`- Stored procedures:`
			- `sp_DiagnosticActionsClear`
			- `sp_DiagnosticsActionsInsert`
			- `sp_DiagnosticsResultsClear`
			- `sp_DiagnosticsResultsAnalogInsert`
			- `sp_DiagnosticsResultsSquibInsert`
			- `sp_DiagnosticsResultsDigitalInsert`
			`- Tables implied by the procedures (not visible in source).`
			`- Assumed Schema:`
			- Tables likely include `IDASCommunicationRecordId`, `DASChannelNumber`, `EventNumber` as composite keys or foreign keys.
			`- Analog/digital/squib results stored in separate tables (based on procedure names).`

			`#### Dependents`
			`- Unknown — not visible in this file. Likely consumed by higher-level diagnostic orchestration or test execution modules.`

			`---`

			`### 5. Gotchas`

			- Silent Failures on Disconnected State: If `DbWrapper.Connected` is `false`, all methods return immediately with no indication of failure (no exception, no log). This may mask configuration or runtime issues.
			- Missing Return of Inserted IDs: The `@new_id` output parameter is declared and populated by the stored procedure but never returned to the caller. Callers cannot reference newly inserted records.
			- Squib Data Null Guard is Incomplete: While `squibFireCurrentData == null` triggers early return, `squibFireVoltageData` or `squibFireTimeAxis` being `null` would cause a `NullReferenceException` in the `foreach` loop. This is inconsistent and risky.
			- Typo in Parameter Name: In `InsertAnalogDiagnosticResult`, the parameter `@AutoZeroPercentDeviation ` has a trailing space in the name (`"AutoZeroPercentDeviation "`), which may cause a mismatch with the stored procedure definition if not also defined with a trailing space.
			- No Validation on Channel/Event Numbers: No checks for negative or out-of-range `dasChannelNumber` or `eventNumber`. Relies on DB constraints or stored procedure logic.
			- Binary Data Conversion: `double[]` → `byte[]` conversion assumes little-endian architecture (standard on .NET on Windows), but may differ on other platforms (though DAS systems are typically Windows-based).
			- Ambiguous Channel Numbering: Source does not clarify whether `dasChannelNumber` is 0-based or 1-based — critical for correct usage.

			> None identified from source alone for other potential issues (e.g., transactional consistency, concurrency, error logging behavior beyond `ProcessReturn`).