Documentation: `DASFactoryDb.Download.Download` Module

1. Purpose

This module provides a set of static methods for managing event-related data in the DAS (Distributed Acoustic Sensing) factory database. Its primary role is to clear or insert records related to event downloads, arm attempts, fault flags, event metadata, GUIDs, and download requests—all scoped to a specific IDASCommunicationRecordId. It acts as a database abstraction layer, encapsulating calls to stored procedures for data integrity and separation of concerns, and ensures that operations are only executed when the database connection is active.

2. Public Interface

All methods are public static and belong to the DASFactoryDb.Download.Download class.

Clearing Methods (all return `void`, accept `int idasRecordId`)

Method	Signature	Behavior
`ClearExistingEventDownloadStatus`	`public static void ClearExistingEventDownloadStatus(int idasRecordId)`	Clears all existing download status entries for the given DAS communication record. Calls `sp_EventDownloadStatusClear`.
`ClearExistingEventArmAttempts`	`public static void ClearExistingEventArmAttempts(int idasRecordId)`	Clears all arm attempt records for the given DAS communication record. Calls `sp_EventArmAttemptsClear`.
`ClearExistingFaultFlags`	`public static void ClearExistingFaultFlags(int idasRecordId)`	Clears all fault flags for the given DAS communication record. Calls `sp_EventFaultFlagsClear`.
`ClearExistingDownloadReports`	`public static void ClearExistingDownloadReports(int idasRecordId)`	Clears all download report entries for the given DAS communication record. Calls `sp_DownloadReportClear`.
`ClearExistingEventGuids`	`public static void ClearExistingEventGuids(int idasRecordId)`	Clears all event GUIDs for the given DAS communication record. Calls `sp_EventGuidsClear`.
`ClearExistingDownloadRequests`	`public static void ClearExistingDownloadRequests(int idasRecordId)`	Clears all download request entries for the given DAS communication record. Calls `sp_DownloadRequestsClear`.
`ClearExistingUARTDownloadRequests`	`public static void ClearExistingUARTDownloadRequests(int idasRecordId)`	Clears all UART-specific download request entries for the given DAS communication record. Calls `sp_UARTDownloadRequestsClear`.

Insertion Methods (all return `void`, accept `idasRecordId` + event-specific parameters)

Method	Signature	Behavior
`InsertEventFaultFlags`	`public static void InsertEventFaultFlags(int iDASRecordId, ushort faultFlag)`	Inserts a single fault flag for the given DAS record. Calls `sp_EventFaultFlagsInsert`. Returns `@new_Id` output parameter (not exposed).
`InsertEventArmAttempts`	`public static void InsertEventArmAttempts(int iDASRecordId, int armAttempts)`	Inserts arm attempt count for the given DAS record. Calls `sp_EventArmAttemptsInsert`. Returns `@new_id` output parameter (not exposed).
`InsertEventInfo`	`public static void InsertEventInfo(int iDASRecordId, int eventNumber, Guid testGUID, ushort faultFlags, int armAttempts, DateTime testTime, string testID, string description, bool hasBeenDownloaded, bool wasTriggered, string xml)`	Inserts core event metadata. Calls `sp_EventInfoInsert`. `testTime` is normalized to `SqlDateTime.MinValue` if `DateTime.MinValue`. `testGUID` is uppercased before insertion. `xml` is UTF-8 encoded and stored as `VarBinary`. Returns `@new_id`.
`InsertEventDownloadStatus`	`public static void InsertEventDownloadStatus(int iDASRecordId, bool downloadStatus)`	Inserts download status (`Downloaded` flag) for the given DAS record. Calls `sp_EventDownloadStatusInsert`. Returns `@new_id`.
`DownloadRequestInsert`	`public static void DownloadRequestInsert(int iDASRecordId, ushort eventNumber, int dasChannelNumber, ulong startSample, ulong endSample, ulong samplesToSkip, double startRecordTimeStampSec, double triggerTimeStampSec, double startRecordTimeStampNanoSec, double triggerTimestampNanoSec, bool PTPMasterSync)`	Inserts a standard (likely Ethernet-based) download request. Calls `sp_DownloadRequestsInsert`. Note: `@StartRecordTimestampNanoSec` parameter is incorrectly assigned `startRecordTimeStampSec` instead of `startRecordTimeStampNanoSec` (see Gotchas).
`UARTDownloadRequestInsert`	`public static void UARTDownloadRequestInsert(int iDASRecordId, ushort eventNumber, ulong totalByteCount, ulong triggerByteCount, ulong faultByteCount, ulong startTimestamp, ulong endTimestamp, int baudRate)`	Inserts a UART-specific download request. Calls `sp_UARTDownloadRequestsInsert`.
`EventGuidInsert`	`public static void EventGuidInsert(int iDASRecordId, Guid guid)`	Inserts a single event GUID for the given DAS record. Calls `sp_EventGuidsInsert`. `guid.ToString().ToUpper()` is used. Returns `@new_Id`.

Note on Output Parameters: All insertion methods declare output parameters (@errorNumber, @errorMessage, @new_id/@new_Id) and call DbWrapper.ProcessReturn(errorNumber, errorMessage) except InsertEventFaultFlags, which does not call DbWrapper.ProcessReturn. This is inconsistent and may lead to unhandled errors.

3. Invariants

Database Connection Check: Every method first checks if (!DbWrapper.Connected) { return; }. No operation proceeds if the database is not connected.
Stored Procedure Execution: All methods use CommandType.StoredProcedure and execute via cmd.ExecuteNonQuery().
Connection Disposal: Each method disposes the command connection in a finally block (cmd.Connection.Dispose()), ensuring cleanup even on exceptions.
Parameter Naming Consistency: Stored procedure parameters consistently use @IDASCommunicationRecordId, @errorNumber, @errorMessage, and @new_id/@new_Id.
GUID Normalization: GUIDs passed to InsertEventInfo and EventGuidInsert are uppercased via .ToString().ToUpper().
DateTime Normalization: testTime == DateTime.MinValue is converted to SqlDateTime.MinValue before insertion in InsertEventInfo.
XML Encoding: The xml parameter in InsertEventInfo is UTF-8 encoded before being passed as VarBinary.

4. Dependencies

Internal Dependencies

DASFactoryDb.Download.Download depends on:
- DbWrapper (static class, not shown in source) — provides Connected, GetDASFactoryCommand(), and ProcessReturn() methods.
- Standard .NET libraries: System.Data, System.Data.SqlClient, System.IO, System.Text, System.Xml.

External Dependencies

SQL Server Database — requires the following stored procedures to exist:
- sp_EventDownloadStatusClear
- sp_EventArmAttemptsClear
- sp_EventFaultFlagsClear
- sp_DownloadReportClear
- sp_EventGuidsClear
- sp_DownloadRequestsClear
- sp_EventFaultFlagsInsert
- sp_EventArmAttemptsInsert
- sp_EventInfoInsert
- sp_EventDownloadStatusInsert
- sp_DownloadRequestsInsert
- sp_UARTDownloadRequestsInsert
- sp_UARTDownloadRequestsClear
- sp_EventGuidsInsert
Database Schema — expects tables/columns compatible with the above stored procedures.

Who Depends on This Module?

Any code that needs to manage DAS event data in the database (e.g., event processing pipelines, download initiators, fault handlers). Not specified in source.

5. Gotchas

Parameter Mismatch in DownloadRequestInsert:
The parameter @StartRecordTimestampNanoSec is assigned startRecordTimeStampSec instead of startRecordTimeStampNanoSec. This is likely a copy-paste error and will cause incorrect timestamp data to be stored.
```
// Current (incorrect):
new SqlParameter("@StartRecordTimestampNanoSec", SqlDbType.Decimal)
  { Value = startRecordTimeStampSec }); // ← should be startRecordTimeStampNanoSec
```
Inconsistent Error Handling:
InsertEventFaultFlags does not call DbWrapper.ProcessReturn(errorNumber, errorMessage), while all other insertion methods do. This may result in unhandled database errors (e.g., constraint violations, stored procedure errors) going silently unnoticed.
No Return of Output Values:
Although all methods declare and populate @new_id/@new_Id output parameters, none expose them to callers. If the new record ID is needed, callers must refactor the method or access it via cmd.Parameters["@new_id"].Value after execution (not possible here due to static encapsulation).
Silent Failures on Disconnection:
Methods return early if !DbWrapper.Connected, but no logging or exception occurs. Callers may assume success even when no operation was performed.
No Input Validation:
Methods do not validate input parameters (e.g., idasRecordId is not checked for negative values). Assumed valid by downstream stored procedures.
Case Sensitivity of GUIDs:
GUIDs are uppercased before insertion. If the database or downstream consumers expect lowercase or canonical format, mismatches may occur.
No Transaction Support:
Each method executes in its own implicit transaction (default ADO.NET behavior). If callers need atomicity across multiple operations (e.g., clear + insert), they must manage transactions externally.
String Length Assumptions:
Parameters like @errorMessage are declared with SqlDbType.NVarChar, 255. If stored procedures return longer messages, truncation may occur silently.
Missing using for SqlParameter:
Parameters are not wrapped in using blocks. While not strictly necessary (they’re not IDisposable), it’s inconsistent with best practices and may raise static analysis warnings.

None identified beyond the above.

9.8 KiB Raw Blame History Unescape Escape

Documentation: DASFactoryDb.Download.Download Module