# RENAME

> [HTML Version](renamesbr.htm)

_Reviewed May 2026_

**xcall RENAME, oldname, newname, status**

RENAME (aka RENAM) provides the means to programmatically rename files. It will fail if _oldname_ does not exist, or if _newname _does. Both _oldname_ and _newname _support either DevPPN or native operating system filenames, and also support the use of embedded environment variables (e.g. %MIAME%).

**Parameters**

_oldname_  ([String](string.md))  \[in\]

current file name

_newname_  ([String](string.md))  \[in\]

name to which the file is being changed

_status_  (F,6)  \[out\]

0 if successful, other if not

Errors are  logged to the ashlog.log file. In addition, if the SYSERR TRACE is active, they will be displayed on the screen. This is helpful in  recognizing and tracking down mysterious Windows rename errors.

**History**

2015 July, A-Shell 6.1.1414:  Under Windows, XCALL RENAME will now overwrite an existing destination file. It was never documented what it should do here, but this matches the way it has always worked under Unix. 

The motivation for the change now is that it has been determined that Windows file sharing networks can sometimes yield false positives—i.e. they report that the destination file exists when it doesn't—causing applications to fail unexpectedly and returning an error in the STATUS parameter of XCALL RENAME. 

Note that this does not affect RENAME.LIT, nor does it affect the MX\_COPYFILE function, which can also be used to rename a file, but which offers an explicit option of whether to replace an existing file.

2007 November, A-Shell 5.0.997: