ARECOVER command

Issue the ARECOVER command when you are ready to perform aggregate recovery.

You can specify the ARECOVER command with the PREPARE parameter to create the ABR record. You can specify the ARECOVER command with the VERIFY parameter to verify the accuracy of an aggregate recovery without actually having the data sets recovered. This is like performing a test run of aggregate recovery. After aggregate recovery verification processing completes, the ARECOVER command stops. No data sets are recovered. When you are ready to have aggregate recovery recover your data sets, you can issue the ARECOVER command and specify the EXECUTE parameter. After successful verification processing, your data sets are recovered.
Note: If SETSYS DEBUG is in effect, the VERIFY parameter is forced, regardless of other settings.

The following two topics describe in more detail what occurs when you issue the ARECOVER command with the EXECUTE parameter.

The DATASETNAME and VOLUMES | XMIT parameters are required if the ABR record was not previously created using the PREPARE parameter of the ARECOVER command. The AGGREGATE parameter is required if the DATASETNAME parameter is not used. Either the PREPARE, EXECUTE, or VERIFY parameters must be specified on the ARECOVER command.

For dsname in DATASETNAME(dsname), specify the data set name of the control file.

For volser1,...volsern in VOLUMES(volser1,...volsern), specify the serial numbers of the control files. The volume serial numbers must be specified in the same order as in message ARC6061I, issued during the aggregate backup.

When files are transferred by using a transmission program such as NetView® FTP, issue the ARECOVER command using the XMIT parameter. This tells DFSMShsm that the aggregate backup output has been transmitted. Do not use the VOLUMES and UNIT parameters on the ARECOVER command when XMIT is specified.
Note:
  • Specify the XMIT parameter with the ARECOVER command only if all aggregate backup output files have been cataloged. For DFSMShsm hosts that are running DFSMS Version 2 Release 10 or subsequent releases, only the control file needs to be cataloged before ARECOVER, as long as you are recovering the original ABACKUP files and as long as all of these files have been backed up to tape.
  • If installations use a utility to convert their existing aggregate backup output files from one tape technology to another, ensure that the newly created tapes are catalogued at the recovery site with the newly created unit name and volume serial number, and use the XMIT parameter on the ARECOVER command. The XMIT parameter ensures that ARECOVER processing retrieves the allocation information for the ABARS files from the catalog rather than using the volser and unit stored on the control file tape.
If you choose to have any or all of your ABACKUP output files directed to DASD volumes, there are special precautions you must observe for successful recovery of the backed up data:
  • The aggregate backup files must be properly cataloged and exist at the recovery site.
  • You must use the XMIT and DATASETNAME parameters on your ARECOVER command.

For agname in AGGREGATE(agname), specify the aggregate group name. Do not use the AGGREGATE parameter if you use the DATASETNAME parameter.

The EXECUTE parameter allows the actual ARECOVER data movement to take place when the ARECOVER command is processed. Before you can use ARECOVER AGGREGATE, one of the following actions must occur:
  • You must be performing aggregate recovery on the same system where ABACKUP has been issued, and where the ABR record still exists, or
  • You must have previously issued the ARECOVER DATASETNAME(dsname) PREPARE command.

Specify the PREPARE parameter to build the ABARS CDS record (ABR record) at the recovery site if it does not already exist, without further verification and without data movement. The PREPARE parameter also catalogs ABACKUP output files and adds volumes to RACF®, if required.

The optional ACTIVITY parameter specifies that the ABACKUP activity log is to be recovered.

The optional INSTRUCTION parameter specifies that the instruction data set is to be recovered.

When the ARECOVER command is issued with the VERIFY or PREPARE parameters, DFSMShsm retrieves this information from the ABR record and issues messages during recovery processing indicating the amount of storage required to recover an aggregate group. The amount of storage required for level 0, ML1, and ML2 recovery is displayed separately, along with the combined total storage requirement. This information is maintained in the ABR record and is written to both the ARECOVER activity log and the FSR record.
Note:
  1. If the aggregate recovery is being made from DFHSM V2.5.0 or V2.6.0 ABACKUP output tapes, no storage requirements are displayed.
  2. When ARECOVER EXECUTE is issued, the storage requirements of data sets not recovered is written in the ARECOVER activity log. The amounts of level 0, ML1, and ML2 storage are kept separately, as well as the combined total storage requirement.
  3. When ARECOVER VERIFY is issued, and DFSMShsm determines that a RESTART data set exists, a message is written in the ARECOVER activity log indicating the storage requirements of data sets not successfully recovered in the previous pass. The amounts of level 0, ML1, and ML2 storage are kept separately, as well as the combined total storage requirement.

The optional, and mutually exclusive, STACK and NOSTACK parameters are only valid with the DATASETNAME parameter. They allow you to override the specified SETSYS ABARSTAPES value, or its default value of STACK. The option you select indicates to ARECOVER DATASETNAME processing whether the ABACKUP output you are going to recover is stacked. This information is needed before mounting the control file tape. When the control file tape is mounted, ARECOVER forward spaces to file sequence number 4 if the output is stacked, but does not if the output is not stacked.

The optional UNIT(unittype) parameter is only valid if the DATASETNAME and VOLUMES parameters are used. For unittype, specify the unit type to be allocated for the control file.

The DATE or VERSION optional parameters are valid only when the AGGREGATE parameter is used. For DATE(yyyy/mm/dd), specify the date of the aggregate group version to be recovered. yyyy is the 4-digit year, mm is the month (01–12), and dd is the day of the month (01–31). If more than one aggregate version has been created on the date you specify, the most current version is selected.

For nnnn in VERSION(nnnn), specify the specific version of the aggregate group to be recovered. If neither DATE nor VERSION is specified, the most current aggregate group version is recovered.

Use the optional DATASETCONFLICT parameter to specify how you want to handle data set name conflicts.
  • The RENAMESOURCE(level) subparameter specifies that the ABACKUP data set be recovered with the new high-level qualifier specified by level.
  • The RENAMETARGET(level) subparameter specifies that the data set at the recovery site be renamed with the high-level qualifier specified by level, and the ABACKUP data set be recovered with its original name.

    RENAMETARGET(level) performs an ALTER NEWNAME for the existing data set name.Special care should be taken when you change the high-level qualifier so that the existing data set does not become uncataloged, which may occur when no catalog alias exists for the new high-level qualifier.

  • The BYPASS subparameter specifies that the ABACKUP data set be skipped and not recovered.
  • The REPLACE subparameter specifies that the data set at the recovery site be deleted and replaced by the ABACKUP data set.
    Note:
    1. When you use the DSCONFLICT(REPLACE) parameter, the data set is deleted before attempting the recovery of the data set from the aggregate backup output files. If the recovery fails, the data set remains deleted. Recovery failure results from the following causes:
      • I/O errors on the input tape
      • Failure to allocate the new data set
      • Recovering at a site that does not support the type of data set being recovered
    2. The DATASETCONFLICT parameter may be specified in conjunction with the RECOVERNEWNAMEALL or RECOVERNEWNAMELEVEL parameters.
    3. The DATASETCONFLICT parameter may be abbreviated DSCONFLICT, RENAMESOURCE may be abbreviated RENSRC, and RENAMETARGET may be abbreviated RENTGT.

If you want to specify a predefined model entity to be used for defining discrete profiles to RACF, use the optional MENTITY parameter. Only those data sets previously protected by discrete profiles and defined to RACF before aggregate backup are protected by using discrete profiles. If the model entity is specified in the ARECOVER command and is not predefined, aggregate recovery fails.

Attention: If MENTITY is not specified and data sets exist that have been discretely RACF-protected at the backup site, the data sets are recovered as RACF indicated, and a default discrete profile is created. The profile owner is set to the high-level qualifier of the data set, and UACC is set to NONE.

If a RACF profile has been predefined for the data sets, they are recovered with this predefined profile.

Use the optional MIGRATEDDATA parameter to specify the migration level to be used when recovering migrated data sets:
  • ML1 specifies that all migrated data sets are recovered to migration level 1 DASD (this is the default if you do not use MIGRATEDDATA).
  • ML2 specifies that all migrated data sets are recovered to nonspecific tape volumes which are then ADDVOLed as ML2 volumes.
    Note: You must specify the tape unit name to be used when recovering migrated data sets to nonspecific volumes by use of the ARECOVERML2UNIT parameter of the SETSYS command.
  • SOURCELEVEL specifies that migrated data sets that have been ML1 at the ABACKUP site are recovered to ML1 DASD; migrated data sets that have been ML2 DASD or ML2 tape are recovered to nonspecific volumes which are then ADDVOLed as ML2 volumes.
    Note: If the duplex tape option is specified for ML2 tapes, a TCN record is created to cause an automatic TAPECOPY during secondary space management. ARECOVER of ML2 data is not duplexed.
DFSMShsm automatically creates MCL records for all data sets that are successfully recovered to ML1 DASD volumes unless directed otherwise. This causes these data sets to be backed up during automatic backup processing.
Note: MCL records are not created for data sets recovered to ML2 tape volumes.

The optional NOBACKUPMIGRATED parameter allows you to specify that recovered migrated data sets are not to be backed up during automatic backup. If you do not specify NOBACKUPMIGRATED, DFSMShsm backs up recovered migrated data sets residing on ML1 DASD the next time automatic backup is run.

The optional ONLYDATASET parameter allows you to recover individual data sets from an aggregate backup version. You can specify a single fully qualified data set name using the NAME(dsname) subparameter of ONLYDATASET to recover a particular data set. To recover multiple data sets, you can supply the name of a data set that contains a list of data set names to be recovered on the LISTOFNAMES(listdsname) subparameter of ONLYDATASET. The LISTOFNAMES data set must be a sequential data set, fixed-block, record size of 80, and be cataloged. The LISTOFNAMES data set should contain one fully qualified data set name per record. The abbreviation for ONLYDATASET is ONLYDS and the abbreviation for LISTOFNAMES is LON.

The optional PERCENTUTILIZED(nnn) parameter allows you to change the percentage to which DFSMShsm allows DFSMSdss to fill non-SMS DASD recovery volumes when recovering data sets to level 0 volumes. For nnn, substitute an integer number between 1 and 100. If SETSYS ARECOVERPERCENTUTILIZED has not been specified, the default value is 080 (80%). The value that you specify overrides any default value specified by the SETSYS ARECOVERPERCENTUTILIZED parameter.

The optional RECOVERNEWNAMEALL(level) parameter specifies that all data sets being recovered be renamed with the high-level qualifier specified by level.

The optional RECOVERNEWNAMELEVEL(olevel1,nlevel1,...) parameter specifies that all data sets that have a high-level qualifier olevelx are recovered with a new high-level qualifier nlevelx. The maximum number of olevelx,nlevelx qualifier pairs is 30.

The RECOVERNEWNAMEALL and RECOVERNEWNAMELEVEL parameters allow data sets to be renamed before verification checking for like-named conflicts. These parameters apply to data sets in the INCLUDE and ALLOCATE lists (except for user catalogs in the ALLOCATE list), but do not apply to ACCOMPANY data sets. In addition, migrated source VSAM data sets may not be renamed. If the rename criteria applies to a migrated source VSAM data set, a message is issued, and the data set is not renamed.

If the rename criteria applies to a nonmigrated source VSAM data set, the new component names are not generated by ARECOVER processing, but are generated by a) DFDSS if the data set is from the INCLUDE list, or b) SMS VSAM allocation if the data set is from the ALLOCATE list. As a result, conflict resolution checking does not check for new conflicts for individual components, since the new component names are unknown.

If RECOVERNEWNAMEALL is specified, a message is issued indicating that all data sets will be renamed with the specified level. If RECOVERNEWNAMELEVEL is specified, a message is issued listing the level pairs specified, and indicating that each data set matching the old level will be renamed to the corresponding new level. Each data set meeting the rename criteria is recovered with the new name during data movement. Like-named conflicts created by the new name are evaluated during the conflict resolution process.

If renaming a data set creates a data set name with more than 44 characters, the data set name is truncated to 44 characters, and if the last character is now a ‘.’, it is also truncated. A message is issued indicating that truncation occurred and the resulting new name.

Programming Interface Information

Programming Interface Information Whether RECOVERNEWNAMEALL or RECOVERNEWNAMELEVEL is specified, if the ARECOVER installation exit ARCSKEXT (which allows any data set to be skipped) is active, it is called, before any conflict resolution, with the original data set name of each data set to be recovered. If a data set has been renamed by the RECOVERNEWNAMELEVEL or RECOVERNEWNAMEALL parameter, but was not selected to be skipped in ARCSKEXT by the original data set name, ARCSKEXT is called again with the new data set name. This allows a data set to be skipped based on either its original or new name. End Programming Interface Information

End Programming Interface Information

The optional TARGETUNIT parameter is used to specify the unit type to be allocated to user tape data sets being recovered to a tape device. If TARGETUNIT is not specified, the unit type defaults to the current value of the SETSYS ARECOVERUNITNAME parameter.

ACS routines can override this parameter by assigning a tape storage group. If this is the case, the unit name specified by these parameters is ignored.

When you use the optional TGTGDS(option) parameter with the ARECOVER command, it overrides the value specified by the SETSYS ARECOVERTGTGDS command. The TGTGDS parameter allows you to specify DEFERRED, ACTIVE, ROLLEDOFF, or SOURCE for the SMS-managed generation data set that you are restoring to level 0 DASD. SOURCE causes the data set to be assigned the status it had at the time it was backed up.

You may find it helpful to use the following DFSMShsm commands to manage and query an ARECOVER command:
  • HOLD ARECOVER prevents all currently queued ARECOVER commands from being processed.
  • RELEASE ARECOVER releases queued ARECOVER commands that have been held by using the HOLD command or by DFSMShsm.
  • STOP causes an orderly shutdown of DFSMShsm after any currently running ABACKUP and ARECOVER commands complete processing.
  • STOP DUMP causes an immediate shutdown of DFSMShsm. Any ABACKUP and ARECOVER commands in process are ended and the secondary address space is released.
  • QUERY or HQUERY displays information relevant to aggregate recovery.
  • CANCEL or HCANCEL cancels any existing queued aggregate recovery.
  • LIST displays information from existing ABR records.

Related reading

Parent topic: Performing aggregate recovery