8.5.13 Rename (rename a file)

Purpose

Renames a file.

In JP1/Script 07-50 or later, the command supports large files.

Syntax

Rename (OldName, [NewName] [, Method])

Arguments

OldName

Specify the old file name or folder name as a character string or as a variable that stores this value.

NewName

Specify the new file name or folder name as a character string or as a variable that stores this value. If you use a full path to specify the old file name or folder name, you must also specify a full path for the new file name or folder name.

If you omit this argument and specify Reboot as the update method, the file will be deleted.

Method

Specify the update method as one of the following values:

Value	Meaning
`Replace`	Rename the file even if a file of the name specified in `NewName` already exists.
`NoReplace` (from version 06-00)	Return an error occurs if a file of the name specified in `NewName` already exists.
`Reboot`	Rename the file at system restart.
`FreeExt`	Replace the file extension with any one of extensions `.000` to `.999` that is not already in use. If you specify this option, any new name is ignored. Unlike the `Pile` option of the `Copy` command, if an existing file with an extension from `.000` to `.999` has the same contents as the file specified in `NewName`, the `Rename` command simply deletes the file specified in `OldName`.

This value is optional. If you omit this value, Replace is assumed.

If you specify Reboot, execute the script file as a user who has administrator permissions. For details, see 1.8.2 Command behavior.

Description

The Rename command renames the file specified in OldName as the file name specified in NewName. The command returns True on successful execution, or False if an error occurs.

If you omit or set a zero-length string ("") in NewName, and specify Reboot as the update method, the file will be deleted.

Note

Take care when specifying a file in the folder set in the environment variable ProgramFiles (normally the Program Files folder on the system drive) or WinDir (normally the Windows folder on the system drive). For details, see 1.8.2 Command behavior.

Examples

' Rename a file.
Dim outDir1
outDir1 = _BIN_
Rename (outDir1+"DEFAULT.DAT", outDir1+"DEFAULT.000",
        FreeExt)
Rename (TEMP_+"WORK.DAT", outDir1+"DEFAULT.DAT")
 
' Copy a file and delete the original (not otherwise
' possible).
Copy (_BIN_+"ABC.EXE", _BIN_+"XYZ.EXE", Overwrite)
Rename (_BIN_+"ABC.EXE", "", Reboot)

JP1/Script version

Supported from JP1/Script 01-00.

To Page Top