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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
DataPRO/DASFactoryDb/Diagnostics/Diagnostics.cs	2026-04-16T03:52:56.599244+00:00	Qwen/Qwen3-Coder-Next-FP8	1	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).