Function FReadStr() | Xbase++

Reads a character string from a file stopping at an occurrence of Chr(0).

FReadStr( <nHandle>, <nBytes> ) --> cString

<nHandle> is an integer numeric value returned from either FCreate() or FOpen(). It is the file handle of the file provided by the operating system.

<nBytes> specifies the maximum number of characters to read from the file.

FReadStr() returns the character string read from the file. If a read error occurs or if the end of the file is reached, a null string ("") is returned.

The low level file function FReadStr() reads characters from a file into a memory variable. A maximum of <nBytes> characters are read starting at the current file pointer position. The file pointer is moved forward <nBytes>. FReadStr() differs from the function FRead() in that the memory variable which accepts the character string from the file does not need to be initialized. Also, FReadStr() terminates the read process if it reaches an ASCII character null (Chr(0)) in the file.

Comparison of FReadStr() and FRead()


// In the example the read operations with FRead() and 
// FReadStr() are compared to one another. 

#include "Fileio.ch" 

PROCEDURE Main 
   LOCAL cBuffer, nHandle 

 * Create file and write character string into file with Chr(0) 
   nHandle := FCreate( "NEWFILE.TXT", FC_NORMAL ) 
   FWrite( nHandle , "James" + Chr(0) + "Bond's BMW" ) 
   FClose( nHandle ) 

   nHandle  := FOpen( "NEWFILE.TXT" , FO_READ ) 

   ? cBuffer := FReadStr( nHandle, 16 ) // result: James 
   ? Len( cBuffer )                     // result: 5 

 * Position of the file pointer after FReadStr() 
   ? FSeek(nHandle, 0, FS_RELATIVE ) // result: 16 

 * Back to the beginning of the file 
   ? FSeek(nHandle, 0, FS_SET )      // result: 0 

 * Read contents with FRead() 
   cBuffer  := Space(16) 
   ? FRead(nHandle, @cBuffer, 16)    // result: 16 
   ? cBuffer                         // result: James Bond's BMW 
   ? Len( cBuffer )                  // result: 16 

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

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.

Function FReadStr() Foundation