LockISAM() is designed to enforce the classic two-phase locking protocol, helping ensure multiple users make consistent updates. The two-phase protocol states that a transaction should never unlock a data record until it is done acquiring all the locks it needs for the entire transaction. In other words, there is a phase during which a transaction acquires record locks and does not free any locks and a second phase during which the transaction relinquishes locks and does not acquire any new locks.
When we refer to a transaction in this discussion, we are NOT referring specifically to Transaction Processing as described in “Data Integrity” on the FairCom Server. We are talking about any group of related actions when accessing a database. The concept discussed here, however, does apply to Transaction Processing as well.
With LockISAM(), the first phase is initiated when LockISAM() is called with the ctENABLE parameter. All subsequent record read operations first acquire a write lock before proceeding. As you can see, you will only need to do one LockISAM() call with the ctENABLE parameter to lock a number of records. If a subsequent call cannot get an appropriate lock on the record, that function will return a value of DLOK_ERR (42).
Note: LockISAM() with ctENABLE does NOT lock records, but enables record read operations to acquire locks.
If you use ctENABLE, and a lock cannot be obtained, the calling function returns with an error code. ctENABLE_BLK is the same as ctENABLE, but a process unable to get a write lock is “put to sleep” until the lock is available. Use this with caution.
Use ctREADREC instead of ctENABLE to specify read locks. Switch from ctENABLE to ctREADREC by another call to LockISAM() using the ctREADREC mode.
The second phase is essentially one operation that occurs when LockISAM() is called with the ctFREE parameter. All ISAM record locks currently held by this application are released a single function call.
LockISAM() with ctRESET is equivalent to two calls to LockISAM(), the first using ctFREE and the second with ctENABLE. This is of value when you are traversing the data file in key sequential order. After each update the previous locks are freed and new locks are enabled for the next transaction.
ctSUSPEND, ctRESTORE, ctRESTORED, and ctRESTORE_BLK
There may be situations during the first phase when it is desirable to read some records without acquiring locks on them, because these records will not be updated. In such cases, call LockISAM() with ctSUSPEND to temporarily disable automatic record locks. When the application is ready to begin reading records with locks again, call LockISAM() with the ctRESTORE parameter (or ctRESTORE_BLK to restore ctENABLE_BLK). Note that this does not violate the first phase restraint of only acquiring locks since no locks are freed in the ctSUSPEND mode. To return to the locking mode with read locks active instead of write locks, call LockISAM() with the ctRESTRED parameter. See “LockISAM” in the function reference section.
Returns the current LockISAM() state. See “LockISAM” for more information.