60d7ea581b
* doc\en\file.txt
* function FOPEN()
! Fixed the meaning of FO_DENYNONE
+ Added FO_SHARED definition to the table
* function FCREATE()
! Fixed table title name, changed Atribute for Meaning
* function FREAD()
! Fixed typo at $ARGUMENTS$ section
! Removed typo <nHandle> from $RETURNS$ section
! Fixed typo at $EXAMPLES$ section
* function FCLOSE()
! Fixed typo at $EXAMPLES$ section
* function CURDIR()
! Fixed typo at $ARGUMENTS$ section
* function MAKEDIR()
! Fixed typo at $RETURNS$ section
+ doc\es\file.txt
+ Added file's operations document
1099 lines
34 KiB
Plaintext
1099 lines
34 KiB
Plaintext
/*
|
|
* $Id$
|
|
*/
|
|
|
|
/*
|
|
* The following parts are Copyright of the individual authors.
|
|
* www - http://www.harbour-project.org
|
|
*
|
|
* Copyright 2000 Chen Kedem <niki@actcom.co.il>
|
|
* Documentation for: __TYPEFILE(), TYPE
|
|
*
|
|
* Copyright 2000 Luiz Rafael Culik <culik@sl.conex.net>
|
|
* Documentation for: FOPEN(), FCLOSE(), FWRITE(), FSEEK(), FREAD(), FILE(),
|
|
* FREADSTR(), FRENAME(), FERROR(), RENAME, ERASE, CURDIR(),
|
|
* DIRMAKE(),DIRCHANGE(),ISDISK(),DIRREMOVE(),DISKCHANGE(),
|
|
* DIRCHANGE()
|
|
*
|
|
* Copyright 2000 David G. Holm <Harbour@SpaceMoose.com>
|
|
* Documentation for: HB_FEOF()
|
|
*
|
|
* See doc/license.txt for licensing terms.
|
|
*
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $FUNCNAME$
|
|
* FOPEN()
|
|
* $CATEGORY$
|
|
* Low Level
|
|
* $ONELINER$
|
|
* Open a file.
|
|
* $SYNTAX$
|
|
* FOPEN( <cFile>, [<nMode>] ) --> nHandle
|
|
* $ARGUMENTS$
|
|
* <cFile> Name of file to open.
|
|
*
|
|
* <nMode> Dos file open mode.
|
|
* $RETURNS$
|
|
* <nHandle> A file handle.
|
|
* $DESCRIPTION$
|
|
* This function opens a file expressed as <cFile> and returns a
|
|
* file handle to be used with other low-level file functions. The
|
|
* value of <nMode> represents the status of the file to be opened;
|
|
* the default value is 0. The file open modes are as follows:
|
|
|
|
* <table>
|
|
* nMode fileio.ch Meaning
|
|
*
|
|
* 0 FO_READ Read only
|
|
* 1 FO_WRITE Write only
|
|
* 2 FO_READWRITE Read/write
|
|
* 16 FO_EXCLUSIVE Exclusive read only
|
|
* 32 FO_DENYWRITE Prevent others from writing
|
|
* 48 FO_DENYREAD Deny read only
|
|
* 64 FO_DENYNONE Not deny, Let to others Read / Write
|
|
* 64 FO_SHARED same as FO_DENYNONE
|
|
* </table>
|
|
* If there is an error in opening a file, a -1 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 occured, see the returns values from FERROR() for
|
|
* possible reasons for the error.
|
|
* $EXAMPLES$
|
|
*
|
|
* IF (nH:=FOPEN('X.TXT',66) < 0
|
|
* ? 'File can't be opened'
|
|
* ENDIF
|
|
* </fixed>
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* This function is CA-Clipper compliant
|
|
* $FILES$
|
|
* Library is rtl
|
|
* Header is fileio.ch
|
|
* $SEEALSO$
|
|
* FCREATE(),FERROR(),FCLOSE()
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $FUNCNAME$
|
|
* FCREATE()
|
|
* $CATEGORY$
|
|
* Low Level
|
|
* $ONELINER$
|
|
* Creates a file.
|
|
* $SYNTAX$
|
|
* FCREATE( <cFile>, [<nAttribute>] ) --> nHandle
|
|
* $ARGUMENTS$
|
|
* <cFile> is the name of the file to create.
|
|
*
|
|
* <nAttribute> Numeric code for the file attributes.
|
|
* $RETURNS$
|
|
* <nHandle> Numeric file handle to be used in other operations.
|
|
* $DESCRIPTION$
|
|
* This function creates a new file with a filename of <cFile>. The
|
|
* default value of <nAttribute> 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 65,535,
|
|
* inclusive. If an error occurs, the return value of this function
|
|
* will be -1.
|
|
*
|
|
* If the file <cFile> already exists, the existing file will be
|
|
* truncated to a file length of 0 bytes.
|
|
|
|
* If specified, the following table shows the value for <nAttribute>
|
|
* and their related meaning to the file <cFile> being created by
|
|
* this function.
|
|
*
|
|
* <table>
|
|
* <nAttribute> fileio.ch Meaning
|
|
*
|
|
* 0 FC_NORMAL Normal/Default,Read/Write
|
|
* 1 FC_READONLY Read-only file attribute is set
|
|
* 2 FC_HIDDEN Hidden,Excluded from normal DIR search
|
|
* 4 FC_SYSTEM Create,Excluded from normal DIR search
|
|
* </table>
|
|
* $EXAMPLES$
|
|
* IF (nh:=FCREATE("TEST.TXT") <0
|
|
* ? "Cannot create file"
|
|
* ENDIF
|
|
* </fixed>
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* This function is CA-Clipper compliant.
|
|
* $FILES$
|
|
* Library is rtl
|
|
* Header is fileio.ch
|
|
* $SEEALSO$
|
|
* FCLOSE(),FOPEN(),FWRITE(),FREAD(),FERROR()
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $FUNCNAME$
|
|
* FREAD()
|
|
* $CATEGORY$
|
|
* Low Level
|
|
* $ONELINER$
|
|
* Reads a specified number of bytes from a file.
|
|
* $SYNTAX$
|
|
* FREAD( <nHandle>, @<cBuffer>, <nBytes> ) --> nBytes
|
|
* $ARGUMENTS$
|
|
* <nHandle> Dos file handle
|
|
|
|
* <cBuffer> Character expression passed by reference.
|
|
|
|
* <nBytes> Number of bytes to read.
|
|
* $RETURNS$
|
|
* <nBytes> the number of bytes successfully read from the file.
|
|
* <nHandle>
|
|
* $DESCRIPTION$
|
|
* This function reads the characters from a file whose file handle
|
|
* is <nHandle> into a character memory variable expressed as <cBuffer>.
|
|
* The function returns the number of bytes successfully read into
|
|
* <cBuffer>.
|
|
|
|
* The value of <nHandle> is obtained from either a call to the FOPEN()
|
|
* or the FCREATE() function.
|
|
|
|
* The <cBuffer> expression is passed by reference and must be defined
|
|
* before this function is called. It also must be at least the same
|
|
* length as <nBytes>.
|
|
|
|
* <nBytes> 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 <cBuffer> or the number
|
|
* of bytes specified in <nBytes> 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 <cBuffer> nor the specified
|
|
* value in <nBytes> an end-of-file condition has been reached.
|
|
* $EXAMPLES$
|
|
* cBuffer:=SPACE(500)
|
|
* IF (nH:=FOPEN('X.TXT))>0
|
|
* FREAD(nH,@cBuffer,500)
|
|
* ? cbuffer
|
|
* ENDIF
|
|
* FCLOSE(nH)
|
|
* </fixed>
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* This function is CA-Clipper compliant, but also extends the possible
|
|
* buffer size to strings greater than 65K (depending on platform).
|
|
* $FILES$
|
|
* Library is rtl
|
|
* $SEEALSO$
|
|
* BIN2I(),BIN2L(),BIN2W(),FERROR(),FWRITE()
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $FUNCNAME$
|
|
* FWRITE()
|
|
* $CATEGORY$
|
|
* Low Level
|
|
* $ONELINER$
|
|
* Writes characters to a file.
|
|
* $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)
|
|
</fixed>
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* This function is not CA-Clipper compatile since
|
|
* it can writes strings greather the 64K
|
|
* $FILES$
|
|
* Library is rtl
|
|
* $SEEALSO$
|
|
* FCLOSE(),FCREATE(),FERROR(),FOPEN(),I2BIN(),L2BIN()
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $FUNCNAME$
|
|
* FERROR()
|
|
* $CATEGORY$
|
|
* Low Level
|
|
* $ONELINER$
|
|
* Reports the error status of low-level file functions
|
|
* $SYNTAX$
|
|
* FERROR() --> <nErrorCode>
|
|
* $RETURNS$
|
|
* <nErrorCode> Value of the DOS error last encountered by a
|
|
* low-level file function.
|
|
*
|
|
* FERROR() Return Values
|
|
*
|
|
* <table>
|
|
* 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
|
|
* </table>
|
|
* $DESCRIPTION$
|
|
* After every low-level file function,this function will return
|
|
* a value that provides additional informationon the status of
|
|
* the last low-level file functions'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$
|
|
* #include "Fileio.ch"
|
|
* //
|
|
* nHandle := FCREATE("Temp.txt", FC_NORMAL)
|
|
* IF FERROR() != 0
|
|
* ? "Cannot create file, DOS error ", FERROR()
|
|
* ENDIF
|
|
* </fixed>
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* This function is CA-Clipper compatible
|
|
* $FILES$
|
|
* Library is rtl
|
|
* $SEEALSO$
|
|
* FCLOSE(),FERASE(),FOPEN(),FWRITE()
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $FUNCNAME$
|
|
* FCLOSE()
|
|
* $CATEGORY$
|
|
* Low Level
|
|
* $ONELINER$
|
|
* Closes an open file
|
|
* $SYNTAX$
|
|
* FCLOSE( <nHandle> ) --> <lSuccess>
|
|
* $ARGUMENTS$
|
|
* <nHandle> DOS file handle
|
|
* $RETURNS$
|
|
* <lSuccess> Logical TRUE (.T.) or FALSE (.F.)
|
|
* $DESCRIPTION$
|
|
* This function closes an open file with a dos file handle
|
|
* of <nHandle> and writes the associated DOS buffer to the
|
|
* disk. The <nHandle> value is derived from the FCREATE()
|
|
* or FOPEN() function.
|
|
* $EXAMPLES$
|
|
* nHandle:=FOPEN('x.txt')
|
|
* ? FSEEK(nHandle, 0, 2)
|
|
* FCLOSE(nHandle)
|
|
* </fixed>
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* This function is CA-Clipper compliant
|
|
* $FILES$
|
|
* Library is rtl
|
|
* $SEEALSO$
|
|
* FOPEN(),FCREATE(),FREAD(),FWRITE(),FERROR()
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $FUNCNAME$
|
|
* FERASE()
|
|
* $CATEGORY$
|
|
* Low Level
|
|
* $ONELINER$
|
|
* Erase a file from disk
|
|
* $SYNTAX$
|
|
* FERASE( <cFile> ) --> nSuccess
|
|
* $ARGUMENTS$
|
|
* <cFile> Name of file to erase.
|
|
* $RETURNS$
|
|
* <nSuccess> 0 if successful, -1 if not
|
|
* $DESCRIPTION$
|
|
* This function deletes the file specified in <cFile> from the disk.
|
|
* No extensions are assumed. The drive and path my be included in
|
|
* <cFile>; 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
|
|
* direcytory 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 successfu, aditional information may be
|
|
* obtained by calling the FERROR() function.
|
|
*
|
|
* Note: Any file to be removed by FERASE() must still be closed.
|
|
*
|
|
* $EXAMPLES$
|
|
* IF (FERASE("TEST.TXT")==0)
|
|
* ? "File successfully erased"
|
|
* ELSE
|
|
* ? "File can not be deleted"
|
|
* ENDIF
|
|
* </fixed>
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* This function is CA-Clipper Compatible
|
|
* $FILES$
|
|
* Library is rtl
|
|
* $SEEALSO$
|
|
* FERROR(),FRENAME()
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $FUNCNAME$
|
|
* FRENAME()
|
|
* $CATEGORY$
|
|
* File management
|
|
* $ONELINER$
|
|
* Renames a file
|
|
* $SYNTAX$
|
|
* FRENAME( <cOldFile>, <cNewFile> ) --> nSuccess
|
|
* $ARGUMENTS$
|
|
* <cOldFile> Old filenarne to he changed
|
|
|
|
* <cNewFile> New filename
|
|
* $RETURNS$
|
|
* <nSuccess> If sucessful, a 0 will he returned otherwise,
|
|
* a -1 will be returned.
|
|
* $DESCRIPTION$
|
|
* This function renames the specified file <cOldFile> to <cNewFile>.
|
|
* A filename and/or directory name may be specified for either para-
|
|
* meter. However, if a path is supplied as part of <cNewFile> and
|
|
* this path is different from either the path specified in <cOldFile>
|
|
* 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 <cOldFile>. It will not search
|
|
* directories named by the SET PATH TO and SET DEFAULT TO commands
|
|
* or by the DOS PATH statement.
|
|
|
|
* If the file specified in <cNewFile> 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 infor-
|
|
* mation about any error found.
|
|
* $EXAMPLES$
|
|
* nResult:=FRENAME("x.txt","x1.txt")
|
|
* IF nResult <0
|
|
* ? "File could not be renamed."
|
|
* ENDIF
|
|
* </fixed>
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* This function is CA-Clipper compliant
|
|
* $FILES$
|
|
* Library is rtl
|
|
* $SEEALSO$
|
|
* ERASE,FERASE(),FERROR(),FILE(),RENAME
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $FUNCNAME$
|
|
* FSEEK()
|
|
* $CATEGORY$
|
|
* Low Level
|
|
* $ONELINER$
|
|
* Positions the file pointer in a file.
|
|
* $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:
|
|
|
|
* <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
|
|
* </table>
|
|
* 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
|
|
*
|
|
* #define EOL HB_OSNEWLINE()
|
|
* 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( 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
|
|
* </fixed>
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* This function is CA-Clipper compliant.
|
|
* $FILES$
|
|
* Library is rtl
|
|
* Header is fileio.ch
|
|
* $SEEALSO$
|
|
* FCREATE(),FERROR(),FOPEN(),FREAD(),FREADSTR(),FWRITE()
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $FUNCNAME$
|
|
* FILE()
|
|
* $CATEGORY$
|
|
* File management
|
|
* $ONELINER$
|
|
* Tests for the existence of file(s)
|
|
* $SYNTAX$
|
|
* FILE( <cFileSpec> ) --> lExists
|
|
* $ARGUMENTS$
|
|
* <cFileSpec> Dos Skeleton or file name to find.
|
|
* $RETURNS$
|
|
* <lExists> a logical true (.T.) if the file exists or logical
|
|
* false (.F.).
|
|
* $DESCRIPTION$
|
|
* This function return a logical true (.T.) if the given filename
|
|
* <cFileSpec> exist.
|
|
|
|
* Dos skeletons symbols may be used in the filename in <cFileSpec>,
|
|
* as may the drive and/or path name. If a path is not explicity
|
|
* 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 DOS PATH is never searched and the
|
|
* current drive/directory is only searched if SET DEFAULT is blank.
|
|
* $EXAMPLES$
|
|
* ? file('c:\harbour\doc\compiler.txt")
|
|
* ? file('c:/harbour/doc/subcodes.txt")
|
|
* </fixed>
|
|
* $STATUS$
|
|
* S (wild card support is missing)
|
|
* $COMPLIANCE$
|
|
* This function is CA-Clipper compatible.
|
|
* $FILES$
|
|
* Library is rtl
|
|
* $SEEALSO$
|
|
* SET DEFAULT,SET PATH,SET()
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $FUNCNAME$
|
|
* FREADSTR()
|
|
* $CATEGORY$
|
|
* Low Level
|
|
* $ONELINER$
|
|
* Reads a string from a file.
|
|
* $SYNTAX$
|
|
* FREADSTR(<nHandle>, <nBytes>) --> cString
|
|
* $ARGUMENTS$
|
|
* <nHandle> DOS file handle number.
|
|
*
|
|
* <nBytes> Number of bytes to read.
|
|
* $RETURNS$
|
|
* <cString> an characted expression
|
|
* $DESCRIPTION$
|
|
* This function returns a character string of <nBytes> bytes from a
|
|
* file whose DOS file handle is <nHandle>.
|
|
|
|
* The value of the file handle <nHandle> is obtained from either the
|
|
* FOPEN() or FCREATE() functions.
|
|
|
|
* The value of <nBytes> is the number of bytes to read from the file.
|
|
* The returned string will be the number of characters specified in
|
|
* <nBytes> or the number of bytes read before an end-of-file charac-
|
|
* ter (ASCII 26) is found.
|
|
|
|
* NOTE This function is similar to the FREAD() function, except that
|
|
* it will not read binary characters that may he required as part of
|
|
* a header of a file construct. Characters Such as CHR(0) and CHR(26)
|
|
* may keep this function from performing its intended operation. In this
|
|
* event, the FREAD() function should he used in place of the FREADSTR()
|
|
* function.
|
|
* $EXAMPLES$
|
|
* IF ( nH := FOPEN("x.txt") ) > 0
|
|
* cStr := Freadstr(nH,100)
|
|
* ? cStr
|
|
* ENDIF
|
|
* FCLOSE(nH)
|
|
* </fixed>
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* This function is not CA-Clipper compliant since may read
|
|
* strings greather the 65K depending of platform.
|
|
* $FILES$
|
|
* Library is rtl
|
|
* $SEEALSO$
|
|
* BIN2I(),BIN2L(),BIN2W(),FERROR(),FREAD(),FSEEK()
|
|
* $END$
|
|
*/
|
|
|
|
/* HARBOUR COMMANDS */
|
|
|
|
/* $DOC$
|
|
* $FUNCNAME$
|
|
* RENAME
|
|
* $CATEGORY$
|
|
* Command
|
|
* $ONELINER$
|
|
* Changes the name of a specified file
|
|
* $SYNTAX$
|
|
* RENAME <cOldFile> TO <cNewFile>
|
|
* $ARGUMENTS$
|
|
* <cOldFile> Old filename
|
|
|
|
* <cNewFile> New Filename
|
|
* $DESCRIPTION$
|
|
* This command changes the name of <cOldFile> to <cNewFile>.Both
|
|
* <cOldFile> and <cNewFile> must include a file extension.This command
|
|
* if not affected by the SET PATH TO or SET DEFAULT TO commands;drive
|
|
* and directoy designaters must be specified if either file is in a
|
|
* directory other then the default drive and directory.
|
|
*
|
|
* If <cNewFile> id currently open or if it previously exists, this
|
|
* command will not perform the desired operation.
|
|
* $EXAMPLES$
|
|
* RENAME c:\autoexec.bat to c:\autoexec.old
|
|
* </fixed>
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* This command is CA-Clipper compatible
|
|
* $FILES$
|
|
* Library is rtl
|
|
* $SEEALSO$
|
|
* CURDIR(),ERASE,FILE(),FERASE(),FRENAME()
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $FUNCNAME$
|
|
* ERASE
|
|
* $CATEGORY$
|
|
* Command
|
|
* $ONELINER$
|
|
* Remove a file from disk
|
|
* $SYNTAX$
|
|
* ERASE <xcFile>
|
|
* $ARGUMENTS$
|
|
* <xcFile> Name of file to remove
|
|
* $DESCRIPTION$
|
|
* This command removes a file from the disk.The use of a drive,directo-
|
|
* ry,and wild-card skeleton operator is allowed for the root of the
|
|
* filename.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 c:\autoexec.bat
|
|
* Erase c:/temp/read.txt
|
|
* </fixed>
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* This command is CA-Clipper compatible
|
|
* $SEEALSO$
|
|
* CURDIR(),FILE(),FERASE(),DELETE FILE
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $FUNCNAME$
|
|
* DELETE FILE
|
|
* $CATEGORY$
|
|
* Command
|
|
* $ONELINER$
|
|
* Remove a file from disk
|
|
* $SYNTAX$
|
|
* DELETE FILE <xcFile>
|
|
* $ARGUMENTS$
|
|
* <xcFile> Name of file to remove
|
|
* $DESCRIPTION$
|
|
* This command removes a file from the disk.The use of a drive,directo-
|
|
* ry,and wild-card skeleton operator is allowed for the root of the
|
|
* filename.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 c:\autoexec.bat
|
|
* Erase c:/temp/read.txt
|
|
* </fixed>
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* This command is CA-Clipper compatible
|
|
* $SEEALSO$
|
|
* CURDIR(),FILE(),FERASE(),ERASE
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $FUNCNAME$
|
|
* __TYPEFILE()
|
|
* $CATEGORY$
|
|
* Data input and output
|
|
* $ONELINER$
|
|
* Show the content of a file on the console and/or printer
|
|
* $SYNTAX$
|
|
* __TYPEFILE( <cFile>, [<lPrint>] ) --> NIL
|
|
* $ARGUMENTS$
|
|
* <cFile> is a name of the file to display. If the file have an
|
|
* extension, it must be specified (there is no default value).
|
|
*
|
|
* <lPrint> is an optional logical value that specifies whether the
|
|
* output should go only to the screen (.F.) or to both the screen and
|
|
* printer (.T.), the default is (.F.).
|
|
* $RETURNS$
|
|
* __TYPEFILE() always return NIL.
|
|
* $DESCRIPTION$
|
|
* __TYPEFILE() function type the content of a text file on the screen
|
|
* with an option to send this information also to the printer. The
|
|
* file is displayed as is without any headings or formating.
|
|
*
|
|
* If <cFile> contain no path, __TYPEFILE() try to find the file first
|
|
* in the SET DEFAULT directory and then in search all of the SET PATH
|
|
* directories. If <cFile> can not be found a run-time error occur.
|
|
*
|
|
* Use SET CONSOLE OFF to suppress screen output.
|
|
* You can pause the output using Ctrl-S, press any key to resume.
|
|
*
|
|
* __TYPEFILE() function is used in the preprocessing of the TYPE
|
|
* command.
|
|
* $EXAMPLES$
|
|
* The following examples assume a file name MyText.DAT exist in all
|
|
* specified paths, a run-time error would displayed if it does not
|
|
*
|
|
* // display MyText.DAT file on screen
|
|
* __TYPEFILE( "MyText.DAT" )
|
|
*
|
|
* // display MyText.DAT file on screen and printer
|
|
* __TYPEFILE( "MyText.DAT", .T. )
|
|
*
|
|
* // display MyText.DAT file on printer only
|
|
* SET CONSOLE OFF
|
|
* __TYPEFILE( "MyText.DAT", .T. )
|
|
* SET CONSOLE ON
|
|
* </fixed>
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* __TYPEFILE() works exactly like CA-Clipper's __TYPEFILE()
|
|
* $FILES$
|
|
* Library is rtl
|
|
* $SEEALSO$
|
|
* COPY FILE,SET DEFAULT,SET PATH,SET PRINTER,TYPE
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $FUNCNAME$
|
|
* TYPE
|
|
* $CATEGORY$
|
|
* Command
|
|
* $ONELINER$
|
|
* Show the content of a file on the console, printer or file
|
|
* $SYNTAX$
|
|
* TYPE <xcFile> [TO PRINTER] [TO FILE <xcDestFile>]
|
|
* $ARGUMENTS$
|
|
* <xcFile> is a name of the file to display. If the file have an
|
|
* extension, it must be specified (there is no default value).
|
|
* It can be specified as literal file name or as a character
|
|
* expression enclosed in parentheses.
|
|
*
|
|
* TO PRINTER is an optional keyword that specifies that the output
|
|
* should go to both the screen and printer.
|
|
*
|
|
* TO FILE <xcDestFile> copy the source <xcFile> also to a file. If no
|
|
* extension is given (.txt) is added to the output file name.
|
|
* <xcDestFile> can be specified as literal file name or as a character
|
|
* expression enclosed in parentheses.
|
|
* $DESCRIPTION$
|
|
* TYPE command type the content of a text file on the screen
|
|
* with an option to send this information also to the printer or to
|
|
* an alternate file. The file is displayed as is without any headings
|
|
* or formating.
|
|
*
|
|
* If <xcFile> contain no path, TYPE try to find the file first in the
|
|
* SET DEFAULT directory and then in search all of the SET PATH
|
|
* directories. If <xcFile> can not be found a run-time error occur.
|
|
*
|
|
* If <xcDestFile> contain no path it is created in the SET DEFAULT
|
|
* directory.
|
|
*
|
|
* Use SET CONSOLE OFF to suppress screen output.
|
|
* You can pause the output using Ctrl-S, press any key to resume.
|
|
* $EXAMPLES$
|
|
* The following examples assume a file name MyText.DAT exist in all
|
|
* specified paths, a run-time error would displayed if it does not
|
|
*
|
|
* // display MyText.DAT file on screen
|
|
* TYPE MyText.DAT
|
|
*
|
|
* // display MyText.DAT file on screen and printer
|
|
* TYPE MyText.DAT TO PRINTER
|
|
*
|
|
* // display MyText.DAT file on printer only
|
|
* SET CONSOLE OFF
|
|
* TYPE MyText.DAT TO PRINTER
|
|
* SET CONSOLE ON
|
|
*
|
|
* // display MyText.DAT file on screen and into a file MyReport.txt
|
|
* TYPE MyText.DAT TO FILE MyReport
|
|
* </fixed>
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* TYPE works exactly like CA-Clipper's TYPE
|
|
* $SEEALSO$
|
|
* COPY FILE,SET DEFAULT,SET PATH,SET PRINTER,__TYPEFILE()
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $FUNCNAME$
|
|
* CURDIR()
|
|
* $CATEGORY$
|
|
* Low Level
|
|
* $ONELINER$
|
|
* Returns the current OS directory name.
|
|
* $SYNTAX$
|
|
* CURDIR( [<cDrive>] ) --> cPath
|
|
* $ARGUMENTS$
|
|
* <cDrive> OS drive letter
|
|
* $RETURNS$
|
|
* <cPath> Name of directory
|
|
* $DESCRIPTION$
|
|
* This function yields the name of the current OS directory on a
|
|
* specified drive.If <cDrive> is not speficied,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()
|
|
* </fixed>
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* This function is Ca-Clipper Compatible
|
|
* $PLATFORMS$
|
|
* ALL
|
|
* $FILES$
|
|
* Library is rtl
|
|
* $SEEALSO$
|
|
* FILE()
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $FUNCNAME$
|
|
* COPY FILE
|
|
* $CATEGORY$
|
|
* Command
|
|
* $ONELINER$
|
|
* Copies a file.
|
|
* $SYNTAX$
|
|
* COPY FILE <cfile> TO <cfile1>
|
|
* $ARGUMENTS$
|
|
* <cFile> Filename of source file
|
|
* <cFile1> Filename of target file
|
|
* $DESCRIPTION$
|
|
* This command makes an exact copy of <cFile> and names it <cFile1>.
|
|
* 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.<cFile1> also can refer to a OS
|
|
* device (e.g. LPT1).This command does not obsert the SET PATH TO or
|
|
* SET DEFAULT TO settings.
|
|
* $EXAMPLES$
|
|
* COPY FILE C:\HARBOUR\TESTS\ADIRTEST.PRG to C:\TEMP\ADIRTEST.PRG
|
|
* COPY FILE c:\harbour\utils\hbdoc\gennf.prg to LPT1
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* This command is Ca-Clipper compliant
|
|
* $SEEALSO$
|
|
* ERASE,RENAME,FRENAME(),FERASE()
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $FUNCNAME$
|
|
* HB_FEOF()
|
|
* $CATEGORY$
|
|
* Low Level
|
|
* $ONELINER$
|
|
* Check for end-of-file.
|
|
* $SYNTAX$
|
|
* HB_FEOF( <nHandle> ) --> lIsEof
|
|
* $ARGUMENTS$
|
|
* <nHandle> The handle of an open file.
|
|
* $RETURNS$
|
|
* <lIsEof> .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 E-O-F.
|
|
|
|
* 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
|
|
* (FS_ERROR) or a C-compiler dependent errno value (EBADF or EINVAL).
|
|
* $EXAMPLES$
|
|
* nH:=FOPEN('FILE.TXT')
|
|
* ? FREADSTR(nH,80)
|
|
* IF HB_FEOF(nH)
|
|
* ? 'End-of-file reached.'
|
|
* ELSE
|
|
* ? FREADSTR(nH,80)
|
|
* ENDIF
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* This function is a Harbour extension
|
|
* $FILES$
|
|
* Library is rtl
|
|
* $SEEALSO$
|
|
* FERROR()
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $FUNCNAME$
|
|
* DIRREMOVE()
|
|
* $CATEGORY$
|
|
* Low Level
|
|
* $ONELINER$
|
|
* Attempt to remove an directory
|
|
* $SYNTAX$
|
|
* DIRCHANGE( <cDirectory> ) --> nError
|
|
* $ARGUMENTS$
|
|
* <cDirectory> The name of the directory you want to remove.
|
|
* $RETURNS$
|
|
* <nError> 0 if directory was successfully removed, otherwise
|
|
* the number of the last error.
|
|
* $DESCRIPTION$
|
|
* This function attempt to remove the specified directory in <cDirectory>
|
|
* If this function fail, the it will return the last OS error code number.
|
|
* See FERROR() function for the description of the error.
|
|
* $EXAMPLES$
|
|
* cDir:= ".\Backup"
|
|
* if (DIRREMOVE(cDir)==0)
|
|
* ? "Remove of directory",cDir, "was successfull"
|
|
* endif
|
|
* $TESTS$
|
|
* See examples
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* This function is CA Clipper 5.3 compliant
|
|
* $PLATFORMS$
|
|
* All
|
|
* $FILES$
|
|
* Library is rtl
|
|
* $SEEALSO$
|
|
* MAKEDIR(),DIRCHANGE(),ISDISK(),DISKCHANGE(),DISKNAME(),FERROR()
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $FUNCNAME$
|
|
* DIRCHANGE()
|
|
* $CATEGORY$
|
|
* Low Level
|
|
* $ONELINER$
|
|
* Changes the directory
|
|
* $SYNTAX$
|
|
* DIRCHANGE( <cDirectory> ) --> nError
|
|
* $ARGUMENTS$
|
|
* <cDirectory> The name of the directory you want do change into.
|
|
* $RETURNS$
|
|
* <nError> 0 if directory was successfully changed, otherwise
|
|
* the number of the last error.
|
|
* $DESCRIPTION$
|
|
* This function attempt to change the current directory to the one
|
|
* specidied in <cDirectory>.If this function fail, the it will return
|
|
* the last OS error code number.See FERROR() function for the
|
|
* description of the error.
|
|
* $EXAMPLES$
|
|
* if (DIRCHANGE("\temp")==0)
|
|
* ? "Change to diretory was successfull"
|
|
* endif
|
|
* $TESTS$
|
|
* See examples
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* This function is CA Clipper 5.3 compliant
|
|
* $PLATFORMS$
|
|
* All
|
|
* $FILES$
|
|
* Library is rtl
|
|
* $SEEALSO$
|
|
* MAKEDIR(),DIRREMOVE(),ISDISK(),DISKCHANGE(),DISKNAME(),FERROR()
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $FUNCNAME$
|
|
* MAKEDIR()
|
|
* $CATEGORY$
|
|
* Low Level
|
|
* $ONELINER$
|
|
* Create a new directory
|
|
* $SYNTAX$
|
|
* MAKEDIR( <cDirectory> ) --> nError
|
|
* $ARGUMENTS$
|
|
* <cDirectory> The name of the directory you want to create.
|
|
* $RETURNS$
|
|
* <nError> 0 if directory was successfully created, otherwise
|
|
* the number of the last error.
|
|
* $DESCRIPTION$
|
|
* This function attempt to create a new directory with the name contained
|
|
* in <cDirectory>.If this function fail, the it will return the last OS
|
|
* error code number.See FERROR() function for the description of the
|
|
* error
|
|
* $EXAMPLES$
|
|
* cDir:= "Temp"
|
|
* If (MAKEDIR( cDir)==0)
|
|
* ? "Directory ",cDir," successfully created
|
|
* Endif
|
|
* $TESTS$
|
|
* See examples
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* This function is CA Clipper 5.3 compliant
|
|
* $PLATFORMS$
|
|
* All
|
|
* $FILES$
|
|
* Library is rtl
|
|
* $SEEALSO$
|
|
* DIRCHANGE(),DIRREMOVE(),ISDISK(),DISKCHANGE(),DISKNAME(),FERROR()
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $FUNCNAME$
|
|
* ISDISK()
|
|
* $CATEGORY$
|
|
* Low Level
|
|
* $ONELINER$
|
|
* Verify if a drive is ready
|
|
* $SYNTAX$
|
|
* ISDISK( <cDrive> ) --> lSuccess
|
|
* $ARGUMENTS$
|
|
* <cDrive> An valid Drive letter
|
|
* $RETURNS$
|
|
* <lSuccess> .T. is the drive is ready, otherwise .F.
|
|
* $DESCRIPTION$
|
|
* This function attempts to access a drive. If the access to the drive
|
|
* was successfull, it will return true (.T.), otherwise false(.F.).This
|
|
* function is usefull for backup function, so you can determine if the
|
|
* drive that will recieve the backup data is ready or not.
|
|
* $EXAMPLES$
|
|
* IF ISDISK("A")
|
|
* ? "Drive is ready "
|
|
* Endif
|
|
* $TESTS$
|
|
* See Examples
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* This function is CA Clipper 5.3 compliant
|
|
* $PLATFORMS$
|
|
* All
|
|
* $FILES$
|
|
* Library is rtl
|
|
* $SEEALSO$
|
|
* DIRCHANGE(),MAKEDIR(),DIRREMOVE(),DISKCHANGE(),DISKNAME()
|
|
* $END$
|
|
*/
|