Retro1.org codex

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.