ONLCLIP - CHANGING THE VOLSER OF A DISK PACK WHILE IT IS ONLINE (c) Copyright 2020 by Sam Golob. All rights reserved. Today we are going to talk about changing the identity of a disk pack. The identity, or "volume serial", of a disk pack in a z/OS system, is located in Record 3 of Track 0 of the pack, 6 bytes long, after 8 bytes from the beginning of the record. The first 8 bytes contain 'VOL1VOL1', and the nest 6 bytes contain the volume serial id. After that, for 4 bytes, is the CCHHR location of the VTOC for the pack. The normal way to establish, or change the identity of, a disk pack, is to initialize it using IBM's program ICKDSF. ICKDSF is a multi-purpose utility, but for some of its purposes, including the initialization of the disk pack, you have to take the disk pack offline first, before invoking ICKDSF. There is a reason for this. Merely changing the disk id on Record 3 of Track 0, does not tell the z/OS operating system that the disk id of this pack at this unit address has changed. The system uses the disk id that is in the UCB for the device, to figure out what the volume serial of the device is. In order to put the both disk id's in sync: the id on the pack, and the id in the UCB, you have to vary the pack offline, and then vary the pack online again. So this will explain why IBM requires that in order to change a disk id, THEIR WAY, you have to take the pack offline first. So when the pack comes online again, the disk id on the pack, and the disk id in the UCB, will now always be in synchronization. There will never be a mismatch, and IBM will not have to worry. However, sometimes it becomes necessary in our systems programming work, to be able to change the disk id on Record 3 of Track 0 of a pack, while it is still online. We'll talk about the circumstances when we might need to do this. If doing this becomes necessary, we need to have some tools to get the job done. I know of two tools. I wrote one, and I have been using the other one for quite a few years. Both of these tools do not come from IBM. Why would one need to change the id of a pack, while it remains online? Sometimes, you simply can't get the pack offline, for instance, if there is some data on that pack that is constantly being used. If such a pack goes bad, and you restore it from a good backup onto a different unit at a different address, you now have both packs online with the same volume id, although the restored pack has a different UCB volser id now, since it is on a different disk device. To set things right, you will need to IPL. And after the IPL, you will want the bad pack to be inactive. How can you ensure that this will happen correctly? You can accomplish this by renaming the bad pack while it is still online, and after the IPL, the good pack will be the only one functioning online with the correct volume id. THE TOOLS I have two tools which will help us to change the volume id of a disk pack while it is online. The first one (which I have been using for many years) is the TSO command "Fullscreen ZAP", from CBT File 134 or CBT File 300. Fullscreen ZAP has been (very) recently modified to accept the UNIT keyword parameter when the VOLUME keyword parameter is present. This modification is very important for us, so it will be good if you upgrade your copy of Fullscreen ZAP to the latest version. Please remember that recent updates to the CBT collection go first to the Updates page of www.cbttape.org, and only later, when a full CBT Version is cut, do these updates reach the CBT page of www.cbttape.org. Always try the Updates page first, to get the latest software. The second tool is a batch program, called ONLCLIP (or "Online CLIP"). Systems programmers refer to "changing the volume id of a pack" as "clipping the pack". The reason for that, is that one of the first IBM tools for changing the id of a pack (I think it doesn't work anymore) was a standalone program (which you would have to IPL) called: "Change Label Information Program" or "CLIP" for short. Our program is a batch program, which changes only the volume serial of the pack, and nothing else. ONLCLIP can be found on CBT File 846, and JCL to run it, is shown in Figure 1, below. An output report from the ONLCLIP program is shown in Figure 2. ONLCLIP reports on all relevant status, and it produces an audit trail, through WTO messages. Of course, IBM's ICKDSF program is also always available, but we are trying to get around its limitations. USING THE ONLCLIP BATCH PROGRAM See Figure 1 again, to see JCL to run the ONLCLIP batch program. The UCB volser, and the UCB unit address should be coded in the DISKUPD DD statement. The new disk id desired, should be coded in the PARM field, which will always be uppercased inside the ONLCLIP program. Why must the UCB volser be coded in the JCL? The reason is that the system JCL can only read information from the UCB control block, and it does not read the volume serial id that is on Record 3 of Track 0. What comes next? Internally, the ONLCLIP program temporarily adjusts the data extent on the disk pack, in the DEB (Data Extent Block), so that the program thinks that the dataset extents are only one track, Track 0. Therefore, since the program has to temporarily adjust the DEB, it has to run APF-authorized. Before the program finishes, it sets the DEB back to what it was previously. After having made sure that the extents that the program is "looking for", consist of only Track 0 of the pack, the program then proceeds to copy the entire contents of Track 0 to a buffer which has been GETMAINed by the program. In that buffer, the program finds Record 3, and changes ONLY the volser that was found there, inserting the volser from the PARM field instead. This is the only change that the program makes to Record 3. Then the program "rewrites in place" the entire Record 3, because a "rewrite in place", CCW opcode X'85', does not wipe out the IPL records (if they exist) on Track 0 that are after Record 3. In the process of doing all of this, the ONLCLIP program keeps track of everything important. Its SYSPRINT report shows the time and date of execution, the UCB unit address and UCB volser of the pack, the "old" Record 3 volume id, and the "new" Record 3 volume id. The SYSPRINT output even advises you that no changes will occur in the UCB for the unit, unless the pack is varied, first offline, and then online again. In addition, a WTO is issued with the same information, but without the date and time, because the date and time are included in the JES execution reports already. Thus the ONLCLIP program produces an audit trail of what it did, and when it did it. SECURITY FOR ONLCLIP, AND CHECKING THE RESULTS ONLCLIP requires RACF authorization in the following way. We need to define a FACILITY class profile called TBCXTUL, and ONLCLIP needs to have READ access to that profile. (TBC is CBT backwards, X, TUL stands for tools.) If ONLCLIP does not have READ access to this profile, then the program is aborted with an appropriate message. ONLCLIP also needs APF-authorization. That is, it needs to be linkedited with SETCODE AC(1), and it needs to be run from an APF-authorized library. Since it is really a system programmer tool, and it is not run often, I figured that while it is run under system programmer supervision, the system programmer would either: 1- Know how to be careful with it. 2- Keep it away from other people and operators, except under controlled conditions. And 3- If the systems programmers would set up a procedure for the operators to use it on a one-time basis, there is enough of an audit trail to determine that the job was done successfully and correctly. After the ONLCLIP job is run, the systems programmer can physically check on the results using several methods. The first method is to print out the entire Track 0 of each pack, using the JCL in Figure 4, which runs the ADRDSSU program, pointing to the UCB unit address, as well as to the UCB volser. It is not generally known (but it is in the book) that you can specify the unit address, as well as the volser, in the INDYNAM statement under ADRDSSU. The second method is to use Fullscreen ZAP with the FULLVOL operand, as a checking tool to verify how ONLCLIP worked, even though you can (now) do the entire job (of both zapping and checking) using Fullscreesn ZAP as well. We have very recently (Feb 2020) modified Fullscreen Zap (CBT Files 134 or 300) so that it can take a UNIT( ) parameter as well as a VOL( ) parameter. So if there are two packs online with the same volser (which can happen when you restore a pack from a backup), you can specify the unit address as well, to Fullscreen ZAP, and it can direct the search to the pack you want to look at, or change. Without the modification to recognize the UNIT parameter, Fullscreen ZAP was restricted to accessing only the volume whose unit address came earlier in the UCB lookup table (usually the pack with the unit address lower in the EBCDIC collating sequence. I have found that if you are running z/OS under VM, and the pack you are looking at is "read only" under VM, then ONLCLIP, or Fullscreen ZAP, will not be able to change the volume id. Besides being obvious, this is probably what you would want anyway. If the VM systems people would be willing to allow write access to the pack in question, then you can do what you want. But that security is there, if you're running under VM. By experimentation, I have seen that it works as I haave described. USING FULLSCREEN ZAP TO CHECK OR CHANGE THE VOLUME ID The TSO Fullscreen ZAP program can both look at, and change, storage. With its FULLVOL operand, that has to be run APF-authorized, the DEB of the volume is "fooled" to "think" that the extents of the dataset being zapped or looked at, IS THE ENTIRE VOLUME. So therefore, when you invoke ZAP in FULLVOL mode, the first thing you get to see is the Track 0 data for the pack. The command is: TSO ZAP 'FORMAT4.DSCB' VOL(volser) UNIT(/uuuu) for 4-character units. Or for 3-character units: TSO ZAP 'FORMAT4.DSCB' VOL(volser) UNIT(uuu) (The UNIT parameter will only work if you have the latest version of Fullscreen ZAP, now available on the Updates page of www.cbttape.org) The first record you'll see is Record 1 of Track 0. You then enter the R command (to get to the next record) twice, to get to see Record 3. Now you have a choice, since ZAP can change the record as well: Either you have first used the ONLCLIP program to change the volume id, so that you'll have an audit trail, and you're just using ZAP to check on the results, or you can use ZAP to do the whole job, using its "S" subcommand to change the volser in Record 3, after having positioned ZAP to point to the correct location. If you're just checking on the results, just do a "Print Screen" and get out, but if you're doing the whole job, ZAP can offer something of an audit trail, as well, if you save its log. The choice is yours. So we'll say good-bye for now, and we hope to see you in this space, the next time. ILLUSTRATIONS Figure 1. JCL to run the ONLCLIP batch program. The new volume id is fed into the program in the PARM field, and the input data is uppercased. The current UCB volume id has to be entered in the VOL=SER= parameter of the DISKUPD DD name. //IBMUSERS JOB ,'SAM GOLOB',CLASS=B, // MSGCLASS=X,NOTIFY=&SYSUID //* //* Purpose of this program is to change the VOLSER of a volume, //* while it is online. The PARM field contains the new volume id. //* //* If two disks are online with identical UCB volsers and identical //* volume labels, then specify the specific unit address in the JCL, //* as per the DISKUPD DD name below. //* //TRK0SAV1 EXEC PGM=ONLCLIP,PARM='VTMVSH' <= New Volume ID //STEPLIB DD DISP=SHR,DSN=SYS1.W$$.LINKLIB //SYSPRINT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //DISKUPD DD UNIT=1005,SPACE=(TRK,1),VOL=SER=VTMVSG <= Device Address // Figure 2. Output of the ONLCLIP batch program. SYSPRINT DD name messages produced by ONLCLIP.... ONLCLIP - Version 1.5 - 02/18/23 ------- - ------- --- - -------- "ONLINE CLIP" Time and Date of Execution: Date: 02/20/2020 Time: 11:06:19 UCB Unit: 1005 UCB Volser: VTMVSG Old VOLSER was: VTMVSG New VOLSER is : VTMVSH To make the change permanent, you have to VARY the pack OFFLINE and then VARY the pack ONLINE again. WTO messages produced by ONLCLIP.... ONLC000 Original (UCB) volume serial is: VTMVSG. ONLC001 Volume Serial for Unit: 1005 changed from VTMVSG to VTMVSH. Figure 3. Sample view of Track 0, Record 3, after the change. Note that the DSN: VOLUME is still the original volume serial, as reflected in the UCB. Z A P ENTER VALID COMMAND ABOVE OR ? FOR HELP VERSION=3.3Z 19FEB20 00000 >E5D6 D3F1 E5D6 D3F1 E5E3 D4E5 E2C8 4000 |VOL1VOL1VTMVSH .| 00010 0000 0101 0000 0004 0000 001E 0000 001E |................| 00020 0000 1518 0000 0006 0000 0040 0000 0040 |........... ... | 00030 9704 0110 4704 0000 0000 0000 0000 0001 |p...............| 00040 0000 000B 0000 000B 0000 0000 0000 0000 |................| 00050 0000 0000 |.... | OFF: 0000 ( 0) ADDR: 00000 ( 0) DSN: VOLUME VTMVSG LEN: 0054 ( 84) BASE: 00000 ( 0) CCHHR: 0000000003 TTR: 000003 Figure 4. Sample JCL to look at Track 0 on several disk packs, each having the same UCB volser (TEST02), but having different unit addresses (A42 and A43). // JOBCARD //DUMP01 EXEC PGM=ADRDSSU,REGION=4096K //SYSPRINT DD SYSOUT=* //OUTPUT DD SYSOUT=* //SYSIN DD * PRINT TRACKS(0,0,0,0) - INDYNAM(TEST02,A42) - ADMIN - OUTDDNAME(OUTPUT) PRINT TRACKS(0,0,0,0) - INDYNAM(TEST02,A43) - ADMIN - OUTDDNAME(OUTPUT) /* //