Enscribe Programmer's Guide

be inserted into any available position by supplying a record number of -2 to FILE_SETPOSITION_
before inserting records into the file. You can specify that subsequent records be appended to the
end of a file by supplying a record number of -1 to the FILE_SETPOSITION_ procedure.
For example, in a relative file in which only record number 10 contains data, you can position to
an empty location (such as record number 5) and use the WRITE procedure to insert a new record
in that location. If you position to record number -2, the record is written to some (not necessarily
the lowest) empty location. Using the READUPDATE procedure after positioning to an empty location
returns file-system error 11 (record not in file); the same positioning causes the READ procedure
to read the next nonempty record.
When -2 or -1 is specified for inserting records into a relative file, the actual record number
associated with the new record can be obtained through the FILE_GETINFOLIST_ procedure.
Relative files are best suited for applications where random access to fixed-length records is desired
and where the record number has some meaningful relationship to a particular piece of data within
each logical record. An inventory file, for example, could be a relative file with the part number
serving as the record number. Such usage, however, would probably be very wasteful of disk
space because part-numbering schemes often leave large gaps in the overall number sequence;
this could result in many records being allocated but not used. An invoice file with the invoice
number serving as the record number might be a better candidate for the relative file type because
there are typically no large gaps in that type of numbering scheme. In the latter case, because
your invoice numbers might begin at some large number such as 10000, you will likely have to
use an address conversion algorithm to generate a record number sequence that begins at zero
and then include the actual invoice number as a data field within the record.
Applicable System Procedures
• FILE_CREATE_, FILE_CREATELIST_
• FILE_OPEN_, FILE_CLOSE_, AWAITIO[X], FILE_AWAITIO64_
• FILE_LOCKFILE64_, FILE_LOCKREC64_, FILE_UNLOCKFILE64_, FILE_UNLOCKREC64_,
LOCKFILE, LOCKREC, UNLOCKFILE, UNLOCKREC
• FILE_SETKEY_, FILE_SETPOSITION_, POSITION, KEYPOSITION, SAVEPOSITION, REPOSITION
• FILE_READ64_, FILE_READLOCK64_, FILE_READUPDATE64_, FILE_READUPDATELOCK64_,
READ[X], READLOCK[X], READUPDATE[X], READUPDATELOCK[X]
• FILE_WRITE64_, FILE_WRITEUPDATE64_, FILE_WRITEUPDATEUNLOCK64_, WRITE[X],
WRITEUPDATE[X], WRITEUPDATEUNLOCK[X]
• FILE_GETINFO_, FILE_GETINFOLIST_, FILE_GETINFOBYNAME_, FILE_GETINFOLISTBYNAME_
Types of Access
You can refer to specific records within a relative file either by their primary key (relative record
number) or by the content of one or more alternate-key fields such as department number or zip
code, for example, in an employee file.
There are three major pointers associated with an Enscribe relative file:
Current-record pointer
Specifies the physical record that was most recently read from or written to.
Next-record pointer
Specifies the next physical record that will be read from or written to.
EOF pointer
Specifies the byte following the record with the highest address that currently contains data.
Note that the same EOF pointer value is shared by all opens of a particular file.
Applicable System Procedures 135