Functions and Directives

Function FCreate() Foundation

Creates a new file or sets the length of an existing file to zero.

Syntax
FCreate( <cFilename>, [<nAttribute>] ) --> nFileHandle
Parameters
<cFilename>
<cFilename> is a character string containing the name of a file. If the file does not exist, it is created. If it already exists, the length of the file is set to zero, consequently deleting all data previously in the file.
<nAttribute>
<nAttribute> is an integer numeric value which sets the access mode for the file. Various symbolic constants are defined in the file "Fileio.ch" for the access mode. The constants can be combined with the + operator. Valid values for <nAttribute>are listed in the following table. The default value is FC_NORMAL:
File attributes for use with FCreate()
Constants Attribute Description
FC_NORMAL Normal creates file with read and write access (default value)
FC_READONLY Read-only creates file with read access
FC_HIDDEN Hidden creates hidden file
FC_SYSTEM System creates system file
FC_AUTODELETE creates file that is deleted when closed
File handle attributes for use with FCreate()
Constants Description
FA_INHERITABLE File handle can be used in child processes (RunShell())
Return

FCreate() returns an integer numeric value. This number is the file handle returned from the operating system for <cFilename>. If an error occurs, the return value is -1 and the error code can be retrieved using FError().

Description

The low level file function FCreate() creates or recreates a file and opens it for write access. When the file <cFilename> already exists, it is reset to zero length, which means all information contained in the file is lost. If <cFilename> cannot be opened for write access, FCreate() returns the value -1. The error which occurred can be determined by the error code returned from the function FError().

The return value of FCreate() is the file handle and must be assigned to a variable so that further file operations can be performed on the file. The file remains open for write access until the file handle is passed to the function FClose(). The file attribute specified with <nAttribute> is set when the file is closed. Therefore with FCreate() a file with exclusive read access (read only) can be created and filled with information. The file receives the "Read only" status only when it is closed.

Low level file functions do not recognize either the path set with PATH or specified with DEFAULT. Therefore, <cFilename> must be a complete file name with drive and path specified. When no drive or path is included in <cFilename>, the file is created in the current directory.

Examples
FCreate()
// In the example, a file is created and a character 
// string is written into the file. 

#include "Fileio.ch" 

PROCEDURE Main 
   LOCAL nHandle := FCreate( "NEWFILE.TXT", FC_NORMAL ) 

   IF nHandle == -1 
      ? "Error with creation of the file:", FError() 
   ELSE 
      FWrite( nHandle, "James Bond's BMW", 16 ) 
      FClose( nHandle ) 
   ENDIF 

RETURN 

Feedback

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.