Restore Configuration (RSTCFG)

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 on the Object types (OBJTYPE) parameter. The QDFTOWN user profile becomes the default owner of any objects restored on the system whose owner is not known to the system. If an object already exists in the library to which that 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 given again.

Note: This command ignores all file overrides currently in effect for the job, except for the output file.

Restrictions:

• You must have save system (*SAVSYS) special authority, or have object existence (*OBJEXIST) authority for (or be the owner of) each object specified if the object already exists on the system.
• This command is shipped with no public authority (*EXCLUDE).
• 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.
• 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 objects from the most current SAVSYS or SAVCFG command for that command. If neither of these is available, you must change existing configuration descriptions to reflect the new resource names.

Parameters

Objects (OBJ)

Specifies the objects to be restored. Specify the name of each object, or the generic name of each group of objects to restore. A generic name is a character string that contains one or more characters followed by an asterisk (*). If an asterisk (*) is not specified with the name, the system assumes that the name is a complete object name.

If the Object types (OBJTYPE) parameter has a value of *ALL, all the object types listed in the description of the OBJTYPE parameter are restored, if they have the specified names.

System resource management (SRM) objects cannot be restored individually or by specifying a generic name. To restore only SRM objects, specify *SRM for this parameter and a value for the System Resource Management (SRM) parameter.

This is a required parameter.

Single values

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

ATTENTION You must specify SRM(*NONE) on the RSTCFG, unless the system you are restoring to is the exact same hardware configuration that the original configuration was saved on, to prevent the restore of the SRM information. If the SRM information is restored, the configuration objects may become unusable.

Other values (up to 300 repetitions)

generic-name

Specify one or more generic names of groups of objects in the specified library to restore.

Note: A generic name is specified as a character string that contains one or more characters followed by an asterisk (*). If a generic name is specified, then all objects that have names with the same prefix as the generic object name are selected.

name

Specify one or more names of specific objects to restore. Both generic names and specific names can be specified in the same command. A maximum of 300 object names can be specified.

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

This is a required parameter.

Single values

*SAVF

The restore operation is done using the save file specified for the Save file (SAVF) parameter.

Other values

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 a virtual tape device is used, it must be the only device specified. 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. When more than one tape volume is to be restored, using more than one tape device permits one tape volume to be rewound while another tape device processes the next tape volume.

Object types (OBJTYPE)

Specifies the types of system objects that are to be restored.

Single values

*ALL

All of the device configuration object types that are specified by name are restored. If *ALL is also specified for the Objects (OBJ) parameter, all of the saved device configuration objects are restored.

Other values (up to 10 repetitions)

character-value

Specify the value for each of the types of objects that are to be restored.

The object types shown are the ones that are saved in the device configuration file by the Save System (SAVSYS) command or the Save Configuration (SAVCFG) command.

*CFGL

Configuration lists

*CNNL

Connection list

*COSD

Class-of-service description

*CTLD

Controller description

*DEVD

Device description

*IPXD

Internet Packet Exchange description

*LIND

Line description

*MODD

Mode description

*NTBD

NetBIOS description

*NWID

Network interface description

*NWSD

Network server description

Note: *SRMSPC can be saved but not restored as an object type. To restore *SRM data, specify *SRM for the OBJ parameter.

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 first version of the objects found in the specified location is restored, unless a specific version is identified by the SAVDATE parameter and SAVTIME parameter, or for tape, the SEQNBR parameter.

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.

Sequence number (SEQNBR)

Specifies the sequence number that 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.

1-16777215

Specify the sequence number of the file to be used for the restore operation.

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.

Save file (SAVF)

Specifies the save file used to restore the data.

Note: A value must be specified for this parameter if *SAVF is specified for the Device (DEV) parameter.

Qualifier 1: Save file

name

Specify the name of save file to be used.

Qualifier 2: Library

*LIBL

All libraries in the library list for the current thread are searched until the first match is found.

*CURLIB

The current library for the thread is used to locate the save file. If no current library entry exists in the library list, the QGPL library is used.

name

Specify the name of the library where the save file is located.

System Resource Management (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 Objects (OBJ) parameter.

ATTENTION Unless the system you are restoring to has exactly the same hardware configuration as the system that the original configuration was saved on, you must specify SRM(*NONE) on this command 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 system resource management information is restored.

*NONE

No system resource management information is restored.

*HDW

All hardware information is restored.

*TRA

All token-ring adapter information is restored.

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 topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/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.

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:

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

Output (OUTPUT)

Specifies whether a listing that shows information about the status of the objects 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.

*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 for the File to receive output (OUTFILE) parameter.

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

File to receive output (OUTFILE)

Specifies the database file to which the output of the command is directed. If the file does not exist, this command creates a database file in the specified library. If the file is created, the public authority for the file is the same as the create authority specified for the library in which the file is created. Use the Display Library Description (DSPLIBD) command to show the library's create authority.

Qualifier 1: File to receive output

name

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

Qualifier 2: Library

*LIBL

The library list is used to locate the file. If the file is not found, one is created in the current library. If no current library exists, the file will be created in the QGPL library.

*CURLIB

The current library for the thread is used to locate the file. If no library is specified as the current library for the thread, the QGPL library is used.

name

Specify the name of the library to be searched.

Note: If a new file is created, the system uses the IBM-supplied file QASRRSTO with format name QSRRST as a model.

Output member options (OUTMBR)

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

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 for the File to receive output (OUTFILE) parameter.

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, you can add records to the end of the existing member or clear the existing member and add the records.

Element 2: Replace or add records

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

Objects to omit (OMITOBJ)

Specifies the objects to be excluded from the operation. Up to 300 objects or generic object values can be specified.

Element 1: Object

Qualifier 1: Object

*NONE

No objects are excluded from the operation.

*ALL

All objects of the specified object type are excluded from the operation.

generic-name

Specify the generic name of the objects to be excluded.

Note: A generic name is specified as a character string that contains one or more characters followed by an asterisk (*). If a generic name is specified, then all objects that have names with the same prefix as the generic object name are selected.

name

Specify the name of the object to be excluded from the operation.

Element 2: Object type

*ALL

All object types are excluded from the operation, depending on the value specified for the object name.

character-value

Specify the object type of the objects to be excluded from the operation.

To see a complete list of object types when prompting this command, position the cursor on the field for this parameter and press F4 (Prompt). For a description of the object types, see "Object types" in the CL topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.

Examples

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

*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

Data encrypted or not save data.

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 or ASP 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.