MVS TOOLS AND TRICKS OF THE TRADE May 1997 Sam Golob MVS Systems Programmer P.O. Box 906 Tallman, New York 10982 Sam Golob is a Senior Systems Programmer. IT'S A BIRD, IT'S A PLANE, IT'S SUPRNAME This month, we're going to discuss a nagging problem that has to do with the way MVS is built. The problem is simple, and has to do with dataset protection. To put it plainly, MVS will not let you delete or rename any dataset that is being currently used. That's a normal and desirable situation. However, if you have an uncataloged copy of that dataset with the same name, which you want to get rid of, MVS will not let you do that either. When does this kind of thing happen? The classic case is with VTAM. When VTAM is up (which is practically all of the time), it requires the use of at least two datasets. One is usually called SYS1.VTAMLIB. This contains load modules that VTAM uses to run. The other is called SYS1.VTAMLST, which contains startup parameters and the network definition statements. A normal MVS shop is set up with some redundancy built in. For example, most shops except for the very smallest, have several copies of the system residence disk pack. It would be stupid not to have them. If something happened to the system res pack, there would be no system to recover with, because there would be no pack to IPL from. You'd be left having to do a standalone restore from a full disk backup, if you ever took such a backup. You get the idea. Now, SYS1.VTAMLIB is usually on the system res pack. If something was wrong with the copy of SYS1.VTAMLIB on your alternate res pack, and you had to delete and reallocate it, MVS would not let you do that until VTAM came down. If VTAM is down, TSO is down. This spells "slight inconvenience". What would you do if you were time-constrained and couldn't wait? Let's start studying, by trying to understand how the dataset protection mechanism in MVS works. Before allowing the deletion or renaming of any dataset, the system checks if there is an outstanding enqueue on that dataset with a QNAME of SYSDSN and an RNAME equal to the dataset's actual name. This is done by asking for an exclusive enqueue with these names. (See this column from Feb. 97, entitled "Creative Enqueuing", for further explanation.) In the case of SYS1.VTAMLIB, the QNAME for the enqueue would be SYSDSN, and the RNAME would be SYS1.VTAMLIB. If the system's exclusive enqueue request is unsuccessful because the dataset was currently being used by some task, the system gets a "no can do" condition code in response to its enqueue request, and you can't do the rename or deletion. What if you have an unused copy of the dataset that you want to delete? The system's exclusive enqueue request is exactly the same as if the "real" copy of the dataset was to be deleted, and our deletion request fails. How can we get around this problem? The easiest way would be if we could rename the uncataloged copy of the dataset to something else, without involving the system in doing any enqueues. For example, if we could somehow rename the uncataloged copy of SYS1.VTAMLIB to SYSQ.VTAMLIB, then we could make progress. When the system makes a subsequent deletion request for this dataset, its exclusive enqueue request would then have an RNAME of SYSQ.VTAMLIB, and its deletion request would not conflict with the existing enqueue for SYS1.VTAMLIB that VTAM's task is holding. Enter SUPRNAME. SUPRNAME is a public-domain batch utility which goes directly into the VTOC of a specified pack and renames or deletes a dataset without doing any enqueue. Instead, it does a direct zap to the dataset's VTOC entry. (This is being slightly simplified, so the process is easier to conceptualize.) After this renaming is done, any subsequent renaming or deletion will not conflict with enqueues on "real" datasets that running tasks are currently holding. SUPRNAME is very simple to use, because you don't have to know the exact CCHHR location of the Format 1 VTOC entry you are interested in changing. Control cards for SUPRNAME are described in Figure 2. Alacazam, the problem is circumvented, and you're in business. There's a little more to it. Direct zapping of a Format 1 VTOC entry for a dataset will only be completely effective if the disk pack does not have an operating VTOC INDEX dataset. For non system-managed indexed packs, the VTOC index can be turned off using an ICKDSF batch job that is very simple to run, and only needs an operator reply. After the rename has been accomplished, the VTOC INDEX dataset can get turned on again by an equally simple ICKDSF job. See Figure 1 for an example of both jobs. For system-managed datasets, which always have to be on a pack with an indexed VTOC operational, you don't usually run into this problem, because all those datasets are cataloged and have unique names. With cleverness and knowledge, you can probably get around that situation too. However, system-managed datasets are not the topic of our current problem. How can you obtain a copy of the SUPRNAME utility? The SUPRNAME program is part of a large collection of programs on File 270 of the CBT MVS Utilites Tape. The CBT Tape is an enormous Free Software tape, independently produced, that can be obtained through the NaSPA office. File 270 was contributed by one of the Washington State data processing organizations in Olympia, Washington. SUPRNAME was written by Kermit Kiser. (Thanks, Kermit.) See Figure 2 for Kermit's instructions on how to run SUPRNAME with the proper JCL control cards. Now let's get back to the VTAM situation. We've un-indexed the pack that our extra copy of SYS1.VTAMLIB is on. Now we want to rename that copy of SYS1.VTAMLIB to SYSQ.VTAMLIB while VTAM is still up. Suppose the "extra" copy of SYS1.VTAMLIB is on the ALTRES pack. All we have to do is to set up the JCL from Figure 2, so the VOL=SER keyword in the SYSLIB ddname points to ALTRES, and the SYSIN ddname has control cards of the form: RENAME DSNAME=SYS1.VTAMLIB NEWNAME=SYSQ.VTAMLIB The SUPRNAME program does the rest, and life is very simple for us, after SUPRNAME has done its job. Multiple control cards can be used in a SUPRNAME batch job; we could even rename or scratch every dataset on the disk pack in one SUPRNAME batch run. Scratching a dataset is done with a DELETE control card instead of the RENAME card. Getting back to our particular case, we can do anything we want with SYSQ.VTAMLIB on ALTRES now, and the system will not "object". When we've finished all our dataset manipulations, we can re-index the pack using the IXVTOC job, and all should be well. MORE ON THIS SUBJECT. USING THE FULLSCREEN ZAP PROGRAM. It's nice to rename datasets using a batch job, and it's effective too, but perhaps you would like to actually see what you are doing on a screen. In that case, the Fullscreen ZAP program on File 134 of the CBT MVS Tape is the tool of choice. Fullscreen ZAP originally came from UCLA, but it has been modified by Greg Price of Melbourne, Australia to add enormous power when it runs as an authorized TSO command. Fullscreen ZAP, being an interactive program, will show you the VTOC entry for only one dataset at a time, so in a case where you're renaming many datasets, SUPRNAME is much faster. However, as we shall see, Fullscreen ZAP can be used profitably to check the results of a SUPRNAME run. How does Fullscreen ZAP work? Assume that the load module name for your Fullscreen ZAP program is ZAP. Then we enter (as a TSO command) the following: ZAP dataset.name VOL(volser) where the VOL keyword is only necessary if the dataset is not cataloged. To look at the beginning of a VTOC on a disk pack, we enter, instead of a regular dataset name, the following: ZAP 'FORMAT4.DSCB' VOL(volser) where the VOL keyword is now necessary so we can specify the particular disk pack name whose VTOC we want to examine. The result of this command is to point us to the beginning of the VTOC of that pack. Specifically, we are pointing to the FORMAT 4 DSCB record, which is the VTOC header. All other VTOC records, including the FORMAT 1 dataset records, will follow this header record on the disk pack. One of the great advantages of the Fullscreen ZAP program is its FIND subcommand, entered as "F". To find a hex string, subsequent to the current pointer, one enters F followed by the hex string, without an intervening space. To find an EBCDIC string, one enters an F, immediately followed by the string enclosed in slashes. For example, to find the string, SYS1 in hex, which is X'E2E8E2F1', one enters the command, FE2E8E2F1. Whereas to find the same string in EBCDIC, one enters the command, F/SYS1/ . This is very easy to use. So, to rename SYS1.VTAMLIB on ALTRES to SYSQ.VTAMLIB, using Fullscreen ZAP, one does the following: ZAP 'FORMAT4.DSCB' VOL(ALTRES) This will point us to the beginning of the VTOC on the ALTRES pack. Then one enters the command: F/SYS1.VTAMLIB/ This should point us to the proper FORMAT 1 VTOC entry for the dataset SYS1.VTAMLIB. However, one must examine the screen carefully to make sure that we are not pointing to an entry for a dataset like SYS1.VTAMLIB.NEW, or SYS1.VTAMLIBN, or something similar. A repeat of the F command, without any operands, will take us to the next occurrence of the same string. When we are sure we are in the right place, we wish to change the SYS1 to SYSQ. This can be done, either by replacing the entire string SYS1 in hex, by SYSQ, or by pointing 3 bytes later, and replacing the "1" by a "Q". The command to replace a string is an "S", and its operand has to be entered in hex. Thus, if we are pointing to the "SYS1", we can enter the command: SE2E8E2D8 which will replace all four characters in the string SYS1 which is hex E2E8E2F1, by the four characters E2E8E2D8, which is EBCDIC SYSQ. Or else we can move the current pointer up 3 bytes with a command: +3 followed by the command to replace only the one current byte "1" by a "Q". This would be: SD8 and the result would be the same. The changes are made permanent by the command: ZAP and the old disk values at the specified location are replaced by the new values. If the VTOC index of the ALTRES pack has been turned off by the OSVTOC job, then these renames are effective, and the result is the same as if SUPRNAME had been used to do the rename. Fullscreen ZAP can be used to check the results of a SUPRNAME run, even if it is not being used to do the actual changes. Suppose that SYS1.LINKLIB is being changed to SYSR.LINKLIB and SYS1.LPALIB is being changed to SYSR.LPALIB on pack ALTRES, using SUPRNAME. The SUPRNAME control cards would be: RENAME DSNAME=SYS1.LINKLIB NEWNAME=SYSR.LINKLIB RENAME DSNAME=SYS1.LPALIB NEWNAME=SYSR.LPALIB To check this rename using Fullscreen ZAP, one would enter, under TSO, the commands: ZAP 'FORMAT4.DSCB' VOL(ALTRES) F/SYSR/ F END This should show clearly, on the screen, the renamed FORMAT 1 VTOC entries for the two datasets. If the renames from SUPRNAME did not work, then ZAP should return a message that we are at the end of the VTOC, and we have not found the string. The string SYSR in any other VTOC records could be clearly seen to be different from the dataset names that we expect to see. In summary, I hope that this month's discussion will improve your working techniques, or if you already know this stuff, it will get you thinking on the subject, and maybe you'll figure out ways to to this job even more effectively. Good luck, and I hope to see you again next month. * * * * * * * * * * * * * * * * * * * * * * * * Figure 1. ICKDSF jobs to turn a VTOC INDEX off and on for a disk pack. It is assumed that the pack was originally INIT'ed to be in indexed format. In this example, the name of the pack is PDNV01, and therefore, the name of the index dataset that was originally defined in the pack initialization process, is SYS1.VTOCIX.VPDNV01. The OSVTOC job disables the index dataset, and the IXVTOC job re-enables the index dataset. //* * * * O S V T O C * * * //TSTBSP2N JOB ,'TECH.SUPPORT',CLASS=M,NOTIFY=&SYSUID,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=&SYSUID,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 /* * * * * * * * * * * * * * * * * * * * * * * * * Figure 2. Sample JCL and control cards for SUPRNAME. //* //* update the volser on the SYSLIB card before submitting //* //S1 EXEC PGM=SUPRNAME //STEPLIB DD DISP=SHR,DSN=your.authrizd.steplib //SYSPRINT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSUT1 DD DISP=(,DELETE),SPACE=(TRK,(1,1)), // DCB=(RECFM=FB,LRECL=80,BLKSIZE=80),UNIT=SYSSQ //SYSLIB DD DISP=SHR,DSN=FORMAT4.DSCB,DCB=KEYLEN=44, // UNIT=SYSALLDA,VOL=SER=PDNV01 <=== place correct volser here //SYSIN DD * RENAME DSNAME=ANY.OLD.NAME NEWNAME=ANY.NEW.NAME DELETE DSNAME=ANY.OTHER.NAME or SCRATCH DSNAME=ANY.OTHER.NAME ABSDUMP DSNAME=ANY.NEW.NAME or ABSDUMPT DSNAME=ANY.NEW.NAME CCHHR DSNAME=ANY.NEW.NAME VER 00 C1 REP 00 C2 SAMPLE JCL and control cards for Indexed VTOC case: (use if altering a dsname on an Indexed VTOC) //* Put the OSVTOC job step from Figure 1 first, then //* put the IXVTOC job step from Figure 1 last, //* with all SUPRNAME job steps in between.