--- source_files: - Common/DTS.CommonCore/Classes/Groups/ChannelSettings/ChannelSettingRecord.cs - Common/DTS.CommonCore/Classes/Groups/ChannelSettings/GroupChannelSettingRecord.cs - Common/DTS.CommonCore/Classes/Groups/ChannelSettings/ChannelSettingBase.cs generated_at: "2026-04-16T02:42:22.673078+00:00" model: "Qwen/Qwen3-Coder-Next-FP8" schema_version: 1 sha256: "f67a48400fa70da5" --- # ChannelSettings ## Documentation: Channel Settings Module ### 1. Purpose This module defines core data structures for modeling channel configuration settings in the DTS system. It provides three key classes: `ChannelSettingRecord` (a metadata record describing a *type* of setting), `GroupChannelSettingRecord` (an *instance* of a setting applied to a specific channel), and `ChannelSettingBase` (a concrete implementation of `IChannelSetting` that supports typed value accessors and constant-based setting name definitions). Together, they enable storage, retrieval, and manipulation of channel-specific configuration values, with support for multiple channel types (analog, digital, squib, UART, etc.) and versioned database interactions. --- ### 2. Public Interface #### `ChannelSettingRecord` - **`ChannelSettingRecord()`** Default constructor; initializes an empty record. - **`ChannelSettingRecord(IDataReader reader)`** Populates the record from an `IDataReader` by reading columns `"Id"`, `"SettingName"`, and `"DefaultValue"` using `Utility.GetInt` and `Utility.GetString`. - **`int Id`** Gets/sets the unique identifier for this setting definition. - **`string SettingName`** Gets/sets the canonical name of the setting (e.g., `"Range"`, `"SquibCurrent"`). - **`string DefaultValue`** Gets/sets the default value string for this setting. #### `GroupChannelSettingRecord` - **`GroupChannelSettingRecord()`** Default constructor; initializes an empty record. - **`GroupChannelSettingRecord(IDataReader reader, int storedProcedureVersionUsed)`** Populates the record from an `IDataReader`. Behavior depends on `storedProcedureVersionUsed`: - If `>= Constants.BULK_GROUPCHANNELSETTINGS_GET_DB_VERSION`, reads `"ChannelId"` via `Utility.GetLong`; otherwise sets `ChannelId = 0`. - Always reads `"SettingId"` (via `Utility.GetInt`) and `"SettingValue"` (via `Utility.GetString`). - **`GroupChannelSettingRecord(long channelId, int settingId, string settingValue)`** Constructor for programmatic creation; directly assigns `ChannelId`, `SettingId`, and `SettingValue`. - **`long ChannelId`** Gets/sets the channel identifier the setting applies to. - **`int SettingId`** Gets/sets the foreign key referencing `ChannelSettingRecord.Id`. - **`string SettingValue`** Gets/sets the actual value string for this channel’s setting instance. #### `ChannelSettingBase` - **`ChannelSettingBase(int settingType, string name, string defaultValue)`** Constructor initializing `SettingTypeId`, `SettingName`, and `DefaultValue`. - **`IChannelSetting Clone()`** Returns a new `ChannelSettingBase` instance with all properties copied from the current instance. - **`long ChannelId { get; set; }`** Channel ID the setting applies to. - **`int SettingTypeId { get; protected set; }`** Type identifier for the setting (e.g., analog, digital). - **`string SettingName { get; protected set; }`** Name of the setting (e.g., `"Range"`). - **`string DefaultValue { get; protected set; }`** Default value string for this setting. - **`string Value { get; set; }`** Current value string for this setting instance. - **`double DoubleValue { get; set; }`** Gets/sets `Value` as a `double`. Falls back to `DoubleDefaultValue` on parse failure. - **`double DoubleDefaultValue { get; }`** Parses `DefaultValue` as a `double` using `CultureInfo.InvariantCulture`. - **`int IntValue { get; set; }`** Gets/sets `Value` as an `int`. Falls back to `IntDefaultValue` on parse failure. - **`int IntDefaultValue { get; }`** Parses `DefaultValue` as an `int` using `CultureInfo.InvariantCulture`. - **`bool BoolValue { get; set; }`** Gets/sets `Value` as a `bool`. Falls back to `BoolDefaultValue` on parse failure. - **`bool BoolDefaultValue { get; }`** Parses `DefaultValue` as a `bool` (uses default `bool.Parse` behavior). #### Constants (public static fields in `ChannelSettingBase`) - **Analog**: `RANGE`, `CFC`, `FilterClass`, `POLARITY`, `POSITION`, `ZEROMETHOD`, `ZEROMETHODSTART`, `ZEROMETHODEND`, `USERVALUE1`, `USERVALUE2`, `USERVALUE3`, `INITIAL_OFFSET`, `ACCouplingEnabled` - **Deprecated**: `LIMIT_DURATION`, `DURATION`, `DELAY` (commented out) - **Bridge/Insertion**: `BRIDGE_TYPE` - **Squib**: `SQUIB_CURRENT`, `SQUIB_LIMIT_DURATION`, `SQUIB_DURATION`, `SQUIB_DELAY`, `SQMODE` - **Digital Out**: `DIGITALOUT_LIMIT_DURATION`, `DIGITALOUT_DURATION`, `DIGITALOUT_DELAY`, `OUTPUT_MODE` - **Digital In**: `DIMODE`, `DEFAULT_VALUE`, `ACTIVE_VALUE` - **UART**: `BAUD_RATE`, `DATA_BITS`, `STOP_BITS`, `PARITY`, `FLOW_CONTROL`, `DATA_FORMAT` - **Stream Out**: `UDP_PROFILE`, `UDP_ADDRESS`, `UDP_TIME_CHID`, `UDP_DATA_CHID`, `UDP_TMNS_CONFIG`, `IRIG_TDP_INTERVAL_MS`, `TMATS_INTERVAL_MS` - **Stream In**: `UDP_ADDRESS_IN` --- ### 3. Invariants - **`ChannelSettingRecord.Id`** must be non-negative (implied by `int` type and database usage). - **`GroupChannelSettingRecord.SettingId`** must correspond to a valid `ChannelSettingRecord.Id` in the database (enforced by foreign key at persistence layer, not here). - **`GroupChannelSettingRecord.ChannelId`** may be `0` *only* when constructed from `IDataReader` with `storedProcedureVersionUsed < Constants.BULK_GROUPCHANNELSETTINGS_GET_DB_VERSION`. Otherwise, it must be positive. - **`ChannelSettingBase.Value`** is stored as a string; numeric/boolean accessors (`DoubleValue`, `IntValue`, `BoolValue`) parse it at runtime and fall back to defaults on failure. - **`ChannelSettingBase.DefaultValue`** must be parseable as the corresponding type (`double`, `int`, `bool`) for `DoubleDefaultValue`, `IntDefaultValue`, and `BoolDefaultValue` to succeed; otherwise, runtime exceptions may occur during parsing. --- ### 4. Dependencies - **Internal Dependencies**: - `DTS.Common.Interface.Channels` (interfaces `IChannelSettingRecord`, `IGroupChannelSettingRecord`, `IChannelSetting`) - `DTS.Common.Base.BasePropertyChanged` (base class for `ChannelSettingRecord`) - `DTS.Common.Base.BasePropertyChanged` (base class for `GroupChannelSettingRecord`) - `DTS.Common.Interface.Channels` (interface `IChannelSetting`) - `System.Data` (`IDataReader`) - `Utility` class (static methods: `GetInt`, `GetString`, `GetLong`) - `Constants` class (reference to `BULK_GROUPCHANNELSETTINGS_GET_DB_VERSION`) - **External Dependencies**: - `System` (core types, `CultureInfo`, `NumberStyles`) - `DTS.Common.Interface.Channels` (consumed by other modules for channel configuration management) --- ### 5. Gotchas - **`GroupChannelSettingRecord` constructor with `IDataReader` silently sets `ChannelId = 0`** when `storedProcedureVersionUsed < Constants.BULK_GROUPCHANNELSETTINGS_GET_DB_VERSION`. This may mask missing data if the stored procedure version is misconfigured. - **`ChannelSettingBase` parsing methods (`DoubleValue`, `IntValue`, `BoolValue`) do not distinguish between parse failure and a valid default value**—e.g., if `Value = "0"` and `DefaultValue = "1"`, `IntValue` returns `0`, not `1`. The fallback only occurs on *parse failure* (e.g., `Value = "abc"`). - **`BoolDefaultValue` uses `bool.Parse(DefaultValue)` without `CultureInfo.InvariantCulture`**, unlike numeric defaults. This may cause culture-dependent failures if `DefaultValue` is not `"True"`/`"False"` (case-sensitive). - **`ChannelSettingBase` is mutable** (`Value`, `ChannelId`, etc., have public setters). Cloning via `Clone()` is shallow but may be insufficient if consumers modify nested objects (none present here, but worth noting). - **`ChannelSettingBase` has no validation on `SettingName` or `DefaultValue`**—invalid names or unparseable defaults may only surface at runtime during type conversion. - **`ChannelSettingBase` constants are string literals**; typos in usage (e.g., `"Rang"` instead of `"Range"`) will compile but cause runtime mismatches with database or UI expectations.