Function FRead() | Xbase++ | Alaska Software

Functions and Directives Functions and Directives

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

FRead( <nHandle>, @<cBuffer>, <nBytes> ) --> nBytes

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

Constant	Description
FH_STDIN	Standard input
FH_STDOUT	Standard output
FH_STDERR *)	Standard error
Not supported by Windows 95

<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> specifies the number of characters to read from the file.

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.

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.

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

Function FRead() Foundation