DP44/enriched-qwen3-coder-next/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-16T04:25:47.865565+00:00	Qwen/Qwen3-Coder-Next-FP8	1	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.