/* $DOC$ $AUTHOR$ Copyright 2000 Luiz Rafael Culik $TEMPLATE$ Function $NAME$ FOpen() $CATEGORY$ API $SUBCATEGORY$ FileSys $ONELINER$ Open a file. $SYNTAX$ FOpen( , [] ) --> nHandle $ARGUMENTS$ Name of file to open. File open mode. $RETURNS$ A file handle. $DESCRIPTION$ This function opens a file expressed as and returns a file handle to be used with other low-level file functions. The value of represents the status of the file to be opened; the default value is 0. The file open modes are as follows: nMode Meaning FO_READ Read only FO_WRITE Write only FO_READWRITE Read/write FO_EXCLUSIVE Exclusive read only FO_DENYWRITE Prevent others from writing FO_DENYREAD Deny read only FO_DENYNONE Not deny, Let to others Read / Write FO_SHARED same as FO_DENYNONE
If there is an error in opening a file, a F_ERROR will be returned by the function. Files handles may be in the range of 0 to 65535. The status of the `SET DEFAULT TO` and `SET PATH TO` commands has no effect on this function. Directory names and paths must be specified along with the file that is to be opened. If an error has occurred, see the returns values from FError() for possible reasons for the error. $EXAMPLES$ #include "fileio.ch" IF ( nH := FOpen( "test.txt", FO_READWRITE + FO_DENYNONE ) ) == F_ERROR ? "File can't be opened" ENDIF $STATUS$ R $COMPLIANCE$ C $FILES$ Library is core Header is fileio.ch $SEEALSO$ FCreate(), FError(), FClose() $END$ */ /* $DOC$ $TEMPLATE$ Function $NAME$ FCreate() $CATEGORY$ API $SUBCATEGORY$ FileSys $ONELINER$ Creates a file. $SYNTAX$ FCreate( , [] ) --> nHandle $ARGUMENTS$ is the name of the file to create. Numeric code for the file attributes. $RETURNS$ Numeric file handle to be used in other operations. $DESCRIPTION$ This function creates a new file with a file name of . The default value of is 0 and is used to set the attribute byte for the file being created by this function. The return value will be a file handle that is associated with the new file. This number will be between zero to 65535, inclusive. If an error occurs, the return value of this function will be F_ERROR. If the file already exists, the existing file will be truncated to a file length of 0 bytes. If specified, the following table shows the value for and their related meaning to the file being created by this function. Meaning FC_NORMAL Normal/Default, Read/Write FC_READONLY Read-only file attribute is set FC_HIDDEN Hidden, Excluded from normal DIR search FC_SYSTEM Create, Excluded from normal DIR search
$EXAMPLES$ #include "fileio.ch" IF ( nh := FCreate( "test.txt" ) ) == F_ERROR ? "Cannot create file" ENDIF $STATUS$ R $COMPLIANCE$ C $FILES$ Library is core Header is fileio.ch $SEEALSO$ FClose(), FOpen(), FWrite(), FRead(), FError() $END$ */ /* $DOC$ $AUTHOR$ Copyright 2000 Luiz Rafael Culik $TEMPLATE$ Function $NAME$ FRead() $CATEGORY$ API $SUBCATEGORY$ FileSys $ONELINER$ Reads a specified number of bytes from a file. $SYNTAX$ FRead( , @, ) --> nBytes $ARGUMENTS$ File handle Character expression passed by reference. Number of bytes to read. $RETURNS$ the number of bytes successfully read from the file. $DESCRIPTION$ This function reads the characters from a file whose file handle is into a character memory variable expressed as . The function returns the number of bytes successfully read into . The value of is obtained from either a call to the FOpen() or the FCreate() function. The expression is passed by reference and must be defined before this function is called. It also must be at least the same length as . is the number of bytes to read, starting at the current file pointer position. If this function is successful in reading the characters from the file, the length of or the number of bytes specified in will be the value returned. The current file pointer advances the number of bytes read with each successive read. The return value is the number of bytes successfully read from the file. If a 0 is returned, or if the number of bytes read matches neither the length of nor the specified value in an end-of-file condition has been reached. $EXAMPLES$ #include "fileio.ch" cBuffer := Space( 500 ) IF ( nH := FOpen( "test.txt" ) ) == F_ERROR FRead( nH, @cBuffer, 500 ) ? cbuffer ENDIF FClose( nH ) $STATUS$ R $COMPLIANCE$ C $PLATFORMS$ All $FILES$ Library is core $SEEALSO$ Bin2I(), Bin2L(), Bin2W(), FError(), FWrite() $END$ */ /* $DOC$ $AUTHOR$ Copyright 2000 Luiz Rafael Culik $TEMPLATE$ Function $NAME$ FWrite() $CATEGORY$ API $SUBCATEGORY$ FileSys $ONELINER$ Writes characters to a file. $SYNTAX$ FWrite( , , [] ) --> nBytesWritten $ARGUMENTS$ File handle number. Character expression to be written. The number of bytes to write. $RETURNS$ the number of bytes successfully written. $DESCRIPTION$ This function writes the contents of to the file designated by its file handle . If used, is the number of bytes in to write. The returned value is the number of bytes successfully written to the 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 . The value of is the string or variable to be written to the open file . The value of is the number of bytes to write out to the file. The disk write begins with the current file position in . If this variable is not used, the entire contents of is written to the file. To truncate a file, a call of `FWrite( nHandle, "", 0 )` is needed. $EXAMPLES$ nHandle := FCreate( "test.txt" ) FOR x := 1 TO 10 FWrite( nHandle, hb_ntos( x ) ) NEXT FClose( nHandle ) $STATUS$ R $COMPLIANCE$ C $PLATFORMS$ All $FILES$ Library is core $SEEALSO$ FClose(), FCreate(), FError(), FOpen(), I2Bin(), L2Bin() $END$ */ /* $DOC$ $AUTHOR$ Copyright 2000 Luiz Rafael Culik $TEMPLATE$ Function $NAME$ FError() $CATEGORY$ API $SUBCATEGORY$ FileSys $ONELINER$ Reports the error status of low-level file functions $SYNTAX$ FError() --> nErrorCode $RETURNS$ Value of the OS error last encountered by a low-level file function. FError() Return Values Error Meaning 0 Successful 2 File not found 3 Path not found 4 Too many files open 5 Access denied 6 Invalid handle 8 Insufficient memory 15 Invalid drive specified 19 Attempted to write to a write-protected disk 21 Drive not ready 23 Data CRC error 29 Write fault 30 Read fault 32 Sharing violation 33 Lock Violation
$DESCRIPTION$ After every low-level file function, this function will return a value that provides additional information on the status of the last low-level file function's performance. If the FError() function returns a 0, no error was detected. Below is a table of possibles values returned by the FError() function. $EXAMPLES$ IF ( nHandle := FCreate( "test.txt" ) ) == F_ERROR ? "Cannot create file, OS error", FError() ENDIF $STATUS$ R $COMPLIANCE$ C $FILES$ Library is core $SEEALSO$ FClose(), FErase(), FOpen(), FWrite() $END$ */ /* $DOC$ $AUTHOR$ Copyright 2000 Luiz Rafael Culik $TEMPLATE$ Function $NAME$ FClose() $CATEGORY$ API $SUBCATEGORY$ FileSys $ONELINER$ Closes an open file $SYNTAX$ FClose( ) --> lSuccess $ARGUMENTS$ File handle $RETURNS$ Logical TRUE (.T.) or FALSE (.F.) $DESCRIPTION$ This function closes an open file with a file handle of and writes the associated buffers to the disk. The value is derived from the FCreate() or FOpen() function. $EXAMPLES$ #include "fileio.ch" nHandle := FOpen( "test.txt" ) ? FSeek( nHandle, 0, FS_END ) FClose( nHandle ) $STATUS$ R $COMPLIANCE$ C $FILES$ Library is core $SEEALSO$ FOpen(), FCreate(), FRead(), FWrite(), FError() $END$ */ /* $DOC$ $TEMPLATE$ Function $NAME$ FErase() $CATEGORY$ API $SUBCATEGORY$ FileSys $ONELINER$ Erase a file from disk $SYNTAX$ FErase( ) --> nSuccess $ARGUMENTS$ Name of file to erase. $RETURNS$ 0 if successful, -1 if not $DESCRIPTION$ This function deletes the file specified in from the disk. No extensions are assumed. The drive and path my be included in ; neither the `SET DEFAULT` not the `SET PATH` command controls the performance of this function. If the drive or path is not used, the function will look for the file only on the currently selected directory on the logged drive. If the function is able to successfully delete the file from the disk, the value of the function will be 0; otherwise a -1 will be returned. If not successful, additional information may be obtained by calling the FError() function. Note: Any file to be removed by FErase() must still be closed. $EXAMPLES$ #include "fileio.ch" IF FErase( "test.txt" ) != F_ERROR ? "File successfully erased" ELSE ? "File cannot be deleted" ENDIF $STATUS$ R $COMPLIANCE$ C $FILES$ Library is core $SEEALSO$ FError(), FRename() $END$ */ /* $DOC$ $AUTHOR$ Copyright 2000 Luiz Rafael Culik $TEMPLATE$ Function $NAME$ FRename() $CATEGORY$ API $SUBCATEGORY$ FileSys $ONELINER$ Renames a file $SYNTAX$ FRename( , ) --> nSuccess $ARGUMENTS$ Old file name to be changed New file name $RETURNS$ If successful, a 0 will be returned otherwise, a -1 will be returned. $DESCRIPTION$ This function renames the specified file to . A file name and/or directory name may be specified for either para- meter. However, if a path is supplied as part of and this path is different from either the path specified in 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 . It will not search directories named by the `SET PATH TO` and `SET DEFAULT TO` commands or by the PATH environment variable. If the file specified in 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 information about any error found. $EXAMPLES$ #include "fileio.ch" nResult := FRename( "test.txt", "test1.txt" ) IF nResult != 0 ? "File could not be renamed" ENDIF $STATUS$ R $COMPLIANCE$ C $FILES$ Library is core $SEEALSO$ ERASE, FErase(), FError(), File(), RENAME $END$ */ /* $DOC$ $AUTHOR$ Copyright 2000 Luiz Rafael Culik $TEMPLATE$ Function $NAME$ FSeek() $CATEGORY$ API $SUBCATEGORY$ FileSys $ONELINER$ Positions the file pointer in a file. $SYNTAX$ FSeek( , , [] ) --> nPosition $ARGUMENTS$ File handle. The number of bytes to move. The relative position in the file. $RETURNS$ the current position relative to begin-of-file $DESCRIPTION$ This function sets the file pointer in the file whose file handle is and moves the file pointer by bytes from the file position designated by . The returned value is the relative position of the file pointer to the beginning-of-file marker once the operation has been completed. is the file handle number. It is obtained from the FOpen() or FCreate() function. The value of is the number of bytes to move the file pointer from the position determined by . The value of may be a negative number, suggesting backward movement. The value of designates the starting point from which the file pointer should he moved, as shown in the following table: File position FS_SET Beginning of file FS_RELATIVE Current file pointer position FS_END End of file
If a value is not provided for , 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 STATIC 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 := hb_BAt( hb_eol(), hb_BLeft( cLine, nNumRead ) ) ) == 0 cB := cLine ELSE cB := hb_BLeft( cLine, nEol - 1 ) FSeek( nH, nSavePos + nEol + 1, FS_SET ) ENDIF RETURN nNumRead != 0 $STATUS$ R $COMPLIANCE$ C $FILES$ Library is core Header is fileio.ch $SEEALSO$ FCreate(), FError(), FOpen(), FRead(), FReadStr(), FWrite() $END$ */ /* $DOC$ $AUTHOR$ Copyright 2000 Luiz Rafael Culik $TEMPLATE$ Function $NAME$ File() $CATEGORY$ API $SUBCATEGORY$ FileSys $ONELINER$ Tests for the existence of file(s) $SYNTAX$ File( ) --> lExists $ARGUMENTS$ File name skeleton or file name to find. $RETURNS$ a logical true (.T.) if the file exists or logical false (.F.). $DESCRIPTION$ This function return a logical true (.T.) if the given file name exist. File name skeletons symbols may be used in the file name in , as may the drive and/or path name. If a path is not explicitly specified, File() will look for the file in the `SET DEFAULT` path, then in each `SET PATH path`, until the file is found or there are no more paths to search. The PATH environment variable is never searched and the current drive/directory is only searched if `SET DEFAULT` is blank. $EXAMPLES$ ? File( hb_DirSepToOS( "/hb/doc/pp.txt" ) ) ? File( "*.txt" ) $STATUS$ S (wild card support is missing) $COMPLIANCE$ C $FILES$ Library is core $SEEALSO$ SET DEFAULT, SET PATH, Set() $END$ */ /* $DOC$ $AUTHOR$ Copyright 2000 Luiz Rafael Culik $TEMPLATE$ Function $NAME$ FReadStr() $CATEGORY$ API $SUBCATEGORY$ FileSys $ONELINER$ Reads a string from a file. $SYNTAX$ FReadStr( , ) --> cString $ARGUMENTS$ File handle number. Number of bytes to read. $RETURNS$ an character expression $DESCRIPTION$ This function returns a character string of bytes from a file whose file handle is . The value of the file handle is obtained from either the FOpen() or FCreate() functions. The value of is the number of bytes to read from the file. The returned string will be the number of characters specified in or the number of bytes read before a zero byte is found. $EXAMPLES$ #include "fileio.ch" LOCAL cStr IF ( nH := FOpen( "test.txt" ) ) != F_ERROR cStr := FReadStr( nH, 100 ) ? cStr FClose( nH ) ENDIF $STATUS$ R $COMPLIANCE$ C $PLATFORMS$ All $FILES$ Library is core $SEEALSO$ Bin2I(), Bin2L(), Bin2W(), FError(), FRead(), FSeek() $END$ */ /* $DOC$ $AUTHOR$ Copyright 2000 Luiz Rafael Culik $TEMPLATE$ Command $NAME$ RENAME $CATEGORY$ Command $SUBCATEGORY$ FileSys $ONELINER$ Changes the name of a specified file $SYNTAX$ RENAME TO $ARGUMENTS$ Old file name New File name $DESCRIPTION$ This command changes the name of to . Both and must include a file extension. This command if not affected by the `SET PATH TO` or `SET DEFAULT TO` commands; drive and directory designates must be specified if either file is in a directory other then the default drive and directory. If id currently open or if it previously exists, this command will not perform the desired operation. $EXAMPLES$ RENAME test.txt TO test.old $STATUS$ R $COMPLIANCE$ C $FILES$ Library is core $SEEALSO$ CurDir(), ERASE, File(), FErase(), FRename() $END$ */ /* $DOC$ $AUTHOR$ Copyright 2000 Luiz Rafael Culik $TEMPLATE$ Command $NAME$ ERASE $CATEGORY$ Command $SUBCATEGORY$ FileSys $ONELINER$ Remove a file from disk $SYNTAX$ ERASE $ARGUMENTS$ Name of file to remove $DESCRIPTION$ This command removes a file from the disk. The use of a drive, directory, and wild-card skeleton operator is allowed for the root of the file name. The file extension is required. The `SET DEFAULT` and `SET PATH` commands do not affect this command. The file must be considered closed by the operating system before it may be deleted. $EXAMPLES$ ERASE test.txt $STATUS$ R $COMPLIANCE$ C $SEEALSO$ CurDir(), File(), FErase(), DELETE FILE $END$ */ /* $DOC$ $TEMPLATE$ Command $NAME$ DELETE FILE $CATEGORY$ Command $SUBCATEGORY$ FileSys $ONELINER$ Remove a file from disk $SYNTAX$ DELETE FILE $ARGUMENTS$ Name of file to remove $DESCRIPTION$ This command removes a file from the disk. The use of a drive, directory, and wild-card skeleton operator is allowed for the root of the file name. The file extension is required. The `SET DEFAULT` and `SET PATH` commands do not affect this command. The file must be considered closed by the operating system before it may be deleted. $EXAMPLES$ DELETE FILE test.txt $STATUS$ R $COMPLIANCE$ C $SEEALSO$ CurDir(), File(), FErase(), ERASE $END$ */ /* $DOC$ $AUTHOR$ Copyright 2000 Luiz Rafael Culik $TEMPLATE$ Function $NAME$ CurDir() $CATEGORY$ API $SUBCATEGORY$ FileSys $ONELINER$ Returns the current OS directory name. $SYNTAX$ CurDir( [] ) --> cPath $ARGUMENTS$ OS drive letter $RETURNS$ Name of directory $DESCRIPTION$ This function yields the name of the current OS directory on a specified drive. If is not specified, the currently logged drive will be used. This function should not return the leading and trailing (back)slashes. If an error has been detected by the function, or the current OS directory is the root, the value of the function will be a NULL byte. $EXAMPLES$ ? CurDir() $STATUS$ R $COMPLIANCE$ C $PLATFORMS$ All $FILES$ Library is core $SEEALSO$ File() $END$ */ /* $DOC$ $TEMPLATE$ Command $NAME$ COPY FILE $CATEGORY$ Command $SUBCATEGORY$ FileSys $ONELINER$ Copies a file. $SYNTAX$ COPY FILE TO $ARGUMENTS$ File name of source file File name of target file $DESCRIPTION$ This command makes an exact copy of and names it . Both files must have the file extension included; the drive and the directory names must also be specified if they are different from the default drive and/or director. also can refer to a OS device (e.g. `LPT1`). This command does not observe the `SET PATH TO` or `SET DEFAULT TO` settings. $EXAMPLES$ COPY FILE test.dbf TO adir.prg COPY FILE test.txt TO LPT1 $STATUS$ R $COMPLIANCE$ C $SEEALSO$ ERASE, RENAME, FRename(), FErase() $END$ */ /* $DOC$ $AUTHOR$ Copyright 2000 David G. Holm $TEMPLATE$ Function $NAME$ hb_FEof() $CATEGORY$ API $SUBCATEGORY$ FileSys $ONELINER$ Check for end-of-file. $SYNTAX$ hb_FEof( ) --> lIsEof $ARGUMENTS$ The handle of an open file. $RETURNS$ .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 (F_ERROR) or a C-compiler dependent errno value (EBADF or EINVAL). $EXAMPLES$ LOCAL nH := FOpen( "test.txt" ) ? FReadStr( nH, 80 ) IF hb_FEof( nH ) ? "End-of-file reached" ELSE ? FReadStr( nH, 80 ) ENDIF $STATUS$ R $COMPLIANCE$ H $FILES$ Library is core $SEEALSO$ FError() $END$ */