Enscribe Programmer's Guide

When you are writing data records, a succession of FILE_WRITE64_/WRITE calls writes data to
successively higher physical records in the file. Note that FILE_WRITE64_/WRITE will only write
data to empty physical records. If you attempt to FILE_WRITE64_/WRITE to a physical record that
already contains data, the operation fails with an error 10 (record already exists).
Upon completion of each FILE_READ64_, FILE_READLOCK64_, FILE_WRITE64_, READ, READLOCK,
or WRITE call, the current-record pointer is set to the present value of the next-record pointer (thereby
pointing to the record that was just read or written) and the next-record pointer is incremented to
point to the next higher physical record in the current access path.
When reading or writing sequentially by primary key, you can access different subsets of physical
records by using the FILE_SETPOSITION_ or POSITION system procedure calls. After each
FILE_SETPOSITION or POSITION call, the next FILE_READ64_, FILE_READLOCK64_, FILE_WRITE64_,
READ, READLOCK, or WRITE call accesses the physical record that you positioned to, and
subsequent FILE_READ64_, FILE_READLOCK64_, FILE_WRITE64_, READ, READLOCK, or WRITE
calls access successively higher physical records in the file.
When reading or writing sequentially by a particular alternate key, you can reposition to the start
of a new alternate-key access path using the FILE_SETKEY_ system procedure. After each
FILE_SETKEY_ call, the next FILE_READ64_, FILE_READLOCK64_, READ or READLOCK call retrieves
the first (lowest) physical record in the file that contains the specified key value in the alternate-key
field identified by the particular key specifier; subsequent FILE_READ64_, FILE_READLOCK64_,
READ or READLOCK calls retrieve successively higher physical records in the particular access
path.
Random Access
The update procedures FILE_READUPDATE64_, FILE_WRITEUPDATE64_,
FILE_READUPDATELOCK64_, FILE_WRITEUPDATEUNLOCK64_, READUPDATE, WRITEUPDATE,
READUPDATELOCK, and WRITEUPDATEUNLOCK, when used in conjunction with
FILE_SETPOSITION_, provide random access to Enscribe relative files. The updating operation
occurs at the record indicated by the current-record pointer. Random processing implies that a
record to be updated must exist. If the physical record indicated by the current-record pointer is
empty, the operation fails with an error 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 by using a FILE_WRITEUPDATE64_/WRITEUPDATE call with a write count of zero, and
then insert the record into the desired physical record by using a FILE_SETPOSITION_ call followed
by a FILE_WRITE64_/WRITE call.
If updating is attempted immediately after a call to FILE_SETKEY_ where a nonunique alternate key
is specified, the operation fails with an error 46 (invalid key). However, if you issue an intermediate
call to FILE_READ64_, FILE_READLOCK64_, READ or READLOCK, updating is then permitted.
Inserting Records
You insert data records into a relative file by using the FILE_WRITE64_/WRITE system procedure.
The data record is written to the physical record indicated by the next-record pointer. Note that,
for relative files, insertion requires that the referenced physical record be empty; if it is not, the
operation fails with an error 10 (duplicate record).
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 (duplicate
record).
Insertion of an empty record (one where write-count = 0) is not valid for relative 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, then the insertion fails with an error 21 (invalid count).
146 Relative Files