[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

HP OpenVMS DCL Dictionary

COPY

Creates a new file from one or more existing files. The COPY command can do the following:

Copy an input file to an output file.
Concatenate two or more input files into a single output file.
Copy a group of input files to a group of output files.

Format

COPY input-filespec[,...] output-filespec

Parameters

input-filespec[,...]
Specifies the name of an existing file to be copied. The asterisk (*) and the percent sign (%) wildcard characters are allowed. If you do not specify the device or directory, the COPY command uses your current default device and directory. If you specify more than one file, separate the file specifications with either commas (,) or plus signs (+).
output-filespec
Specifies the name of the output file into which the input is copied.
You must specify at least one field in the output file specification. If you do not specify the device or directory, the COPY command uses your current default device and directory. The COPY command replaces any other missing fields (file name, file type, version number) with the corresponding field of the input file specification. If you specify more than one input file, the COPY command generally uses the fields from the first input file to determine any missing fields in the output file.
You can use the asterisk (*) wildcard character in place of any two of the following: the file name, the file type, or the version number. The COPY command uses the corresponding field in the related input file to name the output file.

Description

The COPY command creates a new file from one or more existing files. If you do not specify the device or directory, the COPY command uses your current default device and directory. The COPY command can do the following:

Copy an input file to an output file.
Concatenate two or more input files into a single output file.
Copy a group of input files to a group of output files.

The COPY command, by default, creates a single output file. When you specify more than one input file, the first input file is copied to the output file, and each subsequent input file is appended to the end of the output file. If a field of the output file specification is missing or contains an asterisk (*) wildcard character, the COPY command uses the corresponding field from the first, or only, input file to name the output file.
If you specify multiple input files with maximum record lengths, the COPY command gives the output file the maximum record length of the first input file. If the COPY command encounters a record in a subsequent input file that is longer than the maximum record length of the output file, it issues a message noting the incompatible file attributes and begins copying the next file.
To create multiple output files, specify multiple input files and use at least one of the following:

An asterisk (*) wildcard character in the output directory specification, file name, file type, or version number field
Only a node name, a device name, or a directory specification as the output file specification
The /NOCONCATENATE qualifier

When the COPY command creates multiple output files, it uses the corresponding field from each input file in the output file name. You also can use the asterisk (*) wildcard character in the output file specification to have COPY create more than one output file. For example:
$ COPY A.A;1, B.B;1 *.C
This COPY command creates the files A.C;1 and B.C;1 in the current default directory. When you specify multiple input and output files you can use the /LOG qualifier to verify that the files were copied as you intended.
Note that there are special considerations for using the COPY command with DECwindows compound documents. For more information, see the Guide to OpenVMS File Applications.
Version Numbers

If you do not specify version numbers for input and output files, the COPY command (by default) assigns a version number to the output files that is either of the following:

The version number of the input file
A version number one greater than the highest version number of an existing file with the same file name and file type

When you specify the output file version number by an asterisk (*) wildcard character, the COPY command uses the version numbers of the associated input files as the version numbers of the output files.
If you specify the output file version number by an explicit version number, the COPY command uses that number for the output file specification. If a higher version of the output file exists, the COPY command issues a warning message and copies the file. If an equal version of the output file exists, the COPY command issues a message and does not copy the input file.
File Protection and Creation/Revision Dates

The COPY command considers an output file to be new when you specify any portion of the output file name explicitly. The COPY command sets the creation date for a new file to the current time and date.
If you specify the output file by one or more asterisk (*) and percent sign (%) wildcard characters, the COPY command uses the creation date of the input file.
The COPY command always sets the revision date of the output file to the current time and date; it sets the backup date to zero. The file system assigns the output file a new expiration date. (The file system sets expiration dates if retention is enabled; otherwise, it sets expiration dates to zero.)
The protection and access control list (ACL) of the output file is determined by the following parameters, in the following order:

Protection of previously existing versions of the output file
Default Protection and ACL of the output directory
Process default file protection

(Note that the BACKUP command takes the creation and revision dates as well as the file protection from the input file.)
Use the /PROTECTION qualifier to change the output file protection.
Normally, the owner of the output file will be the same as the creator of the output file; however, if a user with extended privileges creates the output file, the owner will be the owner of the parent directory or of a previous version of the output file if one exists.
Extended privileges include any of the following:

SYSPRV (system privilege) or BYPASS
System user identification code (UIC)
GRPPRV (group privilege) if the owner of the parent directory (or previous version of the output file) is in the same group as the creator of the new output file
An identifier (with the resource attribute) representing the owner of the parent directory (or the previous version of the output file)

Copying Directory Files

If you copy a file that is a directory, the COPY command creates a new empty directory of the named directory. The COPY command does not copy any files from the named directory to the new directory. See the examples section for examples of copying directory files.

Qualifiers

/ALLOCATION=number-of-blocks
Forces the initial allocation of the output file to the specified number of 512-byte blocks. If you do not specify the /ALLOCATION qualifier, or if you specify it without the number-of-blocks parameter, the initial allocation of the output file is determined by the size of the input file being copied.
/BACKUP
Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The /BACKUP qualifier selects files according to the dates of their most recent backups. This qualifier is incompatible with the /CREATED, /EXPIRED, and /MODIFIED qualifiers, which also allow you to select files according to time attributes. If you specify none of these four time qualifiers, the default is the /CREATED qualifier.
/BEFORE[=time]
Selects only those files dated prior to the specified time. You can specify time as absolute time, as a combination of absolute and delta times, or as one of the following keywords: BOOT, LOGIN, TODAY (default), TOMORROW, or YESTERDAY. Specify one of the following qualifiers with the /BEFORE qualifier to indicate the time attribute to be used as the basis for selection: /BACKUP, /CREATED (default), /EXPIRED, or /MODIFIED.
For complete information on specifying time values, see the OpenVMS User's Manual or the online help topic Date.
/BLOCK_SIZE=n
Overrides the default block size (124) used by COPY. You can specify a value in the range of 1 through 2**31-1.
/BY_OWNER[=uic]
Selects only those files whose owner user identification code (UIC) matches the specified owner UIC. The default UIC is that of the current process.
Specify the UIC by using standard UIC format as described in the HP OpenVMS Guide to System Security.
/CONCATENATE (default)

/NOCONCATENATE
Creates one output file from multiple input files when you do not use the asterisk (*) or percent sign (%) wildcard characters in the output file specification. The /NOCONCATENATE qualifier 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.
Files from Files-11 On-Disk Structure Level 2 and 5 disks are concatenated in alphanumeric order. If you specify an asterisk (*) or percent sign (%) wildcard character in the file version field, files are copied in descending order by version number. Files from Files-11 On-Disk Structure Level 1 disks are concatenated in random order.
/CONFIRM

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

YES NO QUIT

TRUE FALSE Ctrl/Z

1 0 ALL

[Return]

You can use any combination of uppercase and lowercase letters for word responses. You can abbreviate word responses to one or more letters (for example, T, TR, or TRU for TRUE), but these abbreviations must be unique. Affirmative answers are YES, TRUE, and 1. Negative answers include: NO, FALSE, 0, and pressing Return. Entering QUIT or pressing Ctrl/Z indicates that you want to stop processing the command at that point. When you respond by entering ALL, the command continues to process but no further prompts are given. If you type a response other than one of those in the list, DCL issues an error message and redisplays the prompt.
/CONTIGUOUS

/NOCONTIGUOUS
Specifies that the output file must occupy contiguous physical disk blocks. By default, the COPY command creates an output file in the same format as the corresponding input file. Also, by default, if not enough space exists for a contiguous allocation, the COPY command does not report an error. If you copy multiple input files of different formats, the output file may or may not be contiguous. You can use the /CONTIGUOUS qualifier to ensure that files are copied contiguously.
The /CONTIGUOUS qualifier has no effect when you copy files to or from tapes because the size of the file on tape cannot be determined until after it is copied to the disk. If you copy a file from a tape and want the file to be contiguous, use the COPY command twice: once to copy the file from the tape, and a second time to create a contiguous file.
/CREATED (default)
Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The /CREATED qualifier selects files based on their dates of creation. This qualifier is incompatible with the /BACKUP, /EXPIRED, and /MODIFIED qualifiers, which also allow you to select files according to time attributes. If you specify none of these four time qualifiers, the default is the /CREATED qualifier.
/EXCLUDE=(filespec[,...])
Excludes the specified files from the copy operation. You can include a directory but not a device in the file specification. The asterisk (*) and the percent sign (%) wildcard characters are allowed in the file specification; however, you cannot use relative version numbers to exclude a specific version. If you specify only one file, you can omit the parentheses.
/EXPIRED
Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The /EXPIRED qualifier selects files according to their expiration dates. (The expiration date is set with the SET FILE/EXPIRATION_DATE command.) The /EXPIRED qualifier is incompatible with the /BACKUP, /CREATED, and /MODIFIED qualifiers, which also allow you to select files according to time attributes. If you specify none of these four time qualifiers, the default is the /CREATED qualifier.
/EXTENSION=n
Specifies the number of blocks to be added to the output file each time the file is extended. If you do not specify the /EXTENSION qualifier, the extension attribute of the corresponding input file determines the default extension attribute of the output file.
/LOG

/NOLOG (default)
Controls whether the COPY command displays the file specifications of each file copied.
When you use the /LOG qualifier, the COPY command displays the following for each copy operation:

The file specifications of the input and output files
The number of blocks or the number of records copied (depending on whether the file is copied on a block-by-block or record-by-record basis)
The total number of new files created

/MODIFIED
Modifies the time value specified with the /BEFORE or the /SINCE qualifier. The /MODIFIED qualifier selects files according to the dates on which they were last modified. This qualifier is incompatible with the /BACKUP, /CREATED, and /EXPIRED qualifiers, which also allow you to select files according to time attributes. If you specify none of these four time modifiers, the default is the /CREATED qualifier.
/OVERLAY

/NOOVERLAY (default)
Requests that data in the input file be copied into the existing specified 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.
The /OVERLAY qualifier is ignored if the output file is written to a non-file-structured device.
/PROTECTION=(ownership[:access][,...])
Specifies protection for the output file.

Specify the ownership parameter as system (S), owner (O), group (G), or world (W).
Specify the access parameter as 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.
For more information on specifying protection codes, see the HP OpenVMS Guide to System Security.
/READ_CHECK

/NOREAD_CHECK (default)
Reads each record in the input files twice to verify that it has been read correctly.
/REPLACE

/NOREPLACE (default)
Requests that, if a file exists with the same file specification as that entered for the output file, the existing file is to be deleted. The COPY command allocates new space for the output file. In general, when you use the /REPLACE qualifier, include version numbers with the file specifications. By default, the COPY command creates a new version of a file if a file with that specification exists, incrementing the version number. The /NOREPLACE qualifier signals an error when a conflict in version numbers occurs.
/SINCE[=time]
Selects only those files dated on or after the specified time. You can specify time as absolute time, as combination of absolute and delta times, or as one of the following keywords: BOOT, JOB_LOGIN, LOGIN, TODAY (default), TOMORROW, or YESTERDAY. Specify one of the following qualifiers with the /SINCE qualifier to indicate the time attribute to be used as the basis for selection: /BACKUP, /CREATED (default), /EXPIRED, or /MODIFIED.
For complete information about specifying time values, see the OpenVMS User's Manual or the online help topic Date.
/STYLE=keyword
Specifies the file name format for display purposes.
The valid keywords for this qualifier 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. This file name may contain a DID or FID abbreviation in the file specification.

EXPANDED Displays the file name representation of what is stored on disk. This file name does not contain any DID or FID abbreviations.

The keywords CONDENSED and EXPANDED are mutually exclusive. This qualifier specifies which file name format is displayed in the output message, along with the confirmation if requested.
File errors are displayed with the CONDENSED file specification unless the EXPANDED keyword is specified.
See the OpenVMS User's Manual for more information.
/SYMLINK=keyword

/NOSYMLINK (default)
If the input file is a symbolic link, the file to which the symbolic link refers is the file that is copied.
The /SYMLINK qualifier indicates that any input symbolic link is copied.
If the file named in the command is a symlink, the command operates on the symlink target. The valid keywords for this qualifier are [NO]WILDCARD and [NO]ELLIPSIS. Descriptions are as follows:

Keyword Explanation

NOWILDCARD Indicates that symlinks are disabled during directory wildcard searches.

WILDCARD Indicates that symlinks are enabled during wildcard searches.

NOELLIPSIS Indicates that symlinks are matched for all wildcard fields except for ellipsis.

ELLIPSIS Equivalent to WILDCARD (included for command symmetry).

/TRUNCATE (default)

/NOTRUNCATE
Controls whether the COPY command truncates an output file at the end-of-file (EOF) when copying it. 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 you select /NOTRUNCATE, the allocation of the input file determines the size of the output file.
/VOLUME=n
Places the output file on the specified relative volume number of a multivolume set. By default, the COPY command places the output file arbitrarily in a multivolume set.
/WRITE_CHECK

/NOWRITE_CHECK (default)
Reads each record in the output file after it is written to verify that the record copied successfully and that the file can be read subsequently without error.

Note
Some hardware devices, such as TK50 tape drives, verify data integrity as part of their hardware function. For devices such as these, you do not need to use /WRITE_CHECK. For information about which devices provide automatic write checking, consult your hardware documentation.

Examples

#1
$ COPY TEST.DAT NEWTEST.DAT

In this example, the COPY command copies the contents of the file TEST.DAT from the default disk and directory to a file named NEWTEST.DAT on the same disk and directory. If a file named NEWTEST.DAT exists, the COPY command creates a new version of the file.

#2
$ COPY ALPHA.TXT TMP $ COPY ALPHA.TXT .TMP

In this example, the first COPY command copies the file ALPHA.TXT into a file named TMP.TXT. The COPY command uses the file type of the input file to complete the file specification for the output file. The second COPY command creates a file named ALPHA.TMP. The COPY command uses the file name of the input file to name the output file.

#3
$ COPY/LOG TEST.DAT NEW.DAT;1/REPLACE %COPY-I-REPLACED, DKA0:[MAL]NEW.DAT;1 being replaced %COPY-S-COPIED, DKA0:[MAL]TEST.DAT;1 copied to DKA0:[MAL]NEW.DAT;1 (1 block)

In this example, the /REPLACE qualifier requests that the COPY command replace an existing version of the output file with the new file. The first message from the COPY command indicates that it is replacing an existing file. The version number in the output file must be explicit; otherwise, the COPY command creates a new version of the file NEW.DAT.

#4
$ COPY *.COM [MALCOLM.TESTFILES]

In this example, the COPY command copies the highest versions of files in the current default directory with the file type .COM to the subdirectory MALCOLM.TESTFILES.

$ COPY/LOG *.TXT *.OLD
%COPY-S-COPIED, DKA0:[MAL]A.TXT;2 copied to DKA0:[MAL]A.OLD;2 (1 block)
%COPY-S-COPIED, DKA0:[MAL]B.TXT;2 copied to DKA0:[MAL]B.OLD;2 (1 block)
%COPY-S-COPIED, DKA0:[MAL]G.TXT;2 copied to DKA0:[MAL]G.OLD;2 (4 blocks)
%COPY-S-NEWFILES, 3 files created

In this example, the COPY command copies the highest versions of files with file types .TXT into new files. Each new file has the same file name as an existing file, but a file type .OLD. The last message from the COPY command indicates the number of new files that have been created.

$ COPY/LOG  A.DAT,B.MEM C.*
%COPY-S-COPIED, DKA0:[MAL]A.DAT;5 copied to DKA0:[MAL]C.DAT;11 (1 block)
%COPY-S-COPIED, DKA0:[MAL]B.MEM;2 copied to DKA0:[MAL]C.MEM;24 (58 records)
%COPY-S-NEWFILES, 2 files created

In this example, the two input file specifications are separated with a comma. The asterisk (*) wildcard character in the output file specification indicates that two output files are to be created. For each copy operation, the COPY command uses the file type of the input file to name the output file.

$ COPY/LOG *.TXT TXT.SAV
%COPY-S-COPIED, DKA0:[MAL]A.TXT;2 copied to DKA0:[MAL]TXT.SAV;1 (1 block)
%COPY-S-APPENDED, DKA0:[MAL]B.TXT;2 appended to DKA0:[MAL]TXT.SAV;1 (3 records)
%COPY-S-APPENDED, DKA0:[MAL]G.TXT;2 appended to DKA0:[MAL]TXT.SAV;1 (51 records)
%COPY-S-NEWFILES, 1 file created

In this example, the COPY command copies the highest versions of all files with the file type TXT to a single output file named TXT.SAV. After the first input file is copied, the messages from the COPY command indicate that subsequent files are being appended to the output file.
Note that, if you use the /NOCONCATENATE qualifier in this example, the COPY command creates one TXT.SAV file for each input file. Each TXT.SAV file has a different version number.

#8
$ COPY MASTER.DOC DKA1:[BACKUP]

In this example, the COPY command copies the highest version of the file MASTER.DOC to the device DKA1. If no file named MASTER.DOC exists in the directory [BACKUP], the COPY command assigns the version number of the input file to the output file. You must have write (W) access to the directory [BACKUP] on device DKA1 for the command to work.

#9
$ COPY SAMPLE.EXE DALLAS::DISK2:[000,000]SAMPLE.EXE/CONTIGUOUS

In this example, the COPY command copies the file SAMPLE.EXE on the local node to a file with the same name at remote node DALLAS. The /CONTIGUOUS qualifier indicates that the output file is to occupy consecutive physical disk blocks. You must have write (W) access to the device DISK2 on remote node DALLAS for the command to work.

#10
$ COPY . PRTLND::.

In this example, the COPY command copies all files within the user directory at the local node to the remote node PRTLND. The new files have the same names as the input file. You must have write (W) access to the default directory on remote node PRTLND for the command to work.

#11
$ COPY BOSTON::DISK2:TEST.DAT;5 _To: DALLAS"SAM SECReturn"::DISK0:[MODEL.TEST]TEST.DAT/ALLOCATION=50

In this example, the COPY command copies the file TEST.DAT;5 on the device DISK2 at node BOSTON to a new file named TEST.DAT at remote node DALLAS. The /ALLOCATION qualifier initially allocates 50 blocks for the new file TEST.DAT at node DALLAS. The access control string SAM SECReturn is used to access the remote directory.

#12
$ MOUNT TAPED1: VOL025 TAPE: $ COPY TAPE:. *

In this example, the MOUNT command requests that the volume labeled VOL025 be mounted on the magnetic tape device TAPED1 and assigns the logical name TAPE to the device.
The COPY command uses the logical name TAPE as the input file specification, requesting that all files on the magnetic tape be copied to the current default disk and directory. All the files copied retain their file names and file types.

#13
$ ALLOCATE CR: _CR1: ALLOCATED $ COPY CR1: CARDS.DAT $ DEALLOCATE CR1:

In this example, the ALLOCATE command allocates a card reader for exclusive use by the process. The response from the ALLOCATE command indicates the device name of the card reader, CR1.
After the card reader is allocated, you can place a deck of cards in the reader and enter the COPY command, specifying the card reader as the input file. The COPY command reads the cards into the file CARDS.DAT. The end-of-file (EOF) in the card deck must be indicated with an EOF card (12-11-0-1-6-7-8-9 overpunch).
The DEALLOCATE command relinquishes use of the card reader.

#14
$ COPY [SMITH]MONKEY.DIR [JONES] $ COPY [SMITH.MONKEY]. [JONES.MONKEY].

In this example, the COPY command creates the new empty directory [JONES.MONKEY] that is registered in the [JONES]MONKEY.DIR directory file. After the COPY command creates the new [JONES]MONKEY.DIR directory file, you can copy or create files in the [JONES.MONKEY] directory.
The second COPY command in this example copies files from the [SMITH.MONKEY] directory to the [JONES.MONKEY] directory.

#15
$ COPY [SMITH]CATS.DIR [SMITH]DOGS.DIR

In this example, the COPY command creates the new empty directory file, called [SMITH]DOGS.DIR. Use this copy command to create a directory file that has the same attributes as the [SMITH]CATS.DIR file. This command example has the same effect as entering the command:
$ CREATE/DIRECTORY [SMITH.DOGS]

#16
$ COPY [SMITH]TIGER.DIR [SMITH.ANIMALS] $ COPY [SMITH.TIGER]. [SMITH.ANIMALS.TIGER]. $ DELETE [SMITH.TIGER].;* $ SET SECURITY/PROTECTION=(WORLD:DELETE) TIGER.DIR $ DELETE TIGER.DIR;

In this example, the COPY command creates the new empty directory file called [SMITH.ANIMALS]TIGER.DIR. The subsequent commands in this example then copy the files from the [SMITH.TIGER] directory to the [SMITH.ANIMALS.TIGER] directory, then delete the original TIGER.DIR directory file. Because TIGER.DIR is a directory file, you must specify a protection code of DELETE before you can delete the directory.

Contents

Index