1 08/21/2018 catchup_dump
  2 
  3 Syntax as a command:  catchup_dump {ctl_file {operator {ntapes {int}}}}
  4    {-control_args}
  5 
  6 
  7 Function:  begins a catchup hierarchy dump.  It dumps all storage
  8 system segments and directories which have been modified since a
  9 specified date and time (the default is midnight two days prior).  The
 10 catchup_dump command calls the backup_dump command to do the actual
 11 dumping.
 12 
 13 
 14 The catchup_dump command requires a dump control file, containing the
 15 full pathnames of the objects to be dumped.  It calls backup_dump once
 16 for each line in the control file.  See "Notes on Format of a Dump
 17 Control File" below.  When the control file is exhausted, i.e., when
 18 the catchup dump pass is finished, the catchup_dump command starts up
 19 the incremental hierarchy dumper in the same manner as the start_dump
 20 command.  (Incremental and catchup hierarchy dumps are normally
 21 performed by the same process.)  You can prevent this by using the
 22 -nocontin control argument.  A map of all objects dumped is created in
 23 the working directory, with the name <unique-name>.dump.map.
 24 
 25 If you don't specify the -debug control argument, catchup_dump
 26 increases the scheduling priority of the dumping process by calling
 27 hphcs_$set_timax with a value of 7000000.
 28 
 29 
 30 The catchup_dump command is one of the commands used to control
 31 hierarchy dumping of storage system segments and directories to
 32 magnetic tape.  The other commands are:
 33 
 34    backup_dump
 35    complete_dump
 36    end_dump
 37    start_dump
 38    wakeup_dump
 39 
 40 
 41 You should note that argument processing for all of the hierarchy
 42 backup commands is performed by a common argument processing procedure.
 43 The values of all arguments are remembered in static storage and remain
 44 in effect for the life of the process, unless changed by arguments
 45 given in subsequent invocations of backup commands.  It should also be
 46 noted that the dumping commands and the reloading/retrieving commands
 47 are all part of the same hierarchy backup system, and argument values
 48 set by the dumping commands remain in effect for the
 49 reloading/retrieving commands and vice versa, unless overridden.
 50 However, dumping and reloading cannot be done in the same process; use
 51 the new_proc command between dumping and reloading.  See "Notes on
 52 Default Arguments" below.
 53 
 54 
 55 You may define certain frequently used arguments to the catchup_dump
 56 command in two different ways.  The first way is to precede the
 57 argument with an identifying control argument.  The second way is to
 58 place the argument in a certain position on the command line.  In the
 59 first case, the combination of control argument and argument may appear
 60 anywhere on the command line after any positional information.  In the
 61 second case, the argument must appear at the beginning of the command
 62 line, before any control argument-argument combinations or any control
 63 arguments which stand alone.
 64 
 65 
 66 For the catchup_dump command, the frequently used arguments are the
 67 control file, the operator's name, the number of tape copies, and the
 68 wakeup interval.  When defined to the command positionally, i.e.,
 69 without identifying control arguments, these arguments must appear in
 70 the following positions:
 71 
 72       catchup_dump {ctl_file {operator {ntapes {int}}}} {-control_args}
 73 
 74 The control file and the operator's name must be specified, in one way
 75 or the other.
 76 
 77 
 78 Arguments:
 79 ctl_file
 80    is the pathname of the dump control file (see the -control control
 81    argument).
 82 operator
 83    is the operator's name or initials (see the -operator control
 84    argument).
 85 ntapes
 86    is the number of copies to be made of each hierarchy dump tape (see
 87    the -tapes control argument).
 88 int
 89    is the wakeup interval (see the -wakeup control argument).
 90 
 91 
 92 Control arguments:
 93 -all
 94    causes all directory entries (in the specified subtree) to be
 95    dumped, regardless of their dates modified or dates dumped.  This
 96    argument overrides a previously given -dtd control argument or DATE
 97    argument.  This is the default.
 98 -brief_map, -bfmap
 99    creates a map file that lists the processed entries.
100 -contin
101    causes catchup_dump to start the incremental hierarchy dumper after
102    the catchup pass is finished.  This is the default.
103 
104 
105 -control path
106    indicates that path is the pathname of a dump control file.  The
107    suffix "dump" is assumed.  For example, "-control sys_dirs"
108    specifies a control file named sys_dirs.dump, in the working
109    directory.  See "Notes on Format of a Dump Control File" below.
110 -debug
111    disables those phcs_ and hphcs_ calls that deactivate dumped
112    segments and set quotas.
113 -destination STR, -ds STR
114    specifies a destination for printing maps and error files.  The
115    default is "incremental" for maps and "error file" for error files.
116 -dtd
117    tests and dumps each segment only if the segment or its branch has
118    been modified since the last time it was dumped.
119 
120 
121 -error_off
122    writes error messages into a file rather than online.  The name of
123    the error file is printed when the first error is encountered.  This
124    is the default.
125 -error_on
126    writes error messages on the user's terminal.
127 -header STR, -he STR
128    specifies a heading for dprinting maps and error files.
129 -hold
130    leaves the current hierarchy dump tape or tapes mounted and inhibits
131    rewinding after the current hierarchy dump cycle is completed.
132 -map
133    writes a list of the segments and directories processed into a file.
134    This is the default.
135 
136 
137 -nocontin
138    prevents catchup_dump from starting the incremental hierarchy dumper
139    after the catchup pass is finished.
140 -nodebug
141    enables hphcs_ calls to set quotas and the transparency switches.
142    This is the default.
143 -nohold
144    rewinds and unloads the hierarchy dump tape or tapes at the end of
145    the current dump pass.  This is the default.
146 -nomap
147    inhibits listing of the names of processed segments and directories
148    and turns the tape switch on (see -tape below).
149 -nooutput
150    inhibits writing hierarchy dump information even if the tape switch
151    is on.  This is used for a test run or debugging.
152 
153 
154 -noprimary, -npri
155    uses each pathname as given.  The default is -primary.
156 -notape
157    inhibits writing of a hierarchy tape.  This argument also causes a
158    map to be created even if it was previously inhibited.  (See -map
159    above.)
160 -only
161    indicates that only the requested segment or directory and its
162    branch are to be dumped.  This is the opposite of -sweep.
163 -operator STR
164    indicates that STR is the user's name or initials (up to 16
165    characters in length).
166 -output
167    writes hierarchy dump information onto the tape if the tape switch
168    is on.  This is the default.
169 
170 
171 -primary, -pr
172    replaces all directory names in each pathname with the primary
173    names.  This is the default.
174 -pvname STR
175    indicates that segments and directories may only be dumped if they
176    reside on the physical volume specified by STR.
177 -request_type STR, -rqt STR
178    specifies an output request type for printing maps and error files.
179    Available request types can be listed by using the
180    print_request_types command.  The default is "printer."
181 -restart path
182    indicates that path is the pathname of a segment or directory where
183    hierarchy dumping is to be restarted.  Use of this feature assumes
184    that there is a dump control file.  It is normally used to restart a
185    hierarchy dump that was interrupted by a system failure.
186 
187 
188 -sweep
189    indicates that the whole subtree beginning with the given directory
190    is to be dumped, subject to the criteria of the -dtd control
191    argument or the DATE argument if either has been invoked.  This is
192    the default.
193 -tape
194    allows writing of a tape.  This is the default.
195 -tapes N
196    indicates that N is the number of output tape copies to be made
197    where N can be either 1 or 2.  The default is 1.
198 -volume_pool path, -vp path
199    indicates that the specified volume pool should be used to provide
200    automated selection of tapes to use for dumping. See the
201    manage_volume_pool (mvp) command for help on managing volume
202    pools.
203 
204 
205 -no_volume_pool, -no_vp
206    disables use of a volume pool for automatic tape selection.
207 -1tape
208    sets the number of tape copies to 1 as an alternative to the -tapes
209    argument.
210 -2tapes
211    sets the number of tape copies to 2 as an alternative to the -tapes
212    argument.
213 -wakeup N
214    indicates that N is the wakeup interval between incremental
215    hierarchy dump passes, in minutes.  The default is 60 minutes.
216 
217 
218 DATE
219    an argument beginning with a character other than "-" or ">" is
220    assumed to be a date, in a format acceptable to the
221    convert_date_to_binary_ subroutine.  If the argument can be
222    converted to a date, then only segments and directories modified
223    after that date are dumped.
224 
225 
226 Notes on default arguments:  The values of arguments given to any of
227 the hierarchy backup commands are remembered in static storage and
228 remain in effect for the life of the process, unless explicitly changed
229 during the invocation of a subsequent backup command.
230 
231 
232 The following defaults are in effect for the dumper before any backup
233 commands are given; they are not, however, reset to these values at the
234 start of each backup command, except as noted.
235 
236    -all
237    -contin
238    -error_of
239    -map
240    -nodebug
241    -nohold
242    -output
243    -primary
244    -sweep
245    -tape
246 
247 
248 The following defaults are set automatically at the time the respective
249 commands are executed:
250 
251       catchup_dump
252            -tape
253             (default date yesterday at midnight)
254 
255       complete_dump
256            -all
257            -tape
258 
259       start_dump
260            -dtd
261 
262 
263            -hold
264            -tape
265            -wakeup 60
266 
267 
268 
269 Notes on format of a dump control file:  The control file specified by
270 "-control path" is an ASCII segment containing absolute pathnames of
271 entries (segments, MSFs, and directory subtrees) to be dumped, each on
272 a separate line.