DP44/enriched-qwen3-coder-next/DataPRO/DbAPI/TestSetups.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
DataPRO/DbAPI/TestSetups/IGraphs.cs DataPRO/DbAPI/TestSetups/ICalculatedChannels.cs DataPRO/DbAPI/TestSetups/IRegionsOfInterest.cs DataPRO/DbAPI/TestSetups/ITestSetups.cs DataPRO/DbAPI/TestSetups/CalculatedChannels.cs DataPRO/DbAPI/TestSetups/Graphs.cs	2026-04-16T04:27:03.727990+00:00	Qwen/Qwen3-Coder-Next-FP8	1	7a6cc3dcbca85c45

Documentation: TestSetups Module (DbAPI)

1. Purpose

This module provides data access layer (DAL) interfaces and implementations for managing test setup–related entities in the database: graphs, calculated channels, regions of interest (ROIs), and test setups themselves (including hardware metadata and group associations). It acts as a bridge between higher-level application logic and SQL Server stored procedures, enforcing user authentication, validating input parameters, and translating database errors into standardized error codes. The module is part of the DbAPI.TestSetups namespace and is used to persist and retrieve configuration data for physical test setups (e.g., in data acquisition systems), supporting CRUD operations and domain-specific logic such as ROI generation defaults and test setup completeness flags.

2. Public Interface

All interfaces define public contracts; implementations are internal (CalculatedChannels, Graphs, RegionsOfInterest, TestSetups classes). Only interface methods are documented here.

IGraphs

• ulong GraphsGet(IUserDbRecord user, IConnectionDetails connection, int? graphId, int? testSetupId, out IGraphRecord[] records)
  Retrieves graph records matching optional graphId and testSetupId. Returns array of IGraphRecord.

  • graphId: specific graph ID (nullable); null means all graphs for given testSetupId.
  • testSetupId: required to filter graphs by test setup.

• ulong GraphsUpdate(IUserDbRecord user, IConnectionDetails connection, IGraphRecord record)
  Updates an existing graph record in the database.

  • Requires record.GraphId to be non-null and valid.

• ulong GraphsInsert(IUserDbRecord user, IConnectionDetails connection, ref IGraphRecord record)
  Inserts a new graph record. After successful insert, record.GraphId is updated with the database-generated ID.

• ulong GraphsDelete(IUserDbRecord user, IConnectionDetails connection, int graphId)
  Deletes the graph with the specified graphId.

ICalculatedChannels

• ulong CalculatedChannelsDelete(IUserDbRecord user, IConnectionDetails connection, int calculatedChannelId)
  Deletes the calculated channel with the specified calculatedChannelId.

• ulong CalculatedChannelsGet(IUserDbRecord user, IConnectionDetails connection, int? calculatedChannelId, string testSetupName, out ICalculatedChannelRecord[] records)
  Retrieves calculated channel records matching optional calculatedChannelId and testSetupName.

  • testSetupName may be empty string ("") to match no test setup.

• ulong CalculatedChannelsInsert(IUserDbRecord user, IConnectionDetails connection, ref ICalculatedChannelRecord record)
  Inserts a new calculated channel. After successful insert, record.Id is updated with the database-generated ID.

• ulong CalculatedChannelsUpdate(IUserDbRecord user, IConnectionDetails connection, ICalculatedChannelRecord record)
  Updates an existing calculated channel. Requires record.Id to be set.

IRegionsOfInterest

• ulong RegionsOfInterestDelete(IUserDbRecord user, IConnectionDetails connection, int testSetupId)
  Deletes all ROI records associated with the given testSetupId from both TestSetupROIs and ROIPeriodChannels tables.

• ulong RegionsOfInterestInsert(IUserDbRecord user, IConnectionDetails connection, int clientDbVersion, int testSetupId, IRegionOfInterest regionOfInterest)
  Inserts ROI data into TestSetupROIs and ROIPeriodChannels tables.

  • clientDbVersion: passed to stored procedure (likely for version-specific logic).

• ulong RegionsOfInterestGet(IUserDbRecord user, IConnectionDetails connection, int clientDbVersion, int testSetupId, out IRegionOfInterest[] records)
  Retrieves all ROI records for the given testSetupId, combining data from TestSetupROIs and ROIPeriodChannels.

• ulong TestSetupROIsDelete(...)
  Deletes only from TestSetupROIs table (not ROIPeriodChannels). Signature matches RegionsOfInterestDelete.

• ulong TestSetupROIsInsert(..., out int testSetupROIId)
  Inserts into TestSetupROIs only; outputs the new testSetupROIId.

• ulong TestSetupROIsGet(..., out ITestSetupROIRecord[] records)
  Retrieves only TestSetupROIs records (not joined with ROIPeriodChannels).

• ulong ROIPeriodChannelsInsert(...)
  Inserts a single ROIPeriodChannels record (channel mapping for an ROI period).

• ulong ROIPeriodChannelsGet(..., out IROIPeriodChannelRecord[] roiPeriodChannelRecords)
  Retrieves ROIPeriodChannels records for a given testSetupROIId.

ITestSetups

• ulong TestSetupHardwareDelete(..., int? Id, int? dasId, int? testSetupId)
  Deletes hardware metadata records. At least one of Id, dasId, or testSetupId must be non-null.

• ulong TestSetupHardwareUpdate(..., ITestSetupHardwareRecord record)
  Updates a hardware metadata record.

• ulong TestSetupHardwareInsert(..., ITestSetupHardwareRecord record)
  Inserts a hardware metadata record.

• ulong TestSetupHardwareGet(..., int clientDbVersion, int? testSetupId, out ITestSetupHardwareRecord[] records)
  Retrieves hardware metadata (e.g., sample rate, anti-aliasing filter settings) for given testSetupId or all.

• ulong TestSetupGroupsInsert(..., ITestSetupGroupRecord record)
  Inserts a group–test setup association.

• ulong TestSetupGroupsUpdate(..., ITestSetupGroupRecord record)
  Updates a group–test setup association.

• ulong TestSetupGroupsGet(..., int? groupId, int? testSetupId, string testSetupName, out ITestSetupGroupRecord[] groups)
  Retrieves group–test setup associations matching criteria.

• ulong TestSetupsMarkIsDirtyIsComplete(..., string name, bool dirty, bool complete, string error)
  Updates IsDirty and IsComplete flags for a test setup named name. error may contain validation messages.

• ulong TestSetupsDeleteByDate(..., DateTime date)
  Deletes all test setups older than date.

• ulong TestSetupsAndGroupsDeleteAll(...)
  Deletes all test setups and associated group associations.

• ulong TestSetupsDeleteById(..., int[] ids)
  Deletes test setups by their IDs.

• ulong TestSetupsDeleteByName(..., string[] names)
  Deletes test setups by their names.

• ulong TestSetupsUpdateInsert(..., int clientDbVersion, ref ITestSetupRecord record)
  Inserts or updates a test setup record. record is passed by reference and may be modified (e.g., ID populated on insert).

• ulong TestSetupsGet(..., int clientDbVersion, int? testSetupId, string testSetupName, double defaultROIStart, double defaultROIEnd, bool defaultIgnoreShortedStart, bool defaultIgnoreShortedTrigger, out ITestSetupRecord[] records, out string[] errors)
  Retrieves test setup records. Includes logic to generate default ROIs if missing (using defaultROIStart/defaultROIEnd).

  • defaultIgnoreShortedStart/defaultIgnoreShortedTrigger: flags for backward compatibility with older DB versions (e.g., v91) that lack these fields.

3. Invariants

• Authentication: All methods first check IsUserLoggedIn(user, connection); if false, return ERROR_ACCESS_DENIED.
• Error Handling: All methods return ERROR_SUCCESS (0) on success; non-zero values are error codes. Errors are logged via LogManager.
• Null/Empty Handling:
  • Nullable parameters (int?, string) accept null or "" (where applicable) to mean "no filter".
  • CalculatedChannelsGet allows empty testSetupName.
  • GraphsGet requires testSetupId to be non-null if filtering by test setup (but graphId may be null).
• Input Validation:
  • GraphsInsert, CalculatedChannelsInsert, CalculatedChannelsUpdate, CalculatedChannelsDelete validate record != null.
  • TestSetupHardwareDelete requires at least one ID parameter (Id, dasId, testSetupId) to be non-null.
• Output Parameters:
  • ref parameters (record in Insert methods) are updated with database-generated IDs after successful insert.
  • out parameters (records, errors) are always initialized (e.g., records = new T[0] on failure).
• Resource Cleanup: All methods dispose SqlCommand and connection in finally blocks.

4. Dependencies

Module Dependencies

• DbAPI.Connections: Provides IsUserLoggedIn, ConnectionManager.GetSqlCommand.
• DbAPI.Errors: Defines ErrorCodes.ERROR_* constants.
• DbAPI.Logging: Provides LogManager.
• DTS.Common.Interface.*:
  • Database: IUserDbRecord, IConnectionDetails.
  • Graphs: IGraphRecord, GraphRecord.
  • TestSetups: ICalculatedChannelRecord, ITestSetupRecord, ITestSetupHardwareRecord, ITestSetupGroupRecord, IRegionOfInterest, ITestSetupROIRecord, IROIPeriodChannelRecord.
  • RegionOfInterest: IRegionOfInterest.
• System.Data.SqlClient: Used for SqlCommand, SqlDbType, SqlParameter.
• System.Globalization: Used for CultureInfo.InvariantCulture.TextInfo.ListSeparator (in CalculatedChannels).

Inferred Usage

• Higher-level services (e.g., test setup management UI/backend) depend on these interfaces.
• The TestSetups class (not shown) likely orchestrates calls to IGraphs, ICalculatedChannels, IRegionsOfInterest, and ITestSetups.

5. Gotchas

• GraphsDelete bug: In Graphs.cs, GraphsDelete passes @TestSetupId = null to sp_TestGraphsDelete regardless of input. This likely ignores the testSetupId parameter from the interface and may delete graphs incorrectly (only filters by @GraphId).
  → Observed in source: cmd.Parameters.Add(new SqlParameter("@TestSetupId", SqlDbType.Int) { Value = null });

• Logging inconsistency: In CalculatedChannelsGet, errors are logged under LogManager.LogEvents.Graphs instead of LogManager.LogEvents.CalculatedChannels.
  → Likely copy-paste error.

• TestSetupROIsInsert vs RegionsOfInterestInsert: RegionsOfInterestInsert inserts into both TestSetupROIs and ROIPeriodChannels, while TestSetupROIsInsert inserts only into TestSetupROIs. Confusing naming—RegionsOfInterest* implies full ROI handling, but TestSetupROIs* is a partial subset.

• TestSetupsGet side effects: The defaultROIStart/defaultROIEnd parameters suggest the method may generate default ROIs on retrieval (not just read them). This could cause unexpected behavior if callers expect pure read-only behavior.

• CalculatedChannelsInsert/Update input encoding: InputChannelIds is converted to byte[] using Utility.GetBytesFromStringArray(..., ListSeparator). The separator is hardcoded to CultureInfo.InvariantCulture.TextInfo.ListSeparator (typically ","), but if record.InputChannelIds contains commas, parsing may fail. No validation or escaping is visible.

• Missing clientDbVersion in Graphs* methods: Unlike RegionsOfInterest and TestSetups, the Graphs methods do not accept a clientDbVersion parameter, suggesting version-specific logic is not supported for graphs.

• No transaction support: All operations are executed individually. If a logical operation requires multiple DB calls (e.g., insert ROI + period channels), callers must manage transactions externally.

• No explicit validation of testSetupId existence: Methods like RegionsOfInterestInsert accept testSetupId but do not verify it exists in the database before inserting. This may cause FK violations if the test setup is missing.