Spdsrstr - The SPD Server Table Restore Utility

Restore Description

Spdsrstr is a restore utility that uses a backup file to restore a specified set of SPD Server tables. Tables must meet restore requirements or the spdsrstr utility bypasses them. The spdsrstr utility can also provide a list of the tables in the backup file that are eligible for restoration.
  • When an incremental backup is restored, only the incremental changes to the observations are applied.
  • When a full backup is restored, the table is created with the attribute settings that existed when the full backup was performed, and then all of the rows are added.

Restore Requirements

Before you can use the spdsrstr utility to restore a table, the following must be true:
  • The table to be restored must be identical to the table that was backed up. That is, the name and create date must match the name and create date of the backed up table.
  • Incremental table restores must be performed in the same order as the incremental backups that were performed.
  • The table must not have been modified between the incremental restore dates, assuring that the table is returned to the exact state at time of backup.
  • The backup file (with any file extension) must be available.
If a table does not meet all of the criteria, spdsrstr prints a warning message to stdout, and does not restore the table. If spdsrstr is restoring multiple tables, it will restore only the tables that meet the restore criteria.

Restore Syntax

spdsrstr -d <dom> -h <host> {-f <fullfile> | -e <extfile>} [-hash]
 [-r <count>] [-a | -aforce] [-aonly] [-n] [-q] [-s <serv>]
 [-u <user>] [-p <passwrd>] [-proj <dir>] [table ...]

spdsrstr -v -d <dom> -h <host> {-f <fullfile> | -e <extfile>}
 [-s <serv>] [-u <user>] [-p <passwrd>] [-proj <dir>] [table ...]

spdsrstr -t {-f <fullfile> | -e <extfile>} [table...]

spdsrstr -help
spdsrstr
Restores all or selected tables from a backup file.
spdsrstr -t
Prints a table of contents for a backup file indicating when the backup file was created, and whether it is a full backup, and if so, the number of indexes. Further, it lists for each backed up table, the name, backup sequence, and the number of columns and records that are contained in the table.
spdsrstr -v
Verifies all or selected tables from a backup file can be restored, but does not do the actual restore.

Restore Options

-a
restore the backed up domain ACL (Access Control List) files if they do not already exist.
-aforce
restore the backed up domain ACL files if they do not exist or overwrite the current files if they do exist.
Note: This option should be used when restoring multiple files with the -e option to ensure that the domain ACL files are consistent with the last file restored.
-aonly
Only restore the domain ACL files, and nothing else.
-d
The SPD Server LIBNAME domain.
Note: The system that performs the restore must be able to access the physical path for the domain locally or through a network connection.
-e
<extfile> The backup filename prefix as specified in spdsbkup that can be used to restore ALL backup files in the directory with the name <extfile>_BK_ddmmmyyyy_hhmmss.0.0.0.spds. The backup files are restored in the order from oldest to newest as determined by the ddmmmyyyy_hhmmss component of the filename.
-f
<fullfile> The backup filename that contains the tables to restore.
Note: The filename must be the full filename (including its extension) created by the SPD Server backup utility.
-h
The host SPD Server to use for the backup.
-hash
Prints a hash sign (#) to stdout for each 256K compressed block that is read from the backup file.
-n
Does not create any indexes for a full restore of a table that was backed up with index information.
-p
The user password.
-proj <dir>
The domain project directory.
-q
Runs spdsrstr in quiet mode, which outputs only error and warning messages during a backup operation.
-r
Specifies the number of times spdsrstr will retry accessing tables that are not available during a restore operation because they were in query/update mode. Spdsrstr cannot restore a table if that table is in query/update mode when spdsrstr accesses it. Spdsrstr pauses five seconds and retries the table if it was in query/update mode. Spdsrstr will retry the file -r times before the restore fails. The default retry count for -r is one.
-s
The port number of the name server. If the port number is not specified, the default value is spdsname.
-u
The user name.
-v
Verify which tables in the backup file can be restored, but do not actually perform the restore operations.
[Table ...]
The list of tables to restore from the backup file. If no tables are specified, all tables in the file are restored.
Note: The list of tables must be the last option specified in your spdsrstr command.

Restore Return Values

When spdsrstr exits, it generates a return value. If the spdsrstr return value is 0, the utility was successful. If the spdsrstr return value is 1, one or more data sets could not be restored. In that case, examine your SAS log for WARNING information. If the spdsrstr return value is 2, a critical error caused an early process termination. Examine your SAS log for WARNING and ERROR information.

Restore User Messages

Successful Restore

If spdsrstr successfully restores a table, it writes some notes to stdout, unless the -q option is specified. The notes include useful information, such as the name of the table that was restored, the number of rows that were restored, and whether the restore that was performed was a full restore or an incremental restore.

Warning: Table Cannot Be Restored

If spdsrstr cannot restore a table, it will print an error message stating the reason for the failure. No tables are restored after the failure.

Failed Restore

If the spdsrstr utility detects a serious failure condition, it will halt and print an error message that states the reason for the failure.

Restore Usage Examples

Backup and Restore Utility Example Scenario

Here are some common SPD Server backup and restore utility examples. In our example scenario, the starting date for the backup cycle is Sunday, February 3, 2008. The weekly schedule includes

Example 1: Exclusive SPD Server Full and Incremental Backups

You can use SPD Server backup and restore utilities exclusively to perform full and incremental table backups and restores.
This example outlines the steps you use to perform a full backup of your domain once a week, and to perform incremental backups the rest of the week. The incremental backups will also fully back up any newly created tables.
  1. On Sunday, February 3, 2008 at 23:30, run the SPD Server backup utility to do a full backup of the domain: 
    spdsbkup -full -a -d test -h host -s serv -f backup
    The backup creates the backup data file backup_BK_05Feb2006_233000.0.0.0.spds and the backup table of contents file backup_TC_03Feb2008_233000. The backup file contains the full SPD Server backup for each table and any ACL files in the domain. The table of contents file contains information for each table that was backed up.
  2. Archive the SPD Server backup file and source in the table of contents file into a SAS table of contents table.
  3. On Monday night through Saturday night, use the SPD Server backup facility to perform incremental backups: 
    spdsbkup -a -d test -h host -s serv -f backup
    This statement performs incremental SPD Server backups of tables that were previously backed up, performs a full backup of tables that were created after the previous night's backup, and also backs up any ACL files that are in the domain.

Example 2: SPD Server Incremental/Full Backups and System Full Backups

You can use SPD Server utilities to perform incremental backups on data sets that you have previously archived, as well as to perform full backups on new data sets that have never been backed up. You can also back up your SPD Server data sets using a system utility from your native operating environment. Which one should you use? The advantage in using system full backups is that a system utility does not parse the data set, and therefore usually runs faster than the SPD Server utility when performing a full backup. For example, system utilities often write directly to tape storage media. In contrast, the SPD Server utility first writes backup data to a file on the hard drive, and then the backup file is usually backed up to tape.
This example outlines the steps you use to perform a full system backup of the domain "test" using operating system utilities once a week, then use SPD Server to perform a domain back up on the remaining nights.
  1. On Sunday, February 3, 2008 at 23:30, run the SPD Server list utility spdsls -l to produce a listing of the tables that belong to the domain "test" in preparation for a full backup. 
    spdsls -l -a <physical_path_of_domain>
    Run the operating system backup utility to perform a full backup of the domain tables and ACL files, and then archive the backup.
  2. On Monday, February 4, 2008 at 23:30, run the SPD Server backup utility spdsbkup and set the last full backup date to the previous night for the 'test' tables. Spdsbkup then performs an incremental backup of tables that have changed since the last full system backup, and performs a full backup of tables that were created after the last full system backup was performed. 
    spdsbkup -d test -h host -s serv -t 02/04/08:23:30:00 -f backup
    The utility creates the backup data file backup_BK_04Feb2008_233000.0.0.0.spds and a backup table of contents file backup_TC_04Feb2008_233000.
    The backup file contains incremental changes for tables that were modified after 23:30:00 on February 3, 2008, and full backups of tables created after 23:30:00 on February 4, 2008. Only the tables that were modified or created since the last full backup date are included in the backup file. The table of contents file contains information for each table that was either incrementally or fully backed up.
  3. Archive the SPD Server backup file and source in the table of contents file into a SAS table of contents table.
  4. On Tuesday night through Saturday night, use the SPD Server backup facility to do incremental backups of previously backed up tables and full backups of the newly created tables: 
    spdsbkup -d test -h host -s serv -f backup
    There is no last full backup date specified for the remaining week's incremental backups. The SPD Server backup utility performs incremental backups of tables that were previously backed up and full backups of tables that were created since the previous night's backup. Although the same filename prefix is specified each night, spdsbkup saves each night's backup to a different file, appending the date/time of the backup to the filename.
  5. Archive the incremental data file and source in the table of contents file into a SAS table of contents table.

Example 3: Restoring a Single SPD Server Table

Use the following steps to restore a table that was accidentally deleted from the domain "test" on Friday, February 8, 2008.
  1. If the table was backed up fully by the operating system backup utility, use the system restore utility to restore the table. (Restore the table to its last full backup image, taken on February 3, 2008.) If the table was backed up fully by the SPD Server backup utility, skip this step.
  2. Run a SAS query on the backup table of contents table bkup.toc.
    select bk_file from foo.bkup_toc
where domain = "test"
and table = "results"
and dttime >= '03Feb2008:23:30:00'd;
    The query results indicate which SPD Server backup files are required to restore the table to its last full backup state.
  3. Restore the archived SPD Server backup files and any extensions that are required to restore the table.
  4. Run spdsrstr on each sequential SPD Server backup file to restore the table. The order runs from the oldest backup date to the most recent backup date. Our example table was backed up fully using the SPD Server backup utility on Sunday, February 3, 2008. The table was then backed up incrementally on Tuesday, February 5, and Thursday, February 7. Thus, the order of the statements required to restore the table are 
    spdsrstr -d test -h host -s serv -f backup_BK_03Feb2008_233000.0.0.0.spds results

spdsrstr -d test -h host-s serv -f backup_BK_05Feb2008_233000.0.0.0.spds results

spdsrstr -d test -h host -s serv -f backup_BK_07Feb2008_233000.0.0.0.spds results
    Alternatively, you could use the -e option of spdsrstr and restore all of the files with one single command:
    spdsrstr -d test -h hostname -s serv -e backup results
    Note: When you restore a single table, you do not need to restore the ACL files, because they were not deleted.

Example 4: Restoring an SPD Server Domain

Use the following steps to restore an SPD Server domain named "test" that was lost due to a system media failure that occurred on Friday, February 15, 2008.
  1. If the domain was backed up fully using the system backup utility, use the system restore utility to restore domain "test" to its state at the last full backup date of February 10, 2008. If the domain was backed up fully using the SPD Server utility, then skip this step.
  2. Use SAS to run a query on the backup table of contents table bkup_toc.
    select bk_file from foo.bkup_toc
where domain = "test"
and dttime >= '10FEB2008:23:30:00'd;
    The query results identify which SPD Server backup files are required to restore the domain.
  3. Restore the archived SPD Server backup files required to restore the domain.
  4. Use the SPD Server restore utility to restore domain "test":
    spdsrstr -aforce -d test -h host -s serv -e backup
    The -aforce option will cause the domain ACLs to be updated for each restore file, resulting in the latest backup of the ACLs being restored.
Copyright © SAS Institute Inc. All rights reserved.