Low-Level File Access

Low-Level File Access Functions

FClose Closes a file opened by low-level access
FCreate Creates a file for low-level access
FErase Erase any file from disk by low-level access
FError Reports the error status of low-level file functions
FOpen Open a file for low-level access
FRead Reads bytes from a file opened with low-level access
FReadStr Reads a string from a file opened with low-level access
FRename Renames a file by low-level access
FSeek Positions the file pointer in a file opened with low-level access
FWrite Writes characters to a file opened with low-level access

Harbour All Functions – F

Fact

Fahrenheit

FClose()
FCount()
FCreate()
FErase()
FError()
FieldBlock()

FieldDeci()

FieldGet()

FieldName()
FieldPos()
FieldPut()

FieldSize()
FieldType()

FieldWBlock()

File()
FLock()

Floor

FOpen()

Found()

FRead()
FReadStr()
FRename()
FSeek()

FToC

FV

FWrite()

hb_FUnlock()

HB_FUNLOCK()

Unlocks part or all of any file

Syntax

      HB_FUNLOCK( <nHandle>, <nOffset>, <nBytes> )  --> <lSuccess>

Arguments

<nHandle> Dos file handle

set> Offset of the first byte of the region to be locked.

<nBytes> Number of bytes to be locked.

Returns

<lSuccess> .T. if the lock was removed, else .F.

Description

This function attempts to unlock a region of the file whose file handle is <nHandle>. This is a low level file function. To unlock Harbour data files use the DBUNLOCK() function.

The value of <nHandle> is obtained from either a call to the FOPEN() or the FCREATE() function.

<nOffset> is the offset (from the beginning of the file) to the first of the region to be unlocked. (Offsets from the current position nd of file are not currently supported.)

<nBytes> is the length of the region to be unlocked in bytes.

Examples

      refer to tfl.prg

Compliance

Harbour

Platforms

All (64K)

Files

Library is rtl

Seealso

HB_FLOCK(), FOPEN(), FCREATE(), FERROR(), FCLOSE(), DBUNLOCK()

hb_FLock()

HB_FLOCK()

Locks part or all of any file

Syntax

      HB_FLOCK( <nHandle>, <nOffset>, <nBytes> [, <nType ] )
                --> <lSuccess>

Arguments

<nHandle> Dos file handle

set> Offset of the first byte of the region to be locked.

<nBytes> Number of bytes to be locked.

e> The type (read or write) of lock requested.

Returns

<lSuccess> .T. if the lock was obtained, else .F.

Description

This function attempts to lock a region of the file whose file handle is <nHandle>. This is a low level file function. To lock Harbour data files use either the FLOCK() or RLOCK() function.

The value of <nHandle> is obtained from either a call to the FOPEN() or the FCREATE() function.

<nOffset> is the offset (from the beginning of the file) to the first of the region to be locked. (Offsets from the current position nd of file are not currently supported.)

<nBytes> is the length of the region to be locked in bytes.

e> is the type of lock requested. There are two types of locks: sive write locks ( <nType> = 0x0000 ) – the default, and shared locks( <nType> = 0x0100 ). Additionally you can specify a ing version of this function (that is it won’t return until r an error has occurred or the lock has been obtained) by g Ox0200 to the above values.

Examples

      refer to tfl.prg

Compliance

Harbour

Platforms

All (64K)

Files

Library is rtl

Seealso

HB_FUNLOCK(), FOPEN(), FCREATE(), FERROR(), FCLOSE()

FWrite()

FWRITE()

Writes characters to a file opened with low-level access

Syntax

      FWRITE( <nHandle>, <cBuffer>, [<nBytes>] ) --> nBytesWritten

Arguments

<nHandle> DOS file handle number.

<cBuffer> Character expression to be written.

<nBytes> The number of bytes to write.

Returns

<nBytesWritten> the number of bytes successfully written.

Description

This function writes the contents of <cBuffer> to the file designated by its file handle <nHandle>. If used, <nBytes> is the number of bytes in <cBuffer> to write.

The returned value is the number of bytes successfully written to the DOS file. If the returned value is 0, an error has occurred (unless this is intended). A successful write occurs when the number returned by FWRITE() is equal to either LEN( <cBuffer>) or <nBytes>.

The value of <cBuffer> is the string or variable to be written to the open DOS file <nHandle>.

The value of <nBytes> is the number of bytes to write out to the file. The disk write begins with the current file position in <nHandle>. If this variable is not used, the entire contents of <cBuffer> is written to the file. To truncate a file, a call of FWRITE( nHandle, “”, 0 ) is needed.

Examples

      nHandle := FCreate( "x.txt" )
      FOR X := 1 TO 10
         FWrite( nHandle, Str( x ) )
      NEXT
      FClose( nHandle )

Compliance

Clipper

Platforms

All (64K)

Files

Library is rtl

Seealso

FCLOSE(), FCREATE(), FERROR(), FOPEN(), I2BIN(), L2BIN()

FOpen()

FOPEN()

Open a file for low-level access

Syntax

      FOPEN( <cFile>, [<nMode>] ) --> nHandle

Arguments

<cFile> Name of file to open.

<nMode> Dos file open mode.

Returns

<nHandle> A file handle.

Description

This function opens a file expressed as <cFile> and returns a file handle to be used with other low-level file functions. The value of <nMode> represents the status of the file to be opened; the default value is 0. The file open modes are as follows:

       nMode   fileio.ch      Meaning
       ------- -------------- ------------------------------------
       0       FO_READ        Read only
       1       FO_WRITE       Write only
       2       FO_READWRITE   Read/write
       16      FO_EXCLUSIVE   Exclusive read only
       32      FO_DENYWRITE   Prevent others from writing
       48      FO_DENYREAD    Deny read only
       64      FO_DENYNONE    Not deny, Let to others Read / Write
       64      FO_SHARED      same as FO_DENYNONE

If there is an error in opening a file, a -1 will be returned by the function. Files handles may be in the range of 0 to 65535. The status of the SET DEFAULT TO and SET PATH TO commands has no effect on this function. Directory names and paths must be specified along with the file that is to be opened.

If an error has occurred, see the returns values from FERROR() for possible reasons for the error.

Examples

      #include "fileio.ch"
      IF ( nH := FOpen( "x.txt", FO_READWRITE + FO_DENYNONE ) ) == F_ERROR
         ? "File can't be opened"
      ENDIF

Compliance

Clipper

Files

Library is rtl Header is fileio.ch

Seealso

FCREATE(), FERROR(), FCLOSE()

FError()

FERROR()

Reports the error status of low-level file functions

Syntax

      FERROR() --> <nErrorCode>

Returns

<nErrorCode> Value of the DOS error last encountered by a low-level file function.

FERROR() Return Values

       Error          Meaning
       -------------- ----------------------------------------------
       0              Successful
       2              File not found
       3              Path not found
       4              Too many files open
       5              Access denied
       6              Invalid handle
       8              Insufficient memory
       15             Invalid drive specified
       19             Attempted to write to a write-protected disk
       21             Drive not ready
       23             Data CRC error
       29             Write fault
       30             Read fault
       32             Sharing violation
       33             Lock Violation

Description

After every low-level file function, this function will return a value that provides additional information on the status of the last low-level file functions’s performance. If the FERROR() function returns a 0, no error was detected. Below is a table of possibles values returned by the FERROR() function.

Examples

      #include "fileio.ch"
      nHandle := FCreate( "temp.txt", FC_NORMAL )
      IF FError() != 0
         ? "Cannot create file, DOS error ", FError()
      ENDIF

Compliance

Clipper

Files

Library is rtl

Seealso

FCLOSE(), FERASE(), FOPEN(), FWRITE()