--- source_files: - DataPRO/Modules/DatabaseImporter/DatabaseImport/Storage/IDbTimeStampAware.cs - DataPRO/Modules/DatabaseImporter/DatabaseImport/Storage/DbOperationsEnum.cs - DataPRO/Modules/DatabaseImporter/DatabaseImport/Storage/DbOperations.cs generated_at: "2026-04-16T04:30:21.712903+00:00" model: "Qwen/Qwen3-Coder-Next-FP8" schema_version: 1 sha256: "604c24fe0c2a5ffe" --- # Storage ## Documentation: `DatabaseImport` Storage Module --- ### 1. Purpose This module provides foundational infrastructure for database versioning, timestamp tracking, and database abstraction within the `DatabaseImport` subsystem. Its primary role is to enable consistent detection of data staleness (via `IDbTimeStampAware`) and to centralize database operation utilities (via `DbOperations`), including stored procedure enumeration (`DbOperationsEnum`), database schema metadata (via nested `abstract class` enums), and connection management. It supports both local and centralized SQL Server databases, with authentication configurable at runtime. --- ### 2. Public Interface #### `IDbTimeStampAware` Interface *Defined in `IDbTimeStampAware.cs`* - **`long GetTimeStampMemory()`** Returns the in-memory timestamp value (stored in the protected `DbTimeStamp` field). - **`void SetTimeStampMemory(long value)`** Sets the in-memory timestamp to `value`. - **`long GetTimeStampDb()`** Returns the database timestamp for the current object. *Currently unimplemented* — always returns `0`. The commented-out code suggests it was intended to query a database table (`tblDbVersions` or similar) using constraints derived from `GetConstraints()` (not present in this file). - **`bool IsOutOfDate()`** Compares the in-memory and database timestamps. Returns `true` if the database timestamp (`db`) is non-zero and differs from the in-memory timestamp (`mem`). If `mem == 0` and `db != 0`, it auto-updates `mem` to `db` before comparison. #### `DbTimeStampBase` Abstract Class *Defined in `IDbTimeStampAware.cs`* - **`event PropertyChangedEventHandler PropertyChanged`** Implements `INotifyPropertyChanged`. Notifies listeners of property changes. - **`protected bool SetProperty(ref T storage, T value, string propertyName = null)`** Sets `storage` to `value` if different, raises `PropertyChanged`, and returns `true`. Otherwise returns `false`. - **`protected void OnPropertyChanged(string propertyName = null)`** Invokes the `PropertyChanged` event with the given property name. - **`public long GetTimeStampMemory()`** Returns the current value of the protected field `DbTimeStamp`. - **`public void SetTimeStampMemory(long value)`** Sets `DbTimeStamp` to `value`. - **`public void SetTimeStampMemory(DataRow row)`** Sets `DbTimeStamp` to `0`. *No-op beyond assignment*. - **`public void SetTimeStampMemory(IDataReader reader)`** Sets `DbTimeStamp` to `0`. *No-op beyond assignment*. - **`public long GetTimeStampDb(Dictionary lookup)`** Returns `0`. *Unimplemented*. Commented-out code suggests lookup by constraint values. - **`public long GetTimeStampDb()`** Returns `0`. *Unimplemented*. Commented-out code shows intended SQL query logic. #### `DbOperationsEnum.StoredProcedure` Enum *Defined in `DbOperationsEnum.cs`* - **`StoredProcedure` enum** Lists all stored procedure names used in the system (e.g., `sp_UserDelete`, `sp_DBImportUsers`, `sp_TestSetupsUpdateInsert`). Used to parameterize stored procedure calls. #### `DbOperations` Class *Defined in `DbOperations.cs`* - **`public const int CURRENT_DB_VERSION = 61`** Hardcoded current database schema version. - **`public static bool _usingCentralizedDB`** `true` if using a remote centralized server; `false` for local `SqlLocalDb`. - **`public static bool _usingMSSQL`** `true` if using Microsoft SQL Server. - **`public static bool _usingNTLMAuthentication`** `true` if using Windows Authentication (NTLM); otherwise SQL authentication. - **`public static string _previousDir`** Stores the previous working directory (unused in current code). - **`public static DbOperations Connection`** Singleton instance of `DbOperations`. Thread-safe via `lock(dbLock)`. - **`public static SqlCommand GetSQLCommand(bool newCommand = false)`** Returns a `SqlCommand` instance, reusing `_cmd` unless `newCommand` is `true`. Automatically opens a connection using `Connection.GetLocalConnectionString()` if needed. - **`public static bool IsServerConnected()`** Returns `true` if a connection to the local database (via `Connection.GetLocalConnectionString()`) succeeds. - **`public DataSet QueryDataSet(SqlCommand icmd)`** Executes `icmd` and returns results in a `DataSet`. Throws exceptions on failure. - **`public string GetLocalConnectionString()`** Builds and caches the connection string based on `_usingNTLMAuthentication`, `Server`, `DBName`, `Username`, and `Password`. Throws if connection not initialized. - **`public string Server`, `Username`, `Password`, `DBName`** Properties used to configure connection parameters. #### Nested Abstract Classes (Schema Metadata) *Defined in `DbOperations.cs`* These provide strongly-typed field names and database column metadata for various tables. All use `enum` fields annotated with `[DbTypeAttr(...)]` where applicable. - **`Tags.TagFields`** `TagId`, `TagText`, `Obsolete` - **`DbVersions.DbVersionFields`** `Version`, `Step`, `Date`, `Remarks`, `UserField` - **`Settings.UserFields`** `PropertyId`, `PropertyType`, `PropertyValue`, `UserId` - **`Users.UserFields`**, **`Users.UIItemFields`** User and UI item schema fields. - **`SensorDB.*Fields`** Sensor, SensorModel, and SensorCalibration schema fields (e.g., `SerialNumber`, `Model`, `CalibrationDate`). - **`CalculatedChannels.Fields`** Includes `[DbTypeAttr(...)]` annotations (e.g., `Id` → `"INTEGER PRIMARY KEY NOT NULL"`). - **`LevelTriggers.Fields`** Trigger configuration fields (e.g., `GreaterThanEU`, `TriggerInside`). - **`TestSetups.*Fields`** Test setup, hardware, channel settings, graphs, and object metadata fields. - **`DigitalOutputSettings.Fields`**, **`Squib.Fields`**, **`DigitalInputSettings.Fields`** Device-specific configuration fields. - **`MMETables.*Fields`** MME (likely "Measurement Management Environment") lookup table fields (e.g., `MMEFineLocations1Fields`, `MMETestObjectsFields`). - **`DAS.Fields`**, **`DAS.DASChannelFields`** DAS (Data Acquisition System) device and channel schema fields. #### `DbTypeAttr` Attribute *Defined in `DbOperations.cs`* - **`public static string GetDbType(object o)`** Retrieves the `DbType` string from a `[DbTypeAttr(...)]`-annotated enum value. --- ### 3. Invariants - **`DbTimeStamp` is always initialized to `0`** on construction or via `SetTimeStampMemory(DataRow)`/`SetTimeStampMemory(IDataReader)`. - **`IsOutOfDate()` never returns `true` if `GetTimeStampDb()` returns `0`**, even if `GetTimeStampMemory() != 0`. - **`GetTimeStampDb()` always returns `0`** — the implementation is stubbed and untested. - **`DbOperations.Connection` is a singleton** — only one instance exists per AppDomain. - **`_usingCentralizedDB`, `_usingMSSQL`, `_usingNTLMAuthentication` are global flags** — changing them affects all subsequent connection attempts. - **`CURRENT_DB_VERSION` is fixed at compile time** — no runtime schema migration logic is visible in this module. --- ### 4. Dependencies #### *This Module Depends On* - `System.Data` (for `DataSet`, `SqlDataAdapter`, `SqlDataReader`, `DataRow`, `ConnectionState`) - `System.Data.SqlClient` (for `SqlConnection`, `SqlCommand`) - `System.ComponentModel` (for `INotifyPropertyChanged`) - `System` (for `Attribute`, `Exception`, `StringBuilder`, `BitConverter`, `Trace`, `Dictionary`, `string`) #### *This Module Is Used By* - Any module requiring database timestamp checks (e.g., import/export logic, cache invalidation). - Modules that execute stored procedures (via `DbOperationsEnum.StoredProcedure`). - Modules that construct SQL queries or map database rows to objects (via `DbOperations.*Fields` enums). - UI layers that bind to objects implementing `IDbTimeStampAware` (for change tracking). --- ### 5. Gotchas - **`GetTimeStampDb()` is unimplemented** — always returns `0`. This renders `IsOutOfDate()` effectively useless for detecting *real* DB staleness unless the caller manually populates `DbTimeStamp` and assumes DB matches memory. - **`SetTimeStampMemory(DataRow)` and `SetTimeStampMemory(IDataReader)` ignore their inputs** — they unconditionally set `DbTimeStamp = 0`, which may be unintentional. - **`GetTimeStampDb(Dictionary lookup)` is unimplemented** — the `lookup` parameter is unused. - **`DbOperations.Connection` is a singleton with mutable state** — `Server`, `Username`, `Password`, `DBName` are settable properties, but not thread-safe for concurrent reconfiguration. - **`_cmd` is a static field reused across calls** — calling `GetSQLCommand()` without `newCommand: true` may cause parameter leakage between queries if callers do not clear parameters. - **`IsServerConnected()` only tests the *local* connection string** — if `_usingCentralizedDB == true`, it may not reflect connectivity to the remote server. - **`CURRENT_DB_VERSION` is hardcoded** — no schema versioning logic (e.g., migration, upgrade checks) is present in this module. - **No actual database access occurs in `DbTimeStampBase`** — all DB-related methods are stubbed. Real DB logic may reside elsewhere (not visible here). - **`DbTypeAttr.GetDbType()` relies on reflection** — may be slow or fail if enum values lack attributes or are not defined in the expected way. None identified beyond the above.