$FUNCNAME$
  FCREATE()
$CATEGORY$
  FILE/IO
$SUMMARY$
   Create and/or truncate a binary file to zero-length
$LANG_RU$
    /      .
$SYNTAX$
     FCREATE(<cFile>, [<nAttribute>]) --> nHandle
$LANG_RU$
     FCREATE(< >, [<>]) -->  
$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.

     <PRE>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
     ------------------------------------------------------------------------
     </PRE>
$LANG_RU$
     < >   ,  .  
      ,       .

     <>      , 
       .    ,    
       .

     <PRE>  .
     ---------------------------------------------------------------------
        Fileio.ch        
     ---------------------------------------------------------------------
     0          FC_NORMAL          ,   / ( )
     1          FC_READONLY        
			      
     2          FC_HIDDEN        
     4          FC_SYSTEM        
     ---------------------------------------------------------------------
     </PRE>
$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.
$LANG_RU$
     FCREATE()       DOS 
       0  65535.      
     , FCREATE()   (-1),   FERROR()
         .
$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.
$LANG_RU$
     FCREATE()      , 
        ,      
        .     < >  ,
          .      
        ,     .  
        , FCREATE()   (-1), 
     FERROR()     .

       FCREATE()    ,   
             /. 
     ,     <>, 
         ,      
      ,        . 
           FOPEN().

             
       ,    FCREATE()
          .

      ,       ,  
     FCREATE()    DEFAULT  PATH.    
     ,       .

     :
             
       DOS.      
         .
$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
$LANG_RU$

            , 
       Testfile,       :

       #include "Fileio.ch"
       //
       IF (nHandle := FCREATE("Testfile", FC_NORMAL)) = -1
	  ? "    : " FERROR()
	  BREAK
       ELSE
	  FWRITE(nHandle, " ")
	  FCLOSE(nHandle)
       ENDIF
$SEEALSO$
  FCLOSE(),FERROR(),FOPEN()
$END$
