EXCHANGE COPY — VMS 5.1-B
The EXCHANGE command COPY transfers a file or files from the input
volume to the output volume. EXCHANGE> COPY can:
o Copy a file between a foreign volume and a native volume
o Copy a file from one foreign volume to another foreign volume
o Convert the format of the file during the transfer
o Copy groups of files between volumes
o Give the output file a different name from the input
Format
EXCHANGE> COPY input-file-spec[,...] output-file-spec
Prompts
Input file(s): input-file-spec[,...]
Output file: output-file-spec
Additional information available:
ParametersDescriptionQualifiersExamples
Parameters
input-file-spec[,...]
Specifies the names of one or more input files to be copied. If
you specify more than one input file, you can separate them with
either commas (,) or plus signs (+). Standard VAX/VMS wild cards
can be specified in file names, both Files-11 and foreign. Wild
card directories are supported for Files-11 and DOS-11 input.
The syntax for the file names depends on the particular volume
format option present or implied. See Section 6.0 for
descriptions of the volume format options.
output-file-spec
Specifies the name of the output file, directory or device to
which the input files are to be copied. An explicit output name
(that is, a rename during copy) can only be given if the input
specifies a single file. If the input-file-spec potentially
specifies multiple files, the output-file-spec must be one of:
o Wild cards (*, *.* or *.*;*) specifying current default
device and directory
o An explicit device and/or directory for Files-11 output,
such as CW:<EXCHANGE.TMP>, with or without wild cards for
the file name
o An explicit device for RT-11 as in DLA2:/VOLUME=RT11
o An explicit device or directory for DOS-11 output, such
as TAPE:/VOLUME=DOS11 or TAPE:<11,132>/VOLUME=DOS11
The output file name(s) will be constructed according to rules
implied by the input and output volume qualifiers. EXCHANGE COPY
does not concatenate multiple input files into a single output
file. Wild card directories are not permitted.
The syntax for the output file names is dependent on the
particular volume format qualifier present or implied. See
Section 6.0 for descriptions of the volume format qualifier.
You must specify at least one field in the output file
specification. The EXCHANGE COPY command replaces missing fields
with the corresponding field of the related input file
specification. If the input file has no corresponding field,
EXCHANGE COPY will substitute null text fields and maximize
version numbers.
The UIC of the output file is the UIC of the current process.
For DOS-11 output, EXCHANGE uses the current default directory,
if it is in UIC format; otherwise, it uses the current process's
UIC as a directory. An alternate directory for DOS-11 output may
be specified in the command. Additionally, the /UIC_DIRECTORY
qualifier may be used to determine the output DOS-11 directory.
Description
The EXCHANGE COPY command transfers a file or files from the
input volume to the output volume.
Multiple output files can be created by specifying multiple input
files. When multiple output files are created, the corresponding
field from each input file is used in the output file name.
When no version number field is specified for Files-11 output,
the EXCHANGE COPY command gives the output file a version number
that is one of the following:
o The same version number as the input file, if the input
volume structure supports version numbers and no file
exists with the same name and type
o A version number one greater than the highest version
number of an existing file with the same file name and
file type
o Version 1 if neither of the above applies
When the output file version number is specified by an asterisk
(*) wild card character, the EXCHANGE COPY command uses the
version numbers of the associated input files, if any, as the
version numbers of the output files.
Files-11 magnetic tapes (ANSI) do not treat version numbers
exactly like disks. Please see the VAX/VMS Magnetic Tape User's
Guide for an explanation of version numbers on tapes.
Files may have to be reformatted during the copy operation. The
defaults for reformatting are dependent on the volume format
qualifiers attached to both the input and output file
specifications, as well as the type field of the file
specification. See Section 7.0 for descriptions of the defaults
and of the /RECORD_FORMAT qualifier, which is used to override
the defaults.
Qualifiers
Additional information available:
/BOOT/LOG/ALLOCATION/BEST_TRY_CONTIGUOUS
/CARRIAGE_CONTROL/CONTIGUOUS/DELETE/EXTENSION
/PROTECT/RECORD_FORMAT/REPLACE/REWIND/START_BLOCK
/TRANSFER_MODE/TRUNCATE/VOLUME_FORMAT
/BOOT
/BOOT[=nn]
This qualifier copies bootstrap information from a monitor
file to blocks 0 and 2 through 5 of an RT-11 volume,
permitting you to use that volume as a system volume. The
COPY/BOOT operation does not create any files on the volume,
it is a special purpose command to create bootable RT-11
systems.
RT-11 Version 1 through Version 3 monitors had the system
device handler linked into the monitor image. For Version 4
of RT-11, the system device handler uses the standard device
handler, and the COPY /BOOT command must dynamically link
the handler into the bootstrap area. COPY /BOOT will auto-
matically sense whether the monitor file is an early or late
monitor, and perform this extra step if required. It finds
the default handler for the specific device type, and merges
the handler with the monitor as it is copied to the boot
area.
The optional value on the /BOOT qualifier is used to over-
ride the choice of the default handler. The most frequent
use of this value occurs when a floppy is mounted in an RX02
drive, but it is desired to create a floppy bootable from an
RX01 drive (obviously, the floppy must be single density).
The default handler for the RX02 is DY.SYS, and the handler
needed for the RX01 is DX.SYS. Therefore, one would use the
command COPY /BOOT=DX to make an RX01 bootable system. Do
not specify /BOOT=nn for V3 and earlier systems, choose the
monitor file DYMNxx.SYS or DXMNxx.SYS as the source file.
The /BOOT qualifier only allows a single parameter, the name
of the monitor file. The /BOOT qualifier cannot be combined
with qualifiers other than /LOG.
/LOG
/LOG
/NOLOG
Controls whether EXCHANGE COPY displays the file
specifications of each file copied.
If you specify /LOG, the EXCHANGE COPY command displays, for
each copy operation, the file specifications of the input
and output files and 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).
If it is necessary to change the name of a file because the
output device does not support the format of the file name,
EXCHANGE will log the names (old and new) of the file even
if the /LOG qualifier is not used. To prevent EXCHANGE from
logging name changes, use the /NOLOG qualifier explicitly.
/ALLOCATION
/ALLOCATION=n
Forces the initial allocation of the output file to the number of
512-byte blocks specified as n. /ALLOCATION is only valid for
Files-11 and RT-11 output files.
If not specified, the initial allocation of the output file is
determined by the size of the input file being copied. In normal
use, /ALLOCATION is needed only when:
o Creating a contiguous file on Files-11 (with
/BEST_TRY_CONTIGUOUS or /CONTIGUOUS) when the input file
is on magnetic tape
o Additional space is desired at the end of the file
If /ALLOCATION is specified, EXCHANGE COPY will leave the file at
the allocated size unless /TRUNCATE is also specified.
Specifying both an allocation and /TRUNCATE is useful when the
exact output size is not known beforehand.
/BEST_TRY_CONTIGUOUS
/BEST_TRY_CONTIGUOUS
/NOBEST_TRY_CONTIGUOUS
Indicates whether the output file is to be allocated contiguously
on a "best effort" basis -- that is, whether EXCHANGE will
attempt to place the file on consecutive physical disk blocks.
If insufficient contiguous space is available, the file will
occupy the largest available contiguous space plus additional
extents as necessary for the rest of the allocation. This
qualifier can only be applied to a Files-11 output file.
By default, EXCHANGE COPY will never attempt to create a file on
a best-try-contiguous basis.
The /BEST_TRY_CONTIGUOUS qualifier has no effect when you copy
files to magnetic tapes. When you copy a file from a tape and
want the file to be contiguous if possible, you need to use the
/ALLOCATION qualifier along with /BEST_TRY_CONTIGUOUS because the
size of the file on tape cannot be determined until after it is
copied to the disk. If only the approximate size of the file is
known, you can overestimate the size and specify /TRUNCATE (along
with /ALLOCATION and /BEST_TRY_CONTIGUOUS) to avoid wasted space.
/CARRIAGE_CONTROL
/CARRIAGE_CONTROL=option
The /CARRIAGE_CONTROL qualifier defines the carriage control
attributes of a file. and other attributes of the records.
Option Function
CARRIAGE_RETURN Implied carriage-return/line-feed control
FORTRAN FORTRAN carriage control record attribute
NONE No implied carriage control
See HELP CarriageControl for a complete description of the
/CARRIAGE_CONTROL qualifier and the defaults.
/CONTIGUOUS
/CONTIGUOUS
/NOCONTIGUOUS
Indicates whether the output file is to be contiguous -- that is,
whether the file must occupy consecutive physical disk blocks.
This qualifier can only be applied to a Files-11 output file.
By default, EXCHANGE COPY never creates a contiguous output file.
The /CONTIGUOUS qualifier has no effect when you copy files to
magnetic tapes. When you copy a file from a tape and want the
file to be contiguous, you need to use the /ALLOCATION qualifier
along with /CONTIGUOUS because the size of the file on tape
cannot be determined until after it is copied to the disk. If
the size of the file is only approximately known, you can
overestimate the size and specify /TRUNCATE (along with
/ALLOCATION and /CONTIGUOUS) to avoid wasted space.
/DELETE
/DELETE
/NODELETE
This qualifier controls whether EXCHANGE COPY will delete
existing files of the same name during the copy operation. This
is valid for RT-11 output only.
The default is /DELETE; EXCHANGE will delete existing
identically named files after the new file is copied. A message
will be printed if /LOG is also in effect. Use /NODELETE to
prevent automatic file deletion. The /REPLACE qualifier is also
used to control file deletion, but the action is somewhat
different.
This qualifier is equivalent to the RT-11 COPY command qualifier
/REPLACE.
/EXTENSION
/EXTENSION=n
Specifies the number of blocks to be added to the output file
each time the file is extended. This is valid for Files-11
output files only.
EXCHANGE determines the default extension according to the
following hierarchy:
1. An explicit value specified on the /EXTENSION
qualifier
2. The current process default extension value as set
by the SET RMS_DEFAULT command
3. The current system default extension value as set
at system generation or with the SET
RMS_DEFAULT/SYSTEM command
Setting an extension quantity is normally useful with magnetic
tape input only, since EXCHANGE will preallocate a file of the
correct size when the input is on a directory-structured device.
/PROTECT
/PROTECT
/NOPROTECT
Defines the protection to be applied to an RT-11 output file.
RT-11 files are either protected (/PROTECT specified) or
unprotected (/NOPROTECT, the default).
This qualifier in not valid for Files-11 output files.
Protection attributes for Files-11 output are taken from the
current process default protection.
The /PROTECT qualifier is invalid with DOS-11 output files.
EXCHANGE does not attempt to transfer protection attributes from
the input file to the output file, because protection mechanisms
of various operating systems do not readily translate to one
another.
The owner UIC of the output file is the UIC of the current
process.
/RECORD_FORMAT
/RECORD_FORMAT=(option[,...])
The /RECORD_FORMAT qualifier defines the internal record
structure of a file and other attributes of the records.
Option Function
BINARY Identifies formatted binary mode
transfers
FIXED Identifies fixed-length record format
STREAM Identifies ASCII stream mode transfers
PAD Sets the character to pad short records
on fixed-length output, valid with FIXED
only
/REPLACE
/REPLACE
/NOREPLACE
Requests that if an RT-11 output file already exists with the
same file specification as that entered for the output file, the
existing file is to be deleted before the copy proceeds. The
EXCHANGE COPY command allocates new space for the output file.
This is valid for RT-11 output only.
By default on RT-11 output, EXCHANGE COPY creates the new file
and then deletes the existing file after the copy successfully
completes. With /REPLACE, COPY deletes the file before starting
the transfer. This is useful if there is insufficient room for
two copies of the file. Be careful when you use the /REPLACE
option with RT-11 output; if for any reason the input file is
unreadable, the output file will already have been deleted and
you will be left with no usable version of the file.
This qualifier is equivalent to the RT-11 COPY command qualifier
/PREDELETE.
/REWIND
/REWIND
/NOREWIND
Causes the input tape reel to be rewound (/REWIND) or not
rewound (/NOREWIND) to beginning-of-tape before EXCHANGE
searches for the file name specified in the input specifier.
Use this qualifier only for DOS-11 magnetic tapes. The
/NOREWIND qualifier is the default; use /REWIND when you
want COPY to start searching for a file at the beginning of
the tape rather than starting at the current position.
Note that EXCHANGE maintains an internal list of the files
on a DOS-11 tape, and that the /REWIND qualifier might not
cause an actual rewind of the tape volume. It does cause
EXCHANGE to start the search at the beginning of the
internal list, however.
/START_BLOCK
/START_BLOCK=n
For RT-11 volumes the /START_BLOCK qualifier can be used to
specify the logical block number where the file should be
placed. This can be especially useful with TU58 data
cartridges, because performance can be significantly
enhanced by careful placement of files.
/TRANSFER_MODE
/TRANSFER_MODE=option
The /TRANSFER_MODE option determines how EXCHANGE will
transfer the file. See Transfer_Modes for a more complete
description of /TRANSFER_MODE.
/TRUNCATE
/TRUNCATE
/NOTRUNCATE
Controls whether the EXCHANGE COPY command truncates an output
file at the end-of-file when copying it. By default, the COPY
command uses the allocation of the input file to determine the
size of the output file.
/VOLUME_FORMAT
/VOLUME_FORMAT=option
The /VOLUME_FORMAT qualifier defines the physical format of the
volume to be processed. The default format qualifier is
dependent on the device type. The default is /VOLUME_FORMAT=RT11
for block-addressable devices mounted foreign, and
/VOLUME_FORMAT=DOS11 for magnetic tape devices mounted foreign.
The default for devices mounted native is /VOLUME_FORMAT=FILES11,
the VAX/VMS native volume format.
Option Function
FILES11 Identifies a Files-11 formatted native volume
RT11 Identifies an RT-11 formatted block-
addressable volume
DOS11 Identifies a DOS-11 formatted magnetic tape
volume
Volume format qualifiers must be attached to one or both of the
file specification parameters, they cannot be attached directly
to the verb. A volume format qualifier determines the format of
the file name and directory specifications, and will often imply
certain defaults.
See section 6.0 for a complete description of the /VOLUME_FORMAT
qualifier and the defaults.
Examples
1. EXCHANGE> COPY TEST.DAT DYA0:NEWTST.DAT
The COPY command copies the contents of the file TEST.DAT
from the default disk and directory into a file named
NEWTST.DAT on the RT-11 floppy diskette mounted on DYA0. If
a file named NEWTST.DAT already existed, the COPY command
will have replaced it. The record formats are variable-
length on the Files-11 input and ASCII stream on the RT-11
output.
2. EXCHANGE> COPY/LOG TEST.DAT DYA0:NEWTST.DAT
%EXCHANGE-S-DELETEPREV, previous copy of DYA0:NEWTST.DAT deleted
%EXCHANGE-S-COPIED, WRKD$:<FRED>TEST.DAT;5
copied to DYA0:NEWTST.DAT, 93 records
This COPY command is the same as the preceding example,
except that the /LOG qualifier was used so that the actions
of the command would be seen. The /VOLUME_FORMAT qualifier
has not been used, since EXCHANGE will default to RT11 for
the foreign-mounted floppy. Since NEWTST.DAT was already on
the floppy from the first example, the first copy of the
file was deleted after the second copy was successfully
transferred.
3. EXCHANGE> COPY/LOG LARGE.DAT DYA0:
%EXCHANGE-S-DELETEPREV, previous copy of _DYA0:LARGE.DAT deleted
%EXCHANGE-W-RTOUTEOF, end-of-file on output _DYA0:LARGE.DAT,
insufficient space on volume
%EXCHANGE-I-PARTCOPIED, WRKD$:<FRED>LARGE.DAT;9 partially copied to
_DYA0:LARGE.DAT, 1670 records
EXCHANGE> COPY/LOG/REPLACE LARGE.DAT DYA0:
%EXCHANGE-S-DELETEPREV, previous copy of _DYA0:LARGE.DAT deleted
%EXCHANGE-S-COPIED, WRKD$:<FRED>LARGE.DAT;9 copied to
_DYA0:LARGE.DAT, 3288 records
The first COPY failed because there was not enough room on
DYA0: for EXCHANGE to do a normal copy (that is, to copy
the file into a temporary on DYA0:, delete the existing file
of the same name, and then rename the temporary).
The /REPLACE qualifier requests that EXCHANGE COPY first
delete an existing version of the output file before copying
the new file. The first message from the COPY command
indicates that it is deleting an existing file. The second
message informs of the completed copy.
4. EXCHANGE> COPY MTA0:<11,132>*.COM <FRED.TEMP>
The COPY command copies all the files with a file type of
COM owned by UIC <11,132> to the subdirectory <FRED.TEMP>.
The DOS-11 record format will be STREAM by default, the
Files-11 format will be variable-length records.
5. EXCHANGE> COPY/BOOT DYA0:RT11SJ.SYS DYA0:
This COPY/BOOT command makes the diskette mounted on the
RX02 drive DYA0: a bootable RT-11 system. Boot information
is written to use the RT-11 single job monitor (RT11SJ.SYS).
The diskette could be formatted in single or double density.
6. EXCHANGE> COPY/BOOT CSA1:CONSOL.SYS CSA1:
This COPY/BOOT command writes boot information on the
console storage device on a VAX-11 processor.
8. EXCHANGE> COPY DMA0:FROG.DAT/RECORD=STREAM -
_EXCHANGE> FROG4JUN.DAT/RECORD=(FIXED=80,PAD=" ")
This command copies an ASCII stream file (which is the
default) from an RT-11 volume to the current default device
and directory. The output contains fixed-length records
that are padded to 80 bytes with the space character.