FREAD()
 Lê caracteres de um arquivo binário para uma variável de buffer
------------------------------------------------------------------------------

 Sintaxe

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

 Argumentos

     <nHandle> é o handle de arquivo obtido de FOPEN(), FCREATE(), ou
     pré-definido pelo DOS.

     <cBufferVar> é o nome de uma variável do tipo caractere já
     existente e inicializada, utilizada para armazenar dados lidos do
     arquivo especificado.  O tamanho desta variável deve ser maior ou igual
     a <nBytes>.  <cBufferVar> é passada por referência e portanto deve ser
     precedida pelo operador de passagem por referência (@).

     <nBytes> é a quantidade de bytes a serem lidos para o buffer.  O
     valor retornado por um FREAD() bem sucedido deve ser igual a <nBytes>.

 Retorna

     FREAD() retorna a quantidade de bytes lidos na forma de um valor
     numérico inteiro.  Um valor de retorno menor que <nBytes> ou zero
     indica final de arquivo ou algum outro erro de leitura.

 Descriçao

     FREAD() é uma funçao de tratamento de arquivos de baixo nível que lê
     caracteres de um arquivo binário para uma variável do tipo caractere
     existente.  Ela começa a ler a partir do arquivo onde estiver
     posicionado o ponteiro de arquivos do DOS, avançando o ponteiro de
     arquivos pela quantidade de bytes lidos.  Todos os caracteres sao
     lidos, inclusive caracteres de controle, nulos, e caracteres da tabela
     ASCII que tenham valor acima de 127.

     FREAD() é semelhante em alguns aspectos a FREADSTR() e FSEEK().
     FREADSTR() lê uma quantidade de bytes especificada a partir de um
     arquivo até o próximo caractere nulo (CHR(0)).  FSEEK() apenas move o
     ponteiro de arquivos, sem fazer a leitura.

     Caso haja um erro durante a leitura do arquivo, FERROR() retorna o
     código de erro DOS.  Consulte em FERROR() a relaçao de códigos de erro.

     -----------------------------------------------------------------------
     . Aviso

     Esta funçao permite acesso de baixo nível a arquivos e dispositivos
     DOS.  Ela deve ser utilizada com extremo cuidado e exige que se conheça
     a fundo o sistema operacional.
     -----------------------------------------------------------------------

 Exemplos

     O exemplo a seguir utiliza FREAD() após a abertura de um arquivo para
     ler 128 bytes para uma área de buffer:

     #define F_BLOCK  128
     //
     cBuffer := SPACE(F_BLOCK)
     nHandle := FOPEN("Temp.txt")
     //
     IF FERROR() != 0
        ? "Erro de abertura, erro:", FERROR()
     ELSE
        IF FREAD(nHandle, @cBuffer, F_BLOCK) <> F_BLOCK
           ? "Erro de leitura em Temp.txt"
        ENDIF
     ENDIF

 Arquivos:  Biblioteca CLIPPER.LIB.
 To download this example - click here.

See Also: BIN2I() BIN2L() BIN2W() FERROR() FWRITE()