MPE/iX Intrinsics Reference Manual > Chapter 6 Command Definitions (FLUSHLOG-GETUSERMODE)

FREAD

	MPE documents
	Complete PDF
	Table of Contents
	Index

	Edition 7 E0701
	Edition 7 E0300 ♥
	Edition 6 E0195

NM and CM callable.

Reads a logical record or portion of a record from a file to the stack.

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

When the logical end-of-data is encountered, CCG (0) is returned to the process:

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 labele 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.

When reading from an empty message file and another process has opened that file for write access, the process waits. If the message file is empty and there are no writers, the process waits if there is an FCONTROL=45 in effect or if this is the first FREAD after the reader's FOPEN/HPFOPEN. Otherwise, CCG (0) is returned. If an FREAD is issued against a message file and an FCONTROL=46 is in effect, the writer's ID and the record type code are appended to the beginning of the record.

When an old file containing carriage-control characters supplied through the controlcode parameter of the FWRITE intrinsic is read, and you specified either the carriage-control foption parameter of the FOPEN/HPFOPEN intrinsic, or the CCTL parameter of the FILE command, the carriage-control byte is read as follows:

Figure 6-1 Carriage Control Byte


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

  CCB = Carriage Control Byte

Condition Codes

CCE (2): Request granted. The information was read.
CCG (0): Request denied. The logical end-of-data was encountered during reading. When reading a labeled magnetic tape file that spans more than one volume, CCG (0) is not returned when end-of-tape (EOT) is encountered. CCG (0) is returned at actual end-of-file, with a transmission log of 0 if there is an attempt to read past end-of-file.
CCL (1): Request denied. The information was not read because a terminal read was terminated by a special character or timeout interval, as specified in the FCONTROL intrinsic, or a tape error was recovered and the FSETMODE option was enabled. Check the condition codes both in normal I/O and in nowait I/O.

Related Information

Manual: Accessing Files Programmer's Guide

FPOINT

FREADBACKWARD