READ-FUNCTION (op-code 5)

This routine reads a record out of an indexed file. The READ routine has three parameters, f, record, and keynum.

F must be a valid file handle returned by OPEN.
Record points to the area to hold the record read.
Keynum    is the key number to read from. Key 0 is the primary key, key 1 is the first alternate and so on. The bytes in record corresponding to the key keynum must contain the key value of the record to be read. If this routine succeeds, RETURN-CODE is set to the size of the record read. RETURN-CODE is set to zero on failure.

Records read by a file open for input only are not locked. Furthermore, most file systems do not block the reading of locked records by a file open for input (Note that this feature depends on the host file system - not all can support it). Records read from a file open for I/O are automatically locked unless the external variable f-no-lock is set to a non-zero value first in which case they are treated in the same manner as files open for input.

If the key keynum allows duplicates and the next record in the file contains the same key value as the record read, the variable F-ERRNO is set to W-DUP-OK. This feature is not supported by many host file systems.

A successful READ causes the current key of reference to be set to keynum and the file position is set to the record read. This is used by the NEXT and PREVIOUS routines. If READ is unsuccessful, then the current key of reference is set to an undefined state.