COPY

The last new command in the configuration script is COPY, which is used to copy files. Here is the user documentation.

COPY

COPY can copy one or more input files to one or more output files, or concatenate multiple input files into a single output file.

Format

COPY input-filespec{,...} output-filespec

Parameters

input-filespec{,...}
Specifies the name of an existing file to copy. Wildcards may be specified and multiple file specifications can be specified, delimited by commas (,) or plus signs (+). Any filename containing a comma or plus must be enclosed in quotes. If no device or directory is specified, COPY uses the current default device and directory.

output-filespec
Specifies the name of the output file into which the input is copied. If no device or directory is specified, COPY uses the current default device and directory. COPY replaces any other missing fields (file name, file type, version number) with the corresponding field of the input filespec.
Wildcards can be used, which will be subsituted from the current input file.

Description

If a single input file is specified, that file is copied to the specified destination. If multiple input files are specified, the operation depends upon the output specification. If the output specification contains any wildcards, each input file is copied to the output specification with the wildcard fields substituted from the input file. If the output specification doesn't include any wildcards, the input files are concatenated into the specified output file. Note that missing output fields are treated as "*" wildcards.
If the output file contains a wildcard or the name or extension isn't explicitly specified, the output file will have the same creation date. Otherwise, the output file will be treated as a new file and given the current creation date. In all cases, the Last Modified date is set to the current date, and the Last Backup, Last Access, and Expiration dates are cleared.
The default protection is that of the existing output file. If no output file exists, the current default protection is applied. However, ACLs on the target directory may affect the availability of the new file(s).
The owner of the output file(s) will be the user copying the file(s). However, if the user has SYSPRV or BYPASS privilege, the output file(s) will have the same owner as any previous version of the file or - if there are no previous version - the file is assigned the same owner as the parent directory.
If a directory is copied, an empty output directory is created - the files in the directory are not copied.
Priveleges assigned to a file are limited to the user's current privileges unless the user has the SETPRV privilege.
ACLs on input files are not copied, but all other meta data for the file is copied, except as described above. In the case of conflicting meta data during a concatenation operation, the first instance of meta data from the input files takes precedence.

Switches

/ALLOCATION{=size}
Specifies initial size of each output file, in bytes. If not specified, or the size is null, the initial size comes from the input file size. In a concatenation operation, the output file size is taken from the first input file, if the switch isn't specified.

/BACKUP
Indicates that the /SINCE or /BEFORE switch is to use the file's backup time. This switch is incompatible with the /CREATED, /EXPIRED, and /MODIFIED switches. If none of these are specified, the default is /CREATED.

/BEFORE{=time}
Selects only those files dated prior to the specified time. The time can be an absolute time, a combination of absolute and delta times, or one of the following keywords: BOOT, LOGIN, TODAY (the default), TOMORROW, or YESTERDAY. One of the following can be used with /BEFORE to indicate the time attribute to be used as the basis for selection: /BACKUP, /CREATED (the default), /EXPIRED, or /MODIFIED.

/BLOCK_SIZE=n
Overrides the default block size (128) for RMS blocked files.

/BY_OWNER{=user}
Selects only those files whose owner is the specified user. This may be the user name or the user identification code (UIC). A numeric value is checked against valid user names first and, if not found, is considered to be a UIC.

/CONCATENATE (default)
/NOCONCATENATE
Creates one output file from multiple input files when no wildcard characters are used in the output file specification. The /NOCONCATENATE switch generates multiple output files. A wildcard character in an input file specification results in a single output file consisting of the concatenation of all input files matching the file specification. Input files matching the wildcard specification are concatenated in random order. If /CONCATENATE is used with an output file specification that has no wildcards, the output files are assigned different version numbers.

/CONFIRM
/NOCONFIRM (default)
Controls whether the user is queried before each copy operation to confirm that the operation should be performed on that file. The following responses are valid:

Affirm	Decline	Other
YES	NO	QUIT
TRUE	FALSE	Ctrl/Z
1	0	ALL

Any combination of uppercase and lowercase letters can be used for word responses. The responses can be abbreviated to one or more letters (for example, T, TR, or TRU for TRUE), Entering "QUIT" or pressing Ctrl/Z stops the copy operation at that point. A response of "ALL" causes COPY to continue with no further prompting. If the response is null (such as by simply pressing the ENTER key), it is considered the same as typing "NO". Any other response results in an error message being displayed and the user is prompted again.

/CONTIGUOUS
/NOCONTIGUOUS
Specifies that the output file must occupy contiguous physical disk clusters. By default, COPY creates a contiguous output file only if the input file is contiguous. Also, by default, if not enough space exists for a contiguous allocation, the output file will not be contiguous and COPY does not report an error. During concatenation, if some input files are contiguous and some are not, the output file may or may not be contiguous. /CONTIGUOUS can be used to ensure that the output files are contiguous.
The /CONTIGUOUS switch has no effect when files are copied to sequential devices (such as tapes) because sequential devices are already inherently contiguous. The switch also has no effect when copying files from a serial device since the size of the file cannot be determined until after it is copied to the disk. In this case, the file must first be copied to the disk and then copied in-place on the disk with the /CONTIGUOUS switch.

/CREATED (default)
Indicates which file timestamp to use in conjunction with /BEFORE or /SINCE. /CREATED selects files based on their dates of creation. This is incompatible with /BACKUP, /EXPIRED, and /MODIFIED, which also allow for selecting files according to time attributes. If none of switches are used, the default is /CREATED.

/EXCLUDE=(filespec{,...})
Excludes the specified files from the copy operation. Device specifications in the file specifications are ignored. Wildcard characters are allowed in the file specification; however, you cannot use relative version numbers to exclude a specific version. If only one file is specified, the parentheses can be omitted.

/EXPIRED
Indicates that the expiration date is used with the /BEFORE or /SINCE switches. /EXPIRED is incompatible with /BACKUP, /CREATED, and /MODIFIED. If none of these is specified, the default is /CREATED.

/EXTENSION=n
Specifies the number of clusters to be added to the output file each time the file is extended. If /EXTENSION is not specified, the extension attribute of the corresponding input file determines the default extension attribute of the output file. If the input file has no extension attribute, the default clustersize of the output device is used.

/LOG
/NOLOG (default)
Controls whether COPY displays the file specifications of each file copied. When /LOG is used, COPY displays the following for each file copied:

• The file specifications of the input and output files.
• The number of blocks or records copied.
• The total number of new files created.

/MODIFIED
Indicates that the modification timestamp is to be used with /BEFORE or /SINCE. This is incompatible with /BACKUP, /CREATED, and /EXPIRED, which also allow the selection of files according to time attributes. If none of these are specified the default is /CREATED.

/OVERLAY
/NOOVERLAY (default)
Indicates that data in the input file is to be copied into the existing output file, overlaying the existing data, rather than allocating new space for the file. The physical location of the file on disk does not change; however, for RMS indexed and relative files, if the output file has fewer blocks allocated than the input file, the copy fails giving an RMS-E-EOF error. /OVERLAY is ignored if the output file is written to a non-filestructured store.

/PROTECTION=(ownership{:access}{,...})
Specifies protection for the output file. The ownership parameter is: system (S), owner (O), group (G), or world (W). The access parameter is: read (R), write (W), execute (E), or delete (D). The default protection, including any protection attributes not specified, is that of the existing output file. If no output file exists, the current default protection applies.

/READ_CHECK
/NOREAD_CHECK (default)
Instructs copy to verify the read operation by performing multiple read operations. This does not apply to serial devices

/REPLACE
/NOREPLACE (default)
If a file exists with the same file specification (including version number) as that entered for the output file, the existing file is to be deleted if /REPLACE is specified. By default, COPY creates a new version of a file if a file with that specification exists, incrementing the version number. /NOREPLACE signals an error when a conflict in version numbers occurs.

/SINCE{=time}
Selects only those files dated on or after the specified time. The time can be specified as absolute time, a combination of absolute and delta times, or as one of the following keywords: BOOT, JOB_LOGIN, LOGIN, TODAY (default), TOMORROW, or YESTERDAY. /SINCE indicates the time attribute to be used as the basis for selection in conjunction with /BACKUP, /CREATED (default), /EXPIRED, or /MODIFIED.

/STYLE=keyword
Specifies the file name format for display purposes. The valid keywords for this switch are CONDENSED and EXPANDED. Descriptions are as follows:

Keyword	Explanation
CONDENSED (default)	Displays the file name representation of what is generated to fit into a 255-length character string.
EXPANDED	Displays the file name representation of what is stored on disk.

The keywords CONDENSED and EXPANDED are mutually exclusive. This specifies which file name format is displayed in the output message, along with the confirmation if requested.

/SYMLINK
/NOSYMLINK (default)
/NOSYMLINK indicates that if an input file is a symbolic link, the file to which the symbolic link refers is the file that is copied. Otherwise, the link itself is copied.

/TRUNCATE (default)
/NOTRUNCATE
Controls whether the COPY operation truncates an output file at the end-of-file (EOF) when copying it. When copying an RMS file, this operation can only be used with sequential files. By default, the actual size of the input file determines the size of the output file. If /NOTRUNCATE is used, the allocation of the input file determines the size of the output file. Note that any data following the EOF may or may not be copied to the output file.

/VERSION
/NOVERSION (default)
Indicates whether or not filenames with trailing semicolons and numbers should be treated as having version numbers. /NOVERSION indicates that any version numbers should be ignored and simply treated as part of the filename.

/WRITE_CHECK
/NOWRITE_CHECK (default)
Reads the output file data after it is written to verify that the data copied successfully. This only needs to be used for copy operations to devices that do not have inherent data integrity protection. It does not apply to serial devices.

Examples

COPY MYFILE.TXT COPY.TXT

Copies the file named MYFILE.TXT from the current device/directory to a new file named COPY.TXT in the same device/directory.

COPY *.EXE temp\*.EXEBACKUP

Copies all files with the extension .EXE from the current device/directory to new files with the same name, but the .EXEBACKUP extension in the temp folder in the current device/directory.

COPY FILE1.TXT+FILE2.TXT+FILE3.TXT FILES.TXT

Copies the contents of FILE1.TXT into FILES.TXT, then the contents of FILE2.TXT into FILES.TXT at the end, then the contents of FILE3.TXT into FILES.TXT at the end. When compete, FILES.TXT will contain the contents of all three input files.

COPY MYAPP.EXE MYAPP.EXE/CONTIGUOUS

Copies MYAPP.EXE over itself, making it contiguous.

Note: There is an /FTP switch (and related switches) that VMS allows with COPY. We will cover that operation in the future. Also, /VERSION and /NOVERSION do not exist on VMS. We add it in UOS, and default to /NOVERSION, for two reasons. First, most users in the world aren't familiar with the concept of file versioning and it might be a bit confusing to them. Second, whereas the VMS file system is optimized for file versioning, the UOS native file system is not. The UOS native file system is more general-purpose. As a consequence, handling file versions is a little slower. For the sake of VMS compatibility, we will handle file versions if the user wishes, but we won't force it on people for the aforementioned reasons.

As you can see, the COPY operation has a lot features and isn't quite as simple as just opening an input file, creating the output file, and then copying the data.

In the next article, we will start to look at the code to implement the COPY CUSP.