46.25. $renameDirectory

$renameDirectory renames a directory named oldDirName to newDirName. If the directory is to be renamed 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 renamed to baz/gaz by a device MODULE D, oldDirName should be D>foo/bar and newDirName should be D>baz/gaz.

$renameDirectory operates recursively if oldDirName itself contains directories; i.e., those directories also appear in newDirName after the call to $renameDirectory.

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

Valid ctrlBits bits for $renameDirectory are errorOK, alterOK, and $useOriginalFileName. If errorOK is set, then errMsg is not called when $renameDirectory 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 $renameDirectory is subject to improvement if it proves unsatisfactory.