--- 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`).