Tag Archives: FOPEN()

Low-Level File Access

Posted on by vivaclipper

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

Posted on by vivaclipper

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

Posted on by vivaclipper

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

Posted on by vivaclipper

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

Posted on by vivaclipper

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

Posted on by vivaclipper

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

Posted on by vivaclipper

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

Posted on by vivaclipper

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

FCreate()

Posted on by vivaclipper

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

Posted on by vivaclipper

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