xHarbour Reference Documentation > Function Reference

FOpen()

Opens a file on the operating system level.

Syntax

FOpen( <cFileName>, [<nMode>]) --> nFileHandle

Arguments

<cFilename>

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

<nMode>

A numeric value specifying the open mode and access rights for the file. #define constants from the FILEIO.CH file can be used for <nMode> as listed in the table below:

File open modes

Constant	Value	Description
FO_READ *)	0	Open file for reading
FO_WRITE	1	Open file for writing
FO_READWRITE	2	Open file for reading and writing
*) default

Constants that define the access or file sharing rights can be added to an FO_* constant. They specify how file access is granted to other applications in a network environment.

File sharing modes

Constant	Value	Description
FO_COMPAT *)	0	Compatibility mode
FO_EXCLUSIVE	16	Exclusive use
FO_DENYWRITE	32	Prevent other applications from writing
FO_DENYREAD	48	Prevent other applications from reading
FO_DENYNONE	64	Allow others to read or write
FO_SHARED	64	Same as FO_DENYNONE
*) default

Return

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

Description

The low-level file function FOpen() opens a file on the operating system level. The returned file handle must be preserved in a variable to be passed to other low-level file functions until the file is closed. Without the file handle, data cannot be written to or read from the file.

Open mode and sharing rights can be specified with <nMode>. The default open and sharing mode grants shared read access to the application.

FOpen() does not search the directories specified with SET PATH or SET DEFAULT. Therefore, the file name must be specified including directory information and extension. If no directory information is provided, FOpen() searches the file only in the current directory.

Info

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

Example

// The example implements a user-defined function that reads the
// entire contents of a file into a memory variable using
// low-level file functions:

   #include "FileIO.ch"

   PROCEDURE Main
      LOCAL cFile := "Fopen.prg" //"MyFile.txt"
      LOCAL cStream

      IF .NOT. ReadStream( cFile, @cStream )
         IF FError() <> 0
            ? "Error reading file:", FError()
         ELSE
            ? "File is empty"
         ENDIF
      ELSE
         ? "Successfully read", Len(cStream), "bytes"
      ENDIF
   RETURN

   FUNCTION ReadStream( cFile, cStream )
      LOCAL nFileHandle := FOpen( cFile )
      LOCAL nFileSize

      IF FError() <> 0
         RETURN .F.
      ENDIF

      nFileSize := FSeek( nFileHandle, 0, FS_END )
      cStream   := Space( nFileSize )
      FSeek( nFileHandle, 0, FS_SET )
      FRead( nFileHandle, @cStream, nFileSize )
      FClose( nFileHandle )
   RETURN ( FError() == 0 .AND. .NOT. Empty( cStream ) )