ABR Auto-Recall – Operation

Environments

The ABR Catalog Locate exit supports recalls in a variety of environments: TSO, batch step initiation, and dynamic allocation. Depending on the environment, one or more recall options are available:

  • Recall by invoking FDRABR in the address space of the requester.
  • Recall by invoking FDRABR as a separate started task but waiting for completion (synchronous external recall).
  • Recall by invoking FDRABR as a separate started task without waiting for completion (asynchronous external recall).
  • Recall by adding the request to the Archive Restore remote queue data set

The Data Set Not Found exit is not sensitive to the environment; it always processes in the same way, by invoking FDRABR in the address space issuing the OPEN. The recall may fail if there is insufficient free memory in the region to load and execute FDRABR.

Invoke FDRABR in this address space

The ABR Catalog Locate exit or the Data Set Not Found exit may invoke FDRABR directly to restore the requested data sets in the address space issuing the LOCATE or OPEN. The requesting task waits until the recall is complete; for TSO users the terminal is locked while the restore is progressing).

For this type of recall, sufficient storage must be available in the region for ABR to perform the restore. The basic requirement for the ABR restore is 512K, but the requirement may be much more, depending on such factors as whether the backup is compressed by FDR, whether the restore is to a like device or an unlike device, and the DSORG of the data set being restored. If a recall is performed at batch step initiation, the ABR Catalog Locate exit dynamically increases the REGION size to 1536K if it was smaller than that. In other cases, the recall will fail if sufficient storage is not available.

Synchronous external recall

The ABR Catalog Locate exit initiates a synchronous external recall by issuing a START command for the SYNRECAL cataloged procedure, and then waiting for the SYNRECAL task to complete. The requesting task waits for the recall to complete; for TSO users the terminal is locked while the restore is progressing. Since the recall is done in its own address space, there are no special memory requirements.

Asynchronous external recall

The ABR Catalog Locate exit initiates an asynchronous external recall by issuing a START command for the SYNRECAL cataloged procedure without waiting for SYNRECAL to complete. The requesting task receives control back while the restore is being performed; it gets a “not cataloged” or “not found” indication for the data set.

Limiting concurrent recalls

In installations where there is a lot of recall activity, you may wish to limit resources used for recalls by limiting the maximum number of concurrent external recalls (started tasks) or total recalls (including those in the address space). Options LXMAXSTC and LXMAXREC respectively do this (see LXMAXSTC and LXMAXREC in ABR Auto-Recall – Customization Options). Recalls that would cause the maximums to be exceeded wait until other recalls complete. An ABRNOLIM DD Statement may be added to a job step to make it exempt from these limits.

Remote queue restore

The ABR Catalog Locate exit initiates a remote queue restore by adding a control statement to the Archive Restore remote queue data set, which must have been previously allocated and initialized (see ABRARCH DD Statement in Archive-Restore-Job-Control-Requirements). The requesting task receives control back; it will get a “not cataloged” or “not found” indication for the data set. The installation must schedule an ABR RESTORE TYPE=ARC job to run at frequent intervals to process the remote queue requests. If the recall was on behalf of a TSO user, the user receives a terminal message when the restore is completed, after which the recalled data set can be accessed.

Step initiation

For any batch job, started task, or TSO log in PROC, if one or more Job Control DD statements in a step reference data sets that were archived, the ABR Catalog Locate exit builds a table of those in memory during step initiation. Since step initiation requires a volume serial in order to allocate the data set, the exit temporarily allocates archived data sets to the volume serial number of an online volume of the proper type.

Just before the job step program (PGM=) is attached, FDRABR is invoked to recall those data sets in the address space of the requester. If more than one data set is recalled each required tape volume is mounted only once.

If the recall is successful, the exit reallocates the DD statements pointing to the recalled data sets, so that they now point to the volume to which the data set was recalled.

However, recall of several types of data sets cannot be deferred because they are used during other parts of step initiation, or because they cannot be properly reallocated by the ABR Catalog Locate exit after the recall. For these exceptions, the exit always invokes an immediate synchronous external recall for each data set as it is encountered:

  • STEPLIB and JOBLIB DD statements
  • DCB references (DCB=dsname)
  • Data sets that are concatenated to a temporary data set that specifies DISP=(OLD,DELETE)
  • Data sets that specify DISP=(OLD,PASS) or DISP=(SHR,PASS) on the DD statement for the archived data set or for another data set concatenated to the archived data set
  • GDG-all requests. These are DD statements that specify the name of a Generation Data Group (GDG) without including a generation number, for example, DSN=TEST.GDG, causing z/OS to perform an implicit concatenation of all active generations in the GDG.
  • Volume references (VOL=REF=dsname), if the referenced data set has been recataloged to MIGRAT. The referenced data set must be recalled immediately because VOL=REF requires the serial number of a real volume, which MIGRAT is not.

Dynamic allocation

If a batch job or started task dynamically allocates an archived data set, ABR immediately restores the data set by invoking FDRABR in the address space of the requester. This supports online and database systems such as CICS, DB2, and IMS. You can force a synchronous or asynchronous external recall to be used for a particular job (see ABRSYNCH and ABRASYNC DD Statements in ABR Auto-Recall – Operation).

TSO

If the log in JCL procedure used by a TSO user references archived data sets, they are recalled at step initiation just like any batch job.

All other data sets referenced by TSO, including those used by ISPF, are dynamically allocated by TSO. If a TSO dynamic allocation references an archived data set, an interactive dialog is invoked that informs the user that the data set desired is archived and asks:

  • Whether or not to recall the data set. If the user decides not to recall, the dynamic allocation will get a “not found” return code.
  • Whether to recall the data set to the original DASD volume from which it was archived, or to a different volume.
  • How to perform the recall: foreground (FG), background (BG), or via the remote queue (RQ).

If the choice is foreground (FG), the restore is performed immediately by invoking FDRABR in the TSO user's address space. If the data set has been archived to tape, this requires either that the user have TSO MOUNT authority, or that the installation has set the ALLOCATEFLAG MOUNT option to YES on ISPF panel A.I.4.4.

However, if an ABRSYNCH DD statement is allocated (see ABRSYNCH and ABRASYNC DD Statements in ABR Auto-Recall – Operation) or the LXFGSYNBG option is set (see LXFGSYNBG in ABR Auto-Recall – Customization Options), the restore will instead be performed as a synchronous external recall. Use of an external address space will NOT require the user to have MOUNT authority.

If the recall in the foreground fails for any reason, the LXFGERR option (see LXFGER in ABR Auto-Recall – Customization Options) may direct the ABR Catalog Locate exit to retry the recall in the background or via the remote queue. This option might be used if you archive data sets with COPY1 on DASD and COPY2 on tape. If COPY1 has not yet expired, the foreground recall will recall the data set in a short time, but if COPY1 is expired and ABR was unable to mount the COPY2 tape because the user does not have MOUNT authority, it will do the background or remote queue recall.

  • If the choice is background (BG), the recall is performed as an asynchronous external recall. The user is able to do other work at the terminal while the recall proceeds. The user is notified when the recall is completed.
  • If the choice is remote queue, the recall request is placed in the remote queue for archive restores. The next ABR restore job that references this remote queue recalls the data set. The user is notified when the restore is completed.

The installation may set options in the FDR Global Options that control this dialog (see Setting Options in ABR Auto-Recall – Customization Options). These options can modify any of the bullets above. If you have implemented the ABR RESTORE ALLOCATION LIST you probably want to suppress the request for a target volume serial. You may want to suppress FG restores, allowing only BG or RQ, or you may want to immediately force one type of recall (FG, BG, or RQ) without even asking the user.

Optional recall DD statements

Depending on the environment, the ABR Catalog Locate exit or Data Set Not Found exit may check to see if certain special ddnames have been allocated to the step or TSO user. The presence of these special DD statements modifies the operation of Auto-Recall for that step or user. These allocations will specify DUMMY (except for ABRLIB).

In JCL, code the DD statement as: //ddname DD DUMMY

These are usually used in JCL for batch jobs and started tasks, but you could also include them in TSO log in procedures to affect recall options for all users who log in with a given PROC.

To allocate these DD statements for just one TSO user, the user must go to ISPF Option 6 or TSO READY mode and issue: ALLOCATE FILE (ddname) DUMMY

ABRSYNCH and ABRASYNC DD statements

If an archived data set is recalled because of a dynamic allocation by a batch job or started task, or by a TSO foreground recall request, the ABR Catalog Locate exit normally recalls the data set by invoking FDRABR within the address space of the requester. However, if a ddname of ABRSYNCH has been allocated, the restore is instead performed as a synchronous external recall. If a ddname of ABRASYNC has been allocated, the restore is performed as an asynchronous external recall (and the dynamic allocation fails).

Important

An ABRSYNCH or ABRASYNC DD statement has no effect on recalls at step initiation.

You can force all TSO foreground recalls to be done as synchronous external recalls by setting the LXFGSYNBG option to “YES” (see LXFGSYNBG in ABR Auto-Recall – Customization Options).

ABRIGNOR DD statement

If a ddname of ABRIGNOR has been allocated, the ABR Catalog Locate exit does not recall any data sets for this step or user. The ABR Catalog Locate exit normally gives a successful (zero) return code to the LOCATE SVC, returning the volume serials currently in the catalog. If the MIGRAT=YES option is used, this may result in an attempt to allocate a DASD volume called MIGRAT; if not, and the Data Set Not Found exit is installed, it may attempt to recall the data set at OPEN time (see ABRIGNRD DD Statement in ABR Auto-Recall – Operation).

ABRIGNRD DD statement

If a ddname of ABRIGNRD has been allocated, the Data Set Not Found exit does not recall any data sets for this step or user. If OPEN finds that a data set is not in the VTOC of the allocated volume, it causes a normal S213-04 abend. This can be used to selectively suppress the FDR316 message that is displayed for data sets that were never archived (see Data Set Not Found Exit in ABR Auto-Recall – Introduction).

ABREMOTE DD statement

If a ddname of ABREMOTE has been allocated, the ABR Catalog Locate exit places all recall requests due to dynamic allocation by a batch job or started task, or due to TSO foreground recall, into the Archive Restore Remote Queue (see ABRARCH DD Statement in Archive-Restore-Job-Control-Requirements and Create-the-Remote-Queue-Files). The LOCATE fails so the requesting program probably generates an error message. The data sets are recalled later when an ABR Archive Restore that processes the remote queue is executed (see Remote Queue Restore Example in Archive-Restore-Examples). This might be used with CICS or similar online systems, to accumulate recall requests and minimize tape mounts; the online transaction fails but works if executed after the remote queue is processed.

ABRNOLIM DD statement

If a ddname of ABRNOLIM has been allocated, the ABR Catalog Locate exit makes this job step or user exempt from the limits on concurrent recalls set by the LXMAXSTC and LXMAXREC options.

ABRLIB DD statement

If present, the ABRLIB DD statement must point to a program library containing ABR; it can be used to test new versions of ABR. If the ABR Catalog Locate exit or the Data Set Not Found exit finds that ABRLIB is present, then the module containing the FDR Global Options module (FDROPT) may be read from the ABRLIB library; for recalls performed in the address space of the requester, FDRABR and other modules invoked by FDRABR recall will also be loaded from the ABRLIB library. The following paragraphs explain this in more detail. This is used primarily for testing new versions of ABR (see ABRLIB / STEPLIB for Testing in Testing-the-FDR-z-OS-Exits).

Under the Data Set Not Found exit, ABRLIB is always be used both for FDROPT and FDRABR.

Under the ABR Catalog Locate exit, for a recall performed in the requesters address space, ABRLIB is always be used both for FDROPT and FDRABR. Likewise, for a remote queue recall, the remote queue utility (FDRABRUT) is loaded from ABRLIB.

ABRLIB has no effect on external recalls. The source for the FDRABR and FDROPT modules depend on the JCL in the SYNRECAL started task. STEPLIB can be used to point to a special FDR program library.

The ABR Catalog Locate exit accesses FDROPT for various options that affect the operation of auto-recall, described in ABR Auto-Recall – Operation. These options are set at the time that the ABR Catalog Locate exit is dynamically installed, so an ABRLIB DD statement cannot override them. However, a test copy of the exit can be installed with a unique set of options; as described in Testing-the-FDR-z-OS-Exits, the test exit will apply only to certain specified jobs or TSO users. The Update the Options in Use by the Production Exits While a Test Exit is Active in Testing-the-FDR-z-OS-Exits also shows how to refresh the copy of FDROPT in use by the exit, to change options dynamically.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*