DP44/enriched-qwen3-coder-next/DataPRO/Modules/PreviousDBVersions/Version57/DatabaseExport/Storage.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
DataPRO/Modules/PreviousDBVersions/Version57/DatabaseExport/Storage/DbOperationsEnum.cs DataPRO/Modules/PreviousDBVersions/Version57/DatabaseExport/Storage/DbVersion.cs DataPRO/Modules/PreviousDBVersions/Version57/DatabaseExport/Storage/IDbTimeStampAware.cs DataPRO/Modules/PreviousDBVersions/Version57/DatabaseExport/Storage/DbOperations.cs	2026-04-16T04:57:49.383657+00:00	Qwen/Qwen3-Coder-Next-FP8	1	a23af2f838d45bd9

Documentation: Database Export Module – Version 57 (DatabaseExport)

---

1. Purpose

This module provides infrastructure for exporting and managing database schema and data for Version 57 of the DataPRO system. It defines core abstractions for database interaction, including table/field metadata constants, stored procedure identifiers, version tracking (DbVersion), and timestamp-based concurrency control (DbTimeStampBase/IDbTimeStampAware). Its primary role is to support migration, export, and synchronization workflows by encapsulating versioned database structure and state management logic—particularly for legacy data exports where schema evolution must be tracked and reconciled.

---

2. Public Interface

DbOperationsEnum.StoredProcedure

• Type: enum
• Members:
  • sp_DbVersionGet: Represents the stored procedure used to retrieve the current database version.

DbVersion

• Constructor:

  public DbVersion(System.Data.DataRow dr)
  

  • Behavior: Initializes a DbVersion instance by extracting values from a DataRow expected to contain columns: "Version", "Step", "Date", "Remarks", and "UserField".

• Properties:

  • int Version { get; set; }
    • Database version number.
  • int Step { get; set; }
    • Step within the version (e.g., migration step).
  • DateTime Date { get; set; }
    • Timestamp of the version/step.
  • string Remarks { get; set; }
    • Optional notes about the version/step.
  • string UserField { get; set; }
    • Arbitrary user-defined field.

IDbTimeStampAware Interface & DbTimeStampBase Abstract Class

• Interface:

  public interface IDbTimeStampAware
  {
      long GetTimeStampMemory();
      void SetTimeStampMemory(long value);
      long GetTimeStampDb();
      bool IsOutOfDate();
  }
  

• Abstract Base Class: DbTimeStampBase

  • Properties:

    • public abstract string LookupTable { get; }
      • Name of the database table used to look up the timestamp.
    • public abstract ConstraintHelper[] GetConstraints();
      • Returns an array of ConstraintHelper objects defining the primary key or unique constraints for the record.

  • Methods:

    • long GetTimeStampMemory()
      • Returns the in-memory timestamp (DbTimeStamp field).
    • void SetTimeStampMemory(long value)
      • Sets the in-memory timestamp.
    • void SetTimeStampMemory(System.Data.DataRow row)
      • Sets in-memory timestamp to 0 (currently unimplemented beyond that).
    • void SetTimeStampMemory(System.Data.IDataReader reader)
      • Sets in-memory timestamp to 0 (currently unimplemented beyond that).
    • long GetTimeStampDb()
      • Currently returns 0 (implementation is commented out). Intended to fetch the database timestamp for the current record.
    • long GetTimeStampDb(Dictionary<string, long> lookup)
      • Currently returns 0 (implementation is commented out). Intended to fetch timestamp via lookup table.
    • Dictionary<string, long> GetAllTimeStampDb()
      • Currently returns an empty dictionary (implementation is commented out). Intended to fetch all timestamps from the database.
    • bool IsNotInDb()
      • Returns true if GetTimeStampDb() == 0.
    • bool IsOutOfDate()
      • Compares DB and memory timestamps:
        • Returns false if DB timestamp is 0.
        • If memory timestamp is 0 and DB is non-zero, sets memory to DB and returns false.
        • Otherwise returns true if DB ≠ memory.

  • Nested Types:

    • ConstraintHelper:

      public class ConstraintHelper
      {
          public string ColumnName { get; set; }
          public System.Data.SqlDbType DbType { get; set; }
          public object DbValue { get; set; }
      }
      

• Exception:

  • DbItemOutOfDateException : Exception
    • Thrown when an item is detected as out-of-date (not used in current code, but defined).

DbOperations

• Nested Abstract Classes (Table/Field Constants):

  • Tags:
    • Table = "tblTags", TagFields enum (TagId, TagText, Obsolete).
    • TAGASSIGNMENTS_TABLE = "TagAssignments", TagAssignmentFields.
  • DbVersions:
    • DbVersionFields enum (Version, Step, Date, Remarks, UserField).
  • Settings, Users, SensorDB, CalculatedChannels, LevelTriggers, TestSetups, TestObjectChannelSettings, DigitalOutputSettings, Squib, MMETables, DAS, DigitalInputSettings
    • All define table names and field enums (e.g., TestSetups.TestSetupsTable = "tblTestSetups").
  • DbTypeAttr:
    • Custom attribute for mapping enum fields to SQL types (used in reflection via GetDbType()).
  • CustomChannelFieldSizeAttribute:
    • Custom attribute for specifying max field size (e.g., [CustomChannelFieldSizeAttribute(50)]).

• Static Methods:

  • SqlCommand GetSQLCommand(bool newCommand = false)
    • Returns a SqlCommand with an open connection (uses Connection.GetLocalConnectionString()). Clears parameters.
  • void CreateParam(IDbCommand icmd, string name, SqlDbType type, object value)
    • Adds a parameter to icmd. Special handling for DateTime (formats as "yyyy-MM-dd HH:mm:ss").
  • DataSet QueryDataSet(IDbCommand icmd)
    • Executes icmd and returns results as DataSet. Supports both SQL Server (_usingMSSQL == true) and SQLite (fallback).
  • int ExecuteCommand(IDbCommand icmd)
    • Executes icmd (non-query) and returns affected rows. Supports both SQL Server and SQLite.
  • IDbCommand GetISOCommand()
    • Returns a new SqlCommand connected to the ISO database.
  • IDbCommand GetCommand()
    • Returns a new SqlCommand or SQLiteCommand depending on _usingMSSQL.

• Static Properties:

  • bool _usingCentralizedDB, _usingMSSQL, _usingNTLMAuthentication, _previousDir
  • DbOperations Connection { get; }
    • Singleton instance of DbOperations.
  • bool LastConnectionStatus { get; set; }
    • Tracks last connection success/failure.
  • ConnectionStatusChangedDelegate ConnectionStatusChanged { get; set; }
    • Event for connection status changes.

• Instance Properties:

  • string Server, DBName, Username, Password
    • Connection configuration.
  • string GetLocalConnectionString(), GetLocalISOConnectionString()
    • Builds connection strings based on auth mode and settings.

---

3. Invariants

• DbVersion:

  • All fields (Version, Step, Date, Remarks, UserField) are required in the source DataRow; nulls or missing columns will cause InvalidCastException or NullReferenceException.
  • Date is parsed via Convert.ToDateTime, so culture-sensitive formatting may cause failures.

• DbTimeStampBase:

  • LookupTable and GetConstraints() must be implemented by subclasses; otherwise, runtime errors occur.
  • GetTimeStampDb() and GetAllTimeStampDb() currently always return 0 or empty, indicating incomplete implementation. No functional timestamp comparison occurs.
  • IsNotInDb() and IsOutOfDate() rely on GetTimeStampDb() returning 0 for missing records—currently true by design (but not correctness, since GetTimeStampDb() is unimplemented).
  • SetTimeStampMemory(DataRow) and SetTimeStampMemory(IDataReader) do not populate DbTimeStamp; they unconditionally set it to 0.

• DbOperations:

  • _usingMSSQL and _usingCentralizedDB control runtime behavior (e.g., which DB provider is used). Changing them mid-execution may cause inconsistent behavior.
  • GetLocalConnectionString() throws Exception("db connection not initialized") if Server is null.
  • QueryDataSet and ExecuteCommand throw SystemException with message "NoConnection" on connection failure.
  • CreateParam for DateTime normalizes to "yyyy-MM-dd HH:mm:ss" format—potentially losing precision.

---

4. Dependencies

This Module Depends On:

• System.Data (ADO.NET): DataRow, DataSet, SqlDataAdapter, SqlCommand, SqlDbType, SqlDataReader, SqlException, ConnectionState.
• System.Data.SqlClient: For SQL Server connectivity.
• System.Data.SQLite: For SQLite fallback (used when _usingMSSQL == false).
• System.ComponentModel: INotifyPropertyChanged (used by DbTimeStampBase).
• System.Reflection: Used in DbTypeAttr.GetDbType().

This Module Is Used By:

• Other modules in DataPRO/Modules/PreviousDBVersions/Version57/DatabaseExport/ (inferred from namespace).
• Likely consumed by migration scripts, export utilities, or data sync components that need to:
  • Track DB version (DbVersion).
  • Synchronize state with DB via timestamps (DbTimeStampAware).
  • Access table/field metadata (DbOperations.Tags, DbOperations.TestSetups, etc.).

---

5. Gotchas

• GetTimeStampDb() and GetAllTimeStampDb() are stubbed:
  All timestamp-related logic is non-functional. The implementations are commented out, so IsOutOfDate() and IsNotInDb() will always behave as if the record is missing or in-memory is authoritative. Do not rely on timestamp concurrency control in this module.

• SetTimeStampMemory(DataRow) and SetTimeStampMemory(IDataReader) are no-ops:
  They set DbTimeStamp = 0 regardless of input—likely placeholder code.

• DbOperations.Connection is a singleton but mutable:
  Connection.Server, DBName, etc., can be set externally, potentially causing race conditions if accessed concurrently.

• CreateParam for DateTime truncates precision:
  Converts DateTime to "yyyy-MM-dd HH:mm:ss" (no milliseconds), risking data loss.

• DbVersion constructor lacks null/invalid column checks:
  Assumes dr["Version"], dr["Step"], etc., exist and are non-null. Will throw on schema mismatches.

• MMETables field name inconsistencies:
  Notes that "MyType" → "CustomChannelType" → "TYPE" and "Id" → "ID" were used across versions. Code using these must handle historical schema differences.

• DbOperations.QueryDataSet and ExecuteCommand have duplicated logic for SQL Server/SQLite:
  Code paths for both providers are interleaved, increasing maintenance risk. SQLite fallback uses _previousDir and "db/datapro.db".

• No error handling in GetTimeStampDb/GetAllTimeStampDb stubs:
  The commented-out code had try/catch blocks and logging (APILogger.Log(ex)), but the active code silently returns 0.

• DbOperations.Connection uses GetLocalConnectionString() which is not thread-safe outside the lock:
  While the singleton initialization is locked, GetLocalConnectionString() itself is not re-entrant safe (though lock(dbLock) is used internally).

• _usingMSSQL and _usingNTLMAuthentication are static flags:
  Changing them after Connection is instantiated may not affect existing connections.

• DbItemOutOfDateException is defined but never thrown:
  Its purpose is unclear; no usage found in the provided files.

---

End of Documentation