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

---
source_files:
  - DataPRO/DASFactoryDb/Download/Download.cs
generated_at: "2026-04-16T03:52:56.569022+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "8f2bca6182f06470"
---

# 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.  
  ```csharp
  // 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.