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