Pantheon files are backed up to tapes in the early hours of the morning. These tapes are stored in a tape library dataserver.

To request a file to be restored, connect to the Pantheon terminal (see Using the SSH Client Terminal. Then you can type the correct command at the prompt.

For examples of useful commands, see below. The general syntax for dsmc is:
dsmc restore [options...] sourcefilespec [destinationfilespec]
For descriptions of the command options, see the Command Options section below.

When you request a file to be restored, ADSM determines on which tape your file resides. A robotic arm finds the appropriate tape and puts it in an available tape drive. When the file is found on the tape, it is restored to the location you specify.

A typical file restoration session may look like this:

pantheon% dsmc restore homework.c
ADSTAR Distributed Storage Manager
Command Line Backup Client Interface - Version 2, Release 1, Level 0.3
(C) Copyright IBM Corporation, 1990, 1996, All Rights Reserved.
 
Restore function invoked.
 
Session established with server ADSM: AIX-RS/6000
  Server Version 2, Release 1, Level 0.7
  Data compression forced on by the server
  Server date/time: 05/31/1996 09:01:05   Last access: 05/31/1996 02:59:40 

Restoring        2,512 /home/userid/homework.c  ** Interrupted **
ANS4117I One or more requested files are stored on offline media
ANS4118I Waiting for mount of offline media....
Restoring        2,512 /home/userid/homework.c . Done

Restore processing finished.
 
Total number of objects restored:         1
Total number of bytes transferred:    1,466
Total failures:                           0
Elapsed processing time:            0:00:56

In this case ADSM paused for several seconds while the robotic arm mounted the appropriate tape in the slot and restored the file from it. The total time was still under 1 minute. Note that if no tape drives are available, or if the server is busy fulfilling other backup or restore jobs, you may have to wait several minutes or even hours for the operation to complete.

Below are several examples of tasks you might wish to accomplish, and the command you would input to accomplish them.

• Task: Restore a single file in your home directory named budget.
  Command: dsmc restore budget
• Task: Restore a Pine folder named sent-mail-jun-1994 that is in your local folder collection
  Command: dsmc restore mail/sent-mail-jun-1994
• Task: Restore all files from your home directory that end with the characters .c
  Command: dsmc restore "*.c"
• Task: Restore all files from your home directory that end with the characters .c to a subdirectory called restored, which already exists.
  Command: dsmc restore "*.c" restored
  Attention: If the destination directory does not exist, you must specify the delimiter (/) as the last character of the destination directory (see the next example). Otherwise, ADSM assumes the destination is a file and will repeatedly overwrite each file restored to this destination file if the REPLACE option is set to YES (see the Command Options section for more info).
• Task: Restore all sent-mail files from your mail subdirectory to the subdirectory called restored, where the restored directory does not exist.
  Command: dsmc restore "mail/sent-mail*" restored/
• Task: Restore some files that were in your home directory but which names you don't remember. More than one day may have passed since the files were deleted.
  Use the PICK option to get a menu of backed-up files from which to pick the ones you'd like restored. Also, use the INACTIVE option to specify that you want ADSM to display both active and inactive versions of files (inactive files are files that have been deleted).
  Command: dsmc restore "*" -pick -inactive
  

Output:

+----------------------------------------------------------------------+
|                                                                      |
| ADSM Scrollable PICK Window - Restore                                |
|                                                                      |
|      #     Backup Date/Time  File Size A/I  File                     |
|          ------------------------------------------------------------|
|      1.  | 01/02/1993 21:17       7362  A  /home/userid/projb        |
|      2.  | 02/10/1993 12:19      83442  A  /home/userid/expense      |
|      3.  | 03/22/1993 04:07       8117  I  /home/userid/projx        |
|      4.  | 04/06/1993 12:12       4392  A  /home/userid/salaries     |
|      5.  | 04/07/1993 11:27     287009  A  /home/userid/projd        |
|      6.  | 04/08/1993 07:21        362  I  /home/userid/revenue      |
|          |                                                           |
|          |                                                           |
|          0---------10--------20--------30--------40--------50--------|
| <U>=Up   <D>=Down  <T>=Top  <B>=Bottom  <R#>=Right  <L#>=Left        |
| <G#>=Goto Line #  <#>=Toggle Entry  <+>=Select All  <->=Deselect All |
| <#:#+>=Select A Range <#:#->=Deselect A Range  <O>=Ok  <C>=Cancel    |
| pick>                                                                |
|                                                                      |
+----------------------------------------------------------------------+

When you use the PICK option with the dsmc RESTORE command, ADSM displays a list of files that match the file specification you entered. When you use the INACTIVE option along with the PICK option in the same command, ADSM displays inactive files as well as active files. If you wish to display active files only, just enter the PICK option with the command.

The functions available to manipulate the display and make selections appears at the bottom of the screen. For information on pick window functions please see the Pick Window Manipulation Functions section below. If it takes more than one screen to display the list, you can scroll forward and backward through the screens.

To make selections, at the pick> prompt, type the number or numbers that correspond to the files you want to restore. For example, to select the projx file and the revenue file for restore, enter the following:

pick> 3 6

ADSM marks your selections with an x as shown in the following illustration.

+----------------------------------------------------------------------+
|                                                                      |
| ADSM Scrollable PICK Window - Restore                                |
|                                                                      |
|      #     Backup Date/Time  File Size A/I  File                     |
|          ------------------------------------------------------------|
|      1.  | 01/02/1993 21:17       7362  A  /home/userid/projb        |
|      2.  | 02/10/1993 12:19      83442  A  /home/userid/expense      |
| x    3.  | 03/22/1993 04:07       8117  I  /home/userid/projx        |
|      4.  | 04/06/1993 12:12       4392  A  /home/userid/salaries     |
|      5.  | 04/07/1993 11:27     287009  A  /home/userid/projd        |
| x    6.  | 04/08/1993 07:21        362  I  /home/userid/revenue      |
|          |                                                           |
|          |                                                           |
|          |                                                           |
|          0---------10--------20--------30--------40--------50--------|
| <U>=Up   <D>=Down  <T>=Top  <B>=Bottom  <R#>=Right  <L#>=Left        |
| <G#>=Goto Line #  <#>=Toggle Entry  <+>=Select All  <->=Deselect All |
| <#:#+>=Select A Range <#:#->=Deselect A Range  <O>=Ok  <C>=Cancel    |
| pick>                                                                |
|                                                                      |
+----------------------------------------------------------------------+

To restore the files you selected, enter o at the pick> prompt. For example:

         pick> o

ADSM restores the files and displays the following:

Restore processing finished.

For information on pick window functions, please see the Pick Window Manipulation Functions section below.

The general syntax for dsmc is:

dsmc restore [options...] sourcefilespec [destinationfilespec]

This page contains a description of each variable part of the command, including several of the options you can choose.

sourcefilespec

The path and file name of the file you want to restore. You can use pattern-matching expressions to restore backup versions for multiple files. If you use wildcard characters, enclose the file specification in double quotation marks (").

destinationfilespec

The path and file name where you want to place the restored file or files. If you do not specify a destination, ADSM restores the files to the original source path.

Available options:

-FROMDate=date

The date from which you want ADSM to look for backups. ADSM does not restore files that were backed up before this date, although ADSM might restore directories that are older than this date.

You can use this option in conjunction with the TODATE option to create a time window for backups. This can help you restore a set of files to their state as of that window.

For example, to restore backup versions of files that were created during the last week of March 1995 for the files in the /home/jones directory, enter:

Restore -FROMDate=03/26/1995 -TODate=03/31/1995 /home/jones

The date must be in the format you select with the DATEFORMAT option. For example, the date for date format 1 is mm/dd/yyyy, which is the American English standard. If you include DATEFORMAT on the command, it must precede FROMDATE and TODATE.

The file selected for restore depends on the other options you use:

INACTIVE or LATEST

Restores the latest backup version in the fromdate-todate window, even if it is an inactive version. If a file does not have a backup within the window, the file is not restored.

Using the INACTIVE or LATEST option with FROMDATE and TODATE is likely to get the results you want.

-SUBDIR=YES

Restores the most recent backup of a directory up to the TODATE date. The FROMDATE option is ignored for directories.

If you also use the INACTIVE or LATEST option, then ADSM restores the most recent backup of the directory up to the TODATE date, even if the backup is inactive. If you do not use INACTIVE or LATEST, ADSM only restores active backup versions. If the directory you are restoring does not have an active backup before the TODATE date, ADSM recreates the directory instead of restoring it.

-FROMOwner=owner

Specifies an alternate owner from which you would like to restore files. To successfully use this option, the owner must have granted you access to the files. For example, to restore files from the /u/devel/proja directory that belongs to an owner identified as user_c, and place the restored files in a directory you own named /u/id/proja, you can enter the following:

REStore -FROMOwner=user_c /u/devel/proja /u/id/proja 

-FROMNode=node

Specifies an alternate node from which you would like to restore files that are owned by another user. If the owner of the files you want to restore is on another node, in addition to specifying the owner, you must also specify the owner's node. To successfully use this option, the owner must have granted you access to the files. For example, to restore files from the /u/devel/proja directory that belongs to an owner identified as user_c on another node identified as unix_2, and place the restored files in a directory you own named /u/id/proja, you can enter:

 REStore -FROMN=unix_2 -FROMO=user_c /u/devel/proja /u/id/proja

-FROMTime=time

Used in conjunction with the FROMDATE option to specify a beginning time on the specified date. For example, with FROMTIME and FROMDATE, you can request that ADSM restore only files that were backed up on or after 6:00 AM on June 1, 1995.

You can also use FROMTIME and FROMDATE with TOTIME and TODATE to request that ADSM restore only files that were backed up within a particular window of time. For example, you can request that ADSM restore only files that were backed up between 6:00 AM on June 1, 1995 and 11:59PM on June 15, 1995.

The time must be in the format you select with the TIMEFORMAT option. For example, if TIMEFORMAT is set to the default of 1, the time must be in the format 23:00:00. If you include the TIMEFORMAT option with the command, it must precede the FROMTIME and TOTIME options.

The default for FROMTIME is 00:00:00.

Note: If you want ADSM to use a value you specify for FROMTIME, you must also include FROMDATE with the command. Otherwise, ADSM ignores FROMTIME.

The actual files selected for restore are also determined by other options you use with the command. See the discussion on FROMDATE for more information.

-IFNewer

ADSM should replace an existing file with the backup if the backup is newer than the existing file. This option is ignored if the REPLACE option is NO.

Only active backups are considered unless you also use the INACTIVE or LATEST options.

-INActive

Specifies that you want ADSM to display both active and inactive versions of files when you also use the PICK option. See the last example in this section.

-LAtest

Restores the most recent backup version of a file. If you delete files from your workstation, then run an incremental backup, ADSM changes the status of the active backup versions of the deleted files to inactive. You can restore inactive backup versions of deleted files using this option.

The LATEST option tells ADSM to search both active and inactive files for the latest backup versions. If you do not specify LATEST, ADSM searches only for active files and does not restore any backup versions for deleted files.

For example, to restore the latest backup versions of files from the /u/devel/projecta directory, you can enter the following:

REStore -LAtest /u/devel/projecta

-PIck

Causes ADSM to display a list of active backup versions of your files that match the file specification you enter. From that list, you can select the backup versions to restore.

If you also use the INACTIVE option, ADSM displays both active and inactive versions. See the last example in this section.

-Quiet

Prevents messages from being displayed on your screen during processing. Note that certain error information is still displayed, and messages are posted to log files. If you are restoring a large number of files, and you do not want ADSM to display information about each file it restores, you can enter:

REStore -Quiet /u/devel

-REPlace=value

When restoring a file, determines what happens when a file of the same name as the backup already exists in the destination directory.

The possible values are:

Prompt

ADSM prompts you for your choice for overwriting an existing file. If the file is read-only, you cannot overwrite it. This is the default unless REPLACE is set in the client user options file.

No

ADSM does not overwrite existing files.

Yes

ADSM overwrites existing files, except for read-only files, without prompting you.

All

ADSM overwrites existing files, even if they are read-only, without prompting you.

-RESToremigstate=value

When restoring migrated and premigrated files, determines whether ADSM restores the files to a migrated state or a resident state. The possible values are:

Yes

ADSM restores migrated files and premigrated files to stub files on the local file system. Migrated files remain migrated, and premigrated files become migrated. This is the default.

No

ADSM restores backup versions of migrated and premigrated files to the local file system, and the files become resident.

-SErvername=servername

Specifies the name of the ADSM server from which you want to restore your files. If you have more than one server available to you, this option allows you to override the default server specified in the client user options file you use.

Note: You can use this option only when you issue the RESTORE command in batch mode.

For example, to restore a file named budget from a server identified as server_b, you can enter the following:

dsmc REStore -SErvername=server_b /u/devel/proja/budget

-SUbdir=value

Recursively descends directories, allowing you to either include or exclude files in subdirectories when restoring files. For example, to restore only the files in the /u/devel directory, you can enter:

REStore -SUbdir=no /u/devel

However, to restore the files in the /u/devel directory and all of its subdirectories, you can enter:

REStore -SUbdir=yes /u/devel

If a subdirectory is a mounted file system, ADSM will not include the files with the SUBDIR option.

Note: Be careful when using the SUBDIR option as it can impact ADSM performance. ADSM must search through your subdirectories, which can take extra time. For the best performance, use the SUBDIR option only when necessary.

-TAPEPrompt=value

Specifies whether you want ADSM to wait for a tape to be mounted when required for a restore process, or prompt you for your choice. If you set TAPEPROMPT to Yes, ADSM allows you to choose whether to wait for the tape to be mounted. If TAPEPROMPT is set to No (the default), ADSM waits for the tape to be mounted.

For example, you can enter:

REStore -TAPEPrompt=Yes /u/devel/proja/budget

-TODate=date

The date to which you want ADSM to look for backups. ADSM does not restore files that were backed up after this date. You can use this option in conjunction with the FROMDATE option to create a time window for backups. See the discussion of FROMDATE for more information on using TODATE.

-TOTime=time

Used in conjunction with the TODATE option to specify an ending time on the specified date. For example, with TOTIME and TODATE, you can request that ADSM restore only files that were backed up on or before 11:59 PM on June 15, 1995.

You can also use TOTIME and TODATE with FROMTIME and FROMDATE to request that ADSM restore only files that were backed up within a particular window of time. For example, you could request that ADSM restore only files that were backed up between 6:00 AM on June 1, 1995 and 11:59PM on June 15, 1995.

The time must be in the format you select with the TIMEFORMAT option. For example, if TIMEFORMAT is set to the default of 1, the time must be in the format 23:00:00. If you include the TIMEFORMAT option with the command, it must precede the FROMTIME and TOTIME options.

The default for TOTIME is 23:59:59.

Note: If you want ADSM to use a value you specify for TOTIME, you must also include TODATE with the command. Otherwise, ADSM ignores TOTIME.

The actual files selected for restore are also determined by other options you use with the command. See the discussion on FROMDATE for more information.

You can also use these options:

DATEFORMAT

NODENAME

NUMBERFORMAT

PASSWORD

TIMEFORMAT

VERBOSE

Table 11 provides an explanation of each Pick Window manipulation function.

+----------------------------------------------------------------------+
| Table 11. Pick Window Manipulation Functions                         |
+-----------------------+----------------------------------------------+
| Legend                | Description                                  |
+-----------------------+----------------------------------------------+
| <U>=Up                | Scrolls the window up one page of files.     |
+-----------------------+----------------------------------------------+
| <D>=Down              | Scrolls the window down one page of files.   |
+-----------------------+----------------------------------------------+
| <T>=Top               | Positions the window to the top of the list. |
+-----------------------+----------------------------------------------+
| <B>=Bottom            | Positions the window to the bottom of the    |
|                       | list.                                        |
+-----------------------+----------------------------------------------+
| <R#>=Right            | Positions the window # spaces to the right.  |
|                       | Default is 20 if only R is entered.          |
+-----------------------+----------------------------------------------+
| <L#>=Left             | Positions the window # spaces to the left.   |
|                       | Default is 20 if only L is entered.          |
+-----------------------+----------------------------------------------+
| <G#>=Goto Line #      | Positions the file # entered to top of       |
|                       | screen.                                      |
+-----------------------+----------------------------------------------+
| <#>=Toggle Entry      | Selects the file # entered or deselects it   |
|                       | if already selected.  More than one file #   |
|                       | can be entered by separating each with a     |
|                       | blank.                                       |
+-----------------------+----------------------------------------------+
| <+>=Select All        | Selects all files.                           |
+-----------------------+----------------------------------------------+
| <->=Deselect All      | Deselects all files.                         |
+-----------------------+----------------------------------------------+
| <#:#+>=Select a       | Selects a range of files.  First file #      |
| range.                | entered is beginning of range.  Second file  |
|                       | # entered is end of range.                   |
+-----------------------+----------------------------------------------+
| <#:#->=Deselect a     | Deselects a range of files.  First file #    |
| range.                | entered is beginning of range.  Second file  |
|                       | # entered is end of range.                   |
+-----------------------+----------------------------------------------+
| <O>=Ok                | Restores the files selected.                 |
+-----------------------+----------------------------------------------+
| <C>=Cancel            | Cancels the operation and returns to the     |
|                       | command prompt.                              |
+-----------------------+----------------------------------------------+

This document has been adapted from the original IBM ADSM documentation.