File IO - Petewg/harbour-core GitHub Wiki

🔙 Functions-by-category

• hb_CurDrive([<cNewDrive>]) ➜ cCurrentDrive
  returns the current working disk drive as a single capital letter (e.g. C ) and optionally changes it to <cNewDrive>.

• hb_CWD([<cNewDir>]) ➜ cCurrentDir
  returns the full current working directory (including the drive letter and a trailing path separator) and optionally changes it to <cNewDir>. Use FError() to check the result of operation.

• CurDir( [<cDrive>] ) ➜ cDirectory
  returns the name of the current directory of a drive. If the drive <cDrive> does not exist or the root directory is current, CurDir() returns a null string ("").

• hb_DirBase() ➜ cDirName
  returns the application's executable base directory (program statrtup directory).

• hb_ProgName() ➜ cExeName
  returns the executable program name.

• hb_DirBuild(<cDir>) ➜ lSuccess
  attempts to create (or to validate the existence of) the given <cDir> directory hierarchy, by recursively adding (if it doesn't already exist) a new path after creating the parent directory. f.e.: hb_DirBuild("sub1/sub2/sub3/") will create successively, "sub1" (if it doesn't exist), afterwards "sub2" under (or inside) "sub1", afterwards "sub3" under "sub2".
  It returns .T. when the directory hierarchy, either exists or was successfully created. Otherwise returns .F.

• hb_DirCreate(<cDir>) ➜ nSuccess
  attempts to create <cDir>. returns 0 on success, or a nFError code on failure.

• hb_DirDelete(<cDir>) ➜ nSuccess
  attempt to delete <cDir>. returns 0 on success, or a nFError code on failure.

• hb_Directory(<cDirSpec>, [<cAttributes>]) ➜ aDirectory
  Returns an array of files matching the <cDirspec> and <cAttributes> (if any) filters. The structure of array is identical to that of 'Directory()' except of the F_DATE element, which is a timestamp value type (T) whereas in 'Directory()' it is a date (D).

• hb_DirExists(<cDir>) ➜ lExists
  checks if <cDir> exists. Note: it won't work with wild-cards.
  returns .T. if <cDir> exists, otherwise .F.

• hb_DirRemoveAll(<cDir>) ➜ lResult
  This function attempts to remove entire <cDir> directory.
  ❗️Warning❗️ Since this function removes recursively whole directories along with their contents, be extremely careful while using it.
  For example, invoking this function like:

      hb_DirRemoveAll( hb_ps() )

  can remove all files and directories (even those marked as hidden, system or read-only) from current working disk!

• hb_DirScan(<cPath>, [<cFileMask>], [<cAttr>]) ➜ aFiles
  similar to 'hb_Directory()' (refer to it for more..) with the difference that it scans not only <cPath> but also all subdirectories below <cPath> (recursively).

• hb_DirSepAdd(<cDir>) ➜ cDir
  returns <cDir> with a path separator added to the end of it. (if <cDir> already has an ending path separator, nothing added). see also: hb_DirSepDel().

• hb_DirSepDel(<cDir>) ➜ cDir
  returns cDir without path separator at the end of it (if any). The inverse function of 'hb_DirSepAdd()'.

• hb_DirSepToOS(<cFileName>) ➜ cFileName
  replaces the path separators (if any) into <cFileName> with appropriate ones for the O/S used. e.g.: with / for *nix, \ for Win.

• hb_DirTemp() ➜ tempDir
  returns the full name of temp dir including drive letter and a trailing path-separator (similar to 'hb_GetEnv("temp")' which has no trailing path-separator).

• hb_DirUnbuild(<cDir>) ➜ lSuccess
  attempts to remove <cDir> and all subdirectories inside it.
  the operation acts down-to-top, i.e. at first, attempts to delete the lowermost subdirectory. If succeeds, will continue deleting upper directories until either all subdirectories (including topmost) have been deleted, in which case it will return .T., or until a subdirectory cannot be deleted, for some reason (e.g. because it is not empty or is read-only et.c.) and hence it will return .F.
  (might be seen as the inverse of hb_DirBuild())

• hb_DiskSpace([<cDrive>] [,<nType>]) ➜ nDiskbytes
  returns the free space (in bytes) of <cDrive> (default: current working drive) or the type of space specified by <nType>.
  Supported types:

  nType	Returned value
  HB_DISK_AVAIL	➜ available disk space
  HB_DISK_FREE	➜ free space (similar to above)
  HB_DISK_USED	➜ used disk space
  HB_DISK_TOTAL	➜ total disk space

  See fileio.ch header file. See also: hb_vfDirSpace() with similar syntax.

• hb_FCommit(<hFileHandle>) ➜ NIL
  Flushes the buffers and causes all buffered data to be written to an opened file.

• hb_FCopy(<cSourceFile>, <cDestinationFile>) ➜ nSuccess
  Low level file copy. returns 0 on success, nFError on failure.
  If <cDestinationFile> exists, it will be overwritten, unless it is "read only", in which case hb_FCopy() will fail with -1. (see also: hb_vfCopyFile())

• hb_FCreate(<cFile>, <nCreateFlags>, <nOpenFlags>) ➜ nHandle
  attempts to create cFile. returns handle to created file on success or nFError on failure. File opening flags can be defined with <nOpenFlags>.

• hb_FEof(<nHandle>) ➜ lEof
  returns .T. if the file handle is at end-of-file, otherwise .F.
<nHandle> is the handle of an opened file (see FOpen()).
  If the file handle is missing, not numeric, or not open, then function returns .T. and sets the value returned by FERROR() to -1 or a C-compiler dependent errno value (EBADF or EINVAL). (On a MinGW/Windows build/platform errorcode returned is 6 meaning Invalid Handle.)

• hb_FGetAttr(<cFileName>, @<nAttr>) ➜ lSuccess
  retrieves attributes of a file.

• hb_FGetDateTime(<cFileName>, @<tTimeStamp> [, @<cTime>]) ➜ lSuccess
  it stores date/time of <cFileName> in @<DateTimeStamp> (type="T"). If a 3rd parameter passed then the 2nd will store the date (type="D") and the 3rd the time (type="C") of file.

• hb_FileDelete(<cFileMask> [,<cAttr>]) ➜ lResult
  removes files which match given <cFileMask> (it may contain path) and returns .T. if at least one file was deleted. Optional <cAttr> parameter can be used to include system "S" and hidden "H" files. If <cAttr> contains "R" letter then before deleting READONLY attribute is removed. See also: hb_vfErase()

• hb_FileExists(<cFileName>) ➜ lExists
  Checks if cFileName exists. Wildcards NOT supported. It does recognize (i.e.: finds) hidden and/or system files. If <cFileName> does not include a path, then it searches ONLY into current working directory (i.e.: ignores any SET DEFAULT and SET PATH setting).
  See also: hb_vfExists()

• hb_FileMatch(<cFileName>, <cPattern>) ➜ lMatch
  returns .T. if <cPattern> matches to <cFileName>, otherwise returns .F.
<cPattern> can contain wildcards.

• hb_FLock(<nHandle>, <nOffset>, <nBytes> [, <nType ]) ➜ lSuccess
  Locks part or all of a file with <nHandle> handler.

• hb_FNameDir(<cFileName>) ➜ cDir
  returns full-path-name of <cFileName>including drive letter and trailing path-separator.
  f.e.:

      cMyfile := hb_CWD() + "mydbf.dbf"    
      ? cMyFile // ➜  C:\Appls\bin\data\mydbf.dbf    
      ? hb_FNameDir( cMyFile ) // ➜ C:\Appls\bin\data\    

• hb_FNameExists(<cFileName>) ➜ lExists
  return true if any kind of directory entry exists with the given name. It doesn't matter if it's a regular file, directory, device, symbolic link or whatever is considered as directory entry, in the file system of host OS. It is somehow similar to hb_FileExists(), which however doesn't take into account directories.

• hb_FNameExt(<cFileName>) ➜ cExt
  returns the extension of <cFileName>, if any, including a leading dot separator. e.g. .txt
  If no extension exists an empty string returned.

• hb_FNameExtSet(<cFileName>, <cExt>) ➜ cFileName
  sets the extension <cExt> of <cFileName> replacing the old one (if any).

• hb_FNameExtSetDef(<cFileName>, <cDefExt>) ➜ cFileName
  sets the extension <cDefExt> of <cFileName> only when it has no extension. doesn't replace an existent extension.

• hb_FNameMerge(<cPath>, <cFileName>, <cFileExtension>) ➜ cMergedName
  merges <cPath>, <cFileName>, <cFileExtension> and returns produced name. (It's the inverse of hb_FNameSplit()).
  NOTE: The validity of parameters passed are not checked, which means any invalid path, filename or extension will give invalid result.

• hb_FNameName(<cFileName>) ➜ cName
  returns bare name of <cFileName>, that is, without path and extension.

• hb_FNameNameExt(<cFileName>) ➜ cNameExt
  returns the full name of <cFileName>, that is, the file name with extension (if any) but without path.

• hb_FNameSplit(<cFileName>, [@cFullPathWithDrive], [@cName], [@cExt], [@cDriveLetter]) ➜ NIL
  splits out the <cFileName> and fills corresponding variables, being passed by reference, with each separate component. (It's the inverse of hb_FNameMerge()).
  After execution and provided that relevant parameters have been passed by reference, they will be:

  • cFullPathWithDrive = Full path with drive letter in front and a path-separator at end.
  • cName = File name without extension.
  • cExt = extension of filename, if any.
  • cDriveLetter = the drive letter as a single character without drive-delimiter (: in windows)

  NOTE: The validity of <cFileName> is not checked, which means incorrectly formed or invalid filenames will give invalid results (effect mainly seen in cFullPathWithDrive content).

• hb_FReadLen(<nFHandle>, <nBytesToRead>) ➜ cBytesRead
  returns a string with length equal or less than <nBytesToRead> or null string if invalid parameters have been passed.

• hb_FSetAttr(<cFileName>, <nAttr>) ➜ lSuccess
  sets <nAttr> to <cFileName>.

• hb_FSetDateTime(<cFileName>, [<dDate>], [<cTime HH;MM;SS>]) ➜ lSuccess
  apply a new date/time to <cFileName>. If invalid date passed, the current system date/time will be used/set.

• hb_FSize(<cFileName>, [<lUseDirEntry>]) ➜ nBytes
  returns the size of <cFileName> in bytes. If the specified file does not exist or is empty, returned value is 0 (zero).
  If optional <lUseDirEntry> parameter is .F., then the file size is determined using internal harbour low-level file access mechanism, otherwise if it's .T. or omitted (in which case it defaults to .T.) the returned file size is that as it's reported by OS's file system (directory entry).

• hb_FTempCreate([<cTempDir>], [<cPrefix>], [<nFileAttr>], [@<cFileName>]) ➜ nFileHandle
  Creates and opens a temporary file. The file name of the newly created file is unique with a default .tmp extension. To obtain the file name of the temporary file, parameter <cFileName> must be passed by reference and it can be used to remove the temporary file from disk when it is no longer needed.

• hb_FTempCreateEx([@<cFileName>], [<cTempDir>], [<cPrefix>], [<cExtension>], [<nFileAttr>]) ➜ nFileHandle
  similar to 'hb_FTempCreate()'. Main differences are:

  • repositioning of arguments (became more intuitive now).
  • added the <cExtension> parameter, so no default .tmp extension
    • NOTE: when <cExtension> it's passed, in order to make sense, it must include a leading extension separator (f.e.: a dot character .) otherwise <cExtension> will be shown concatenated with filename. (a meaningful extension could be: ".temp" while a 'fuzzy' one just "temp")

• hb_FUnlock(<nHandle>, <nOffset>, <nBytes>) ➜ lSuccess
  Unlocks part or all of a file with <nHandle> handler.

• hb_MemoRead(<cFileName>) ➜ cString
  Returns the contents of <cFileName> (file of any size, limited only by system memory resources) as a character string. If <cFileName> is not found, the function returns an empty string. If <cFileName> does not contain a path, only the current directory is searched, (i.e. SET DEFAULT or SET PATH are ignored).
  This function is identical to MemoRead() except it won't truncate the last byte (on non-UNIX compatible systems) if it's an EOF char.

• hb_MemoWrit( <cFileName>, <cString>) ➜ lSuccess
  writes (or save) a memo field or character string to a text file on disk. If not specified a path, <cFileName> is written to the current directory (ignores SET DEFAULT). If <cFileName> already exists, it is overwritten. Returns .T. on success or .F. on failure.
  NOTE: unlike MemoWrit(), this function never adds an EOF Chr( 26 ) character at the end of the created file.

• hb_osPathDelimiters() ➜ cPathDelimiters
  returns \/: on windows, / on *nixes.

• hb_OsPathListSeparator() ➜ PathListSeparator
  returns the character used as separator in a list of paths. It is semicolon ; on windows, colon : on *nixes.

• hb_OsPathSeparator() ➜ OSpathSepator
  returns the character used as path separator; usually backslash \ on Windows, slash / on *nixes. Deprecated! Use hb_ps() instead.

• hb_PathJoin(<cPathAbsolute>, <cPathRelative>) ➜ cResultPath
  attempts to, safely, join the given paths to form a unified one.
  If <cPathRelative> is not string the returned value is null string ""
  otherwise,
  returns: <cPathRelative> when it includes a drive letter or starts with a path delimiter (e.g. :\/) or when <cPathAbsolute> is empty or not path or not string;
  otherwise,
  returns: <cPathAbsolute> properly joined with the <cPathRelelative> at the end. Both paths should be ending with path-separators, in order to be joined correctly. (to ensure this, use hb_DirSepAdd() if needed).

TODO: hb_PathNormalize(), hb_PathRelativize()

• hb_ps() ➜ OSpathSepator
  returns the character used as path separator; usually backslash \ on Windows, slash / on *nixes.

• hb_vfAttrGet( <cFileName>, [@<nAttr>] ) ➜ lOk
  retrieves the file attributes of <cFileName> and store them into <nAttr> variable that must be passed by reference.
  This <nAttr> value is a bitwise combination of all file attribute flags that have been set for the file.

• hb_vfAttrSet( <cFileName>, <nAttr> ) ➜ lOk
  attempts to set the <nAttr> flag(s) for file <cFileName>. returns TRUE on success, otherwise FALSE (i.e. when failed to set new attributes).

  • For a complete list of file attributes supported by both the above functions,
    see the section /* File attributes flags */ into fileio.ch

• hb_vfClose( <pHandle> ) ➜ lOk closes a previously opened file, denoted by its <pHandle>. returns .T. on success, .F. on failure. On invalid <pHandle> RTE occures!

• hb_vfCommit( <pHandle> ) ➜ NIL
  permanently writes any pending data (memory buffers) of <pHandle> file to disk.

• hb_vfConfig( <pHandle>, <nSet>, [ <nParam> ] ) ➜

• hb_vfCopyFile( <cFileSrc>, <cFileDst> ) ➜ nResult
  returns 0 on success, nFError on failure.
  If <cDestinationFile> exists, it will be overwritten, unless it is "read only",
  in which case hb_vfCopyFile() will fail with -1. (see also: hb_FCopy())

• hb_vfDirectory( [<cDirSpec>], [<cAttr>] ) ➜ aDirectory
  returns an array of files matching the <cDirspec> and [<cAttributes>] (if any) filters. The structure of array is identical to that of Directory() except of the F_DATE element, which is a timestamp value type (T) whereas in Directory() it is a date (D).

• hb_vfDirExists( <cDirName> ) ➜ lExists
  checks if a directory specified by <cDirName> exists.

• hb_vfDirMake( <cDirName> ) ➜ nSuccess
  attempts to create a directory with name <cDirName>.
  returns 0 on success, -1 on failure; invoke FError() to determine exact reason of failure.
  See also: hb_DirCreate()

• hb_vfDirRemove( <cDirName> ) ➜ nSuccess
  attempts to remove <cDirName>. It returns 0 on success otherwise -1 value is returned and FError() will return exact OS error code. (e.g. If <cDirName> is not empty hb_vfDirRemove() will fail with -1 and FError() shall return 145.)

• hb_vfDirSpace( <cDirName>, [<nInfoType>] ) ➜ nFreeSpace

• hb_vfEof( <pHandle> ) ➜ lEOF
  returns .T. if the seeking pointer has reached the end of file (EOF), otherwise .F.
<pHandle> (required argument) is the handle of an opened file and if is missing (i.e. not passed) or is not numeric, then (unlike hb_FEof()) an RTE occurs.

• hb_vfErase( <cFileName> ) ➜ nResult
  attempts to remove (delete) file <cFileName> from disk.
  returns zero 0 on success, -1 on failure. See also: hb_FileDelete()

• hb_vfExists( <cFileName> [, @<cDestFileName>] ) ➜ lExists
  checks if <cFileName> exists. Wildcards are NOT supported, recognizes hidden and/or system files. If <cFileName> does not include a path, then it searches (with this order):
  1st) into current directory, 2nd) into directory set by SET DEFAULT setting, 3rd) into directories listed in the SET PATH Harbour setting (not to be confused with PATH envar).
  See also: hb_FileExists()

• hb_vfFlush( <pHandle>, [<lDirtyOnly>] ) ➜ NIL

• hb_vfFromSocket( <pSocket> ) ➜ pFile
  converts socket created by socket open into TCPIP virtual file which works just like files created by hb_vfOpen( "tcp:...", ... )

• hb_vfHandle( <pHandle> ) ➜ nOsHandle

• hb_vfLink( <cExistingFileName>, <cNewFileName> ) ➜ nSuccess
  Creates a Hard Link between an existing file and a new file. Under MS Windows, is only supported on the NTFS file system, and only for files, not directories.

• hb_vfLinkRead( <cFileName> ) ➜ cDestFileName> | "" (empty string)

• hb_vfLinkSym( <cTargetFileName>, <cNewFileName> ) ➜ nSuccess
  Creates a Symbolic Link with the name <cNewFileName>, that points to <cTargetFileName>
  NOTE 1: Symbolic Link creation under MS Windows OS, is supported only on Vista and later versions.
  NOTE 2: Application must be run with Administrator privileges, otherwise the function will fail to create symbolic link.

• hb_vfLoad( <cFileName>, [ <nMaxSize> ] ) ➜ cFileBody | NIL

• hb_vfLock( <pHandle>, <nStart>, <nLen>, [ <nType> ] ) ➜ lOk

• hb_vfLockTest( <pHandle>, <nStart>, <nLen>, [ <nType> ] ) ➜ nPID | 0 (nolock) | -1 (err)

• hb_vfMoveFile( <cFileSrc>, <cFileDst> ) ➜ nResult
  this function allows to move files between different file systems/drives and also different Harbour file IO drivers. This means that file name IO driver prefix is significant in both source and destination file names unless it's local FS operation.
  When both file names point to the same Harbour file IO driver, the function attempts to perform a simple rename operation. If it fails then tries to copy the file to <cFileDst> and remove the source <cFileSrc>.
  Return value: 0 on success, -1 on failure. (Use FError() to determine the reason of failure)
  NOTE: this is a new function, that's been added with 2017-03-15 09:50 UTC+0100 commit (it's not available on earlier versions).

• hb_vfOpen( [@]<cFileName>, [ <nModeAttr> ] ) ➜ pHandle | NIL opens <cFileName> for I/O operation(s) specified by <nModeAttr>.
  on success returns a handle (pointer) to newly opened file; if file couldn't be opened NIL is returned.

• hb_vfRead( <pHandle>, @<cBuff>, [ <nToRead> ], [ <nTimeOut> ] ) ➜ nRead

• hb_vfReadAt( <pHandle>, @<cBuff>, [ <nToRead> ], [ <nAtOffset> ] ) ➜ nRead

• hb_vfReadLen( <pHandle>, <nToRead>, [ <nTimeOut> ] ) ➜ cBuffer

• hb_vfRename( <cFileSrc>, <cFileDst> ) ➜ nResult

• hb_vfSeek( <pHandle>, <nOffset>, [ <nWhence> ] ) ➜ nOffset

• hb_vfSize( <pHandle> | <cFileName> [, <lUseDirEntry> ] ) ➜ nSize
  returns the size in bytes of <cFileName> (or <pHandle>). If the specified file does not exist or is empty, returned value is 0 (zero). If no file or handle specified, RTE occurs (unlike hb_FSize() which returns 0).
  If optional <lUseDirEntry> parameter is .F., then the file size is determined using internal harbour low-level file access mechanism, otherwise if it's .T. or omitted (in which case it defaults to .T.) the returned file size, (I think...) is that as it's reported by OS's file system (directory entry).

• hb_vfTempFile(@<cFileName>, [<cDir>], [<cPrefix>], [<cExt>], [<nAttr>]) ➜ pHandle> | NIL
  creates a temp file and stores its randomly constructed name into cFileName parameter variable (which must be passed by reference).
  Returns a file handler (pointer) on created file or NIL on failure.
  NOTE: the temporary file is created always on local system (i.e. without switching to FILE IO redirector), into <cDir> or into user's %TEMP% directory if no <cDir> specified.
  It remains opened until it's closed either imperatively (f.e. by using hb_vfClose(<pHandle>)) or by Operating System (upon program termination).

• hb_vfTimeGet( <cFileName>, @<tsDateTime> ) ➜ lOk

• hb_vfTimeSet( <cFileName>, <tsDateTime> ) ➜ lOk

• hb_vfTrunc( <pHandle>, [ <nAtOffset> ] ) ➜ lOk

• hb_vfUnlock( <pHandle>, <nStart>, <nLen> ) ➜ lOk

• hb_vfWrite( <pHandle>, <cBuff>, [ <nToWrite> ], [ <nTimeOut> ] ) ➜ nWritten

• hb_vfWriteAt( <pHandle>, <cBuff>, [ <nToWrite> ], [ <nAtOffset> ] ) ➜ nWritten

• DefPath() ➜ cDefaultPath
  returns the current default path, if it has been set, or empty string otherwise. synonym to __DefPath().

• DeleteFile(<cFileName>) ➜ nErrorCode
  returns zero on success or a numeric error code on failure.

• DirChange(<cDir>) ➜ nResult
  Change the current DOS directory. <cDir> is the name of the directory to change to, including the drive. Returns 0 if successful or -1 if there is an argument error or the DOS error code otherwise.

• Directory(<cDirSpec> [, <cAttributes>]) ➜ aDirectory
  returns an array of subarrays; each subarray refers to each file matching <cDirSpec> and has the struct: {cF_NAME, nF_SIZE, dF_DATE, cF_TIME, cF_ATTR}. Wildcards are allowed in <cDirSpec>. If <cDirSpec> is omitted, the default value is *.*.

• DirRemove(<cDirName>) ➜ nSuccess
  removes a specified directory. Returns 0 if successful or -1 if there is an argument error. Otherwise, the DOS error code. Note that you must have sufficient rights to delete a directory. A directory must be empty in order to be deleted.

• DiskChange(<cDrive>) ➜ lSuccess
  returns true (.T.) if successful; otherwise, it returns false (.F.). <cDrive> specifies the letter of the disk drive to change to.

• DiskName() ➜ cDrive
  Returns the letter of the current DOS drive, without a trailing colon.

• DiskSpace([<nDrive>]) ➜ nBytes
  returns the number of bytes of empty space on the specified disk drive. <nDrive> is the number of the drive to query, where one is drive A, two is B, three is C, etc. The default is the current DOS drive if <nDrive> is omitted or specified as zero.

• FClose(<nHandle>) ➜ lError returns true (.T.) or (.F.) if an error occured (e.g.: when an invalid handle used). <nHandle> is the file handle obtained previously from 'FOpen() or 'FCreate()'.

• FCreate(<cFile, [<nAttibute>]) ➜ nHandle
  attempts to create a new binary file. returns the file handle number if succesful or -1 on failure and FError() is set to indicate an error code. <cFile> is the name of the file to create. If the file already exists, its length is truncated to zero without warning. <nAttribute> is one of the binary file attributes and can be: 0=Create normal read/write file (default), 1=Create read-only file, 2=Create hidden file, 4=Create system file. (refer to 'Fileio.ch' for defined constants).

• FErase(<cFile>) ➜ nSuccess
  returns 0 on success or -1 on failure. FError() can be used to determine the nature of the error. <cFile> is the name of the file to be deleted from disk, including extension, optionally preceded by a drive and/or path specification. The function does not use either SET DEFAULT or SET PATH to locate <cFile>. Warning! Files must be CLOSEd before removing them with FErase().

• FError() ➜ nErrorCode
  returns the DOS error from the last file operation as an integer numeric value. If there is no error, returns zero.

• File(<cFileSpec>) ➜ lExist
  checks if a file exists. Supports wildcards, does NOT recognize hidden and/or system files. If the <cFileName> does not include a path, then it searches with this order into: the current directory, the directory set with SET DEFAULT, the directories listed in the SET PATH setting.

• FLock() ➜ lSuccess
  returns .T. if the entire file in a work area successfully locked, otherwise .F.

• FOpen(<cFileName>, [<nMode>]) ➜ nHandle
  returns a file handle or -1 when the operation fails. The cause of failure can be determined by 'FError()'.

• FRead(<nFileHandle>, @<cBuffer>, <nBytes>) ➜ nBytes
  reads <nBytes> characters from a binary file into <cBuffer> variable. Returns the number of bytes read. If the number is less than <nBytes> either the end of file is reached, or a file read error ocurred.

• FReadStr(<nHandle>, <nBytes>) ➜ cString reads characters from an open binary file beginning with the current file pointer position. Characters are read up to <nBytes> or until a null character CHR(0) is encountered. All characters are read including control characters except for CHR(0). The file pointer is then moved forward <nBytes>. If <nBytes> is greater than the number of bytes from the pointer position to the end of the file, the file pointer is positioned to the last byte in the file.

• FRename(<cOldFile>, <cNewFile>) ➜ nSuccess
  changes the name of a specified file to a new name. <cOldFile> is renamed only if it is located in the current directory or in the specified path. Any SET DEFAULT or SET PATH are ignored. If the source directory is different from the target directory, the file is moved to the target directory. In the instance that either <cNewFile> exists or is currently open, function fails and returns -1. Use FError() to determine the exact error. Warning! Files must be CLOSEd before renaming. Attempting to rename an open file will produce unpredictable results. When a database file is renamed, the associated memo file (if any) must also be renamed otherwise you may compromise the integrity of your databases.

• FSeek(<nHandle>, <nOffset>, [<nOrigin>]) ➜ nPosition
  moves the file pointer forward or backward in an open binary file without actually reading the contents. <nHandle> is the file handle obtained from 'FOpen()', or 'FCreate()'. <nOffset> is the number of bytes to move the file pointer from the position defined by <nOrigin>. A positive number moves the pointer forward, and a negative number moves the pointer backward in the file. <nOrigin> defines the starting location of the file pointer. The default value is zero, representing the beginning of file. If <nOrigin> is the end of file, <nOffset> must be zero or negative.

• FWrite(<nHandle>, <cBuffer>, [<nBytes>]) ➜ nBytesWritten
  returns the number of bytes written and should be equal to <nBytes>. If it is lesser or zero, an error occurred.
  <nHandle> is the file handle obtained from 'FOpen()' or 'FCREATE()'. <cBuffer> is the character string to be written. <nBytes> are the number of bytes to be written beginning at the current file pointer position. If omitted, the entire content of <cBuffer> is written.

• MemoRead( <cFileName> ) ➜ cString
  Returns the contents of <cFileName> (file of any size limited only by system memory rersouces) as a character string or empty string if <cFileName> not found. If <cFileName> does not contain a path, only the current directory is searched, (SET DEFAULT or SET PATH are ignored).

• MemoWrit( <cFileName>, <cString> ) ➜ lSuccess
  writes (or save) a memo field or character string to a text file on disk. If not specified a path, <cFileName> is written to the current directory (ignores SET DEFAULT). If <cFileName> already exists, it is overwritten. NOTE: this function always adds an EOF Chr( 26 ) character at the end of the created file.

• TFileRead() ➜ oFileToRead
  returns an instance of the File Reader class. See /contrib/hbmisc/doc/en/ht_class.txt for more..

🔙 Functions-by-category
🔙 Home