retrieve_file [-fhlvGEN_FLAGS] ds=<record_set> out=<dest> [segment=<segment_name>]
record_set is a database query that allows the user to select a subset of records of a series. In particular, the user can supply values for the sel and note keywords in record_set to search for files saved with store_file - store a file to SUMS. For each file in the record set specified by record_set, retrieve_file - retrieve a file from SUMS will copy (or link, if the -l flag is present) the record segment's file to dest. If the series contains more than one segment, segment_name must be present. Since the name of a segment's file is the segment name, any file in dest whose name matches the segment's name will be overwritten. However, a backup will be saved (the file will be renamed with a ~ suffix) if an overwrite is to occur, unless the -f flag is specified. retrieve_file - retrieve a file from SUMS prints to stdout the list of files retrieved, or NOT_FOUND if a file cannot be found. It also prints the contents of the note keyword value.
If the link flag, -l, is specified, then retrieve_file - retrieve a file from SUMS will create a link to the SUMS file instead of copying the SUMS file to the destination directory. Over time this link may become broken as SUMS may remove a stored file if it is present in SUMS longer than its specified retention time.
Example: to retrieve a single file:
-f: Force removal of a pre-existing file with same name as retreived file.
-h: Print usage message and exit.
-l: Create a symbolic link to the SUMS file instead of copying it to dest.
-v: Run in verbose mode.
|record_set||A series name followed by an optional record set filter (i.e., name[filter]). Causes selection of a subset of records in the series. Each record retrieved with this record_set query will refer to one file that will be copied to dest.|
|dest||The destination directory to which the SUMS file(s) should be copied/linked. Do not append a final '/' to the path (i.e., /home/arta/dir1 is acceptable, but /home/arta/dir1/ is not)|
|segment_name||Name of the segment whose file should be retrieved.|