1 COPY Transfers a file or files from an input volume to an output volume. You can use the COPY command to do any of the following: o Copy a file from a foreign volume to a native volume o Copy a file from a native volume to a foreign 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 from volume to volume o Give the output file a different name from the input file Format COPY input-file-spec[, . . . ] output-file-spec 2 Parameters input-file-spec[, . . . ] Specifies the names of one or more input files to be copied. If you specify more than one input file, separate them with commas or plus signs. The syntax for input file names depends on the volume format option. You can specify standard OpenVMS wildcards in both Files-11 and foreign file names. COPY supports wildcard directories for Files-11 and DOS-11 input. NOTE The EXCHANGE COPY command does not process search lists as input files. If you specify a search list as input to the COPY command, only the first item is processed. For example, suppose you issue the following commands: $ DEFINE search_list [directory_1], [directory_2] $ EXCHANGE COPY search_list:*.* [directory_3] The EXCHANGE command does not copy anything from directory_2. output-file-spec Specifies the name of the output file, directory, or device to which the input files are to be copied. If the input is a single file, you can specify an explicit output name (which is equivalent to a rename on a copy operation). If the input is more than one file, the output specifier must be one of the following: o Wildcards (*, *.* or *.*;*) specifying current default device and directory o An explicit device and/or directory for Files-11 output, such as BB:[EXCHANGE.TMP], with or without wildcards 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 names are constructed according to rules implied by the input and output volume qualifiers. COPY does not concatenate multiple input files into a single output file. Wildcard directories are not permitted. The syntax for input file names depends on the volume format option. You must specify at least one field in the output file specification; COPY replaces missing fields with the corresponding field of the related input file specification. If the input file has no corresponding field, COPY substitutes null text fields and maximizes version numbers. The UIC of the output file is the UIC of the current process. For DOS-11 output in UIC format, EXCHANGE uses the current default directory; otherwise, it uses the current process UIC as a directory. You can specify an alternate directory for DOS-11 output in the command. 2 Qualifiers /BOOT /BOOT[=nn] Copies bootstrap information from a monitor and the handler files 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 intended only to create bootable RT-11 systems. The /BOOT qualifier implies /VOLUME_FORMAT=RT11 for both input and output specifications. The output device can be omitted, as it is assumed to be identical to the input device. You cannot combine the /BOOT qualifier with qualifiers other than /LOG. The COPY/BOOT command requires that both the input and output devices be the same volume or virtual device. The file name of the desired monitor must be specified as the input specification. RT-11 Version 1.0 through Version 3.0 monitors had the system device handler linked into the monitor image. For Version 4.0 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 finds the default handler for the specific device type and merges the handler with the monitor as it is copied to the boot area. You can use the two-letter argument nn to override the default system device handler. The most frequent use of this option occurs when a diskette is mounted in an RX02 drive, and you want to create a diskette bootable from an RX01 drive. (The diskette must be single density.) The default handler for the RX02 is DY.SYS, and the handler for the RX01 is DX.SYS; therefore, you would use the command COPY/BOOT=DX to create the bootable RX01 system diskette. Do not specify /BOOT=nn for Version 3.0 RT-11 and earlier systems; instead, choose the monitor file DYMNxx.SYS or DXMNxx.SYS as the source file. /LOG /LOG /NOLOG Controls whether the EXCHANGE command COPY displays the file specifications of each file copied. If you specify /LOG, the system displays the following data 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). The default is /NOLOG. 2 File_Qualifiers /ALLOCATION /ALLOCATION=n Forces the initial allocation of the output file to the number of 512-byte blocks that you specified as n. The /ALLOCATION qualifier is valid only for Files-11 and RT-11 output files. By default, COPY determines the initial allocation of the output file by the size of the input file. Typically, /ALLOCATION is needed only when you are creating a contiguous file on Files-11 (using /BEST_TRY_CONTIGUOUS or /CONTIGUOUS), when the input file is on magnetic tape, or when you want additional space at the end of the file. If you specify /ALLOCATION, the file's allocated size does not change, unless you also specify /TRUNCATE. When you are unsure of the output size, you might want to specify both /ALLOCATION and /TRUNCATE. /BEST_TRY_CONTIGUOUS /BEST_TRY_CONTIGUOUS /NOBEST_TRY_CONTIGUOUS Indicates whether the Files-11 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 occupies the largest available contiguous space plus additional extents as necessary for the rest of the allocation. You can apply this qualifier only to a Files-11 output file. The /BEST_TRY_CONTIGUOUS qualifier has no effect when you copy files to magnetic tape volumes. When you would like a file from a magnetic tape to be copied contiguously, use both the /ALLOCATION and the /BEST_TRY_CONTIGUOUS qualifiers, because the size of the file on magnetic tape cannot be determined until after it is copied to the disk. If you do not know the exact size of the file, overestimate the size and specify /TRUNCATE (along with /ALLOCATION and /BEST_TRY_CONTIGUOUS) to avoid wasted space. The default is /NOBEST_TRY_CONTIGUOUS. /CARRIAGE_CONTROL /CARRIAGE_CONTROL=option Defines the carriage control attributes of a file, as well as other attributes of the records. The carriage control options are: CARRIAGE_RETURN, which implies carriage return/line-feed control; FORTRAN, which indicates that the first character of each record is to be interpreted as the carriage control specifier; and NONE, which indicates that carriage control is not implied. The default is /CARRIAGE_CONTROL=CARRIAGE_RETURN. /CONTIGUOUS /CONTIGUOUS /NOCONTIGUOUS Indicates whether the copied file is to be contiguous; that is, stored on consecutive physical blocks on an output disk volume. The /CONTIGUOUS qualifier is valid only for Files-11 output files. The /CONTIGUOUS qualifier has no effect when you copy files to magnetic tape volumes. When you would like a file from a magnetic tape to be copied contiguously, use both the /ALLOCATION and /CONTIGUOUS qualifiers because the size of the file on magnetic tape cannot be determined until after it is copied to the disk. If you do not know the exact size of the file, overestimate the size and specify the /TRUNCATE qualifier (along with /ALLOCATION and /CONTIGUOUS) to avoid wasted space. The default is /NOCONTIGUOUS. /DELETE /DELETE /NODELETE Controls whether COPY deletes existing files of the same name during the copy operation. This qualifier is valid for RT-11 output only; it is equivalent to the RT-11 COPY command qualifier /REPLACE. In fact, you can use the EXCHANGE COPY command qualifier /REPLACE to control file deletion, although its function differs from that of /DELETE (see the description of the /REPLACE qualifier for details on its function). If you want a message displayed when you delete a file, include the /LOG qualifier in your command. To prevent automatic file deletion, use /NODELETE. The default is /DELETE. Files with the same name as the output file name are deleted after the new file has been copied. /EXTENSION /EXTENSION=n Specifies the number of blocks to be added to the output file each time the file is extended. This qualifier 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 set by the command SET RMS_DEFAULT 3. The current system default extension value set at system generation or with the SET RMS_DEFAULT/SYSTEM command Use the /EXTENSION qualifier to set an extension quantity with magnetic tape input; EXCHANGE preallocates a file of the correct size when the input is on a directory-structured-device. /PROTECT /PROTECT /NOPROTECT Determines whether protection is set for an RT-11 output file. The owner UIC of the output file is the UIC of the current process. This qualifier is not valid for Files-11 or DOS-11 output files. Protection attributes for Files-11 output are taken from the current process default protection. 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 default is /NOPROTECT. /RECORD_FORMAT /RECORD_FORMAT=(option[, . . . ]) Defines the internal record structure of a file, as well as other attributes of the records. /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. COPY allocates new space for the output file. The /REPLACE qualifier is valid for RT-11 output only; it is equivalent to the RT-11 COPY command qualifier /PREDELETE. By default, COPY creates the new file first and then, after the copy operation is done, deletes the previous file. However, when you use /REPLACE, COPY deletes the previous file before it copies the new file. This can be a problem if the input file has been corrupted because the previous version of the file will have been deleted. Therefore, you should use /REPLACE only when there is insufficient room for two copies of the file. /REWIND /REWIND /NOREWIND Determines whether a DOS-11 input magnetic tape reel logically rewinds to the beginning-of-tape mark (BOT) before EXCHANGE searches for the file name specified in the input specifier. This qualifier is valid for DOS-11 magnetic tape only. The default is /NOREWIND. Use the /REWIND qualifier when you want COPY to search for a file from the logical beginning of the magnetic tape, instead of from the current physical position of the tape. /START_BLOCK /START_BLOCK=[n] For RT-11 volumes, specifies the logical block number where the file is to be placed. This qualifier is especially useful with TU58 tape cassettes, because performance can be significantly enhanced by careful placement of files. /SYSTEM /SYSTEM /NOSYSTEM Controls whether the COPY command copies files that have the file type SYS. Files with a file type of SYS are usually necessary for the operation of an RT-11 system. Only RT-11 volumes handle SYS files in this manner. The default is /NOSYSTEM; the COPY command does not copy an RT-11 file with the type SYS, whether matched by a wildcard specification or explicitly named. EXCHANGE displays a message whenever it skips over a SYS file during a copy operation. /TRANSFER_MODE /TRANSFER_MODE=option Specifies the I/O method to be used in a transfer. This qualifier is useful for all volume formats. Option Function AUTO Select BLOCK transfer for efficiency if possible BLOCK Transfer block by block without looking at records RECORD Transfer record by record The default is the AUTOMATIC transfer mode. In AUTOMATIC mode, EXCHANGE attempts to use a BLOCK transfer whenever possible. BLOCK transfers are possible between RT-11 volumes or between RT-11 and DOS-11 volumes, since the internal file structures are identical. AUTOMATIC does not use the BLOCK transfer if either file specification contains a /RECORD_FORMAT qualifier. A BLOCK transfer moves data between devices. Since no interpretation is done on the data, BLOCK transfers are more efficient than RECORD transfers. The block sizes on both devices must be identical. Both input and output must be in BLOCK format. Specifying BLOCK on one parameter implies BLOCK for the other file or device specification. A BLOCK transfer produces an exact copy of the file. If the output device is Files-11, the file will be a sequential file with fixed-length 512-byte records. This feature is used primarily to avoid any interpretation of the data during the transfer. If the Files-11 file is a sequential file with 512-byte fixed-length records, there is no difference between a /TRANSFER_ MODE=BLOCK transfer and a /RECORD=FIXED=512 transfer. A RECORD transfer moves the data record by record. A RECORD transfer requires more time than a BLOCK transfer, but it must be used if the input and output record structures differ. When the /LOG qualifier is used in a COPY command, EXCHANGE displays the size of the file that was transferred. If BLOCK mode was used, the message gives the file size as the number of blocks transferred. If RECORD mode was used, the message displays the number of records. /TRUNCATE /TRUNCATE /NOTRUNCATE Controls whether COPY truncates an output file at the end-of- file when copying it. The default is /NOTRUNCATE; COPY uses the allocation of the input file to determine the size of the output file. /VOLUME_FORMAT /VOLUME_FORMAT=option Defines the physical format of the volume to be processed. The default format qualifier is dependent on the device type. If used, volume format qualifiers must be attached to one or both of the file specification parameters; you cannot attach them directly to the command. A volume format qualifier determines the format of the file name and directory specifications, and often implies certain defaults. 2 Description COPY transfers a file or files from an input volume to an output volume. You can create multiple output files 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. If you do not specify a version number for Files-11 output, COPY applies a version number as follows: o The same version number as that of 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 that is 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 If you use an asterisk (*) wildcard character to specify the output file version number, COPY uses the version numbers of the associated input files (if any) as the version numbers of the output files. Note that ANSI-formatted magnetic tapes do not handle version numbers in the same manner as disks. EXCHANGE might reformat files during the copy operation. The defaults for reformatting are dependent on the record and volume format qualifiers that are attached to both the input and output file specifications, as well as the type fields of the file specifications. The COPY command does not copy a file with the SYS type unless you specify the /SYSTEM qualifier. EXCHANGE displays a message if it passes over one or more SYS files during a copy operation. EXCHANGE does not copy files with the type BAD if the file specification contains wildcards. EXCHANGE does not display a message when it passes over one or more BAD files during a copy operation. Therefore, to copy a file with the type BAD, specify the file name explicitly instead of using wildcards. 2 Examples 1.EXCHANGE> COPY TEST.DAT DYA0:NEWTST.DAT/VOLUME=RT11 The command in this example copies the contents of the file TEST.DAT from the default disk and directory into a file named NEWTST.DAT on an RT-11 diskette (mounted on DYA0). If a file named NEWTST.DAT already exists, the COPY command replaces 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 The command in this example is the same as in the preceding example, except that the /LOG qualifier is included so that the actions of the command are displayed. The /VOLUME_FORMAT qualifier is omitted; EXCHANGE defaults to RT-11 format for the foreign mounted diskette. Since a file named NEWTST.DAT already exists on the diskette (from the command in the previous example), the first copy of the file is deleted after the second copy is successfully transferred. 3.EXCHANGE> COPY/LOG LARGE.DAT DYA0:/VOLUME=RT11 %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:/VOLUME=RT11 %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 command in this example fails because there is insufficient space on DYA0 for EXCHANGE to do a normal copy (that is, to copy the file into a temporary file on DYA0, delete the existing file of the same name, and then rename the temporary file). The second command in this example includes the /REPLACE qualifier, which directs COPY to delete an existing version of the output file before copying the new file. The first message generated by this command indicates that EXCHANGE has deleted an existing file. The second message indicates that the copy operation has successfully completed. 4.EXCHANGE> COPY MTA0:[11,132]*.COM/VOLUME=DOS11 [FRED.TEMP] The command in this example copies all files with the file type COM owned by UIC [11,132] to the subdirectory [FRED.TEMP]. The default DOS-11 record format is STREAM. The default Files-11 record format is VARIABLE. 5.EXCHANGE> COPY/BOOT DYA0:RT11SJ.SYS DYA0: The COPY/BOOT command in this example makes the diskette mounted on the RX02 drive DYA0 a bootable RT-11 system. Bootstrap information is written to the volume using the RT-11 single job monitor RT11SJ.SYS and the system device handler DY.SYS. The diskette can be formatted in single or double density. 6.EXCHANGE> COPY/BOOT=DX DYA0:RT11SJ.SYS DYA0: As in the previous example, the COPY/BOOT command in this example makes the diskette mounted on the RX02 drive DYA0 a bootable RT-11 system. In this example, however, the system device handler is DX.SYS, the RX01 diskette handler. The diskette must be formatted in single density in order to boot on the RT-11 system. 7.EXCHANGE> COPY/BOOT CSA1:CONSOL.SYS The command in this example writes bootstrap information on the console storage device on a VAX processor. 8.EXCHANGE> COPY DMA0:FROG.DAT/VOLUME=RT11/RECORD=STREAM - _EXCHANGE> FROG4JUN.DAT/RECORD=(FIXED=80,PAD=" ") The command in this example copies an ASCII stream file (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.