ARCHIVER - Back-up/Restore Utility for PDS Members

The ARCHIVER is a batch utility program to back-up and restore PDS and PDSE members in the MVS/ESA, OS/390 and z/OS environments. The ARCHIVER can perform full or incremental back-ups under the control of an end-user or of an automated job scheduler. The ARCHIVER uses a dedicated PDS or PDSE as its back-up repository.

The ARCHIVER provides four functions: BACKUP, PARMLIB, RESTORE and RECOVER

BACKUP reads the libraries (PDS or PDSE) specified by the user and saves a copy of the members which are new or whose content has been modified since the last back-up. BACKUP also keeps track of members which have been deleted, renamed, packed, unpacked, or whose ISPF statistics have changed. BACKUP can run in FULL mode at regular intervals (e.g. weekly or monthly) and in INCREMENTAL mode at more frequent intervals, such as daily.
PARMLIB backs-up the system PARMLIB libraries like BACKUP. ARCHIVER automatically retrieves the data set names of all the PDSes and PDSEs which are currently used on the system. As a result, these data set names do not need to be specified in the JCL, as shown in the example below.
RESTORE recreates an entire library by playing previous back-up operations in reverse order. Individual members can be easily restored using the ISPF COPY service.
RECOVER retrieves PDS members which have been deleted or updated and writes the data out to SYSPUNCH as an IEBUPDTE input stream. If the PDS directory was overlayed by accident, RECOVER is able to extract the data for all the members.

The ARCHIVER is designed to give application programmers and consultants an easy way to take incremental back-ups of their critical libraries. Unlike DASD management tools like HSM or ABR which back-up entire libraries at a time, the ARCHIVER only backs-up new or modified members. As a result, the ARCHIVER can be used several times a day to back-up the same libraries, generating small amounts of archival data in the process.

Restrictions

Currently, the ARCHIVER does not support load-libraries, or libraries whose LRECL is greater than the LRECL of the archive data set.
The RECOVER function only supports PDS libraries, i.e. RECOVER does not support PDSE libraries.

Running the PDS Archiver

The ARCHIVER runs as an MVS batch job. Its processing is controlled via the PARM field of the EXEC statement, as shown in the JCL examples below.

PARM Field (BACKUP/RESTORE)

The format of the PARM is function,index,dsname,volume,noalias.

function must be specified as BACKUP, PARMLIB, or RESTORE.
index is the optional member name of the index in the archive data set. The default name is $$$INDEX.
dsname and volume apply to the RESTORE function only and specify the dsname and optional volume serial of the original library to be restored into the SYSLIB data set.
noalias is an optional parameter for the BACKUP function which must be specified as NOALIAS. When NOALIAS is specified, the ARCHIVER will not create ALIAS entries in the archive data set for input members with matching CRCs. If NOALIAS is not coded, then the ARCHIVER creates ALIAS entries for input members when their CRC matches the CRC value of a member already stored in the archive data set.

DD Statements (BACKUP/PARMLIB/RESTORE)

The ARCHIVER requires the presence on three DD statements in the JCL.

A SYSPRINT DD which it uses to write messages and statistics.
An ARCHIVE DD allocated to the archive data set.
A SYSLIB DD allocated to the input user libray or concatenation of user libraries to be backed-up, or to the output library into which the library specified in the PARM will be restored.
- In a BACKUP operation, a concatenation of RECFM=FB and RECFM=VB libraries is permitted, with hundreds of data sets. If data set names include member names, only the specified members are archived. Each PDS or PDSE specified in SYSLIB is processed independently, and different libraries can contain members with the same name.
- In a PARMLIB operation, SYSLIB is not specified. Instead, the ARCHIVER issues a system request to retrieve the names of the PARMLIB libraries specified in SYS1.IPLPARM(LOADxx).
- In a RESTORE operation, SYSLIB only specifies a single library; OPTCD=R can be specified to empty the output library before writing members into it.

Archive Data Set

The ARCHIVER uses a dedicated PDS or PDSE called the Archive Data Set to store archived members and its index. The Archive Data Set is a permanent partitioned data set allocated with RECFM=FB; the minimum value for the LRECL is 80 and the maximum is 255. Members in the the Archive Data Set are exact duplicates of the members of which they are a copy, and can be accessed via TSO, ISPF, or any MVS utility able to process PDS members. If OPTCD=L is specified on the ARCHIVE DD statement, the BACKUP function of the ARCHIVER stores the archived members in compressed format, compatible with the PACK option of ISPF/PDF. Specifying OPTCD=L typically cuts DASD requirements in half for the Archive Data Set.

When OPTCD=R or OPTCD=RL is specified on the ARCHIVE DD statement for a BACKUP operation, the ARCHIVER resets the Archive Data Set to empty when it starts processing. As a result, the existing index is ignored, and a full back-up is performed. If OPTCD=R is not specified, then an incremental back-up is performed if the index member exists already.

The format of the index member (which, by default, is called $$$INDEX) is plain text; the index can be BROWSEd or VIEWed under ISPF/PDF. The index is created by the ARCHIVER when it performs a full back-up, and extended when the back-up is incremental. The index should not be modified by the user.

Sample JCL

The ARCHIVER runs as a batch job in the MVS/ESA, OS/390 and z/OS environments.

BACKUP Example - Full

//ARCHIVER JOB (ACCT#),'Archive PDS Members',
// NOTIFY=&SYSUID,
// CLASS=A,MSGCLASS=X
//JOBLIB   DD DSN=<ARCHIVER load library>,DISP=SHR
//*
//*	Create Full Back-up of Specified Libraries
//*
//BACKUP  EXEC PGM=ARCHIVER,PARM=BACKUP
//SYSPRINT DD SYSOUT=*
//*
//*	Input Libraries
//*
//SYSLIB   DD DSN=USER.PARMLIB,DISP=SHR
//         DD DSN=JOHNDOE.APPL2.CNTL(CONTROL),DISP=SHR
//         DD DSN=JOHNDOE.APPL2.CNTL(OPTIONS),DISP=SHR
//         DD DSN=JOHNDOE.APPL2.SOURCE,DISP=SHR
//         DD DSN=JOHNDOE.APPL2.COPYLIB,DISP=SHR
//*
//*	Archive Data Set
//*
//*	OPTCD=R : empty the archive data set at start of processing.
//*	OPTCD=L : pack the members in the archive data set
//*
//ARCHIVE  DD DSN=JOHNDOE.ARCHIVE,DISP=SHR,OPTCD=RL

BACKUP Example - Incremental

//*
//*	Create Incremental Back-up of Specified Libraries
//*
//BACKUP  EXEC PGM=ARCHIVER,PARM=BACKUP
//SYSPRINT DD SYSOUT=*
//*
//*	Input Libraries
//*
//SYSLIB   DD DSN=USER.PARMLIB,DISP=SHR
//         DD DSN=JOHNDOE.APPL2.CNTL(CONTROL),DISP=SHR
//         DD DSN=JOHNDOE.APPL2.CNTL(OPTIONS),DISP=SHR
//         DD DSN=JOHNDOE.APPL2.SOURCE,DISP=SHR
//         DD DSN=JOHNDOE.APPL2.COPYLIB,DISP=SHR
//*
//*	Archive Data Set
//*
//*	OPTCD=L : pack the members in the archive data set
//*
//ARCHIVE  DD DSN=JOHNDOE.ARCHIVE,DISP=SHR,OPTCD=L

RESTORE Example

//*
//*	Restore a PDS from the Archive Data Set
//*
//BACKUP  EXEC PGM=ARCHIVER,PARM='RESTORE,,JOHNDOE.APPL2.SOURCE'
//SYSPRINT DD SYSOUT=*
//*
//*	Archive Data Set (Input)
//*
//ARCHIVE  DD DSN=JOHNDOE.ARCHIVE,DISP=SHR
//*
//*	Restored Partitioned Data Set
//*
//SYSLIB   DD DSN=JOHNDOE.APPL2.SOURCE.OLD,DISP=(,CATLG),
// SPACE=(TRK,(350,50,88),RLSE),UNIT=SYSALLDA

PARMLIB Example

//*
//*	Back-up System PARMLIB
//*
//PARMLIB EXEC PGM=ARCHIVER,PARM=PARMLIB
//SYSPRINT DD SYSOUT=*
//*
//*	Archive Data Set (Output)
//*
//ARCHIVE  DD DSN=SYS2.PARMLIB.ARCHIVE,DISP=SHR

RECOVER Function

The RECOVER function of the ARCHIVER retrieves data for deleted PDS members, or for old versions of recently-updated members. This is often possible because the space occupied by a deleted member (sometimes referred to as a gas member) remains unchanged and its content available until the PDS is compressed. To retrieve gas members, the ARCHIVER scans the entire PDS for data which does not correspond to an existing directory entry, and copies it to the SYSPUNCH data set as an IEBUPDTE input stream. The SYSPUNCH data set is a sequential data set which can be BROWSEd, VIEWed or EDITed in ISPF, or used as input to IEBUPDTE or PDSUTIL to load the data into PDS members. If the directory of the PDS from which the data was recovered is still available and large enough, then the data can be loaded into the same PDS; otherwise, the data can be loaded into a different PDS or PDSE.

The input PDS must be allocated to SYSLIB and may contain fixed-length or variable-length records of any size. The data for each gas member written to SYSPUNCH is preceded by a ./ ADD NAME=Ztttttrr statement where ttttt is the relative track number of the member, and rr the record number of the first block of data. The ARCHIVER lists recovered members on SYSPRINT in tttttrr sequence, interspersed with the current directory entries for orientation. The list also indicates the position of the data set's current end-of-file mark (as indicated in the DS1LSTAR field of the data set's format-1 DSCB) to help distinguish between gas members that were created before or after the last compress operation.

By default, the RECOVER function stops looking for gas members at EOF, i.e. when it reaches the end-of-file mark (DS1LSTAR). When PARM='RECOVER,EOF=CONTINUE' is specified, RECOVER ignores DS1LSTAR and scans the data set until it reaches the end of the allocated space, or until an I/O error occurs.

The RECOVER function of the ARCHIVER processes the SYSLIB PDS in read-only mode and does not require the directory to exist. Consequently, if the directory was overlayed by accident, the ARCHIVER will recover the data for all the members, starting after the first EOF mark in the PDS.

The ARCHIVER expects the RECFM, LRECL and BLKSIZE attributes of the SYSLIB PDS to be consistent with its content. If these attributes have been corrupted, then the appropriate values must be specified on the SYSLIB DD statement.

Gas members in ISPF PACK format are automatically unPACKed when read from SYSLIB. However, it is common for the first gas member after the EOF to be truncated, preventing it from being successfully unPACKed.

The RECOVER function of the ARCHIVER does not support recovering members from a PDSE or a load library.

//*
//*	Recover Deleted Members from a PDS (Stop at EOF)
//*
//RECOVER  EXEC PGM=ARCHIVER,PARM=RECOVER
//SYSPRINT DD SYSOUT=*
//*
//*	Input PDS (Read-Only)
//*
//SYSLIB   DD  DSN=USER.PARMLIB,DISP=SHR
//*
//*	Output data set in IEBUPDTE format
//*
//SYSPUNCH DD  SYSOUT=*

//*
//*	Recover Deleted Members from a PDS (Ignore EOF)
//*
//RECOVER2 EXEC PGM=ARCHIVER,PARM='RECOVER,EOF=CONTINUE'
//SYSPRINT DD SYSOUT=*
//*
//*	Input PDS (Read-Only)
//*
//SYSLIB   DD  DSN=USER.PARMLIB,DISP=SHR
//*
//*	Output data set in IEBUPDTE format
//*
//SYSPUNCH DD  DSN=JOHNDOE.USER.PARMLIB.RECOVER,DISP=(,CATLG),
//	UNIT=3390,SPACE=(TRK,(100,100),RLSE),
//	RECFM=FB,LRECL=80,DSORG=PS

Messages

ARC00I PARM Specified for this Run: 'parameters'

ARC01E ** ERROR ** Invalid PARM Field

ARC02E ** ERROR ** Archive Data Set missing or invalid

ARC03I Entries read from Index: nnnnn

ARC04E **ERROR** Data Set dsname on Volume volser has invalid DCB Attributes

ARC05E **ERROR** SYSLIB DD Missing

ARC06E ** ERROR ** Directory is full - DDN=ddname

ARC07I Entries read from Index: nnnnn

ARC12I DDNAME(ARCHIVE) IS ALLOCATED TO DSNAME=dsname,VOL=33x0=volser

ARC13I DDNAME(SYSLIB) IS ALLOCATED TO DSNAME=dsname,VOL=33x0=volser

ARC18E Error from IEFPRMLB: Retcode(nnn)Rsncode(X'nnnnnnnn')

ARC21I Now starting to archive SYSLIB members

ARC44I Statistics for current archival operation:
        LIBRARIES PROCESSED . . . nnnnnnnn
        MEMBERS PROCESSED . . . . nnnnnnnn
        MEMBERS ARCHIVED  . . . . nnnnnnnn
        MEMBERS DELETED . . . . . nnnnnnnn
        ALIASES CREATED . . . . . nnnnnnnn

ARC45E ** ERROR ** Member ',member, not found in Archive Data Set

ARC46E ** ERROR ** Directory is full - DDN=ddname

ARC48I Members restored . . . . nnnnnn

ARC49E ** ERROR ** dsname Data Set missing or invalid

ARC82E Error opening the SYSLIB data set, RC=20

ARC85E RECFM=U not supported for RECOVER, RC=20

ARC83W The directory of the SYSLIB PDS appears invalid.

ARC84I The Directory contains nnnnnn Member(s) and nnnnnn Alias(es).

ARC88I nnnnnn Members and nnnnnnnn Records recovered

ARC98I ELAPSED TIME: nnMnnS    CPU TIME: nn.nn      CPU RATE: nn.n%
ARC98I CONNECT TIME: nnnnn    I/O COUNT: nnnK       I/O RATE: nnn.n
ARC98I REGION ALLOCATED: nnnnK,nnnnnK      REGION USED: nnnK,nnnnK

ARC99I End of processing, RC=nnn

Search key-words: ibm mainframe legacy multiple find undelete version unerase erase erased corrupted destroyed damaged changed replaced saved resurrect resurrecting protect protection protecting retrieve retrieving rescue recovery rescuing rescueing ttr ttrs ttrn dsorg=po po-e PDS/E hsm dfhsm df/hsm dfsmshsm migrate hmigrate hmig recall hrecall cobol over-written overwritten tips tracking updates CA-PDSMAN