RSTOBJ (Restore Object)

RSTOBJ Command syntax diagram

 

Purpose

The Restore Object (RSTOBJ) command restores to the system a single object, or a group of objects, in a single library, that were saved on diskette, tape, optical volume, or in a save file by using a single command. The types of objects that can be restored by this command are listed in the OBJTYPE parameter. They can be saved either as separate objects or as part of the library save operation. The RSTOBJ command restores the object description and contents of each object specified in the command.

For job queues, output queues, user-defined message queues, logical files, and data queues, only the object descriptions are restored; the contents of those objects are not restored. However, logical file access paths can be saved by a save command with ACCPTH(*YES) specified; if this is done, the access paths can be restored. More information on restoring access paths is in the Database Programming topic in the Information Center.

The command can be used to restore the objects even if the object storage was freed by the Save Object (SAVOBJ) command or Save Library (SAVLIB) command, or if the objects were deleted by the associated delete command for that object type. If the storage was not freed, each object is restored in the same area of storage that it previously occupied. If the version of the object being restored is larger than the version in the system (for example, data records that were deleted from the system still exist in the saved version of a file), the additional storage needed for the object is acquired. If the saved version of the object is smaller (for example, data records that are added to the system), the space that was acquired for the object remains assigned to that object and available for use by that object.

If logical file access paths were saved (ACCPTH(*YES) was specified when the objects were saved), the access paths are restored if (1) all based-on physical files are also being restored by the same restore command, (2) the logical file is also being restored by the same restore command, or the logical file already exists on the system (the same file exists, not a re-created version), and (3) MAINT(*IMMED or *DLY) is in effect for the logical file if it still exists on the system.

If the storage was freed, the system finds the storage space needed to store the contents (only the data portion) of each file, module, program, service program, journal receiver, and Structured Query Language (SQL) package. If the objects do not exist on the system because they were deleted or they are being restored in a different system, the system must find the storage to store everything (the description and the data portion) about each unknown object.

The user profile of the system default owner (QDFTOWN) becomes the default owner of objects restored in the system whose owner is not known to the system.

If an object already exists in the library to which it is restored, the public and private authorities of the existing object are kept. If the object does not exist in the library, all public authorities are restored, but any private authorities must be granted again. For an existing output queue object that is actively spooling during the restore operation, or a data queue that already exists in the library, none of the attributes are restored, and a diagnostic message is issued.

If an object is being restored over an existing object on the system, the object auditing value of the existing object is kept. If the object is being restored as new to the system, the object auditing value is restored from the media.

Attention:

Do not use the Restore Object (RSTOBJ) command to restore licensed programs into library QSYS. Unpredictable results can occur.

 

Restrictions

  1. This command is shipped with public *EXCLUDE authority.

  2. The user must have use authority for the Create Save File (CRTSAVF) command when restoring a save file that does not currently exist on the system.

  3. When saving or restoring to an existing database file using the OUTFILE parameter, the user must have execute authority to the output file library.

  4. With the exception of overrides for the restore listing file and database files specified on the OUTFILE parameter, this command ignores all file overrides that are currently in effect for the job.

  5. To use this command, the user must have the special authority *SAVSYS, specified in the user profile (SPCAUT parameter), or the following:

    • Add and execute authority for the specified library and save file library.

    • Object existence authority for, or be the owner of, each object specified if the object already exists in the library on the system. Object existence authority and use authority are required for message queue objects. If the object does not already exist in the library on the system, the user must have add authority for the user profiles that own each object being restored.

    • If VOL(*SAVVOL) is specified, use authority to the saved-from library.

  6. The RSTOBJ command does not restore the library's data dictionary or its associated database files. To do this, the RSTLIB command must be used.

  7. The user must have use authority for the save file to restore from the save file. In addition, the user must have use authority for the device description when restoring from tape, diskette, or optical device.

  8. When using a media definition, the user must have *USE authority to the media definition and *EXECUTE authority to the media definition library.

  9. If this command is used to restore a program, the copy of that program that is currently in the system must not be running while the program is being restored. If this occurs, the running program will not be restored.

  10. Objects saved by separate commands must also be restored by separate commands. If a single command is used, some of the objects are not restored.

  11. If the user domain object user space (*USRSPC), user index (*USRIDX), or user queue (*USRQ) is restored to a library that is not permitted in the system value QALWUSRDMN (allow user domain objects in libraries), the object is converted to the system domain.

 

Required Parameters

OBJ
Specifies the names of one or more objects to restore. The objects specified are restored from the first file that meets the search criteria and contains any of the objects. If a tape or diskette contains multiple files for the same library, specify the tape file sequence number or the diskette file label to ensure that all of the correct objects are restored.

If the file does not contain all of the objects specified, diagnostic messages are issued for the objects not found. The completion message contains a count of objects restored and objects not restored.

If the OBJTYPE parameter is not specified when the command is run, all of the object types listed in the description of the OBJTYPE parameter are restored, if they are in the specified library on the media or in the save file and have the specified names.

*ALL: All the objects saved from the specified library are restored, depending on the values specified for the OBJTYPE and OPTION parameters.

generic*-object-name: Specify the generic name of the object. A generic name is a character string of one or more characters followed by an asterisk (*); for example, ABC*. The asterisk (*) substitutes for any valid characters. A generic name specifies all objects with names that begin with the generic prefix, for which the user has authority. If an asterisk is not included with the generic (prefix) name, the system assumes it to be the complete object name. For more information on the use of generic functions, refer to generic object names.

object-name: Specify one or more names of specific objects to restore. Both generic names and specific names can be specified in the same command.

SAVLIB
Specifies the name of the library from which the objects were saved. If RSTLIB is not specified, this is also the name of the library to which the objects are restored.

DEV
Specifies the name of the device used to restore the objects. The device name must already be known on the system by a device description.

*SAVF: The restore operation is done using the save file specified on the save file (SAVF) parameter.

*MEDDFN: The restore operation is done using the devices and media identified in the media definition specified by the Media Definition (MEDDFN) parameter.

diskette-device-name: Specify the name of the diskette device used to restore objects.

optical-device-name: Specify the name of the optical device used for the restore operation.

tape-media-library-device-name: Specify the name of the tape media library device used for the restore operation.

tape-device-name: Specify the names of one or more tape devices used for the restore operation. If more than one tape device is specified, they are used serially in the order in which they are specified. Using more than one tape device permits one tape volume to be rewound and unloaded while another tape device processes the next tape volume. To use more than one device in parallel, a media definition must be specified.

 

Optional Parameters

OBJTYPE
Specifies the types of OS/400 system objects that are restored. More information on this parameter is in commonly used parameters.

*ALL: All object types that are specified by name and that were saved from the specified library are restored. If *ALL is also specified for the OBJ parameter, then all objects saved for that library are restored.

object-type: Specify the value for each of the types of objects that are restored (such as command (*CMD), file (*FILE), or program (*PGM)). This value can be repeated; the maximum repetitions varies depending on the environment.

The object types that can be restored also can be saved and restored by the Save Library (SAVLIB), Save Change Object (SAVCHGOBJ), Save Object (SAVOBJ), Restore Library (RSTLIB), and Restore Licensed Program (RSTLICPGM) commands. Data dictionaries (*DTADCT) are only restored with the RSTLIB command. Other object types can be saved only by the Save System (SAVSYS) command and restored by the OS/400 system restore operation, or saved by the Save Document Library Object (SAVDLO) command and restored by the Restore Document Library Object (RSTDLO) command.

Note: *CFGL object types can be restored using the RSTOBJ command only from objects saved on releases prior to V2R2M0. *CFGL object types saved on V2R2M0 and newer releases are restored using the Restore Configuration (RSTCFG) command.

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 objects that is restored is the first version found in the specified location, unless a specific version is identified 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.

*SAVVOL: The system, using the save/restore history information, determines which volumes contain the most recently saved version of the objects.

Note: If this is a restore from an optical device, only the first 6 characters of the volume name are available. If the volume name of the optical media exceeds 6 characters, the volume may not be found. You should specify the complete volume or file name on the command instead of using VOL(*SAVVOL) when the name of the optical media exceeds 6 characters.

When *SAVVOL is specified, the following operational characteristics and restrictions apply:

  • If the characteristics of the device specified in the DEV parameter do not match the device and location of the most recently saved version of the library, an error message is sent to the user, and the function is ended.

  • If the wrong volume is placed in a device in the location specified by the command, a message is sent to the system operator that identifies the first volume that must be placed in the device before the objects can be restored.

  • When OBJ(*ALL) and OBJTYPE(*ALL) is specified, the objects are considered in the order they would appear in a display produced by the Display Library (DSPLIB) command. The object names and types specified in the RSTOBJ command are used to determine which file of saved objects is used in the restore operation. One file is produced for each SAVLIB or SAVOBJ command run. The file chosen is the one in which the first considered object was last saved. Objects that were not saved in the file chosen to be processed, or that were more recently saved, are not restored; an error message is sent to the user for each unrestored object.

  • If *SAVVOL is specified, the SAVDATE and SAVTIME parameters cannot be specified.

  • If *SAVVOL is specified and the RSTLIB value is equal to the SAVLIB value, OPTION(*NEW) cannot be specified.

  • If *SAVVOL is specified, SEQNBR(*SEARCH) and LABEL(*SAVLIB) must be specified.

volume-identifier: Specify the identifiers of one or more volumes in the order in which they are placed in a device and used to restore the objects.

SEQNBR
Specifies, only when tape is used, the sequence number used for the restore operation.

*SEARCH: The volume on a tape device is searched for a data file with an identifier that is a match for the SAVLIB parameter value; when a match is found, the object is restored. If the last operation on the device specifies ENDOPT(*LEAVE) (that is, the tape is positioned at the location where the last operation ended), the file search starts with the first data file beyond the current tape position. If ENDOPT(*LEAVE) was not used for the last operation (or if the tape was manually rewound after an ENDOPT(*LEAVE) operation), the search starts with the first data file on the volume.

sequence-number: Specify the sequence number of the file. Valid values range from 1 through 16777215.

LABEL
Specifies the name that identifies the data file on the tape or diskette used for the restore operation. This label must have been specified on the save command.

*SAVLIB: The file label is the name of the library specified on the SAVLIB parameter.

data-file-identifier: Specify the data file identifier (up to 17 characters) of the data file used for the restore operation. This option is valid only for a single library restore.

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.

SAVF
Specifies the qualified name of the save file that contains the save data for the objects that are restored.

The name of the save file can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

save-file-name: Specify the name of the save file from which to perform the restore.

MEDDFN
Specifies the qualified name of the media definition that identifies the devices and media used to restore the data. For information about creating and using a media definition, see the Set up saves to multiple devices article in the Information Center.

Note: If a media definition is specified, the VOL, SEQNBR, SAVF, and OPTFILE parameters cannot be specified. The volume identifiers and sequence numbers are specified in the media definition.

The name of the media definition can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

media-definition-name: Specify the name of the media definition.

OPTION
Specifies how to handle restoring each object.

*ALL: All the objects in the saved library are restored to the library. All objects in the saved library are restored to the library on the system. Objects in the saved library replace the objects in the library on the system. Saved objects not on the system are added to the library on the system. Objects in the system library but not in the saved library remain in the library.

*NEW: Only the objects in the saved library that do not exist in the current version of the library in the system are added to the library. Only objects not known to the library in the system are restored; known objects are not restored. This option adds objects that were deleted after they were saved or that are new to this library. If any saved objects have a current version in the library in the system, they are not restored; an informational message is sent for each object, but the restore operation continues.

*OLD: Only objects in the library that have a saved version are restored; the current version of each object is replaced by the saved version. Only objects known to the library are restored. If any saved objects are no longer part of the current version of the library, they are not added to the library; an informational message is sent for each object, but the restore operation continues.

*FREE: The saved objects are restored only if they exist in the library in the system with their space freed. The saved version of each object is restored in the system in its previously freed space. This option restores objects that had their space freed when they were saved. If any saved objects are no longer part of the current version of the library, or if the space is not free for any object, the object is not restored and an informational message is sent for each object. The restore operation continues and all of the freed objects are correctly restored.

FILEMBR
Specifies the database file members to restore. This parameter is made up of two parts: the file name and the member name. This parameter cannot be specified if MBROPT(*MATCH) is specified.

 

Notes

  1. Each database file specified on the FILEMBR parameter must also be specified on the OBJ parameter by either its complete name, a generic name, or *ALL.

  2. The OBJTYPE parameter value must be *ALL, or it must include the *FILE value.

  3. Generic names are not valid for the database file name, but are allowed for the member name.

  4. Duplicate file names are not allowed.

Element 1: Database File Names

*ALL: The member list following this value applies to all files specified on the OBJ parameter.

database-file-name: Specify the name of the database file that contains the members to be restored. Up to 50 of the file/member combinations can be specified for a single command.

Element 2: Member Names

*ALL: All members are restored from the specified file.

*NONE: No members are restored from the specified file. Only the file description is restored.

generic*-member-name: Specify the generic name of the members to be restored from the specified file. A generic name is a character string of one or more characters followed by an asterisk (*); for example, ABC*. The asterisk substitutes for any valid characters. A generic name specifies all objects with names that begin with the generic prefix, for which the user has authority. If an asterisk is not included with the generic (prefix) name, the system assumes it to be the complete object name. For more information on the use of generic functions, refer to generic object names.

member-name: Specify the name of the member to be restored from the specified file.

 

Notes

  1. If the nongeneric member names are specified, all specified members must exist in the file in order for any part of the file to be restored.

  2. If generic member names are specified, the file is not restored if it does not contain any members that match the generic names. For example, if the user specifies PAY* as a generic member name, and the system is unable to find any members whose names start with PAY, the file is not restored. If no files specified by the FILEMBR parameter are restored because no members with the specific generic name can be found, a diagnostic message is sent, the restore operation ends, and an escape message is sent specifying the number of files not restored. If at least one of the files processed for the FILEMBR parameter is restored, the diagnostic message is not sent, and the number of files not restored is shown on the final completion message.

  3. The members are first checked by using the MBROPT parameter. If a match is found, the members are checked against the list of the FILEMBR parameter.

MBROPT
Specifies, for database files currently on the system, which file members are restored.

If MBROPT(*MATCH) is used, the member list in the saved file must match, member for member, the current version on the system.

Note: Before restoring a file, the system verifies that the file and member creation dates of the known system objects match the creation dates of the objects to be restored. If this check fails, the file is not restored.

*MATCH: The saved members are restored if the lists of the files where they reside match, member for member, the lists of the current system version.

*ALL: All members in the saved file are restored.

*NEW: Only new members (members not existing on the system) are restored.

*OLD: Only members already existing on the system are restored.

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 volume, specify the date that identifies which version of the objects to restore. 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. If a volume identifier or VOL(*MOUNTED) is specified, but SAVDATE is not, the restored version of the objects is the first version found on the volume. This parameter is valid only if a volume identifier or VOL(*MOUNTED) is specified, or if a save file (SAVF parameter) is specified. Specify the date when the objects were saved.

SAVTIME
Specifies the time that the objects were saved.

The time can be specified with or without a time separator:

  • Without a time separator, specify a string of 4 or 6 digits (hhmm or hhmmss) where hh = hours, mm = minutes, and ss = seconds.

  • With a time separator, specify a string of 5 or 8 digits where the time separator specified for your job is used to separate the hours, minutes, and seconds. If you enter 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.

If a volume identifier or *MOUNTED is specified on the VOL parameter, but this parameter is not specified, the version of the objects to be restored is the first version found on the volume. This parameter is ignored when the SEQNBR parameter is specified.

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

ALWOBJDIF
Specifies whether certain differences encountered during a restore operation are allowed. The differences include:

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

  • The primary group of the object on the system is different than the primary group of the object from the save operation.

  • File creation date: The file creation date of the database file on the system does not match the creation date of the file that was saved.

  • File level identifier: The file and/or member 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.

  • Member creation date: The file creation date of the database file on the system does not match the creation date of the member that was saved. The member creation date on the system does not match the creation date from the save operation.

  • Validation value verification: The validation value created at the time an object was created does not match the validation value created during the restore operation of an object on a system with a QSECURITY level of 40 or higher.

  • Authorization list linking: The object is being restored to a system different from the one on which it was saved.

 

Notes

  1. The user of this parameter must have *ALLOBJ special authority.

  2. If *ALL is specified, *MATCH cannot be specified on the MBROPT parameter.

*NONE: None of the differences described above are allowed on the restore operation. For validation value verification failure cases, the object is restored but ownership is transferred to QDFTOWN and all authorities are revoked. For authorization list cases, the object is restored, but the object is not linked to the authorization list, and public authority is set to *EXCLUDE. For all other cases, a diagnostic message is sent for the object, and the object is not restored.

*ALL: All of the differences listed above are allowed for the restore operation. An informational message is sent, except for valid value verification and authorization list linking cases, and the object is restored. The following facts must be noted:

  • If the owners of the object do not match, the object is restored, but the ownership and authorities it had before the restore operation are retained.

  • If the primary groups of the object do not match, the object is restored, but the primary group it had before the restore operation is retained.

  • Either the file itself or members of the file are restored based on the following facts:

    1. If there is a file level mismatch and ALWOBJDIF(*ALL) has been specified, the existing version of the file is renamed and the saved version of the file is restored.

    2. If there is a member level mismatch, the existing version of the member is renamed and the saved version of the member is restored.

  • Validation value verification:

    1. For programs with no validation value stored on the media (in reference to program data saved on an OS/400 system prior to version 1, release 3.0), the program is restored and the system does not attempt to recreate it. Nothing is logged in the security journal and no informational messages are sent.

    2. For programs that do have a validation value stored on the media and the system fails to recreate the program, the original version of the program is restored and an entry is logged in the security journal and job log.

  • The informational message causes a diagnostic message to be sent indicating that security or integrity changes occurred during the restore operation. This results in sending an escape message for the restore operation.

  • If the user is restoring objects to a system different from the one on which they were saved and the objects are secured by an authorization list, specifying *ALL automatically links the objects to the authorization list again. If the authorization list does not exist on the new system, a message that includes the name of the missing list is issued and the public authority is set to *EXCLUDE.

*FILELVL: The file and/or member level identifier of a physical file can be different. If a database physical file already exists on the system with a different file and/or member level identifier than the saved physical file, then an attempt will be made to restore the physical file data. The file and/or member level identifiers of the physical file on the system remain unchanged. Objects other than physical files will be restored as if ALWOBJDIF(*NONE) is specified.

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 be observable (have the required observable information) in order 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.

Element 1: Force Conversion

*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 system value QFRCCVNRST must have a value of either "0," or "1,".>

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

 

Notes

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

  2. 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 specified, then QFRCCVNRST can have any valid value and FRCOBJCVN(*YES *ALL) overrides the QFRCCVNRST system value.>

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 if the objects are in the current format, they are converted again. However, if the objects are not observable, the objects are not restored.

RSTLIB
Specifies whether the objects are restored to a different library or to the same library where they were saved.

*SAVLIB: The objects are restored to the same library from which they were saved.

library-name: Specify the name of the library to which the saved objects are restored.

RSTASPDEV
Specifies the name of the auxiliary storage pool (ASP) device to which the data is restored.

*SAVASPDEV: The data is restored to the same auxiliary storage pool from which it was saved.

auxiliary-storage-pool-device-name: Specify the name of the independent ASP to which you want to restore the data. End of change

RSTASP
Specifies whether the objects are restored to the same auxiliary storage pool (ASP) from which they were saved or to the system ASP (ASP number 1) or to a basic user ASP (ASP numbers 2-32). >This parameter affects only object types, journals, journal receivers, save files, and libraries. All other object types are restored to the ASP of the library unless the library is in a user ASP and the object type is not one of the valid user ASP object types. A list of the valid user ASP object types and additional information about user ASPs are in the Backup and recovery topic in the Information Center.

Journals, journal receivers, and save files can be restored to a user ASP with the library in the system ASP if the objects do not already exist in a different ASP, and if the ASP to which they are being restored contains no libraries.

User ASPs that contain one or more libraries cannot contain valid ASP object types, journals, journal receivers, and save files in libraries on the system ASP.

*SAVASP: The objects are restored to the same auxiliary storage pools from which they were saved.

auxiliary-storage-pool-number: Specify the ASP number. When the specified ASP is 1, the objects are restored to the system ASP, otherwise the objects are restored to the basic user ASP specified. Start of changeTo restore libraries and objects to an independent ASP, use the RSTASPDEV parameter. >

Note: System libraries (for example, QSYS, QUSRSYS, and QDOC) must not be created in or restored to user ASPs. Doing so can cause unpredictable results.

OUTPUT
Specifies whether a listing that shows information about the status of the object is created and directed to an output file. The listing shows the restore information and shows all objects, restored, not restored, and excluded. Information about each object's security is listed for the restored objects. More information on this parameter is in commonly used parameters.

*NONE: No output is created.

*PRINT: The output is printed with the job's spooled output.

*OUTFILE: The output is directed to the database file specified on the OUTFILE parameter.

Note: You must specify the database file name on the OUTFILE parameter when OUTPUT(*OUTFILE) is specified.

OUTFILE
Specifies the qualified name of the database file to which the information about the object is directed when *OUTFILE is specified on the OUTPUT parameter. If the file does not exist, this command creates a database file in the specified library. If a new file is created, the system uses QASRRSTO in QSYS with the format name QSRRST as a model.

The name of the database file can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

database-file-name: Specify the name of the database file to which the output of the command is directed.

OUTMBR
Specifies the name of the database file member to which the output is directed when OUTPUT(*OUTFILE) is specified.

Element 1: Member to Receive Output

*FIRST: The first member in the file receives the output. If OUTMBR(*FIRST) is specified and the member does not exist, the system creates a member with the name of the file specified on the OUTFILE parameter.

member-name: Specify the name of the file member that receives the output. If OUTMBR(member-name) is specified and the member does not exist, the system creates it. If the member exists, the user can add records to the end of the existing member or clear the existing member and add the records.

Element 2: Operation to Perform on Member

*REPLACE: The existing records in the specified database file member are replaced by the new records.

*ADD: The new records are added to the existing information in the specified database file member.

INFTYPE
Specifies the type of information directed to the database file. This parameter is valid only when OUTPUT(*OUTFILE) is specified.

*OBJ: The list contains an entry for each object requested to be restored.

*MBR: The list contains an entry for each object or, for database files, each member requested to be restored.

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.

Examples for RSTOBJ

Example 1: Restoring Most Recently Saved Version 

RSTOBJ   OBJ(PAYROLL)  SAVLIB(LIBX)  DEV(TAP01)
  OBJTYPE(*PGM) VOL(*SAVVOL)

This command restores to LIBX the program named PAYROLL that was saved from LIBX. The tape drive named TAP01 is used to restore the most recently saved version of the program.

Example 2: Specifying Save Date and Time 

RSTOBJ   OBJ(PAY*)  SAVLIB(LIBX)  DEV(DKT01)  VOL(ABCD)
  OPTION(*OLD)  SAVDATE(102292)
  SAVTIME(143000)  RSTLIB(LIBY)

All objects whose names start with PAY and that were saved from the library named LIBX on diskette volume ABCD at 14:30:00 on 10/22/92 are restored to LIBY. Volume ABCD must be put on the diskette device named DKT01. Because OPTION(*OLD) is specified, the only objects restored are those having the same object name and type both in LIBY on the system and in LIBX on diskette.

Example 3: Adding a New Program to the QGPL Library 

RSTOBJ   OBJ(NEWPROG)  SAVLIB(QGPL)  DEV(DKT01)
  OBJTYPE(*PGM)  VOL(PGMS)  OPTION(*NEW)

A new program named NEWPROG is added to the general purpose library, QGPL. It is restored from a volume labeled PGMS that is inserted in the diskette device named DKT01.

Example 4: Printing An Output List 

RSTOBJ   OBJ(*ALL)  SAVLIB(LIB)  DEV(TAP01)  OBJTYPE(*PGM)
  VOL(SVOL)  SEQNBR(2)  SAVDATE(082392)
  SAVTIME(143000)  OUTPUT(*PRINT)

All programs that were saved from the library named LIB that exist in the saved version on the tape volume named SVOL, sequence number 2, saved at 14:30:00 on 08/23/92, are restored to the library named LIB. An output list of all objects restored as well as objects not restored is provided.

Example 5: Restoring Journal Receivers 

RSTOBJ OBJ(*ALL) SAVLIB(BACKUP) DEV(*SAVF)
  OBJTYPE(*JRNRCV)  SAVF(SAVEJ) RSTASP(3)

All journal receivers that were saved from the library named BACKUP into the save file named SAVEJ are restored to the library named BACKUP. The journal receivers are restored to basic user ASP 3 (unless they already exist in the library named BACKUP and are in a different ASP or ASP 3 contains a library).

Error messages for RSTOBJ

*ESCAPE Messages

CPFACDB
M36 &1 in library &2 is active. Request not allowed.
CPFACDE
Unconverted M36 exists. Restore not allowed.
CPF370C
Not authorized to ALWOBJDIF parameter.
CPF3705
&2 &1 in &3 not journaled.
CPF3706
&2 &1 not restored to library &3.
CPF3707
Save file &1 in &2 contains no data.
CPF3709
Tape devices do not support same densities.
CPF3727
Duplicate device &1 specified on device name list.
CPF3728
Device &1 specified with other devices.
CPF3730
Not authorized to &2 &1 in library &3.
CPF3731
Cannot use &2 &1 in library &3.
CPF3733
&2 &1 in &3 previously damaged.
CPF3738
Device &1 used for save or restore is damaged.
CPF3739
Database file &1 member in &3 damaged.
CPF374C
No objects restored to ASP &2.
CPF3743
File cannot be restored, displayed, or listed.
CPF3748
Object information for library &1 damaged.
CPF3767
Device &1 not found.
CPF3768
Device &1 not valid for command.
CPF3769
File found on media not save/restore file.
CPF3770
No objects saved or restored for library &1.
CPF3773
&1 objects restored. &2 not restored to &4.
CPF3780
Specified file for library &1 not found.
CPF3781
Library &1 not found.
CPF3782
File &1 in &2 not a save file.
CPF3783
Cannot determine VOL(*SAVVOL) location. No objects restored.
CPF3784
Restore device specified in the DEV parameter does not match VOL(*SAVVOL) device.
CPF3791
While processing &2 &1 in &3, encountered end of file &4.
CPF3793
Machine storage limit reached.
CPF3794
Save or restore operation ended unsuccessfully.
CPF3796
Storage limit exceeded for user profile &4.
CPF3805
Objects from save file &1 in &2 not restored.
CPF3807
Data decompression error for save file &1 in &2.
CPF3812
Save file &1 in &2 in use.
CPF384F
&2 &1 not restored to library &3.
CPF3867
Contents of FILEMBR parameter not correct.
CPF3868
FILEMBR specified but OBJTYPE must be *ALL or *FILE.
CPF3871
No objects saved or restored; &3 objects not included.
CPF3872
Not all objects restored from library &3 to library &4.
CPF5729
Not able to allocate object &1.
CPF9809
Library &1 cannot be accessed.
CPF9812
File &1 in library &2 not found.
CPF9814
Device &1 not found.
CPF9820
Not authorized to use library &1.
CPF9822
Not authorized to file &1 in library &2.
CPF9825
Not authorized to device &1.
CPF9829
Auxiliary storage pool &1 not found.
CPFB8ED
Device description &1 not correct for operation.End of change
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.