RENAM

Rename a file

xcall RENAM(new_name, old_name)

Arguments

new_name

An expression that contains the new specification to be assigned to the file. (a)

old_name

An expression that contains the file’s current specification. (a)

Discussion

The RENAM subroutine changes the name of a file. See OPEN for the correct format of a file specification. If new_name has no extension, the extension defaults to the old_name extension.

If you specify a new filename that already exists, one of two things occurs, depending on whether the FLAGS subroutine runtime option flag 3 is set:

If flag 3 is set, the runtime checks for an existing file with the same name, and a “Cannot supersede existing file” error ($ERR_REPLAC) is generated.
If flag 3 is not set, the runtime does not check for duplicate filenames, and the existing file is overwritten as part of the renaming process. For example, if file a.b already exists and the following statement is executed, the current a.b file is deleted, and the current old.ddf is renamed to become the new a.b file:

xcall renam("a.b", "old.ddf")

If the RENAM subroutine can’t find the specified old filename, you’ll get a “File not found” error ($ERR_FNF). If old_name is an ISAM file and new_name doesn’t have an extension, both the data file and the index file are renamed to new_name, with the same extension as old_name.

Old_name and new_name can also include a search list logical, which specifies one or more directory paths in which to search for the file. If a search list logical is used on the new_name specification, the renamed file is placed in the first directory specified in the search list.

When using remote specifications for new_name and old_name, any server name that is specified as part of new_name is ignored, and new_name is assumed to be on the same machine as old_name.

Before renaming a file, make sure you close any channels that your program has open to that file.

If either the old or the new file is already open by any user, a “File in use by another user” error ($ERR_FINUSE) is generated.

On OpenVMS,

The new file must be on the same device as the old file. If new_name doesn’t contain an explicit version number, and a file already exists with the same name, the file is renamed to the next higher version number. If new_name does contain an explicit, nonzero version number and a file of the same name and version number already exists, the RENAM subroutine replaces the existing file (unless flag 3 is set).
If system option #35 is set for VAX DIBOL compatibility, and no version number is specified on new_name, all previous versions of new_name are deleted before the rename occurs (if the source is accessible). If, however, flag 3 is set, if any version of new_name exists, a fatal “Invalid option” error (INVOPT) is generated.
If new_name or old_name ends with a semicolon but no version number, Synergy DBL assumes the version number is zero. For example, if you rename file.ddf; to new.ddf, the RENAM subroutine renames file.ddf;0 to new.ddf.
You cannot rename across logical drives.

On Windows, because a virus scanner can take several seconds to scan a file, the RENAM routine will retry for up to five seconds before reporting that a file is in use. (The default is 50 1/10th-of-a-second retries, or 5 seconds. You can change the retry count by setting the RETRYTIME environment variable.) The best way to avoid the wait time is to try to open the file exclusively first, so that an $ERR_FINUSE error will occur if the file is being used. This works only if the virus scanner is set to scan on CLOSE or WRITE. If the virus scanner instead performs a default scan of all files on OPEN, READ, and WRITE, an endless loop can occur.