Skip to content

Native File Copy {R}←X ⎕NCOPY Y

This function copies native files and directories from one or more sources specified by Y to a destination specified by X. ⎕NCOPY is similar to ⎕NMOVE (see Native File Move).

X is a character vector that specifies the name of the destination.

Y is a character vector that specifies the name of the source, or a vector of character vectors containing zero or more sources.

Source and destination path names can be full or relative (to the current working directory) path names which adhere to the operating system conventions.

If X specifies an existent directory, then each source in Y is copied into that directory, otherwise X specifies the name of the copy. X must specify an existent directory if the source contains multiple names or if the Wildcard option is set.

The shy result R contains count(s) of top-level items copied. If Y is a single source name, R is a scalar otherwise it is a vector of the same length as Y.

Examples

There are a number of possibilities which are illustrated below. In all cases, if the source is a file, a copy of the file is created. If the source is a directory, a copy of the directory and all its contents is created.

The source name must be an existent file or directory. If the destination name does not exist but its path name does exist, the source is copied to the destination name. If the destination name is an existing directory the copy is created within that directory with the base name of the source. 

       ⊃1 ⎕NPARTS ''
i:/Documents/Dyalog APL-64 17.0 Unicode Files/

⍝ Make a named back-up of the Session file
      ⊢'session.bak' ⎕NCOPY 'default.dlf'
1
      ⊢ ⎕MKDIR 'backups' ⍝ Make a backups directory
1
 ⍝ Copy the Session file to backups directory
      ⊢'backups'⎕NCOPY'default.dlf'
1
      ↑⊃0 (⎕NINFO⍠1) 'backups\*'
backups/default.dlf

Each source name must specify a single file or directory which must exist. The destination name must be an existing directory. Copies of each of the files and/or directories specified by the source base names are made in the destination directory. 

       ⊃1 ⎕NPARTS ''
i:/Documents/Dyalog APL-64 17.0 Unicode Files/

      ⊢ ⎕MKDIR 'backups' ⍝ Make a backups directory
1
⍝ Copy 2 files to backups directory
      ⊢'backups'⎕NCOPY'default.dlf' 'def_uk.dse'
1 1
      ↑⊃0 (⎕NINFO⍠1) 'backups\*'
backups/default.dlf
backups/def_uk.dse

Variant Options

⎕NCOPY supports four variant options, specified using the variant operator ⍠, summarised in Table 1, and described in detail beneath it. The principal option is Wildcard.

Table 1: Variant options for ⎕NCOPY
Variant Option Valid Values Default Effect
Wildcard
principal		 0 or 1 0 Whether the names in Y are matched literally or as patterns.
IfExists 'Error', 'Skip', 'Replace', or 'ReplaceIfNewer' 'Error' What happens when a target file already exists.
PreserveAttributes 0 or 1 0 Whether file attributes are preserved.
ProgressCallback the name of a callback function none Reports progress during the copy.

Variant Option: Wildcard

0 (default) The name or names in Y identifies a specific file name.
1 The name or names in Y that specify the base name and extension (see NParts ), can also contain the wildcard characters "?" and "*". An asterisk is a substitute for any 0 or more characters in a file name or extension; a question-mark is a substitute for any single character.

When Wildcard is 1, element(s) of R can be 0, 1, or >1. If Wildcard is 0, elements of R are always 1.

Examples

The source name can include wildcard characters that match a number of existing files and/or directories. The destination name must be an existing directory. The files and/or directories that match the pattern specified by the source name are copied into the destination directory. If there are no matches, zero copies are made. 

       ⊃1 ⎕NPARTS ''
i:/Documents/Dyalog APL-64 17.0 Unicode Files/

      ⊢ ⎕MKDIR 'backups' ⍝ Make a backups directory
1
⍝ Copy all files to backups directory
      ⊢'backups'(⎕NCOPY⍠'Wildcard' 1)'*.*'
3

      ↑⊃0 (⎕NINFO⍠1) 'backups\*'
backups/default.dlf        
backups/def_uk.dse         
backups/UserCommand20.cache

The destination name must be an existing directory. Copies of each of the files and/or directories that match the patterns specified by the source names (if any) are made in the destination directory. 

      ⊃1 ⎕NPARTS ''
i:/Documents/Dyalog APL-64 17.0 Unicode Files/

      ⊢ ⎕MKDIR 'backups' ⍝ Make a backups directory
1
⍝ Copy files to backups directory
      ⊢'backups'(⎕NCOPY⍠1)'d*' 'UserCommand20.cache'
2 1
      ↑⊃0 (⎕NINFO⍠1) 'backups\*'
backups/default.dlf
backups/def_uk.dse
backups/UserCommand20.cache

Variant Option: IfExists

The IfExists variant option determines what happens when a source file is to be copied to a target file that already exists. It does not apply to directories, only to the files within them.

Value Description
'Error' (default) Existing files will not be overwritten and an error will be signalled.
'Skip' Existing files will not be overwritten but the corresponding copy operation will be skipped (ignored).
'Replace' Existing files will be overwritten.
'ReplaceIfNewer' Existing files can be overwritten if, and only if, the corresponding source file is newer (more recently modified) than the existing one, otherwise it is skipped.

The following cases cause an error to be signalled regardless of the value of the IfExists variant.

  • If the source specifies a directory and the destination specifies an existing file.
  • If the source specifies a file and the same base name exists as a sub-directory in the destination.

Variant Option: PreserveAttributes

The PreserveAttributes variant option (a Boolean) determines whether file attributes are preserved. It does not apply to directories, only to files.

0 (default) file attributes are not preserved.
1 where possible, copied files will be given at least the same modification time as the source. Other file attributes will be preserved as permitted by the operating system and file system.

When files are copied across file systems, the different file systems might have different timestamp granularity therefore the timestamps might not be exactly the same.

Variant Option: ProgressCallback

The ProgressCallback variant option is described in the Dyalog Programming Reference Guide. The following is specific to ⎕NCOPY:

  • The first element of the right argument to the callback function is the character vector '⎕NCOPY'.

Notes

  • The special directories . and .. can never be copied into an existing directory.
  • If any source name is a symbolic link it is dereferenced; that is, the source or directory it references is copied rather than the link itself.
  • In the result R, a directory together with all its contents is counted once. A directory might be partially copied if the IfExists option is set to 'Replace' or 'ReplaceIfNewer').
  • If an error occurs during the copy process, then processing will immediately stop and an error will be signalled. The operation is not atomic; some items might be copied before this happens. In the event of an error there will be no result and therefore no indication of how many names were copied before the error occurred.
⎕NCOPY NCOPY