Enscribe Programmer's Guide

blocks interspersed among in-use blocks. When you are adding data to a key-sequenced file, the
EOF pointer increments each time a new block is added because there are no empty blocks.
The system maintains a working copy of the file's EOF pointer in the file control blocks (FCBs) that
are in both the primary and backup system processes that control the associated disk volume. For
Enscribe key-sequenced files, the EOF pointer is physically written to the disk when any of these
events occurs: any file label field is changed, the last accessor closes the file, the DISK_REFRESH_
system procedure is called for the file or the REFRESH command is executed for the file's volume.
Sequential Access
You perform sequential processing, in which a related subset of records is read in ascending order
within the current access path, by using the FILE_READ64_, FILE_READLOCK64_, READ and
READLOCK system procedures.
The records comprising a subset are indicated by the file's current positioning mode: approximate,
generic, or exact. A subset can be all or part of a file, or it can be empty. An attempt to read
beyond the last record in a subset, or to read an empty subset, returns an EOF indication.
The first call to FILE_READ64_, FILE_READLOCK64_, READ or READLOCK after a file-opening or
positioning operation reads the record (if any) at the current position. Subsequent calls to
FILE_READ64_, FILE_READLOCK64_, READ or READLOCK, without intermediate positioning, return
successive records (if any) in the designated subset.
After each call to FILE_READ64_, FILE_READLOCK64_, READ or READLOCK, the position of the
returned record becomes the current position.
Random Access
You perform random access processing by using the FILE_READUPDATE64_,
FILE_WRITEUPDATE64_, FILE_READUPDATELOCK64_, FILE_WRITEUPDATEUNLOCK64_,
READUPDATE, WRITEUPDATE, READUPDATELOCK, and WRITEUPDATEUNLOCK system procedures.
The update operation occurs at the record indicated by the current position. Random processing
implies that a record to be updated must exist. Therefore, if no record exists at the current position
(as indicated by an exact match of the current key value with a value in the key field designated
by the current-key specifier), the file system returns error code 11 (record not found).
You cannot use FILE_WRITEUPDATE64_, FILE_WRITEUPDATEUNLOCK64_, WRITEUPDATE or
WRITEUPDATEUNLOCK to alter a record's primary key. If you need to do so, you must first delete
the record and then reinsert it (using a FILE_WRITE64_/WRITE call) with the new key value.
If updating or locking is attempted immediately after a call to FILE_SETKEY_ or KEYPOSITION
where a non-unique alternate key is specified, the updating or locking fails with an error 46 (invalid
key). However, if an intermediate call to FILE_READ64_, FILE_READLOCK64_, READ or READLOCK
is performed, then the updating or locking is permitted.
Inserting Records
You perform record insertion by using the FILE_WRITE64_/WRITE system procedure. Insertion
requires that no other record exists with the same primary-key value as the record being inserted.
Therefore, if such a record already exists, the operation fails with an error 10 (record already
exists). If the operation is part of a TMF transaction, the record is locked for the duration of the
transaction.
If an alternate key has been declared to be unique and an attempt is made to insert a record
having a duplicate value in such an alternate-key field, the operation fails with an error 10 (record
already exists).
Insertion of an empty record (where the write count parameter of the FILE_WRITE64_/WRITE call
is zero) is not valid for key-sequenced files.
The length of a record to be inserted must be less than or equal to the record length defined for
the file; if it is not, the insertion fails with an error 21 (invalid count).
86 Key-Sequenced Files