LOCKTABLE Function (Record)

Locks a C/SIDE table to protect it from write transactions that conflict with each other.

Record.LOCKTABLE([Wait] [, VersionCheck])



Type: Record

The record that refers to the table that you want to lock.


Type: Boolean

Specifies what to do if the table is already locked.

If this parameter is true and if another application has already locked the table, the system will wait until the table is unlocked.

If this parameter is false and if another application has already locked the table, a run-time error occurs.


Type: Boolean

If this parameter is true, the version will be checked. If this parameter is false, blank, or not used, the version will not be checked.

Because all write operations automatically lock the table in use, LOCKTABLE would appear unnecessary. However, you could have a transaction in which an application wants to inspect data and then only possibly change it, with a guarantee that the data being changed has not been modified by other applications since the read operation. The solution is to explicitly lock the table before the read operation. This ensures that no other application makes changes between the read operation and the possible write operation.

The SQL Server Option for Microsoft Dynamics NAV only supports the default values for the parameters of the LOCKTABLE function – LOCKTABLE(TRUE,FALSE). From the point where it takes effect, the LOCKTABLE function causes all operations on the table to be SERIALIZABLE. If [Wait] is set to false, it will be ignored. You must set [VersionCheck] to false otherwise an error will occur.

This example shows how to use the LOCKTABLE function without the VersionCheck parameter.

This example uses pseudo-language to show the scope of write locks. Both an explicit lock and an automatic lock are illustrated.

The first line (1) explicitly locks table A. If this explicit lock was not set on table A, the Database Management System (DBMS) would automatically lock this table when a record was inserted (3). Table B is not locked explicitly, but is locked automatically by the DBMS when a record is inserted (4). Both locks are active until the system exits the C/AL code module (5).

LockTable(TableA) // (1)
FindRec(TableA, ...) // (2)
InsertRec(TableA,...) // (3)
InsertRec(TableB) // (4)
EndWriteTransaction // (5)

This example shows how to use the LOCKTABLE function with the VersionCheck parameter.

If a data update depends on a prior read operation and there is a long time between the read operation and the write operation, you may not want to lock the table as you usually would during a transaction. This enables you to avoid preventing other users from updating the table until your transaction is committed. You can do this by using the VersionCheck parameter, which compares time stamps to check if a record has been changed.

Customer.GET('AAA 1050'); // Reading at 10:00. 
// Time stamp automatically set to 10:00
Customer.LOCKTABLE(TRUE, TRUE); // Start write transaction at 10:15
. // A run-time error occurs if the time stamp on Customer in the data
. // version used in the transaction differs from the time stamp made
. // the last time you read the record before the write transaction
. // started.
{End write transaction}

When the VersionCheck parameter is true, the MODIFY Function (Record) compares the time stamp of the record that you modify within a transaction with the time stamp made the last time you read the record before the transaction started. If these time stamps differ, the record was changed after you read it and before you locked the table. If this occurs, an error message is displayed.

Community Additions