120 lines
8.8 KiB
Markdown
120 lines
8.8 KiB
Markdown
---
|
|
source_files:
|
|
- DataPRO/DbAPI/DAS/IDataRecorders.cs
|
|
- DataPRO/DbAPI/DAS/DataRecorders.cs
|
|
generated_at: "2026-04-16T04:25:47.865565+00:00"
|
|
model: "Qwen/Qwen3-Coder-Next-FP8"
|
|
schema_version: 1
|
|
sha256: "6d8f47b7e121e9aa"
|
|
---
|
|
|
|
# Documentation: `IDataRecorders` Interface and `DataRecorders` Implementation
|
|
|
|
## 1. Purpose
|
|
|
|
This module provides data access service (DAS) functions for managing data recorders (DAS units) and their associated channels in the database. It serves as the persistence layer for DAS-related operations—including CRUD (Create, Read, Update, Delete), channel management, and hierarchical relationships (e.g., parent/child encapsulated DAS). The interface `IDataRecorders` defines the contract, while the internal class `DataRecorders` implements it using SQL Server stored procedures and ADO.NET. It enforces user authentication, logs errors, and ensures database version compatibility for certain DAS types (e.g., SLICE6_AIR_TC).
|
|
|
|
## 2. Public Interface
|
|
|
|
The interface `IDataRecorders` defines the following public methods:
|
|
|
|
### `ulong DASChannelsDelete(IUserDbRecord user, IConnectionDetails connection, string hardwareId)`
|
|
- **Behavior**: Deletes all DAS channel records associated with the given `hardwareId` (format: `SerialNumber_DASType`).
|
|
- **Returns**: `ERROR_SUCCESS` (0) on success; otherwise, an error code (e.g., `ERROR_ACCESS_DENIED`, `ERROR_UNKNOWN`).
|
|
- **Note**: Does *not* delete the DAS record itself—only its channels.
|
|
|
|
### `ulong DASChannelsInsert(IUserDbRecord user, IConnectionDetails connection, string hardwareId, ref IDASChannelDBRecord record)`
|
|
- **Behavior**: Inserts a new DAS channel record into the database. On success, populates `record.DaschannelId` with the new database ID.
|
|
- **Returns**: `ERROR_SUCCESS` (0) on success; `ERROR_MISSING_PARAMETER` if `record` or `hardwareId` is null/empty; `ERROR_ACCESS_DENIED` if user not logged in; `ERROR_UNKNOWN` on failure.
|
|
- **Note**: Modifies the `record` parameter *by reference* to update the `DaschannelId`.
|
|
|
|
### `ulong DASChannelsGet(IUserDbRecord user, IConnectionDetails connection, string hardwareId, out IDASChannelDBRecord[] channels)`
|
|
- **Behavior**: Retrieves all DAS channel records for the given `hardwareId`. If `hardwareId` is `null`, returns *all* DAS channel records.
|
|
- **Returns**: `ERROR_SUCCESS` (0) on success; `ERROR_ACCESS_DENIED` if user not logged in; `ERROR_UNKNOWN` on failure.
|
|
- **Output**: `channels` is always initialized to an array (possibly empty) on return.
|
|
|
|
### `ulong DASChildrenGet(IUserDbRecord user, IConnectionDetails connection, string dasSerialNumber, out string[] childrenSerialNumbers)`
|
|
- **Behavior**: Retrieves serial numbers of all child DAS units associated with the given parent `dasSerialNumber`. Used for encapsulated/compacted DAS discovery.
|
|
- **Returns**: `ERROR_SUCCESS` (0) on success; `ERROR_ACCESS_DENIED` if user not logged in; `ERROR_UNKNOWN` on failure.
|
|
- **Output**: `childrenSerialNumbers` is always initialized to an array (possibly empty) on return.
|
|
|
|
### `ulong DASDelete(IUserDbRecord user, IConnectionDetails connection, int DASId, string serialNumber, bool embedded)`
|
|
- **Behavior**: Deletes a DAS record from the database. Requires *either* `DASId > 0` *or* non-null/non-empty `serialNumber`.
|
|
- Removes associated test setup entries.
|
|
- Removes channel assignments (and channels if not `embedded`).
|
|
- Deletes DAS channels and metadata.
|
|
- **Returns**: `ERROR_SUCCESS` (0) on success; `ERROR_MISSING_PARAMETER` if both `DASId ≤ 0` and `serialNumber` is null/empty; `ERROR_ACCESS_DENIED` if user not logged in; `ERROR_UNKNOWN` on failure.
|
|
|
|
### `ulong DASGet(IUserDbRecord user, IConnectionDetails connection, int clientDbVersion, string DASSerial, string position, out IDASDBRecord[] das)`
|
|
- **Behavior**: Retrieves DAS records matching the search criteria.
|
|
- If both `DASSerial` and `DASId` are omitted (via `null`/empty), returns *all* DAS records.
|
|
- Does *not* enforce user permission checks (only login status).
|
|
- **Returns**: `ERROR_SUCCESS` (0) on success; `ERROR_ACCESS_DENIED` if user not logged in; `ERROR_UNKNOWN` on failure.
|
|
- **Output**: `das` may be `null` or an empty array on success.
|
|
|
|
### `ulong DASInsert(IUserDbRecord user, IConnectionDetails connection, IDASDBRecord das)`
|
|
- **Behavior**: Inserts a new DAS record into the database. On success, populates `das.DASId` with the new database ID.
|
|
- **Returns**: `ERROR_SUCCESS` (0) on success; `ERROR_MISSING_PARAMETER` if `das` is `null`; `ERROR_ACCESS_DENIED` if user not logged in; `ERROR_UNKNOWN` on failure or version mismatch.
|
|
- **Special Behavior**: For `DASType == SLICE6_AIR_TC`, verifies `serverDbVersion >= SLICE_TC_DB_VERSION`; otherwise, returns `ERROR_UNKNOWN`.
|
|
|
|
### `ulong DASUpdate(IUserDbRecord user, IConnectionDetails connection, IDASDBRecord das)`
|
|
- **Behavior**: Updates an existing DAS record in the database.
|
|
- **Returns**: `ERROR_SUCCESS` (0) on success; `ERROR_ACCESS_DENIED` if user not logged in; `ERROR_UNKNOWN` on failure.
|
|
- **Note**: Does *not* validate presence of `DASId`; relies on stored procedure logic to locate the record.
|
|
|
|
---
|
|
|
|
## 3. Invariants
|
|
|
|
- **User Authentication**: All methods require the user to be logged in (checked via `IsUserLoggedIn(user, connection)`). Failure returns `ERROR_ACCESS_DENIED`.
|
|
- **Parameter Validation**:
|
|
- `DASChannelsInsert`: Fails early if `record == null` or `hardwareId` is null/empty/whitespace.
|
|
- `DASDelete`: Requires at least one of `DASId > 0` or non-empty `serialNumber`.
|
|
- `DASInsert`: Fails early if `das == null`.
|
|
- **Database Version Compatibility**: For `SLICE6_AIR_TC` DAS types, insertion is blocked if `serverDbVersion < SLICE_TC_DB_VERSION`.
|
|
- **Output Initialization**: All `out` array parameters (`channels`, `childrenSerialNumbers`, `das`) are initialized to a non-null array (possibly empty) before returning.
|
|
- **Resource Cleanup**: All database connections (`cmd.Connection`) are disposed in `finally` blocks.
|
|
- **Error Reporting**: SQL stored procedure errors are logged via `LogManager`, and the method returns `ERROR_UNKNOWN` (not the raw DB error code).
|
|
|
|
---
|
|
|
|
## 4. Dependencies
|
|
|
|
### Module Dependencies
|
|
- **Imports/Usings**:
|
|
- `DbAPI.Connections` (for `IsUserLoggedIn`, `ConnectionManager`, `GetDatabaseVersion`)
|
|
- `DbAPI.Errors` (for `ErrorCodes`)
|
|
- `DbAPI.Logging` (for `LogManager`)
|
|
- `DTS.Common.Interface.DataRecorders` (for `IDASChannelDBRecord`, `IDASDBRecord`)
|
|
- `DTS.Common.Interface.Database` (for `IUserDbRecord`, `IConnectionDetails`)
|
|
- `DTS.Common.Classes`, `DTS.Common.Enums.*` (for types like `HardwareTypes`, `DFConstantsAndEnums`)
|
|
- `System.Data`, `System.Data.SqlClient` (ADO.NET types)
|
|
|
|
### External Dependencies
|
|
- **Database**: Requires SQL Server with the following stored procedures:
|
|
- `sp_DASChannelsDelete`
|
|
- `sp_DASChannelsInsert`
|
|
- `sp_DASChannelsGet`
|
|
- `sp_DASChildrenGet`
|
|
- `sp_DASDelete`
|
|
- `sp_DASGet`
|
|
- `sp_DASInsert`
|
|
- `sp_DASUpdate`
|
|
- **Database Version**: Must support `SLICE_TC_DB_VERSION` constant for `SLICE6_AIR_TC` DAS types.
|
|
|
|
### Depended Upon
|
|
- **Consumers**: Other modules in `DbAPI.DAS` (e.g., higher-level services or UI layers) that need DAS CRUD operations.
|
|
|
|
---
|
|
|
|
## 5. Gotchas
|
|
|
|
- **Parameter Name Typo**: In `DASChannelsGet`, the parameter `connetion` (missing 'c') is used instead of `connection`. This is consistent in both interface and implementation.
|
|
- **`DASUpdate` Does Not Validate `DASId`**: Unlike typical updates, `DASUpdate` does not require `das.DASId` to be set; it relies on the stored procedure to locate the record (likely via `SerialNumber` or other fields). This could cause unintended updates if `SerialNumber` is not unique or stable.
|
|
- **`DASInsert` Modifies Input Record**: The `das` parameter is mutated to include the new `DASId` on success. Callers must be aware of this side effect.
|
|
- **`DASChannelsInsert` Modifies Input Record**: Similarly, `record` is mutated to include `DaschannelId`.
|
|
- **`DASGet` Ignores `DASId` Parameter**: The interface declares `int DASId` but the implementation does *not* use it (see `DASGet` signature in `IDataRecorders.cs`). Only `DASSerial` and `position` are used. This is likely a legacy or incomplete parameter.
|
|
- **`DASDelete` Behavior with `embedded` Flag**: When `embedded == true`, channels are *not* deleted (only assignments are removed). When `embedded == false`, channels *are* deleted. This is critical for correct usage.
|
|
- **`DASInsert` Version Check is Hardcoded**: The version check for `SLICE6_AIR_TC` is hardcoded and does not use a configurable constant beyond `DTS.Common.Constants.SLICE_TC_DB_VERSION`. Ensure this constant is up-to-date.
|
|
- **No Transaction Handling**: Operations are executed individually (no explicit transaction scope), risking partial failures if multiple operations must succeed/fail together.
|
|
- **`Console.WriteLine` in Production Code**: `DataRecorders.cs` contains `Console.WriteLine` calls (e.g., in `DASDelete`), which may leak debug output in production. |