1 02/11/85  copy_file, cpf
  2 
  3 Syntax as a command:
  4    cpf in_control_arg out_control_arg {-control_args}
  5 
  6 
  7 Function: copies records from an input file to an output file that has
  8 been restructured for maximum compactness.  The input and output file
  9 records must be structured (see "Notes on unstructured files" below).
 10 The input file can be copied either partially or in its entirety.
 11 
 12 
 13 Arguments:
 14 in_control_arg
 15    the input file from which records are read can be specified by
 16    either of the following:
 17    -input_switch STR, -isw STR
 18       specifies the input file by means of an already-attached I/O
 19       switch name, where STR is the switch name.
 20    -input_description STR, -ids STR
 21       specifies the input file by means of an attach description STR.
 22       STR must be enclosed in quotes if it contains spaces or other
 23       command language characters.
 24 
 25 
 26 out_control_arg
 27    the output file to which the records are written can be specified by
 28    either of the following:
 29    -output_switch STR, -osw STR
 30       specifies the output file by means of an already-attached I/O
 31       switch name, where STR is the switch name.
 32    -output_description STR, -ods STR
 33       specifies the output file by means of an attach description STR.
 34       STR must be enclosed in quotes if it contains spaces or other
 35       command language characters.
 36 
 37 
 38 Control arguments:
 39 -all, -a
 40    copies until the input file is exhausted.  (Default)
 41 -brief, -bf
 42    suppresses a message indicating the number of records or lines
 43    actually copied.
 44 -count N, -ct N
 45    copies until N records have been copied or the input file is
 46    exhausted, whichever occurs first, where N is a positive integer.
 47    (Default: to copy until the input file is exhausted)
 48 -from N, -fm N
 49    copies records beginning with the Nth record of the input file,
 50    where N is a positive integer.  (See "Notes.") (Default: to begin
 51    copying with the "next record")
 52 
 53 
 54 -keyed
 55    copies both records and keys from a keyed sequential input file to a
 56    keyed sequential output file.  (See "Notes on keyed files.")
 57    (Default: to copy records from an input file, keyed or not, to a
 58    sequential output file)
 59 -long, -lg
 60    prints a message indicating the number of records or lines actually
 61    copied: "345 records copied".  (Default)
 62 -start STR, -sr STR
 63    copies records beginning with the record whose key is STR, where STR
 64    is 256 or fewer ASCII characters.  (Default: to begin copying with
 65    the "next record")
 66 
 67 
 68 -stop STR, -sp STR
 69    copies until the record whose key is STR has been copied or the
 70    input file is exhausted, whichever occurs first, where STR is 256 or
 71    fewer ASCII characters.  This control argument can be given without
 72    specifying -start.  However, if -start is supplied, the STR used
 73    with -stop must be greater than or equal to (according to the ASCII
 74    collating sequence) the STR given with -start.
 75 -to N
 76    copies until the Nth record has been copied or the input file is
 77    exhausted, whichever occurs first, where N is a positive integer
 78    greater than or equal to the N given with -from.  If you use -to,
 79    you must give -from.
 80 
 81 
 82 Notes: If either the input or output specification is an attach
 83 description, it is used to attach a uniquely named I/O switch to the
 84 file.  The switch is opened, the copy performed, and then the switch is
 85 closed and detached.  Alternately the input or output file can be
 86 specified by an I/O switch name.  Use either io_call or iox_ to attach
 87 the file prior to the invocation of copy_file.
 88 
 89 If the input file is specified by an I/O switch name and the switch is
 90 not open, copy_file opens it for (keyed_)sequential_input, performs the
 91 copy, and closes it.  If the switch is already open when copy_file is
 92 invoked, the opening mode must be sequential_input,
 93 sequential_input_output, keyed_sequential_input, or
 94 keyed_sequential_update.  The switch is not closed after the copy has
 95 been performed.
 96 
 97 
 98 The "next record" must be defined if neither -start nor -from is
 99 specified as the absolute starting position within the input file.  If
100 the I/O switch is opened by copy_file, the next record is the first
101 record of the file; otherwise the next record is the one at which the
102 file is positioned when copy_file is invoked.
103 
104 
105 If the output file is specified by an I/O switch name and the switch is
106 not open, copy_file opens it for (keyed_)sequential_output, performs
107 the copy, and closes it.  If the switch is already open when copy_file
108 is invoked, the opening mode must be sequential_output,
109 sequential_input_output, keyed_sequential_output,
110 keyed_sequential_update, direct_output, or direct_update.  (In update
111 mode, output file records with keys that duplicate input file records
112 are rewritten.)  The switch is not closed after the copy has been
113 performed.
114 
115 The following control arguments are mutually exclusive-- -from and
116 -start; -to, -stop, -count, and -all; -brief and -long.
117 
118 
119 Notes on unstructured files: This command operates by performing
120 record I/O on structured files.  If you want to copy from/to an
121 unstructured file, you can use the record_stream_ I/O module:
122    cpf -ids "record_stream_ -target vfile_ pathname" -osw OUT
123 which takes lines from the file specified by pathname via the vfile_
124 I/O module, transforms them into records via the record_stream_ I/O
125 module, and copies them to the I/O switch named OUT.
126 
127 
128 Notes on keyed files: The command can copy a keyed sequential file to
129 produce an output file that has been restructured for maximum
130 compactness as a keyed file or as though it were sequential.  By
131 default it copies only records and does not place keys in the output
132 file.  To copy the keys, use -keyed.  When you select -keyed the input
133 file must be a keyed sequential file.  Whether keys are copied or not,
134 choose control arguments to delimit the range of records to be copied
135 (e.g., -start, -stop).  Copying is always performed in key order.
136 
137 If the keyed file has keys but no records (e.g., a dictionary file),
138 the file, its keys, and its associated record descriptors are copied.