RenameFile

Fault tolerant renaming of a file.

Syntax

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

Arguments

<cOldFileName> : The name and path of the existing file. <cNewFileName> : The new name and path for the file.

Returns

<nErrorCode> : A 0 when the file can be renamed; otherwise, it returns an error code. The codes are defined below:

          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 is 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)

See also

DeleteFile()