MVS TOOLS AND TRICKS OF THE TRADE March 1992 Sam Golob MVS Systems Programmer sbgolob@cbttape.org A TOUR OF THE WORLD THROUGH FULLSCREEN ZAP - PART I. One of the most useful single tools in the public domain, for an MVS systems programmer, is the Fullscreen ZAP program, originally from UCLA in California. I have mentioned fullscreen ZAP numerous times in the history of this column, but from my many "straw polls" of working systems programmers over the years, I don't think the message has taken hold as much as it should. That's the reason for running this series of at least two parts, to explain the uses of this beautiful program in some detail. Fullscreen ZAP is a nearly complete replacement for IBM's utility to change data on disk files, known as AMASPZAP or "superzap". The advantage of Fullscreen ZAP is that it can be used for disk exploration far more conveniently, allowing you to take a "Tour of your DASD World". Fullscreen ZAP in its current incarnations, allows a system programmer, with authorization, to easily view and change any record on a disk pack. Without authorization, one can do the same thing for most individual datasets. In FULLVOL (full volume) mode, ZAP can be used to CLIP a pack (change its volume id) while it is online, and to view and zap IPL text or any other "track zero" data. VTOC access is also easy and sure. Unlike its IBM equivalent AMASPZAP or HMASPZAP, Fullscreen ZAP allows you to see what you're doing every step of the way and to find what you're looking for, even if you originally didn't know where it was. Fullscreen ZAP has an almost complete tutorial self-contained in its one load module, consisting of thirteen help screens. Any time you need help, you type a question mark "?" or "HELP". This will initiate a rotating sequence of displays for all these help screens. When you've seen what you need, typing a "U" will return you to your previous work place. Our current series on Fullscreen ZAP will consist of at least two parts, explaining how to use the program. We shall include some "war stories" to show you the kind of tight situations this program could save you from. Of course, any short series such as ours can't teach you everything about a powerful multi-use product. Our aim is simply to get more people to use Fullscreen ZAP so its benefit for themselves and their installations can be spread around. INSTALLATION AND BEGINNINGS. Fullscreen ZAP is a single load module. It is in the public domain, and its source is readily available on the CBT MVS Utilities Tape, available from either NaSPA (414) 423-2420, or SPLA (305) 284-6257. Versions of Fullscreen ZAP source code can be found on Files 186 or 134 on the CBT Tape (File 186 preferred), and a load module created from the source of File 134 can be found on File 135. Installation consists of one assembly and linkedit of the load module. You can even IEBCOPY the load module from File 135 and use it immediately. The source code requires some UCLA macros to assemble properly. These are contained on the previously mentioned files, or on the UCLA file, File 149. The ZAP load module is a TSO command, and it is invoked from any library accessible to your TSO session. See Figure 1 for a good overview of ZAP command invocation options. Let's see how to begin using the ZAP command. ZAP can be used to examine, dump, and update in place, any type of sequential, partitioned, or direct access dataset. If the user is authorized, ZAP can similarly manipulate VTOCs, catalogs, VVDSs and components of VSAM datasets. ZAP is not restricted to load modules only. But since the updating of load modules is probably the most frequent use of IBM's AMASPZAP, we shall begin by showing this use of Fullscreen ZAP, to keep things familiar. In our example, we will look at csect IEBDSCPY of load module IEBCOPY which is a member of the cataloged copy of SYS1.LINKLIB on our system. From TSO Ready, we enter: "ZAP SYS1.LINKLIB" . There will appear a fullscreen display, with the cursor pointing to a command area. From the command area, we enter two commands. The first is: "MIEBCOPY" (or "member IEBCOPY"). The second is: "EIEBDSCPY" (or "entry point IEBDSCPY"). The screen resulting from these commands is shown in Figure 2. Decimal 224 bytes in the vicinity of our data are displayed in hex and in EBCDIC. A wedge-shaped character among the hex data, points to our current location. This is at the beginning of the csect IEBDSCPY, or at location +0 within the csect. We enter the command: "+212" in the command area, to relocate us hex 212 further into the data record of the csect. This is obviously in the middle of some code. We may disassemble the code by typing the command: "DISASM" in the command area. The result is now shown in Figure 3. At this point, we may choose to change the data or to leave it alone. To change the data, we have the subcommand "S" followed by up to eight hex bytes of new data (without an intervening space). We can also "OR" the original data data with this new data by using "O" instead of "S". We can "AND" that data using "A" instead. Or we can "XOR" the data with our hex operand, by using "X" instead. If we have decided to keep our changes, we enter the command "ZAP" in the command area to write our changes in place, back to the original data block. We can invoke the "LOG" subcommand, to make a record of what we've done. To end the ZAP session, we simply type the command "END" in the command area. We may receive a message if we want to keep the log. If we say YES, the log is written to SYSOUT(A). Otherwise, the log is deleted. To write the log to a dataset, that dataset must be pre-allocated to the ddname ZAPLOG. When we ZAP a load module, the program writes an IDR zap record to the load module, using our TSO id name to identify the maker of the change. USING ZAP FOR ANY ARBITRARY DATASET ON A DISK VOLUME. To zap a non-cataloged dataset on a disk volume, enter the ZAP command with the VTOC dataset name, followed by the keyword: "VOL()". See Figure 1 for the format. For example, if we wanted to look at the copy of SYS1.LINKLIB on the alternate residence volume called ALTRES, we need merely enter: "ZAP SYS1.LINKLIB VOL(ALTRES)". Then we proceed as before. For non-partitioned datasets, the result of the primary command will get us directly into the first disk record of the dataset. That is also true for partitioned datasets, but the first disk record of a partitioned dataset is the first block of the directory, and we need the "M" (and possibly "E") commands to reach what we want subsequently. In any case, we may position ourselves forward or backward, starting initially from the beginning of the file. Please bear in mind that our use of the term "disk record" or "record" really refers to physical data blocks on the disk. ZAP does not do any logical deblocking. Two useful commands to know at this point are "L" and "F" which are "find" commands. These can be used to search forward from the current point to find either hex or EBCDIC strings. The difference between "L" and "F" is that "L" will not proceed to look past zero length records or "EOFs", but "F" will look past EOFs. Both of them will stop at the end of the dataset extents. To search for a hex string, merely enter the string immediately after L or F with no intervening space. To look for an EBCDIC string, enclose the string between slashes after the L or F, with no intervening space. A "repeat find" is executed merely by entering the letter "L" or "F" again, by itself. Some uses for "L" or "F": One obvious one is when you're pointed to a Format 4 record which is a VTOC header, and you want to find the subsequent Format 1 record belonging to a dataset on the pack. Simply enter "F/dataset.name/" in the command area, and ZAP will get you to to proper Format 1 record promptly. This record can then be changed or even zeroed out, if you want. A second use is if you want to do a scan-replace for a string, somewhere within the dataset. Merely point to the beginning of the dataset with the "P" command, and then use the "L" or "F" commands to determine the first location of the desired string to replace. Enter an "S" command to replace the string when you're there. Then do a repeat find by executing "F" again, and so on. ZAP does not have to be used to make changes, but since it shows you up to 224 bytes at a time, ZAP is a useful tool for browsing on disk. Its many commands for finding strings and moving back and forth within a dataset, can be employed for the purpose of exploration, as well as for changing data. PF8 is like a "Page Down" and PF7 is like a "Page Up" command within a data block on disk. "R" will advance one record; "R+n" will advance n records from the current record. "B" will point one record back. And so on. The tutorial is very helpful to show the power of these commands. FULLVOL ..... Greg Price of Melbourne, Australia has made ZAP into the Mario Perillo of the disk pack, by introducing the FULLVOL parameter at ZAP invocation time. With the FULLVOL parameter, Fullscreen ZAP allows you to make a "global tour" of an entire disk pack, as though the whole pack were one dataset. FULLVOL works as follows. The user simply enters the name of a dataset on a disk pack, possibly with the VOL() keyword parameter just to make sure he or she has the volume right. The ZAP invocation is followed by the word, "FULLVOL". For example, to look at the volume ALTRES, you might enter: "ZAP SYS1.LINKLIB VOL(ALTRES) FULLVOL". ZAP then alters the DEB of the dataset SYS1.LINKLIB to pretend that its extents started at the very beginning of the disk pack and ended at the very end of the pack. Actually, ZAP knows that it is in FULLVOL mode. When in FULLVOL mode, ZAP shows a volume name at the bottom of the display, instead of a dataset name that it usually shows there. FULLVOL mode has immediate uses. Record 3 of Track zero of Cylinder zero is the Disk Id of the volume. In FULLVOL mode, simply enter the subcommand, "R+2" and you're there. See Figure 4 which displays the disk id of a volume in this way. The volume id field of this physical record can be changed in the usual way, to "CLIP" the pack while it is still online. You can see everything you're doing. Then you need merely re-mount the pack, using the new volume id. It may be necessary to bring the pack offline and then online before re-mounting it. Another use of FULLVOL mode is to examine IPL text on a volume. Usually this text begins in Record 5 of Track zero, if it is present on a volume. Often, an IPL failure on a new RES pack is caused by lack of replacement of the old IPL text with new IPL text for the new operating system release. With Fullscreen ZAP in FULLVOL mode there's no guesswork anymore. Just proceed two records past the volume id, and see what's there. The eyecatchers for any IPL text will stare you right in the face. Another exploitation of FULLVOL mode is to scan-replace strings in a dataset that is enqueued DISP=OLD by a long-running job, but which is not really active. Merely determine the CCHHR disk location of the dataset by using a VTOC map or some other tool, or by exploring with Fullscreen ZAP itself. Then get into FULLVOL mode on that pack. Position yourself to the Cylinder and Track location of the beginning of the dataset (from your exploration knowledge), and then use the "F" (or "find") subcommand over and over, as described above. This works because you are not really accessing the dataset by its own name. You are accessing it through the name of another dataset on the pack that is not currently being enqueued upon, and which allows you to explore the entire pack at will. This is slick stuff to know about. TO BE CONTINUED. I hope this is enough to whet your appetite and get you started exploring the newer versions of Fullscreen ZAP from the CBT Tape. Next month, I'll show you some more useful tricks that this tool makes possible. Good Luck. See you soon. * * * * * * * * * * * * * * * * * * * * * * * FIGURE 1. The following is a portion of TSO help for the ZAP command written and elucidated by Jeff Broido. The portion shown here illustrates how to invoke ZAP from a TSO session and most of the options that can be used at invocation time. Function The ZAP command is used to examine, dump, and update in place any type of sequential, partitioned, or direct access dataset. If the user is authorized, ZAP can also similarly manipulate VTOCs, catalogs, VVDSs and components of VSAM datasets. Any record format is accepted. This command is the TSO interactive equivalent of IBM's service aid AMASPZAP (otherwise known as IMASPZAP, HMASPZAP or "Superzap"). Syntax ZAP 'DSNAME' VOLUME('SERIAL') CRT NOT3270 TERSE/VERBOSE BLKSIZE('BLKSIZE') NOLOG/LOG ALLOCDSN('DSNTOALLOC') FULLVOL Required: 'DSNAME' Defaults: TERSE, NOLOG No volume implies a cataloged dataset. If you invoke ZAP at a terminal in the 3270 family, CRT is the default. BLKSIZE defaults to the blocksize of the dataset. Note: Usage of the ALLOCDSN keyword is required only for the 'DSNAME' of FORMAT4.DSCB * * * * * * * * * * * * * * * * * * * * * * * FIGURE 2. This is a Fullscreen ZAP screen after two subcommands have been entered. ZAP was originally invoked to get into SYS1.LINKLIB to look at csect IEBDSCPY from load module IEBCOPY. "ZAP SYS1.LINKLIB" was entered from TSO Ready mode. Then, the subcommand MIEBCOPY (or "member IEBCOPY") was entered from the command area of the ZAP screen. Finally, EIEBDSCPY (or "entry point IEBDSCPY") was entered in the command area. The resulting screen is shown below. Note two things. First, the most recently entered command is re-shown in the open space two lines below the command area. This command is modifiable and usable if the primary command area is left blank. Second, notice the wedge that points to the data at offset +0 of the entry point. This wedge shows the current modifiable area of the data. A command to the command area can modify up to eight bytes from the location of the wedge, forward. Z A P ENTER VALID COMMAND ABOVE OR ? FOR HELP VERSION=2.3G 25JUL89 EIEBDSCPY 00000 >90EC D00C 05B0 47F0 B07A C9C5 C2C4 E2C3 Ý..}....0.:IEBDSCÝ 00010 D7E8 F1F0 61F1 F361 F8F6 D6E9 F9F8 F0F0 ÝPY10/13/86OZ9800Ý 00020 F640 D1C4 D8F1 F1F1 F040 F5F6 F6F5 60F2 Ý6 JDQ1110 5665-2Ý 00030 F9F5 404D C35D 40C3 D6D7 E8D9 C9C7 C8E3 Ý95 (C) COPYRIGHTÝ 00040 40C9 C2D4 40C3 D6D9 D740 F1F9 F8F1 6B40 Ý IBM CORP 1981, Ý 00050 F1F9 F8F3 40D3 C9C3 C5D5 E2C5 C440 D4C1 Ý1983 LICENSED MAÝ 00060 E3C5 D9C9 C1D3 4060 40D7 D9D6 C7D9 C1D4 ÝTERIAL - PROGRAMÝ 00070 40D7 D9D6 D7C5 D9E3 E840 D6C6 40C9 C2D4 Ý PROPERTY OF IBMÝ 00080 5840 B2DA 50D0 418C 41A0 4188 50AD 0008 Ý. ..&}.....h&...Ý 00090 18DA 4120 0008 1B77 1B88 1B99 9180 1000 Ý.........h.rj...Ý 000A0 4710 B0FE 5851 0004 4865 0000 4155 0002 Ý................Ý 000B0 1266 47D0 B0DC 4199 0001 4998 B2EC 4770 Ý...}...r...q....Ý 000C0 B0D4 9500 5000 4780 B0CE 41E7 4528 D207 Ý.Mn.&......X..K.Ý OFF: 0000 ( 0) ADDR: 00000 ( 0) DSN: SYS1.LINKLIB LEN: 4128 ( 16680) BASE: 00000 ( 0) CCHHR: 000E000001 TTR: 007801 * * * * * * * * * * * * * * * * * * * * * * * FIGURE 3. We are now pointing to location +212 hex, in csect IEBDSCPY of load module IEBCOPY. Note the location of the wedge, amidst the data area. We have disassembled the instruction located there. The result of this disassembly is shown immediately below the hex display. From what we see, we may decide whether to change the data at this location or to merely learn about it. Also note the "WHERE" information at the very bottom of the display, showing in which record within the dataset, we are currently located. Z A P ENTER VALID COMMAND ABOVE OR ? FOR HELP VERSION=2.3G 25JUL89 DISASM 001B0 0001 8970 001E 5070 402C 4111 0001 4118 Ý..i...&. .......Ý 001C0 1004 47F0 B106 4111 0001 4660 B106 4160 Ý...0.......-...-Ý 001D0 4590 D207 6028 4528 4160 45F0 D207 6028 Ý..K.-....-.0K.-.Ý 001E0 4530 4160 4650 D207 6028 4538 4160 4698 Ý...-.&K.-....-.qÝ 001F0 D207 6028 4540 4160 4790 D207 6028 4548 ÝK.-.. .-..K.-...Ý 00200 4160 47C8 D207 6028 4550 41E0 B29E 90BE Ý.-.HK.-..&.\....Ý 00210 4178>9220 4B38 9220 4B3A 58F0 43A0 05EF Ý..k...k....0....Ý 00220 9410 4B3A 9601 4B30 5870 B306 4100 00FD Ým...o...........Ý 00230 8900 0018 1607 4510 B234 0A0A 5010 4D18 Ýi...........&.(.Ý 00240 4510 B248 0000 0050 0000 0058 E000 0A04 Ý.......&....\...Ý 00250 12FF 4770 B6B2 9200 4B38 9878 4058 1A87 Ý......k...q. ..gÝ 00260 5800 4060 1B80 1818 5080 409C 5080 40A0 Ý.. -....&. .&. .Ý 00270 5080 4028 4177 0014 5070 4070 4177 0514 Ý&. .....&. .....Ý INSTR: MVI 2872(4),X'20' OFF: 0212 ( 530) ADDR: 00212 ( 530) DSN: SYS1.LINKLIB LEN: 4128 ( 16680) BASE: 00000 ( 0) CCHHR: 000E000001 TTR: 007801 * * * * * * * * * * * * * * * * * * * * * * * FIGURE 4. This illustrates a use of Fullscreen ZAP in FULLVOL mode. The record being pointed to is Record 3 of Track 0 which is the Disk Volume Id Standard Label. Notice that in FULLVOL mode on pack MVS001, the "dataset name" is always: VOLUME MVS001, in the "where" information at the bottom of the display. Z A P ENTER VALID COMMAND ABOVE OR ? FOR HELP VERSION=2.3G 25JUL89 R+2 00000 >E5D6 D3F1 E5D6 D3F1 D4E5 E2F0 F0F1 4000 ÝVOL1VOL1MVS001 .Ý 00010 0000 0401 4040 4040 4040 4040 4040 4040 Ý.... Ý 00020 4040 4040 4040 4040 40C3 C2C9 D7D6 4040 Ý CBIPO Ý 00030 4040 4040 4040 4040 4040 4040 4040 4040 Ý Ý 00040 4040 4040 4040 4040 4040 4040 4040 4040 Ý Ý 00050 4040 4040 Ý Ý OFF: 0000 ( 0) ADDR: 00000 ( 0) DSN: VOLUME MVS001 LEN: 0054 ( 84) BASE: 00000 ( 0) CCHHR: 0000000003 TTR: 000003