FOPEN()
 Open a binary file
------------------------------------------------------------------------------
 Syntax

     FOPEN(<cFile>, [<nMode>]) --> nHandle

 Arguments

     <cFile> is the name of the file to open, including the path if there
     is one.

     <nMode> is the requested DOS open mode indicating how the opened
     file is to be accessed.  The open mode is composed of elements from the
     two types of modes described in the tables below.  If just the Access
     Mode is used, the file is opened non-sharable.  The default open mode is
     zero, which indicates non-sharable and read-only.

     FOPEN() Access Modes
     ------------------------------------------------------------------------
     Mode    Fileio.ch      Operation
     ------------------------------------------------------------------------
     0       FO_READ        Open for reading (default)
     1       FO_WRITE       Open for writing
     2       FO_READWRITE   Open for reading or writing
     ------------------------------------------------------------------------

     The Sharing Modes determine how other processes may access the file.

     FOPEN() Sharing Modes 
     ------------------------------------------------------------------------
     Mode    Fileio.ch      Operation
     ------------------------------------------------------------------------
     0       FO_COMPAT      Compatibility mode (default)
     16      FO_EXCLUSIVE   Exclusive use
     32      FO_DENYWRITE   Prevent others from writing
     48      FO_DENYREAD    Prevent others from reading
     64      FO_DENYNONE    Allow others to read or write
     64      FO_SHARED      Same as FO_DENYNONE
     ------------------------------------------------------------------------

     The Access Modes in combination (+) with the Sharing modes determine the
     accessibility of the file in a network environment.

 Returns

     FOPEN() returns the file handle of the opened file in the range of zero
     to 65,535.  If an error occurs, FOPEN() returns -1.

 Description

     FOPEN() is a low-level file function that opens an existing binary file
     for reading and writing, depending on the <nMode> argument.  Whenever
     there is an open error, use FERROR() to return the DOS error number.
     For example, if the file does not exist, FOPEN() returns -1 and FERROR()
     returns 2 to indicate that the file was not found.  See FERROR() for a
     complete list of error numbers.

     If the specified file is opened successfully, the value returned is the
     DOS handle for the file.  This value is similar to an alias in the
     database system and is required to identify the open file to other file
     functions.  It is, therefore, important to assign the return value to a
     variable for later use as in the example below.

     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.

 Notes

     .  Accessing files in other directories: FOPEN() does not obey
        either SET DEFAULT or SET PATH.  Instead, it searches the current DOS
        directory and path setting unless a path is explicitly stated as part
        of the <cFile> argument.

 Examples

     .  This example uses FOPEN() to open a file with  sharable
        read/write status and displays an error message if the open fails:

        #include "Fileio.ch"
        //
        nHandle := FOPEN("Temp.txt", FO_READWRITE + FO_SHARED)
        IF FERROR() != 0
           ? "Cannot open file, DOS error ", FERROR()
           BREAK
        ENDIF

 Files   Library is CLIPPER.LIB, header file is Fileio.ch.