MVS TOOLS AND TRICKS OF THE TRADE JANUARY 2003 Sam Golob MVS Systems Programmer P.O. Box 906 Tallman, New York 10982 Sam Golob is a Senior Systems Programmer. He also participates in library tours and book signings with his wife, author Courtney Taylor. Sam can be contacted at sbgolob@cbttape.org. Information about the CBT MVS Tapes can be found on the web, at http://www.cbttape.org. TRICKS WITH TAPES - PART II - Tape Copying Tricks Last month, we introduced the concept of tape copying, as it ought to be. As we mentioned last month, there is a general misconception in the MVS computing world about what it means to copy an entire tape. A straightforward concept of copying all of a tape's data blocks, and the tape marks that separate the files, and which would create a "facsimile copy" of the entire tape, has been hidden from the public's view, in the name of "security". As a result, most public opinion about tape copying really is a concept of "tape file copying". And it completely obscures the simple process of making a tape copy that is identical, or nearly identical, to the content of the original tape. Very often in my career, I've asked seasoned MVS computer professionals the question: "What tool do you use to copy a tape?" And they've answered: "IEBGENER". I've never heard a sillier answer in my life. IEBGENER only copies one tape FILE. What about all the rest of the files? How do you know how many files there are, on that tape? And what about blocking considerations? Come on, let's get real! IEBGENER is at best, an awkward, inaccurate (because it now does automatic file reblocking without telling you), and incomplete tape copying tool at best. And we haven't even thought about the worst! This month, I'll try to clear that up. In addition, I'll present some tricks to make partial tape copies, and to move tape files from source tapes to target tapes, in whatever order you want them. There are proper tools to do all of that. You can have free tools to list the contents of a tape, or to make tape copies. These can be found on the CBT Tape collection, at www.cbttape.org . Some of those tools are COPYMODS and COPYFILE (from File 229 of the CBT Tape), TCOPY (from File 193), TAPESCAN (from File 102), and TAPECOPY (from File 174). Tools to strip labels from an SL (Standard Labeled) tape, to make a NL (non-Labeled) tape, are: COPYSLNL and COPYMODS with its STRIP option. (Both these programs are on File 229.) Partial tape copies can be made, using the COPYFILE, COPYSLNL, and COPYNLNL programs from File 229, and the COPYMODS program also has a capability of limiting the number of files to be copied from the input tape. If you're interested in a vendor-supported tape copying and tape listing tool, one of the most excellent packages is TelTape from Cartagena Software (www.cartagena.com). TelTape has a full ISPF interface to browse the contents of tapes and copy them--and TelTape allocates tape volumes dynamically. Using TelTape, you can look at what's in a tape, or copy it interactively, as well as in a batch job. Unlike the free tape manipulation products, TelTape is designed to work together with your tape management system, and it can automatically update system catalogs if necessary. TelTape, besides being an extremely versatile batch and interactive tape utility, also is a heavy duty tape migration tool, that can copy thousands of tapes. TelTape will update the system catalogs and tape management databases, while retaining the original tape creation dates, jobnames, and expiration dates. TelTape is ATL (Automated Tape Library) aware. For a general vendor tape utility, TelTape is definitely a package well worth looking into. TAPE LABELS, EXPOSED We mentioned last month, that the tape labels on a SL tape, are hidden by the operating system from general view. For our purposes, it is very important that all of us should know what is in a tape label. Of course, I'm talking about the IBM-format EBCDIC tape labels that are in general use by the MVS operating system. Our IBM reference books will be the "Using Magnetic Tapes" manual, which for DFSMS on OS/390 systems has the designation SC26-4923, and for z/OS systems it has the designation SC26-7412. The information we want, is in Chapter Two of either book. In a Standard Labeled tape, each tape data file is sandwiched between two tape label files. So each "file" on a SL tape is actually three files: the header label file, followed by the tape data file, followed by the trailer label file, with one tape mark in between each, to separate the files. The label file records (also known as "the labels") are always 80-bytes long and unblocked. IBM convention specifies that all the field contents of the labels be EBCDIC and printable, so you won't find any packed or binary number fields in tape labels. This is an important fact to know, and it makes reading the tape labels much easier. At the beginning of every tape label, for four characters, is an identifier field indicating the type of label it is. This will also tell the operating system what format to look for, in the rest of the label. The typical label types are VOL1 (for a volume label), HDR1 (for the first header label), HDR2 (for the second header label), EOF1 (for the first trailer or end-of-file label), EOF2 (for the second trailer label) and so forth. Additionally, if a SL tape is to be continued on another volume, EOV1 (first end-of-volume) and EOV2 (second end-of-volume) labels are created by the operating system at the end of the tape volume. HDR1, EOF1, and EOV1 labels have the same format as each other. HDR2, EOF2, and EOV2 also have a common format. Generally speaking, one might characterize the HDR1 and EOF1 labels as containing external operating system and device-dependent data that relates to the data set, such as its name, file sequence number, creation and expiration dates, and (on the trailer labels) block count in the file. The HDR2 and EOF2 labels contain more specific data set characteristics, such as the type of information contained in the DCB, JFCB, and UCB control blocks for the dataset, with the creating jobname and stepname. Both types of labels are used to identify and describe the data set and to protect it from unauthorized use. RACF or whatever security system you have, interacts with this information. So does the MVS Operating System itself. The format of the trailer labels is identical to the format of the header labels, except for the fact that the EOF1 and EOV1 labels contain actual block counts, as opposed to the HDR1 labels, which contain zeroes in the low order block count field, and blanks in the high order block count field. The reason for that, is that sometimes a tape is read backwards, and this symmetry is built into the label formats so the operating system has no trouble reading a tape in either direction. This concludes our general description of tape label contents. For the details, see either of the "Using Magnetic Tape" books mentioned above. COPYING PARTS OF TAPES For argument's sake, let's start our discussion with a feature of the COPYMODS program (from File 229 of the CBT Tape), whose principal reason for being, is to make "Xerox copies" of entire tapes. Suppose we have a SL tape that contains 50 files, and we want to copy only its first 27 files. We can create some COPYMODS JCL (illustrated in Figure 1) and code FILELIMIT=27 in a SYSIN card. What happens when we run the job? From our discussion above, we know that a Standard Labeled tape really contains three times as many files as its stated number, because each data file is sandwiched between two label files. So on a SL tape, to copy 27 files, you really have to copy 27 times 3, or 81 files. However, on a NL tape, which does not contain any label files, you just have to copy the stated number, or 27 files. How does COPYMODS tell the difference? COPYMODS, when asked to do file limitation, does an initial OPEN, REWIND, and READ of the input tape. Thus it determines if the first record on the tape is a VOL1 label. If so, COPYMODS assumes that the tape is SL, and it internally multiplies the coded FILELIMIT number by 3. Otherwise, COPYMODS leaves the FILELIMIT number as stated, and assumes that the input tape is NL. Whatever the final outcome of this process, COPYMODS copies the resulting number of files from the input tape, then CLOSEs the input tape and output tape(s). So, on a basic level, you see the trickiness of having to copy parts of a tape. On a labeled tape, one file is really three files, and a mindless program (such as COPYNLNL), which is told to copy file numbers, will do what it was told. The result you get, might not be the result you want. Therefore, some "foolproof factors" are built into tape copying programs which copy SL tapes. For example, if you use the COPYFILE program to copy some files from an SL tape to another SL tape, and the input tape you mount is NL, COPYFILE will kick it down. That's because COPYFILE, which is designed only for SL tapes, when it copies a "file", really handles all three files that are in the sandwich. With COPYFILE, as with most programs that copy SL tapes, the needed safeguard has been built in. HOW YOU CAN MAUL AN OUTPUT TAPE In this section, we'll use the three related programs, COPYFILE, COPYSLNL, and COPYNLNL, to illustrate the principles we want to show. All three of these programs use the same JCL and control cards, except for the program name. COPYFILE (the original program of the three) can copy selected files from an input SL tape, to another output SL tape. The particular files copied, are determined by control cards, usually containing numbers, in the SYSIN DD card. For example, if you want to copy file 56 from an input tape, to file 7 of the output tape, you code 56/7 in the SYSIN DD card. COPYFILE has a help member in File 229, which explains the use of the control cards, so you can refer to that for further reference. You can see sample COPYFILE JCL, in Figure 2. I adapted the other two programs, COPYSLNL and COPYNLNL, from the COPYFILE program. All three programs use the exact same control cards to determine which files you want the program to copy. However, COPYSLNL takes an input SL tape, and creates an output NL tape by only copying the data file to the output tape, and skipping the copy of the two label files that are before and after it. COPYNLNL does another thing entirely. COPYNLNL makes no assumption whether a tape is SL or NL, assuming all tapes to be NL. COPYNLNL "mindlessly" copies all the files you told it to (whether they are label files or data files), only stopping after two consecutive tape marks on the input tape. Of course I intended COPYNLNL only to be used for NL tapes. But I didn't put any of the usual safeguards into it. All three of these programs have to run authorized, since they do a RDJFCB and change the JFCB copy, before the OPEN TYPE=J, so that the BLP attribute is forced on, no matter what you coded in the JCL. That operation needs APF authorization. So you see that all these programs can just copy tape files, no matter whether they are data files or label files. Now, let's get to the "mauling" part. The most extreme case of tape mauling that I can think of, is to take a multi-file SL tape, and use COPYNLNL to create an output tape consisting of a hodgepodge of tape labels and data files, out of the correct order. You can even make an output tape consisting of only labels. For example, with COPYNLNL, copy files 1, 3, 4, 6, 7, 9, and so forth, from an SL tape. By doing that, you've skipped over the data files, and only copied the label files. Actually, that idea was the inspiration for inventing the LABLDUMP feature of COPYMODS, where you can dump all the tape labels out to an external file, and the LABADDIN feature of COPYMODS, where you splice these labels back into a NL version of the same tape, re-creating the SL tape from the NL tape and the set of labels. By the way, the new STRIP option of COPYMODS will clean up a mauled tape like the first one above. The STRIP option of COPYMODS will read an input tape, detect which files are label files and which are not, wherever they are, and only copy the data files--not the label files. So you're left with a clean NL tape that has only data files. A more typical case of tape mauling, which usually happens by accident, is worthy of mention. It occurs when you're writing a tape, and you close it in the wrong place. I can create an example of this purposely, using COPYMODS. And I can cure it too, using COPYMODS. We mentioned the FILELIMIT=nnn SYSIN card in COPYMODS before. This card limits how many files we copy, when we copy a tape. There are two new option keywords in COPYMODS, to force this limit to be either SL or NL, no matter whether the input tape is really SL, or NL. These are: NLLIM, which forces the FILELIMIT number to be regarded as NL, and SLLIM, which forces the FILELIMIT number to be regarded as SL, and multiplied by 3. So if you ran COPYMODS to copy an SL tape, and used the NLLIM keyword, and made the FILELIMIT number a non-multiple of 3, you've effectively mauled the end of the output tape, either by ending it just after writing the header labels, or by ending it after writing a data file without writing the trailer labels that should follow. We can usually detect conditions like this, by mapping the tape with the TAPESCAN program from File 102 of the CBT Tape. TAPESCAN will show the last file, without the following tape labels, or it will show the last header labels, without the following data file. If you really want to become an expert at tape copying tricks, I'll leave you with the example of how to cure the problem, when you have a tape that doesn't have the final trailer labels. One way is to use COPYMODS to STRIP the labels off and make a NL tape, while at the same time doing a LABLDUMP to dump all the labels to a file. You can then either edit the label file before you do LABADDIN processing with the CORRBLKS and BLKCNT options on, and splice the final trailers back in, or you can use the LBLFIX parameter, that will reconstruct the last set of trailer labels out of the last header labels, plus the measured block count of the last data file. So now you've now seen some wonders that you can do to tapes. These wonders have been largely made possible by the fact that you can copy tape blocks, and generally control tape processing very closely, by using the EXCP access method against tapes. In the last part of this 3-part series next month, I'll explain a lot of the nitty-gritty of how EXCP processing is done, and you'll see that it's a lot simpler than you may have thought. Good luck to you. I'll see you then. * * * * * * * * * * * * * * * * * * * * * * * Figure 1. Sample JCL to run the COPYMODS program. COPYMODS is now at Level 052, and it is recommended to use version Level 050 or higher. //* insert JOB card here //******************************************************************// //* COPYMODS FILE LIMITING RUN *// //******************************************************************// //* //COPY EXEC PGM=COPYMODS,REGION=4096K,PARM=SYSIN (Now not necessary) //STEPLIB DD DISP=SHR,DSN=your.steplib //LABLDUMP DD DISP=SHR,DSN=userid.CBT.CNTL(C454LAB2) //SYSPRINT DD SYSOUT=* //IN DD VOL=SER=C454MU,DISP=OLD,UNIT=CART,LABEL=(,BLP,EXPDT=98000) //OUT1 DD VOL=SER=SML454,DISP=OLD,UNIT=CART,LABEL=(,BLP,EXPDT=98000) //SYSIN DD * FILELIMIT=27 CUMSEP LABLDUMP LABELS /* * * * * * * * * * * * * * * * * * * * * * * * Figure 2. Sample COPYFILE JCL. JCL and control cards to run COPYSLNL and COPYNLNL are identical, except for the program name in the EXEC card. See CBT Tape File 229, for a HELP member that explains all the COPYFILE control cards. //* insert JOB card here //COPYSTEP EXEC PGM=COPYFILE,REGION=4000K,PARM='TAPEL' //STEPLIB DD DISP=SHR,DSN=your.steplib //MSG DD SYSOUT=* //TAPELOUT DD SYSOUT=* //SYSABEND DD SYSOUT=* //IN DD DSN=INPUT.FILE,UNIT=CART,DISP=SHR,LABEL=EXPDT=98000, // VOL=SER=FROMVL //TAPELIN DD DSN=OUTPUT.FILE, // UNIT=(CART,,DEFER),VOL=(,RETAIN,SER=TOVOL1), // DISP=(NEW,KEEP),LABEL=EXPDT=98000,DCB=TRTCH=COMP //SYSIN DD * 1/1 -700 /*