Restore Object (RST)

Where allowed to run: All environments (*ALL)
Threadsafe: No

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 information in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter.

Restrictions:

This command is shipped with no public authority (*EXCLUDE).
For detailed restrictions on using this command to restore objects by using name patterns in the root directory, to restore objects in libraries, or to restore document library objects, see the Backup and Recovery book, SC41-5304.

Top

Parameters

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
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
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

Top

Device (DEV)

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 information in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter.

This is a required parameter.

'save-file-path-name'

Specify the path name of the save file 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 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. If a virtual tape device is used, it must be the only device specified.

'media-definition-path-name'

Specify the path name of the media definition (*MEDDFN) object that identifies the devices and media used to restore the data.

For information about creating a media definition, see the Create Media Definition API in the System API Reference information in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter.

For information about using a media definition, see the Backup and Recovery book, SC41-5304 and the Backup Your Server topic topic in the System API Reference information in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter.

Top

Objects (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 "Object naming rules" in the CL concepts and reference topic in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter.

Additional information about object name patterns is in the Integrated file system information in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter.

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.

'*': The objects in the current directory are restored.
path-name: Specify an object path name or a pattern that can match many names. If *SAME is specified for the third element of this parameter, 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

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 to be restored, unless overridden by an *OMIT specification.
*OMIT: The objects that match the object name pattern are not to be restored. This overrides an *INCLUDE specification and is intended to be used to omit a subset of a previously selected pattern.

Element 3: New object name

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.
path-name: Specify the path name with which to restore the object. If a pattern is specified in the first element, the new path name must be the 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.

Top

Name pattern (PATTERN)

Specifies a pattern to be used to include or omit objects. A maximum of 300 patterns can be specified.

Element 1: Pattern

'*': All objects which qualify for the operation are included or omitted.
character-value: Specify an object name or a pattern that can match many names.

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.

*INCLUDE: Only objects which are included by the OBJ parameter and match the PATTERN parameter are included in the restore, unless overridden by an *OMIT specification.
*OMIT: All objects which are included by the OBJ parameter are included in the restore except those objects which match the PATTERN parameter. This overrides an *INCLUDE specification and is intended to be used to omit a subset of a previously selected pattern.

Top

Directory subtree (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 will be 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).

Top

Output (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.

*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.

Top

Create parent directories (CRTPRNDIR)

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.

*NO: Parent directories will not be created if they do not exist. Diagnostic message CPD375B will be sent and the object will not be restored.
*YES: The restore will create parent directories if they do not exist. The directories created by the restore will have *EXCLUDE public authority and will be owned by the user profile specified for the Parent directory owner (PRNDIROWN) parameter. The other parent directory attributes will be set using the shipped default values for the Create Directory (CRTDIR) command parameters.

Top

Parent directory owner (PRNDIROWN)

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.

*PARENT: The owner of a parent directory being created by the restore will be the same as the owner of the directory it is being created into. For example, if object '/a/b/c/file1' is being restored and directory '/a' exists but the '/b' and '/b/c' directories do not exist, the '/b' and '/b/c' directories are created with the same owner as the '/a' directory.
name: Specify the name of a user profile to be the owner of any parent directories that are created by the restore.

Top

Volume identifier (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.

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

*MOUNTED: The objects are restored from the volumes placed in the device specified for the Device (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.

Other values (up to 75 repetitions)

character-value: Specify the identifiers of one or more volumes in the order in which they are placed in a device and used to restore the data.

Top

Label (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.
character-value: Specify the identifier (up to 17 characters) of the tape file to be used for the restore operation.

Top

Sequence number (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.
1-16777215: Specify the sequence number of the file.

Top

End of media option (ENDOPT)

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.

*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.

Top

Optical file (OPTFILE)

Specifies the path name of the optical file that is used for the restore operation, beginning with the root directory of the volume.

*: 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.

Top

Type of output information (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.

Top

System (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.

Top

Date when saved (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.

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.

date: Specify the date the objects to be restored were saved.

Top

Time when saved (SAVTIME)

Specifies the time the objects were saved.

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.

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:

This parameter is valid only if the SAVDATE parameter is specified.
This parameter is ignored when the SEQNBR parameter is specified.

time: Specify the time the objects to be restored were saved.

Top

Option (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.

Top

Allow object differences (ALWOBJDIF)

Specifies whether differences are allowed between the saved objects and the restored objects.

Notes:

You must have all object (*ALLOBJ) special authority to specify any value other than *NONE for this parameter.
If differences are found, the final message for the restore operation is an escape message rather than the normal completion message.

The types of differences include:

Authorization list: The saved object had an authorization list, and either the object exists on the system but does not have the same authorization list, or the object does not exist and it is being restored to a different system than the save system.
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.

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.

Single values

*NONE: None of the differences listed above are allowed on the restore operation. See the description of each individual value to determine how differences are handled.

*ALL: All of the differences listed above are allowed on the restore operation. See the description of each individual value to determine how differences are handled.

Other values (up to 3 repetitions)

*AUTL: Authorization list differences are 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 restored with the authorization list of the existing object. 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 and it is linked to the authorization list. If the authorization list does not exist, the public authority is set to *EXCLUDE.
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.

*OWNER: Ownership differences are allowed. 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 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.

*PGP: Primary group differences are allowed. 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.
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

Force object conversion (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 have creation data (either observable or unobservable) 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.

Single values

*SYSVAL: The objects are converted based on the value of the QFRCCVNRST system value.
*NO: The objects are not converted during the restore operation.
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

*YES

The objects are converted during the restore operation.

Notes:

If FRCOBJCVN(*YES *RQD) is specified, then the QFRCCVNRST system value must have a value of "0", "1", or "2". FRCOBJCVN(*YES *RQD) will override a QFRCCVNRST value of "0" or "1". If FRCOBJCVN(*YES *ALL) is specfied, then QFRCCVNRST can have any valid value and FRCOBJCVN(*YES *ALL) overrides the QFRCCVNRST system value.
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 do not have all creation data (either observable or unobservable), the objects cannot be converted and will not be restored.
*ALL: All objects are converted regardless of their current format, including objects already in the current format. However, if the objects do not have all creation data (either observable or unobservable), the objects cannot be converted and will not be restored.

Top

Object ID (OBJID)

This parameter has been disabled and is no longer valid.

Top

Examples

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.

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

Top

Error messages

*ESCAPE Messages

CPFA0DB: Object not a QSYS.LIB object. Object is &1.
CPFA0DC: Object not a QDLS object. Object is &1.
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.
CPF38A5: Error on the PATTERN parameter.
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.

Top