Restore Object (RST)

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

Restrictions:

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

*

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.

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:

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

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

  1. You must have all object (*ALLOBJ) special authority to specify any value other than *NONE for this parameter.

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

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:

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

  2. An object must have creation data (either observable or unobservable) to be converted.

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

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:

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

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

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