DP44/docs/ai/DataPRO/DbAPI/DAS.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
DataPRO/DbAPI/DAS/IDataRecorders.cs DataPRO/DbAPI/DAS/DataRecorders.cs	2026-04-17T15:58:00.233947+00:00	zai-org/GLM-5-FP8	1	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.