Please enable JavaScript to view this site.

A-Shell Reference

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 AMOS or native operating system filenames, and also support the use of embedded environment variables (e.g. %MIAME%).

Parameters

oldname  (String)  [in]

current file name

newname  (String)  [in]

name to which the file is being changed

status  (F,6)  [out]

0 if successful, other if not

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:  errors are now 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.

2006 June, A-Shell 5.0.958:  Function now properly handles the renaming of files without extensions and does not append .DAT to the new file name.