1 04/26/84  do_subtree
  2 
  3 Syntax:  do_subtree path -control_args
  4     or:  do_subtree -slave
  5 
  6 
  7 Function:  operates on a given directory, called the starting node, and
  8 all directories inferior to it by executing one or two given command
  9 lines after substituting the pathname of that directory in the command
 10 line.  The do command performs the substitution, the directory pathname
 11 being taken as the first executed at each node before inferior nodes
 12 are operated on (the top-down command line) and after inferior nodes
 13 are operated on (the bottom-up command line).
 14 
 15 This command enables you to execute the argument command lines in
 16 several processes.  The walking of the hierarchy can be substantially
 17 speeded up by use of this facility.  The process in which the initial
 18 command lines in starting node is given is named the master process;
 19 the other cooperating processes are called the slave processes.  The
 20 cooperating processes communicate via a segment called dos_mp_seg,
 21 which is found (or created if not found) in the working directory when
 22 do_subtree is issued.  The master process must be logged in and begin
 23 executing first when multiple processes are used.
 24 
 25 
 26 Arguments:
 27 path
 28    is the starting node; -working_dir (-wd) specifies the working
 29    directory of the master process if multiple processes are being
 30    used.
 31 
 32 
 33 Control arguments:
 34 -bottom_up STR, -bu STR
 35    specifies the bottom-up command line.  If STR contains blanks, it
 36    must be enclosed in quotes.  The name of the directory of execution
 37    is the first argument to the do command.  Access this value with the
 38    string "&r1" rather than "&1" in case any directory names contain
 39    special characters.  Give one of -bottom_up or -top_down, but you
 40    can use both.
 41 -first N, -ft N
 42    makes N the first level of the directory hierarchy at which the
 43    command lines are executed.  By definition, the starting node is at
 44    level 1.  The default is -first 1.
 45 -last, -lt N
 46    makes N the last level in the storage system hierarchy at which the
 47    command lines are executed.  The default is 99999, i.e., all levels.
 48 
 49 
 50 -long, -lg
 51    prints the names of the directories at which the command lines are
 52    executed.  Unlike walk_subtree, this printing is off by default.  In
 53    multiprocess executions with a bottom-up command line, an asterisk
 54    precedes all directory names for which the process executing the
 55    bottom-up command line is not the process that entered the directory
 56    first.
 57 
 58 
 59 -multiprocess, -mp
 60    makes the invoking process the master process of a multiprocess
 61    execution.  The dos_mp_seg segment is created in the current working
 62    directory and execution begins.  As slave processes are started,
 63    work is distributed by the master process among the slave processes.
 64    Execution ends in all processes simultaneously.  The
 65    top-down/bottom-up order of execution is guaranteed by all
 66    processes:  no command line is executed at a given directory until
 67    either the top-down command line is executed in all superior
 68    directories or the bottom-up command line is executed in all
 69    inferior directories.
 70 
 71 
 72 -no_msf
 73    does not treat multisegment files as directories.  Unlike
 74    walk_subtree, multisegment files are treated as directories by
 75    default.  Avoid -no_msf for most storage system maintenance
 76    operations.
 77 -slave
 78    executes the command line in another process, which must be in a
 79    working directory where an active master process has begun executing
 80    a multiprocess invocation of do_subtree.  The master process uses
 81    all control arguments and command lines of the slave process.
 82    Execution in all processes finishes at the same time.  Don't use
 83    more than 35 slave processes.
 84 
 85 
 86 -top_down STR, -td STR
 87    specifies the top-down command line.  If STR contains blanks, it
 88    must be enclosed in quotes.  The name of the directory of execution
 89    is the first argument to the do command.  Access this value with the
 90    string "&r1" rather than "&1" in case any directory names contain
 91    special characters.  Give one of -bottom_up or -top_down, but you
 92    can use both.
 93 
 94 
 95 Entry:  do_subtree$recover
 96 This entry point is used to pick up the work load of a process that has
 97 died in a multiprocess execution.  The process picking up the work load
 98 of the dead process must have as its working directory the directory in
 99 which the dos_mp_seg segment for the current multiprocess execution
100 exists.
101 
102 
103 Syntax:  do_subtree$recover processnumber
104 
105 
106 Arguments:
107 processnumber
108    is the process number of the dead process.  The process number of a
109    do_subtree process in a multiprocess execution is typed out as it
110    joins the execution.
111 
112 
113 Entry:  do_subtree$abort
114 This entry point halts a multiprocess execution of do_subtree.  All
115 processes return to command level at once.  The process executing this
116 command must have as its working directory the directory in which the
117 dos_mp_seg segment of the current multiprocess execution exists.
118 
119 
120 Syntax:  do_subtree$abort
121 
122 
123 Entry:  do_subtree$status
124 This entry point prints out much debugging and status information
125 about all processes involved in a multiprocess execution of
126 do_subtree, including the process identifiers and command lines.  The
127 process executing this command must have as its working directory the
128 directory in which the dos_mp_seg of the current multiprocess
129 execution exists.