FCREATE()
 Create and/or truncate a binary file to zero-length
------------------------------------------------------------------------------
 Syntax

     FCREATE(<cFile>, [<nAttribute>]) --> nHandle

 Arguments

     <cFile> is the name of the file to create.  If the file already
     exists, its length is truncated to zero without warning.

     <nAttribute> is one of the binary file attributes shown in the table
     below.  If this argument is omitted, the default value is zero.

     Binary File Attributes
     ------------------------------------------------------------------------
     Value   Fileio.ch      Attribute Description
     ------------------------------------------------------------------------
     0       FC_NORMAL      Normal    Create normal read/write file (default)
     1       FC_READONLY    Read-only Create read-only file
     2       FC_HIDDEN      Hidden    Create hidden file
     4       FC_SYSTEM      System    Create system file
     ------------------------------------------------------------------------

 Returns

     FCREATE() returns the DOS file handle number of the new binary file in
     the range of zero to 65,535.   If an error occurs, FCREATE() returns
     -1 and FERROR() is set to indicate an error code.

 Description

     FCREATE() is a low-level file function that either creates a new file or
     opens and truncates an existing file.  If <cFile> does not exist, it is
     created and opened for writing.  If it does exist and can be opened for
     writing, it is truncated to zero-length.  If it cannot be opened for
     writing, FCREATE() returns -1 and FERROR() returns the appropriate error
     value.

     When FCREATE() successfully creates a new file, the file is left open in
     compatibility sharing mode and read/write access mode.  The file
     attribute specified by the <nAttribute> argument is applied to the new
     file when it is closed, allowing writing to a newly created read-only
     file.  For a list of access modes, see FOPEN().

     Since a file handle is required in order to identify an open file to
     other file functions, always assign the return value from FCREATE() to a
     variable for later use.

     Like other file functions, FCREATE() does not use either the DEFAULT or
     PATH settings for its operation.  Instead, it writes to the current DOS
     directory unless a path is explicitly stated.

     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 creates a file called Testfile and opens it for
        reading and writing:

        #include "Fileio.ch"

        //
        IF (nHandle := FCREATE("Testfile", FC_NORMAL)) == -1
           ? "File cannot be created:", FERROR()
           BREAK
        ELSE
           FWRITE(nHandle, "Hello there")
           FCLOSE(nHandle)
        ENDIF

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

See Also: FCLOSE() FERROR() FOPEN()