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

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