hb_V - Petewg/harbour-core GitHub Wiki

🔙 Home

• hb_Val( <cStr> [, <nLen> ] ) ➜ nVal
  similar to Val() (refer for more) but sets the length for numeric result equal to passed string length or to <nLen> parameter if it'is large enough to hold the resulted number.

• hb_ValToExp(<xVal>, [<lRaw>]) ➜ cExp
  converts a value of any type (including complex types) into a string for serialization. The returned string cExp can be evaluated (f.e. with the macro operator &) to obtain the original value. Optional 2nd parameter <lRaw>, if set to .T., forces all raw serialization format (by default is .F.).

• hb_ValToStr( <xValue> ) ➜ cText
  converts a value of any type into a human readable string expression. Complex types are converted to an empty string.

• hb_Version( [<n>] ) ➜ xVersion
  returns Harbour version info. where <n> might be:
  2 ➜ HB_VERSION_MAJOR (num)
  3 ➜ HB_VERSION_MINOR (num)
  NIL (empty) ➜ detailed version descriptor (string)
  Please refer to <hbver.ch> for (a lot) more!

^{[according to this opinion the «vf» prefix stands for (v)irtual (f)ile, (I couldn't find a relevant explicit reference by the FILE IO author himself, confirming this assertion, but it is an «expansion» which makes sense).]}

• 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>) ➜ lResult
  closes a previously opened file, handled by <pHandle> file handle.
  returns .T. on success, .F. on failure. Using invalid <pHandle> an RTE occurs.

• hb_vfCommit(<pHandle>) ➜ NIL
  permanently writes to storage media any pending data (cached memory buffers) of the file being processed.
  <pHandle> (required argument) is the handle of the opened file.

• hb_vfConfig( <pHandle>, <nSet>, [ <nParam> ] ) ➜ xResult
  «...is general function which can be used by redirector authors to make some special operations which are specific to given device.»
  -- for details, please contact the author of this remark, who happens to be the creator of the function, as well as, of the entire «vf» squad! :-)

• hb_vfCopyFile( <cFileSrc>, <cFileDst> ) ➜ nResult
  attempts to copy <cFileSrc> source file to <cFileDst> destination file. Both arguments can contain full path designator. Wildcard characters are not allowed.
  returns 0 on success, -1 on failure. Use FError() to retrieve exact O/S error code.
  If destination file <cFileDst> exists, it will be overwritten, unless it is read only, in which case the function will fail with -1 and FError() should return 05 (Access denied).
  see also: hb_FCopy()

• hb_vfCopyFileEx(<cFileSrc>, <cFileDst>, [<nBufSize>], [<lTimePreserve>], [<bCallBack>]) ➜ nResult
  This is an 'extended' version of hb_vfCopyFile() function; supports a callback function (or a code-block) which, if properly utilized, can inform the users about copy progress, (e.g., display a progress bar, percentage completion etc).
  Purpose: copy a file from one location to another --or even to the same location but with a different name. Must be noted that the copy operation is always done locally («...it is never redirected to remote server»).
  - <cFileSrc> is the file-name of the source file being copied. Can contain full path designator, i.e. drive and or folder-name(s).
  - <cFileDst> the destination file-name. Can contain full path designator.
       In both file-names (source & destination), wildcard characters are not allowed!
  - nBufSize is the read/write buffer size (the size of memory chunk utilized inside copying loop); the less this size the more the I/O accesses performed on the storage media, which 'translates' to longer time of copy completion. As suggested by developer, «...for very big files setting nBufSize to greater value, i.e., 16777216 (16 MiB), may increase performance.»
  - lTimePreserve is a boolean flag specifying whether the timestamp of source file will be preserved to copied file or not; if not specified, default is TRUE, i.e., the newly copied file will retain the original timestamp, otherwise, when FALSE specified, a timestamp designated by OS will be used (normally, the current date-time).
  - bCallBack is a function-symbol or code-block which will be fired at the beginning of copy operation and then repeatedly executed every time a chunk of nBufSize bytes is written. It receives two parameters: nBytesWritten and nTotalSize; (there is a warning here by author: «... nTotalSize could be 0 (zero!) when non regular files like pipes or sockets are copied.»)
  - return value 0 on success, -1 on failure. Use FError() to retrieve exact O/S error code.
  (Note: new function, available after 2024-05-09 23:23 UTC+0200 Przemyslaw Czerpak commit, not available in earlier versions).

• 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_vfDirBuild(<cDir>) ➜ lSuccess
  attempts to create (or to validate the existence of) the given <cDir> directory hierarchy.
  for more, see hb_DirBuild()

• hb_vfDirUnbuild(<cDir>) ➜ lSuccess
  attempts to remove the given <cDir> directory and all sub-directories inside it.
  for more, see hb_DirUnBuild()
  Note: both of the above <Build/Unbuild> functions are new available after 2021-04-14 22:25 UTC+0200 commit.

• 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 is returned and FError() will return the exact O/S error code. (e.g., if <cDirName> is not empty, hb_vfDirRemove() will fail with -1 and FError() will return 145.)

• hb_vfDirSpace( <cDirName>, [<nInfoType>] ) ➜ nFreeSpace
  Returns space info for the given <cDirName>.
  If no <nInfoType> supplied it defaults to HB_DISK_AVAIL (i.e. returns available free space).
  Other <nInfoType> specifiers are HB_DISK_FREE, HB_DISK_USEDand HB_DISK_TOTAL.
  See also: hb_DiskSpace()

• 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 (runtime error) occurs.

• hb_vfErase( <cFileName> ) ➜ nResult
  attempts to remove (delete) file <cFileName> from disk.
  returns zero 0 on success, -1 on failure. To determine exact reason of failure, the FError() function can be used.
  Typically, hb_vfErase() function shall fail to erase a "Read-Only" file. In that case, in place of hb_vfErase(), could be used the hb_FileDelete() function which can delete such a Read-Only file, by removing "R" attribute before the erase. (Worth to note that hb_FileDelete() itself, calls internally the hb_vfErase() function to finally do the deletion). See also: FErase()

• hb_vfExists( <cFileName> [, @<cDestFileName>] ) ➜ lExists
  checks if <cFileName> exists.
  Wildcards are NOT supported but function recognizes hidden and/or system files.
  If <cFileName> does not include a path, then tries to locate the file by searching (with this order):

  • into current directory
  • into directory set by SET DEFAULT setting,
  • 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
  returns the O/S file handle (numeric) of a previously opened (or created/opened) file denoted by its <pHandle> (pointer). Using invalid <pHandle> an RTE occurs.

• hb_vfIsLocal(<cFileName>) ➜ lLocalFileSystem
  returns TRUE if cFileName> is not redirected to any Harbour File IO driver but access local file system API.
  (Note: new function, available after 2023-04-21 11:45 UTC+0200 commit, not available in earlier versions).

• 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, available after 2017-03-15 09:50 UTC+0100 commit, not available in earlier versions).

• hb_vfNameExists(<cName>) ➜ lExists
  see hb_FNameExists()

• hb_vfOpen([@]<cFileName>, [<nModeAttr>]) ➜ pHandle | NIL
  attempts to open <cFileName> for I/O operation(s) that are specified by <nModeAttr> (see \include\fileio.ch for available opening flags).
  If <cFileName> cannot be found (f.e. when it doesn't exist) and HB_FO_CREAT is specified in <nModeAttr> the file is created/opened otherwise (file doesn't exist and no HB_FO_CREAT is specified) the function fails and returns NIL.
  If <cFileName> parameter has been passed by reference then the function honors SET DEFAULT and/or SET PATH settings (if any), otherwise it seeks for the file either into the directory specified by <cFileName> (if it includes one) or into the current directory (if <cFileName> does not not include a path).
  The function returns a handle (pointer) to the newly opened file; if the file couldn't be opened NIL is returned.
  NOTE: avoid HB_FO_CREAT and HB_FO_EXCL combination, i.e., hb_vfOpen(<cFile>, HB_FO_CREAT + HB_FO_EXCL), because, if the the file fails to be opened, the actual reason is not clear (was it due to file creation failure or because the file already exists?). Using of hb_vfExists() to check if the file exists and then hb_vfOpen(<cFile> ) or hb_vfOpen(<cFile>, HB_FO_CREAT) to create it if needed, is much more unambiguous and secure.

• 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
  attempts to rename the given file/directory named <cFileSrc> to new name <cFileDst>.
  returns 0 (zero) on success, non-zero on failure. Use FError() to determine the actual error code. See also: FRename()

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

• hb_vfSize( <pHandle> | <cFileName> [, <lUseDirEntry> ] ) ➜ nSize
  returns the size (in bytes) of the file specified by <pHandle> or <cFileName>.
  If the specified file does not exist or is empty, returned value is 0 (zero).
  If neither filename or handle specified, an RTE occurs (unlike hb_FSize() which returns 0).
  If optional <lUseDirEntry> parameter is .F., then the file size is determined using harbour's internal 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). This parameter is significant only when the file has been specified by passing a character value parameter <cFileName> (i.e. when <pHandle> used then <lUseDirEntry> is meaningless).

• 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>|@<dDate> [, @<cTime>] ) ➜ lOk
  retrieves date and time of a given <cFileName> file.
  Values are stored in the passed by reference parameters either as a TimeStamp or separate dDate and cTime values.

• hb_vfTimeSet( <cFileName>, <tsDateTime>|<dDate> [, <cTime>] ) ➜ lOk
  sets (changes) date and time of file <cFileName>.
  Argument for 2nd parameter can be either a valid TimeStamp or a Date value. If it is of date type (implying it must have been initialized as such before passed), then a 3rd cTime parameter can be optionally used (which may include a milliseconds fraction) to set file-time as well.

  • NOTES:
    • on Windows O/S, after successful completion of this function, both the Last Access Time and Last Write Time are affected (changed) while Creation Time remains unaffected.
    • Again on Windows O/S, Windows Explorer, in certain situations, shows up wrong (both Access and Write) dates/times for file, to the contrary of command line where they're displayed correctly. (tested on Windows 7 pro, p.d. - 12/03/2018).

• 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

🔙 Home