1 08/21/2018 start_dump
  2 
  3 Syntax as a command:  start_dump {ctl_file {operator {ntapes {int}}}}
  4    {-control_args}
  5 
  6 
  7 Function:  begins incremental hierarchy dumping.  It dumps all storage
  8 system segments and directories which have been modified since the last
  9 time they were dumped.  After setting a timer to periodically wakeup
 10 and begin an incremental dump pass, the start_dump command calls the
 11 backup_dump command to do the actual dumping.  (The default wakeup
 12 interval is one hour.)
 13 
 14 
 15 The start_dump command requires a dump control file, containing the
 16 full pathnames of the objects to be dumped.  It calls backup_dump once
 17 for each line in the control file.  See "Notes on Format of a Dump
 18 Control File" below.  When the control file is exhausted, the
 19 incremental dumper "goes to sleep" until it is awakened by the timer to
 20 begin another pass.  A map of all objects dumped is created in the
 21 working directory, with the name <unique-name>.dump.map.
 22 
 23 
 24 The start_dump command is one of the commands used to control hierarchy
 25 dumping of storage system segments and directories to magnetic tape.
 26 The other commands are listed below.
 27 
 28    backup_dump
 29    catchup_dump
 30    complete_dump
 31    end_dump
 32    wakeup_dump
 33 
 34 
 35 You should note that argument processing for all of the hierarchy
 36 backup commands is performed by a common argument processing procedure.
 37 The values of all arguments are remembered in static storage and remain
 38 in effect for the life of the process, unless changed by arguments
 39 given in subsequent invocations of backup commands.  It should also be
 40 noted that the dumping commands and the reloading/retrieving commands
 41 are all part of the same hierarchy backup system, and argument values
 42 set by the dumping commands remain in effect for the
 43 reloading/retrieving commands and vice versa, unless overridden.
 44 However, dumping and reloading cannot be done in the same process; use
 45 the new_proc command between dumping and reloading.  See "Notes on
 46 Default Arguments" below.
 47 
 48 
 49 You may define certain frequently used pieces of information to the
 50 start_dump command in two different ways.  The first way is to precede
 51 the peice of information with an identifying control argument.  The
 52 second way is to place the piece of information in a certain position
 53 on the command line.  In the first case, the combination of control
 54 argument and information may appear anywhere on the command line after
 55 any positional information.  In the second case, the information must
 56 appear at the beginning of the command line, before any control
 57 argument-information combinations or any control arguments which stand
 58 alone.
 59 
 60 
 61 For the start_dump command, the frequently used pieces of information
 62 are the control file, the operator's name, the number of tape copies,
 63 and the wakeup interval.  When defined to the command positionally,
 64 i.e., without identifying control arguments, these peices of
 65 information must appear in the following positions.
 66 
 67       start_dump {ctl_file {operator {ntapes {int}}}} {-control_args}
 68 
 69 The control file and the operator's name must be specified, in one way
 70 or the other.
 71 
 72 
 73 Arguments:
 74 ctl_file
 75    is the pathname of the dump control file (see the -control control
 76    argument).
 77 operator
 78    is the operator's name or initials (see the -operator control
 79    argument).
 80 ntapes
 81    is the number of copies to be made of each hierarchy dump tape (see
 82    the -tapes control argument).
 83 int
 84    is the wakeup interval (see the -wakeup control argument).
 85 
 86 
 87 Control arguments:
 88 -all
 89    causes all directory entries (in the specified subtree) to be
 90    dumped, regardless of their dates modified or dates dumped.  This
 91    argument overrides a previously given -dtd control argument or DATE
 92    argument.
 93 -brief_map, -bfmap
 94    creates a map file that lists the processed entries.
 95 -control path
 96    indicates that path is the pathname of a dump control file.  The
 97    suffix "dump" is assumed.  For example, "-control sys_dirs"
 98    specifies a control file named sys_dirs.dump, in the working
 99    directory.  See "Notes on Format of a Dump Control File" below.
100 
101 
102 -debug
103    disables those phcs_ and hphcs_ calls that deactivate dumped
104    segments and set quotas.
105 -destination STR, -ds STR
106    specifies a destination for printing maps and error files.  The
107    default is "incremental" for maps and "error file" for error files.
108 -dprint, -dp
109    causes the start_dump command to dprint maps and error files.  This
110    is the default.
111 -dtd
112    tests and dumps each segment only if the segment or its branch has
113    been modified since the last time it was dumped.  This is the
114    default.
115 
116 
117 -error_of
118    writes error messages into a file rather than online.  The name of
119    the error file is printed when the first error is encountered.  This
120    is the default.
121 -error_on
122    writes error messages on the user's terminal.
123 -header STR, -he STR
124    specifies a heading for dprinting maps and error files.
125 -hold
126    leaves the current hierarchy dump tape or tapes mounted and inhibits
127    rewinding after the current hierarchy dump cycle is completed.  This
128    is the default.
129 
130 
131 -map
132    writes a list of the segments and directories processed into a file.
133    This is the default.
134 -nodebug
135    enables hphcs_ calls to set quotas and the transparency switches.
136    This is the default.
137 -nodprint, -no_dprint, -ndp
138    causes the start_dump command not to dprint maps and error files.
139    The default is -dprint.
140 
141 
142 -nohold
143    rewinds and unloads the hierarchy dump tape or tapes at the end of
144    the current dump pass.  This is the default for all hierarchy dump
145    modes except incremental.
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 -noprimary, -npri
153    uses each pathname as given.  The default is -primary.
154 
155 
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 STR is the name of a physical volume to be dumped.
176 -request_type STR, -rqt STR
177    specifies an output request type for printing maps and error files.
178    Available request types can be listed by using the
179    print_request_types command (described in the Multics Commands and
180    Active Functions manual, Order No.  AG92).  The default is
181    "printer."
182 
183 
184 -sweep
185    indicates that the whole subtree beginning with the given directory
186    is to be dumped, subject to the criteria of the -dtd control
187    argument or the DATE argument if either has been invoked.  This is
188    the default.
189 -tape
190    allows writing of a tape.  This is the default.
191 -tapes N
192    indicates that N is the number of output tape copies to be made
193    where N can be either 1 or 2.  The default is 1.
194 -volume_pool path, -vp path
195    indicates that the specified volume pool should be used to provide
196    automated selection of tapes to use for dumping. See the
197    manage_volume_pool (mvp) command for help on managing volume
198    pools.
199 
200 
201 -no_volume_pool, -no_vp
202    disables use of a volume pool for automatic tape selection.
203 -1tape
204    sets the number of tape copies to 1 as an alternative to the -tapes
205    argument.
206 -2tapes
207    sets the number of tape copies to 2 as an alternative to the -tapes
208    argument.
209 -wakeup N
210    indicates that N is the wakeup interval between incremental
211    hierarchy dump passes, in minutes.  The default is 60 minutes.
212 
213 
214 DATE
215    an argument beginning with a character other than "-" or ">" is
216    assumed to be a date, in a format acceptable to the
217    convert_date_to_binary_ subroutine.  If the argument can be
218    converted to a date, then only segments and directories modified
219    after that date are dumped.
220 
221 
222 Notes on default arguments:  The values of arguments given to any of
223 the hierarchy backup commands are remembered in static storage and
224 remain in effect for the life of the process, unless explicitly changed
225 during the invocation of a subsequent backup command.
226 
227 The following defaults are in effect for the dumper before any backup
228 commands are given; they are not, however, reset to these values at the
229 start of each backup command, except as noted.
230 
231    -all             -nohold
232    -contin          -primary
233    -error_of        -output
234    -map             -sweep
235    -nodebug         -tape
236 
237 
238 The following defaults are set automatically at the time the respective
239 commands are executed.
240 catchup_dump
241    -tape
242     (default date yesterday at midnight)
243 complete_dump
244    -all
245    -tape
246 start_dump
247    -dtd
248    -hold
249    -tape
250    -wakeup 60
251 
252 
253 Notes on format of a dump control file:  The control file specified by
254 "-control path" is an ASCII segment containing absolute pathnames of
255 entries (segments, MSFs, and directory subtrees) to be dumped, each on
256 a separate line.  Cross-dumping is specified by "=new_path" following a
257 pathname, with no intervening spaces, where new_path is the pathname of
258 the new parent directory if the string contains >'s; otherwise, it is a
259 new entryname to replace the entryname portion of the pathname dumped.
260 The entry is placed on the tape as if its pathname were the resulting
261 new pathname.