DP44/enriched-qwen3-coder-next/DataPRO/Modules/DatabaseImporter/DatabaseImport/Storage.md

---
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<T>(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<string, long> 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<string, long> 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.