Tag Archives: FERROR()

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

HB_DirDelete

Posted on by vivaclipper

HB_DirDelete

Attempt to remove a directory

Syntax

      HB_DirDelete( <cDirectory> ) --> nError

Arguments

<cDirectory> The name of the directory to delete

Returns

<nError> 0 if directory was successfully removed, otherwise the number of the last DOS error.

Most probable error codes :

      Code Meaning
      ---- ----------------------------
        2  File ( directory ) not found
      145  Directory not empty

Description

This function attempt to remove the specified directory in <cDirectory>. If this function fails, it will return the last OS error code number. See FERROR() function for the description of the error.

Notes

. This function is file/folder names case sensitive

. <cDirectory> must be empty

. HB_DirDelete()is same as DirRemove() C5.3 function, but it’s always available, not just when HB_COMPAT_C53 is enabled.

Examples

      cDir := ".\backup"
      IF HB_DirDelete( cDir ) == 0
         ? "Remove of directory", cDir, "was successfull"
      ENDIF

Seealso

DirRemove(), MakeDir(), DirChange(), Ferror()

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

MakeDir

Posted on by vivaclipper

MAKEDIR()

Create a new directory

Syntax

      MAKEDIR( <cDirectory> ) --> nError

Arguments

<cDirectory> The name of the directory you want to create.

Returns

<nError> 0 if directory was successfully created, otherwise the number of the last error.

Description

This function attempt to create a new directory with the name contained in <cDirectory>. If this function fails, it will return the last OS error code number. See FERROR() function for the description of the error

Note

     MakeDir() is equivalent to DirMake(), HB_DirCreate() and HB_DirBuild()

Examples

      cDir := "temp"
      IF MakeDir( cDir ) == 0
         ? "Directory", cDir, "successfully created"
      ENDIF

Tests

      See examples

Compliance

This function is CA-Cl*pper 5.3 compliant

Platforms

All

Files

Library is rtl

Seealso

DIRCHANGE(), DIRREMOVE(), ISDISK(), DISKCHANGE(), DISKNAME(), FERROR(), DirMake(), HB_DirCreate(), HB_DirBuild()

HB_FEof()

Posted on by vivaclipper

HB_FEOF()

Check for end-of-file.

Syntax

      HB_FEOF( <nHandle> ) --> lIsEof

Arguments

<nHandle> The handle of an open file.

Returns

<lIsEof> .T. if the file handle is at end-of-file, otherwise .F.

Description

This function checks an open file handle to see if it is at EOF.

If the file handle is missing, not numeric, or not open, then this function returns .T. and sets the value returned by FERROR() to -1 (FS_ERROR) or a C-compiler dependent errno value (EBADF or EINVAL).

Examples

      nH := FOpen( "file.txt" )
      ? FReadStr( nH, 80 )
      IF hb_FEof( nH )
         ? "End-of-file reached."
      ELSE
         ? FReadStr( nH, 80 )
      ENDIF

Compliance

Harbour

Files

Library is rtl

Seealso

FERROR()

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

FRename()

Posted on by vivaclipper

FRENAME()

Renames a file by low-level access

Syntax

      FRENAME( <cOldFile>, <cNewFile> ) --> nSuccess

Arguments

<cOldFile> Old filename to be changed

<cNewFile> New filename

Returns

<nSuccess> If successful, a 0 will be returned otherwise, a -1 will be returned.

Description

This function renames the specified file <cOldFile> to <cNewFile>. A filename and/or directory name may be specified for either parameter. However, if a path is supplied as part of <cNewFile> and this path is different from either the path specified in <cOldFile> or (if none is used) the current drive and directory, the function will not execute successfully.

Neither parameter is subject to the control of the SET PATH TO or SET DEFAULT TO commands. In attempting to locate the file to be renamed, this function will search the default drive and directory or the drive and path specified in <cOldFile>. It will not search directories named by the SET PATH TO and SET DEFAULT TO commands or by the DOS PATH statement.

If the file specified in <cNewFile> exists or the file is open, the function will be unable to rename the file. If the function is unable to complete its operation, it will return a value of -1. If it is able to rename the file, the return value for the function will be 0. A call to FERROR() function will give additional infor- mation about any error found.

Examples

      #include "fileio.ch"
      nResult := FRename( "x.txt", "x1.txt" )
      IF nResult == F_ERROR
         ? "File could not be renamed."
      ENDIF

Compliance

Clipper

Files

Library is rtl

Seealso

ERASE, FERASE(), FERROR(), FILE(), RENAME