MVS TOOLS AND TRICKS OF THE TRADE May 1995 Sam Golob MVS Systems Programmer sbgolob@cbttape.org Sam Golob is a Senior Systems Programmer VTOC TIDBITS - PART II Good News You Can Use. I'd like to begin this month's column with some updates to what we've written in the past. There are two items from previous columns. First, I'm happy to inform you that a JES2 Exit Loader (see the September 1994 issue) has been developed by Terry Martin of Baltimore, which dynamically loads all three varieties of JES2 exits: exits resident in the JES2 address space, in CSA, and in LPA. I am hoping that by the time you read this, Terry's code will have been added to the CBT Tape, so you can get a look at it. Now we should be able to dynamically load and test a fresh version of any JES2 exit we are working on, regardless of type. And we won't absolutely require IBM to add such a feature to JES2, at least for now. Our second piece of news refers to a previous three-part series of columns (December 1991 thru February 1992) concerning dataset block sizes and I/O efficiency. Those columns were based on Rick Fochtman's research analyzing channel commands to DASD, which were generated by standard access methods (mainly QSAM). Rick's work was done on an XA 2.2.3 system. He found that when a dataset is allocated in tracks, the seek commands generated by QSAM are limited by the track boundary, and must be clumsily restarted for the next track. Therefore, since QSAM normally attempts to fill up five buffers to receive the data it reads, it would be most efficient to block track-allocated data at five blocks per track. That would allow each read to cover a complete track without restarting, because it would fill up all five buffers completely in the one read. Cylinder-allocated datasets would not have such a problem, because for them, the seeks go past the track boundary to the cylinder boundary, and half-track blocking would still fill all five buffers in one read. Therefore, Rick recommended allocating larger datasets only in cylinders, and smaller ones in tracks, blocked 5 blocks per track. Now, somewhere between XA 2.2.3 and ESA 4.3, IBM seems to have corrected this problem. Rick's current research on his MVS/ESA 4.3 system now shows that DASD seeks generated by QSAM only stop at extent boundaries, even for track allocations, so the previous efficiency problems are now removed. Therefore if you are on a newer ESA system, the best advice for data access efficiency with QSAM is to allocate in tracks, and block two blocks per track, period. Maybe some IBM'ers have been reading this column. Who knows! General VTOC Facts. We resume our discussion of the DASD Volume Table of Contents, known to the world as the VTOC of a disk pack. As we mentioned last month, the VTOC is a fixed, unblocked, keyed file on the disk pack, whose record length is 140, of which the first 44 bytes constitute the key (and the other 96 bytes, the data). How does the operating system find the VTOC of a pack? The first record in the VTOC is pointed to by the VOLVTOC field (5 bytes at hex +B into the data area) of the disk label of the pack. That is what the system uses to find where the pack's VTOC is. The disk label is on Track 0, Record 3 of every pack initialized under MVS. Its fields are described after the DXLBL or VOLAREA labels in the IECDSECT macro which is in SYS1.MODGEN. The disk label is 84 bytes long, of which the first four bytes are a separate key, not described by the IECDSECT macro. See Figure 1 for a picture of the Disk Volume Label record, as shown by the "Fullscreen ZAP" TSO command in FULLVOL mode. This command comes from File 134 of the CBT MVS Tape, which can be ordered from NaSPA. A record in the VTOC is commonly and officially referred to as a "Data Set Control Block" or DSCB. Although most control blocks are in central storage, the DSCB is one of the comparatively few, which are entirely on disk storage. There are currently eight supported formats of VTOC records, colorfully described by IBM as "Format 0" through "Format 7". Figure 2 briefly describes the purpose of each type of VTOC record. DSCB formats 1 through 6 are mapped by a macro in SYS1.AMODGEN or SYS1.MODGEN, called IECSDSL1. Figure 3 shows how to code this macro in order to obtain a map of these six VTOC formats. You can also get a lot of help from an IBM manual, the MVS/DFP System Programming Reference, SC26-4567. Chapters 2 and 3 of this manual provide an excellent discussion and overview of VTOC facts and information. There is probably an equivalent manual in the DFSMS literature. Last time, we looked at the "Format 4 DSCB", which is the VTOC Header Record. Every MVS VTOC has exactly one Format 4 record, and it has to come first. The Format 4 record describes the general geometry of the disk pack, even down to the surprising detail of how many VTOC records will fit on one track of this DASD device, and how many PDS directory blocks will fit on that same track size. Every MVS VTOC has to have one "Format 5 DSCB" following the "Format 4 DSCB" header record. Format 5 DSCB's on a VTOC are chained together to describe the free space, or unallocated extents, of a disk volume. This is true unless the volume has an active "VTOC Index". A VTOC Index is an optional separate file on a disk pack which, if activated, will take over the free-space describing function of the chain of Format 5's. A field in the VTOC Header (Format 4) tells the system if a VTOC Index is present and active on this disk pack. Even if the VTOC Index is active, the first Format 5 record which follows the Format 4 Header record, must always be present. Because even if that Format 5 record isn't being used now, it may be required later, if we'd ever want to forcibly deactivate the VTOC Index (as sometimes we will). This first Format 5 record will then form the beginning of a new chain of Format 5 records describing the un-indexed pack's free space. SMS-mananged packs are somewhat different. SMS-managed packs must always have an activated VTOC Index. For SMS packs, the VTOC Index is required, and not optional. VTOC Dataset Descriptor Records: Format 1 DSCB's. Nearly every dataset on a disk pack is described, at least partially, by a VTOC record known as a "Format 1 DSCB". Today, we'll see just a few of the many properties of our datasets which originate from fields in this powerful data area. For further information and exploration, you should see the "DSCB1" entry in the IBM System Data Areas manual, LY28-1044, or in the DFP System Programming Reference mentioned above. For instance: the DSORG of a dataset is determined by the DS1DSORG field, which consists of 2 bytes of flags at location +52 hex into the Format 1 DSCB. Whether the dataset is PS, DA, PO, VSAM, or Unmovable, is determined by separate flags in this field. Let's see an example of how to exploit this kind of knowledge. I've found one neat way to delete the junk data and index components of an uncataloged VSAM cluster from the VTOC. They are hard to get rid of. The technique involves changing the following fields in the Format 1 DSCB for each component: First turn its DSORG from VS into PS, then zap off the password bits X'14' in the DS1DSIND field at +5D hex, and finally zero out the three-byte expiration date field at +38 hex. Then you can delete the junked data and index components using ordinary means, such as ISPF 3.2 or 3.4. This trick was courtesy of Rick Fochtman, and I can testify that it works fine. A little-known flag is the DS1IND02 bit X'02' in the DS1DSIND byte at +5D hex into the Format 1 DSCB. This flag is used by DASD management packages which do incremental dataset backups. Whenever a dataset is opened for other than input, this flag gets turned on. Opening a dataset for other than input is usually a fair indicator that the dataset was changed. If this flag is on for a dataset, an incremental backup package such as HSM or FDRABR will back up the dataset and then turn the flag off. Thus, you've backed up only datasets which could have changed since the last backup. Of course, the DASD management package must keep a history of when all the backups were done, and be able to synchronize all the data on the pack properly, but this VTOC flag is crucial to making that whole process work. Secondary allocation is another useful thing to know about. When a dataset overflows its extents, in other words: if you want to add more data to a dataset than its disk allocation can currently hold, allocation adds another extent according to the specifications in the Format 1 DSCB for the dataset. The fields affecting us are: DS1SCAL1, a one-byte field of flags at +5E hex, and DS1SCAL3, a three-byte binary number which tells you the size of the extent. DS1SCAL1 is very important, in that it tells you if the secondary quantity is in Tracks, Cylinders, or Blocks. DS1SCAL3 then indicates the quantity of the units specified by DS1SCAL1. Speaking practically, we can show a common case. Suppose a certain dataset has a very small secondary space specified, such as one track. There is a limit of 16 extents on a single volume that can be allocated for a non-VSAM dataset. When that limit is reached, you can't expand that dataset on that volume any more. Let us say that our dataset has overflowed, and has already created 13 extents, 12 of which are one track only (according to the DSCB specifications). We expect the dataset to overflow further, but it is hard to reallocate (like SYS1.VTAMLST, for example). A way to fix this situation would be to zap the Format 1 DSCB of the dataset to specify a much larger secondary extent value, such as 30 tracks. This way, the next time the dataset overflows, a single 30-track extent will be created, and we will have only 14 extents instead of 15 or 16. By doing this, we can head off the trouble before it becomes unmanageable. Last for today, we'll talk about the DS1LSTAR or "high water mark" field of a dataset. DS1LSTAR is a three-byte field located at +62 hex into the Format 1 DSCB for a dataset. DS1LSTAR contains the TTR of the last used track and last used record on the track. If this value lies below the end of the dataset extents, we may find it useful to raise it a bit, so that we can look past the previous end of data location. This is a tricky business, because you have to know that the data which was past what was used, has proper attributes (blocksize, etc.) so as not to cause an I/O error when you try to look at it. Rather than zap DS1LSTAR so you can look past it, it is probably safer to use the REVIEW TSO command from File 134 of the CBT MVS Tape. REVIEW is a powerful fullscreen browsing program which can override such obstacles as DS1LSTAR, and blocksizes of data which are bigger than the block size values in the DS1BLKL field (at +56 hex for two bytes). To use REVIEW to override DS1LSTAR, first REVIEW the dataset normally, and go to the BOTTOM. REVIEW will display the highest TTR value for normal data in the dataset. This is the DS1LSTAR value. REVIEW can override this value with its NEWTOP ttr subcommand. NEWTOP acts as if the new top-of-data is the TTR that you specify after it. If you give NEWTOP a TTR that is past the DS1LSTAR value, REVIEW will attempt to read such data and display it. However, because of block size problems or other I/O errors, this may not work, and REVIEW will tell you so. You may then try to re-invoke REVIEW with its BLKSIZE keyword, which can be used to open the dataset with a bigger blocksize than the DS1BLKL value. Thus, if the data past DS1LSTAR is fairly well behaved, it may very well be possible to view it, and optionally "rescue" it. I'd like to add one more thought before wrapping this discussion up. Nowadays, the Format 1 DSCB for a dataset does not always tell us the whole story. For disk packs with indexed VTOCs, the VTOC Index dataset contains some additional information. Further, if the dataset is cataloged in an ICF catalog, the disk pack's VVDS dataset will also contain information that can affect how the system treats your dataset. The IBM DFP manual called "Managing Catalogs", SC26-4555, covers the VVDS angle quite thoroughly, while the System Programming Reference manual mentioned above, covers the VTOC Index information. This month's discussion has shown that you can gain a lot of knowledge about disk datasets by doing some digging and exploring. Good luck with it. We'll see you next month. * * * * * * * * * * * * * * * * * * * * * * * Figure 1. This is a Volume Label of disk pack AKD001, 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) FULLVOL". Then you advance 2 records by typing command "R" once, and again. Fullscreen ZAP shows the Volume Label record to have 84 bytes decimal (54 bytes hex). However, the first four bytes constitute a separate key, not described by the macro IECDSECT in SYS1.MODGEN. The location arrow < is pointed to the 5-byte location describing the CCHHR of the pack's VTOC Header Record, which is 0000000101. Z A P _ ENTER VALID COMMAND ABOVE OR ? FOR HELP VERSION=2.3G 17AUG92 00000 E5D6 D3F1 E5D6 D3F1 C1D2 C4F0 F0F1 4000< *VOL1VOL1AKD001 .* 00010 0000 0101 4040 4040 4040 4040 4040 4040 *.... * 00020 4040 4040 4040 4040 4040 4040 40C9 D4E3 * IMT* 00030 C8C5 D6E6 D5C5 D940 4040 4040 4040 4040 *HEOWNER * 00040 4040 4040 4040 4040 4040 4040 4040 4040 * * 00050 4040 4040 * OFF: 0000 ( 0) ADDR: 00000 ( 0) DSN: VOLUME AKD001 LEN: 0054 ( 84) BASE: 00000 ( 0) CCHHR: 0000000003 TTR: 000003 * * * * * * * * * * * * * * * * * * * * * * * Figure 2. A Quick Summary of the VTOC formats. FORMAT 0 DSCB - Blank entry (all hex zeros) 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 3. 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 SIX 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 ,