READ - unit-oriented block I/O.

Alternate Entry: RAW.RD

Usage:

B:
   status = read( [unit,] buffer [, sector [, nwds] ] );

C:
   int read( [FILE *unit,] void *buffer,
            [int sector[, int nwds]]);

Where:

unit

indicates the unit number on which I/O will be performed. The unit must be open. If "unit" is not specified, it defaults to the current read unit.

buffer

points to the first word of a buffer into which READ places the data it reads. "buffer" must be big enough to hold "nwds".

sector

is the starting sector address in the file which is being read. A sector is 64 words long and the first sector of the file has an address of zero. If "sector" is omitted a default value of zero is assumed. For sequential files and tapes, "sector" is ignored unless you specified the "zi" option when you opened the file with OPEN. For linked files, the read operation advances the file pointer by the number of llinks accessed. "sector" must be supplied for random files. For tape files, "sector" should be zero. If "sector" is 04000000000, then the next sequential sector is used on either random or sequential files.

nwds

is the number of words to read. This is discussed below. If "nwds" is not specified, the default is 320 words.

status

is the number of words read, if the I/O operation is successful. If an I/O error occurs, and the unit was opened with the "e" action to prevent the error ending the program, "status" receives the negative of the major I/O status.

Description:

READ performs binary I/O on random or sequential disk files or tapes which have been opened by a call to OPEN. Buffer Sizes: For a random disk file, "nwds" may be any non-zero value. However, if it is not a multiple of 64 when writing, the hardware will fill the remainder of the last sector with zeroes. The file pointer will be advanced (words+63)/64 sectors (where "words" is the number of words transfered, normally "nwds").

For a sequential disk file, "nwds" would normally be a non-zero multiple of 320. It must be less than or equal to 20160 (63 llinks). The file pointer will be advanced by (words+319)/320 llinks (where "words" is the number of words read, normally "nwds").

For a tape, "nwds" must be a non-zero value.

Notes:

READ may return zero, indicating that an EOF was encountered. A second read at the same location will raise a physical EOF error.

When "status" is negative indicating an error was raised, and the file was opened with the "e" option, the A-register will contain the number of words transfered before the error. B users can retrieve this with a call to .NULL; C users can define the functions as returning a two-word struct.

When "unit" is in an error state, a call to READ will fail immediately without actually attempting a new I/O. Any error must be cleared from the unit before a call to READ can proceed.

See Also:

expl b lib write

for unit-oriented block output.

expl b lib .grow

for the details of the file growth algorithm.

expl c lib _rblock, expl c lib _wblock

For alternative routines for the C user.

Copyright © 1993,1997 Thinkage Ltd.