Routines (alphabetical) > Routines: F > FILE_MOVE

FILE_MOVE

The FILE_MOVE procedure renames files and directories, effectively moving them to a new location. The moved files retain their permission and ownership attributes. Within a given filesystem or volume, FILE_MOVE does not copy file data. Rather, it simply changes the file names by updating the directory structure of the filesystem. This operation is fast and safe, but is only possible within a single filesystem. Attempts to move a regular file from one filesystem to another are carried out by copying the file using FILE_COPY, and then deleting the original file. It is an error to attempt to use FILE_MOVE to move a directory from one filesystem to another.

Syntax

FILE_MOVE, SourcePath, DestPath [, /ALLOW_SAME] [, /NOEXPAND_PATH] [, /OVERWRITE] [, /REQUIRE_DIRECTORY] [, /VERBOSE]

Arguments

SourcePath

A scalar string or string array containing the names of the files or directories to be moved.

DestPath

A scalar string or string array containing the names of the destinations to which the files and directories specified by SourcePath are to be moved. If more than one file is to be moved to a given destination, that destination must exist and be a directory.

Keywords

ALLOW_SAME

Attempting to move a file on top of itself by specifying the same file for SourcePath and DestPath is usually considered to be an error. If the ALLOW_SAME keyword is set, no renaming is done and the operation is considered to be successful.

NOEXPAND_PATH

Set this keyword to cause FILE_MOVE to use SourcePath and DestPath exactly as specified, without expanding any wildcard characters or environment variable names included in the paths. See FILE_SEARCH for details on path expansion.

OVERWRITE

Set this keyword to allow FILE_MOVE to overwrite an existing file.

REQUIRE_DIRECTORY

Set this keyword to cause FILE_MOVE to require that DestPath exist and be a directory.

VERBOSE

Set this keyword to cause FILE_MOVE to issue an informative message for every file move operation it carries out.

Rules Used by FILE_MOVE

The following rules govern how FILE_MOVE operates:

The arguments to FILE_MOVE can be scalar or array. If both arguments are arrays, they must contain the same number of elements, and the files are moved in pairs, with each file from SourcePath being renamed to the corresponding file in the DestPath. If SourcePath is an array and DestPath is a scalar, all files in SourcePath are renamed to the single location given by DestPath, which must exist and be a directory.
Elements of SourcePath may use wildcard characters (as accepted by the FILE_SEARCH function) to specify multiple files. All the files matched for that element of SourcePath are renamed to the location specified by the corresponding element of DestPath. If multiple files are renamed to a single element of DestPath, that element must exist and be a directory.
If a file specified in DestPath does not exist, the corresponding file from SourcePath is moved using the name specified by DestPath. Any parent directories to the filename specified by DestPath must already exist.
If DestPath names an existing regular file, FILE_MOVE will not overwrite it, unless the OVERWRITE keyword is specified.
If DestPath names an existing directory and SourcePath names a regular (non-directory) file, the source file is moved into the specified directory.
If DestPath specifies an existing directory and SourcePath also names a directory, FILE_MOVE checks for the existence of a subdirectory of DestPath with the same name as the source directory. If this subdirectory does not exist, the source directory is moved to the specified location. If the subdirectory does exist, an error is issued, and the rename operation is not carried out.

Examples

Rename the file backup.dat to primary.dat in the current working directory:

FILE_MOVE, 'backup.dat', 'primary.dat'

Create a subdirectory named BACKUP in the current working directory and move all .pro files, makefile, and mydata.dat into it:

FILE_MKDIR, 'BACKUP'

FILE_MOVE, ['*.pro', 'makefile', 'mydata.dat'], 'BACKUP'

Version History

5.6	Introduced