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

HB_FTempCreateEx

HB_FTempCreateEx

Creates and opens a temporary file.

Syntax

HB_FTempCreateEx( @<cFileName,;
                    <cTempDir>,;
                    <cPrefix>,;
                    <cFileExtension> --> <nFileHandle>

Arguments

 @<cFileName> :must be passed by reference. It receives the file name of the created temporary  file as a character string.

<cTempDir> : A character string specifying the directory where to create the temporary file. It defaults to the operating       system variable SET TEMP or SET TMP. Operating system variables can be queried with function HB_GetEnv().

<cPrefix> : A character string of three characters specifying the prefix to use for the name of the temporary file. It defaults  to the string “hb”.

<nFileExtension> : A character value specifying extension of the temporary file.

Returns

<nFileHandle> : a numeric value > 0 when the temporary file is successfully created. This is the file handle of the created temporary file.

Description

Function HB_FTempCreateEx() creates a temporary file and opens it. The return value is the file handle of the temporary file. It can be used with low level file functions, such as FWrite() to store data in the file. Temporary files are often required in an application.

HB_FTempCreateEx() guarantees that the file name of the newly created file is unique, so that no existing file will be overwritten. To obtain the file name of the temporary file, parameter <cFileName> must be passed by reference. It can then later be passed to function FErase() in order to remove the temporary file from disk.

HB_FTempCreateEx() is similar to HB_FTempCreate(), but allows to control the extension. Note, that the ordering of parameters had slightly changed compared to hb_fsCreateTemp().

Example

      PROC TestHBFTempEx()

         LOCAL nFileHandle
         LOCAL cFileName

         nFileHandle := HB_FTempCreateEx( @cFileName,;   // File Name
                                          ,;             // <cTempDir>
                                          ,;             // <cPrefix>
                                          '.tmp' )       // file extension

         IF nFileHandle > 0
            ? 'Temp file builded with name :', cFileName
            WAIT
            FClose( nFileHandle )
            FErase( cFileName )
         ELSE
            ALERT( "Couldn't build temp file"  )
         ENDI

      RETU // TestHBFTempEx()

Seealso

TempFile(), HB_FTempCreate(), FCreate(), FErase(), FWrite(), HB_GetEnv()

HB_FTempCreate

HB_FTempCreate

Creates and opens a temporary file.

Syntax

      HB_FTempCreate( [<cTempDir>] , ;
                         [<cPrefix>]  , ;
                         [<nFileAttr>], ;
                         [@<cFileName>]  ) --> <nFileHandle>

Arguments

<cTempDir> : An optional character string specifying the directory where to create the temporary file. It defaults to the operating system variable SET TEMP or SET TMP. Operating system variables can be queried with function HB_GetEnv().

<cPrefix> : An optional character string of three characters specifying the prefix to use for the name of the temporary file. It defaults to the string “hb”.

<nFileAttr> : An optional numeric value defining how to create and open the temporary file. See function FCreate() for a description of <nFileAttr>.

@<cFileName> : If specified, <cFileName> must be passed by reference. It receives the file name of the created temporary file as a character string.

Returns

<nFileHandle> : a numeric value > 0 when the temporary file is successfully created. This is the file handle of the created temporary file.

Description

Function HB_FTempCreate() creates a temporary file and opens it. The return value is the file handle of the temporary file. It can be used with low level file functions, such as FWrite() to store data in the file.

Temporary files are often required in an application. HB_FTempCreate() guarantees that the file name of the newly created file is unique, so that no existing file will be overwritten. To obtain the file name of the temporary file, parameter <cFileName> must be passed by reference. It can then later be passed to function FErase() in order to remove the temporary file from disk.

Example

      PROC TestHBFTemp()

         LOCAL nFileHandle
         LOCAL cFileName

         nFileHandle := HB_FTempCreate( ,;   // <cTempDir>
                                        ,;   // <cPrefix>
                                        ,;   // <nFileAttr>
                                        , @cFileName )

         IF nFileHandle > 0
            ? 'Temp file builded with name :', cFileName
            WAIT
            FClose( nFileHandle )
            FErase( cFileName )
         ELSE
            ALERT( "Couldn't build temp file"  )
         ENDI

      RETU // TestHBFTemp()

Seealso

TempFile(), HB_FTempCreateEx(), FCreate(), FErase(), FWrite(), HB_GetEnv()

TempFile

TempFile

Creates a file for temporary use

Syntax

      TempFile([<cDirectory>], [<cExtension>], [<nFileAttr>])
             --> <cFileName>

Arguments

<cDirectory> : The drive and directory where the temporary file is to be created. The default is the system/user temp directory.

<cExtension> : The file extension for the file. The default is no extension.

<nFileAttr> : A file attribute for the file.

Returns

<cFileName> : The name of the temporary file. If no file is created, the function returns a null string.

Description

If you only need a file for a short time and want to avoid conflicts with existing files, use TempFile() to create a file with a unique name. Names created by TempFile() use the system date and system time. You can hide the file, if you specify an attribute. Attributes are coded as follows:

         File Attribute Coding
         ------------------------------------------------------------------------
         Value   Symb. constants     Definition
         ------------------------------------------------------------------------
         0       FA_NORMAL
         1       FA_READONLY         READ ONLY
         2       FA_HIDDEN           HIDDEN (Hidden files)
         4       FA_SYSTEM           SYSTEM (System files)
         32      FA_ARCHIVE          ARCHIVE (Changed since last backup)
         ------------------------------------------------------------------------

Notes

. The temporary file name is always 8 characters long and consists exclusively of numbers with a period, if no extension has been specified. The file is created with a length of 0 bytes.

Examples

      .  Create a temporary file in the system/user temp  directory:

         cTempFile := TempFile()

      .  Create a temporary file in the root directory of the E: drive:

         cTempFile := TempFile("E:\")

      .  Create a temporary file with a .TMP extension and a HIDDEN
         attribute in the root directory of the C: drive:

         cTempFile := TempFile("C:\", "TMP", 2)

Seealso

HB_FTempCreate(), HB_FTempCreateEx(), FCreate(), FErase(), FWrite(), HB_GetEnv()

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

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