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

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

FReadStr()

FREADSTR()

Reads a string from a file opened with low-level access

Syntax

      FREADSTR(<nHandle>, <nBytes>) --> cString

Arguments

<nHandle> DOS file handle number.

<nBytes> Number of bytes to read.

Returns

<cString> an character expression

Description

This function returns a character string of <nBytes> bytes from a file whose DOS file handle is <nHandle>.

The value of the file handle <nHandle> is obtained from either the FOPEN() or FCREATE() functions.

The value of <nBytes> is the number of bytes to read from the file. The returned string will be the number of characters specified in <nBytes> or the number of bytes read before an end-of-file charac- ter (ASCII 26) is found.

NOTE This function is similar to the FREAD() function, except that it will not read binary characters that may he required as part of a header of a file construct. Characters Such as CHR(0) and CHR(26) may keep this function from performing its intended operation. In this event, the FREAD() function should he used in place of the FREADSTR() function.

Examples

      #include "fileio.ch"
      IF ( nH := FOpen( "x.txt" ) ) != F_ERROR
         cStr := FReadStr( nH, 100 )
         ? cStr
         FClose( nH )
      ENDIF

Compliance

Clipper

Platforms

All (64K)

Files

Library is rtl

Seealso

BIN2I(), BIN2L(), BIN2W(), FERROR(), FREAD(), FSEEK()

FRead()

FREAD()

Reads bytes from a file opened by low-level access

Syntax

      FREAD( <nHandle>, @<cBuffer>, <nBytes> ) --> nBytes

Arguments

<nHandle> Dos file handle

<cBuffer> Character expression passed by reference.

<nBytes> Number of bytes to read.

Returns

<nBytes> the number of bytes successfully read from the file. <nHandle>

Description

This function reads the characters from a file whose file handle is <nHandle> into a character memory variable expressed as <cBuffer>. The function returns the number of bytes successfully read into <cBuffer>.

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

The <cBuffer> expression is passed by reference and must be defined before this function is called. It also must be at least the same length as <nBytes>.

<nBytes> is the number of bytes to read, starting at the current file pointer position. If this function is successful in reading the characters from the file, the length of <cBuffer> or the number of bytes specified in <nBytes> will be the value returned. The current file pointer advances the number of bytes read with each successive read. The return value is the number of bytes successfully read from the file. If a 0 is returned, or if the number of bytes read matches neither the length of <cBuffer> nor the specified value in <nBytes> an end-of-file condition has been reached.

Examples

      #include "fileio.ch"
      cBuffer := Space( 500 )
      IF ( nH := FOpen( "x.txt" ) ) == F_ERROR
         FRead( nH, @cBuffer, 500 )
         ? cbuffer
      ENDIF
      FClose( nH )

Compliance

Clipper

Platforms

All (64K)

Files

Library is rtl

Seealso

BIN2I(), BIN2L(), BIN2W(), FERROR(), FWRITE()

FCreate()

FCREATE()

Creates a file for low-level access

Syntax

      FCREATE( <cFile>, [<nAttribute>] ) --> nHandle

Arguments

<cFile> is the name of the file to create.

<nAttribute> Numeric code for the file attributes.

Returns

<nHandle> Numeric file handle to be used in other operations.

Description

This function creates a new file with a filename of <cFile>. The default value of <nAttribute> is 0 and is used to set the attribute byte for the file being created by this function. The return value will be a file handle that is associated with the new file. This number will be between zero to 65, 535, inclusive. If an error occurs, the return value of this function will be -1.

If the file <cFile> already exists, the existing file will be truncated to a file length of 0 bytes.

If specified, the following table shows the value for <nAttribute> and their related meaning to the file <cFile> being created by this function.

       <nAttribute>   fileio.ch     Meaning
       -------------  ------------- ---------------------------------------      
       0              FC_NORMAL     Normal/Default,Read/Write
       1              FC_READONLY   Read-only file attribute is set
       2              FC_HIDDEN     Hidden,Excluded from normal DIR search
       4              FC_SYSTEM     Create,Excluded from normal DIR search

Examples

      #include "fileio.ch"
      IF ( nh := FCreate( "test.txt" ) ) == F_ERROR
          ? "Cannot create file"
      ENDIF

Compliance

Clipper

Files

Library is rtl Header is fileio.ch

Seealso

FCLOSE(), FOPEN(), FWRITE(), FREAD(), FERROR()

FClose()

FCLOSE()

Closes a file opened by  low-level access

Syntax

      FCLOSE( <nHandle> ) --> <lSuccess>

Arguments

<nHandle> DOS file handle

Returns

<lSuccess> Logical TRUE (.T.) or FALSE (.F.)

Description

This function closes an open file with a dos file handle of <nHandle> and writes the associated DOS buffer to the disk. The <nHandle> value is derived from the FCREATE() or FOPEN() function.

Examples

      #include "fileio.ch"
      nHandle := FOpen( "x.txt" )
      ? FSeek( nHandle, 0, FS_END )
      FClose( nHandle )

Compliance

Clipper

Files

Library is rtl

Seealso

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

Bin2W()

 

BIN2W()

Convert unsigned short encoded bytes into Harbour numeric

Syntax

      BIN2W( <cBuffer> ) --> nNumber

Arguments

<cBuffer> is a character string that contain 16 bit encoded unsigned short integer (least significant byte first). The first two bytes are taken into account, the rest if any are ignored.

Returns

BIN2W() return numeric integer (or 0 if <cBuffer> is not a string).

Description

BIN2W() is one of the low level binary conversion functions, those functions convert between Harbour numeric and a character representation of numeric value. BIN2W() take two bytes of encoded 16 bit unsigned short integer and convert it into standard Harbour numeric value.

You might ask what is the need for such functions, well, first of all it allow you to read/write information from/to a binary file (like extracting information from DBF header), it is also a useful way to share information from source other than Harbour (C for instance).

BIN2W() is the opposite of W2BIN()

Examples

      // Show header length of a DBF
      #include "fileio.ch"
      PROCEDURE Main()
         LOCAL nHandle, cBuffer := Space( 2 )
         nHandle := FOpen( "test.dbf" )
         IF nHandle != F_ERROR
            FSeek( nHandle, 8 )
            FRead( nHandle, @cBuffer, hb_BLen( cBuffer ) )
            ? "Length of DBF header in bytes:", Bin2W( cBuffer )
            FClose( nHandle )
         ELSE
            ? "Can not open file"
         ENDIF
         RETURN

Compliance

Clipper

Files

Library is rtl

Seealso

BIN2I(), BIN2L(), BIN2U(), I2BIN(), L2BIN(), W2BIN(), WORD(), U2BIN(), FREAD()

Bin2U()

BIN2U()

Convert unsigned long encoded bytes into Harbour numeric

Syntax

      BIN2U( <cBuffer> ) --> nNumber

Arguments

<cBuffer> is a character string that contain 32 bit encoded unsigned long integer (least significant byte first). The first four bytes are taken into account, the rest if any are ignored.

Returns

BIN2U() return numeric integer (or 0 if <cBuffer> is not a string).

Description

BIN2U() is one of the low level binary conversion functions, those functions convert between Harbour numeric and a character representation of numeric value. BIN2U() take four bytes of encoded 32 bit unsigned long integer and convert it into standard Harbour numeric value.

You might ask what is the need for such functions, well, first of all it allow you to read/write information from/to a binary file (like extracting information from DBF header), it is also a useful way to share information from source other than Harbour (C for instance).

BIN2U() is the opposite of U2BIN()

Examples

      // Show number of records in DBF
      #include "fileio.ch"
      PROCEDURE Main()
         LOCAL nHandle, cBuffer := Space( 4 )
         nHandle := FOpen( "test.dbf" )
         IF nHandle != F_ERROR
            FSeek( nHandle, 4 )
            FRead( nHandle, @cBuffer, hb_BLen( cBuffer ) )
            ? "Number of records in file:", Bin2U( cBuffer )
            FClose( nHandle )
         ELSE
            ? "Can not open file"
         ENDIF
         RETURN

Compliance

XPP

Files

Library is rtl

Seealso

BIN2I(), BIN2L(), BIN2W(), I2BIN(), L2BIN(), W2BIN(), WORD(), U2BIN(), FREAD()

Bin2L()

 

BIN2L()

Convert signed long encoded bytes into Harbour numeric

Syntax

      BIN2L( <cBuffer> ) --> nNumber

Arguments

<cBuffer> is a character string that contain 32 bit encoded signed long integer (least significant byte first). The first four bytes are taken into account, the rest if any are ignored.

Returns

BIN2L() return numeric integer (or 0 if <cBuffer> is not a string).

Description

BIN2L() is one of the low level binary conversion functions, those functions convert between Harbour numeric and a character representation of numeric value. BIN2L() take four bytes of encoded 32 bit signed long integer and convert it into standard Harbour numeric value.

You might ask what is the need for such functions, well, first of all it allow you to read/write information from/to a binary file (like extracting information from DBF header), it is also a useful way to share information from source other than Harbour (C for instance).

BIN2L() is the opposite of L2BIN()

Examples

      // Show number of records in DBF
      #include "fileio.ch"
      PROCEDURE Main()
         LOCAL nHandle, cBuffer := Space( 4 )
         nHandle := FOpen( "test.dbf" )
         IF nHandle != F_ERROR
            FSeek( nHandle, 4 )
            FRead( nHandle, @cBuffer, hb_BLen( cBuffer ) )
            ? "Number of records in file:", Bin2L( cBuffer )
            FClose( nHandle )
         ELSE
            ? "Can not open file"
         ENDIF
         RETURN

Compliance

Clipper

Files

Library is rtl

Seealso

BIN2I(), BIN2U(), BIN2W(), I2BIN(), L2BIN(), W2BIN(), WORD(), U2BIN(), FREAD()