MVS TOOLS AND TRICKS OF THE TRADE JUNE 2000 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. COPYING TAPES As a longtime systems programmer who has talked with many of my peers over the years, I am puzzled by some people's attitudes about the copying of tapes. I have heard many opinions about the subject--some of them very knowledgeable, and some of them surprisingly ignorant. When asked the question, "how do you copy a tape?" people have actually answered: "You use IEBGENER." I'd ask in reply: "But what if the tape has 500 files on it--what do you do then?" And I've gotten a blank look in return. Fortunately, most of the people in our field do not answer this question in this way. Actually, before you can accurately copy a tape, you should know what is on it--how many files, standard labeled (SL) or non-labeled (NL). Is it an MVS tape, or a DOS/VSE tape, or does it come from some other kind of computer system? You should know how to use some tools which can tell you accurately and exactly what kind of files the tape contains, and what they look like. Today, we'll talk about some particulars from the subject of accurately copying tapes, and we'll recommend some tools for this purpose. Of course, after the tape has been copied, you'd like to check and make sure of two things: first, that the copy was complete--all the files have been copied, and second, that it was accurate--the copy is byte for byte identical with the original. Some Fundamentals Tapes contain sequential blocks of data, one block after another. These blocks are organized into logical files. And the files are separated one from another. The separator string which separates one file from another, is called a "tape mark". A tape mark is generated by the tape hardware. It makes a big difference if a tape is "labeled", or "non-labeled". A labeled tape has each file of data surrounded by what can be termed "label files", or labels, for short. A non-labeled tape has its files separated only by tape marks, with no label files at all. The structure of data files on a tape is very simple, but it is crucial that it be thoroughly and clearly understood. See Figure 2 for a simple diagram of how files are arranged on a tape. To understand the structure of files on a tape, it is necessary to have some tools, which can generally be termed "tape mapping programs". I can tell you about some free tape mapping programs, such as TAPESCAN and TAPEMAP, which I've found highly useful. Also, some of the vendors, such as SAS, have tape mapping tools. IBM's DITTO programs, both for MVS and VSE, can be used to map and copy tapes. As frequent readers of this column already know, I'd rather write about the free programs, which can be obtained and used by anyone without restriction. If you know how to use a free tool, you can use it anywhere, and you can always take that skill with you to any shop. Besides mentioning some specific tape mapping programs, such as TAPESCAN and the various TAPEMAP programs, I have to talk about the CBT MVS Utilities Tape, which contains the source code (and load modules) for these programs. The CBT Tape is a huge collection of system programmer "goodies" from all over the world. Physically, the collection is on several tapes. The CBT MVS Utilities Tape, and the CBT Overflow Tape are the two current volumes. There is also an old version of the CBT Tape (Version 249) from July 1985, which contains old programs whose source code would otherwise be hard to find today. All of the files on these tapes can now be downloaded from the CBT Tape web site, which has its own URL, but which can be reached from the "Members" portion of the NaSPA web site as well. After discussing the mechanics of tape file transfer, I'll look at the operation of one specific program which can copy tapes conveniently. Please see Figure 1 for a list of several free tape mapping and copying programs. How Do Tape Copying Programs Work? Tape copying consists of reading a block of input tape data into a data buffer, and then writing the contents of the buffer out to an output tape. When writing a tape copying program, you must take care to position both tapes appropriately, and to make sure to write the proper tape marks, (and labels, if the output tape is Standard Labeled). Effective tape mapping and tape copying programs usually use the EXCP or BSAM access methods. While it is perfectly OK to write a tape copying program using QSAM, you get more generality to handle irregular tapes, using either EXCP or BSAM. Furthermore, using both EXCP and BSAM, it's possible to copy up to 64K blocks of tape data in one CCW, but with QSAM, you can't--32K is the QSAM limit. EXCP is the more elementary and straightforward of the two methods. In fact, at least one of the free programs mentioned in Figure 1, TAPESCAN, which uses BSAM for reading tape input, in truth only employs the BSAM for some extra window dressing and control, but the actual input I/O is really being done by EXCP under the covers. So it's important for us to learn something about how to do EXCP for tapes. EXCP (Execute Channel Program) can be pictured as the "assembler language" for I/O. On the other hand, the IBM Access Methods, BSAM, QSAM, and the like, can be pictured as higher-level languages for I/O. Tape files, being sequential files exclusively, are simpler to handle than disk files, so the EXCP to handle tape files will also be quite simple. You only have to know a few pieces of information, and soon you'll be able to study and write tape EXCP programs like a pro. The EXCP process for tapes moves data to or from a tape, and/or positions a tape to wherever you want it. Control of all this is done by "channel programs". A channel program consists of a succession of "channel command words", or CCWs, that are chained to each other. The "chaining" is done by turning on a "chaining bit" in the third operand of the channel command word. Look at Figure 3 to see the structure of channel command words. To write a tape EXCP operation, you just have to specify a succession of one or more appropriate channel command words, then include these CCWs into a larger control block (that you construct) called an IOB, or Input Output Block, and then you EXCP the IOB. That's all there is to it, except for a few details, which we'll now touch on briefly. To specify any I/O operation in an assembler program, you always need a DCB macro, to define the ddname of the file you're looking at. To set up EXCP access to the DCB for a file, all you really have to specify is MACRF=E. Besides that, you can just specify the DDNAME keyword parameter. With EXCP there are no RECFM or BLKSIZE parameters to worry about. All of that information is specified in the CCWs that are executed, and in any deblocking that your program itself does. In the generalized tape programs we're looking at, you might also want to do some manipulation of JCL DD parameters inside the program, such as forcing the operating system to ignore Standard Labels, even if you didn't specify BLP in the LABEL parameter of your JCL. This type of miracle is done by changing the Job File Control Block (JFCB), which contains all your JCL DD information after your program starts executing. To give your program access to this JCL information, you have to set up an Exit List for your DCB, and point to it with the EXLST keyword parameter of the DCB macro. After you execute a RDJFCB macro, this exit list will contain an accessible image of all your JCL in the DD card. To make all this work, just set up an exit list address in your program, which consists of a fullword address in your program that starts with an X'87' character, followed by a 24-byte (3 character) address of a 176-byte area that you specify in you program, to hold all of the JFCB information. To copy (for any use) all the DD information into your 176-byte area, just execute a RDJFCB macro pointing to the DCB. You can then change any DD information, and this is later honored if you don't do a regular OPEN of the file, but you do a special type of OPEN, called OPEN TYPE=J. Now let's look at the EXCP again. The EXCP operation reads or writes data between the device and your computer storage. Sometimes an EXCP operation will just position the tape, but in any case, this operation takes a long time, compared to the short time needed in executing computer instructions. In order to stop execution of your program until the I/O operation completes, you have to issue a WAIT macro after you issue the EXCP macro. If an EXCP is followed by a WAIT macro, the EXCP "knows" how to inform the WAIT macro that the I/O operation has successfully been completed. This communication is done through a fullword area you specify in your program, called an ECB (Event Control Block). Just specify an ECB as DC F'0', label it, make sure the IOB knows where it is, before you do the EXCP, and say WAIT ECB=this label. The next instruction in your program should be a TM of the first byte of the ECB to equal X'7F'. If all these bytes aren't on, in other words, if they're not all ONES, then you've got an error situation. Otherwise, all is well, and you can now go to the buffer and read the data (on a read) or you can know the data was written from the buffer to the tape (on a write). Cool. It really works. This all may seem complicated, but you can study some real code, and see this process in action. Probably one of the simplest tape copying programs I know of, is the COPYMODS program from File 229 of the CBT MVS Tape, which makes from one to 16 exact copies of an existing tape, end to end. I'll conclude this article with at step-by-step look at the basic operations of the COPYMODS program. The COPYMODS program. The COPYMODS program makes a full copy of a tape, from one end to the other. It doesn't matter if the tape is Standard Labeled (SL) or Non-Labeled (NL)--COPYMODS will copy the entire contents of the input tape, to as many as 16 output tapes. To simplify our explanation, let's assume that there's only one output tape. The input ddname is called IN, and the output ddname is called OUT1. You can obtain the source for the COPYMODS program from File 229 of the CBT MVS Tape, by looking at location ftp://ftp.cbttape.org/pub/cbttape/cbt/CBT229.zip . To begin, COPYMODS opens the IN file and the OUT1 file. Since COPYMODS does not use OPEN TYPE=J, but a regular OPEN, it requires that you specify LABEL=(,BLP) in the ddnames IN and OUT1. Then the program begins copying files. It reads the first block of data into a 64K buffer that's right inside the program, and it writes that data out to the output tape, continuing until the first file has been completely read. When the first tape mark is encountered on input, COPYMODS writes a tape mark to the output tape. All of this is done with EXCP instructions, each pointing to an IOB that contains the correct CCW chains. When two consecutive tape marks are encountered, COPYMODS writes a second tape mark to the output tape, and closes both tape files. It's a very simple operation. I've recently "taught" COPYMODS not to stop at every double tape mark. Sometimes, when copying an SL tape, there's a situation in which two consecutive tape marks is normal, and I detect that. This arises when a file with no data, such as an IEBCOPY backup of a pds with no members, is written to a Standard Labeled tape. The data pattern for an SL tape is normally: HDR1 label, HDR2 label, TM, data, TM, EOF1 label, EOF2 label. If there's no data in the SL file, the two TM's become consecutive. So I programmed into COPYMODS, that if it "sees" a HDR1 and/or a HDR2 followed by 2 consecutive TM's, then it should not stop, but it should go on and look for EOF's or EOV's in the input tape. I hope that you've gotten an appreciation of tape copying from this month's column. As one practical application, you can use my new version of the COPYMODS program to make real copies of virtual tapes that are in an IBM Virtual Tape box. The Virtual Tape box has a provision to do a logical "eject" of a tape that's inside it, but then the "tape" that's inside the box gets deleted. If you use COPYMODS to make the copy of the "inside tape" to an outside tape, then you won't have to actually delete the "inside" tape. Here's a real, practical use for the COPYMODS program in this modern day and age. Good luck. See you next month! * * * * * * * * * * * * * * * * * * * * * * * Figure 1. A Selection of TAPE Copying and TAPE Mapping Programs which are free. Information on General Function is according to the level of the program on Version 424 of the CBT MVS Utilities Tape. Program Name Where Obtained General Function COPYMODS File 229 of CBT Can make from 1 to 16 Tape exact copies of a tape, in a single run. Can now copy DOS/VSE tapes and tapes with leading tape marks. Can copy tapes with blocks up to 64K. COPYFILE File 316 of CBT Can select files from one Tape standard labeled (SL) tape and copy the selected files to another SL tape. Has sophisticated control card scheme to select the files to be copied. Can copy up to 64K blocks of data. COPYSLNL File 316 of CBT Can select files from one Tape standard labeled (SL) tape and copy them to a non- labeled (NL) output tape, using the same control cards that COPYFILE uses. Can copy up to 64K blocks of data. COPYNLNL File 316 of CBT Can select files from one Tape non-labeled (NL) tape to another NL tape, using the same control cards that COPYFILE has. Can copy up to 64K blocks of data. CT File 316 of CBT Can copy one complete tape Tape to another, under operator console control. Can do multi-volume copies. Can verify the copy, if it was a single volume. Recently fixed to handle 64K blocks of data. TAPESCAN File 102 of CBT Shows details of what is on Tape a tape. Shows tape label contents and first 100 bytes in hex, of first blocks of a tape record. Maps SL files of an SL tape. Not fixed yet to handle 64K byte blocks; only good until 32K byte blocks. Can be used to copy one tape to another. Handy for tape diagnosis. TAPEMAP File 299 of CBT Shows label information of Tape. Another MVS tapes. Second report shows version is on details of the contents of many Leonard Woren's formats of unloaded files, such web site. as IEBCOPY, IEBUPDTE, and the CBT973-compressed CBT Tape files themselves. TAPECOPY File 174 of CBT This program can copy tapes and Tape. This pgm has many options to handle bad is from Aron or damaged tapes. A unique Eisenpress. feature of this program is its ability to create a SL tape from an NL tape, supplying a standard format for a label, from parm information. So far, can only handle up to 32K blocks. * * * * * * * * * * * * * * * * * * * * * * * Figure 2. How files are arranged on IBM MVS Standard Labeled (SL) and on Non-Labeled (NL) tapes. Let's say each tape contains two files, and they don't fill the volume completely. SL tape: VOL1 label, HDR1 label, HDR2 label, TM, File 1 data, TM, EOF1 label, EOF2 label, TM, HDR1, HDR2, TM, File 2 data, TM, EOF1, EOF2, TM, TM. NL tape: File 1 data, TM, File 2 data, TM, TM. IBM References: DFSMS/MVS Using Magnetic Tapes (SC26-4923) DFSMS/MVS Using Data Sets (SC26-4922) * * * * * * * * * * * * * * * * * * * * * * * Figure 3. Structure of a Channel Command Word (CCW). A CCW is eight bytes in length, and the IBM assembler "understands" the CCW instruction, with four operands, without its being a macro. A CCW, defined by a CCW instruction, looks like: label CCW one byte command code, 3-byte address of buffer, flag bits for chaining, etc. (2 bytes) length of data to be moved (up to 64K - 2 bytes) Command codes can be found in the IBM "yellow card" pocket reference. Some command codes for tapes are: X'02' Read X'01' Write X'07' Rewind X'1F' Write Tape Mark X'03' No Operation X'37' Forward Space Block X'3F' Forward Space File X'27' Back Space Block X'2F' Back Space File