hb_F - Petewg/harbour-core GitHub Wiki

🔙 Home

• 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_FieldDec(<cFieldName>|<nFieldPos>) ➜ nDecimals
  returns the number of decimal places of <cFieldName> or 0 for non-existent/empty <cFieldName>

• hb_FieldLen(<cFieldName>|<nFieldPos>) ➜ nLen
  returns the length of <cFieldName> or 0 for non-existent/empty <cFieldName>.

• hb_FieldType(<cFieldName>|<nFieldPos>) ➜ cType
  returns a single character indicating the data type of the specified field, or a null string "" for non-existent/empty <cFieldName>.

• 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>) ➜ .cExtension
  returns the extension of <cFileName>, if any, including a leading dot separator. e.g. .txt
  If the elaborated <cFileName> has no extension, an empty string is 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_ForNext([<nStart>], <nEnd>|<bEnd>, <bCode> [, nStep ]) ➜ NIL|nEnd
  This function is a "functionification" of the FOR ... NEXT traditional loop.
  It is similar to for(initStatement; testExpression; updateStatement) loop in C-language but it's more self-contained, since it includes the processing code that shall be executed during loop.
  Executes (evaluates) iteratively the <bCode> code-block until the iteration counter reaches the <nEnd> value, starting from <nStart>. The <bCode> code-block receives iteratively the successive value of the internal iteration counter as a parameter. If a bEnd code-block (instead of nEnd) is passed as 2nd parameter, it is evaluated first and the value returned by evaluation is used as <nEnd>. This means that <bEnd> should return numeric value, otherwise the function will break-exit immediately, without neither warning or error. When needed, the value returned by hb_ForNext() can be examined to identify the result of <bEnd>.

  • NOTES:
    • Reverse iteration is not supported!
    • when the 2nd parameter is numeric (and not a code-block) the hb_ForNext() returns NIL.
    • If <nStart> is NIL or non-numeric, defaults to 0 (zero).

  Example usage:

   // print the squares of numbers 1...10 , using the value returned 
   // by <bEnd> code-block as ending value.
   ? hb_ForNext( 1, { || Iif( .T., 10, 0 ) }, { | i | Qout( i^2 ) }, 1 ) 
   
   // print all extended ASCII characters (codes 0...255)
   // note the absence of the <nStart> -- it becomes zero by default
    ? hb_ForNext( , 255, { | i | QQout( Chr( i ) ) } ) 

• 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:

  • convenient recomposition of arguments.
  • added the <cExtension> parameter, so no default .tmp extension
  • NOTE: when <cExtension> is passed, in order to make a sense, it must include a leading extension separator (f.e.: a dot character .) otherwise it will be joined with filename in a single word; (a meaningful extension might be: ".temp" while a 'fuzzy' one just "temp").

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

🔙 Home