xHarbour Reference Documentation > Function Reference

FCreate()

Creates an empty binary file.

Syntax

FCreate( <cFileName>, [<nFileAttr>] ) --> nFileHandle

Arguments

<cFilename>

This is a character string holding the name of the file to create. It must include path and file extension. If the path is omitted from <cFileName>, the file is created in the current directory.

<nFileAttr>

A numeric value specifying one or more attributes associated with the new file. #define constants from the FILEIO.CH file can be used for <nFileAttr> as listed in the table below:

Attributes for binary file creation

Constant	Value	Attribute	Description
FC_NORMAL *)	0	Normal	Creates a normal read/write file
FC_READONLY	1	Read-only	Creates a read-only file
FC_HIDDEN	2	Hidden	Creates a hidden file
FC_SYSTEM	4	System	Creates a system file
*) default attribute

Return

The function returns a numeric file handle to be used later for writing data to the file using FWrite(). The return value is -1 when the operation fails. Use FError() to determine the cause of failure.

Description

The low-level file function FCreate() creates a new file, or truncates an existing file to contain zero bytes. If the operation is successful, the return value must be preserved in a variable for accessing the file lateron. The file is left open in compatibility sharing mode and read/write access mode so that the creating application can write data to the file. The file attribute <nFileAttr> is set when the file is closed again. Any attribute restricting file access, like FC_READONLY, for example, becomes effective after the newly created file is closed.

Info

See also:	FClose(), FErase(), FError(), FOpen(), FRead(), FSeek(), FWrite(), HB_FCommit(), HB_FCreate(), HB_FTempCreate()
Category:	File functions , Low level file functions
Header:	FileIO.ch
Source:	rtl\philes.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example creates a new file, writes some data to it and closes it.
// If file creation or data write fails, an error message is displayed
// along with the error code obtained from the operating system.

   #include "Fileio.ch"

   PROCEDURE Main
      LOCAL nFileHandle, cText

      nFileHandle := FCreate( "NewFile.txt", FC_NORMAL )

      IF FError() <> 0
         ? "Error while creatingg a file:", FError()
         QUIT
      ENDIF

      cText := "Text for new file"

      IF FWrite( nFileHandle, cText ) <> Len( cText )
         ? "Error while writing a file:", FError()
      ENDIF

      IF .NOT. FClose( nFileHandle )
         ? "Error while closing a file:", FError()
      ELSE
         ? "File successfully created and closed"
      ENDIF

   RETURN