Resume Retrieve using BRM (RSMRTVBRM)
| Where allowed to run: All environments (*ALL) Threadsafe: No |
Parameters Examples Error messages |
You can resume delayed retrieve operations for libraries, documents and bytestream files, including those held due to lack of disk space. The Resume Retrieve using BRM (RSMRTVBRM) command attempts to retrieve items from media.
To use this command, you must have the Backup Recovery and Media Services for IBM i licensed program installed.
Restrictions:
- The BRMS Advanced feature (Option 2) is required to use this command.
- *ALLOBJ special authority is required to use any value other than *NONE for the ALWOBJDIF parameter.
- You can select only one virtual device for serial retrieve operations. In addition, only one *MEDCLS can be specified when using media classes which specify a virtual device density.
| Top |
Parameters
| Keyword | Description | Choices | Notes |
|---|---|---|---|
| HDLOBJ | Retrieve select | *ALL, *DELAY, *SECURITY, *STORAGE | Optional, Positional 1 |
| ACTION | Action | *RETRIEVE, *REPORT | Optional, Positional 2 |
| CFMRTV | Confirm retrieval | *YES, *NO | Optional, Positional 3 |
| ASP | Auxiliary storage pool | Character value, *ALL, *SYSTEM | Optional, Positional 4 |
| TYPE | Item type | *LIB, *FLR, *LNK | Optional |
| SAVLIB | Library | Name, *ALL | Optional |
| DEV | Retrieve device | Single values: *RTVPCY Other values (up to 4 repetitions): Name, *MEDCLS |
Optional |
| PRLRSC | Parallel device resources | Element list | Optional |
| Element 1: Minimum resources | 1-32, *SAV, *AVAIL, *NONE | ||
| Element 2: Maximum resources | 1-32, *MIN, *AVAIL | ||
| ENDOPT | End of media option | *RTVPCY, *LEAVE, *REWIND, *UNLOAD | Optional |
| RSTOPT | Option | *RTVPCY, *ALL, *FREE, *NEW, *OLD | Optional |
| ALWOBJDIF | Allow object differences | Single values: *RTVPCY, *ALL, *COMPATIBLE, *NONE Other values (up to 4 repetitions): *AUTL, *FILELVL, *OWNER, *PGP |
Optional |
| Top |
Retrieve select (HDLOBJ)
Specifies the type of held items that you want to retrieve when you process the command. You can specify a type of held object such as an item that was not retrieved due to lack of storage space on the disk unit or you can specify all held items.
- *ALL
- Attempts to retrieve all items that have been held during a previous retrieve process.
- *DELAY
- Attempts resume delayed retrieve operations.
- *SECURITY
- Attempts to retrieve items that were held due to insufficient security during a previous retrieve request.
- *STORAGE
- Attempts to retrieve items that were held due to insufficient disk unit space in a previous retrieve request.
| Top |
Action (ACTION)
Specifies whether you want to create a report or perform an actual retrieve.
- *RETRIEVE
- You want to retrieve the requested items from the BRMS media content information.
- *REPORT
- You want to create the Retrieve Report. This will allow you to review what will be retrieved prior to retrieving the selected items. The report, if printed, is written to printer file QP1ASX.
| Top |
Confirm retrieve (CFMRTV)
Specifies whether items that are selected for retrieve are displayed on the Confirm Retrieve display prior to retrieve.
Note: This parameter is ignored in batch.
- *YES
- The Confirm Retrieve display is shown before the retrieve begins.
- *NO
- The Confirm Retrieve display is not shown before the retrieve begins.
| Top |
Auxiliary storage pool (ASP)
Specifies the auxiliary storage pool into which you want to retrieve items.
- *ALL
- You want to retrieve items into all auxiliary storage pools.
- *SYSTEM
- You want to retrieve items into the system (1) auxiliary storage pool.
- ASP-number
- Specify the number of the system (1) or basic user auxiliary storage pool (2-32) into which you want to retrieve items.
- ASP-name
- Specify the auxiliary storage pool name into which you want to retrieve items.
Restriction:
- The auxiliary storage pool specified for retrieval must be valid for the Item Type specified.
| Top |
Item type (TYPE)
Specifies which type of item is displayed on the Confirm Retrieve display prior to retrieve operations.
- *LIB
- Retrieve information for libraries is to be included.
- *FLR
- Retrieve information for folders is to be included.
- *LNK
- Retrieve information for bytestream files is to be included.
| Top |
Library (SAVLIB)
Specifies the library into which you want to retrieve items.
- *ALL
- Items are retrieved to their original library.
- library-name
- Specify the name of the library into which items are retrieved.
| Top |
Retrieve device (DEV)
Specify the device name that is to be used in the retrieve process. You must use a single device for retrieve processing.
Single values
- *RTVPCY
- The retrieve device specified in the BRMS retrieve policy is used.
Other values (up to 4 repetitions)
- *MEDCLS
- BRMS determines the media class of the media on which the requested item is saved. Once the media class is determined, a device that supports that media class is selected to retrieve the requested save item or items.
- device-name
- Specify the name of the device that is used as the default retrieve device in retrieve processing.
| Top |
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.
| Top |
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.
- *RTVPCY
- The value specified in the BRMS retrieve policy is the value that is used.
- *LEAVE
- The volume does not rewind or unload after the operation ends. It remains at the current position on the device.
- *REWIND
- The volume is automatically rewound but not unloaded after the recovery operation ends.
- *UNLOAD
- The volume is automatically rewound and unloaded after the recovery operation ends.
| Top |
Option (RSTOPT)
Specifies which items are retrieved, depending on whether the items exist in the library on the system.
- *RTVPCY
- The value from the BRMS retrieve policy is used.
- *ALL
- All the items in the saved library are retrieved to the library. Old items on volume or in a save file replace the current versions in the library on the system. Items not having a current version are added to the library on the system. Items presently in the library, but not on the media, remain in the library.
- *FREE
- The saved items are retrieved only if they exist in the system library with their space freed. The saved version of each item is retrieved in the system in its previously freed space. This option retrieves items that had their space freed when they were saved. If any saved items are no longer part of the current version of the library, or if the space is not free for any item, the item is not retrieved. The retrieve operation continues, and all of the freed items are retrieved.
- *NEW
- Only the items in the saved library that do not exist in the current version of the library on the system are added to the library. Only items not known to the library on the system are retrieved; known items are not retrieved. This option retrieves items that were deleted after they were saved or that are new to this library. If any saved items have a version already in the library on the system, they are not retrieved, and an informational message is sent for each one, but the retrieve operation continues.
- *OLD
- Only the items in the library having a saved version are retrieved; that is, the version of each item currently in the library is replaced by the saved version. Only items known to the library are retrieved. If any saved items are no longer part of the online version of the library, they are not added to the library; an informational message is sent for each one, but the retrieve continues.
| Top |
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.
- File level identifier: The creation date and time of the database file on the system does not match the creation date and time of the file that was saved.
- Member level identifier: The creation date and time of the database file member on the system does not match the creation date and time of the member that 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
- *RTVPCY
- The value from the retrieve policy is used for this value.
- *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. *COMPATIBLE is usually preferable to the value *ALL since it only allows differences that are compatible with existing database files.
Note: If restoring objects that were saved with SAVOBJ or SAVCHGOBJ, BRMS will change the parameter to ALWOBJDIF(*COMPATIBLE) for these objects to prevent the renaming.
- *COMPATIBLE
- 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. This value allows differences that are compatible with existing database files. This value is usually preferable to the value *ALL which also allows differences that are not compatible with existing database files.
- *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.
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.
- *FILELVL
- File level identifier and member level identifier differences are allowed.
An attempt will be made to restore existing physical files even though the physical file on the save media may have a different file level identifier or member level identifier than the physical file on the system. The physical file data will only be restored for those physical files whose format level identifiers on the save media match the format level identifiers of the corresponding physical file on the system.
If this value is not specified, file level identifier and member level identifier differences are not allowed. If an object already exists on the system with a different file level identifier or member level identifier than the saved object, the object is not restored.
- *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.
| Top |
Examples
Example 1: Resuming a Retrieve for Security Items
RSMRTVBRM HDLOBJ(*SECURITY)
This command resumes the retrieve operation for items that were held due to lack of authorization.
| Top |
Error messages
*ESCAPE Messages
- BRM1917
- Feature not installed.
- BRM1921
- Feature not licensed.
- BRM2112
- ASP &2 not valid.
- 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.
| Top |