DP44/enriched-qwen3-coder-next/Common/DTS.CommonCore/Classes/Locking.md

---
source_files:
  - Common/DTS.CommonCore/Classes/Locking/LockRecord.cs
  - Common/DTS.CommonCore/Classes/Locking/LockError.cs
generated_at: "2026-04-16T02:40:09.269029+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "ee1fc4660f405448"
---

# Locking

### **Purpose**  
This module defines core data structures for representing and handling locking state and errors within the DTS system. Specifically, `LockRecord` encapsulates the metadata of an active lock (e.g., who holds it, when it was created, and what resource it pertains to), while `LockError` provides a structured way to represent lock-related error conditions—including recoverable states like lock theft or loss—enabling callers to programmatically respond to specific failure modes. Together, they serve as the foundational data models for a locking service, likely used in distributed or multi-user scenarios where resource contention must be managed.

---

### **Public Interface**  

#### `LockRecord`  
A read-only data class representing the state of a lock.  
- **Constructor**:  
  ```csharp
  public LockRecord(string user, string machine, DateTime createTime, DateTime lastUpdate, string itemKey, int itemCategory, int itemId)
  ```  
  Initializes a new instance with the specified lock metadata. All properties are set once at construction and immutable thereafter.  

- **Properties**:  
  - `string LockingUserName` – The username of the entity holding the lock.  
  - `string LockingMachineName` – The machine name of the entity holding the lock.  
  - `DateTime CreationTime` – Timestamp when the lock was first acquired.  
  - `DateTime LastUpdated` – Timestamp of the last lock maintenance (e.g., heartbeat or renewal).  
  - `string ItemKey` – A string-based identifier for the locked item (e.g., a unique key or path).  
  - `int ItemCategory` – An integer category code (corresponding to `LockCategories` in the database) classifying the type of item being locked.  
  - `int ItemId` – A numeric identifier for the locked item (likely a primary key in a database table).  

#### `LockError`  
A read-only data class representing an error condition in lock operations.  
- **Constructor**:  
  ```csharp
  public LockError(int error, string message, string user = null, string machine = null)
  ```  
  Initializes a new instance with an error code, descriptive message, and optional context about the locking user/machine.  

- **Properties**:  
  - `int ErrorCode` – The numeric error code (read-only after construction).  
  - `string Message` – Human-readable error description (read-only after construction).  
  - `string LockingUser` – Username associated with the error (defaults to `string.Empty` if `null`).  
  - `string LockingMachine` – Machine name associated with the error (defaults to `string.Empty` if `null`).  
  - `bool LockStolen` – `true` if `ErrorCode == LOCKSTOLEN_ERROR` (i.e., `998`).  
  - `bool LockLost` – `true` if `ErrorCode == LOCKDOESNTEXIST_ERROR` (i.e., `997`).  

- **Constants**:  
  - `BAD_NETPATH_ERROR = 994` – Network path error (e.g., lost remote DB connection).  
  - `SEM_TIMEOUT_ERROR = 995` – Semaphore timeout (e.g., connection failure).  
  - `ITEM_NOT_FOUND = 996` – Referenced item does not exist.  
  - `LOCKDOESNTEXIST_ERROR = 997` – Lock record no longer exists (e.g., expired or deleted).  
  - `LOCKSTOLEN_ERROR = 998` – Lock was forcibly released by another party.  
  - `UNKNOWN_ERROR = 999` – Generic/unspecified error.  

---

### **Invariants**  
- `LockRecord` instances are **immutable** after construction: all properties are `readonly` (via auto-properties with `private set` implied by lack of setters) and initialized only in the constructor.  
- `LockError.ErrorCode`, `Message`, `LockingUser`, and `LockingMachine` are immutable after construction (via `private set`).  
- `LockingUser` and `LockingMachine` in `LockError` are never `null`; if `null` is passed to the constructor, they default to `string.Empty`.  
- `LockStolen` and `LockLost` are derived solely from `ErrorCode` and are guaranteed to be consistent with the defined constants.  

---

### **Dependencies**  
- **Internal dependencies**:  
  - `System` (for `DateTime`, `string`, `object`, etc.).  
  - `System.Data` (imported but unused in these files; may indicate legacy or future use).  
- **External dependencies (inferred)**:  
  - Likely consumed by other modules in `DTS.CommonCore` (e.g., a locking service or database persistence layer).  
  - `ItemCategory` suggests integration with a database-defined `LockCategories` table (not present in source, but referenced in XML doc).  
  - Error constants (`994`–`999`) imply coupling to SQL Server or ADO.NET error handling (per comments referencing `SqlClient`).  

---

### **Gotchas**  
- **`System.Data` import is unused**: The `using System.Data;` statement in `LockRecord.cs` serves no purpose in the current implementation and may be legacy or placeholder.  
- **`LockingUser`/`LockingMachine` null-safety**: While `LockError` constructor normalizes `null` inputs to `string.Empty`, callers must be aware that `null` is *not* preserved—this may mask missing context if not handled explicitly.  
- **No validation in constructor**: Neither `LockRecord` nor `LockError` validates inputs (e.g., empty strings, negative `ItemId`/`ItemCategory`). Callers must ensure data integrity externally.  
- **`LockLost` vs. `LockStolen` semantics**: The distinction between `LOCKDOESNTEXIST_ERROR` (`LockLost`) and `LOCKSTOLEN_ERROR` (`LockStolen`) is subtle:  
  - `LockLost` implies the lock vanished *without* explicit release (e.g., timeout, crash).  
  - `LockStolen` implies another party *intentionally* released the lock (e.g., admin override).  
  This distinction may be critical for retry or conflict-resolution logic but is not enforced programmatically.  
- **No versioning or extensibility mechanism**: The classes are simple DTOs with no support for forward/backward compatibility (e.g., new fields would require breaking changes).