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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
DataPRO/DbAPI/Channels/IChannels.cs DataPRO/DbAPI/Channels/Channels.cs	2026-04-17T15:58:55.611952+00:00	zai-org/GLM-5-FP8	1	971339938de11eb6

Documentation: DbAPI.Channels

1. Purpose

The DbAPI.Channels namespace provides the database access layer for managing channel-related data. It implements the IChannels interface to perform CRUD operations on Channels, ChannelCodes, and ChannelSettings tables via SQL stored procedures. This module acts as the bridge between the application's business logic and the database, handling user authentication validation, ADO.NET command construction, and hydration of data objects from query results.

2. Public Interface

The public functionality is defined by the IChannels interface and implemented by the internal Channels class.

Channel Code Operations

• ulong ChannelCodesInsert(IUserDbRecord user, IConnectionDetails connection, IReadOnlyDictionary<ChannelEnumsAndConstants.ChannelCodeType, short> lookup, IChannelCode channelCode, out int id)
  • Inserts a new channel code record. Returns ERROR_SUCCESS (0) on success; returns the new record's ID via the id out parameter.
• ulong ChannelCodesUpdate(IUserDbRecord user, IConnectionDetails connection, IReadOnlyDictionary<ChannelEnumsAndConstants.ChannelCodeType, short> lookup, IChannelCode channelCode)
  • Updates an existing channel code record identified by channelCode.Id.
• ulong ChannelCodesDelete(IUserDbRecord user, IConnectionDetails connection, int? id, string code, string name, int? codeType)
  • Deletes channel codes matching the provided criteria. All filter parameters are nullable; non-null parameters are used to filter the delete operation.
• ulong ChannelCodesGet(IUserDbRecord user, IConnectionDetails connection, int? Id, string code, string name, ChannelEnumsAndConstants.ChannelCodeType? codeType, IReadOnlyDictionary<short, string> channelTypeLookup, out IChannelCode[] records)
  • Retrieves channel codes matching the criteria. Requires a channelTypeLookup dictionary to map database IDs to enum types.
• ulong ChannelCodeTypesGet(IUserDbRecord user, IConnectionDetails connection, short? id, string codeType, out Tuple<short, string>[] records)
  • Retrieves available channel code types (ID and string identifier).

Channel Settings Operations

• ulong ChannelSettingsUpdate(IUserDbRecord user, IConnectionDetails connection, int settingId, string defaultValue)
  • Updates the default value for a specific channel setting.
• ulong ChannelSettingsGet(IUserDbRecord user, IConnectionDetails connection, int? settingId, string settingName, out IChannelSettingRecord[] records)
  • Retrieves channel settings, filtered by ID or name.

Group Channel Settings Operations

• ulong GroupChannelSettingsDelete(IUserDbRecord user, IConnectionDetails connection, long channelId, int? settingId)
  • Deletes settings for a specific channel. If settingId is null, all settings for the channel are deleted.
• ulong GroupChannelSettingsInsert(IUserDbRecord user, IConnectionDetails connection, int clientDbVersion, long channelId, IGroupChannelSettingRecord record)
  • Inserts a new group channel setting record.
• ulong GroupChannelSettingsGet(IUserDbRecord user, IConnectionDetails connection, int clientDbVersion, List<long> channelIdList, out IGroupChannelSettingRecord[] records, out string[] errors)
  • Retrieves settings for a list of channels. Logic varies based on clientDbVersion (see Gotchas).

Channel Operations

• ulong ChannelsInsert(IUserDbRecord user, IConnectionDetails connection, ref IChannelDbRecord channel)
  • Inserts a new channel. The channel parameter is passed by reference; its Id property is populated upon successful insertion.
• ulong ChannelsUpdate(IUserDbRecord user, IConnectionDetails connection, IChannelDbRecord channel)
  • Updates an existing channel record.
• ulong ChannelsGet(IUserDbRecord user, IConnectionDetails connection, int clientDbVersion, long? channelId, int? groupId, int? dasId, int? sensorId, int? testSetupId, string testSetupName, out IChannelDbRecord[] channels)
  • Retrieves channels based on various filter criteria.
• ulong ChannelsDelete(IUserDbRecord user, IConnectionDetails connection, long id, out string errorString)
  • Deletes a channel by ID. Returns error details via the errorString out parameter.

3. Invariants

• Return Codes: All methods return a ulong error code. A value of 0 (ErrorCodes.ERROR_SUCCESS) indicates success; any non-zero value indicates failure.
• Authentication: All public methods enforce authentication. They check DbAPI.Connections.IsUserLoggedIn(user, connection) before executing database logic. If this check fails, methods return ErrorCodes.ERROR_ACCESS_DENIED.
• Parameter Validation: Methods performing inserts/updates validate that specific parameters (e.g., channelCode.Code, channelCode.Name) are not null or empty. Failure results in ErrorCodes.ERROR_MISSING_PARAMETER.
• Database Connection: Methods rely on ConnectionManager.GetSqlCommand to establish commands. The Channels class itself does not manage connection pooling or opening logic directly but relies on these dependencies.
• Resource Cleanup: All database commands are wrapped in try/finally blocks that dispose of the SqlCommand and its Connection.

4. Dependencies

Internal Dependencies (DbAPI/DTS)

• DbAPI.Connections: Used for IConnectionDetails, ConnectionManager, and IsUserLoggedIn validation.
• DbAPI.Errors: Provides ErrorCodes constants.
• DbAPI.Logging: Provides LogManager for error logging.
• DbAPI.Database: Used for PrepareForDbAccess and GetStoredProcedureVersionCached.
• DTS.Common.Interface.Channels: Defines interfaces IChannelCode, IChannelSettingRecord, IGroupChannelSettingRecord, IChannelDbRecord.
• DTS.Common.Enums.Channels: Defines ChannelEnumsAndConstants.
• DTS.Common.Classes: Used for Utility helper methods (e.g., GetShort, GetString).

External Dependencies

• System.Data.SqlClient: Used heavily for SqlConnection, SqlCommand, SqlParameter, and SqlDataReader.
• System.Data: Used for CommandType, ParameterDirection, DataTable.

5. Gotchas

• Critical Bug in ChannelsUpdate: In the ChannelsUpdate method, the code checks the @errorNumber output parameter before calling cmd.ExecuteNonQuery(). This means the error check logic is effectively dead code; it checks uninitialized (or default) values, and the stored procedure is executed regardless of the check. The error logging for this method will not trigger correctly on database errors.
• Hardcoded Business Logic in ChannelsGet: The ChannelsGet method contains hardcoded filtering logic. It silently excludes any channel where UserChannelName ends with DFConstantsAndEnums.USER_CHANNEL_NAME_HUMIDITY. This filtering happens client-side after retrieval, which may cause confusion if the database contains records that do not appear in the application layer.
• Documentation Mismatch in ChannelCodesInsert: The XML documentation for ChannelCodesInsert states "channel code is modified with a new id if successful." However, the implementation passes channelCode by value (not ref) and does not