98 lines
6.7 KiB
Markdown
98 lines
6.7 KiB
Markdown
---
|
|
source_files:
|
|
- DataPRO/DbAPI/DAS/IDataRecorders.cs
|
|
- DataPRO/DbAPI/DAS/DataRecorders.cs
|
|
generated_at: "2026-04-17T15:58:00.233947+00:00"
|
|
model: "zai-org/GLM-5-FP8"
|
|
schema_version: 1
|
|
sha256: "ebd38454d2f83c37"
|
|
---
|
|
|
|
# Documentation: DataRecorders Module
|
|
|
|
## 1. Purpose
|
|
|
|
This module provides the database abstraction layer for Data Acquisition System (DAS) hardware management within the DataPRO system. It implements CRUD operations for DAS devices and their associated channels through the `IDataRecorders` interface. The module handles persistence of DAS metadata, channel configurations, and parent-child relationships between encapsulated/compacted DAS units, serving as the bridge between the application layer and SQL stored procedures.
|
|
|
|
---
|
|
|
|
## 2. Public Interface
|
|
|
|
### Interface: `IDataRecorders` (namespace: `DbAPI.DAS`)
|
|
|
|
#### `ulong DASChannelsDelete(IUserDbRecord user, IConnectionDetails connection, string hardwareId)`
|
|
Deletes all channels associated with a specific DAS hardware identifier. Returns `0` on success, non-zero error code on failure.
|
|
|
|
#### `ulong DASChannelsInsert(IUserDbRecord user, IConnectionDetails connection, string hardwareId, ref IDASChannelDBRecord record)`
|
|
Inserts a DAS channel record into the database. The `record` parameter is passed by reference and is modified to include the newly assigned `DaschannelId` after successful insert. Returns `0` on success.
|
|
|
|
#### `ulong DASChannelsGet(IUserDbRecord user, IConnectionDetails connection, string HardwareId, out IDASChannelDBRecord[] channels)`
|
|
Retrieves DAS channel records for a given hardware ID. Pass `null` for `HardwareId` to retrieve all channel records. Returns `0` on success; `channels` array is populated with results.
|
|
|
|
#### `ulong DASChildrenGet(IUserDbRecord user, IConnectionDetails connection, string dasSerialNumber, out string[] childrenSerialNumbers)`
|
|
Retrieves serial numbers of child DAS units associated with a parent DAS (used for encapsulated/compacted DAS configurations). Returns `0` on success.
|
|
|
|
#### `ulong DASDelete(IUserDbRecord user, IConnectionDetails connection, int DASId, string serialNumber, bool embedded)`
|
|
Deletes a DAS record from the database. Either `DASId` or `serialNumber` must be provided. Cascading behavior includes removal from test setups, channel assignments, and associated metadata. Returns `0` on success.
|
|
|
|
#### `ulong DASGet(IUserDbRecord user, IConnectionDetails connection, int clientDbVersion, string DASSerial, string position, out IDASDBRecord[] das)`
|
|
Retrieves DAS records matching the specified criteria. Pass `null` for both `DASSerial` and `position` to retrieve all DAS records. Returns `0` on success; `das` array may be null or empty.
|
|
|
|
#### `ulong DASInsert(IUserDbRecord user, IConnectionDetails connection, IDASDBRecord das)`
|
|
Inserts a new DAS record. The `das.DASId` property is updated with the newly assigned database ID after successful insert. Returns `0` on success.
|
|
|
|
#### `ulong DASUpdate(IUserDbRecord user, IConnectionDetails connection, IDASDBRecord das)`
|
|
Updates an existing DAS record in the database. Returns `0` on success.
|
|
|
|
---
|
|
|
|
## 3. Invariants
|
|
|
|
- **Authentication Required**: All methods require a valid logged-in user via `DbAPI.Connections.IsUserLoggedIn(user, connection)`. Failure returns `ErrorCodes.ERROR_ACCESS_DENIED`.
|
|
- **Return Code Convention**: All methods return `ulong` where `0` (`ErrorCodes.ERROR_SUCCESS`) indicates success; all other values indicate errors.
|
|
- **Stored Procedure Usage**: All database operations are performed via SQL stored procedures (`sp_DASChannelsDelete`, `sp_DASChannelsInsert`, `sp_DASChannelsGet`, `sp_DASChildrenGet`, `sp_DASDelete`, `sp_DASGet`, `sp_DASInsert`, `sp_DASUpdate`).
|
|
- **Connection Cleanup**: All methods dispose of the SQL connection in a `finally` block via `cmd.Connection.Dispose()`.
|
|
- **Parameter Validation**:
|
|
- `DASChannelsInsert`: `record` cannot be null; `hardwareId` cannot be null or whitespace.
|
|
- `DASDelete`: Either `DASId > 0` or `serialNumber` must be non-empty.
|
|
- `DASInsert`: `das` cannot be null.
|
|
- **Side Effects on Insert**: Both `DASChannelsInsert` and `DASInsert` modify the input record's ID field (`DaschannelId` and `DASId` respectively) upon successful insertion.
|
|
- **StandIn Logic**: For `DASInsert` and `DASUpdate`, `TestId` and `GroupId` parameters are only set if `das.StandIn` is `true`.
|
|
|
|
---
|
|
|
|
## 4. Dependencies
|
|
|
|
### This Module Depends On:
|
|
- `DbAPI.Connections` - For `IConnectionDetails`, `IsUserLoggedIn()`, `ConnectionManager.GetSqlCommand()`
|
|
- `DbAPI.User` - For `IUserDbRecord`
|
|
- `DbAPI.Errors` - For `ErrorCodes` constants
|
|
- `DbAPI.Logging` - For `LogManager`
|
|
- `DbAPI.Database` - For `Database.PrepareForDbAccess()` (used in `DASGet`)
|
|
- `DTS.Common.Interface.Database` - For `IDASChannelDBRecord`, `IDASDBRecord`
|
|
- `DTS.Common.Interface.DataRecorders` - Referenced in interface
|
|
- `DTS.Common.Classes` - For `DASChannelDBRecord`, `DASDBRecord`, `DFConstantsAndEnums.FIRST_USE_DATE_NOT_SET`
|
|
- `DTS.Common.Enums.Hardware` - For `HardwareTypes.SLICE6_AIR_TC`
|
|
- `DTS.Common.Constants` - For `SLICE_TC_DB_VERSION`
|
|
- `System.Data.SqlClient` - For ADO.NET SQL client types
|
|
|
|
### Consumers:
|
|
- Unclear from source alone. The `DataRecorders` class is `internal`, suggesting it is consumed by other classes within the `DbAPI.DAS` namespace or via dependency injection through the `IDataRecorders` interface.
|
|
|
|
---
|
|
|
|
## 5. Gotchas
|
|
|
|
1. **Inconsistent Command Preparation**: `DASGet` uses `Database.Database.PrepareForDbAccess()` while all other methods use `ConnectionManager.GetSqlCommand()`. The reason for this difference is unclear from source alone.
|
|
|
|
2. **Debug Code Left In**: `DASDelete` contains `Console.WriteLine` statements (lines ~226 and ~248) that appear to be debug artifacts.
|
|
|
|
3. **Exception Handling Inconsistency**: `DASUpdate` and `DASInsert` throw an exception when the stored procedure returns a non-zero error number, whereas other methods log and return `ERROR_UNKNOWN` without throwing.
|
|
|
|
4. **Hardware Version Check**: `DASInsert` contains special-case logic for `HardwareTypes.SLICE6_AIR_TC` that checks database version compatibility against `DTS.Common.Constants.SLICE_TC_DB_VERSION`. Other hardware types do not have this check.
|
|
|
|
5. **Typo in Interface**: The `DASChannelsGet` interface declaration has a parameter named `connetion` (misspelled), though the implementation correctly uses `connection`.
|
|
|
|
6. **Output Array Initialization**: `DASChannelsGet` and `DASChildrenGet` initialize their output arrays to empty arrays (`new IDASChannelDBRecord[0]` and `new string[0]`) before the login check, meaning access-denied failures still return valid empty arrays rather than null.
|
|
|
|
7. **DASUpdate Overwrites DASId**: The `DASUpdate` method sets `das.DASId` from the `@new_id` output parameter, which may be unexpected for an update operation. |