RSTCFG (Restore Configuration)
Purpose
The Restore Configuration (RSTCFG) command restores to the system a configuration object that was saved by the Save System (SAVSYS) or Save Configuration (SAVCFG) command. The types of objects that can be restored by this command are listed in the OBJTYPE parameter.
The user profile of the system default owner (QDFTOWN) becomes the default owner of any objects being restored on the system when the profile of the owner is not known to the system.
If an object already exists, in the library to which the object 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.
Restrictions
- To use this command, the user must have *SAVSYS authority, or object existence authority for (or be the owner of) each object specified if the object already exists on the system.
- This command is shipped with public *EXCLUDE authority.
- The device configuration object must be varied off when it is being restored. To vary off a device configuration object, use the Vary Configuration (VRYCFG) command.
- With the exception of overrides for the output listing file, this command ignores all file overrides currently in effect for the job.
- System resource management (SRM) objects are not restored if the RSTCFG command is run using media that was created prior to V2R2M0.
- If the RSTCFG command and the SAVSYS or SAVCFG commands are not run on the same system, the configuration objects may not match the physical hardware on the target system.
- If you restore system resource management objects on a system other than the one on which the SAVSYS or SAVCFG command was saved, the system then treats the target system hardware as new and creates all new resource names, making the existing configuration descriptions useless. If this occurs, you need to restore the correct system resource management database from the most current SAVSYS or SAVCFG command for that command. If neither of these is available, change existing configuration descriptions to reflect the new resource names.
Required Parameters
- OBJ
- Specifies the names of one or more configuration objects being restored.
System resource management (SRM) objects cannot be restored individually or by specifying a generic name. To restore only SRM objects, specify *SRM on the OBJ parameter and a value on the SRM parameter.
*ALL: All the device configuration objects are restored, depending on the values specified for the OBJTYPE parameter.
*SRM: The device configuration objects are not restored, but system resource management (SRM) objects are restored based on the SRM parameter value.
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 being restored. Both generic names and specific names can be specified in the same command. A maximum of 300 object names can be specified.
- DEV
- Specifies the name of the device used for the restore operation. The device name must already be known on the system by a device description.
*SAVF: The save file specified on the SAVF parameter is used for the restore operation.
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 you are using more than one tape device (up to a maximum of four), specify the names of the devices in the order in which they are used.
The device name must already be known on the system by a device description. If using more than one tape drive (up to four), specify the names of the drives in the order they are used. If the objects are on more than one tape volume, the user may want to use more than one tape drive, so that one tape volume can be rewound and unloaded while another tape drive processes the next volume.
Optional Parameters
- OBJTYPE
- Specifies the types of OS/400 system objects that are restored.
*ALL: All device configuration object types that are specified by name are restored. If *ALL is also specified on the OBJ parameter, all of the saved device configuration objects are restored.
object-type: Specify the value for each of the types of objects that are being restored. The following types can be specified:
- *CFGL
- Configuration list
- *CNNL
- Connection list
- *COSD
- Class-of-service description
- *CTLD
- Controller description
- *DEVD
- Device description
- *LIND
- Line description
- *MODD
- Mode description
- *NTBD
- NetBIOS description
- *NWID
- Network interface description
- *NWSD
- Network server description
The object types shown are the ones saved in the device configuration media file by using the Save System (SAVSYS) or Save Configuration (SAVCFG) command.
Note: *SRMSPC are also saved, but not restored as an object type. Specify *SRM on the OBJ parameter to restore SRM data. - 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. *MOUNTED: The objects are restored from the volumes placed in the device specified on the DEV parameter. For a media library device, the volume to be used is the next cartridge in the category mounted by the Set Tape Category (SETTAPCGY) command.
Note: This value cannot be specified when using an optical media library device. volume-identifier: Specify the identifiers of one or more volumes in the order in which they are placed in the device and used to restore the objects.
- SEQNBR
- Specifies which sequence number is used for the restore operation.
*SEARCH: The volume placed in a device is searched for a data file containing the saved device configuration objects. When a match is found, the configuration objects are restored. If the last operation on the device specifies ENDOPT(*LEAVE), the tape remains 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.
file-sequence-number: Specify the sequence number of the file. Valid values range from 1 through 16777215.
- ENDOPT
- Specifies the operation that is automatically performed on the tape or optical volume after the restore operation ends. If more than one volume is used, this parameter applies only to the last volume used; all other volumes are unloaded when the end of the volume is reached.
Note: This parameter is valid only if a tape or optical device name is specified on the DEV parameter. For optical devices, *UNLOAD is the only special value supported, *REWIND and *LEAVE will be ignored. *REWIND: The tape is automatically rewound, but not unloaded, after the operation has ended.
*LEAVE: The tape does not rewind or unload after the operation ends. It remains at the current position on the tape drive.
*UNLOAD: The tape is automatically rewound and unloaded after the operation ends. Some optical devices will eject the volume after the operation ends.
- SAVF
- Specifies the qualified name of the save file used to restore the save data.
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.
- SRM
- Specifies the type of system resource management (SRM) information to be restored. This parameter is valid only when *ALL or *SRM is specified on the OBJ parameter.
Attention:
You must specify SRM(*NONE), unless the system you are restoring to has exactly the same hardware configuration as the system that the original configuration was saved on, to prevent the restore of the SRM information. If the SRM information is restored on a system with a different hardware configuration, the configuration objects may become unusable.
*ALL: All SRM information is restored.
*NONE: No SRM information is restored.
*HDW: All hardware information is restored.
*TRA: All token-ring adapter information is restored.
- ALWOBJDIF
- Specifies whether certain differences encountered during a restore operation are allowed. There are three differences that apply to the RSTCFG command:
- The owner of the object on the system is different than the owner of the object from the save operation.
- The object is secured by an authorization list and is being restored to a system other than the one on which it was saved.
- The primary group of the object on the system is different than the primary group of the object from the save operation.
Note: The user of this parameter must have *ALLOBJ authority. *NONE: The differences described above are not allowed for the restore operation. For an ownership difference, the object is not restored. For an authorization list difference, the object is restored, but the object is not linked to the authorization list, and public authority is set to *EXCLUDE. For a primary group difference, the object is not restored.
*ALL: The differences described above are allowed for the restore operation. The object is restored.
Notes
- If the owners of the object do not match, the object is restored, but it retains the ownership and authorities it had before the restore operation.
- The informational message causes a diagnostic message to be sent indicating that security or integrity changes occurred during the restore operation. This results in an escape message for the restore operation.
- If the user is restoring objects to a system other than the one on which they were saved and the objects are secured by an authorization list, specifying *ALL automatically relinks the objects to the authorization list. If the authorization list does not exist on the new system, a message that includes the name of the missing list is issued.
- If the primary groups of the object do not match, the object is restored, but it retains the primary group it had before the restore operation.
- The informational message causes a diagnostic message to be sent indicating that security or integrity changes occurred during the restore operation. This results in an escape message for the restore operation.
- 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.
- 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.
Examples for RSTCFG
Example 1: Restoring All Objects
RSTCFG OBJ(*ALL) DEV(TAP01) OBJTYPE(*ALL)This command restores all of the device configuration and SRM objects from the tape on the TAP01 drive.
Example 2: Restoring a Device Description
RSTCFG OBJ(PRT01) DEV(TAP01) OBJTYPE(*DEVD) VOL(ABCD)The device description for PRT01 that was saved on tape volume ABCD is restored to the system. If device description PRT01 already exists on the system, it must be varied off before it can be restored.
Example 3: Restoring a Network Server Description
RSTCFG OBJ(SERVER1) DEV(TAP01) OBJTYPE(*NWSD) VOL(SAV1)The network server description SERVER1 that was saved on tape volume SAV1 is restored to the system. If the network server description SERVER1 already exists on the system, it must be varied off before it can be restored.
Error messages for RSTCFG
*ESCAPE Messages
- CPF26C1
- Network server &1 not varied off.
- CPF370C
- Not authorized to ALWOBJDIF parameter.
- 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.
- CPF3733
- &2 &1 in &3 previously damaged.
- CPF3738
- Device &1 used for save or restore is damaged.
- CPF3743
- File cannot be restored, displayed, or listed.
- CPF3748
- Object information for library &1 damaged.
- CPF376B
- File &1 not found.
- CPF3767
- Device &1 not found.
- CPF3768
- Device &1 not valid for command.
- CPF3769
- File found on media not save/restore file.
- CPF377B
- No objects restored. &3 objects excluded.
- CPF377C
- &1 objects restored; &2 not restored; &6 excluded.
- CPF3780
- Specified file for library &1 not found.
- CPF3782
- File &1 in &2 not a save file.
- CPF379B
- Objects from save file &1 in &2 not restored.
- 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.
- CPF3883
- S/38 device configuration objects not restored.
- CPF5729
- Not able to allocate object &1.
- CPF9809
- Library &1 cannot be accessed.
- CPF9812
- File &1 in library &2 not found.
- CPF9820
- Not authorized to use library &1.
- CPF9822
- Not authorized to file &1 in library &2.
- CPF9825
- Not authorized to device &1.