diff --git a/docs/img/locking-mechanism.drawio.png b/docs/img/locking-mechanism.drawio.png new file mode 100644 index 0000000..0c75fe9 Binary files /dev/null and b/docs/img/locking-mechanism.drawio.png differ diff --git a/docs/img/mpe_lockanytable.png b/docs/img/mpe_lockanytable.png new file mode 100644 index 0000000..9d478ad Binary files /dev/null and b/docs/img/mpe_lockanytable.png differ diff --git a/docs/locking-mechanism.md b/docs/locking-mechanism.md new file mode 100644 index 0000000..d74fcdf --- /dev/null +++ b/docs/locking-mechanism.md @@ -0,0 +1,37 @@ +--- +layout: article +title: Locking Mechanism +description: Data Controller uses a locking mechanism to handle parallel updates to the same table by different users. This mechanism is also available to non-DC applications. +og_image: https://docs.datacontroller.io/img/locking-mechanism.drawio.png +--- + +# Locking Mechanism + +In any multi-user application a locking mechanism is necessary to avoid conflicts when the same table is updated by two people or processes. In Data Controller this is handled using the `DCLIB.MPE_LOCKANYTABLE` table, specifically using the [mp_lockanytable](https://core.sasjs.io/mp__lockanytable_8sas.html) macro. + +This macro is invoked whenever a process requires an exclusive lock on a table - first to mark the table as locked, and again to mark it as unlocked. The logic flow is demonstrated below: + +![lockanytable logic](/img/locking-mechanism.drawio.png) + +Notice above the red box - this situation can occur in unusual circumstances (such as a system shutdown or OS error). If you are waiting more than a minute or two for a table to be unlocked, then it is advised to follow the process below. + +## Unlock Process + +Before proceeding with an unlock, the first step should be to understand why the process is locked. By opening the [mpe_lockanytable](locking-mechanism) it will be possible to see which user performed the lock, and when. Simply filter the table where `LOCK_STATUS_CD='LOCKED'`. + +![](/img/mpe_lockanytable.png) + +If an unlock is deemed necessary, simply open this table in the EDIT menu, and change the value from UNLOCKED to LOCKED. + +## Scalability + +This locking mechanism does not scale well if the table remains in SAS dataset (.sas7bdat) form. If you are deploying Data Controller for usage beyond 10-20 users then you are advised to put the control tables (DC library) in a database. + +## Third Party Applications + +Third party SAS apps may also make use of this locking table. This is handled by simply: + +1. Ensuring the DC library is assigned in the Service +2. Using the [mp_lockanytable](https://core.sasjs.io/mp__lockanytable_8sas.html) macro to perform the lock +3. Using the [mp_lockanytable](https://core.sasjs.io/mp__lockanytable_8sas.html) macro to perform the unlock +4. Performing appropriate error handling to ensure an unlock if there are any issues in the service diff --git a/docs/tables/mpe_lockanytable.md b/docs/tables/mpe_lockanytable.md new file mode 100644 index 0000000..18f412b --- /dev/null +++ b/docs/tables/mpe_lockanytable.md @@ -0,0 +1,28 @@ +--- +layout: article +title: MPE_LOCKANYTABLE +description: The MPE_LOCKANYTABLE table provides a mechanism for a process to secure a logical 'lock' on an object to avoid conflicts when running the application with multiple users in parallel +og_image: https://docs.datacontroller.io/img/mpe_lockanytable.png +--- + +# MPE_LOCKANYTABLE + +The `MPE_LOCKANYTABLE` table provides a mechanism for a process to secure a logical 'lock' on an object to avoid conflicts when running the application with multiple users in parallel. + +The underlying utility is open source and documented [here](https://core.sasjs.io/mp__lockanytable_8sas.html). + +For more information, see the [locking mechanism guide](https://docs.datacontroller.io/locking-mechanism). + +![locking](/img/mpe_lockanytable.png) + +## Columns + + - 🔑 `LOCK_LIB char(8)`: SAS Libref (8 chars) + - 🔑 `LOCK_DS char(32)`: The dataset name + - `LOCK_STATUS_CD char(10)`: Either LOCKED or UNLOCKED + - `LOCK_USER_NM char(100)`: The logged-in user who performed the lock or unlock + - `LOCK_REF char(200)`: Description of the lock purpose + - `LOCK_PID char(10)`: The value of the automatic `sysjobid` macro variable + - `LOCK_START_DTTM num`: The timestamp when the record was LOCKED + - `LOCK_END_DTTM num`: The timestamp when the record was UNLOCKED. This is set to missing whilst the record is locked. + diff --git a/mkdocs.yml b/mkdocs.yml index 2f43e0d..7763dee 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -9,6 +9,7 @@ nav: - Data Lineage: dcu-lineage.md - File Uploads: dcu-fileupload.md - Filter Mechanism: filter.md + - Locking Mechanism: locking-mechanism.md - Table Viewer: dcu-tableviewer.md - Admin Services: admin-services.md - Table Guide: