Rename a file

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
xcall RENAM(new_name, old_name)



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


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


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:

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.

In previous versions of Synergy DBL, you could also specify a channel argument on the RENAM subroutine. This syntax is still valid, but channel is ignored.

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,

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.

See also


The following example renames “beta” to “alpha” and oldfile to newfile. If a file called newfile already exists, you’ll get an error message and oldfile won’t be renamed.

    oldfile             ,a*,    ""
    newfile             ,a*,    "dp3:a12.c"
    xcall flags(7000320)
    xcall renam("alpha", "beta")
    xcall renam(newfile, oldfile)

The example below uses a search list logical. We’ll assume the MYFILES logical is defined as follows:


Synergy DBL first looks in /usr/programs for the from file, and if it doesn’t find it, it looks in
/usr/programs/new. The renamed file is placed in /usr/programs.

xcall renam("MYFILES:to", "MYFILES:from")