/*
 * $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()
 *
 * See doc/license.txt for licensing terms.
 *
 */

/*  $DOC$
 *  $FUNCNAME$
 *      FOPEN()
 *  $CATEGORY$
 *      Low level file handling
 *  $ONELINER$
 *      Open a file.
 *  $SYNTAX$
 *      FOPEN( <cFile>, [<nMode>] ) --> nHandle
 *  $ARGUMENTS$
 *      <cFile> Name of file to open

 *      <nMode> Dos file open mode   
 *  $RETURNS$
 *      <nHandle> a DOS file handle   
 *  $DESCRIPTION$
 *      This function opens a file expressed as <cFile> and returns a DOS
 *      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 DOS file open modes are as the follows:   

 *  <table>
 *       nMode        Meaning
 *
 *       0              Read only
 *       1              Write only
 *       2              Read/write
 *       16             Exclusive read only
 *       17             Exclusive write only
 *       18             Exclusive read/write only
 *       32             Prevent others from writing
 *       33             Prevent others from reading
 *       34             Prevent read/write only
 *       48             Deny read only
 *       49             Deny write only
 *       50             Deny read/Write
 *       64             Share read only
 *       65             Share write only
 *       66             Share read/write
 *  </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 cann't be open'
 *      ENDIF
 *  </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This function is CA-Clipper compliant   
 *  $FILES$
 *      Library is Rtl.lib
 *  $SEEALSO$
 *      FCREATE(),FERROR(),FCLOSE()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      FCREATE()
 *  $CATEGORY$
 *      Low level file handling
 *  $ONELINER$
 *      Creates a file
 *  $SYNTAX$
 *      FCREATE( <cFile>, [<nAttribute>] ) --> nHandle
 *  $ARGUMENTS$
 *      <cFile> is the name of the file to create.   
 *
 *      <nAttribute> Numeric code for the DOS file attribute   
 *  $RETURNS$
 *      <nHandle>  Numeric expression   
 *  $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 DOS
 *      attribute byte for the file being created by this function.
 *      The return value will be DOS 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 lenght of 0 bytes.   

 *      If specified, the folowing table shows the value for <nAttribute>
 *      and their related meaning to the file <cFile> being created by
 *      this Function.   

 *  <table>
 *       <nAttribute>   File Attribute
 *
 *       0              Normal/Default,Read/Write
 *       1              Read-only,Attempting to open for output returns an error
 *       2              Hidden,Excluded from normal DIR search                                  
 *       4              Create,Excluded from normal DIR search
 *  </table>
 *  $EXAMPLES$
 *      IF (nh:=FCREATE("TEST.TXT") <0
 *          ? "Can not create file"
 *      ENDIF
 *    </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This function is CA-Clipper compliant   
 *  $FILES$
 *      Library is Rtl.lib
 *  $SEEALSO$
 *      FCLOSE(),FOPEN(),FWRITE(),FREAD(),FERROR()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      FREAD()
 *  $CATEGORY$
 *      Low level file handling
 *  $ONELINER$
 *      Reads a specified number of bytes from a file.
 *  $SYNTAX$
 *      FREAD( <nHandle>, @<cBuffer>, <nBytes> ) --> nBytes
 *  $ARGUMENTS$
 *      <nHandle>     Dos file handle   

 *      <cBufferVar>  Character expression passed by reference   

 *      <nBytes>      Number of bytes to read.   
 *  $RETURNS$
 *      <nBytes> the number of bytes successfyly read from the file
 *      <nHandle>   
 *  $DESCRIPTION$
 *      This function reads the characters from a DOS file whose file handle
 *      is <nHandle> into it 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 it 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 DOS
 *      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
 *      DOS file pointer advances the number of bytes read with each succe-
 *      ssive read.The return value is the number of byte successfully read
 *      from the file <nHandle>. 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(Hh,@cBuffer,500)
 *         ? cbuffer
 *      ENDIF
 *      FCLOSE(nH)
 *      </fixed>
 *  $STATUS$
 *     R
 *  $COMPLIANCE$
 *     This function is not CA-Clipper compliant since may can read
 *     strings greather the 65K depending of platform.   
 *  $FILES$
 *      Library is Rtl.lib
 *  $SEEALSO$
 *     BIN2I(),BIN2L(),BIN2W(),FERROR(),FWRITE()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      FWRITE()
 *  $CATEGORY$
 *      Low level file handling
 *  $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.lib
 *  $SEEALSO$
 *      FCLOSE(),FCREATE(),FERROR(),FOPEN(),I2BIN(),L2BIN()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      FERROR()
 *  $CATEGORY$
 *      Low level file handling
 *  $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.lib
 *  $SEEALSO$
 *     FCLOSE(),FERASE(),FOPEN(),FWRITE()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *     FCLOSE()
 *  $CATEGORY$
 *     Low level file handling
 *  $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(nHandle0,2)
 *     FCLOSE(nHandle)
 *     </fixed>
 *  $STATUS$
 *     R
 *  $COMPLIANCE$
 *     This function is CA-Clipper compliant   
 *  $FILES$
 *      Library is Rtl.lib
 *  $SEEALSO$
 *     FOPEN(),FCREATE(),FREAD(),FWRITE(),FERROR()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      FERASE()
 *  $CATEGORY$
 *      Low level file handling
 *  $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.lib
 *  $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.lib
 *  $SEEALSO$
 *     ERASE,FERASE(),FERROR(),FILE(),RENAME
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      FSEEK()
 *  $CATEGORY$
 *      Low level file handling
 *  $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>      File position
 *
 *       0              Beginning of file
 *       1              Current file pointer position
 *       2              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.lib
 *      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 drive are not explicity
 *      specified,FILE() will first search the current drive and directory,
 *      and will look for the file in the directories specified by SET PATH
 *      TO and SET DEFAULT TO commands.However, this command does not look
 *      at the values in the DOS PATH command.   
 *  $EXAMPLES$
 *      ? file('c:\harbour\doc\compiler.txt")
 *      ? file('c:/harbour/doc/subcodes.txt")
 *  </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This function is CA-Clipper compatible.   
 *  $FILES$
 *      Library is Rtl.lib
 *  $SEEALSO$
 *      SET PATH,SET DEFAULT,SET()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      FREADSTR()
 *  $CATEGORY$
 *      Low level file handling
 *  $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.lib
 *  $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.lib
 *  $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.lib
 *  $SEEALSO$
 *      COPY FILE,SET DEFAULT,SET PATH,SET PRINTER,TYPE
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      TYPE
 *  $CATEGORY$
 *      Data input and output
 *  $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$
 *      <cDir> 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.lib
 *  $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$
 */
