COPYFILE CMS User Area command
Use the COPYFILE command to copy and/or modify CMS disk files. The manner in
which the file identifiers are entered determines whether or not one or more
output files are created. The format of the COPYFILE command is:
+----------+------------------------------------------------------------------+
| COPYfile | fileidi1 [fileidi2...] [fileido] [(options...[)]] |
| | options: |
| | NOType|Type NEWDate|OLDDate |
| | NEWFile|REPlace PRompt|NOPRompt |
| | copy extent options: |
| | FRom recno|FRLabel xxxxxxxx OVly|APpend |
| | FOR numrec|TOLabel xxxxxxxx NOSPecs|SPecs |
| | data modification options: |
| | RECfm F|V LRecl nnnnn |
| | NOTRunc|TRUnc PAck|UNPack |
| | FIll 40|c|hh |
| | character translation options: |
| | EBcdic TRAns UPcase|LOwcase |
+----------+------------------------------------------------------------------+
where:
fileidi1 is the first (or only) input file. Each file identifier (filename,
filetype, and filemode) must be specified either by indicating the
specific identifier or by coding an asterisk.
fileidi2 is one or more additional input files. Each file identifier
(filename, filetype, and filemode) must be specified. In single
output mode, any of the three input file identifiers may be specified
either by indicating the specific identifier or by coding an asterisk.
However, all three file identifiers of fileidi2 cannot be specified by
asterisks. In multiple output mode, an asterisk is an invalid file
identifier. An equal sign may be coded for any of the file
identifiers, indicating that it is the same as the corresponding
identifier in fileidi1.
fileido is the output file(s) to be created. Each file identifier (filename,
filetype, and filemode) must be specified. To create multiple output
files, an equal sign must be coded in one or more of the identifier
fields. If there is only one input file, fileido may be omitted, in
which case it defaults to = = = (the input file represented by
fileidi1 is replaced).
Options:
NOType suppresses the display of the names of the files being copied. This
is the default.
Type displays, at the terminal, the names of the files being copied.
NEWDate uses the current date as the creation date of the new file(s). This
is the default.
OLDDate uses the date on the (first) input file as the creation date of the
new file(s).
NEWFile checks that files with the same fileid as the output file do not
already exist. If one or more output files do exist, an error message
is displayed and the COPYFILE command terminates. This option is the
default so that existing files are not inadvertently destroyed.
REPlace causes the output file to replace an existing file with the same file
identifier. REPLACE is the default option when only one fileid is
entered or when the output fileid is specified as "= = =".
PRompt displays the messages that request specification or translation lists.
This is the default.
NOPRompt suppresses the display of prompting messages for specification and
translation lists.
Copy extent options:
FRom recno
is the starting record number for each input file in the copy
operation.
FRLabel xxxxxxxx
xxxxxxxx is a character string that appears at the beginning of the
first record to be copied from each input file. Up to eight nonblank
characters may be specified.
FOR numrec
is the number of records to be copied from each input file.
TOLabel xxxxxxxx
xxxxxxxx is a character string which, if at the beginning of a record,
stops the copy operation for that input file. The record containing
the given character is not copied. Up to eight nonblank characters
may be specified.
OVly overlays the data in an existing output file with data from the input
file. You can use OVLY with the SPECS option to overlay data in
particular columns.
APpend at the end of the output file.
SPecs indicates that you are going to enter a specification list to define
how records should be copied. See "Entering a COPYFILE Specification
List" for information on how you can define output records in a
specification list.
NOSPecs indicates that no specification list is to be entered.
Data modification options:
The following options can be used to change the record format of a file. See
"Modifying Record Formats" for more details.
RECfm F | V
is the record format of the output files. If not specified, the output
record format is the same as that of the input file.
LRecl nnnnn
is the logical record length of the output file(s) if it is to be
different from that of the input file(s). The maximum value of nnnnn
is 65535.
NOTRunc suppresses the removal of trailing blanks (or fill characters) when
converting fixed-length files to variable-length format. This is the
default.
TRUnc removes trailing blanks (or fill characters) when converting fixed-
length files to variable-length format.
PAck compresses records in a file so that they can be stored in packed
format.
Caution: A file in packed format should not be modified in any way.
If such a file is modified, the UNPACK routines are unable to
reconstruct the original file.
UNPack reverses the PACK operation. If a file is inadvertently packed twice,
you can restore the file to its original unpacked form by issuing the
COPYFILE command twice.
FIll 40 | c | hh
is the padding and truncation character for the TRUNC option or the
principal packing character for the PACK option. The fill character
may be specified as a single character, c, or by entering a two-digit
hexadecimal representation of a character. The default is 40 (the
hexadecimal representation for a blank in EBCDIC).
Character translation options:
EBcdic converts a file that was created with 026 keypunch characters (BCD),
to 029 keypunch characters (EBCDIC). The following conversions are
made: { to ), & to +, % to (, # to =, @ to ', ' to :
UPcase converts all lowercase characters in each record to uppercase before
writing the record to the output file.
LOwcase converts all uppercase characters in each record to lowercase before
writing the record to the output file.
TRAns indicates that you are going to enter a list of character translations
to be made as the file is copied. See "Entering Translation
Specifications" for details on entering a list of characters to be
translated.
Incompatible options:
The table below shows combinations of options that should not be specified
together in the same COPYFILE command. If the option in the first column is
specified, do not code any of the options in the second column.
Options Incompatible Options
APPEND LRECL, NEWDATE, NEWFILE, OLDDATE, OVLY, PACK, RECFM, REPLACE,
UNPACK
EBCDIC PACK, UNPACK
FOR PACK, TOLABEL, UNPACK
FRLABEL FROM, PACK, UNPACK
FROM FRLABEL, PACK, UNPACK
LOWCASE PACK, UNPACK
LRECL APPEND, PACK, UNPACK
NEWDATE APPEND, OLDDATE
NEWFILE APPEND, OVLY, REPLACE
NOPROMPT PROMPT
NOSPECS SPECS
NOTRUNC TRUNC
NOTYPE TYPE
OLDDATE APPEND, NEWDATE
OVLY APPEND, NEWFILE, PACK, REPLACE, UNPACK
PACK APPEND, EBCDIC, FOR, FRLABEL, FROM, LOWCASE, LRECL, OVLY,
RECFM, SPECS, TOLABEL, TRANS, TRUNC, UNPACK, UPCASE
PROMPT NOPROMPT
RECFM APPEND, PACK, UNPACK
REPLACE APPEND, NEWFILE, OVLY
SPECS NOSPECS, PACK, UNPACK
TOLABEL FOR, PACK, UNPACK
TRANS PACK, UNPACK
TRUNC NOTRUNC, PACK, UNPACK
TYPE NOTYPE
UNPACK APPEND, EBCDIC, FOR, FRLABEL, FROM, LOWCASE, LRECL, OVLY, PACK,
RECFM, SPECS, TOLABEL, TRANS, TRUNC, UPCASE
UPCASE PACK, UNPACK
Usage notes:
Two simple uses of the COPYFILE command are: (1) to copy a single CMS file
from one disk to another, or (2) to make a duplicate copy of the file on the
same disk. For example:
copyfile test1 assemble a test2 assemble a
makes a copy of the file TEST1 ASSEMBLE A and names it TEST2 ASSEMBLE A.
For those portions of the file identifier that you want to stay the same, you
may code an equal sign in the output fileid. Thus, the command line above can
be entered:
copyfile test1 assemble a test2 = =
The equal sign may be used as a prefix or suffix of a file identifier. For
example, the command:
copyfile a b c file= type= =
creates an output file called FILEA TYPEB C.
When you copy a file from one virtual disk to another, you specify the old and
new filemodes, and any filename or filetype change you want to make; for
example:
copyfile test3 assemble c good = a
This command makes a copy of the file TEST3 ASSEMBLE C, and names it GOOD
ASSEMBLE A.
If you want to copy only particular records in a file, you can use the FROM/FOR
FRLABEL/TOLABEL options. For example:
copyfile old test a new test a (frlabel start for 41
copies 41 records from the file OLD TEST A1, beginning with the record starting
with the character string START into the file NEW TEST A1.
Also:
1. If the input filemode is an '*', then you should specify an explicit
filemode, not an '=', for the output filemode. If you do not specify an
explicit output filemode, it is possible to create an output file that
would be recognized as an input file which generates the error message
DMSCPY024E stating that the file already exists. For example, if you have a
file named 'C B A' and you issue the command 'COPY C * * = D =', COPY will
first create an output file named 'C D A'. This file will then match the
input fileid of the file 'C * *' and copy will attempt to write an output
file with the name 'C D A', which already exists.
2. If the output filemode number is not specified, it is determined by the
following rules:
o If the output file does not exist, the input filemode number is used.
o If the output file exists, the existing output filemode number is used.
3. COPYFILE uses a temporary workfile called COPYFILE CMSUT1. If the copy
operation ends abnormally, the workfile may be left on your disk. You
should erase or rename this file. Its presence can prevent you from copying
files in the future. COPYFILE CMSUT1 is a reserved workfile name for the
COPYFILE command.
Multiple input and output files:
You can combine two or more files into a single file with the COPYFILE command.
For example:
copyfile test data1 a test data2 = test data3 b
copies the files TEST DATA1 and TEST DATA2 from your A-disk and combines them
into a file, TEST DATA3, on your B-disk.
Note that if any input file has a filemode number of 3, it is possible that the
file will be copied in a sequence different from its order on the disk.
If you want to combine two more files without creating a new file; use the
APPEND option. For example:
copyfile new list a old list a (append
appends the file NEW LIST A to the bottom of the existing file labeled OLD LIST
A.
Note: If the file NEW LIST A has a different LRECL from the file OLD LIST A,
the appended data is padded, or truncated, to the LRECL of the file OLD LIST A.
Whenever you code an asterisk in an input fileid, you may cause one or more
files to be copied, depending upon the number of files that satisfy the
remaining conditions. For example:
copyfile * test a combined test a
copies all files with a filetype of TEST on your A-disk into a single file
named COMBINED TEST. If only one file with a filetype of TEST exists, only
that file is copied.
If you want to copy all the files on a particular disk to another disk, you
could enter:
copyfile * * b = = a
All the files on the B-disk are copied to the A-disk. The filenames and
filetypes remain unchanged.
You can also copy a group of files and change all the filenames or all the
filetypes. For example:
copyfile * assemble b = test a
copies all ASSEMBLE files on the B-disk into files with a filetype of TEST on
the A-disk. The filenames are not changed.
Whenever an asterisk appears, it indicates that all files are to be copied;
whenever an equal sign (=) appears, it indicates that the same files are to be
copied. For example:
copyfile x * a1 = file =
combines all files with a filename of X on the A-disk into a single file named
X FILE A1.
Whenever an equal sign appears in the output fileid in a position corresponding
to an asterisk in an input fileid, multiple input files produce multiple output
files. When you perform copy operations of this nature you might wish to use
the TYPE option, which displays the names of files being copied. For example:
copyfile * test a = output a = summary = (type
might result in the display:
COPY 'ALPHA TEST A1' TO 'ALPHA SUMMARY A1' (NEW FILE)
COPY 'ALPHA OUTPUT A'
COPY 'BETA TEST A1' TO 'BETA SUMMARY A1' (NEW FILE)
COPY 'BETA OUTPUT A.'
which indicates that files ALPHA TEST A and ALPHA OUTPUT A were copied into a
file named ALPHA SUMMARY A and that files BETA TEST A and BETA OUTPUT A were
copied into a file named BETA SUMMARY A.
Modifying record formats:
You can use the RECFM and LRECL options to change the record format of a file
as you copy it. For example:
copyfile data file a (recfm f lrecl 130
converts the file DATA FILE A1 to fixed-length 130-character records.
If you specify an output fileid, for example:
copyfile data file a fixdata file a (recfm f lrecl 130
the original file remains unchanged. The file FIXDATA FILE A contains the
converted records.
If the records in a file being copied are variable-length, each output record
is padded with blanks to the specified record length. If any records are
longer than the record length, they are truncated.
When you convert files from fixed-length records to variable-length records,
you can specify the TRUNC option to ensure that all trailing blanks are
truncated:
copyfile data file a (recfm v trunc
If you specify the LRECL option and RECFM V, the LRECL option is ignored and
the output record length is taken from the longest record in the input file.
When you convert a file from variable-length to fixed-length records, you may
also specify a fill character to be used for padding instead of a blank. If
you specify:
copyfile short recs a (recfm f fill *
then each record in the file SHORT RECS is padded with asterisks to the record
length. Assuming that SHORT RECS was originally a variable-length file, the
record length is taken from the longest existing record. Note that if SHORT
RECS is already fixed-length, it is not altered.
Similarly, when you are converting back to variable-length a file that was
padded with a character other than a blank, you must specify the FILL option to
indicate the pad character, so that character is truncated.
The FILL option can also be used to specify the packing character used with the
PACK option. When you use the PACK option, a file is compressed as follows:
all occurrences of two or more blanks are encoded as one character, and four or
more occurrences of any other character are written as three characters. If
you use the FILL option to specify a fill character, then that character is
treated as a blank when records are compressed. You must, of course, specify
the FILL option to unpack any files packed in this way. Since most fixed-
length files are blank-padded to the record length, you do not need to specify
the FILL option unless you know that some other character appears more
frequently.
When you convert record formats on packed files with the COPYFILE command you
can specify single or multiple output files, in accordance with the procedures
outlined under "Modifying Record Formats." For example:
copyfile * assemble a (pack
compresses all ASSEMBLE files in the A-disk without changing any file
identifiers. The command:
copyfile * assemble a = script = (recfm v trunc
creates copies of all ASSEMBLE files residing on your A-disk. The copies will
have variable-length record formats and filetypes of SCRIPT.
Entering a COPYFILE specification list:
When you use the COPYFILE command, you can specify particular columns of data
to be manipulated or particular characters to be translated. Again, how you
specify the file identifier determines how many files are copied or modified.
When you use the SPECS option on the COPYFILE command, you receive the message:
DMSCPY601R Enter specification list:
The system waits for you to enter a specification list. If you do not wish to
receive this message, use the NOPROMPT option. The specification list you
enter may consist of one or more pairs of operands in the following format:
nnn-mmm ¦ /string/ ¦ hxx... col
where:
nnn-mmm specifies the start and end columns of the input file that are to be
copied to the output file. If mmm exceeds the length of the input
record, the end of the record is the assumed ending position.
string is any string of uppercase and lowercase characters or numbers
delimited by any non-alphameric character.
hxx... is an even number of hexadecimal digits prefixed with an h.
col is the column in the output file at which the copy operation is to
begin.
You can enter as many as 20 pairs of specifications resulting in as many as 130
characters per line. If you want to enter more than one line of
specifications, enter two plus signs (++) before column 130 at the end of one
input line as continuation indicators.
A specification list may contain any combination of specification pairs; for
example:
copyfile sorted list a (specs
DMSCPY601R Enter specification list:
/ / 1 1-8 3 / / 12 /***/ 14 ++
9-80 18
After this command is executed, each record in the file SORTED LIST will look
like the following:
oooooooo *** oooo....
where the o's in columns 3 through 10 indicate information originally in
columns 1 through 8; the o's following the asterisks indicate the remainder of
each record, columns 9 through 80.
When you enter a specification list, you are actually constructing a file
column by column. If you specify multiple input or output files, the same copy
operation is performed for each record in each output file.
Those columns for which you do not specify any data are filled with blanks or,
if you use the FILL option, the fill character of your choice. For example:
copyfile sorted list a (specs noprompt lrecl 20 fill $
1-15 6
copies columns 1 through 15 beginning in column 6 and writes dollar signs($) in
columns 1 through 5.
If you do want to modify data in particular columns of a file but want to leave
all of the rest of each record unchanged, you can use the OVLY (overlay)
option. For example, the sequence:
COPYFILE * bracket a (specs ovly noprompt
had 1 hbd 80
overlays the characters ( (X'AD') and ) (X'BD') in columns 1 and 80 of all the
files with a filetype of BRACKET on your A-disk.
When you copy fixed-length files, records are padded or truncated to the record
length; variable-length files are always written as specified.
Entering translation specifications:
You can perform conversion on particular characters in CMS files or groups of
files with the TRANS option of the COPYFILE command.
When you enter the TRANS option, you receive the message:
DMSCPY602R Enter translation list:
and a read is presented to your virtual machine. You may enter the translation
list. If you do not wish to receive this message, use the NOPROMPT option.
A translation list consists of one or more pairs of characters or hex digits,
each pair representing the character you want to translate and the character
you want to translate it to, respectively. For example:
copy test file a (trans
DMSCPY602R Enter translation list:
* - A f0 00 ff
specifies that all occurrences of the character * are to be translated to -,
all character A's are to be translated to X'F0' and all X'00's are to be
translated to X'FF's.
If any translation specifications you enter conflict with the LOWCASE, EBCDIC,
or UPCASE options specified on the same command line, the translation list
takes precedence. In the preceding example, if LOWCASE had also been
specified, all A's would be translated to X'F0's, not to a's.
You can enter as many as 130 characters per line. You can enter translation
pairs on more than one line if you enter two plus signs (++) before column 130
at the end of one input line as continuation indicators.
Responses:
DMSCPY601R ENTER SPECIFICATION LIST:
This message prompts you to enter a specification list when you use the
SPECS option.
DMSCPY602R ENTER TRANSLATION LIST:
This message prompts you to enter a translation list when you use the TRANS
option.
DMSCPY721I COPY 'fn ft fm' [TO¦APPEND¦OVLY] 'fn ft fm' [OLD¦NEW] FILE
This message appears for each file copied with the TYPE option. It
indicates the names of the input file and output file. When you have
multiple input files, the output fileid is displayed only once.