--- 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> 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)` - `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>`). - **`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.