HP 3000 Manuals HP 3000 Manuals
FREAD
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 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.
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:
_________________________________________
| |
| |
| +-+----------------------------+ |
| |C| | |
| |C| Data Read | |
| |B| | |
| +-+----------------------------+ |
| |
| CCB = Carriage Control Byte |
| |
_________________________________________
Figure 4-8. 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
Intrinsics None
Commands None
Manuals Accessing Files Programmer's Guide (32650-90017)