Function FRead() Foundation

Reads a character string from a file into a memory variable.

Syntax
FRead( <nHandle>, @<cBuffer>, <nBytes> ) --> nBytes
Parameters
<nHandle>
<nHandle> is an integer numeric value returned from either FCreate() or FOpen(). It is the file handle for the file provided by the operating system.
Alternatively, constants defined in FILEIO.CH can be specified for <nHandle>. They indicate a standard device.
Predefined file handles for standard devices
Constant Description
FH_STDIN Standard input
FH_STDOUT Standard output
FH_STDERR *) Standard error
  1. Not supported by Windows 95
<cBuffer>
<cBuffer> is the name of a memory variable. Before the call to FRead() it must already contain a character string (character buffer) long enough to hold the specified number of characters <nBytes>from the file. <cBuffer> must be passed by reference to the function FRead() so that the characters read from the file can be placed in this memory variable. The reference operator (@) must be placed in front of the argument <cBuffer> to do this.
<nBytes>
<nBytes> specifies the number of characters to read from the file.
Return

FRead() returns an integer numeric value. It corresponds to the number of bytes which could actually be read from the file. The return value should be the same as the value of <nBytes>. A return value less than <nBytes> indicates that the end of the file was reached or a read error occurred.

Description

The low level file function FRead() reads characters from a file into a memory variable previously initialized to be long enough to hold the data. <nBytes> characters are read starting at the current file pointer position.

The file pointer is moved forward <nBytes> by the read process, unless the end of the file is reached. FRead() reads all characters, including Chr(0), into the memory variable. This differs from the function FReadStr(), which stops reading characters from the file when the character Chr(0) is found. To move the file pointer without reading characters, the function FSeek() is used.

When FRead() reaches the end of the file, the function returns a value less than <nBytes> and the return value of the function FError() is zero. If an error occurs during the read, FRead() also returns a value less than <nBytes>, but FError() provides an error code not equal to zero.

Examples
FRead()
// In the example a file is created and a character string 
// is written into it. Then the character string is read 
// illustrating several possible possibilities for FRead(). 

#include "Fileio.ch" 

PROCEDURE Main 
   LOCAL cBuffer, nHandle, nBytes, nPointer 

   nHandle := FCreate( "NEWFILE.TXT", FC_NORMAL ) 
   FWrite( nHandle , "Xbase++" ) 
   FClose( nHandle ) 

   nHandle  := FOpen( "NEWFILE.TXT" , FO_READ ) 
   cBuffer  := Space(4) 
   nPointer := 0 

   ? nBytes   := FRead(nHandle, @cBuffer, 4) // result: 4 
   ? nPointer += nBytes                      // result: 4 
   ? cBuffer                                 // result: Xbas 

   ? nBytes   := FRead(nHandle, @cBuffer, 4) // result: 3 
   ? nPointer += nBytes                      // result: 7 
   ? cBuffer                                 // result: e++s 

   ? nBytes   := FRead(nHandle, @cBuffer, 4) // result: 0 
   ? nPointer += nBytes                      // result: 7 
   ? cBuffer                                 // result: e++s 

   ? FSeek(nHandle, -nPointer, FS_RELATIVE)  // result: 0 

   cBuffer  := "XXXXXXXXXX" 
   ? nBytes := FRead(nHandle, @cBuffer, 10)  // result: 7 
   ? cBuffer                                 // result: Xbase++XXX 

   FClose( nHandle ) 
   FErase( "NEWFILE.TXT" ) 
RETURN 

Feedback

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.