SAVING AND RELOADING IPL TEXT - A NEW TECHNIQUE (c) Copyright 2020 by Sam Golob. All rights reserved. IPL text is a somewhat mysterious item to most of us. When setting up a new system, you load it onto (Track 0 of) the system residence pack using the ICKDSF program from IBM, and then you forget about it. The IPL text to boot the current level of the system is located in two members of SYS1.SAMPLIB, and you run the job to load it. Please see Figure 1 for a sample job which will be similar to the actual job that is run. If you loaded the IPL text for the wrong z/OS release, you will get a wait state 075, reason code 6 when you try to IPL. Everybody knows that the IPL text is what boots up the operating system. Very few of us know how it is coded. And not many of us know how to jockey it from pack to pack, or save it and restore it. This third thing is what we'll teach you about today. Today we're going to talk a lot about this subject of IPL text. And we have to start somewhere. I guess that the first thing we should mention is how to find out which disk packs on your system already have IPL text loaded on them. There has to be at least one disk pack on the system which is loaded with IPL text, or your system would not be able to boot. So such a search of all your packs will definitely have to yield at least one positive result. You'll have to find some IPL text somewhere on the installation's volumes. How is it done? Lionel Dyck made this task easy, with his IPLTCHK exec that can be found on CBT Tape File 312. IPLTCHK depends on the TSO command DUDASD, which can be found on CBT File 612. The DUDASD command displays a list of all the disk volumes on your system, and then the IPLTCHK exec reads the list and generates multiple ADRDSSU job steps to print out Track 0 from all of them. When you look at the resulting report, it then becomes obvious, not only which packs have IPL text, but you can also see exactly what the IPL text is. It's quick and fantastic. Try it. See Figure 2 for an illustration of the generated JCL from the IPLTCHK exec. You can copy this JCL to print out Track 0 from any ONE disk pack as well. And by the way, you can filter the list of disk volumes which IPLTCHK will list. See the comments in the IPLTCHK exec. This is based on the fact that DUDASD has a filter to limit the number of volumes that it displays. At this point, if you've performed the exercise of printing all the track 0 contents from your system, and you're looking at the report, you might want to try saving the IPL text from one or more of the packs which have IPL text. Not everybody knows how to do this. Actually, this is something that very few people know how to do (until now). SAVING YOUR IPL TEXTS TO A PDS Once you know which disk packs contain IPL text, you might want to do one of our favorite types of system programmer tasks. You might want to back up all the IPL texts on your system for safekeeping. Most people don't know how to do that. And not long ago, we didn't know how to do that either. But now I'll show you how, using a great set of tools, originally written by our friend somitcw and which can be found on CBT File 846. These tools allow you to back up IPL text and restore it to the same volume, or to a different volume. The names of the 3 main programs on CBT Tape File 846 are: TRK0SAVE to back up the IPL text from a pack, TRK0UPD to reload the saved IPL text in TRK0SAVE format, and TR02ABS to convert the saved IPL text from TRK0SAVE format, to IBM's ICKDSF ABSFORMAT format. There is also a program called TRK0INIT on File 846, which can REMOVE IPL text from a volume, but it is not recommended to use it. The first reason not to use TRK0INIT to remove IPL text, is because of the danger. You don't want to remove IPL text from a pack that needs it, especially from the system res pack. That's disastrous because you won't be able to IPL. The second reason happens when you only want to put different IPL text on a volume which already has IPL text, using the TRK0UPD program. When using TRK0UPD to put new IPL text on a volume, it will overlay any old IPL text that was there before, and wipe it out. Therefore it is not necessary to wipe off the old IPL text that was on the pack, before putting new IPL text on the same pack. The only reason why TRK0INIT was created, was for completeness. What if you put IPL text on a pack by mistake, and you want to clean it off. We need to have a way to do that. This is why we wrote TRK0INIT. As we inferred, the format of these TRK0SAVE backups is different from the format that ICKDSF ABSFORMAT needs to reload them, but CBT File 846 now contains a program called TR02ABS which converts our TRK0SAVE format backup into the ICKDSF ABSFORMAT format. (See the comments in the TR02ABS code, which explain the difference in the formats.) So once you've converted your backups, they can always be reloaded by ICKDSF. If you have a pds of IPL text backups in TRK0SAVE format, I'd recommend that you also keep a corresponding pds of IPL text backups in ABSFORMAT as well. Besides the redundancy, someone later might not have a copy of TRK0UPD which is needed to reload the backups in the TRK0SAVE format. Safety first. The IBM program ICKDSF is in every z/OS system. What kind of pds can we save our IPL texts to? What DCB properties should it have? To answer this, we'd say that IPL text is similar to a load module, and it can contain any length records, only being limited by the length of Track 0 on that disk device. So it is clear that the DCB of our backup pds will have to be RECFM=U, and LRECL=32760. By the way, you can also save your IPL text to a sequential dataset with these attributes, but in my opinion, a pds is better, because with a pds, you can store backups of many different IPL texts in one convenient place. And since IPL text cannot be any longer than one track in size, each IPL text does not take up much room. Therefore a pds is a really convenient way to store your backups of IPL texts. So how do we do it? Look at Figure 3 to see sample backup JCL of IPL text. Look at Figure 4 to see a sample reload of the same IPL text. Using the TRK0SAVE program to back up the IPL text, the DISKIN DD name points to the pack whose Track 0 you want to back up. And the OUTPUT DD name points to the RECFM=U, LRECL=0, BLKSIZE=32760 output dataset, whether it be sequential, or a member of a pds. To restore the backed up IPL text you run the TRK0UPD program, and use its DD names to do the opposite. The DISKIN DD name is the same as for TRK0SAVE, except that in TRK0UPD it is the input file. The output disk is pointed to by the DISKUPD DD name. Figure 4 illustrates this well enough. These processes run very quickly, because they don't have to process much data. CHECKING UP ON YOUR WORK Since the TRK0SAVE and TRK0UPD programs (as well as the other programs) were not meant to be used often, and were meant to be used by relatively experienced personnel, they were not written to produce any output messages. (This may change in the future.) So for now, we need a way to check if such crucial work, which has to be 100 percent accurate, was done correctly. The tool of choice here, is called Fullscreen ZAP. If you don't want to run Fullscreen ZAP, then you can run the ADRDSSU job shown in Figure 2, against the pack you're working on. This will print out the contents of Track 0 on your pack, and you can keep track of everything you have done, to make sure it is accurate. To look at the backup dataset, whether it be a pds member or a sequential dataset, you can ISPF Browse it, or use the wonderful REVIEW program (source on CBT File 134, load modules on CBT File 135) to see what is there. But if you want to update anything on the backup file, or even if you just want to see it more clearly, you will probably be best off using the TSO Fullscreen ZAP command. Fullscreen ZAP is also practical for just viewing the backup dataset. In addition, Fullscreen ZAP can directly view Track 0 records in Hex, and you can get a graphic picture of everything there, up to 208 bytes at a time, on the screen. I'll tell you how to start using Fullscreen ZAP. ZAP is a TSO command, which is invoked (under ISPF) by saying: TSO ZAP dataset.name If you want to see track zero of a pack whose volume serial is MYPACK, then you say: TSO ZAP 'FORMAT4.DSCB' VOL(MYPACK) FULLVOL FULLVOL support requires that ZAP be invoked APF-authorized. When you get into ZAP in FULLVOL mode, the program thinks that the extents it is looking for, encompass the entire volume, so the "dataset" you're opening consists of the entire volume. That's why the display starts at Track 0, Record 1 of the track. And therefore you can get a good look at Track 0. To look at a sequential dataset using ZAP, and if it is cataloged, then you just say: ZAP dataset.name . If it is not cataloged, you say: ZAP dataset.name VOL(volser) . To look at a pds with ZAP, you do the same thing, but once you're in, you're looking at the directory. If you want to look at a member of the pds, you say: Mmember. Don't put any spaces between the "M" (which is the command) and the member name. If you're looking at a load library, which we aren't doing now, you say Mmember and then you say Eentrypt . When you're within ZAP, help is always at hand, by typing in a question mark. Source code for ZAP is on CBT File 134 (member ZAP) and the load module is on CBT File 135. For some of its functions, the ZAP module has to be authorized, so it is advisable to linkedit it with SETCODE AC(1) and put it into the IKJEFTE2 TSO Table (AUTHCMD NAMES in the IKJTSOxx PARMLIB member). Once you've started executing ZAP, and you are in one of its screens, full HELP is accessible by entering the command "?" (without the quotes) at any time. PF3 gets you back to what you were doing. Pressing ENTER while you're in help mode, gets you to the next help screen, and there are 13 of them. A little bit of practice with the help for ZAP, goes a long way. Everything is really there, and you can learn to use ZAP well, all on your own. A FEW EXAMPLES OF BACKING UP IPL TEXT AND RESTORING IT Let's say that we're building a clone of our z/OS 2.4 system, and we already have a running system residence pack. Instead of re-running the IBM job to load the IPL text from SYS1.SAMPLIB (see Figure 1), we are going to run two jobs (see Figures 3 and 4). The first job (Fig. 3) backs up the existing IPL text from pack ZOSRES into a backup dataset which is a member of the pds: IBMUSER.IPLTEXT.PDS. The second job (Fig. 4) reloads the backup of the z/OS 2.4 IPL text, on to the new res pack called ZNWRES. This performs the same work as the running the IBM job (from Figure 1) twice, but it also provides a backup of the IPL text which we can save for future use. This technique is much more useful when we have to deal with IPL texts that don't come from IBM. Suppose we have a disk pack which has IPL text from a vendor who went out of business, and we need to run the product, but we don't have the original install materials. Then this technique will save the day. Just back up the (obscure) IPL text to a dataset, and restore it to any pack that you want, which needs it. No fuss, no muss. It takes less than a minute. Next, I'll illustrate another technique. Suppose we have a saved copy of the IPL text for ZZSA (CBT Files 437 and 538), which is a system recovery tool. ZZSA is a multi-utility package which is installed as IPL text on (for example) a disk volume. When you IPL ZZSA, you have access to a primitive editor, disk browser, and other tools. You can use these tools when the system won't come up because of an IPL problem, and you can fix your system res pack or any other data that needs fixing, so you can IPL normally afterward. Let's say that our only copy of ZZSA IPL text which we have, is a backup in TRK0SAVE format. We can convert this backup into ICKDSF ABSFORMAT format, using a job like in Figure 5, and then you can run the IBM job (using ICKDSF) such as in Figure 6, to load this same IPL text on to any pack you want. I'll conclude this article with an observation. When a disk pack does not contain IPL text, the IPL2 record (Record 2 on Track 0) has a standard format for a pack with no IPL record. I've displayed this record (Figure 8), using the Fullscreen ZAP TSO command. As we said before, to get into ZAP and to look at Track 0, we have to type: TSO ZAP 'FORMAT4.DSCB' VOL(ourpak) FULLVOL. To get to Record 2, we just type R to get to the next record. Notice, in Figure 8, that the TTR of the displayed record is 000002. (The TTR of the first record in Track 1 would be 000101.) Now look at Figure 7. By contrast, you can see that there are other fields which are filled in, when IPL text exists on Record 4 of Track 0, or (in other words) more records exist on Track 0. The disk pack illustrated by Figure 7 has IBM IPL text on it for z/OS 2.3. This IPL text adds only one additional record (Record 4) to Track 0. By contrast again, look at Figure 9. Figure 9 shows the IPL2 record (Track 0 Record 2) for a pack with ZZSA IPL text on it. ZZSA IPL text contains 11 records, from 4 thru 14 (or Record E in hex). You can see that this Record 2 is very different from the other two. We have to break now, till next time. I hope that this topic is instructive and enlightening, and it helps you in your work. This idea of backing up and restoring IPL text is not well-known among z/OS systems practitioners at this time. But it is not hard to grasp, once you look at it carefully, and it can potentially be a life-saver in many situations. All the best of everything to all of you. ILLUSTRATIONS Figure 1. The normal job that is run when you want to load z/OS IPL text onto Track 0 of the system residence pack. The system level of SYS1.SAMPLIB must match the system level of z/OS that you want to run. If the levels do not match, you might get a wait state 075 with reason code 6, when you try to IPL. //IBMUSERP JOB ,'LOAD IPL TEXT',CLASS=B, // MSGCLASS=X,NOTIFY=&SYSUID //* //***************************************************************** //* PUT IPL TEXT ON IPL VOLUME USING ICKDSF //***************************************************************** //IPLTEXTL EXEC PGM=ICKDSF,PARM=NOREPLYU,REGION=4M,COND=(0,NE) //SYSPRINT DD SYSOUT=* //IPLTEXT DD DISP=SHR,DSN=SYS1.SAMPLIB(IPLRECS) // DD DISP=SHR,DSN=SYS1.SAMPLIB(IEAIPL00) //SYSIN DD * REFORMAT DDNAME(IPLTEXT) - IPLDD(IPLTEXT) - NOVERIFY - BOOTSTRAP /* IPLRECS OF IPLTEXT DD WILL SUPPLY IT */ /* Figure 2. Partial output of Lionel Dyck's IPLTCHK REXX exec. The exec runs the DUDASD TSO command to list all active DASD on the system, and then it parses the list, to generate a printout of Track 0 for each DASD volume. It then becomes obvious, not only which volumes CONTAIN IPL text on them, but also, you can see exactly what the IPL text consists of. This is a great report. You can also run the JCL against any single pack to see its IPL text. //DUMP01 EXEC PGM=ADRDSSU,REGION=4096K //SYSPRINT DD SYSOUT=* //OUTPUT DD SYSOUT=* //SYSIN DD * PRINT TRACKS(0,0,0,0) - INDYNAM(ZOSRES) - ADMIN - OUTDDNAME(OUTPUT) PRINT TRACKS(0,0,0,0) - INDYNAM(ZOSRS1) - ADMIN - OUTDDNAME(OUTPUT) PRINT TRACKS(0,0,0,0) - INDYNAM(ZOSRS2) - ADMIN - OUTDDNAME(OUTPUT) PRINT TRACKS(0,0,0,0) - INDYNAM(ZOSRS3) - ADMIN - OUTDDNAME(OUTPUT) PRINT TRACKS(0,0,0,0) - INDYNAM(ZOSRS4) - ADMIN - OUTDDNAME(OUTPUT) PRINT TRACKS(0,0,0,0) - INDYNAM(ZOSRS5) - ADMIN - OUTDDNAME(OUTPUT) PRINT TRACKS(0,0,0,0) - INDYNAM(ZOSRS6) - ADMIN - OUTDDNAME(OUTPUT) * * * * * * * * (etc. etc. etc.) Figure 3. Job to back up the IPL text of a disk pack, to a pds member. //IBMUSERS JOB ,'SAVE IPL TEXT',CLASS=B, // MSGCLASS=X,NOTIFY=&SYSUID //* //* If you change output to go to SYS1. or SYS2. data sets, then //* reply the master catalog password on the console. Twice. //* //TRK0SAV1 EXEC PGM=TRK0SAVE //STEPLIB DD DISP=SHR,DSN=SYS1.W$$.LINKLIB (APF-authorized) //SYSUDUMP DD SYSOUT=* //DISKIN DD UNIT=3390,SPACE=(TRK,1),VOL=SER=ZOSRES //OUTPUT DD DISP=SHR,DSN=IBMUSER.IPLTEXT.PDS(Z24IPLT) //* Figure 4. Job to load the IPL text of a disk pack, from a backup which is a pds member. //IBMUSERI JOB ,'LOAD IPL TEXT',CLASS=B, // MSGCLASS=X,NOTIFY=&SYSUID //* //TRK0UPD EXEC PGM=TRK0UPD //STEPLIB DD DISP=SHR,DSN=SYS1.W$$.LINKLIB (APF-authorized) //SYSUDUMP DD SYSOUT=* //DISKUPD DD UNIT=SYSDA,SPACE=(TRK,1),VOL=SER=ZNWRES //DISKIN DD DISP=SHR,DSN=IBMUSER.IPLTEXT.PDS(Z24IPLT) //* Figure 5. Job to convert an IPL text backup in TRK0SAVE format to IPL text source in ICKDSF ABSFORMAT format. //IBMUSERC JOB ,'CONVERT IPLTEXT BACKUP',CLASS=B, // MSGCLASS=X,NOTIFY=&SYSUID //* //CNVIPLT PROC MEMB=XXXX //CONVERT EXEC PGM=TR02ABS //STEPLIB DD DISP=SHR,DSN=SYS1.W$$.LINKLIB //SYSUT1 DD DISP=SHR,DSN=IBMUSER.IPLTEXT.PDS(&MEMB) //SYSUT2 DD DISP=SHR,DSN=IBMUSER.IPLTEXT.ABS(&MEMB) // PEND //C001 EXEC CNVIPLT,MEMB=Z21IPLT //C002 EXEC CNVIPLT,MEMB=Z23IPLT //* Figure 6. Job to use ICKDSF to load converted IPL text in ICKDSF ABSFORMAT format, to a disk pack. //IBMUSERP JOB (ACCT#),S-GOLOB, // NOTIFY=&SYSUID, // CLASS=B,MSGCLASS=X //***************************************************************** //* PUT IPL TEXT ON IPL VOLUME USING ICKDSF //***************************************************************** //* //STP1 EXEC PGM=ICKDSF,REGION=0M //SYSPRINT DD SYSOUT=* //IVOL DD VOL=SER=ZZSAVL,UNIT=SYSALLDA,DISP=SHR //SAMPLIB DD DISP=SHR,DSN=IBMUSER.IPLTEXT.ABS(ZZSATEXT) //SYSIN DD * REFORMAT DDNAME(IVOL) VERIFY(ZZSAVL) IPLDD(SAMPLIB,ABS) BOOTSTRAP /* // Figure 7. Record 2 (IPL2) of Track 0, for a volume which contains IPL text in Record 4. Shown using the Fullscreen ZAP TSO command. The IPL text is for z/OS 2.3 in this case, which adds just one extra Track 0 record: Record 4. Z A P ENTER VALID COMMAND ABOVE OR ? FOR HELP VERSION=3.3Z 02MAY13 R 00000 >C9D7 D3F2 0700 4AB8 4000 0006 3100 4ABE |IPL2..½. .....½.| 00010 4000 0005 0800 4AA0 0000 0000 0600 0000 | .....½.........| 00020 2000 2F55 0000 0000 0000 0000 0000 0400 |................| 00030 0000 0000 0000 0000 0000 0000 0000 0000 |................| 00040 0000 0000 0000 0000 4040 4040 4040 4040 |........ | 00050 4040 4040 4040 4040 4040 4040 4040 4040 | | 00060 4040 4040 4040 4040 4040 4040 4040 4040 | | 00070 4040 4040 4040 4040 4040 4040 4040 4040 | | 00080 4040 4040 4040 4040 4040 4040 0000 0000 | ....| 00090 0000 0000 |.... | OFF: 0000 ( 0) ADDR: 00000 ( 0) DSN: VOLUME Z23RES LEN: 0094 ( 148) BASE: 00000 ( 0) CCHHR: 0000000002 TTR: 000002 Figure 8. Record 2 (IPL2) of Track 0, for a volume which does not contain IPL text, and there is no Record 4 on Track 0. Z A P ENTER VALID COMMAND ABOVE OR ? FOR HELP VERSION=3.3Z 02MAY13 R 00000 >C9D7 D3F2 0700 3AB8 4000 0006 3100 3ABE |IPL2.... .......| 00010 4000 0005 0800 3AA0 0000 0000 0600 0000 | ...............| 00020 2000 0000 0000 0000 0000 0000 0000 0400 |................| 00030 0000 0000 0000 0000 0000 0000 0000 0000 |................| 00040 0000 0000 0000 0000 0000 0000 0000 0000 |................| 00050 0000 0000 0000 0000 0000 0000 0000 0000 |................| 00060 0000 0000 0000 0000 0000 0000 0000 0000 |................| 00070 0000 0000 0000 0000 0000 0000 0000 0000 |................| 00080 0000 0000 0000 0000 0000 0000 0000 0000 |................| 00090 0000 0000 |.... | OFF: 0000 ( 0) ADDR: 00000 ( 0) DSN: VOLUME Z23RS1 LEN: 0094 ( 148) BASE: 00000 ( 0) CCHHR: 0000000002 TTR: 000002 Figure 9. Record 2 (IPL2) of Track 0, for a volume which contains IPL text for the ZZSA recovery tool from Jan Jaeger. ZZSA IPL text adds many records to Track 0, going from Record 4 to Record E (decimal 14). This is somehow reflected in the IPL2 record (Record 2) which we see here. Z A P ENTER VALID COMMAND ABOVE OR ? FOR HELP VERSION=3.3Z 02MAY13 R 00000 >C9D7 D3F2 0600 6238 4000 0A44 0600 6E30 |IPL2.... .....>.| 00010 4000 0832 0600 7818 0000 0607 0000 0000 | ...............| 00020 0000 0000 0000 0000 0000 0000 0000 0400 |................| 00030 0000 0000 0700 7E40 4000 0006 3100 7E46 |......= .....=.| 00040 4000 0005 0800 7E58 0000 0000 0600 0000 | .....=.........| 00050 4000 0008 0600 0058 4000 0028 0600 0200 | ....... .......| 00060 4000 0028 0600 02E8 4000 1B48 0600 1EE8 | ......Y ......Y| 00070 4000 0100 0600 2768 4000 0D98 0600 35A0 | ....... ..q....| 00080 4000 1725 0600 55C6 4000 0ACC 0800 7E20 | ......F .....=.| 00090 0000 0000 |.... | OFF: 0000 ( 0) ADDR: 00000 ( 0) DSN: VOLUME ZZSA01 LEN: 0094 ( 148) BASE: 00000 ( 0) CCHHR: 0000000002 TTR: 000002