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 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 IBM i licensed program installed.

Restrictions:

1. 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.
2. You must have authority to use the Restore Object (RST) command.
3. 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.
4. You must have *ALLOBJ special authority to use any value other than *NONE for the ALWOBJDIF parameter.
5. 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.
6. This command should not be used by control group *EXIT item processing as results will be unpredictable.
7. You can restore data from an optical device by using this command. You can only specify one optical device or *MEDCLS, which must select an optical device.

Parameters

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.

Single values

*LIST

The List (LIST) parameter will be used to indicate which objects to restore.

Other values

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.

Save level (SAVLVL)

Specifies the copy of the object that you want to restore from the media content information.

*CURRENT

The most current copy of the object is restored.

*SAVDATE

Specifies a save date that will be used to identify the level of object you want to restore. The save date is specified on Save level time reference (SAVDATE) parameter.

save-level-number

Specify the age of the copy that you want to restore from the media content information. You can specify a copy number from 1 - 99. For instance, if you want to restore the next to the last most recent copy specify 1.

Save level time reference (SAVDATE)

Specifies a time reference point for the object you want to restore.

Element 1: Save date

Specifies a date for the object you want to restore. The object is not restored if there is no save of the object on the specified date.

Note: A value must be specified for this parameter if *SAVDATE is specified for the Save level (SAVLVL) parameter.

save-date

Specify the date that the library to be restored was saved. The date must be entered in the job date format.

Element 2: Save time

Specifies a time for the object you want to restore. The object whose save time is on or before the time specified and on the save date specified is restored.

Note: This value will be ignored if *SAVDATE is not specified for the Save level (SAVLVL) parameter.

*LATEST

The latest time that is available for the save date is included.

save-time

Specify the save time for the specified save date that indicates which objects are to be restored.

End of media option (ENDOPT)

Specifies the operation that is automatically done on the tape or optical volume after the save 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.

Note: For optical devices, *UNLOAD is the only special value supported, *REWIND and *LEAVE will be ignored.

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.

Option (OPTION)

Specifies how to handle restoring each object.

*ALL

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

*NEW

Only the objects that do not exist on the system are restored.

*OLD

Only the objects that exist on the system are restored.

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. See the description of each individual value to determine how differences are handled.

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.

Private authorities (PVTAUT)

Specifies whether to restore private authorities with the objects that are restored.

Note: You must have all object (*ALLOBJ) special authority to restore private authorities.

*NO

No private authorities are restored.

*YES

Private authorities are restored with the objects that have had the authorities saved. If no private authorities were saved with the object, then just the object will be restored.

Object ID (OBJID)

This parameter has been disabled and is no longer valid.

Create parent directories (CRTPRNDIR)

Specifies whether parent directories are to be created automatically if the directories do not exist before the object is restored. This parameter only applies to "root" (/), QOpenSys, and user-defined file systems.

*NO

Specifies parent directories are not to be automatically created.

*YES

Specifies parent directories are to be automatically created. The parent directory owner can be specified using the Parent directories owner (PRNDIROWN) parameter.

Parent directory owner (PRNDIROWN)

Specifies the name of the owner to be used for the parent directory when creating parent directories which do not exist.

*PARENT

Specifies the owner of the directory into which the parent directory is created will be used for the owner of the created parent directory.

user-profile

Specifies the name of the user profile to use for the parent directory owner when creating parent directories which do not exist.

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.

Output (OUTPUT)

Specifies whether a list of information about the restored objects is created. The information can be directed to a stream file or a user space.

A stream file or user space is specified as a path name.

*NONE

No output is created.

'stream-file-path-name'

Specify the path name of the existing stream file to which the output of the command is directed.

'user-space-path-name'

Specify the path name of the existing user space to which the output of the command is directed.

List (LIST)

Specifies a list that will be used to determine which objects will be restored.

Element 1: Type

The first element specifies the type of list that will be used to determine which objects to restore.

*DAOS

Specifies that the list of objects to restore should be taken from a stream file generated by a Domino Server for Domino Attached and Object Service (DAOS) objects. The second element specifies a path name to a stream file that was created by a Domino Server.

Element 2: Path name

'list-name'

Specify the name that should be used to process the type specified in element 1. See the description of the values for element 1 to determine how to specify element 2.

Examples

Example 1: Restoring All Integrated File System Objects

RSTBRM DEV(TAPE01)

This command allows you to select and restore integrated file system objects that were saved using the SAVBRM command and whose contents information still exist in the media contents information. In this example, the restore operation is for all integrated file system objects and will use device TAPE01 for the restore operation.

Error messages

*ESCAPE Messages

BRM1177

Cannot establish connection with remote system.

BRM1917

Feature not installed.

BRM1921

Feature not licensed.

BRM2262

Errors occurred receiving data from TSM server.

BRM4040

Access denied for user &1.

BRM40A2

BRMS product initialization required.

CPF3700

All CPF37xx messages could be signaled. xx is from 01 to FF.

CPF3800

All CPF38xx messages could be signaled. xx is from 01 to FF.

CPF9800

All CPF98xx messages could be signaled. xx is from 01 to FF.