Enscribe Programmer's Guide

Note that if generic locking is enabled for a key-sequenced file, the FILE_LOCKREC64_/LOCKREC
procedure also locks any other records in the file whose keys begin with the same character
sequence as the key of the referenced record. Generic locking applies only to key-sequenced files.
If both the referenced record and its file are unlocked (or the existing locks belong to you) when
you call FILE_LOCKREC64_, FILE_READLOCK64_, FILE_READUPDATELOCK64_, LOCKREC,
READLOCK, or READUPDATELOCK, the lock is granted and your application process continues
execution.
If either the referenced record or its file is locked through a different file number or transid when
you call FILE_LOCKREC64_, FILE_READLOCK64_, FILE_READUPDATELOCK64_, LOCKREC,
READLOCK, or READUPDATELOCK, the action taken depends upon the locking mode that is in
effect at the time of the call.
These procedures unlock records within a file:
• FILE_UNLOCKREC64_/UNLOCKREC unlocks the current record, as determined by the most
recent operation against the file.
• FILE_UNLOCKFILE64_/UNLOCKFILE unlocks all of the records in the specified file that were
locked through the file number or transid associated with the
FILE_UNLOCKFILE64_/UNLOCKFILE call. In addition, if the file itself is locked through that
same file number or transid, FILE_UNLOCKFILE64_/UNLOCKFILE releases the file lock as
well.
• For nonaudited files, FILE_WRITEUPDATEUNLOCK64_/WRITEUPDATEUNLOCK releases the
associated record lock after writing or deleting the record.
• For audited files, ENDTRANSACTION unlocks all of the records that the transaction had locked
but does not do so until the transaction has been either committed or aborted and backed
out.
• For nonaudited files, FILE_CLOSE_ unlocks all of the records that were locked through the file
number associated with the call.
Note that if generic locking is enabled for a key-sequenced file, calls to the
FILE_UNLOCKREC64_/UNLOCKREC procedure are ignored.
When you delete a record from a nonaudited file, the record lock is released immediately. When
you delete a record from an audited file, however, the lock is not released until the transaction has
been either committed or aborted and backed out.
Record locking provides maximum concurrency of access to a file while still guaranteeing the
logical consistency of the file's content. However, for complex updating operations involving many
records, record locking can involve a lot of system processing, consume a lot of memory required
by the locks, and increase the possibility of deadlock. In such cases, file locking might be preferable.
Generic Locking
In addition to locking entire files or individual records within files, you can lock sets of records
within key-sequenced files whose keys all begin with the same character sequence. This is referred
to as generic locking.
You enable generic locking by issuing a SETMODE 123 procedure call that defines a generic lock
key length that is shorter than the key length defined for the particular file. You disable generic
locking by issuing a SETMODE 123 procedure call that defines a generic lock key length that is
either zero or equal to the key length defined for the particular file.
When generic locking is disabled, a record lock obtained with the FILE_UNLOCKREC64_/LOCKREC
file-system procedure locks a single record by locking the specific key of that record.
When generic locking is enabled, a record lock obtained with the FILE_UNLOCKREC64_/LOCKREC
procedure locks all of the records whose keys begin with the same byte string.
Note that when generic locking is enabled for a particular file, it applies to all opens of that file.
152 File and Record Locking