filemove
Move the specified file to the target location.
filemove FilePath, DirPath | NewFilePath
Example: filemove ".\test1.txt", ".\saved\text.txt"
Parameters
| Parameter | Data Type | Description |
|---|---|---|
| FilePath | String | File name, optionally preceded by the path to the file. Must not end with a directory separator. |
| DirPath | String | Directory name, optionally preceded by the path to the directory. Must end with a directory separator |
| NewFilePath | String | New file name, optionally preceded by the path to the file. Must not end with a directory separator. |
Return Values
| 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 filemove statement moves the specified file FilePath to the target location, using any file redirections in the assignment file. You can move the file by specifying DirPath, or move and rename the file by specifying NewFilePath. The file to be moved can be located within a zip archive and moved to a different directory in the same archive, to a different zip archive, or to a local directory.
To rename a file without moving it, use filerename.
Specifying File and Directory 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 exampleab?, or in its suffix, for exampleabc\*.txt.
For more information, see Syntax of File and Directory Names.
Operation Failure
The operation fails if FilePath:
- Is not a file
- Does not exist
- Has invalid syntax
The operation also fails if the directory part of DirPath or NewFilePath:
- Does not already exist
- Does not permit user-writing due to insufficient authorization level
- Has invalid syntax
The operation also fails if the file NewFilePath:
- Already exists
- Has invalid syntax
Moving From and To Zip Files and Across Platforms
If the specified file FilePath is located in a ZIP archive, it can be moved to different directory in the same archive, to another ZIP archive, or to a directory on the file system.
When moving files to or from zip archives, or across operating systems or media, Uniface handles text files differently than binary files. It copies binary files as-is, but it automatically adjusts text file attributes so that EOL characters and optional character set conversions match the platform. This may result in changes in the file size, making it appear that source and target files are not the same.
You can define the files to be treated as text files, or switch off automatic cross-platform text file handling using the $TEXT_FILE_EXTENSIONS assignment setting.
iSeries
On the iSeries, the particular ‘move’ command that is used depends on the following circumstances:
- When both the source and the destination use the IFS prefix, or when both do not use the IFS prefix, the MOVE command is used
- When the source has the IFS prefix, but the destination does not, then CPYFRMSTMF is used. If the copy finishes successfully, the source file is deleted; if the delete fails (for example, due to lack of authorization), the copy is undone, and $procerror -13 is returned. The file (indicated by its extension), into which the member is to be moved, must already exist; filemove does not implicitly create files.
- When the destination has the IFS prefix, but the source does not, then CPYTOSTMF is used.
Moving a File to Another Directory
The following example moves the file test.txt, from the directory sub1dir in the current directory, to the directory sub2dir in sub1dir:
filemove "sub1dir\test.txt", "sub1dir\sub2dir\"
or
filemove "[.sub1dir]test.txt", "[.sub1dir.sub2dir]"
Note that it is the presence of the directory separator at the end of the second argument that determines that this is only a move to another directory, not a move combined with a file rename.
Moving and Renaming a File
The following example moves the file test1.txt from the current directory to the directory sub2dir, renaming the file to text.txt:
filemove ".\test1.txt", ".\sub2dir\text.txt"
Note that it is the absence of a directory separator at the end of the second argument that determines that this is a move to another directory, combined with a file rename.
| Version | Change |
|---|---|
| 9.1.01 | Introduced |
