Click above to get retro games delivered to your door ever month!

 RENAMEFILE()
 Fault tolerant renaming of a file.
------------------------------------------------------------------------------
 Syntax

     RENAMEFILE(<cOldFileName>, <cNewFileName>) --> nErrorCode

 Arguments

     <cOldFileName>   Designates the name and path of the existing file.

     <cNewFileName>   Designates the new name and path for the file.

 Returns

     The function returns a 0 when the file can be renamed; otherwise, it
     returns an error code.  The codes are defined below:

     Table 7-19:  RENAMEFILE() Error Codes
     ------------------------------------------------------------------------
     Code    Definition
     ------------------------------------------------------------------------
      0      No error found
     -2      File not found
     -3      Path not found
     -5      Access denied (e.g., in network)
     -17     Target file not on same network
     ------------------------------------------------------------------------

 Description

     Currently, you may not be able to rename a file on a network drive.
     Another user may currently have the file open.  RENAMEFILE() actually
     says "attempt a RENAME and, should the situation arise, return an error
     code".  This follows the basic programming philosophy:  never fall into
     an error trap when you can avoid it.

 Notes

     .  The <cNewFileName> must always contain the complete path for
        the designated file (see Examples).

     .  Wildcard characters cannot be used.

 Examples

     .  Rename a file from OLD to NEW:

        IF RENAMEFILE("OLD", "NEW") = 0
           ? "The file can be renamed!"
        ENDIF

     .  Use the path from the old file specification for the new name:

        cFSpecOld   := "C:\TEST\TEST.TXT"
        cFileName   := TOKEN(cFSpecOld, ":\")      // last token
        cFSpecNew   := BEFOREATNUM(cFileName, cFSpecOld) + "TEST.NEW"
        RENAMEFILE(cFSpecOld, cFSpecNew)