BKBYVTOC Utility Program

Purpose of the utility

This program is designed to automate backing up files from disk volumes on MVS3.8J systems.

It will generate all the backup jobs needed to backup all catalogued files on the disk volsers you select. It currently only supports backup of partitioned(PO) and physical-sequential(PS).

Features

• Scans the disk VTOC to locate all DSORG=PS and DSORG=PO files to be backed up. You don't need to know what files are on the volume(s).
  You can provide an optional EXCLUDE DD card to provide dsname masks for files you do not want backed up.
• Produces a backup report listing showing what has been backed up from disk which includes the file position on the tape, the file name, the origional disk volume, the file DSORG, RECFM, LRECL and BLKSIZE from the disk file (which you will need if you want to restore anything). This listing is also stored at file position 001 on every tape used for the backup so you can't lose it; which does require that the backup listing be written to a dataset or PDS member and the program will check for and refuse to use a JES2 spool dataset for this output,
• Produces a "skipped file" report that shows what files on the volume(s) were not selected for backup that you can review for anything unexpected.
  Skipped files are currently any dataset not PO or PS type, any file that is not catalogued (uncatalogued files, vsam files, system work files that may be on the pack etc are skipped) and any files matching dsname masks provided via the exclude dd card.
• Creates as many backup jobs as needed to perform the backup; or to put it another way it handles the MVS3.8J limitation of only allowing 254 job steps per job and will create additional jobs as needed.
  Notes: each seperate job will use a different tape, and I have arbitrarily decided job breaks are at step 250; in case I add to add a few more steps to my templates (one step already exists for the initial tape mount request)
• The backup jobs are built from a job template that defines the two required procedures (BKPPS and BKPPO) needed to perform the backup.
  Not only does that make it easy for you to customise but theoretically means it should be easy to modify the program to handle other filetypes as needed by adding the appropriate procedure to the template and tweaking the code to not ignore the new filetype
• Is very simple to use. You can start using it immediately with just the supplied template and testjob.

Sample JCL

You can't get much simpler than this. This job backs up four packs, if you want to backup more with each job then just add additional DDnn cards. The four CBT packs on a TK3 system have enough files on them to demonstrate multiple job creations.

//MARKBKPJ JOB  (0),'BACKUP 4 PACKS',CLASS=A,MSGCLASS=A
//BKBYVTOC EXEC PGM=BKBYVTOC
//DD1      DD   UNIT=3350,VOL=SER=CBTCAT,DISP=OLD
//DD2      DD   UNIT=3350,VOL=SER=CBT000,DISP=OLD
//DD3      DD   UNIT=3350,VOL=SER=CBT001,DISP=OLD
//DD4      DD   UNIT=3350,VOL=SER=CBT002,DISP=OLD
//SKIPLIST DD   SYSOUT=*
//BKPLIST  DD   DISP=(NEW,CATLG,DELETE),
// DSN=MARK.TEST.BKBYVTOC,
// UNIT=3380,VOL=SER=PUB002,
// DCB=(DSORG=PS,RECFM=FBA,LRECL=80,BLKSIZE=3200),
// SPACE=(CYL,(2,1))
//JCLOUT   DD   SYSOUT=(A,INTRDR)   FOR LIVE RUN
//TEMPLATE DD   DISP=SHR,DSN=INSTALL.UTILS.BKBYVTOC(TEMPLAT1)
//EXCLUDE  DD   *
CBTCOV.FILE039
MARK.EXCLUDE.ME1
MARK.EXCLUDE.ME2
/*
//

One thing of note. There is additional code in BKBYVTOC to handle output to an existing PDS dataset (ie: 'xxx.xxx(mbrname)') rather than seperate flat files as I needed that functionality for a while. I have left it in as I will probably need it again at some point; feel free to remove it from your copy if you will never have that requirement.

The template file

As mentioned above the backup jobs are built using a template file that defined the BKPPS and BKPPO procedures. This allows you a great deal of customisation with minimal effort.

The only requirements for the template files are the four points listed below. Refer to the sample template member for a working example.

• Must have a valid jobcard, and ensure you have 8 bytes for the jobname, note: if you use RAKF and have removed all access for the default PROD (batch) class as I have, also include the USER=/PASWORD= fields on your template jobcard for a user that can read the files on the volsers (and put the template in a dataset only batch jobs can read)
• Must have a procedure BKPPO, for partitioned dataset backup
• Must have a procedure PKPPS, for sequential dataset backup
• Both procedures must accept parms of D= and LABEL= which are used for the dataset to be backed up and the file position it is to be written to on the tape

The supplied template member TEMPLAT1 provided shows how the job template can be used to initially mount a tape and retain it, and all the backup steps can then referback to that tape to avoid repeated tape mounts.

Obtaining the program(s)

The program is provided as a single JCL deck that will create an install dataset with the assembly jobs and source for all the programs, test jobs and sample templates.

The BKBYVTOC program does not need to be in a APF authorised library if you wish to use that on its own.
The additional MDEXWRAP needs to be authorised if it is to wrap iebcopy as the iebcopy code getmains into the higher subpool ranges that non-authorised programs cannot reach

Read the comments at the top of the job to see what you should customise before running the JCL; and the $DOC member after install (or by viewing the text file (searching for $DOC) to see what is needed to get it running after the install.

The JCL deck to use to install the utility and the program itself of course come with no warantee of suitability. As always use at your own risk.
The JCL deck uses UNIX line feeds, don't open it in notepad :-).

Additional utilities

There are additional programs and scripts I have been using to try to permit me to fully automate restores. To avoid cluttering the main BKBYVTOC jobdeck the additional programs are in a seperate jobdeck, they are (or will be) useful to me but possibly not to anyone else.

I use some of the programs in here to post process the bkbyvtoc output with a list of the actual tapes allocated for the backups to get a complete combined listing of what I have backed up, write that to a hercules pipe printer to get the report as a linux text file, and use the text file as data for a php webpage that is used for point-and-click on-demand restores. If you have a webserver running on the same Linux server as your hercules system you might want to look at these. The php code and bash pipe printer script are included in the jobdeck.
One day there will probably be a clist to request a restore, followed by a full screen 3270 program; but thats in the future, just check back every six months.