Rename the specified directory.

dirrename  DirPath,  NewDirName

Example: dirrename "data/exports", "saved"


Parameter Data Type Description
DirPath String Directory name, optionally preceded by the path to the directory, which can be in a zip archive.
NewDirName String New directory name, which can be in a zip archive. Must not end with a directory separator, and must not include the path to the directory.

Return Values

Values returned by $procerror
Value  Error constant Meaning


-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.


Allowed in all component types.


The dirrename statement renames the specified directory DirPath to NewDirName, taking file redirections in the assignment file into account.

  • 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 fails if DirPath:

  • Is not a directory
  • Does not exist
  • Is not empty
  • Is in use (locked)
  • Is the current directory or root
  • Does not permit user-renaming due to insufficient authorization level
  • Has invalid syntax

The operation also fails if NewDirName:

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

Use with $RES

When using dirrename with the resources deployment path ($RES), only use $RES with DirPath. Using $RES with NewDirName doesnot rename the existing directory and gives an error.

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


Renaming libraries is only possible for libraries that are not in use and not on somebody else's library list. Therefore, the ProcScript programmer must be prepared for a negative return value when renaming libraries. The same applies for files in libraries. IFS directories can be renamed in the same way as on Unix systems.

Using dirrename

The following ProcScript renames the directory drinks\coffee to drinks\tea:

dirrename "drinks\coffee\", "tea"


dirrename "[drinks.coffee]", "tea"

or, when used with $RES:

dirrename "$RES:drinks\coffee", "tea"

Related Topics