MVS TOOLS AND TRICKS OF THE TRADE April 1995 Sam Golob MVS Systems Programmer sbgolob@cbttape.org Sam Golob is a Senior Systems Programmer VTOC TIDBITS - PART I Sometimes, even we systems programmers get a bit depressed, and we need to do something exciting to get us out of it. Once, I was assigned a long series of humdrum problems to work on, one after another. I was starting to forget that I have a set of skills. Then one evening, one of my colleagues came into my room all in a panic. She had deleted a dataset on a new MVS res pack, and she had no backup. Could I please help her get the dataset back? I sat down for about an hour, and constructed a brand-new Format 1 VTOC entry for the dataset, completely zapping it out of a Format 0 (blank VTOC entry) by hand. And I got it to work perfectly. That was the boost I needed to climb out of my depression and prove to myself that I was worth my pay. This month, I don't have space to tell you how I did that. But I'd like to spend some time talking about fundamentals related to this. We will discuss some of the structure of the DASD table of contents, known as the "VTOC" for a disk pack. There are some interesting fields buried in some of the VTOC records, and one can only gain by knowing about them. When a disk pack is initialized by the ICKDSF program, the system programmer specifies the size (in tracks) and location of the VTOC on the disk pack. Sometimes the VTOC is placed at the beginning of the pack; sometimes it is placed in the middle. If a VTOC index is specified, its placement is also determined at initialization time. At this point, I'd just like to mention that if I'm initializing a pack, my personal preference is to place the index (if it exists) just behind the actual VTOC, as opposed to just after it. That is because the VTOC index dataset is hard to move. If you'd later need to enlarge the VTOC, the space just after the end of the VTOC should be easily available to expand into, and with the index there, matters become much tougher. VTOC STRUCTURE. Getting back to basics, Track 0, Record 3 of an initialized disk pack contains the volume serial name of the pack. This record also contains a pointer to the CCHHR location of the VTOC as referenced from the beginning of the pack. That is how the VTOC, and ultimately the datasets on the pack, can be located by the operating system. The VTOC itself is a direct access, fixed-length unblocked dataset consisting of the same size records in as many as six, seven or eight different formats. There is a 44-byte key at the beginning of each record, and there are 96 bytes of data which follow the key. That makes 140 bytes in all. The VTOC itself originally contained all or most of the information necessary to describe dataset extents on a disk pack. A "VTOC Index" dataset is an optional and relatively new development. It is a separate dataset which keeps track of free space on the disk. If the disk pack is not SMS-managed, the VTOC Index is not absolutely necessary, and if one exists for a non-SMS pack, we can enable or disable it as we need to. This month, we will not discuss any details about the VTOC Index itself. VTOC RECORD FORMATS. There are six (and now possibly seven) non-zero formats among VTOC records, known more technically as DSCB's or "Data Set Control Blocks". The formats are named by number. We refer to a "Format 1 DSCB" or a "Format 5 DSCB". Each one of these formats serves a specialized purpose. In addition, there are blank VTOC records consisting of 140 bytes of all hex zeros. These "empty slots" in a VTOC are called "Format 0 DSCBs". Please see Figure 1 for a summary of all the VTOC record formats. Six VTOC formats are mapped by a macro in SYS1.MODGEN (or SYS1.AMODGEN) called IECSDSL1. See Figure 2 for an example of how to code this macro to display these six VTOC formats. There is now a seventh VTOC format (called a Format 7 DSCB) that was created to track the free space on the new 3390 model 9 disk packs. The model 9's have three times the number of cylinders that a 3390 model 3 has. And they are so large, that normal Format 5 DSCB's cannot describe their free space. Therefore, the Format 7 DSCB was created. The Format 7 DSCB is described by a macro called IGGDADS7, which I was unable to find on my MVS/ESA 4.3 system with DFSMS 1.0. Maybe you'll have better luck looking for it on your system. TOOLS TO USE. My philosophy (at least for systems programming), is that it is better to see than to be blind. That's what we collect tools for. I'll show you some IBM tools first. To print out a VTOC of a disk pack, you can use the IBM tool IEHLIST with its LISTVTOC DUMP control card. The DFP Utilities manual will tell you all the details. IEHLIST is a fine tool for this purpose. After you've used IEHLIST to display all the VTOC records, you can then use the IBM superzap program called AMASPZAP with its CCHHR control cards, if you need to change any VTOC fields. AMASPZAP is documented in IBM's Service Aids manual. There are versions of the Service Aids manual that have been published for all releases of MVS. Any of them can help you. However, I myself don't use the IBM tools. Instead, I use the Fullscreen ZAP TSO command from the CBT MVS Utilities Tape. Program source for Fullscreen ZAP is on File 134 of that tape, and a load module is on File 135. You can order the CBT MVS TAPE through the NaSPA office. Fullscreen ZAP will accomplish both the function of IEHLIST, and the function of AMASPZAP. Moreover, ZAP operates interactively on the screen, very quickly. Since Fullscreen ZAP has a lot of power, it should of course be restricted to qualified systems personnel only. But used properly, ZAP shows you a lot about the VTOC fields in real time, right on your screen. See Figures 3 and 4 for sample ZAP screen images. To use the ZAP command to display the start of the VTOC for pack AKD001, simply enter (from the ISPF command line): TSO ZAP 'FORMAT4.DSCB' VOL(AKD001). ZAP contains a full system of help screens, which you can use by typing a question mark on its command line. You also have a detailed report of what record you are in, what volume you're looking at, and a HEX and EBCDIC character display of the current record. ZAP can easily change the record you're looking at. If you're altering fields in a VTOC, the index must be disabled, and you had better be very, very careful and know exactly the effect of what you're doing. Nevertheless, ZAP keeps track of what it changed, and you can print its log out. SOME FACTS ABOUT THE VTOC HEADER RECORD. Our discussion of specific VTOC formats will begin with the "Format 4 DSCB". The Format 4 is the first record of the VTOC for a disk pack, and it can be correctly referred to as the VTOC Header record. There is exactly one Format 4 DSCB for each pack. The Format 4 DSCB defines and reflects many of the logical and physical characteristics of the pack, and we will see some very interesting things in it. The 44-byte key of the VTOC Header consists of 44-bytes (2C in hex) of hex '04'. The later fields, with specific information, follow the key. It seems that because of this, the Format 4 DSCB differs from all other VTOC formats. For other formats, +0 displacement into the VTOC entry begins at the beginning of the key, or in other words, at the beginning of the record. For the Format 4 DSCB, displacement +0 begins at +2C from the beginning, or at the beginning of the data. In other words, +0 into a Format 4 DSCB starts at the 45th byte from the beginning. I'm not sure why IBM made that decision, but it seems from the externals that since there is no real information in the key of a Format 4 DSCB, we might as well start looking from where the actual information is. All other VTOC formats have real information in the first 44 bytes, and some of them (Formats 2, 3, 5, and 6) use abbreviated keys and not full keys. I'll show you some interesting things in the Format 4. The Format 4 describes the entire pack. At +1E into the Format 4 (which is really +4A from the beginning of the record) there is a one byte field which tells how many DSCB's will fit on one track of this pack. The next byte, +1F, tells you how many PDS directory blocks will fit on one track of this pack. For a 3380, the numbers are: 53 VTOC records (hex 35) and 46 directory blocks (hex 2E) per track. For a 3390, the numbers are smaller: 50 VTOC entries (hex 32) and 45 directory blocks (hex 2D). Evidently, the inter-block gaps on a 3390 are bigger than the ones on a 3380. At +10 in the Format 4, if bits X'C0' are turned on, the pack is SMS-managed. If they are turned off, the pack is not SMS-managed. The two bytes at +12 tell you how many logical cylinders there are on the pack. For example (see Figure 3), on a 3390 model 3, there are X'D0C' or decimal 3340 logical cylinders on the pack. The corresponding numbers for a 3380K are X'A60', or decimal 2656 logical cylinders. At +14, there is a two-byte field which tells you how many tracks there are in a cylinder. For both the 3380 and the 3390 devices, this number is X'000F', or 15 tracks per cylinder. At +16, the device track length in bytes (hex) is displayed. For a 3380, the track length is X'BB60' or 47968 bytes. For a 3390, the track length is X'E5A2', or 58786 bytes. I don't have space this month to go into some of the VTOC indicator flags that are located at +C into the Format 4. If you print out all the VTOC formats for yourself, using the IECSDSL1 macro as in Figure 2, you will acquire a lot more information than I can mention now. Especially with an IEHLIST "LISTVTOC DUMP" in front of you, a bit of study will send you on your way to becoming an expert in this area. We'll continue on this topic next time. Meanwhile, good luck and good hunting! * * * * * * * * * * * * * * * * * * * * * * Figure 1. A Quick Summary of the VTOC formats. FORMAT 0 DSCB - Blank entry FORMAT 1 DSCB - Dataset descriptor FORMAT 2 DSCB - ISAM dataset information FORMAT 3 DSCB - Location of extra extents FORMAT 4 DSCB - VTOC Header Record FORMAT 5 DSCB - Chained Free Space Descriptors (if VTOC index is disabled or is not there) FORMAT 6 DSCB - Cylinder sharing FORMAT 7 DSCB - Free Space Descriptors for 3390 model 9 (or future large-capacity disk packs) Every VTOC begins with a Format 4 DSCB. It is always followed by one Format 5 DSCB. This Format 5 DSCB will begin a chain of other Format 5's to describe the free space on the volume if there is no VTOC Index, or if the VTOC Index is disabled. * * * * * * * * * * * * * * * * * * * * * * Figure 2. This is how to code the IECSDSL1 macro from SYS1.AMODGEN or SYS1.MODGEN, to display DSECT descriptions of all six (older) VTOC formats. * * * * V T O C D E S C R I P T I O N * * * * ASSEMBLING THIS GIVES VTOC FORMATS FOR ALL TYPES OF * VTOC ENTRIES. (SYS1.AMODGEN) IECSDSL1 1 , FORMAT 1 DSCB IECSDSL1 2 , FORMAT 2 DSCB IECSDSL1 3 , FORMAT 3 DSCB IECSDSL1 4 , FORMAT 4 DSCB IECSDSL1 5 , FORMAT 5 DSCB IECSDSL1 6 , FORMAT 6 DSCB END , * * * * * * * * * * * * * * * * * * * * * * Figure 3. This is a Format 4 DSCB as pictured by the Fullscreen ZAP program from the CBT MVS Utilities Tape, File 134. That program is a TSO command. To obtain the result pictured here, you enter TSO ZAP 'FORMAT4.DSCB' VOL(AKD001) . This gets you to the VTOC Header for the pack AKD001. Fullscreen ZAP has a complete HELP sequence, which you can enter by typing a question mark on the command line. From the help sequence, if you type a U, you get back to where you were. This volume is a non-SMS 3390 model 3. Z A P _ ENTER VALID COMMAND ABOVE OR ? FOR HELP VERSION=2.3G 17AUG92 00000 >0404 0404 0404 0404 0404 0404 0404 0404 *................* 00010 0404 0404 0404 0404 0404 0404 0404 0404 *................* 00020 0404 0404 0404 0404 0404 0404 F400 0200 *............4...* 00030 0E32 07A1 0D0B 0000 000F 8B01 0000 0D0C *...~............* 00040 000F E5A2 0000 0020 0000 322D 0000 0000 *..Vs............* 00050 0000 0000 0000 0000 0000 0000 0000 0000 *................* 00060 0000 0000 0000 0000 0001 0000 0000 0100 *................* 00070 0200 0E00 0000 0000 0000 0000 0000 0000 *................* 00080 0000 0000 0000 0000 0000 0000 *............ * OFF: 0000 ( 0) ADDR: 00000 ( 0) DSN: VTOC FOR AKD001 LEN: 008C ( 140) BASE: 00000 ( 0) CCHHR: 0000000101 TTR: 000001 * * * * * * * * * * * * * * * * * * * * * * Figure 4. This is a Format 1 DSCB as pictured by the Fullscreen ZAP program from the CBT MVS Utilities Tape, File 134. From here you can see some of the advantages of using this TSO command for viewing VTOC records. Everything can be seen very clearly. The dataset name is SBHCIT.GARBAGE.DATASET. The dataset resides on an SMS-managed pack called SMQ001. Z A P _ ENTER VALID COMMAND ABOVE OR ? FOR HELP VERSION=2.3G 17AUG92 00000 >E2C2 C8C3 C9E3 4BC7 C1D9 C2C1 C7C5 4BC4 *SBHCIT.GARBAGE.D* 00010 C1E3 C1E2 C5E3 4040 4040 4040 4040 4040 *ATASET * 00020 4040 4040 4040 4040 4040 4040 F1E2 D4D8 * 1SMQ* 00030 F0F0 F100 0158 0019 0000 0001 0000 C9C2 *001...........IB* 00040 D4D6 E2E5 E2F2 4040 4040 405F 002E 8020 *MOSVS2 ‰....* 00050 0296 4000 9000 235C 0092 0000 0080 C000 *.o ....*.k....{.* 00060 0001 0000 02AB 1000 0081 0000 9300 0000 *.........a..l...* 00070 9300 0E00 0000 0000 0000 0000 0000 0000 *l...............* 00080 0000 0000 0000 0000 0000 0000 *............ * OFF: 0000 ( 0) ADDR: 00000 ( 0) DSN: VTOC FOR SMQ001 LEN: 008C ( 140) BASE: 00000 ( 0) CCHHR: 0000000105 TTR: 000005