MVS TOOLS AND TRICKS OF THE TRADE OCTOBER 1999 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. ZAPPING, DISASSEMBLING, DELINKING, AND RE-LINKEDITING With Y2K really approaching, I feel that every systems programmer should get "the old emergency tool kit" into working order, to be ready for the big moment. Today our subject will be about load module manipulation tools that you might need. For example, suppose it's right around that famous night that we're all eagerly anticipating. What if you've got a program that doesn't work. You don't have source--only a load module, and it requires a little tweak, or the replacement of one csect by a repaired version. You've got 15 or 20 minutes to get your shop running. What are you going to do? Are you ready to handle that situation? We're talking about minor re-engineering of load modules here, which can be either difficult or easy, depending on how many tools you have available, and how well you know how to use them. The load module manipulation operations we'll learn about (or review) here are zapping, disassembling, delinking, and re-linkediting. If you can do these with a fair amount of sureness, I can grant you an unofficial programming degree--the MLM degree: "Master of Load Modules", and you can proudly write those letters after your name. Let's define our terms here, so we'll all be on the same page. To ZAP a load module is to change some bytes in it, so it'll probably run differently. No source is affected, no compiling is done--only a direct change to the load module is made. This is ZAPping. We talk about it by saying that we ZAP a load module. We'll mention some names of tools for zapping load modules, or raw data, now. IBM's zapping tool is called AMASPZAP, or "Super Zap". AMASPZAP does "everything", pretty much, but it's cumbersome to use. My favorite zapping tool is "UCLA Fullscreen ZAP", as modified by Greg Price. Both of those tools can work on raw data, as well as on load modules. DISASSEMBLING means to take a load module and convert it to assembler source code, instruction by instruction. There are various tools to do this. These tools are called "disassemblers". Most disassemblers start with an executable load module and directly produce assembler source code, as output. However, to disassemble the code in an 80-byte card-image object deck, as opposed to a load module, you normally have to linkedit the object deck into a load module, and then disassemble the resulting load module. A direct object-deck disassembler program is rare, but the vendor product STARTOOL from Serena, Inc. of Burlingame, CA, does provide one, using STARTOOL's READOBJ subcommand. READOBJ allows you to directly disassemble object decks. I use an object code disassembler to disassemble the object decks in ptf's, so I can refit old zaps to the new ptf module versions, without the aid of microfiche source listings (that often aren't available anymore). DELINKing means to convert a load module into 80-byte object decks, similar to those produced by the assembler, or by compilers. Usually, this has to be done separately, csect by csect, but the STARTOOL delinker will DELINK the entire load module, and automatically generate re-linkedit JCL to re-linkedit the stack of generated object decks. Finally, I have to define what I mean by "re-linkediting". This term might mean different things to different people, but I'd guess that most people would think my definition is reasonable. By re-linkediting a load module, you run an existing load module through the linkage editor again, producing a new load module that should have identical function to the old load module. This sounds superfluous, so I have to give at least one reason why someone would need to do this. One reason for re-linkediting an old load module is to satisfy the program fetch component of the MVS operating system. Sometimes, a very old load module will have problems when the current MVS system tries to load it into storage. The old PL1/F compiler and library load modules had this problem, before Larry Williams cleverly re-linkedited them. (See File 092 of the CBT Tape, which contains the re-linkedited PL1/F compiler and library. You can now run PL1/F on an OS/390 system.) Where do the program fetch problems come from? More recently linkedited programs have some internal quantities called RLD counts, that help a modern MVS system load them efficiently. Very old load modules don't have them, and they have a few other structural differences as well. The new versions of MVS program fetch, which perform the "program loading" function, are supposed to work, even with very old load modules, but on rare occasions, they won't. What if this happens to you on the night of January 1, 2000, or on some other night when you have an emergency? A lot of times, re-linkediting the load module will cure this problem, but you have to know how to re-linkedit a program properly, otherwise it still won't work, or it could have even a worse problem than before. Now that we've outlined what these terms mean, and we've seen what these various operations are, we'll start looking at a few tools which can help us carry these "load module manipulation operations" out with knowledge and sureness. Many of the tools are free, and can be found on the huge tool collections called the CBT MVS Utilities Tape, and the CBT Overflow Tape. The materials from both tapes are online. You can get there from www.naspa.net, and click on "Online CBT Tape" to get to the CBT Tape website. The integrated vendor supported toolkit called STARTOOL, from Serena, Inc., also has many of these functions incorporated within it. Throughout the rest of this article, I'll try and emphasize the relationship of these techniques to Y2K-type emergencies. I want to make sure that you have your equipment ready, whenever you might need it. It would help a lot, if you could earn your MLM degree before January, 2000. MY FAVORITE ZAPPING TOOL. My favorite zapping tool is a TSO command called UCLA Fullscreen ZAP, which is distributed on File 134 of the CBT MVS Utilities Tape, and which can be downloaded from the CBT Tape web site. ZAP is a TSO command processor program that generates full screen output under TSO, and will show you several hundred bytes of load module data or raw data a time. ZAP is a single load module, which includes its own self-contained HELP screens. To get HELP, type HELP or ? on the ZAP command line, and after you've gotten to the proper help screen, you just type the letter U on the command line, press ENTER, and you're back to where you were. I don't have space now, to describe how Fullscreen ZAP is used in detail. Suffice it to say that it's very intuitive, once you get used to it, and you actually "see a clear picture of the load module or data" that you're zapping. Because of this clarity, I'll always use Fullscreen ZAP instead of AMASPZAP when researching a load module problem in an emergency, and Y2K problems are no exception. As modified by Greg Price, Fullscreen ZAP can actually be used to look at, or change, any disk data, even deleted disk data that hasn't yet been overwritten. Fullscreen ZAP is not just restricted to changing data in load modules, but it can look at any disk data. In addition to allowing data changes, Fullscreen ZAP is handy for simple data observation, and will show you the physical characteristics of the data blocks you're looking at, using a display at the bottom of the screen. For example, suppose you've moved a DSORG=DA dataset, and the copy is not behaving properly. Fullscreen ZAP will show you how the data blocks fit on each track, so you can see if the physical data organization has been disturbed by the move. Not many other tools will show you such information about a data file. I have written about Fullscreen ZAP in detail in previous columns, especially in those from March and April 1992. You can get these old columns from File 120 of the CBT MVS Tape, and Fullscreen ZAP hasn't changed much since then. Fullscreen ZAP can do just about everything that IBM's AMASPZAP program can do, and it's much easier to use, with it's FIND capability for hex and EBCDIC strings within the data. To earn your MLM degree, you owe it to yourself to get very familiar with TSO Fullscreen ZAP. For completeness, I'd just like to mention that STARTOOL has an ISPF-based load module zapper built within it. With STARTOOL pointing at a load library, you issue the CSECT subcommand against any load module, which gives you a list of all csects within that load module. If you issue the ZAP line command against any csect, you get a full-screen display of the load module in hex and EBCDIC, and you can zap any bytes, in hex or EBCDIC, by simply typing over them. STARTOOL will generate AMASPZAP control statements to duplicate, or reverse, everything you did, and these generated statements serve as a log, for safety, so you can duplicate or reverse any changes you've made, using an AMASPZAP batch job. This STARTOOL facility is a load module zapper only, and will not work on raw disk data, but it's very convenient to know about in an emergency situation, if your shop is licensed for the STARTOOL product. DISASSEMBLING LOAD MODULES. There are several disassembler programs on the CBT MVS Tape which are free. One disassembler is on File 217, and another improved one, is on File 171. These two programs are run in batch, and disassemble one csect at a time. A third batch disassembler is from Randy Hall; it is on File 354 of the CBT Tape. The CBT Tape also contains a very cleverly designed ISPF-based full-screen disassembler written in PL/I by Valentin Chernyak, on Files 238 through 242. Valentin's disassembler is run under TSO, it is interactive, and I think it's a lot of fun to use. The vendor product STARTOOL has a DISASM subcommand that is very fast, accurate, and handy, and which defaults to disassemble an entire load module all at once. The STARTOOL DISASM subcommand has a REASM option, to perform the disassembly in such a way, that the generated source code can be reassembled, and correctly linkedited, to exactly duplicate the original load module. Back in the MVS/370 days, I used what is now the STARTOOL disassembler, to produce a working version of the MVS nucleus, IEANUC01, which could actually be IPL'ed. This copy of the nucleus was produced by disassembling the production load module IEANUC01 with the REASM option, and assembling the disassembled source code. Of course, I checked the result for byte-for-byte and structural equality 12 times over. I don't recommend doing this nowadays with an ESA nucleus, (and MVS/370 wasn't OCO). But I can say that using the STARTOOL disassembler is a very fast way to recover source code when you don't have any, and it duplicates the original load module(s) with a very minimum of effort. Of course, you have to test the duplication for byte-by-byte accuracy, and identical functionality, just to be sure. DELINKING LOAD MODULES. Way back in the OS/360 days, IBM came out with a free FE tool, that you could get from IBM if you asked for it. It was called DELINK0. DELINK0 is a program which runs in batch, and which will produce one object deck at a time, to correspond to one csect from a load module. If a load module has, for example, 9 csects, you have to run DELINK0 nine times, to recover all of its object decks. Nevertheless, DELINK0 is a super-handy tool in certain Y2K recovery situations. You can get source code for DELINK0, that was disassembled and supplied with labels, from File 316 of the CBT Tape. One recovery situation I recall, occurred when I was trying to re-install a non-IBM utility which called an IBM-supplied subroutine that was linkedited with it. IBM had modified this subroutine for its own programs, so that in a later MVS release, it was not the same as before, and the calling sequence of the parameters was different in the new version. If I'd try to linkedit the new version of IBM's subroutine with a reassembled version of the non-IBM program, it would fail and abend. I'd completely lost any IBM-supplied old version of the subroutine. The only copy I had, was the one that was linkedited into my old non-IBM load module. For me, it was no problem. I just delinked the old version of the IBM subroutine from the old load module, and relinkedited the object deck I obtained, back with the newly assembled version of the user program. The combination worked fine. It pays to have an MLM degree! The vendor product STARTOOL also has a DELINK subcommand that you can apply against an entire load module, or against any subcollection of its csects. DELINK in STARTOOL is fast, and it beats DELINK0 by a mile! The STARTOOL delinker is also a part of STARTOOL's SMPGEN facility, which can generate PTFs and many other SMP/E modification control structures, to repackage any non-SMP/E-installed software for installation under SMP/E. Now, there's a new free delinking tool on File 090 of the CBT Tape. This is DELINKI from David Noon. DELINKI is a far more modern delinker than DELINK0; it was written in PL/I, and it delinks an entire load module with all csects stacked up. The REVIEW program (a TSO browsing program that is being maintained by Greg Price, and is on File 134 of the CBT Tape) hooks into DELINKI when you're REVIEWing a load module library, and you can delink any load module on the spot, using a combination of these two programs. Here's how. DELINKI and REVIEW should be in a load library accessible to your TSO session. If you're running REVIEW 31.0, which is a recent version, then ALLOCATE ddname SYSUT2 to an 80-byte output dataset, then REVIEW the load library, get a member list, TAG (line command T) the members in the load library you want to delink, and enter the =DELINK command in the directory list command field of REVIEW. REVIEW will call DELINKI to delink all the chosen members, and the object decks will be written out, one after the other, to the SYSUT2 output dataset. The procedure works very well, and very quickly. RE-LINKEDITING LOAD MODULES. Y2K situations can provide ample opportunity for you to exercise your re-linkediting skills. Re-linkediting can be done to produce an identically functional load module to the original, or the techniques can be used to accurately replace a csect in a load module, with a different, repaired version. You should have both techniques ready and available for fixing possible Y2K emergencies. My favorite re-linkediting technique involves the use of the STARTOOL package, or its free precursor from the CBT Tape, the PDS command from File 182, now at version level 8.5. Given a load module in a load library, you can point the PDS package, or STARTOOL, at that load library under TSO. Then you issue a certain subcommand against one load module, or a group of them. This subcommand is called MAP. MAP normally produces an AMBLIST-like load module map. But with an extra keyword called RELINK, the MAP subcommand will generate perfectly accurate JCL and linkage editor control statements, to correctly re-linkedit the load module, keeping all csects in their original, proper order. All the linkage editor PARM options are generated properly too. With PDS or STARTOOL, you'll never have to beat your head over a linkage editor manual again! Using PDS or STARTOOL for re-linkediting certainly is a neat trick, and it's very handy for us to know, and use often. To re-linkedit a load module exactly, just use the MAP subcommand with the RELINK keyword against it, and edit the generated SYSLMOD DD statement, so it points to a different load library than the original one. We don't want the output of the re-linkediting job to overlay the original load module. If we made a mistake, we want to have a backout. Just add a JOB card to this JCL, and run it. To accurately replace a csect with a newer version, use the MAP (PDS or STARTOOL) subcommand with the RELINK keyword, against the original load module, to generate re-linkedit JCL as before. Then, besides changing the SYSLMOD library name, we add a ddname to the JCL, pointing to the library containing the new version of the csect, and add an INCLUDE linkage editor control card to refer to it, just before the INCLUDE card for the original load module. This will replace the old csect by the new one. Just make sure to look at the linkage editor output messages carefully, and check that the csect replacement process was carried out correctly. AN ADDITIONAL PREREQUISITE FOR YOUR MLM DEGREE. If you've installed these programs (free or vendor), and you've learned how to use them, you're well on your way to acquiring your MLM degree. However, there's an additional prerequisite of at least 24 hours of "lab time". This degree requirement is to be satisfied by "playing" with the above tools, until you can manipulate all of them fluently. I hope to see you at the graduation exercises. And I also hope you'll come again and meet with me, here, next month. I'm looking forward to seeing you. Good luck!