Restore Object using BRM (RSTBRM)

The Restore Object using BRM (RSTBRM) 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 Introduction book.

Virtual tape media and devices can be used with this command. The following restrictions apply to the use of virtual media and virtual devices.

The Device (DEV) parameter is limited on only one device or *MEDCLS special value for serial operations.
Execute authority is required to the Load or Unload Image Catalog (LODIMGCLG) command.
*CHANGE authority is required to the image catalogs.
Execute (*X) authority is required to each directory in the image catalog path name.
Read, write, execute (*RWX) authority is required to each image file in the parent directory that will be loaded or mounted.
*USE authority is required to the virtual devices using the image catalogs.

To use this command, you must have the Backup Recovery and Media Services for iSeries, 5722-BR1, licensed program installed.

Restrictions:

For detailed restrictions on using this command to restore objects by using name patterns in the root directory, to restore objects in libraries, or to restore document library objects, see the Restore Object (RST) command in the Backup and Recovery book.
The RSTBRM command does not support optical files.
You must have authority to use the Restore Object (RST) command.
You must have save system (*SAVSYS) special authority, or have all of the following object authorities:
- You must have *W and *OBJEXIST authority to restore a file if it already exists on the system.
- You must have *WX authority to the parent directory.
- You must have *ADD authority to the owning user profile of the directory into which the parent directories are created.
- You must have *ALLOBJ special authority to create parent directories with a user profile other than your own.
You must have *ALLOBJ special authority to use any value other than *NONE for the ALWOBJDIF parameter.
You can restore data from a TSM server device by using this command. You can only specify one TSM device or *MEDCLS, which must select a TSM device. The TSM device selected can either be *APPC, which supports the SNA network protocol, or *NET, which supports the TCP/IP protocol.
This command should not be used by control group *EXIT item processing as results will be unpredictable.

Parameters

Keyword	Description	Choices	Notes
DEV	Device	Values (up to 4 repetitions): Name, *MEDCLS	Required, Positional 1
PRLRSC	Parallel device resources	Element list	Optional
	Element 1: Minimum resources	1-32, SAV, NONE, *AVAIL
	Element 2: Maximum resources	1-32, MIN, AVAIL
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
SUBTREE	Directory subtree	ALL, DIR, NONE, OBJ	Optional
SAVLVL	Save level	1-99, *CURRENT	Optional
ENDOPT	End of tape option	REWIND, LEAVE, *UNLOAD	Optional
OPTION	Option	ALL, NEW, *OLD	Optional
ALWOBJDIF	Allow object differences	Single values: NONE, ALL Other values (up to 2 repetitions): AUTL, OWNER, *PGP	Optional
OBJID	Object ID	SAVED, SYS	Optional
CRTPRNDIR	Create parent directories	NO, YES	Optional
PRNDIROWN	Parent directory owner	Name, *PARENT	Optional
FROMSYS	From system	Character value, *LCL	Optional

Top

Device (DEV)

Specifies the device name or a specific media class that is to be used to restore the object. You must use a single device for recovery processing.

You can restore data from a TSM (ADSM) server using this command. You can only specify one TSM type server or *MEDCLS, which must select a TSM server. The device selected can either be *APPC, which supports SNA network protocol, or *NET, which supports TCPIP protocol.

This is a required parameter.

*MEDCLS: BRMS determines the media class of the media on which the requested item is saved. Once the media class is determined, a device supporting that media class is selected to restore the requested object or objects.
device-name: Specify the name of the device that you want to use to restore the selected object or objects.

Parallel device resources (PRLRSC)

Specifies the minimum and maximum number of device resources to be used in a restore operation.

Element 1: Minimum Resources

Specifies the minimum number of device resources required for a parallel restore.

Note: If a Media Library Device (MLB) is being used and the required resources are not available, the command will wait for the MLB to become available for a time period specified by the user. The wait time is determined by the value specified on the *MLB device description for INLMNTWAIT. If a *TAP device is being used and the required resources are not available, the command will fail.

Note: Transferring save files to tape does not support parallel operations.

*SAV: Specifies that the same number of device resources used for the save will be used for the restore. If the save was a serial save, then the restore will also be serial.
*AVAIL: Use any available devices up to the maximum specified. Specifying this value for the minimum will allow BRMS to use any available resources, but will complete using one resource if only one is available at the start of the command.
*NONE: No device resources are to be used. The restore will be performed as a serial restore.
1-32: Specify the minimum number of device resources to be used with this restore command, up to the maximum of what was used for the save.

Element 2: Maximum Resources

*MIN: Uses the value specified for the minimum number of device resources.
*AVAIL: Use any available devices. Specifying this value for the maximum will allow BRMS to use any available resources but at a minimum use the value specified in the minimum element.
1-32: Specify the maximum number of device resources to be used with this restore command, up to the maximum of what was used for the save.

Objects (OBJ)

Specifies the objects that you want to include or exclude from a list of objects you want to restore. A maximum of 300 object name patterns can be specified.

For more information on specifying path names, refer to Chapter 2 of the Command Language Reference book.

Additional information about object name patterns is in the Integrated File System Introduction book. The first element specifies the path names of 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.

Element 1: Name

object-path-name-pattern: Specify an object path name or a pattern that can match many names.

Element 2: Include or omit

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

Element 3: New object name

The third element 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.
new-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 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.

Directory subtree (SUBTREE)

Specifies whether directory subtrees are included in the restore operation.

*ALL: The entire subtree for each directory that matches the object name pattern is included. The subtree includes all subdirectories and the objects within those subdirectories.
*DIR: Objects in the first level of each directory that matches the object name pattern are included. 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 exactly match the object name pattern will be processed. If the object name pattern specifies a directory, objects in the directory are not included.

End of tape option (ENDOPT)

Specifies, when volume is used, what positioning operation is automatically done on the volume after the restore operation ends. If more than one volume is included, this parameter applies only to the last volume used; all other volumes are rewound and unloaded when the end of the volume is reached.

If you specify *LEAVE and the device is a shared device, the device will not be varied off after the save operation. If you specify *LEAVE and the device is not a shared device, the device will be varied off after the save operation.

*REWIND: The volume is automatically rewound but not unloaded after the recovery operation ends.
*LEAVE: The volume does not rewind or unload after the operation ends. It remains at the current position on the device.
*UNLOAD: The volume is automatically rewound and unloaded after the recovery operation ends.

Allow object differences (ALWOBJDIF)

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

Authorization list: The authorization list of an object on the system is different than the authorization list of an object from the save operation. Or the system on which a new object with an authorization list is being restored is different from the system on which it was saved.

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.

Note: To use this parameter, you need *ALLOBJ special authority.

Single values

*NONE: None of the differences listed above are allowed on the restore operation.
*ALL: All of the differences listed above are allowed on the restore operation. File level identifier and member level identifier differences are handled differently than the *FILELVL value. If there is a file level difference and *ALL is specified on the Data base member option (MBROPT) parameter, the existing version of the file is renamed and the saved version of the file is restored. If there is a member level difference, the existing version of the member is renamed and the saved version of the member is restored. This value will restore the saved data, but the result may not be correct. For other differences, see the description of each individual value to determine how differences are handled.
Note: If restoring objects that BRMS saved with SAVOBJ or SAVCHGOBJ, BRMS will change the parameter to ALWOBJDIF(*FILELVL *AUTL *OWNER *PGP) for these objects to prevent the renaming.

Other values (up to 4 repetitions)

*AUTL

Authorization list differences are allowed.

If an object already exists on the system with a different authorization list than the saved object, the object is restored with the authorization list of the object on the system. New objects that are being restored to a system that is different from which they were saved are restored and linked to their authorization list. If the authorization list does not exist on the new system, the public authority is set to *EXCLUDE.

If this value is not specified, authorization list differences are not allowed. If an object already exists on the system with a different authorization list than the saved object, the object is not restored. New objects that are being restored to a system that is different from which they were saved are restored, but they are 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.

Object ID (OBJID)

Specifies whether the SOM object ID of the restored object will be the SOM object ID of the object from the save media, the SOM object ID of the object that exists on the system prior to the restore, or a new SOM object ID generated by the system if the object does not exist on the system prior to the restore.

*SAVED: The restored object will have the SOM object ID it had when it was saved.
*SYS: The restored object may have a new SOM object ID generated by the system. If the object is being restored as a new object, a new SOM object ID will be given to the restored object. If an object with the same name as the object from the media already exists on the system, the SOM object ID of the restored object will be the same as the SOM object ID of the object on the system before the restore.

From system (FROMSYS)

Specifies the location and network identification of the system from which you want to restore media information to the local system.

Note: Use the Display Network Attributes (DSPNETA) command to view the system network attributes.

Note: The BRMS Network feature (Option 1) is required to use this value if a value other than *LCL is specified.

*LCL: Specifies that the from-system is the local system. BRMS uses the Default local location name (LCLLOCNAME) network attribute and not the System name (SYSNAME) network attribute to determine the current system name. In most cases, the systems have the same value specified for LCLLOCNAME as for SYSNAME.
location-name: Specifies the Default local location name (LCLLOCNAME) network attribute of the remote system for the network operation. The current system Local network ID (LCLNETID) network attribute is used to connect with the remote system.
network-id.location-name: Specifies the Local network ID (LCLNETID) and the Default local location name (LCLLOCNAME) network attributes of the remote system for the network operation. Specify these values using the format nnnnnnnn.cccccccc where nnnnnnnn is the LCLNETID and cccccccc is the LCLLOCNAME.