FILE_COPY

The FILE_COPY procedure copies files, or directories of files, to a new location. The copies retain the permission settings of the original files, and belong to the user that performed the copy. See Rules Used By FILE_COPY for additional information.

FILE_COPY copies files based on their names. To copy data between open files, see the COPY_LUN procedure.

Syntax

FILE_COPY, SourcePath, DestPath [, /ALLOW_SAME] [, /NOEXPAND_PATH] [, /OVERWRITE] [, /RECURSIVE] [, /REQUIRE_DIRECTORY] [, /VERBOSE]

Arguments

SourcePath

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

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 copied. If more than one file is to be copied to a given destination, that destination must exist and be a directory.

Keywords

ALLOW_SAME

Attempting to copy 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 copying is done and the operation is considered successful.

COPY_NAMED_PIPE (UNIX Only)

When FILE_COPY encounters a UNIX named pipe (also called a fifo) in SourcePath, it usually opens it as a regular file and attempts to copy data from it to the destination file. If COPY_NAMED_PIPE is set, FILE_COPY will instead replicate the pipe, creating a new named pipe at the destination using the system mkfifo() function.

COPY_SYMLINK (UNIX Only)

When FILE_COPY encounters a UNIX symbolic link in SourcePath, it attempts to copy the file or directory pointed to by the link. If COPY_SYMLINK is set, FILE_COPY will instead create a symbolic link at the destination with the same name as the source symbolic link, and pointing to the same path as the source.

FORCE (UNIX Only)

Even if the OVERWRITE keyword is set, FILE_COPY does not overwrite files that have their file permissions set to prevent it. If the FORCE keyword is set, such files are quietly removed to make way for the overwrite operation to succeed.

NOEXPAND_PATH

Set this keyword to cause FILE_COPY 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

RECURSIVE

Set this keyword to cause directories specified by SourcePath to be copied to DestPath recursively, preserving the hierarchy and names of the files from the source. If SourcePath includes one or more directories, the RECURSIVE keyword must be set.

REQUIRE_DIRECTORY

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

VERBOSE

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

Rules Used By FILE_COPY

The arguments to FILE_COPY can be scalar or array. If both arguments are arrays, the arrays must contain the same number of elements; in this case, the files are copied pairwise, with each file from SourcePath being copied to the corresponding file in the DestPath. If SourcePath is an array and DestPath is a scalar, all files in SourcePath are copied 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 a given element of SourcePath are copied to the location specified by the corresponding element of DestPath. If multiple files are copied 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 copied using the name specified by DestPath. Any parent directories to the file specified by DestPath must already exist.

If DestPath names an existing regular file, FILE_COPY will not overwrite it, unless the OVERWRITE keyword is specified.

If DestPath names an existing directory and SourcePath names a regular (non-directory) file, then FILE_COPY creates a file with the same name as the file given by SourcePath within the DestPath directory.

If DestPath specifies an existing directory and SourcePath also names a directory, and the RECURSIVE keyword is set, FILE_COPY checks for the existence of a subdirectory of DestPath with the same name as the source directory. If this subdirectory does not exist, it is created using the same permissions as the directory being copied. Then, all the files and directories underneath the source directory are copied to this subdirectory. FILE_COPY will refuse to overwrite existing files within the destination subdirectory unless the OVERWRITE keyword is in effect.

Examples

Make a backup copy of a file named myroutine.pro in the current working directory:

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