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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
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	2026-04-16T02:40:36.766589+00:00	Qwen/Qwen3-Coder-Next-FP8	1	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.