DP44/docs/ai/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-17T15:51:12.206877+00:00	zai-org/GLM-5-FP8	1	37c4e37f0df42b66

TestSetups Module Documentation

1. Purpose

This module provides the database access layer for test setup configuration data within the DataPRO system. It defines and implements CRUD operations for four primary entities: graphs (IGraphs/Graphs), calculated channels (ICalculatedChannels/CalculatedChannels), regions of interest (IRegionsOfInterest), and test setup metadata (ITestSetups). The module abstracts SQL Server stored procedure calls behind strongly-typed interfaces, handling user authentication, parameter marshalling, and error propagation. It serves as the persistence boundary between the application's domain model and the relational database.

---

2. Public Interface

IGraphs Interface

Method	Signature
GraphsGet	ulong GraphsGet(IUserDbRecord user, IConnectionDetails connection, int? graphId, int? testSetupId, out IGraphRecord[] records)
GraphsUpdate	ulong GraphsUpdate(IUserDbRecord user, IConnectionDetails connection, IGraphRecord record)
GraphsInsert	ulong GraphsInsert(IUserDbRecord user, IConnectionDetails connection, ref IGraphRecord record)
GraphsDelete	ulong GraphsDelete(IUserDbRecord user, IConnectionDetails connection, int graphId)

Behaviors:

• GraphsGet: Retrieves graph records filtered by optional graphId and/or testSetupId. Returns empty array if no matches.
• GraphsUpdate: Updates an existing graph record identified by record.GraphId.
• GraphsInsert: Inserts a new graph record. The ref parameter is mutated with the new GraphId from the database.
• GraphsDelete: Removes a graph record by its database ID.

ICalculatedChannels Interface

Method	Signature
CalculatedChannelsDelete	ulong CalculatedChannelsDelete(IUserDbRecord user, IConnectionDetails connection, int calculatedChannelId)
CalculatedChannelsGet	ulong CalculatedChannelsGet(IUserDbRecord user, IConnectionDetails connection, int? calculatedChannelId, string testSetupName, out ICalculatedChannelRecord[] records)
CalculatedChannelsInsert	ulong CalculatedChannelsInsert(IUserDbRecord user, IConnectionDetails connection, ref ICalculatedChannelRecord record)
CalculatedChannelsUpdate	ulong CalculatedChannelsUpdate(IUserDbRecord user, IConnectionDetails connection, ICalculatedChannelRecord record)

Behaviors:

• CalculatedChannelsGet: Retrieves calculated channel records filtered by optional calculatedChannelId and/or testSetupName.
• CalculatedChannelsInsert: Inserts a new calculated channel. The ref parameter is mutated with the new Id from the database.
• CalculatedChannelsUpdate: Updates an existing calculated channel identified by record.Id.
• CalculatedChannelsDelete: Removes a calculated channel by its database ID.

IRegionsOfInterest Interface

Method	Signature
RegionsOfInterestDelete	ulong RegionsOfInterestDelete(IUserDbRecord user, IConnectionDetails connection, int testSetupId)
RegionsOfInterestInsert	ulong RegionsOfInterestInsert(IUserDbRecord user, IConnectionDetails connection, int clientDbVersion, int testSetupId, IRegionOfInterest regionOfInterest)
RegionsOfInterestGet	ulong RegionsOfInterestGet(IUserDbRecord user, IConnectionDetails connection, int clientDbVersion, int testSetupId, out IRegionOfInterest[] records)
TestSetupROIsDelete	ulong TestSetupROIsDelete(IUserDbRecord user, IConnectionDetails connection, int testSetupId)
TestSetupROIsInsert	ulong TestSetupROIsInsert(IUserDbRecord user, IConnectionDetails connection, int testSetupId, IRegionOfInterest regionOfInterest, out int testSetupROIId)
TestSetupROIsGet	ulong TestSetupROIsGet(IUserDbRecord user, IConnectionDetails connection, int testSetupId, out ITestSetupROIRecord[] records)
ROIPeriodChannelsInsert	ulong ROIPeriodChannelsInsert(IUserDbRecord user, IConnectionDetails connection, int clientDbVersion, int testSetupROIId, string channelName, long channelId)
ROIPeriodChannelsGet	ulong ROIPeriodChannelsGet(IUserDbRecord user, IConnectionDetails connection, int clientDbVersion, int testSetupROIId, out IROIPeriodChannelRecord[] roiPeriodChannelRecords)

Behaviors:

• RegionsOfInterestDelete: Removes records from both TestSetupROIs and ROIPeriodChannels tables for a given testSetupId.
• RegionsOfInterestInsert: Inserts records into both TestSetupROIs and ROIPeriodChannels tables.
• RegionsOfInterestGet: Retrieves and combines records from TestSetupROIs and ROIPeriodChannels tables.
• TestSetupROIsInsert: Inserts into TestSetupROIs table; outputs the new testSetupROIId.

ITestSetups Interface

Method	Signature
TestSetupHardwareDelete	ulong TestSetupHardwareDelete(IUserDbRecord user, IConnectionDetails connection, int? Id, int? dasId, int? testSetupId)
TestSetupHardwareUpdate	ulong TestSetupHardwareUpdate(IUserDbRecord user, IConnectionDetails connection, ITestSetupHardwareRecord record)
TestSetupHardwareInsert	ulong TestSetupHardwareInsert(IUserDbRecord user, IConnectionDetails connection, ITestSetupHardwareRecord record)
TestSetupHardwareGet	ulong TestSetupHardwareGet(IUserDbRecord user, IConnectionDetails connection, int clientDbVersion, int? testSetupId, out ITestSetupHardwareRecord[] records)
TestSetupGroupsInsert	ulong TestSetupGroupsInsert(IUserDbRecord user, IConnectionDetails connection, ITestSetupGroupRecord record)
TestSetupGroupsUpdate	ulong TestSetupGroupsUpdate(IUserDbRecord user, IConnectionDetails connection, ITestSetupGroupRecord record)
TestSetupGroupsGet	ulong TestSetupGroupsGet(IUserDbRecord user, IConnectionDetails connection, int? groupId, int? testSetupId, string testSetupName, out ITestSetupGroupRecord[] groups)
TestSetupsMarkIsDirtyIsComplete	ulong TestSetupsMarkIsDirtyIsComplete(IUserDbRecord user, IConnectionDetails connection, string name, bool dirty, bool complete, string error)
TestSetupsDeleteByDate	ulong TestSetupsDeleteByDate(IUserDbRecord user, IConnectionDetails connection, DateTime date)
TestSetupsAndGroupsDeleteAll	ulong TestSetupsAndGroupsDeleteAll(IUserDbRecord user, IConnectionDetails connection)
TestSetupsDeleteById	ulong TestSetupsDeleteById(IUserDbRecord user, IConnectionDetails connection, int[] ids)
TestSetupsDeleteByName	ulong TestSetupsDeleteByName(IUserDbRecord user, IConnectionDetails connection, string[] names)
TestSetupsUpdateInsert	ulong TestSetupsUpdateInsert(IUserDbRecord user, IConnectionDetails connection, int clientDbVersion, ref ITestSetupRecord record)
TestSetupsGet	ulong TestSetupsGet(IUserDbRecord user, IConnectionDetails connection, int clientDbVersion, int? testSetupId, string testSetupName, double defaultROIStart, double defaultROIEnd, bool defaultIgnoreShortedStart, bool defaultIgnoreShortedTrigger, out ITestSetupRecord[] records, out string[] errors)

Behaviors:

• TestSetupHardwareDelete: Requires at least one of Id, dasId, or testSetupId to be specified.
• TestSetupsMarkIsDirtyIsComplete: Updates the IsDirty and IsComplete flags for a test setup by name.
• TestSetupsGet: Accepts default ROI values for backward compatibility with older database versions that may lack ROI data.

---

3. Invariants

1. Return Value Convention: All methods return ulong where 0 equals ERROR_SUCCESS. Any non-zero value indicates an error.

2. Authentication Requirement: All public methods in Graphs and CalculatedChannels implementations call DbAPI.Connections.IsUserLoggedIn(user, connection) before executing database operations. Failure returns ErrorCodes.ERROR_ACCESS_DENIED.

3. Null Record Handling: Insert and Update methods in CalculatedChannels check for null record parameter and return ErrorCodes.ERROR_MISSING_PARAMETER if null.

4. Resource Cleanup: All implementations use try/finally blocks to dispose of SqlCommand and its Connection. The SqlConnection is disposed via cmd.Connection.Dispose().

5. Stored Procedure Usage: All database operations use stored procedures (e.g., sp_CalculatedChannelsInsert, sp_TestGraphsGet). No inline SQL is used.

6. Output Parameter Mutation: Insert methods (GraphsInsert, CalculatedChannelsInsert) use ref parameters to return the newly assigned database ID to the caller.

7. Error Propagation: Stored procedures return errors via @errorNumber and @errorMessage output parameters. Non-zero error numbers are logged via LogManager.Log and result in ErrorCodes.ERROR_UNKNOWN being returned.

---

4. Dependencies

This module depends on:

Namespace	Purpose
DbAPI.Connections	IConnectionDetails, ConnectionManager.GetSqlCommand(), IsUserLoggedIn()
DbAPI.Errors	ErrorCodes constants (ERROR_SUCCESS, ERROR_ACCESS_DENIED, ERROR_MISSING_PARAMETER, ERROR_UNKNOWN)
DbAPI.Logging	LogManager.Log(), LogEvents enum
DTS.Common.Interface.Database	IUserDbRecord
DTS.Common.Interface.Graphs	IGraphRecord
DTS.Common.Interface.TestSetups	ICalculatedChannelRecord, ITestSetupRecord, ITestSetupHardwareRecord, ITestSetupGroupRecord, ITestSetupROIRecord, IROIPeriodChannelRecord
DTS.Common.Interface.RegionOfInterest	IRegionOfInterest
DTS.Common.Classes.TestSetups	Concrete implementations: GraphRecord, CalculatedChannelRecord
DTS.Common.Classes	Utility.GetBytesFromStringArray()
System.Data.SqlClient	SqlConnection, SqlCommand, SqlParameter, SqlDataReader

What depends on this module:

Not determinable from the provided source files alone. The interfaces are public and the implementations are internal, suggesting they are consumed by other components within the DbAPI assembly.

---

5. Gotchas

1. Incorrect Log Event in CalculatedChannelsGet: The implementation logs errors using LogEvents.Graphs instead of LogEvents.CalculatedChannels:

   LogManager.Log(TraceEventType.Error, LogManager.LogEvents.Graphs, $"sp_CalculatedChannelsGet failed: {ex.Message}");
   

   This appears to be a copy-paste error.

2. Incorrect Log Message in GraphsDelete: The exception log message incorrectly references "GraphsInsert":

   LogManager.Log(TraceEventType.Error, LogManager.LogEvents.Graphs, $"GraphsInsert exception {ex.Message}");
   

3. Inconsistent Command Disposal: The Graphs class only disposes cmd.Connection in its finally block, while CalculatedChannels disposes both cmd.Connection and cmd. This may indicate inconsistent cleanup patterns.

4. Missing XML Documentation: The IRegionsOfInterest interface lacks XML documentation for TestSetupROIsDelete, TestSetupROIsInsert, TestSetupROIsGet, ROIPeriodChannelsInsert, and ROIPeriodChannelsGet methods.

5. Undocumented clientDbVersion Parameter: The purpose and valid values of the clientDbVersion parameter (present in IRegionsOfInterest and ITestSetups methods) is not documented in the interface. Comments in TestSetupsGet hint at Version 91 database compatibility concerns, but specifics are unclear from source alone.

6. InputChannelIds Serialization: CalculatedChannelsInsert and CalculatedChannelsUpdate serialize InputChannelIds using Utility.GetBytesFromStringArray() with CultureInfo.InvariantCulture.TextInfo.ListSeparator. The deserialization logic is not present in these files.