filerename

Rename a file in the same directory.

filerename  FilePath, NewFileName

Example: filerename "sub1dir/test.txt", "tested.txt"

Parameters

Parameters
Parameter Data Type Description
FilePath String File name, optionally preceded by the path to the file. Must not end with a directory separator.
NewFileName String New file name. Must not end with a directory separator and must not include the path to the file.

Return Values

Values returned by $procerror
Value  Error constant Meaning
0

 

 Successful
-13 <UIOSERR_OS_COMMAND> An error occurred while trying to perform the OS command. Set /pri=64 to display the exact error in the message frame.

Use

Allowed in all component types.

Description

The filerename statement renames the file specified by FilePath to NewFileName within the same directory, using any file redirections in the assignment file to locate the file. The file can be renamed in a ZIP archive.

Specifying File Names

  • Each specification can be a string, a field (or indirect reference to a field), a variable, or a function that evaluates to a string.
  • The total length of any path (or file name or directory name) must not exceed 255 bytes.
  • Valid generic directory separators are the backward slash (\), the forward slash (/) , and the period (.) in combination with square brackets ([a.b]). These are translated to the platform-specific separators.
  • No wildcards are allowed in any path, except for $ldirlist and $dirlist, which allows the Uniface wildcards ? (GOLD ?) and * (GOLD *) in the directory name, for example ab?, or in its suffix, for example abc\*.txt.

For more information, see Syntax of File and Directory Names.

Operation Failure

The operation filerename fails if FilePath:

  • Is not a file
  • Does not exist
  • Is in use (locked)
  • Does not permit user-renaming due to insufficient authorization level
  • Has invalid syntax

The operation also fails if the file NewFileName:

  • Already exists
  • Has invalid syntax
  • Specifies the $RES path

Use with $RES

When using filerename with the resources deployment path ($RES), only use $RES with FilePath. Using $RES with NewFileName will not rename the existing file and gives an error.

For more information about using $RES, see Resources Deployment Path ($RES) .

iSeries

On the iSeries, when you attempt to rename a file (that does not reside in the IFS) such that its extension is changed, this implies a move of a member to a different file. For example, the command filerename lib/aaa.ext1, bbb.ext2 will move member aaa from file ext1 to file ext2 and rename the member to bbb. This works only if file ext2 already exists and the process has appropriate access rights, because the statement filerename does not implicitly create files.

Renaming a File in the Same Directory

The following example renames the file test.txt in the directory sub1dir in the current directory to tested.txt:

filerename "sub1dir/test.txt", "tested.txt"

or:

filerename "[.sub1dir]test.txt;5", "tested.txt"

or, when used with $RES:

dirrename "$RES:sub1dir/test.txt", "tested.txt"
History
Version Change
9.1.01 Introduced

Related Topics