FOPEN()
 Abre um arquivo binário
------------------------------------------------------------------------------

 Sintaxe

     FOPEN(<cArq>, [<nModo>]) --> nHandle

 Argumentos

     <cArq> é o nome do arquivo a ser aberto que inclui o path caso haja
     um.

     <nModo> é o modo de acesso DOS solicitado que indica como o arquivo
     aberto deve ser acessado.  O acesso é de uma das categorias
     relacionadas na tabela abaixo.  O modo padrao é zero, somente para
     leitura.

     Tabela 5-18: Modos de Acesso a Arquivos Binários
     ------------------------------------------------------------------------
     Modo           Directry.ch          Operaçao
     ------------------------------------------------------------------------
     0              FO_READ              Aberto para leitura (assumido)
     1              FO_WRITE             Aberto para gravaçao
     2              FO_READWRITE         Aberto para leitura e gravaçao
     ------------------------------------------------------------------------

 Retorno

     FOPEN() retorna o handle de arquivo do arquivo aberto na faixa de zero
     a 65.535.  Caso ocorra um erro, FOPEN() retorna -1.

 Descriçao

     FOPEN() é uma funçao de tratamento de arquivo de baixo nível que abre
     um arquivo binário existente para que este possa ser lido e escrito,
     dependendo do argumento <nModo>.  Toda vez que houver um erro na
     abertura do arquivo, FERROR() pode ser usado para retornar o código de
     erro do DOS.  Por exemplo, caso o arquivo nao exista, FOPEN() retorna
     -1 e FERROR() retorna 2 para indicar que o arquivo nao foi encontrado.
     Veja FERROR() para uma lista completa dos códigos de erro.

     Caso o arquivo especificado seja aberto, o valor retornado é o handle
     DOS para o arquivo.  Este valor é semelhante a um alias no sistema de
     banco de dados, e ele é exigido para identificar o arquivo aberto para
     as outras funçoes tratamento de arquivo.  Portanto, é importante sempre
     atribuir o valor que foi retornado a uma variável para uso posterior,
     como mostra o exemplo abaixo.

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

 Notas

       Acessando arquivos em outros diretórios: FOPEN() nao
        obedece a SET DEFAULT nem a SET PATH.  Ao invés disso, ela procura
        na configuraçao de diretório e path DOS corrente a nao ser que um
        path seja declarado explicitamente como parte do argumento <cArq>.

 Exemplos

     O exemplo a seguir utiliza FOPEN() para abrir um arquivo com status
     ler/escrever e exibe uma mensagem de erro caso a abertura falhe:

     #include "Fileio.ch"
     //
     nHandle := FOPEN("Temp.txt", FO_READWRITE)
     IF FERROR() != 0
        ? "Erro de abertura, erro DOS", FERROR()
        BREAK
     ENDIF

 Arquivos:  Biblioteca CLIPPER.LIB, arquivo header Fileio.ch.
 To download this example - click here.

See Also: FCLOSE() FCREATE() FERROR()