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

FileDelete

Deletes file(s) by name and attribute

Syntax

      FileDelete(<cFileMask>, [<nFileAttr>]) --> <lDeleted>

Arguments

<cFileMask> : Designates the file or files to delete.

<nFileAttr> : Designates one of the following file attributes. The default value is 32.

          File Attribute Coding
          ---------------------------------------------------------------
          Value     Symb. constants   Definition
          ---------------------------------------------------------------
          0         FA_NORMAL
          1         FA_READONLY       Read-only
          2         FA_HIDDEN         HIDDEN (Concealed files)
          4         FA_SYSTEM         SYSTEM (System files)
          8         FA_VOLUME         VOLUME (Name of floppy/hard disk)
          32        FA_ARCHIVE        ARCHIVE (Changed since last backup)
          63        Everything
          ---------------------------------------------------------------

Returns

<lDeleted> .T. when at least one or more files are deleted; otherwise, .F. is returned.

Description

ERASE command and FErase() function doesn’t support “wildcard” ( “*” / “?” ) characters in file specification. FileDelete() function of tools library does. Occasionally, you will need to clean up a floppy or a hard disk or delete whole file groups. This function deletes entire file groups with a function call, without using the RUN command.

Notes

Warning! FileDelete() can also can delete system files.

. The default standard attribute is archive (32). Drive and path designations, and wildcards are permitted.

. Subdirectories must be deleted with the help of the DirRemove() function.

Example

      Attempt to delete all index files, then display the completion status:

      IF FileDelete("*.NDX")
         ? "Files deleted."
      ELSE
         ? "No files found."
      ENDIF

Seealso

DeleteFile()

 DELETEFILE()
 Deletes an error-tolerant file

 Syntax

     DELETEFILE(<cFileName>) --> nErrorCode

 Argument

     <cFileName>  Designates which file name to delete.

 Returns

     DELETEFILE() returns a code that signifies its completion status:

     Table 7-1:  DELETEFILE() Error Codes
     ------------------------------------------------------------------------
     Code    Symb. constants     Definition
     ------------------------------------------------------------------------
      0      NO_DISK_ERR         No error occurs
     -2      ER_FILE_NOT_FOUND   File not found
     -3      ER_PATH_NOT_FOUND   Path not found
     -5      ER_ACCESS_DENIED    Access denied (e.g., file is read-only)
     ------------------------------------------------------------------------

 Description

     In contrast to FILEDELETE(), which permits you to specify file groups
     with wildcards, DELETEFILE() only accepts specific file names.  However,
     the function avoids all DOS error messages and returns an error code
     directly to the calling program.  This makes error-tolerant erasures in
     networks possible (see Examples).

 Note

     .  You can use a drive designator and path name, but no
        wildcards.

 Examples

     .  How NOT to delete a file in a network environment:

        IF FILE ("TEST.DBF")
           * Is it actually possible to delete the file?
           DELETE FILE TEST.DBF
        ENDIF

     .  This is a better way:

        nStatus  :=  DELETEFILE("TEST.DBF")
        IF nStatus == 0
           ? "File deleted."
        ELSE
           IF nStatus == -5
              ? "ACCESS DENIED!"
              ? "File in use elsewhere!"
           ENDIF
        ENDIF

See Also: FILEDELETE() RENAMEFILE()