FREAD()
 Read characters from a binary file into a buffer variable
------------------------------------------------------------------------------
 Syntax

     FREAD(<nHandle>, @<cBufferVar>, <nBytes>) --> nBytes

 Arguments

     <nHandle> is the file handle obtained from FOPEN(), FCREATE(), or
     predefined by DOS.

     <cBufferVar> is the name of an existing and initialized character
     variable used to store data read from the specified file.  The length of
     this variable must be greater than or equal to <nBytes>.  <cBufferVar>
     must be passed by reference and, therefore, must be prefaced by the pass-
     by-reference operator (@).

     <nBytes> is the number of bytes to read into the buffer.

 Returns

     FREAD() returns the number of bytes successfully read as an integer
     numeric value.  A return value less than <nBytes> or zero indicates end
     of file or some other read error.

 Description

     FREAD() is a low-level file function that reads characters from a binary
     file into an existing character variable.  It reads from the file
     starting at the current DOS file pointer position, advancing the file
     pointer by the number of bytes read.  All characters are read including
     control, null, and high-order (above CHR(127)) characters.

     FREAD() is similar in some respects to both FREADSTR() and FSEEK().
     FREADSTR() reads a specified number of bytes from a file up to the next
     null (CHR(0)) character.  FSEEK() moves the file pointer without
     reading.

     If there is an error during the file read, FERROR() returns the DOS
     error number.  See FERROR() for the list of error numbers.

     Warning!  This function allows low-level access to DOS files and
     devices.  It should be used with extreme care and requires a thorough
     knowledge of the operating system.

 Examples

     .  This example uses FREAD() after successfully opening a file to
        read 128 bytes into a buffer area:

        #define F_BLOCK      128
        //
        cBuffer := SPACE(F_BLOCK)
        nHandle := FOPEN("Temp.txt")
        //
        IF FERROR() != 0
           ? "File open error:", FERROR()
        ELSE
           IF FREAD(nHandle, @cBuffer, F_BLOCK) <> F_BLOCK
              ? "Error reading Temp.txt"
           ENDIF
           FCLOSE(nHandle)
        ENDIF

 Files   Library is CLIPPER.LIB.

See Also: BIN2I() BIN2L() BIN2W() FCLOSE() FCREATE()