DbAPI

DbAPI Module Documentation

1. Purpose

This module serves as the central entry point and facade for database interaction within the DataPRO system. It provides static access to a range of domain-specific data access layers (e.g., sensors, channels, groups, test setups) via singleton-backed properties, while also exposing core database utility functions—most notably for stored procedure version resolution and database version discovery. Its primary role is to abstract database connectivity and version compatibility logic, enabling client code to reliably invoke versioned stored procedures across heterogeneous client-server database environments.

2. Public Interface

Static Methods

Method	Signature	Behavior
`GetStoredProcedureToUse`	`public static ulong GetStoredProcedureToUse(IConnectionDetails connection, string storedProcedure, int clientDbVersion, out int storedProcedureVersionToUse)`	Determines the highest compatible stored procedure version (≤ min(clientDbVersion, serverDbVersion)) by querying the database. Does not use caching. Returns `ErrorCodes.ERROR_SUCCESS` on success, or an error code otherwise.
`GetStoredProcedureToUseCached`	`public static ulong GetStoredProcedureToUseCached(IConnectionDetails connection, string storedProcedure, int clientDbVersion, out int storedProcedureVersionToUse)`	Same as `GetStoredProcedureToUse`, but caches the mapping `(storedProcedure, clientDbVersion, serverDbVersion) → storedProcedureVersionToUse` in an in-memory dictionary (`_spLookup`) for reuse. Thread-safe via `StoredProcedureLock`.
`GetDatabaseVersion`	`public static ulong GetDatabaseVersion(IConnectionDetails connection, out int serverDbVersion)`	Executes stored procedure `sp_DbVersionGet` to retrieve the highest database version number from the server. Returns `ErrorCodes.ERROR_SUCCESS` on success, `ErrorCodes.ERROR_UNKNOWN` on exception.
`GetStoredProcedureVersion`	`public static ulong GetStoredProcedureVersion(IConnectionDetails connection, string storedProcedure, int maxSPVersion, out int storedProcedureVersionToUse)`	Executes stored procedure `sp_StoredProcedureVersionsGet` with parameters `@StoredProcedure` and `@Version = maxSPVersion`, then returns the highest version ≤ `maxSPVersion` found. Returns `ErrorCodes.ERROR_SUCCESS` on success, `ErrorCodes.ERROR_UNKNOWN` on exception.
`InitializeLogger`	`public static void InitializeLogger(int logSize, string path, int logTypes)`	Initializes the logging subsystem via `Logging.LogManager.Initialize(...)`. Sets internal flag `_loggerInitialized = true`. `logTypes` is a bitmask of `TraceEventType` values (see XML comment for bit definitions).
`LogDBCaching`	`public static void LogDBCaching(string message)`	Logs `message` at `TraceEventType.Information` level under event ID `LogManager.LogEvents.Information`.

Static Properties (Singleton Accessors)

Property	Type	Description
`Connections`	`IConnections`	Exposes `ConnectionManager` instance for connection management.
`Database`	`IDatabase`	Exposes `Database.Database` instance for database-level operations.
`DAS`	`IDataRecorders`	Exposes `DataRecorders` instance for data recorder (DAS) operations.
`Sensors`	`ISensors`	Exposes `Sensors.Sensors` instance for sensor-related operations.
`Graphs`	`IGraphs`	Exposes `Graphs` instance for graph-related operations.
`RegionsOfInterest`	`IRegionsOfInterest`	Exposes `RegionsOfInterest` instance for ROI operations.
`CalculatedChannels`	`ICalculatedChannels`	Exposes `CalculatedChannels` instance for calculated channel operations.
`TestSetups`	`ITestSetups`	Exposes `TestSetups.TestSetups` instance for test setup management.
`Tags`	`ITags`	Exposes `Tags.Tags` instance for tag management.
`Channels`	`IChannels`	Exposes `Channels.Channels` instance for channel operations.
`GroupHardware`	`IGroupHardware`	Exposes `GroupHardware.GroupHardware` instance for group hardware operations.
`Groups`	`IGroups`	Exposes `Groups.Groups` instance for group management.
`CustomerDetails`	`ICustomerDetails`	Exposes `CustomerDetails.CustomerDetails` instance for customer data operations.
`LabratoryDetails`	`ILabratoryDetails`	Exposes `LabratoryDetails.LabratoryDetails` instance for lab data operations.
`TestEngineerDetails`	`ITestEngineerDetails`	Exposes `TestEngineerDetails.TestEngineerDetails` instance for test engineer data operations.

Internal Types Referenced

SPCache: Used in _spLookup. Contains fields: ClientVersion, DbVersion, StoredProcedureVersion. Instantiated only in GetStoredProcedureToUseCached.
ErrorCodes: Source of return codes (e.g., ERROR_SUCCESS, ERROR_UNKNOWN).
Logging.LogManager: Used for logging; accessed via static methods.

3. Invariants

Version Compatibility: The version of a stored procedure returned by GetStoredProcedureToUse/GetStoredProcedureToUseCached is guaranteed to be ≤ both clientDbVersion and the server’s database version (serverDbVersion), as determined by sp_DbVersionGet.
Stored Procedure Version Resolution: GetStoredProcedureVersion returns the maximum version ≤ maxSPVersion returned by sp_StoredProcedureVersionsGet, or 0 if none found (no explicit error for “not found” beyond return code).
Thread Safety: Caching in GetStoredProcedureToUseCached is guarded by a private static lock (StoredProcedureLock). The _spLookup dictionary is only mutated inside lock blocks.
Connection Disposal: All database commands created via ConnectionManager.GetSqlCommand are disposed (cmd.Connection.Dispose()) in finally blocks.
Logging Initialization: _loggerInitialized is set to true only after InitializeLogger completes successfully (no error checking on InitializeLogger itself).
No Null Checks on Connection: Methods assume connection and connection.ConnectionDbVersion are non-null; no defensive checks are present.

4. Dependencies

Internal Dependencies (from source imports)

DbAPI.Connections → IConnectionDetails, ConnectionManager, IConnections
DbAPI.DAS → DataRecorders, IDataRecorders
DbAPI.Database → Database.Database, IDatabase
DbAPI.Sensors → Sensors.Sensors, ISensors
DbAPI.Channels → Channels.Channels, IChannels
DbAPI.Groups → Groups.Groups, IGroups
DbAPI.GroupHardware → GroupHardware.GroupHardware, IGroupHardware
DbAPI.TestSetups → TestSetups.TestSetups, ITestSetups
DbAPI.Tags → Tags.Tags, ITags
DbAPI.CustomerDetails, DbAPI.LabratoryDetails, DbAPI.TestEngineerDetails → respective detail interfaces
DbAPI.Errors → ErrorCodes
DbAPI.SPCaching → SPCache
System.Data, System.Data.SqlClient → SqlCommand, SqlDbType, CommandType, SqlDataReader
Logging.LogManager → static logging API (exact location inferred from usage)

External Dependencies

SQL Server (due to use of SqlClient, stored procedures sp_DbVersionGet, sp_StoredProcedureVersionsGet)
Logging infrastructure (Logging.LogManager) — not defined in this file.

What Depends on This Module?

All client modules that require database access (e.g., UI, test execution engine, configuration tools) — inferred from the broad surface area of exposed interfaces.

5. Gotchas

Caching Scope: _spLookup is per-app-domain and not persisted across application restarts. Cache is never invalidated or cleared.
Version Mismatch Risk: If clientDbVersion is outdated relative to the server, GetStoredProcedureToUseCached may return a stale version mapping until the cache entry expires (i.e., never, unless app restarts).
No Validation of storedProcedure Name: Methods accept any string; SQL injection is mitigated via parameterized queries, but invalid procedure names will cause runtime errors.
GetStoredProcedureVersion Returns 0 on Failure: If no matching stored procedure version is found, storedProcedureVersionToUse is set to 0, and ERROR_SUCCESS may still be returned — callers must check storedProcedureVersionToUse != 0 if 0 is not a valid version.
Connection.ConnectionDbVersion Assumed Valid: GetStoredProcedureToUseCached uses connection.ConnectionDbVersion directly; if this property is uninitialized or incorrect, caching will be incorrect.
_loggerInitialized Not Thread-Safe: While InitializeLogger sets _loggerInitialized = true, there is no synchronization or guard against multiple calls or use before initialization.
No Timeout Configuration: Stored procedure execution uses default command timeouts (not shown in source).
No Retry Logic: Transient SQL failures (e.g., network hiccups) are not retried; exceptions result in ERROR_UNKNOWN.

None identified beyond those above.

9.1 KiB Raw Blame History Unescape Escape