1 01/17/86  enter_retrieval_request, err
 2 
 3 Syntax as a command:  err path {-control_args}
 4 
 5 
 6 Function:  queues volume retrieval requests for specific segments,
 7 directories, multisegment files (MSFs), and subtrees.
 8 
 9 
10 Arguments:
11 path
12    is the pathname of a segment, directory, or node of a subtree.  The
13    star convention is not allowed.
14 
15 
16 Control arguments:
17 -brief, -bf
18    supresses printing of the ID and number of requests in queue.
19 -from DT, -fm DT
20    specifies that the search for path and all inferior branches, if
21    supplied, stops at time DT; thus, objects dumped before time DT are
22    not recovered.  (See time_strings.gi for a description of valid DT
23    values.)  If you give no -from, all valid dump volumes are searched.
24 -long_id
25    prints the long ID of the request.  (Default: to print the short
26    ID)
27 -multisegment_file, -msf
28    specifies that the object named in path is a MSF and that all its
29    components are to be recovered.
30 
31 
32 -new_path newpath
33    specifies that if you have the correct access to retrieve the
34    segment specified in path and to create a segment with the pathname
35    newpath, then the object identified by path is retrieved into
36    newpath.  You can't cross-retrieve directories, MSFs, or subtrees.
37 -notify, -nt
38    notifies you by online mail of the success or failure of the
39    request.  (Default: not to notify you)
40 -previous, -prev
41    retrieves the object dumped prior to the object presently online.
42    With -previous you can retrieve successively earlier copies of an
43    object.  (Default: to retrieve the most recent copy)
44 -queue N, -q N
45    queues requests in priority queue N.  (Default: 3)
46 
47 
48 -subtree, -subt
49    retrieves the subtree inferior to the directory given in path as
50    well as the directory.  If a subtree is found intact after a
51    directory is recovered, then no further action is taken, unless you
52    have provided a time interval (see "Notes").  (Default: not to
53    retrieve subtrees)
54 -to DT
55    searches for path and all inferior branches from time DT backwards;
56    thus, objects dumped later than time DT are not recovered.  (See
57    time_strings.gi for a description of valid DT values.)  If you don't
58    select -to, time DT is assumed to be the start of the retrieval
59    operation.
60 
61 
62 Access required: To retrieve a segment, you need w access to the
63 segment or m access to the containing directory; to retrieve a
64 directory, you need m access to the directory or m access to the
65 containing directory.
66 
67 
68 Notes: In certain cases where a directory is damaged the inferior
69 subtree may be unavailable until the directory is recovered.  When a
70 directory is recovered and -subtree is used, a check is made to see if
71 the subtree is available, and, if so, retrieval is assumed complete.
72 
73 Retrieval requests of objects for which the online copy is more recent
74 or the same as the dump copy are refused, unless you use -previous,
75 -from, or -to.
76 
77 You need not supply as a set of primary names the pathnames of the
78 segments and directories to be retrieved.  Any set of valid entrynames
79 is acceptable.
80 
81 You have to log in to ring 1 to submit retrieval requests for mailboxes
82 and other ring 1 objects.