32.55. $copyDirectory

$copyDirectory copies a directory named oldDirName to newDirName. If the directory is to be copied by a device MODULE other than the default disk device MODULE, the device prefix should be prepended to both oldDirName and newDirName, separated from the names by the STRING $devModBrkStr. For example, if $devModBrkStr is ">" and the directory foo/bar is to be copied to baz/gaz by a device MODULE D, oldDirName should be "D>foo/bar" and newDirName should be "D>baz/gaz".

$copyDirectory copies all the files contained in oldDirName into newDirName. It operates recursively if oldDirName itself contains directories; i.e., copies of the contained directories also appear in newDirName after the call to $copyDirectory.

$copyDirectory returns TRUE on success, FALSE on failure. If it fails, msg is set to an error message describing the failure.

Valid ctrlBits bits for $copyDirectory are errorOK, alterOK, and $useOriginalFileName. If errorOK is set, then errMsg is not called when $copyDirectory fails. If alterOK is set, then if a file or directory named newDirName already exists, it is deleted without prompting the user; otherwise, if newDirName exists, the user is prompted with OK to delete newDirName before the existing file or directory is replaced. If $useOriginalFileName is set, no logical file name or file searchpath substitution is performed on oldDirName or newDirName.

The interface of $copyDirectory is subject to improvement if it proves unsatisfactory.