46.24. $rename

$rename renames the existing file with the name oldFileName to have the name newFileName. The rename fails and an error is generated if newFileName is the null STRING.

The valid ctrlBits bits are errorOK, alterOK, $useOriginalFileName, $text, $data, and random. If errorOK is specified and the rename fails, $rename returns FALSE. If errorOK is not specified and the rename fails, a prompt is written to logFile and oldFileName is read from cmdFile. If it is the null STRING, FALSE is returned. Otherwise, another prompt is written to logFile and newFileName is read from cmdFile. $rename then attempts the rename again.

If alterOK is specified on a system without file version numbers (i.e., on a system where the $hasFileVersions bit is not set in $attributes), $rename attempts to delete the file with the name newFileName if it exists before renaming the file with the name oldFileName. $rename fails if such a deletion fails or if a file with the name newFileName exists and alterOK is not specified. On systems with file version numbers, alterOK is ignored; $rename attempts to create a new version of the file named newFileName.

If $useOriginalFileName is set, no logical name lookup or application of searchpaths is done; oldFileName and newFileName are used as specified.

The $text, $data, and random bits are relevant only if $rename should call $copyFile if the source and destination file names specify different device MODULEs (see Section 22.11). If neither $text nor $data is set and oldFileName and newFileName do not use the same MAINSAIL device MODULE, $rename fails.

In order for $rename to use $copyFile, it must know whether the file to be renamed is a text or data file since both files must be opened by MAINSAIL as either text or data files. If you want $rename to do a $copyFile if the device MODULEs are different, specify $text in the ctrlBits argument if the file to be renamed is a text file or $data if it is a data file. These bits serve both to tell $rename to do the $copyFile if necessary, and to indicate the type of the source and destination files. In addition, set the random bit in ctrlBits if it is desired that this bit be set in openBits by the call to open that creates the destination file (if $copyFile is used). This can make a difference on systems like VAX/VMS, where in the absence of the random bit, a text open creates a VAR format file rather than a bytestream file.

Calling $rename with the name of an open file (as oldFileName or newFileName) has undefined effects on the program that has the file open.