Enscribe Programmer's Guide

Record Locking Requests and Alternate Key Files
An application request to lock a record requires a file number as input. The file number is necessarily
that of the primary file, since the application has no file number for any alternate key file.
If the request is FILE_READ[UPDATE]LOCK64_, READ[UPDATE]LOCK, FILE_LOCKREC64_ or
LOCKREC, Enscribe locks the referenced primary file record but does not lock any alternate key
records. There is no need to do so as long as the alternate key record is not being changed.
If the request is FILE_WRITEUPDATE[UNLOCK]64_/WRITEUPDATE[UNLOCK], Enscribe locks any
affected alternate key records. For audited files, the locks are held until the transaction commits or
aborts. For unaudited files, the locks are released when the application unlocks the corresponding
primary record.
If the request is FILE_WRITE64_/WRITE and the file is audited, Enscribe locks inserted alternate
key records and holds the locks until the transaction commits or aborts. If the request is
FILE_WRITE64_/WRITE and the file is unaudited, Enscribe does not lock inserted alternate key
records unless SETMODE 149,1 is in effect, in which case alternate key records are locked upon
insertion and unlocked when insertion of the primary record and all of its alternate key records
have completed.
Implementation of Updates to Alternate Key Records
Deletion/Insertion Sequence
If a null value is defined for an alternate key and an application updates that alternate key field
from a non-null value to the null value, Enscribe deletes the corresponding alternate key record. If
a null value is defined for an alternate key and an application updates that alternate key field from
the null value to a non-null value, Enscribe inserts a corresponding alternate key record.
If an application updates an alternate key field from one non-null value to another, Enscribe deletes
the corresponding old alternate key record and inserts a new one. The deletion/insertion sequence
is necessary because the alternate key value is part of the primary key of the alternate key file,
and primary keys cannot be updated.
Transaction Aborts, Alternate Keys, and Locks
Backout of an aborted transaction executes asynchronously with respect to running applications.
Because backout of alternate key insertions and deletions requires corresponding deletions and
insertions which the system must protect with internally generated locks, transaction aborts can
cause alternate key records to be locked and unlocked asynchronously with respect to an
application's locking and unlocking of records in the primary file. In particular, it is possible for
one process to have a primary record locked and for the system to lock a corresponding alternate
key record on behalf of an aborting transaction of another process.
SETMODE 4 (Set Lock Mode) and Alternate Key Files
The SETMODE procedure call requires a file number as input. The file number is necessarily that
of the primary file, since the application has no file number for any alternate key file.
Enscribe propagates SETMODE 4 to all alternate key files. Enscribe also propagates SETMODE
4 to all secondary partitions of the primary file and alternate key files if any are partitioned.
SETMODE 4,6 and SETMODE 4,7 (Read through Lock with Warning)
Both SETMODE 4,6 and 4,7 allow FILE_READ64_, FILE_READUPDATE64_, READ and READUPDATE
to read locked records. Such reads complete with warning code 9. With SETMODE 4,6 in effect,
FILE_LOCKFILE64_, FILE_LOCKREC64_, LOCKFILE, LOCKREC, FILE_READ[UPDATE]LOCK64_,
READ[UPDATE]LOCK, FILE_WRITE[UPDATE][UNLOCK]64_, and WRITE[UPDATE][UNLOCK]
requests wait for lock release if the record or file in question is locked; with SETMODE 4,7, such
requests are rejected with error 73.
36 Positioning Within Structured Files