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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
DataPRO/Modules/DatabaseImporter/DatabaseImport/Storage/IDbTimeStampAware.cs DataPRO/Modules/DatabaseImporter/DatabaseImport/Storage/DbOperationsEnum.cs DataPRO/Modules/DatabaseImporter/DatabaseImport/Storage/DbOperations.cs	2026-04-16T04:30:21.712903+00:00	Qwen/Qwen3-Coder-Next-FP8	1	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.