swirl
Guide to OmniMark 9   OmniMark home
docs home 
IndexConceptsTasksSyntaxLibrariesLegacy LibrariesErrors
 
  Related Topics   Other Library Functions  
function  

vfs.copy

 
 

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:

    Related Topics
 
Other Library Functions
 
 

Top [ INDEX ] [ CONCEPTS ] [ TASKS ] [ SYNTAX ] [ LIBRARIES ] [ LEGACY LIBRARIES ] [ ERRORS ]

OmniMark 9.1.0 Documentation Generated: September 2, 2010 at 1:38:10 pm
If you have any comments about this section of the documentation, please use this form.

Copyright © Stilo International plc, 1988-2010.