DP44/enriched-qwen3-coder-next/Common/DTS.CommonCore/Classes/Groups.md

---
source_files:
  - Common/DTS.CommonCore/Classes/Groups/GroupGRPImportError.cs
  - Common/DTS.CommonCore/Classes/Groups/GroupGRPImportGroup.cs
  - Common/DTS.CommonCore/Classes/Groups/GroupHardwareDbRecord.cs
  - Common/DTS.CommonCore/Classes/Groups/TestSetupGroupRecord.cs
  - Common/DTS.CommonCore/Classes/Groups/GroupDbRecord.cs
  - Common/DTS.CommonCore/Classes/Groups/GroupGRPImportChannel.cs
  - Common/DTS.CommonCore/Classes/Groups/ChannelDbRecord.cs
  - Common/DTS.CommonCore/Classes/Groups/GroupHelper.cs
generated_at: "2026-04-16T02:40:36.766589+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "2f1b395f0369a2ed"
---

# Documentation: Group Import and Database Record Classes

## 1. Purpose

This module provides data structures and helper utilities for importing, representing, and managing group-based test configurations—specifically for `.GRP` files (TDC group files)—and their corresponding database records. It enables parsing of `.GRP` files into structured in-memory objects (`GroupGRPImportGroup`, `GroupGRPImportChannel`), tracking import errors (`GroupGRPImportError`), and mapping between in-memory group/channel representations and database entities (`GroupDbRecord`, `ChannelDbRecord`, `GroupHardwareDbRecord`, `TestSetupGroupRecord`). The module serves as the foundational data layer for group import workflows, supporting validation, error reporting, and persistence of group configurations in the DTS system.

## 2. Public Interface

### `GroupGRPImportError`
- **`Errors` enum**  
  Defines all possible error types during `.GRP` file import:
  - `FileEmpty`, `InvalidISOCodeInput`, `InvalidFullScaleInput`, `InvalidSensorInput`, `InvalidInvertInput`, `SensorNotFound`, `InvalidInputMode`, `InvalidDefaultValue`, `InvalidActiveValue`, `InvalidFireMode`, `InvalidDelay`, `InvalidLimitDuration`, `InvalidDuration`, `InvalidCurrent`
- **`ErrorCode` (property, `Errors`)**  
  The specific error encountered during import.
- **`File` (property, `string`)**  
  Path or name of the file where the error occurred.
- **`Line` (property, `int`)**  
  Line number in the file where the error occurred.
- **`ExtraInfo` (property, `string`)**  
  Additional human-readable context for the error.
- **`ToString()`**  
  Returns `ExtraInfo`.

### `GroupGRPImportGroup`
- **`Included` (property, `bool`, default `true`)**  
  Indicates whether the group should be included in the import operation.
- **`Overwrite` (property, `bool`, default `true`)**  
  Indicates whether existing group data should be overwritten during import.
- **`GroupName` (property, `string`)**  
  Name of the group (from the `.GRP` file).
- **`GroupTags` (property, `string`)**  
  Tags associated with the group.
- **`ImportingUserTags` (property, `string`)**  
  User-provided tags during import.
- **`SourceFile` (property, `string`)**  
  Path to the source `.GRP` file.
- **`Channels` (property, `GroupGRPImportChannel[]`, default empty array)**  
  Array of channels parsed from the `.GRP` file.
- **`GroupErrors` (property, `GroupGRPImportError[]`, default `null`)**  
  List of errors encountered during import of the group (e.g., file-level errors).
- **`GroupNameHasError` (property, `bool`)**  
  Indicates whether the group name itself has an error; used for UI validation (e.g., red border on textbox).

### `GroupGRPImportChannel`
- **Field index constants** (`public const uint`)  
  `SerialNumberField`, `DisplayNameField`, `ISOCodeField`, `InvertField`, `CapacityField`, `InputModeField`, `DefaultValueField`, `ActiveValueField`, `FireModeField`, `DelayField`, `LimitDurationField`, `DurationField`, `CurrentField`  
  Represent column indices in `.GRP` file rows.
- **`SensorSerialNumber` (property, `string`)**  
  Serial number of the sensor associated with this channel.
- **`DisplayName` (property, `string`)**  
  Human-readable name for the channel.
- **`ISOCode` (property, `string`)**  
  ISO-compliant code for the channel.
- **`Invert` (property, `bool`)**  
  Whether the channel signal should be inverted.
- **`FullScale` (property, `double`)**  
  Full-scale value for analog channels.
- **`InputMode` (property, `InputModes?`, default `null`)**  
  Input mode for digital channels; enum values: `na`, `TLH`, `THL`, `CCNO`, `CCNC`. Default: `InputModes.CCNO`.
- **`DefaultValue`, `ActiveValue`, `Delay`, `Duration`, `Current` (properties, `double?`, defaults `0.0`, `1.0`, `0.0`, `10.0`, `1.5` respectively)**  
  Optional numeric parameters for channel configuration.
- **`FireMode` (property, `FireModes?`, default `null`)**  
  Fire mode for squib channels; enum values: `na`, `CD`, `CC`. Default: `FireModes.CD`.
- **`LimitDuration` (property, `bool?`, default `null`)**  
  Whether duration limiting is enabled. Default: `true`.
- **`Error` (property, `GroupGRPImportError`, default `null`)**  
  Channel-specific import error (if any).
- **`ParentGroup` (property, `GroupGRPImportGroup`)**  
  Reference to the parent group.
- **`GroupName` (property, `string`)**  
  Returns `ParentGroup.GroupName` or `"---"` if `ParentGroup` is `null`.
- **`GroupNameInvalidate()`**  
  Raises `PropertyChanged` for `GroupName` to force UI refresh.

### `GroupHardwareDbRecord`
- **`Id` (property, `int`, `[Key]`)**  
  Primary key in `GroupHardware` table.
- **`GroupId` (property, `int`)**  
  Foreign key to group.
- **`DASId` (property, `int`)**  
  Foreign key to DAS (Data Acquisition System).
- **`SerialNumber` (property, `string`)**  
  Serial number of hardware device.
- **Constructors**  
  - `GroupHardwareDbRecord()`  
  - `GroupHardwareDbRecord(IGroupHardwareDbRecord copy)`  
  - `GroupHardwareDbRecord(IDataReader reader)` — populates from database reader.

### `TestSetupGroupRecord`
- **`GroupId` (property, `int`)**  
  Database ID of the group.
- **`DisplayOrder` (property, `int`)**  
  Order in which the group appears in UI/test setup.
- **`Position` (property, `string`)**  
  ISO 13499 position field (may be mixed across channels).
- **`TestObjectType` (property, `string`)**  
  ISO 13499 test object field (may be mixed across channels).
- **`TestSetupId` (property, `int`)**  
  Database ID of the test setup.
- **Constructors**  
  - `TestSetupGroupRecord()`  
  - `TestSetupGroupRecord(ITestSetupGroupRecord copy)`  
  - `TestSetupGroupRecord(IDataReader reader)` — populates from database reader.

### `GroupDbRecord`
- **`Id` (property, `int`, `[Key]`)**  
  Primary key in group table.
- **`SerialNumber` (property, `string`)**  
  Serial number of the group (often derived from group name).
- **`Picture` (property, `string`)**  
  Path or identifier for group image.
- **`DisplayName` (property, `string`)**  
  Human-readable name.
- **`Description` (property, `string`)**  
  Optional description.
- **`Embedded` (property, `bool`)**  
  Whether the group is embedded (e.g., system-provided).
- **`LastModified` (property, `DateTime`)**  
  Timestamp of last modification.
- **`LastModifiedBy` (property, `string`)**  
  User who last modified the group.
- **`StaticGroupId` (property, `int?`)**  
  Optional ID for static groups.
- **`ExtraProperties` (property, `string`)**  
  JSON-serialized dictionary of additional properties.
- **Constructors**  
  - `GroupDbRecord()`  
  - `GroupDbRecord(IGroupDbRecord copy)`  
  - `GroupDbRecord(IGroup copy, List<KeyValuePair<string,string>> extraProperties)`  
  - `GroupDbRecord(IDataReader reader)` — populates from database reader.

### `ChannelDbRecord`
- **`Id` (property, `long`, `[Key]`)**  
  Primary key in channel table.
- **`GroupId` (property, `int`)**  
  Foreign key to group.
- **`IsoCode`, `IsoChannelName` (properties, `string`)**  
  ISO-compliant identifiers.
- **`UserCode`, `UserChannelName` (properties, `string`)**  
  User-defined identifiers.
- **`DASId`, `DASChannelIndex` (properties, `int`)**  
  DAS device and channel index.
- **`GroupChannelOrder`, `TestSetupOrder` (properties, `int`)**  
  Ordering within group and test setup.
- **`SensorId` (property, `int`)**  
  Foreign key to sensor.
- **`Disabled` (property, `bool`)**  
  Whether channel is disabled.
- **`IsDisabled` (property, `bool`)**  
  Backward-compatible alias for `Disabled`.
- **`LastModified`, `LastModifiedBy` (properties, `DateTime`, `string`)**  
  Timestamp and user of last modification.
- **Constructors**  
  - `ChannelDbRecord()`  
  - `ChannelDbRecord(IChannelDbRecord copy)`  
  - `ChannelDbRecord(IDataReader reader)` — populates from database reader.

### `GroupHelper` (abstract class)
- **Static group metadata caches**  
  All methods are static and operate on internal static dictionaries.
  - `ClearStaticGroupNames()`, `SetStaticGroupName(int, string)`, `GetStaticGroupName(int)`  
  - `ClearEmbeddedGroupIdList()`, `SetEmbeddedGroupId(int)`, `IsGroupEmbedded(int)`  
  - `ClearTestSetupGroupIds()`, `SetTestSetupGroupId(int, int)`, `GetTestSetupGroupId(int)`  
  - `ClearGroupChannelIds()`, `AddGroupChannelId(int, int)`, `GetGroupIdsFromChannels(int)`  
  - `ClearDASIds()`, `SetDASId(string, int)`, `GetDASId(string)`  
  - `ClearBaseModuleChannelIndexList()`, `SetBaseModuleChannelIndexList(...)`, `GetChannelIndexes(string, string)`  
  - `ClearDASIdChannelIndexGroupIdList()`, `SetDASIdChannelIndexGroupIdList(...)`, `GetGroupIds(int, List<int>)`  
  - `ClearTestSetupHardwareIds()`, `AddTestSetupHardwareId(int, int)`, `GetTestSetupHardwareIds(int)`  
  - `ClearGroupHardwareIds()`, `AddGroupHardwareId(int, int)`, `GetGroupHardwareIds(int)`  
  *Note: These are caching utilities for runtime lookups, not persistent storage.*

## 3. Invariants

- **`GroupGRPImportChannel.InputMode`**  
  Must be `null` or one of `na`, `TLH`, `THL`, `CCNO`, `CCNC`. Default is `CCNO`.
- **`GroupGRPImportChannel.FireMode`**  
  Must be `null` or one of `na`, `CD`, `CC`. Default is `CD`.
- **`GroupGRPImportChannel.LimitDuration`**  
  Must be `null` or `true`/`false`. Default is `true`.
- **`GroupGRPImportChannel.DefaultValue`, `ActiveValue`, `Delay`, `Duration`, `Current`**  
  Must be `null` or a non-negative `double`. Defaults are defined as `0.0`, `1.0`, `0.0`, `10.0`, `1.5` respectively.
- **`GroupGRPImportChannel.Error`**  
  If non-`null`, indicates a channel-level import error; if `null`, the channel is valid.
- **`GroupGRPImportGroup.GroupErrors`**  
  If non-`null`, contains group-level errors (e.g., file corruption, invalid header). If `null`, no group-level errors were recorded.
- **`GroupDbRecord.ExtraProperties`**  
  Must be valid JSON (serialized `List<KeyValuePair<string,string>>`).
- **`ChannelDbRecord.IsDisabled`**  
  Always mirrors `Disabled`; setting either updates both.

## 4. Dependencies

### Dependencies *of* this module:
- **`DTS.Common.Base`**  
  Provides `BasePropertyChanged` (base class for `GroupGRPImportGroup`, `GroupGRPImportChannel`, `GroupHardwareDbRecord`, `TestSetupGroupRecord`, `GroupDbRecord`, `ChannelDbRecord`).
- **`DTS.Common.Interface.Groups`**  
  Defines interfaces: `IGroupHardwareDbRecord`, `ITestSetupGroupRecord`, `IGroupDbRecord`.
- **`DTS.Common.Interface.Channels`**  
  Defines interface: `IChannelDbRecord`.
- **`System.Data`**  
  Used for `IDataReader` in constructors.
- **`Newtonsoft.Json`**  
  Used in `GroupDbRecord` constructor to serialize `ExtraProperties`.

### Dependencies *on* this module:
- **Import/Export logic** (not shown)  
  Likely uses `GroupGRPImportGroup`, `GroupGRPImportChannel`, and `GroupGRPImportError` to parse `.GRP` files.
- **Database persistence layer**  
  Uses `GroupDbRecord`, `ChannelDbRecord`, `GroupHardwareDbRecord`, `TestSetupGroupRecord` for CRUD operations.
- **UI layer**  
  Binds to `GroupGRPImportGroup.GroupNameHasError`, `GroupGRPImportChannel.GroupName`, and `GroupGRPImportChannel.GroupNameInvalidate()` for validation and refresh.

## 5. Gotchas

- **`GroupGRPImportChannel.GroupName` is a computed property**  
  Returns `ParentGroup.GroupName` or `"---"`. UI bindings must call `GroupNameInvalidate()` after `ParentGroup` changes to refresh.
- **`ChannelDbRecord.IsDisabled` is a legacy alias**  
  Directly reads/writes `Disabled`; new code should use `Disabled` for clarity.
- **`GroupDbRecord.SerialNumber` is derived from `IGroup.Name`**  
  In the constructor `GroupDbRecord(IGroup, ...)`, `SerialNumber` is set to `copy.Name`, not a separate serial field.
- **`GroupHelper` caches are static and global**  
  State persists across operations; callers must explicitly clear caches (e.g., `ClearStaticGroupNames()`) to avoid stale data.
- **`GroupHardwareDbRecord.Id` uses `int` (not `long`)**  
  Contrasts with `ChannelDbRecord.Id`, which uses `long`.
- **`GroupGRPImportChannel.InputMode`, `FireMode`, etc., are nullable**  
  `null` indicates "not set" or "N/A", not a default value. Validation must handle `null` explicitly.
- **`GroupGRPImportGroup.Channels` defaults to empty array (not `null`)**  
  Safe to enumerate without null checks.
- **`GroupGRPImportGroup.GroupErrors` defaults to `null`**  
  Not an empty array—must check for `null` before enumeration.
- **`GroupHelper.GetChannelIndexes` and `GetGroupIds` use substring matching**  
  `GetChannelIndexes` matches `baseSerialNumberSubstring` exactly (not a substring search), despite the parameter name suggesting partial matching. Similarly, `GetGroupIds` requires exact `dasId` and `channelIndex` matches.