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

FSeek()

FSEEK()

Positions the file pointer in a file opened with low-level access

Syntax

      FSEEK( <nHandle>, <nOffset>, [<nOrigin>] ) --> nPosition

Arguments

<nHandle> DOS file handle.

<nOffset> The number of bytes to move.

<nOrigin> The relative position in the file.

Returns

<nPosition> the current position relative to begin-of-file

Description

This function sets the file pointer in the file whose DOS file handle is <nHandle> and moves the file pointer by <expN2> bytes from the file position designated by <nOrigin>. The returned value is the relative position of the file pointer to the beginning-of-file marker once the operation has been completed.

<nHandle> is the file handle number. It is obtained from the FOPEN() or FCREATE() function.

The value of <nOffSet> is the number of bytes to move the file pointer from the position determined by <nOrigin>. The value of <nOffset> may be a negative number, suggesting backward movement.

The value of <nOrigin> designates the starting point from which the file pointer should he moved, as shown in the following table:

       <nOrigin>   fileio.ch     File position
       ----------- ------------- ---------------------------------- 
       0           FS_SET        Beginning of file
       1           FS_RELATIVE   Current file pointer position
       2           FS_END        End of file

If a value is not provided for <nOrigin>, it defaults to 0 and moves the file pointer from the beginning of the file.

Examples

      // here is a function that read one text line from an open file

      // nH = file handle obtained from FOpen()
      // cB = a string buffer passed-by-reference to hold the result
      // nMaxLine = maximum number of bytes to read

      FUNCTION FREADln( nH, cB, nMaxLine )
         LOCAL cLine, nSavePos, nEol, nNumRead
         cLine := Space( nMaxLine )
         cB := ""
         nSavePos := FSeek( nH, 0, FS_RELATIVE )
         nNumRead := FRead( nH, @cLine, nMaxLine )
         IF ( nEol := At( hb_eol(), SubStr( cLine, 1, nNumRead ) ) ) == 0
            cB := cLine
         ELSE
            cB := SubStr( cLine, 1, nEol - 1 )
            FSEEK( nH, nSavePos + nEol + 1, FS_SET )
         ENDIF
         RETURN nNumRead != 0

Compliance

Clipper

Files

Library is rtl Header is fileio.ch

Seealso

FCREATE(), FERROR(), FOPEN(), FREAD(), FREADSTR(), FWRITE()

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