MVS TOOLS AND TRICKS OF THE TRADE April 1989 Sam Golob MVS Systems Programmer ENLARGING THE VTOC OF AN ACTIVE DISK PACK This monthly column is for sharing practical advice and techniques which can be employed in your shop. In this issue, we will provide a means for enlarging the VTOC, or "Volume Table of Contents", of an active disk pack. The NASCOM HIGHLIGHTS of December '88 have emphasized the enormity of the need for that information. We encourage readers to contribute to this column. We depend on you for its continued success! Contributions can be sent through NASCOM, or you can write to me care of the Editor. The contributor's name will be mentioned when his technique is printed in this column. If software tools are required for any of the techniques, we will mention tools that are available to the public. Of course, if a vendor product suffices for a particular user, that is fine, too. There is a tremendous public domain literature of MVS tools. Many useful tools can be found on NaSPA's own V.I.P. tapes, and we will draw heavily from the Connecticut Bank and Trust MVS Utilities tape, known as the CBT tape (which is available online at www.cbttape.org). A list of sources for MVS tools can be found in the January issue of "Technical Support". Our technique for dynamically enlarging the VTOC of an active pack can also be found on File 29 of the CBT MVS Utilities tape. I have preferred to use a "cookbook approach" in the explanation, because of the delicacy and care with which the job has to be done. So without further ado...... RECIPE TITLE: Enlarging the VTOC of an active disk pack, without impact on the users of the pack. INGREDIENTS. Our most helpful tool is the UCLA Full Screen ZAP program that can be found on the CBT tape, File 300. You can use other zapping tools, but this one enables you to really see what is going on, and it's fast. To use Full Screen ZAP to update a VTOC, it'll have to run authorized. Zap your module IKJEFTE2 (in load module IKJEFT02. (This is outdated--IKJEFTE2 can either be found in PARMLIB in member IKFTSOxx under AUTHCMD NAMES (..etc) or in an APF-authorized STEPLIB library, assembled into module "IKJTABLS".) with the name "ZAP", put the program in an authorized library, and make sure it's linkedited with SETCODE AC(1). Authorize it another way if you're sophisticated. (Hint: to save an IPL (since IKJEFT02 is usually in LPALIB), make a copy of load module IKJEFT02 with all its aliases, in an authorized steplib or in a linklist library, and zap that copy. Make sure to get rid of it later, or it may cause confusion.) You'll need an MVS SPL DEBUGGING GUIDE to show you the format of the different DSCB's (VTOC entries). I shall assume that you have a Debugging Guide. If you are really stuck without a Debugging Guide, you can expand the macro IECSDSL1, which maps all the VTOC entry formats. The macro is in SYS1.AMODGEN. You can assemble the coding example I have given for this macro, and you'll get a description of all the format types. I'll also assume you have ISPF. I certainly hope that you do! The ABE Editor from Tom Smith at Kimberly-Clark in Neenah, Wisconsin, will also be OK. This fine editor, written in PL/I, is a public-domain product. I'm including 2 job streams. The one called OSVTOC converts a pack with an indexed VTOC into an old-style OS VTOC, which we'll need to do, if the VTOC is indexed. The job IXVTOC converts the OSVTOC back to indexed format. You'll do this after you've enlarged the VTOC, if it was originally indexed. One more tool is necessary. You'll have to obtain a track map of the pack. That is, you'll need to find out where your VTOC is on the pack, and what datasets are just below it. (This makes sense, because you have to expand the VTOC to the space just beyond it.) I use the UCLA VTOCLIST program on File 149 of the CBT tape. Execute it with PARM=MAP (which gives the track map). IEHMAP (CBT tape File 083) will do it too. If you insist on using IBM utilities, use IEHLIST. A job to run the VTOCLIST program is included. PROCEDURE. Assuming you now have all the ingredients available, here is what you do. 1. Make sure you have at least 5 or 6 free DSCBs (VTOC entries) on the pack. This is especially critical if the VTOC is currently in INDEXED format. If the VTOC is not indexed, then one or two free entries will suffice. Move datasets off the pack, or delete some, to get the necessary free DSCBs. (If you don't know if a pack is currently indexed, there must be 2 conditions for it. The DS4VTOCI bit in the FORMAT4 DSCB (volume header DSCB) must be on, and also, that there is an INDEX dataset, with name of the type SYS1.VTOCIX.VOLSER on the pack.) 2. If the pack is indexed, run the job OSVTOC to convert the VTOC to non-indexed format. This will require a few free DSCBs to be available (for new FORMAT5 DSCBs to describe free space on the pack). The job will require an operator reply of "U". The job does not delete the dataset SYS1.VTOCIX.VOLSER on the pack. In fact, you will need to have this dataset later, when you convert back to indexed format, so just leave it alone. 3. Get a TRACK MAP of the pack. Determine how many new VTOC entries you want. On a 3380 there are 53 entries per track. This number, in binary, is in field DS4DEVDT of the FORMAT4 DSCB. Once you've decided how many new entries you want, clear the appropriate number of tracks just after the extent where the VTOC currently is. Do this by moving any datasets that are there off the pack (or to any other place of your preference). 4. Using the job VTEXALLC (modify it for your needs and use the MVS JCL manual for reference), allocate a new dataset, with DCB attributes LRECL=96,KEYLEN=44, DSORG=PS,RECFM=F. At this point, run another track map to make sure your new dataset is right after the VTOC. Delete and reallocate if necessary, until you've gotten it right. Make sure the dataset has enough tracks. BE CAREFUL WITH THIS. 5. Now edit the dataset with ISPF. There should be no lines in the dataset. Insert a line and save it. Make sure you are NOT IN NUMBER MODE. To do this, issue the ISPF edit command "NUMBER OFF". The two commands in succession "RENUM" then "UNNUM" will also do it. Get into hex mode (ISPF command "HEX"). Convert every blank to x'00'. Make sure you've done it for ALL 140 CHARACTERS. Be very careful. Then save the line again. Repeat the line of hex zeros many times. (Do it more than the 795 entries per 3380- cylinder.) Now attempt to save the edit. If you don't go down with a D37 abend, you probably didn't repeat the line enough times to fill all the tracks of the dataset. Make sure you get ABEND D37 on the save. If not, repeat the line (each line becomes a new FORMAT0 VTOC entry) more times, and save again, until you get an ABEND D37. The attempted "SAVE" has now formatted the dataset to look something like a blank VTOC. 6. Now you have to use Full Screen ZAP. If you're using another zapping tool, you can accomplish the same things with it, but probably not as easily. To get the FORMAT4 VTOC entry on the TSO screen, you have to have a cataloged dataset on the pack. If there are none, catalog a NONVSAM dataset on the pack (with ISPF 3.2) using some garbage name. (This is what you need another free DSCB for.) See the instructions later in this article for how to look at and modify VTOC entries with the UCLA Full Screen ZAP program. (I'll assume henceforth that you know how to do this.) You should keep a track map of the pack in front of you. You must now change two things on the FORMAT4. Number one, you must modify the SECOND EXTENT DESCRIPTOR (giving the high track address - the upper limit of the VTOC) so it points to the end of your new extension dataset that you put after the VTOC. The layout of the extent descriptors is described in detail under FORMAT3 (detailed in the SPL Debugging Guide under control block DSCB3). They are 10 bytes in length and give the cylinder and track numbers in binary. If you used VTOCLIST to get the track map, and Full Screen ZAP to see the FORMAT4 DSCB, it should be quite clear where the descriptors are. Use the Debugging Guide (DSCB4) or the assembly of the mapping macro (described above) and be careful. When you are satisfied you've done everything right (you can ruin access to the pack if you didn't), make the change permanent. Now you must turn the DIRF bit on: this is DS4DIRF on the FORMAT4. Make the change permanent. Finally, you must delete the VTOC entry for the new dataset which is right after the VTOC. This is so that the VTOC "thinks" that there is no dataset there. You do this by setting the entire entry to hex zeros. In Full Screen ZAP, the "F" command F/dsname/ can be used to find the correct FORMAT1 DSCB. The command "SET00" sets the entire record to hex zeros, and the command "ZAP" makes the change permanent. These 3 items: a) Changing the second extent descriptor. b) Turning on the DIRF bit in the FORMAT4. c) Zeroing out the FORMAT1 VTOC entry of your new formatted VTOC extension dataset, complete the VTOC zaps that must be done. 7. Now get out of ZAP, get a ZAP log, and get into ISPF 3.2. Try to allocate another dataset on the pack. If you have access to an operator console, you should see a message to the effect: "VTOC CONVERT ROUTINE ENTERED - REASON DIRF". This should probably be the only console message you get. You may get a message that the routine was successful, but you may not. In any case, if you get any message that the routine was unsuccessful, you should immediately set the FORMAT4 DSCB back to what it was (so you don't kill access to the pack), scratch your head, and try again. I'll assume you were successful so we'll look at the next step. 8. You now should have an extended VTOC. Run VTOCLIST again to verify the number of free DSCBs on the pack, or use ISPF 3.4 (in ISPF release 2.3) or ISPF 3.7 (for previous releases) or any other method of checking the number of free DSCBs. If your VTOC was originally not indexed, you're home free. Otherwise, 9. Run the job IXVTOC to reconvert the VTOC back to indexed format. Remember that the operator will have to reply "U". 10. Now your boss should applaud you, and put you in for a raise or a bonus. If you have any questions or problems in doing this, I hope I'll be available (during the day, please: unless your shop is about to die). My phone number is on the CBT tape, File 029, or call the editor of "Technical Support" or (201) information if you need to contact me. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * APPENDIX A. ZAPPING A VTOC ENTRY WITH UCLA FULL SCREEN ZAP ---------------------------------------------- ****** IT IS ADVISABLE TO ZAP SOME LESS-MEANINGFUL DATASETS ****** BEFORE TACKLING A VTOC. I am referring to the ZAP program available on File 300 of the CBT MVS Utilities tape. This is Jim Marshall's library of TSO commands. I assume you have the ZAP program properly installed. It is a TSO command, and it must be executed authorized in order to zap a VTOC entry. If you can't do this, please consult your local TSO guru until you've gotten it right. (For most other uses, ZAP doesn't have to be authorized). To get to the VTOC on a given pack do the following: (I am assuming that the pack name is PACK01, and there is a cataloged dataset on PACK01 called SYS2.DATASET). a. Invoke the ZAP program authorized: ( Enter the command: ZAP ) ( In my shop, there's a "magic" SVC, so I enter either "OP Z" or "$$ ZAP" ) b. The system comes back with: "ENTER DATA SET NAME" Enter: 'FORMAT4.DSCB' ALLOCD('SYS2.DATASET') If 'SYS2.DATASET' is cataloged to PACK01, you'll get the FORMAT4 DSCB of PACK01. All the other DSCB's come afterwards. * Note. If you're zapping another dataset, just enter its TSO-qualified name. c. The system will now display the FORMAT4 (header) DSCB. The ZAP program has a built-in tutorial that can be entered by putting "?" on the command line. To get out of the tutorial, put "U" on the command line. Changes are made permanent with the command "ZAP". d. Advice: Learn the tutorial first. You can always get into it by entering "?" on the command line, and back to where you were by entering "U" on the command line. The tutorial has 13 screens. At least glance at them all. You don't put spaces between the command and the operand. The command "END" quits you out of ZAP at any time. The command "P" gets you to the beginning of the FORMAT4. There is a little arrow "<" or ">" that points to the current byte. Go forward and backward by entering plus or minus the number of bytes in hex. For example: +3 (3 bytes forward), -c (x'c' bytes backward), etc. To substitute up to 8 bytes starting from the current byte, enter "S" followed by a hex value--no spaces in between. To make changes permanent, enter "ZAP". Always get a ZAP log if you've changed something, until you're completely familiar with the program. APPENDIX B. JOBSTREAMS. //* * * * O S V T O C * * * //TSTBSP2N JOB ,'TECH.SUPPORT',CLASS=M,NOTIFY=TSTBSSG,TIME=1440, // MSGLEVEL=(1,1),MSGCLASS=T //*******************************************************************// //* NOTE..... THIS WILL ASK OPERS FOR A REPLY - YOU NEED A "U" IF OK. //*******************************************************************// //* ------------------------------------------- *// //* INVOKE THE DEVICE SUPPORT FACILITY PROGRAM //* ------------------------------------------- *// //****************************************// //* CONVERT IXVTOC TO OSVTOC: //****************************************// //S1 EXEC PGM=ICKDSF,TIME=1439 //SYSPRINT DD SYSOUT=* //VPDNV01 DD VOL=SER=PDNV01,UNIT=SYSDA,DISP=SHR, <=== CHANGE ALL // DSN=SYS1.VTOCIX.VPDNV01 <=== OCCURRENCES OF VOLSER NAME. BUILDIX DDNAME(VPDNV01) OSVTOC /* //* * * * I X V T O C * * * //TSTBSP2N JOB ,'TECH.SUPPORT',CLASS=M,NOTIFY=TSTBSSG,TIME=1440, // MSGLEVEL=(1,1),MSGCLASS=T //*******************************************************************// //* NOTE..... THIS WILL ASK OPERS FOR A REPLY. "U" IF OK. **** //*******************************************************************// //* ------------------------------------------- *// //* INVOKE THE DEVICE SUPPORT FACILITY PROGRAM //* ------------------------------------------- *// //****************************************// //* REBUILD INDEXED VTOC: //****************************************// //START EXEC PGM=ICKDSF,TIME=1439 //SYSPRINT DD SYSOUT=* //VPDNV01 DD VOL=SER=PDNV01,UNIT=SYSDA,DISP=SHR, <=== CHANGE ALL // DSN=SYS1.VTOCIX.VPDNV01 <=== OCCURRENCES OF VOLSER NAME TO YOURS BUILDIX DDNAME(VPDNV01) IXVTOC /* //* * * * V T E X A L L C * * * //TSTBALLV JOB ,'TECH.SUPP-SAM.GOLOB',CLASS=M,NOTIFY=TSTBSSG, // MSGLEVEL=(1,1),MSGCLASS=T TYPRUN=HOLD //***************************************************************// //* ALLOCATE MODEL DATASET THAT LOOKS LIKE DCB OF A BLANK VTOC *// //***************************************************************// //ALLOCDX EXEC PGM=IEFBR14 //SYS00058 DD DSN=TSP.VTOC,DISP=(OLD,DELETE),UNIT=3380, // VOL=SER=PDNV01 //ALLOCIX EXEC PGM=IEFBR14 //SYS00058 DD DSN=TSP.VTOC,DISP=(NEW,KEEP,DELETE),UNIT=3380, // DCB=(RECFM=F,BLKSIZE=96,DSORG=PS,KEYLEN=44),VOL=SER=PDNV01, // SPACE=(ABSTR,(15,6615)) <=== ABSOLUTE TRACK ALLOCATION. //* <=== YOU'LL HAVE TO CHANGE IT. //* <=== SEE THE MVS JCL MANUAL. * * * * 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 , //* * * * V T O C L I S T * * * //TSTBSP2M JOB ,'TECH.SUPPORT',CLASS=M,NOTIFY=TSTBSSG, // MSGLEVEL=(1,1),MSGCLASS=T TYPRUN=HOLD //* //* THE VTOCLIST PROGRAM IS OBTAINABLE FROM FILE 149 OF THE CBT TAPE. //* //VTOCLIST PROC SOUT='SYSOUT=*', // U=DISK, // VOLID='INVALID' //********************************************************************* //* ***** M A P D I S K - V T O C / D I R E C T O R Y D U M P * //*****************************************************************RHD* //VTOCLIST EXEC PGM=VTOCLIST,PARM='MAP' //STEPLIB DD DISP=SHR,DSN=TST.TSO.CMDLIB //VOL1 DD UNIT=&U,VOL=SER=&VOLID,DISP=SHR //SYSPRINT DD &SOUT, // SPACE=(CYL,(1,2)), // DCB=BLKSIZE=990 //SYSUDUMP DD &SOUT // PEND //* //PDNV01 EXEC VTOCLIST,PARM='MAP', // SOUT='SYSOUT=*', /*** DEF = SYSOUT=A ****/ // U=3380, /*** DEF = DISK ****/ // VOLID=PDNV01 //*