Using a permanent Application Control File
All examples in this section are found in the JCL library installed with FDR. The member names are EX5211x.
This section describes use of FDRAPPL with a permanent Application Control File. Example job steps are provided. These examples are also found in the JCL library loaded during FDRAPPL's installation (see Installing).
There must be at least one unique permanent Application Control File (ACF) for each application that uses FDRAPPL. You may need to create multiple ACFs for an application if it needs to backup different data sets at different times. The Application Control File accumulates entries that record all of the Application Backups that have been done for that application.
The high-level index of the Application Control File data set name is also used as the high-level index of all backup files on tape created by FDRAPPL, making it easier to identify the owner of the backup tapes and easier to define tape management rules for those tapes.
If you are restoring the data sets at your home site, you can simply reference the Application Control File, and Application Restore restores the latest copy of every data set recorded in it.
If you are restoring at a disaster site, you must first restore the latest copy of the Application Control File. You have two options for doing this:
1.You can back up and restore the Application Control File independently of the Application Backup process. One way to do this is to back up the Application Control Files for all applications using ABR Volume Backups, with full-volume and incremental backups. This means that the Application Control Files must be on volumes that are backed up by ABR Volume Backups, and which are recovered using ABR volume recovery or data set restore (see Working-with-FDRABR-Volume-Backups) before doing any Application Restore.
2.Unless you specify ARCBACKUP=NO during the Application Backup, FDRAPPL automatically does a DSF-type backup of the Application Control File to the last file on the backup tapes, and catalogs that backup file (the backup file can be a GDG to make it easier to recover it from various levels). You can use FDRDSF to restore the Application Control File from that backup, and then use it to restore the application data sets. It is recommended that those ACF backups be generations of a Generation Data Group (GDG) so that you can track and restore from several versions.
To successfully restore at a disaster site, you must first restore all system catalogs that are involved, including the catalogs for the application data sets, and the catalogs in which the Application Backups themselves are cataloged (based on the names of the Application Control File and the ARCB1DSN=/ARCB2DSN= operands).
Here are the steps required to implement FDRAPPL for a given application with a permanent ACF:
- Create the GDG bases for the backups of the Application Control File.
- Create and format the Application Control File with the FORMAT function of FDRARCH.
Build job steps that execute backups for the application. You may want to convert these into cataloged procedures (PROCs), which can be executed by many different applications, with symbolic parameters for data set names and other values. These steps can be inserted into application job streams, or can be run as separate jobs in the application cycle.
- Build job steps that can be used to restore data sets from the backups. These may also be converted into cataloged procedures. You may need separate job steps to restore the Application Control File from the backup on tape before you restore the application data sets. You may need separate procedures for on site and off site (disaster) restores.
- Periodically execute the REORG function of FDRARCH to delete obsolete entries from the ACF and compress it.
Examples of all of these steps follow. In the sample JCL shown, you may need to modify data set names, unit names, and other parameters to meet local requirements.
Create GDG bases in catalog example
For each application, you must execute this IDCAMS step one time to create the GDG bases used by that application. Every application using FDRAPPL must have a unique set of GDG bases for each Application Control File it uses. This example creates the GDG bases required by the following examples. The GDGs for the ACF backups on tape have a limit of five, to keep five generations of the backup of the ACF. You can change these values to suit the application's backup and recovery requirements.
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
DEFINE GDG(NAME(PAYROLL.APPL.ACFBKP1) LIMIT(5))
DEFINE GDG(NAME(PAYROLL.APPL.ACFBKP2) LIMIT(5))
/*
Initialize the application control file example
To use a permanent Application Control File, you must initialize it with the FDRARCH utility, described in Archive Maintenance Utility (FDRARCH). The following job stream must be executed one time for each Application Control File.
The USERINDEX=YES operand is required for FDRAPPL and instructs FDRAPPL to name the backup files it creates on tape using the high-level index of the Application Control File; the security user ID of the application must be authorized to create these data sets. This allows those backup files to be easily identified as belonging to this application. The rest of the name of the Application Control File is your choice.
If you use the automatic backup of the Application Control File at the end of each FDRAPPL, and you do not specify the file names for that backup with the ARCB1DSN= and ARCB2DSN= operands, the Application Control File name must have an index level of “ARCHIVE” somewhere in the name. The NODSNCK operand shown below prevents FDRARCH from insisting on an index level of “ARCHIVE”.
The value for RECS= depends on the total number of data sets that are ever recorded in the Application Control File, considering the number of data sets in the application and the number of backups you intend to keep. However, the Application Control File can contain several hundred data sets per track (292 on a 3380, 348 on a 3390) so the space required is usually small. Any excess tracks beyond those required to hold the indicated number of data sets is released.
One record in the ACF is required for each non-VSAM data set (multiple records are required for multi-volume data sets). VSAM clusters require one record per cluster for each volume it exists on, plus one record for each component on each of those volumes (for example, a single volume KSDS requires three records). This is multiplied by the number of backups that you intend to keep in the ACF, for example, daily backup of 140 non-VSAM data sets kept for 14 days requires 1960 records (six tracks on a 3390). Since your backup requirements may change, and since expired backups are not immediately deleted from the ACF, you should generously over-allocate the ACF.
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//ARCHIVE DD DSN=PAYROLL.APPL.BACKUP,UNIT=SYSALLDA,
// SPACE=(TRK,(10,5),RLSE),DISP=(,CATLG)
//SYSIN DD *
FORMAT NODSNCK,RECS=10000,USERINDEX=YES
/*
FDRAPPL with ARCBACKUP example
This is an example of an FDRAPPL job stream that includes a backup of the permanent Application Control File as the last file on the backup tape. ARCBACKUP=DSF is the default and does not need to be specified.
Since both TAPE1 and TAPE11 are present, two copies of the backup are created, so that one can be sent off site. The names of the backup tape files created start with the high-level index of the ACF, but the rest of the name is controlled by FDRAPPL, as shown in “Tape Format and Naming Conventions” in FDRAPPL-introduction. These files are not cataloged. They are retained for 14 days; the tape is expired by your tape management system at that time.
The ARCB1DSN= and ARCB2DSN= operands are included to specify the names of the tape files that contains the Application Control File backup; they are GDGs so that multiple copies of the backup are tracked. These files are cataloged when created.
All cataloged data sets matching the SELECT statements are backed up.
//SYSPRINT DD SYSOUT=*
//SYSPRIN1 DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//ARCHIVE DD DSN=PAYROLL.APPL.BACKUP,DISP=SHR
//TAPE1 DD DSN=PAYBKUP.APPL1,UNIT=TAPE,DISP=(,KEEP),
// VOL=(,,,255)
//TAPE11 DD DSN=PAYBKUP.APPL2,UNIT=TAPE,DISP=(,KEEP),
// VOL=(,,,255)
//SYSIN DD *
DUMP TYPE=APPL,ARCB1DSN=PAYROLL.APPL.ACFBKP1(+1), ARCB2DSN=PAYROLL.APPL.ACFBKP2(+1),RETPD=14,RTC=YES
SELECT CATDSN=PAYROLL.**
SELECT CATDSN=HOURLY.PAY*.**
/*
FDRAPPL without ARCBACKUP example
This is an example of an FDRAPPL job stream that does not backup the permanent Application Control File. If the Application Control File is required at a disaster site, it must be recovered by other means.
Since only TAPE1 is present, only one copy of the backup is created. The names of the backup tape files created start with the high-level index of the Application Control File, but the rest of the name is controlled by FDRAPPL, as shown in “Tape Format and Naming Conventions” in FDRAPPL-introduction. These files are cataloged (ARCCAT=ALL). They are retained for 30 days; the tape is expired by your tape management system at that time.
All cataloged data sets matching the SELECT are backed up. Because of CATLIMITGDG=1, for any GDGs that match the SELECT, only the current (0) generation are selected; the operand does not affect non-GDGs, they are all backed up.
//SYSPRINT DD SYSOUT=*
//SYSPRIN1 DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//ARCHIVE DD DSN=PAYROLL.APPL.BACKUP,DISP=SHR
//TAPE1 DD DSN=PAYBKUP.APPL1,UNIT=TAPE,DISP=(,KEEP),
// VOL=(,,,255),RETPD=30
//SYSIN DD *
DUMP TYPE=APPL,ARCBACKUP=NO,ARCCAT=ALL,RTC=YES
SELECT CATDSN=HOURLY.PAY*.**,CATLIMITGDG=1
/*
Restoring application data sets example
This is the job step necessary to restore all of the data sets that were backed up for an application. It can be used at your home site or with slight modifications at a disaster site. It assumes that the required Application Control File is on DASD; at a disaster site you need to recover the ACF before running this restore step (see “Restoring the ACF and Application Data Sets Example” in ).
It restores the latest backup for every data set recorded in the Application Control File. By default, it attempts to restore every data set to its original DASD volume. If it cannot be allocated there, the ABR RESTORE ALLOCATION LIST, if enabled, can specify alternate volumes (see “Panel A.I.6.1 Restore Allocation List” in Define-the-ABR-Protect-Lists-and-Restore-Allocation-List). The data sets do not need to be deleted or reallocated; FDRAPPL simply restores over them if they exist.
If you need to restore other than the latest copy, you may need to add ADATE= or OLDBACKUP= operands to the SELECT. In addition, if the application includes GDGs ABR may try to restore all recorded generations, so you may need to add ADATE= for the most recent backup date, so that older generations are not also restored (which may cause more recent generations to be deleted). You can specify DSN= on one or more SELECTS if only certain data sets are required.
If you are restoring at a disaster site, you may need to add COPY=2 to the RESTORE or SELECT statement if COPY2 is your off site copy. However, your installation may modify the FDR Global Options to make COPY2 the default for off site restores.
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//ARCHIVE DD DSN=PAYROLL.APPL.BACKUP,DISP=SHR
//SYSIN DD *
RESTORE TYPE=APPL,RECAT,VRECAT,DYNTAPE
SELECT ALLDSN
/*
Restoring the ACF and application data sets example
If the Application Control File required is not already on DASD, as it might be a disaster site, or after a hardware error at your home site, this two-step procedure can be used to restore the ACF, and then to restore the application data sets recorded in it. The input tape is mounted only once unless the backup used multiple tape volumes.
This job stream assumes that you have already restored the catalogs into which the backup of the Application Control File was cataloged. (If not, it is possible to restore the Application Control File by specifying DSN=, and VOL=SER= and UNIT= and LABEL=, if that information is available at the recovery site).
This example restores the COPY2 backup of the ACF, plus the COPY2 backups of all the application files; this is usually used at a disaster site, since COPY2 is usually sent off site.
Since the Application Control File is backed up in FDRDSF format, FDRDSF is used to restore it. This example restores it to its original volume, and allocates it there if necessary. Since the Application Control File is the only data set in this backup, SELECT ALLDSN restores it. If the original volume is not available, you need to specify the NVOL= operand to specify a new target volume.
See the previous example for notes on the Application Restore step.
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//TAPE1 DD DSN=PAYROLL.APPL1.ACFBKP2(0),DISP=(OLD,PASS)
//SYSIN DD *
RESTORE TYPE=DSF,RECAT SELECT ALLDSN
/*
//RESTAPPL EXEC PGM=FDRABR,REGION=0M
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//ARCHIVE DD DSN=PAYROLL.APPL.BACKUP,DISP=SHR
//TAPE1 DD DSN=PAYROLL.APPL1.ACFBKP2(0),DISP=(OLD,KEEP)
//SYSIN DD *
RESTORE TYPE=APPL,RECAT,VRECAT,COPY=2
SELECT ALLDSN
/*
Application control file maintenance example
With permanent Application Control Files, a job must be run periodically against each Application Control File to reorganize it, primarily to eliminate expired entries. This job should usually be run once a week, but it may be run more or less frequently, depending on how frequently FDRAPPL is run and the number of data sets dumped.
This example deletes all expired entries, those past their expiration date. This assumes that a retention period (RETPD=) or expiration date (EXPDT=) was specified at backup time as shown in the earlier examples. It is possible to specify other criteria for deletion such as MAXOCCURRENCES=nn to retain “nn” copies of each data set. In particular, if the application includes GDGs, you may want to specify MAXGENERATIONS=nn, so that only the appropriate number of generations are retained.
TAPE1 specifies a data set used to take a temporary backup of the Application Control File during the reorganization. It must be large enough to hold the entire contents of the ACF.
Details on the REORG function of FDRARCH are found in FDRARCH-REORG-Statement.
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//ARCHIVE DD DSN=PAYROLL.APPL.BACKUP,DISP=SHR
//TAPE1 DD UNIT=SYSALLDA,SPACE=(TRK,(10,5))
//SYSIN DD *
REORG DUMPDEVICE=DISK,SORT=YES,SORTALLOC=YES,DISABLE=DSNCK
/*