# vfs.copy

function

 Library: File system utilities (OMVFS) Import : omvfs.xmd

Declaration
export external function copy
value string source-path
on      value directory source-dir optional
to      value string target-path
in      value directory target-dir optional



Argument definitions

source-path
The file or directory to be copied.
target-path
The directory where the file or directory is to be copied to. If you are copying a file and you specify a destination file name the file will be given that name in the new location. If you do not specify a file name, the original file name will be used.
source-dir
A connected vfs.directory object. If this parameter is specified, the source-path is evaluated relative to the specified vfs.directory.
target-dir
A connected vfs.directory object. If this parameter is specified, the target-path is evaluated relative to the specified vfs.directory.

Purpose

You can use vfs.copy to copy a file or directory to a new location. vfs.copy will not overwrite a file or directory that already exists.

  import "omvfs.xmd" prefixed by vfs.

process
vfs.copy "../version1"
to "/oldversion"


There are two ways to use vfs.copy. The first is a straight copy and the second is copy and rename.

In straight copy mode, the source parameter names the file or directory to be copied and the target parameter names the destination to which that file or directory will be copied. That location must exist, and the specifed file or directory is created in that location using its existing name. Thus the following code copies the file test.txt from directory foo to directory bar, creating a copy of test.txt in that directory:

  import "omvfs.xmd" prefixed by vfs.

process
vfs.copy "c:\foo\test.txt"
to "c:\bar\"


In copy and rename mode, the source parameter names the file or directory to be moved and the target parameter names the destination to which that file or directory will be copied, and the new name it will be given at that destination. Thus the following code copies the file test.txt from directory foo to directory bar, creating a file named experiment.txt in that directory with the same contents as test.txt:

  import "omvfs.xmd" prefixed by vfs.

process
vfs.copy "c:\foo\test.txt"
to "c:\bar\experiment.txt"


### Troubleshooting

The difference between straight copy mode and copy and rename mode is determined by examining the target parameter. When copying files, the interpretation of this parameter is unambiguous. However, when copying directories, the distinction between straight copy and copy and rename can depend on the current state of the file system. Consider the following program:

  import "omvfs.xmd" prefixed by vfs.

process
vfs.copy "c:\temp\bar"
to "c:\foo\baz"


If the directory c:\foo\baz exists, the function operates in straight copy mode, creating a directory with the name bar inside the baz directory and copying the contents of c:\temp\bar into that directory. This creates a new directory named c:\foo\baz\bar.

However, if the directory c:\foo\baz does not exist, but the directory c:\foo does exist, the function operates in copy and rename mode, creating a directory named baz in c:\foo, and copying the contents of c:\temp\bar into that directory. This creates a new directory named c:\foo\baz.

This means that if the program above were executed three times in succession, and assuming that initially c:\foo exists and c:\foo\bar does not, it would have three different outcomes.

1. c:\foo\baz does not exist, so the function operates in copy and rename mode, creating c:\foo\baz.
2. c:\foo\baz now exists, so the function operates in straight copy mode, creating c:\foo\baz\bar.
3. c:\foo\baz exists, so the function operates in straight copy mode and attempts to create c:\foo\baz\bar. However, c:\foo\baz\bar already exists so an exception is thrown.

For this reason, you should check the status of the copy destination before using vfs.copy to copy directories.

### Exceptions

The following exceptions may occur:

• VFS001 The requested function is not supported for the type of connection
• VFS004 The specified name 'X' exceeds system length limits
• VFS100 The vfsDir object must be connected before it can be used
• VFS105 The path 'X' is not a valid absolute or relative path
• VFS111 The URL 'X' contains invalid encoding
• VFS300 Generic operating system error
• VFS306 The file 'X' does not exist
• VFS307 The path 'X' exists