Syntax

rename [<drive>:][<path>]<file name 1> <file name 2>

or

ren [<drive>:][<path>]<file name 1> <file name 2>

Meaning

Change the name of a file (file 1) or of several files at once, into file name 2. You have to use existing drives and paths (relative, local or UNC paths). File name 2 cannot be preceded by a path. This function can only be used in ADAPL as the parameter in a SYSTEM command. File names containing spaces should be enclosed in double quotes, and backslashes or forward slashes in the path should not be escaped (so keep them as they are).

Parameters between [ and ] are optional, and parameters between < and > must be replaced by an actual value. Do not include any of these brackets in your command.

Besides its intended use, RENAME can be used as a work-around to check if a file is present somewhere, without having to try to open the file. You can do that by renaming the file to the name it already has, so effectively the file remains unchanged but the result code from SYSTEM will tell you indirectly if the file exists. If the result is 0 the "renaming" was succesful, so the file most probably exists (unless it is opened for editing somewhere), and if the result is anything other than 0, the file most probably doesn't exist.
Note that you cannot use text variables or tags as arguments for RENAME, but you can use a text variable as the argument for SYSTEM. So if you want to use variable file names (maybe coming from a field in a record), you'll have to build up the entire SYSTEM argument string in a variable and pass the variable to SYSTEM, for example:

argumentstringvar = 'rename "' + pathplusfilename1var + ~
'" "' + filename2var + '"'
resultvar = system(argumentstringvar)

Example 1

stat = SYSTEM('rename "my test.txt" fail.txt')

Example 2

RENAME can be used as a work-around to check if a file is present somewhere, without having to try to open the file. A partial code sample is the following:

* Find the last backslash in the path taken from a field
slashpositionfromback = rinstr$(len(pathplusfilenamefield[i]), pathplusfilenamefield[i] , '\')
 
* Calculate the position of that backslash from the left
slashposition = len(pathplusfilenamefield[i]) - ~
               slashpositionfromback
 
* Extract the file name from the full path
filename = right$(pathplusfilenamefield[i], slashposition)
 
* Put the entire SYSTEM argument string together for
* renaming the file to itself
fileteststring = 'rename "' + pathplusfilenamefield[i] + ~
                '" "' + filename + '"'
 
* Execute the SYSTEM command with the argument string
filetest = system(fileteststring)
 
* If not successful, the file probably doesn't exist.
* Show error message.
if (filetest) {
  errorm 'The file ' + escape(pathplusfilenamefield[i]) + ~
         ' doesn''t exist yet.'
}