Function FCreate() | Xbase++

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

FCreate( <cFilename>, [<nAttribute>] ) --> nFileHandle

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

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

Constants	Description
FA_INHERITABLE	File handle can be used in child processes (RunShell())

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

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.

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

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.

Function FCreate() Foundation