1 02/27/85 retrieve
2
3 Syntax as a command: retrieve path -control_args
4
5
6 Function: retrieves specified storage system segments, directories and
7 subtrees. It does this by copying them from a hierarchy dump tape into
8 the hierarchy, possibly into different places in the hierarchy than
9 those from which they were originally dumped. The retireve command
10 calls the backup_load command to do the actual retrieving.
11
12 The retrieve command requires a retrieval control file, containing the
13 pathnames of the objects to be retrieved. It calls backup_load once
14 for each line in the control file. See "Notes on Format of a Retrieval
15 Control File" below. Cross retrievals are allowed; i.e., objects can
16 be retrieved into different places in the hierarchy than those
17 specified on the dump tape. The retrieve command places its maps in
18 the working directory and doesn't automatically dprint them. Quota on
19 the retrieved directories is not force-set.
20
21
22 The retrieve command is one of the commands used for hierarchy
23 reloading and retrieving of storage system segments and directories.
24 The other commands are:
25
26 backup_load
27 reload initializer command
28 reload Multics command
29 reload_system_release
30
31
32 You should note that argument processing for all of the hierarchy
33 backup commands is performed by a common argument processing procedure.
34 The values of all arguments are remembered in static storage and remain
35 in effect for the life of the process, unless changed by arguments
36 given in subsequent invocations of backup commands. It should also be
37 noted that the dumping commands and the reloading/retrieving commands
38 are all part of the same hierarchy backup system, and argument values
39 set by the dumping commands remain in effect for the
40 reloading/retrieving commands and vice versa, unless overridden.
41 However, dumping and reloading cannot be done in the same process; use
42 the new_proc command between dumping and reloading. See "Notes on
43 Default Arguments" below.
44
45
46 Arguments:
47 path
48 is the absolute pathname of a retrieval control file see "Notes on
49 Format of a Retrieval Control File" below. This argument is
50 required. It can be given anywhere on the command line.
51
52
53 Control arguments:
54 -all
55 causes segments to be retrieved from the tape regardless of their
56 date/time dumped. This is the default. This control argument
57 overrides a previously given DATE argument.
58 -brief_map, -bfmap
59 creates a map file that lists the processed entires.
60 -control path
61 indicates that path is a hierarchy retrieval control file pathname.
62 See "Notes on Format of a Retrieval Control File" below.
63
64
65 -debug
66 disables those hphcs_ calls that set quotas and transparency
67 switches.
68 -destination STR, -ds STR
69 specifies a destination for printing maps and error file. The
70 default is "incremental" for maps and "error file" for error files.
71 -error_of
72 writes error messages into a file rather than printing them. The
73 name of the error file is printed when the first error is
74 encountered. This is the default.
75 -error_on
76 writes error messages on the user's terminal.
77 -first
78 prevents searching a tape for additional copies of a requested
79 segment or subtree after the first copy has been retrieved.
80
81
82 -header STR, -he STR
83 specifies a heading for printing maps and error files.
84 -last
85 indicates that the last copy of a given segment or subtree on a tape
86 or set of tapes is to be retrieved. This is the default.
87 -map
88 writes a list of the segments and directories processed into a file.
89 This is the default.
90 -nodebug
91 enables hphcs_ calls to set quotas and the transparency switches.
92 This is the default.
93
94
95 -nomap
96 inhibits listing of the names of processed segments and directories.
97 -noprimary, -npri
98 uses each pathname as given. The default is -primary.
99 -noqcheck
100 causes the hierarchy reload to be done with quota checking
101 suspended. Access to hphcs_ is required. This is the default.
102 -noquota
103 inhibits resetting of quotas. See -quota. This is the default.
104 -noreload
105 inhibits actual hierarchy reloading of segments into the hierarchy.
106 This control argument can be used with -map to create a table of
107 contents of the tape. The -noreload control argument also causes
108 the names that would have been reloaded to be put into the map.
109
110
111 -nosetlvid
112 inhibits the setting of the logical volume identifiers for each
113 directory to be reloaded.
114 -notrim
115 inhibits deletion of entries in a directory. Entries can only be
116 added or modified. This is the default.
117 -operator STR
118 indicates that STR is the user's name or initials up to 16
119 characters in length.
120 -primary, -pri
121 replaces all directory names in each pathname with the primary
122 names. This is the default.
123 -pvname STR
124 indicates that segments and directories can only be retrieved onto
125 the physical volume specified by STR.
126
127
128 -qcheck
129 causes quota restrictions to be enforced during the reload.
130 -quota
131 causes the quotas on directories being reloaded to be set to the
132 values they had when the directories were dumped. Access to hphcs_
133 is required.
134 -reload
135 enables actual reloading of segments into the hierarchy. This is
136 the default.
137 -request_type STR, -rqt STR
138 specifies an output request type for printing maps and error files.
139 Available request types can be listed by using the
140 print_request_types command described in the Multics Commands and
141 Active Functions manual Order No. AG92 . The default is
142 "printer".
143
144
145 -setlvid
146 enables setting of the logical volume identifier for reloaded
147 entries inferior to each directory reloaded. This is the default.
148 -trim
149 enables deletion of all entries in a directory not found in the copy
150 of that directory being reloaded. This causes entries deleted from
151 an earlier version of the directory to be deleted when a later
152 version is reloaded. It has effect only in the case of a directory
153 that is both on the tape and in the hierarchy. This is the default.
154 DATE
155 an argument beginning with a character other than "-", or ">" is
156 assumed to be a date in a format acceptable to the
157 convert_date_to_binary_ subroutine. If it can be converted
158 successfully, then the hierarchy retriever only retrieves segments
159 and directories dumped at or after the given date/time.
160
161
162 Notes on default arguments: The values of arguments given to any of
163 the hierarchy backup commands are remembered in static storage and
164 remain in effect for the life of the process, unless explicitly changed
165 during the invocation of a subsequent backup command.
166
167 The following defaults are in effect for the reloader and retriever
168 before any backup commands are given; they are not, however, reset to
169 these values at the start of each backup command, except as noted
170 below.
171
172 -all -noquota
173 -error_of -primary
174 -map -reload
175 -nodebug -setlvid
176 -nohold -trim
177
178
179 The following defaults are set automatically at the time the respective
180 commands are executed:
181
182 reload initializer command, reload Multics command,
183 reload_system_release:
184 -quota
185 -trim
186
187 retrieve:
188 -all
189 -noquota
190 -notrim
191
192 All of the above commands:
193 -map
194
195
196 Notes on format of a retrieval control file: The hierarchy retrieval
197 is controlled by an ASCII segment containing one line for each object
198 to be retrieved. A line can contain a single pathname or two pathnames
199 separated by an equal sign. The left-hand side specifies the segment
200 or directory sought and the right-hand side, if present, specifies the
201 new name under which that entity is to be retrieved. The sought
202 pathname must begin with a > and end with either an entryname or the
203 characters >**. If an entryname is specified, a single object of that
204 name is retrieved.
205
206
207 If >** is specified, the entire directory hierarchy, beginning at the
208 point indicated in the pathname, is retrieved. In this case, the
209 right_hand pathname, if present, ends in the name of the directory
210 under which these entries are to be reloaded. For example:
211
212 >udd>one_dir>**=>udd>two_dir
213
214 If a new name is specified on the right, it can be either a pathname or
215 an entryname. If an entryname is given, the single object found is
216 loaded with its former pathname and the new entryname.
217
218
219 If two pathnames are specified, both are checked against the current
220 hierarchy and a new pathname consisting only of the primary entryname
221 is created. This new pathname, as well as the original, is then used
222 in searching the hierarchy. For example, >udd>sd is translated into
223 >user_dir_dir>SysDaemon and both versions are sought. Primary names
224 are used unless the -noprimary control argument is in effect.
225
226 A hierarchy retrieval control file can contain a maximum of 256 lines.