MVS TOOLS AND TRICKS OF THE TRADE APRIL 2008 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. TAPE MAPPING, TAPE MEASURING, TAPE COPYING Physical tapes have not gone away yet. Nor are they likely to go away in the foreseeable future. Even though we don't deal with tapes nowadays as often as we used to, I think it is still valuable for us to know something about the structure, measuring, and mapping of a "tape", whether it be a real tape, or a "virtual tape" in a Virtual Tape Library, or whether the physical media is on an old-style reel, or on a cartridge. Tapes are still a part of our lives, and we ought to have the tools to look at what's inside them and to analyze them. Back when I first started, I'd look at a tape, and the only way I'd know anything about what was on it, was by looking at the physical paper label (if it had one). A bunch of tapes in a pile, have a funny way of "looking identical to each other" unless there are paper labels on them. Later, I learned about tools which can read what kind of contents a tape has, even if it doesn't have a paper label. These are the "tape mapping" tools. Then there are the "tape copying" tools, which copy the contents or data blocks from one tape to another, faithfully reading each block from the input tape, and copying it to one or more output tapes afterward. What do "tape mapping" programs and "tape copying" programs have in common? Let's look. Since both of these kinds of programs will operate by reading an "input tape", they will also be capable (potentially) of measuring the tape and looking at the tape's data as they are reading each block. So if you program them properly, this class of programs is exposed to information that can tell you about how much tape data there is, what the data is, and how big each of the data blocks is, in each tape file. These programs share the common mechanism of reading all the blocks on a tape. After they do that, it just depends on how the program is made to evaluate the data that it has been exposed to. Therefore, as they are reading data from each tape block, these programs can be made to examine and analyze that data, measure the size of the blocks, and count the blocks at the same time. It all depends on the programming which is used to ANALYZE or DISPLAY the tape blocks as they pass through the program. The kind of programming necessary to accomplish these various tasks, and tell us what we want to know about a tape, is what we are going to talk about next. READING TAPE DATA BLOCKS Most tape mapping and tape copying programs use either the EXCP (EXecute Channel Program) or BSAM (Basic Sequential Access Method) access methods to read the tape blocks. You can use QSAM (Queued Sequential Access Method) to read tape blocks, but QSAM is not practical to use for tape mapping and copying programs in most cases, because when you encounter an unknown tape, you don't know in advance, what its record structure will be like. The BSAM and EXCP access methods are much more flexible regarding that. QSAM requires some previous knowledge of the record structure which will be read. Remember that tapes are one-dimensional and sequential in structure. Using EXCP is the most "native" or "assembler-like" way of doing I/O programming. BSAM is a bit more like a higher-level language. With BSAM you use READ and WRITE macros, and you don't directly access the tape device's operation codes. With EXCP you do. Therefore, if you are using EXCP to read a tape, you have to know the specific device operation codes that can manipulate the tape device. EXCP operation codes for tape drives can be found in the tape hardware manuals, such as the 3480 or 3490 hardware manuals, but I'll summarize a few of them that we use often. X'02' is to READ a block of data from the tape. X'01' is to WRITE a block of data to the tape. X'03' is a "no operation" or a NOOP which does nothing (but you need it as a placeholder and for status reporting when you write channel programs). X'3F' is to forward space the tape (FSF) for one or more files. X'2F' is to backward space the tape (BSF) for one or more files. X'07' is the REWIND code, to rewind the tape to the beginning. X'27' is to backspace one or more blocks (BSB). X'37' is to forward space one or more blocks (FSB). X'1F' is to write a tape mark (which separates between tape files). These are most of what we need in a tape mapping or tape copying program. These operation codes are incorporated into "Channel Command Words" or CCWs, which are the individual instructions to the tape device. Strings of CCWs are incorporated into "Channel Programs" that are executed by the EXCP instruction, but more on that, later. Included in the CCWs are a 3-byte data area address (4 bytes for Format 1 CCWs) to read the data into, or to write the data from). At the end of the CCW is a halfword count field, which for READ or WRITE operations means the number of bytes to read or write. Included also, is a bit called the SILI bit, which (if it's on) tells the CCW that the READ or WRITE count is only a maximum, but if the CCW runs out of bytes while it is executing a READ or a WRITE, it should stop, and report the number of bytes of the total actually NOT YET WRITTEN or NOT YET READ by the operation. Technically, that number is called the "residual count" of bytes NOT READ or NOT WRITTEN. So if you subtract that number (the residual count) from the maximum count number in the CCW, you will get the number of bytes that were actually read or written. That is very important for us to know, because it enables us to measure the amount of data bytes in each data block on a tape. As the tape program executes Channel Programs to read the tape blocks (the address of the strings of CCWs are included in an IOB (an I/O Block) and you actually EXCP the I/O Block) and you are reading blocks of data into an input area in your program, you then can actually SEE THE DATA that was in the tape block just read. At this point, you know how many bytes of data that were in the block, and you have copied all of this data into your program's "input area" in main storage. This action makes it possible to analyze and measure (or copy) the data that is on the tape, one block at a time. IT ALL DEPENDS ON THE PROGRAMMING Now that we know we have access to all the data blocks on the tape, one at a time, the next thing we have to do is to write code in the tape mapping or tape copying program, so that it will REPORT something about the information it has seen. At this point, we need to see some ideas about the kinds of information we might like to report. We'll throw out some suggestions. First, the program might want to differentiate between whether it is looking at a tape label, or whether it is looking at data. Second, if the program "knows" it is looking at a label, it might want to report all the information that is contained in the label. Third, while the program is reading tape blocks and counting how many bytes are in each one, it might report many statistics concerning those figures (minimum block size, maximum block size of records in the file, and so forth). You can use your imagination as to what might be useful information to report from a block scan. Also, with a labeled tape, where the RECFM (record format) and LRECL (record length) and BLKSIZE (block size) and other file characteristics are reported in the labels, the program might try to compare those numbers (side by side) to the actual numbers it found when it scanned the actual tape data blocks by reading them. If you've ever used DITTO to read a tape, you know that you can see a HEX print of the actual bytes in the tape records. Your program might want to do this, but you probably would not want to make the report too long. So one idea, would be to hex print the first 100 bytes, or the first 132 bytes of the first few blocks in each tape file, just to give the reader an idea about what kind of data is there. Of course ASCII tape labels are rather rare in MVS systems, but they do exist. And you might want to treat ASCII labels as though they are labels, and not as raw data. So (it's difficult but doable, and) if it's worth your while, you might look into the "Using Magnetic Tapes" manual and see how ASCII tape labels are different from the usual EBCDIC tape labels. Our idea is that the sky is the limit, and it only depends on how much work you want to put in, to report whatever information about a tape that you feel is useful. If this kind of programming job sounds too daunting for you, or you just don't have the time right now, you can rest assured that if you get some of the existing tape mapping and tape copying programs, many of which are free, a lot of this "reporting stuff" has already been done for you. That's what we are going to talk about next. EXAMPLES OF TAPE MAPPING AND TAPE COPYING PROGRAMS Many tape mapping and tape copying programs can be found in the CBT Tape collection, all of which is free to anyone to download and use (go to www.cbttape.org). I would recommend looking in the Updates section first, to get the latest version of each "CBT tape file", before looking in the "CBT" section for that file number. I would say that the best general tape mapping program in the CBT tape collection is probably the TAPEMAP program from CBT File 299. I would probably recommend, for making exact copies of an existing tape, the COPYMODS program from CBT File 229. TAPEMAP is best used with no parms or extra options. Just run the TAPEMAP JCL "vanilla". On the other hand, the COPYMODS program, which can make from one to 16 copies of a tape in a single run, or it can just read a tape and report statistics about it, has many options and possibilities which may be entered via EXEC PARM field or SYSIN card. If you use the COPYMODS program, it might pay for you to investigate the possible parms, to see all the stuff that COPYMODS can do. If you want to copy all or selected SL files from a Standard Labeled tape, you may try the COPYFILE program, also on CBT File 229. COPYFILE allows you to select any files from the input SL tape by file number, and put the copied files, one at a time, in any order on the output SL tape. COPYFILE, with all its file number selectivity, has two other programs associated with it, also on CBT File 229. One of them is called COPYSLNL, which produces an NL output tape from the SL input tape by stripping the labels off (COPYMODS can also do this if you say PARM=STRIP). The second dervied program from COPYMODS is called COPYNLNL, which is intended to deal with NL tapes and to copy selected file numbers from them, onto an output tape. I trust that if you play with these programs, you will find them to be very useful tools in your personal toolbox. Getting back to the TAPEMAP program, I have to say that the interesting thing about it, is that it can show you about tape files which have been created in certain formats. For example, if a tape file was created by IEBCOPY, TAPEMAP, in its SYSPRNT2 DD name, will tell you all the member names that were dumped by IEBCOPY from the original pds. TAPEMAP can tell you about IEBUPDTE dumped files, FDR tape file headers, SMPPTFIN format files (it reports the PTF numbers) and others. The first report from TAPEMAP, the SYSPRINT DD, includes much useful information from the tape labels, if any, and it compares this label information to the results of its scan of the actual tape blocks. The SYSPRINT report from the File 299 TAPEMAP program also tells you which input format that each tape file is in, if the program knows how to detect it. Obvious things, such as Dataset Name from the labels, block counts and maximum block sizes found from the scan, and approximate relative footages for each tape file, are also reported in TAPEMAP's SYSPRINT DD name. There are many other tape mapping and tape copying programs on the CBT Tape collection. I don't have time now to tell you more of the details about them. The main idea is that they all do approximately the same thing and have similar function. The differences are mainly in the REPORTING, and the kind and extent of the reporting. SUMMARY Tape mapping and tape copying programs all do approximately the same thing. That is, they read the input tape, block by block, and copy each block into some storage that is accessible to the program. How each program uses the information so obtained, is where each of these programs differs from the other programs of this type. Reading of the tape blocks usually has to be done using the EXCP or BSAM access methods, in order to ensure the maximum flexibility and ability to read unknown tape data. As far as reporting goes, it is up to the programmer to determine which information he or she needs or thinks is useful to report. Free examples and source code for a good number of tape mapping and tape copying programs can be obtained from the CBT Tape collection at www.cbttape.org. I wish all of you everything good, and I hope to see you here again next month.