| Where allowed to run: All environments (*ALL) Threadsafe: No |
Parameters Examples Error messages |
The Restore (RST) command restores a copy of one or more objects that can be used in the integrated file system.
For more information about integrated file system commands, see the Integrated file system topic collection in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.
Restrictions:
| Top |
| Keyword | Description | Choices | Notes |
|---|---|---|---|
| DEV | Device | Values (up to 4 repetitions): Path name | Required, Positional 1 |
| OBJ | Objects | Values (up to 300 repetitions): Element list | Optional, Positional 2 |
| Element 1: Name | Path name, * | ||
| Element 2: Include or omit | *INCLUDE, *OMIT | ||
| Element 3: New object name | Path name, *SAME | ||
| PATTERN | Name pattern | Values (up to 300 repetitions): Element list | Optional |
| Element 1: Pattern | Character value, * | ||
| Element 2: Include or omit | *INCLUDE, *OMIT | ||
| SUBTREE | Directory subtree | *ALL, *DIR, *NONE, *OBJ, *STG | Optional |
| OUTPUT | Output | Path name, *NONE, *PRINT | Optional |
| CRTPRNDIR | Create parent directories | *NO, *YES | Optional |
| PRNDIROWN | Parent directory owner | Simple name, *PARENT | Optional |
| RBDMFS | Rebuild mounted file system | *NONE, *UDFS | Optional |
| VOL | Volume identifier | Single values: *MOUNTED Other values (up to 75 repetitions): Character value |
Optional |
| LABEL | Label | Character value, *SEARCH | Optional |
| SEQNBR | Sequence number | 1-16777215, *SEARCH | Optional |
| POSITION | Starting position in file | Hexadecimal value, *FIRST | Optional |
| ENDOPT | End of media option | *REWIND, *LEAVE, *UNLOAD | Optional |
| OPTFILE | Optical file | Path name, * | Optional |
| INFTYPE | Type of output information | *ALL, *ERR, *SUMMARY | Optional |
| SYSTEM | System | *ALL, *LCL, *RMT | Optional |
| SAVDATE | Date when saved | Date | Optional |
| SAVTIME | Time when saved | Time | Optional |
| OPTION | Option | *ALL, *NEW, *OLD | Optional |
| ALWOBJDIF | Allow object differences | Single values: *NONE, *ALL Other values (up to 3 repetitions): *AUTL, *OWNER, *PGP |
Optional |
| FRCOBJCVN | Force object conversion | Single values: *SYSVAL, *NO Other values: Element list |
Optional |
| Element 1: Convert during restore | *YES | ||
| Element 2: Objects to convert | *RQD, *ALL | ||
| OBJID | Object ID | *SAVED, *SYS | Optional |
| PVTAUT | Private authorities | *NO, *YES | Optional |
| Top |
Specifies the device from which the objects are restored.
For more information on specifying device path names, refer to "Specifying the device name" in the Backup and recovery topic collection in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.
This is a required parameter.
Note: This parameter is Unicode-enabled. See "Unicode support in CL" in the CL topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/ for additional information.
For information about creating a media definition, see the Create Media Definition API in the APIs topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.
For information about using a media definition, see the Recovering your system book, SC41-5304 and the Back up your server topic in the Backup and recovery topic collection in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.
| Top |
Specifies the path name of the object to restore. You can specify a pattern for this path name. A maximum of 300 path names can be specified.
For more information on specifying path names, refer to "Object naming rules" in the CL topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.
Additional information about object name patterns is in the Integrated file system topic collection in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.
Note: This parameter is Unicode-enabled. See "Unicode support in CL" in the CL topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/ for additional information.
Element 1: Name
Specifies the objects saved on the media. Directory abbreviations (for example, the current directory) are expanded with their current values, not the values they had at the time of the save operation.
Element 2: Include or omit
Specifies whether names that match the pattern should be included or omitted from the operation. Note that in determining whether a name matches a pattern, relative name patterns are always treated as relative to the current working directory.
Note: The SUBTREE parameter determines whether the subtrees are included or omitted.
Element 3: New object name
Specifies the new path name of the object.
| Top |
Specifies a pattern to be used to include or omit objects. A maximum of 300 patterns can be specified.
Note: This parameter is Unicode-enabled. See "Unicode support in CL" in the CL topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/ for additional information.
Element 1: Pattern
Element 2: Include or omit
Specifies whether names that match the pattern should be included or omitted from the operation.
Note: The SUBTREE parameter determines whether the subtrees are included or omitted.
| Top |
Specifies whether directory subtrees are included in the restore operation.
| Top |
Specifies whether a list of information about the restored objects is created. The information can be directed to a spooled file, a stream file, or a user space.
A stream file or user space is specified as a path name.
For more information on specifying path names, refer to "Object naming rules" in the CL topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.
Note: This parameter is Unicode-enabled. See "Unicode support in CL" in the CL topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/ for additional information.
| Top |
Specifies whether parent directories of objects being restored should be created if they do not exist. For example, if object '/a/b/c/file1' is being restored then directories '/a', '/a/b' and '/a/b/c' must exist. This parameter only applies to "root" (/), QOpenSys and user-defined file systems, and will be ignored for all other file systems.
| Top |
Specifies the name of an existing user profile that will own parent directories created by the restore. This parameter only applies to "root" (/), QOpenSys and user-defined file systems, and will be ignored for all other file systems.
Note: If a value is specified for this parameter, *YES must be specified for the Create parent directories (CRTPRNDIR) parameter.
| Top |
Specifies which mounted file systems should be rebuilt during the restore.
Note: You must have save system (*SAVSYS) or all object (*ALLOBJ) special authority to specify a value other than *NONE for this parameter.
If a user-defined file system is created during the restore, the attributes will be set based on the saved user-defined file system including any user-defined file system specific attributes such as 'Case sensitivity' or 'Default file format'. If the user-defined file system exists before the restore, no attributes will be changed.
If there is an error creating or mounting a user-defined file system, none of the objects that were saved from the mounted user-defined file system will be restored.
Note: If it does not exist before the restore, the directory that is being mounted over will be created with attributes and authorities copied from the directory being restored into. This could cause problems when the user-defined file system is unmounted and then remounted, if the authorities are not sufficient to allow the mount to occur.
| Top |
Specifies the volume identifiers of the media or the cartridge identifiers of tapes in a tape media library device, from which the objects are being restored. The volumes must be in the same order as they were when the data was saved. The volume that contains the beginning of the file to be restored should be placed in the device.
Note: The version of the object that is restored is the first version found in the specified location, unless a specific version is identified by the values on the SAVDATE and SAVTIME parameters.
Single values
Note: This value cannot be specified when using an optical media library device.
Other values (up to 75 repetitions)
| Top |
Specifies the file identifier of the media to be used for the restore operation.
| Top |
Specifies the tape file sequence number to be used.
| Top |
Specifies the position in the tape file at which to start searching for the data to restore. Specifying a value may improve the performance of the restore operation if you only want to restore data that is far from the beginning of the tape file.
| Top |
Specifies the operation that is automatically done on the tape or optical volume after the restore operation ends. If more than one volume is used, this parameter applies only to the last volume used; all other volumes are unloaded when the end of the volume is reached.
Note: This parameter is valid only if a tape or optical device name is specified for the DEV parameter. For optical devices, *UNLOAD is the only special value supported, *REWIND and *LEAVE will be ignored.
| Top |
Specifies the path name of the optical file that is used for the restore operation, beginning with the root directory of the volume.
For more information on specifying path names, refer to "Object naming rules" in the CL topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.
| Top |
Specifies the type of information which is directed to the spooled file, stream file, or user space.
| Top |
Specifies whether to process objects that exist on the local system or remote systems.
| Top |
Specifies the date the objects were saved. If the most recently saved version is not the one being restored, or if multiple saved versions reside on the media, specify the date that identifies which version of the objects to restore.
The date must be specified in the job date format. If the separators that are specified by the system value QDATSEP are used, the value must be enclosed in apostrophes.
Note: This parameter is valid only if a volume identifier or the value *MOUNTED is specified for the VOL parameter, or if *SAVF is specified for the DEV parameter. If this parameter is valid and is not specified, the restored version of the objects is the first version found.
| Top |
Specifies the time the objects were saved.
If a volume identifier or the value *MOUNTED is specified for the VOL parameter, and the SAVTIME parameter is not specified, the version of the objects to be restored is the first version found on the volume.
Notes:
| Top |
Specifies whether to restore objects that already exist on the system or objects that do not already exist on the system.
| Top |
Specifies whether differences are allowed between the saved objects and the restored objects.
Notes:
The types of differences include:
Note: This parameter has no effect when the saved object did not have an authorization list. If the object exists, it is restored with the authorization list of the existing object. If it does not exist, it is restored with no authorization list.
Single values
Other values (up to 3 repetitions)
If this value is not specified, authorization list differences are not allowed. If the saved object had an authorization list and the object exists on the system but does not have the same authorization list, the object is not restored. If the saved object had an authorization list and the object does not exist and it is being restored to a different system than the save system, the object is restored, but it is not linked to the authorization list, and the public authority is set to *EXCLUDE.
If this value is not specified, ownership differences are not allowed. If an object already exists on the system with a different owner than the saved object, the object is not restored.
If this value is not specified, primary group differences are not allowed. If an object already exists on the system with a different primary group than the saved object, the object is not restored.
| Top |
Specifies whether to convert user objects to the format required for use in the current version of the operating system, or to be compatible with the current machine, when the objects are restored.
Notes:
Single values
Note: If FRCOBJCVN(*NO) is specified, then the QFRCCVNRST system value must have a value of either "0" or "1".
Element 1: Convert during restore
Notes:
Element 2: Objects to convert
| Top |
| Top |
Specifies whether to restore private authorities with the objects that are restored.
Note: You must have all object (*ALLOBJ) special authority to specify this value.
| Top |
Example 1: Restoring All Data Not in Libraries or Document Library Objects
RST DEV('/QSYS.LIB/TAP01.DEVD')
OBJ(('/*') ('/QSYS.LIB' *OMIT) ('/QDLS' *OMIT))
This command restores all objects that are not in libraries and are not document library objects.
Example 2: Restoring a Library
RST DEV('/QSYS.LIB/TAP01.DEVD') OBJ('/QSYS.LIB/A.LIB')
This command restores the library A from the tape device named TAP01.
Example 3: Restoring All Files in MYLIB
RST DEV('/QSYS.LIB/TAP01.DEVD')
OBJ('/QSYS.LIB/MYLIB.LIB/*.FILE')
This command restores all files in the library MYLIB from the tape device named TAP01.
Example 4: Restoring All Objects in the Current Directory
RST DEV('/QSYS.LIB/TAP01.DEVD')
This command uses the default value on the OBJ parameter to restore all objects in the current directory and its subdirectories.
RST DEV('/QSYS.LIB/TAP01.DEVD') OBJ('*') SUBTREE(*NONE)
This command restores all objects in the current directory but not in subdirectories.
RST DEV('/QSYS.LIB/TAP01.DEVD') OBJ('.') SUBTREE(*DIR)
This command restores the current directory and all of the objects in the current directory. It does not restore objects in the subdirectories of the current directory.
Example 5: Omitting Objects
RST DEV('/QSYS.LIB/TAP01.DEVD')
OBJ(('*') ('**.BACKUP' *OMIT) ('**.TEMP' *OMIT))
This command restores all objects in the current directory except those with extensions of .BACKUP and .TEMP (the entire subtrees of directories with these extensions are omitted).
Example 6: Renaming or Moving Objects
RST DEV('/QSYS.LIB/TAP01.DEVD')
OBJ(('MYDIR/X.PGM' *INCLUDE 'YOURDIR/Y.PGM'))
This command restores the program X from the directory MYDIR as the program Y in the directory YOURDIR.
RST DEV('/QSYS.LIB/TAP01.DEVD')
OBJ(('MYDIR/*.PGM' *INCLUDE 'YOURDIR')) SUBTREE(*OBJ)
This command restores all programs in the directory MYDIR to the directory YOURDIR.
Example 7: Restoring From a Save File
RST DEV('/QSYS.LIB/MYLIB.LIB/MYSAVF.FILE') OBJ(MYDIR)
This command restores the directory MYDIR from a save file named MYSAVF in a library named MYLIB.
Example 8: Using Symbolic Links
Assume the current directory contains the following symbolic links.
Symbolic links can be used to specify the device and output file. When symbolic links are restored, only the names of the associated objects are restored, not the content of the associated objects. A symbolic link to a directory can be used to restore objects in the directory. Additional information about symbolic link is in the Integrated file system topic in the File systems and management category of the Information Center. To restore the names associated with DirLink and FileLink from device TAP01:
RST DEV('DevLink') OBJ(('DirLink') ('FileLink'))
To restore the objects in SomeDirectory from device TAP01:
RST DEV('DevLink') OBJ(('DirLink/*'))
| Top |
*ESCAPE Messages
| Top |