filecopy

Copy a file to a target location.

filecopy  FilePath, DirPath | NewFilePath

Example: filecopy "data\test.txt", "data\saved\"

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

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 filecopy statement copies the specified file FilePath to the target location, using any locations specified in the assignment file to locate files.

If DirPath is specified (that is, the path ends with a directory separator), the file FilePath is copied to the directory DirPath using the same file name.

If NewFilePath is specified, the specified file is copied to the directory name and file name supplied in NewFilePath.

If the specified file FilePath is located in a zip archive, it can be copied to different directory in the same archive, to another zip archive, or to a directory on the file system.

Specifying Parameters

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

Copying From and To Zip Files and Across Platforms

If the specified file FilePath is located in a ZIP archive, it can be copied to different directory in the same archive, to another ZIP archive, or to a directory on the file system.

When copying 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. For more information, see $TEXT_FILE_EXTENSIONS.

iSeries

On the iSeries, the particular ‘copy’ 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 CPY command is used
  • When the source has the IFS prefix, but the destination does not, then CPYFRMSTMF is used
  • When the destination has the IFS prefix, but the source does not, then CPYTOSTMF is used.

Copying a File to Another Directory

The following example copies the file test.txt from the directory sub1dir in the current directory to the directory sub2dir in sub1dir:

filecopy "sub1dir\test.txt", "sub1dir\sub2dir\"

or

filecopy "sub1dir/test.txt", "sub1dir/sub2dir/"

or

filecopy "[.sub1dir]test.txt", "[.sub1dir.sub2dir]"

Copying a File to the Same Directory Under Another Name

The following example copies the file test1.txt to test2.txt in the same directory:

filecopy "sub1dir\test1.txt", "sub1dir\test2.txt"

or

filecopy "[.sub1dir]test1.txt", "[.sub1dir]test2.txt"

Copying a File to Another Directory Under Another Name

The following example copies the file test1.txt in the current directory to the file test2.txt in sub3dir in the current directory:

filecopy "test1.txt", ".\sub3dir/test2.txt"
History
Version Change
9.1.01 Introduced

Related Topics