RST

RST (Restore)

RST Command syntax diagram

Purpose

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 in the File systems and management category of the Information Center.
Restrictions: This command is shipped with public *EXCLUDE authority.
For detailed restrictions on using this command to restore objects in libraries or to restore document library objects, see the Backup and recovery topic in the Information Center.

Required Parameters

DEV

Specifies the path name of the device from which the objects are restored. For more information on specifying path names, refer to path names.
'save-file-path-name': Specify the path name of the save file used to restore the objects.
'diskette-device-path-name': Specify the path name of the diskette device used to restore the objects.
'optical-device-path-name': Specify the path name of the optical device used to restore the objects.
'tape-media-library-device-path-name': Specify the path name of the tape media library device used to restore the objects.
'tape-device-path-name': Specify the path name of the tape device used to restore the objects. A maximum of four tape devices can be specified.

Optional Parameters

OBJ

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 path names.
Additional information about name patterns is in the Integrated file system topic in the File systems and management category of the Information Center.
Element 1: Object Name
The first element specifies the path names of the objects saved on the media. Directory abbreviations (for example, the current directory) are expanded with their current values, not with the values they had at the time of the save operation.
'*': The objects in the current directory are restored.
'object-path-name': Specify an object path name or a pattern that can match many names. If the default is specified in element 3, each component in the path name must exist with the exception of the last component. The object name in the last component is restored as new if it doesn't exist.
Element 2: Include or Omit
The second element 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.

*INCLUDE: The objects that match the object name pattern are restored, unless overridden by an *OMIT specification.
*OMIT: The objects that match the object name pattern are not restored. This overrides an *INCLUDE specification and is intended to be used to omit a subset of a previously selected pattern.
Element 3: New Path Name
The third element specifies the new path name of the object.
*SAME: The objects are to be restored with the same names they had when they were saved.
'new-path-name': Specify the path name with which to restore the object. If a pattern is specified in element 1, the new name must be an existing directory into which to restore any objects that match the pattern. If an object name is specified in element 1, each component in the new path name must exist with the exception of the last component. If the object described in the last component doesn't exist, it will be restored as new.

SUBTREE

Specifies whether directory subtrees are included in the restore operation.
*ALL: The entire subtree of each directory that matches the object name pattern is processed. The subtree includes all subdirectories and the objects within those subdirectories.
*DIR: The objects in the first level of each directory that matches the object name pattern are processed. The subdirectories of each matching directory are included, but the objects in the subdirectories are not included.
*NONE: No subtrees are included in the restore operation. If a directory matches the object name pattern specified, the objects in the directory are included. If the directory has subdirectories, neither the subdirectories nor the objects in the subdirectories are included.
*OBJ: Only the objects that match the object name pattern are processed. If the object name pattern specifies a directory, objects in the directory are not included.
*STG: The objects that match the object name pattern are processed along with the storage for related objects. Objects can only be restored using this value if they were saved with SUBTREE(*STG).

SYSTEM

Specifies whether to process objects that exist on the local system or remote systems.
*LCL: Only local objects are processed.
*RMT: Only remote objects are processed.
*ALL: Both local and remote objects are processed.

SAVDATE

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. If this parameter is not specified, the restored version of the objects is the first version found.
The date must be specified in the job date format. If separators, specified by the system value QDATSEP, are used, the value must be enclosed in apostrophes.

SAVTIME

Specifies the time the objects were saved. If this parameter is not specified, the version of the objects to be restored is the first version found on the volume.
The time is specified in 24-hour format with or without a time separator as follows:

With a time separator, specify a string of 5 or 8 digits, where the time separator for the job separates the hours, minutes, and seconds. If you issue this command from the command line, the string must be enclosed in apostrophes. If a time separator other than the separator specified for your job is used, this command fails.

Without a time separator, specify a string of 4 or 6 digits (hhmm or hhmmss) where hh = hours, mm = minutes, and ss = seconds. Valid values for hh range from 00 through 23. Valid values for mm and ss range from 00 through 59.

Notes

This parameter is valid only if the SAVDATE parameter is specified.

This parameter is ignored when the SEQNBR parameter is specified.

OPTION

Specifies whether to restore objects that already exist on the system or objects that do not already exist on the system.
*ALL: All of the specified objects are restored, whether they already exist on the system or not.
*NEW: Objects are restored only if they do not already exist on the system.
*OLD: Objects are restored only if they already exist on the system.

ALWOBJDIF

Specifies whether differences are allowed between the saved object and the restored object. The differences include:

Ownership: The owner of an object on the system is different than the owner of an object from the save operation.

Primary Group: The primary group of an object on the system is different than the primary group of an object from the save operation.

File level identifier: The file and/or member level identifier of a physical file on the save media is different than the file and/or member level identifier of the physical file on the system.

Authorization list linking: The system on which an object with an authorization list is being restored is different from the system on which it was saved.

*NONE: No differences are allowed between the saved object and the restored object. If the owner is different, the object is not restored. If the system is different for an object with an authorization list, the object is restored, but the object is not linked to its authorization list. If the primary group is different, the object is not restored. If the file and/or member level identifier of a physical file are different, the physical file data is not restored.
*ALL: All differences are allowed between the saved object and the restored object. If the owner is different, the object is restored with the owner of the system on which it is restored. If the system is different for an object with an authorization list, the object is restored and linked to its authorization list. If the primary group is different, the object is restored with the primary group of the object on the system. If the file and/or member level identifiers are different, the file or member on the system will be renamed and the file or members is restored from the save media.
*OWNER: The object owner can be different. If an object already exists on the system with a different owner than the saved object, the object is restored with the owner of the object on the system. If owner differences are not allowed, the object is not restored.
*PGP: The primary group can be different. If an object already exists on the system with a different primary group than the saved object, the object is restored with the primary group of the object on the system.
*AUTL: The system of an object with an authorization list can be different. The new object, which is being restored to a system that is different from which it was saved, is restored and linked to its authorization list. If the system of an object with an authorization list cannot be different, the object is restored but not linked to an authorization list.

FRCOBJCVN

Specifies whether to convert user objects to the format required for use in the current version of the operating system when the objects are restored.

Notes

This parameter applies only to user objects of the *MODULE, *PGM, *SRVPGM, and *SQLPKG object types.

An object must be observable (have the required observable information) in order to be converted.

If an object needs to be converted (because it is formatted for an earlier version of the operating system), but is not converted during this restore operation, the object is automatically converted the first time it is used.

Element 1: Force Conversion
*SYSVAL: The objects are converted based on the value of the QFRCCVNRST system value.

Note: If this value is specified and the system value QFRCCVNRST has a value of "1," the restore operation proceeds as if FRCOBJCVN(*YES *RQD) is specified. If QFRCCVNRST has a value of "0", the restore operation proceeds as if FRCOBJCVN(*NO) is specified.

*NO: The objects are not converted during the restore operation.
*YES: The objects are converted during the restore operation.

Note: Specifying this value increases the time of the restore operation, but avoids the need to convert the objects when they are first used.

Element 2: Objects to Convert
*RQD: The objects are converted only if they require conversion to be used by the current operating system. If the objects are not observable, the objects are restored but are not converted.
*ALL: All objects are converted regardless of their current format. Even the objects are in the current format, they are converted again. However, if the objects are not observable, the objects are not restored.

OBJID

Specifies whether the object ID of the restored object will be the object ID of the object from the save media, the object ID of the object that exists on the system prior to the restore, or a new object ID generated by the system if the object does not exist on the system prior to the restore.
*SAVED: The restored object will have the object ID it had when it was saved.
*SYS: The restored object may have a new object ID generated by the system. If the object is being restored as a new object, a new object ID will be given to the restored object. If an object with the same name as the object from the media already exists on the system, the object ID of the restored object will be the same as the object ID of the object on the system before the restore.

VOL

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. More information on this parameter is in commonly used parameters.

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.

*MOUNTED: The objects are restored from the volumes placed in the device specified on the DEV parameter. For a media library device, the volume to be used is the next cartridge in the category mounted by the Set Tape Category (SETTAPCGY) command.

Note: This value cannot be specified when using an optical media library device.

volume-identifier: Specify the identifiers of one or more volumes used to restore the objects.

LABEL

Specifies the file identifier of the media to be used for the restore operation.
*SEARCH: The file label for which to search is determined by the system.
diskette-file-identifier: Specify the identifier (up to 17 characters) of the diskette file used for the restore operation.
tape-file-identifier: Specify the identifier (up to 17 characters) of the tape file used for the restore operation.

SEQNBR

Specifies the tape file sequence number to be used.
*SEARCH: The tape volume is searched for the next file that contains any of the specified objects.
sequence-number: Specify the sequence number of the file. Valid values range from 1 through 16777215.

ENDOPT

Specifies the operation that is automatically performed 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 on the DEV parameter. For optical devices, *UNLOAD is the only special value supported, *REWIND and *LEAVE will be ignored.

*REWIND: The tape is automatically rewound, but not unloaded, after the operation has ended.
*LEAVE: The tape does not rewind or unload after the operation ends. It remains at the current position on the tape drive.
*UNLOAD: The tape is automatically rewound and unloaded after the operation ends. Some optical devices will eject the volume after the operation ends.

OPTFILE

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 path names.
'*': The system searches the root directory of the optical volume for the default name generated by the corresponding save operation.
'optical-directory-path-name/*': The system searches the specified directory of the optical volume for the default name generated by the corresponding save operation.
'optical-file-path-name': Specify the path name of the optical file.

OUTPUT

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 path names.
*NONE: No output is created.
*PRINT: Output information about the restore will be printed.
'stream-file-path-name': Specify the path name of the existing stream file to which the output of the command is directed.
'user-space-path-name': Specify the path name of the existing user space to which the output of the command is directed.

INFTYPE

Specifies the type of information which is directed to the spooled file, stream file, or user space.
*ALL: The file will contain information about the command, an entry for each directory, an entry for each object that was successfully restored, and an entry for each object that was not successfully restored.
*ERR: The file will contain information about the command, an entry for each directory, and an entry for each object that was not successfully restored.
*SUMMARY: The file will contain information about the command, and an entry for each directory.

Examples for RST
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 Everything Saved from the Home Directory
RST DEV('/QSYS.LIB/TAP01.DEVD') OBJ('~')

This command restores everything saved in the user's home directory from the tape device named TAP01.
Example 5: 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 6: 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 7: 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 8: 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 9: Using Symbolic Links
Assume the current directory contains the following symbolic links.

DevLink = /QSYS.LIB/TAP01.DEVD

DirLink = /SomeDirectory

FileLink = /SomeDirectory/SomeFile

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/*'))

Error messages for RST
*ESCAPE Messages

CPFA0DB

Object name not a QSYS object.

CPFA0DC

Object name not a QDLS object.

CPF370C

Not authorized to ALWOBJDIF parameter.

CPF3707

Save file &1 in &2 contains no data.

CPF3727

Duplicate device &1 specified on device name list.

CPF3738

Device &1 used for save or restore is damaged.

CPF3743

File cannot be restored, displayed, or listed.

CPF3768

Device &1 not valid for command.

CPF3782

File &1 in &2 not a save file.

CPF3794

Save or restore operation ended unsuccessfully.

CPF380D

Save or restore of entire system completed unsuccessfully.

CPF3805

Objects from save file &1 in &2 not restored.

CPF381E

Not authorized to ALWOBJDIF parameter.

CPF3812

Save file &1 in &2 in use.

CPF382A

Specified parameter not valid for QDLS file system.

CPF382B

Parameters not valid with multiple file systems.

CPF382C

OBJ parameter value not valid for QSYS file system.

CPF382D

Specified parameter not valid for QSYS file system.

CPF382F

OBJ parameter value not valid for QDLS file system.

CPF3823

No objects saved or restored.

CPF3826

*INCLUDE object required on OBJ parameter.

CPF3828

Error occurred while attempting to use &1.

CPF383A

Save or restore ended unsuccessfully.

CPF383B

End of file &1.

CPF383C

Storage limit exceeded for user profile &1.

CPF383D

Cannot use &1.

CPF383E

&1 objects restored. &2 objects not restored.

CPF3833

Specified value on DEV parameter not valid.

CPF3834

Too many values specified on the DEV parameter.

CPF3835

Tape devices do not support same densities.

CPF3839

&1 objects restored. &2 not restored.

CPF384A

Volume identifier &1 not valid.

CPF384B

Optical file specified not valid.

CPF384C

Error occurred during CCSID conversion.

CPF384F

&2 &1 not restored to library &3.

CPF3840

Specified file for restore operation not found.

CPF5729

Not able to allocate object &1.

CPF9802

Not authorized to object &2 in &3.

CPF9825

Not authorized to device &1.

OPT1498

Volume name list exhausted on device &1.

OPT1502

Attempted to process past the end of a multi-volume set.

OPT1605

Media or device error occurred.