FREAD

Syntax

  I16                     I16V     UDS     I16V
  transfercount := FREAD (filenum, buffer, length);

Functional Return

transfercount

16-bit signed integer (assigned functional return)

Returns the length of the data transferred to buffer:

• If a negative value is passed in the length parameter, transfercount is a positive value indicating the number of bytes transferred.

• If a positive value is passed in the length parameter, transfercount is a positive value indicating the number of half words transferred.

• If nowait I/O is specified in FOPEN/HPFOPEN, a zero is returned. The record length is returned in the length parameter of the IOWAIT or IODONTWAIT intrinsic.

NOTE: If the file was opened with the nowait I/O option enabled, transfercount is zero. The IOWAIT intrinsic can be used to determine the length of the data transferred.

Parameters

filenum

16-bit signed integer by value (required)

Passes the file number of the file to be read. If filenum references a directory node, FREAD fails with a CCL file code.

buffer

user-defined structure (required)

Returns the record that was read. This structure must be large enough to hold all of the information to be transferred.

length

16-bit signed integer by value (required)

Passes the length of the data to be transferred to buffer:

Value	Meaning
< 0	Length in bytes
= 0	No transfer occurs
> 0	Length in half words

If length is larger than the size of the logical record, and the multirecord aoption in FOPEN/HPFOPEN was not specified, transfer is limited to the length of the logical record. If the multirecord aoption in FOPEN/HPFOPEN is specified, transfer continues until either length is satisfied or end-of-data is encountered, and each transfer begins at the start of the next physical record (block). Any data remaining in the last physical record read is inaccessible. Data transfer for byte stream files continues until either length bytes are read or an end-of-file occurs.

Operation Notes

• On magnetic tape, the end-of-data is a physical indicator such as a tape mark. When the program reads a file that spans more than one volume of labeled magnetic tape, the program is suspended until an operator mounts the next tape. CCG (0) is not returned when end-of-tape is encountered.

• On disk, the end-of-data occurs when there is an attempt to read past the last logical record of the file. In this case, CCG (0) is returned, and no record is read.

• If the file is embedded in an input source containing commands, an end-of-data occurs when an EOD command is encountered. End-of-data is indicated by a hardware end-of-file, including EOF (on $STDIN), any record beginning with a colon (:), or on $STDINX, by EOD.

• On a standard input device for a job (not a session) JOB, EOJ, or DATA indicate end-of-data.

  +-+----------------------------+
  |C|                            |
  |C|         Data Read          |
  |B|                            |
  +-+----------------------------+

  CCB = Carriage Control Byte

Condition Codes

Related Information