Unattended Restore Using ^DBREST
Unattended Restore Using ^DBREST
The Caché restore utility, ^DBREST, provides a non-interactive execution option using external entry points.
If you are restoring mirrored databases, review Mirrored Database Considerations in this section before you perform an unattended restore.
You can write a script to implement unattended restores by calling one of these two entry points:
-
EXTALL^DBREST — Restores all databases from the backup device (the unattended equivalent to the procedure described in Restore All Databases Using ^DBREST). The syntax to use the EXTALL entry point of the ^DBREST utility is as follows:
EXTALL^DBREST(quietmode,allowupd,inpdev,dirlist,jrnopt,jrnfile,jdirglo)
Note:If the target directory exists but the CACHE.DAT file does not, EXTALL^DBREST restores the CACHE.DAT file.
-
EXTSELCT^DBREST — Restores selected files from the backup device, or restores to a target directory that is different from the source directory (the unattended equivalent to the procedures described in Restore Selected or Renamed Databases Using ^DBREST). The syntax to use the EXTSELCT entry point of the ^DBREST utility is as follows:
EXTSELCT^DBREST(quietmode,allowupd,inpdev,dirlist,jrnopt,jrnfile,jdirglo)
Both entry points are functions, which return the status of the call. All arguments are input only. The following table describes the input arguments used for both functions except where indicated.
| Argument | Description |
|---|---|
| allowupd | Indicates whether or not to allow updates during the restore process:
1 — allow updates during the restore process 0 — do not allow updates |
| dirlist | Name of file containing a list of directories to restore. One record for each directory to be restored has to be present. Ignored for the EXTALL entry point. See Directory List File Requirements. |
| inpdev | Input device that contains the backup. If this device is a tape device, the utility prompts you to specify the device for the next volume. |
| jdirglo | Only used when jrnopt is 3. This is the name of the file containing selection criteria for directories and globals for the journal restore. See Directory and Global Selection Criteria. |
| jrnfile | Journal file. If null, the utility uses the current file, which is stored in the ^%SYS("JOURNAL“,”CURRENT") global. |
| jrnopt | Options to restore the journal:
1 — All directories for which you just restored the backup 2 — All directories in the journal 3 — Selected directories and globals specified by the jdirglo argument 4 — No directories |
| quietmode | A value indicates the operation is in quiet (non-interactive) mode; must be a non-null value for this external call, typically 1. |
The following return codes are possible from calling these functions:
| Return Code | Description |
|---|---|
| 3 | No errors; successful completion |
| -1 | Cannot open input device (device to restore from) |
| -2 | Volume label does not match label in backup history |
| -3 | Backup/Restore already in progress |
| -4 | Invalid device for reading selection criteria (for selective restore of directories) |
| -5 | Invalid journal restore option |
| -6 | Invalid journal file or file for selection criteria for journal restore cannot be opened |
Directory List File Requirements
Requirements of the file indicated by dirlist:
-
Contains one record for each directory to restore
-
Separate each field with a comma (,).
-
Format of each record is SourceDir,TargetDir,CreateDir; where:
Argument Description SourceDir Name of the directory to restore. TargetDir Name of the directory to which to restore; omit if restoring to same as source directory. CreateDir Whether or not to create the target directory if it does not exist. Y — create the target directory
N — do not create target directory
For example, assuming you have created a text file (RestoreList.txt) in the C:\Backup\ directory that contains the string:
C:\intersystems\cache\mgr\user\,C:\intersystems\cache\mgr\,Y
you could execute the following routine in the %SYS namespace to restore the database from C:\intersystems\cache\mgr\user\ to C:\intersystems\cache\mgr\:
set SourceDir = "C:\intersystems\cache\mgr\user\"
set BackupDir = "C:\Backup\"
set BackupListFile="C:\Backup\RestoreList.txt"
do EXTSELCT^DBREST(1,0,BackupDir_"back1.cbk",BackupListFile,4,"","")
Directory and Global Selection Criteria
Requirements of the file indicated by jdirglo:
-
Contains one record for each directory that you want to restore.
-
Separate each field with a comma (,).
-
Format of each record is DirName, RestAll, Globals; where:
| Argument | Description |
|---|---|
| DirName | Name of the directory on which you want to restore the journal. |
| Globals | A list of globals separated by commas for journal restore. Only used if RestAll is N. If the list of globals is large, you can enter the remaining global names on the next line but you must specify the directory name again followed by N and then the list of globals. |
| RestAll | Whether or not to restore journal entries for all globals in the directory; not case-sensitive and required.
Y — restore journal on all globals in this directory N — specify globals for journal restore in globals list |
Examples of different records:
DUA0:[TEST1],Y
DUA1:[TEST2],N,GLO1,GLO2,GLO3
DUA1:[TEST2],N,GLO4,GLO5,GLO6
DUA1:[TEST3],n
The last record could also be completely omitted if you do not want to restore the journal for that directory.
