Enscribe Programmer's Guide

The length of the generic lock key length must be less than the length of the entire key. Note that
there are now two key lengths: the overall key length defined at file creation time and the generic
lock key length; each is defined on a per-file basis.
Consider this example:
File X is a key-sequenced file with a defined key length of 6. It contains records with these keys:
Aabcde
A1aabb
A2bbbb
A21ccc
A27def
B4dddd
B5abcd
C9dddd
If generic locking is enabled with a generic lock key length of 2, locking the record A2bbbb with
a FILE_UNLOCKREC64_/LOCKREC procedure call locks these subset of records:
A2bbbb
A21ccc
A27def
Note that the records containing the keys A21ccc and A27def are also locked because the first
two bytes of their record keys are identical to those of the locked record (A2bbbb). The records
containing the keys Aabcde and A1aabb are not locked, however, because the first two bytes of
their record keys do not exactly match those of the locked record.
The generic lock key length is stored in the file label and can be modified with SETMODE 123
procedure calls.
You can obtain the current generic lock key length programmatically by using the
FILE_GETINFOLIST_ system procedure. You can also obtain the current generic lock key length
interactively by using the File Utility Program (FUP) INFO command or change it interactively by
using the FUP ALTER command.
Generic locking is activated whenever the generic lock key length is nonzero and less than the
key length of the file. Note that the generic lock key length is initialized to the defined key length
of the file so that generic locking is initially deactivated.
The lengths of all generic key locks possible at any one time on a file is a constant. This means
that the generic lock key length cannot be changed if there are currently any locks in effect for the
file.
When generic locking is activated, calls to the FILE_UNLOCKREC64_/UNLOCKREC procedure
are ignored. Thus, with generic locking activated, you cannot unlock records either generically or
individually. You can, however, unlock all records in the file with the
FILE_UNLOCKFILE64_/UNLOCKFILE procedure.
The decision whether or not to use generic key locking should be made on a per-file basis and
applies to all processes that lock records in that file. Therefore, you should carefully analyze all
application programs that use that file to be certain that the benefits of generic locking to one
application are not offset by drawbacks to another application.
The applications that benefit the most from generic locking are those that need to concurrently lock
a set of records that together form a generic subset. One generic lock could potentially replace
hundreds or thousands of individual record locks. In some application environments, the use of
generic locking could both improve performance (because there will be fewer calls to the lock
manager to allocate, deallocate and search locks) and reduce memory use (because there are
fewer locks).
Applications that should not use generic locking are those that lock individual, unrelated records.
Note that if one process owns a generic lock on a subset of records and a second process tries to
insert a record into that subset, the attempted insertion will fail and the second process will get an
error 73 (file/record is locked) whether or not the record actually exists.
Generic Locking 153