MVS TOOLS AND TRICKS OF THE TRADE OCTOBER 2007 Sam Golob MVS Systems Programmer P.O. Box 906 Tallman, New York 10982 Sam Golob is a Senior Systems Programmer. He also participates in library tours and book signings with his wife, author Courtney Taylor. Sam can be contacted at sbgolob@cbttape.org. Information about the CBT MVS Tapes can be found on the web, at http://www.cbttape.org. EXPLORING "LIVE" STORAGE WITH THE "LOOK" TSO COMMAND It is extremely useful, helpful, and often quite necessary, to be able to examine "live" system storage in the MVS (z/OS or any other flavor) machine that is currently running. There are many available tools to do that, and most of them are vendor products which not everyone has. But today, I want to concentrate on using one free tool to examine system storage. And this is a tool that anyone, in any MVS shop, can easily acquire. It is called LOOK, and it can be found on File 264 of the CBT MVS Utilities collection (www.cbttape.org). Programmers who write utilities for the MVS system must often also examine live system storage, because that comprises the data which their programs are usually trying to look at. I assure you that you cannot effectively write utilites that read control block contents, unless you can see the data which resides in the control blocks. It is extremely inaccurate to program blindly, without looking at the data that you are trying to either display or manipulate. Then, in our modern MVS systems, there's also the question of going cross memory. In other words, virtual storage, at the same numerical address, but in different address spaces, contains different contents. So you'd often like to know what is going on, when one address space communicates with another. A memory display program which communicates between two or more address spaces in live storage on the machine, is a useful thing to have in your tool box. LOOK can do that, albeit with some limitations, if it is running APF-authorized. THE FREE "LOOK" PROGRAM LOOK is a TSO command, and as I said before, it is free for the downloading. Source code is on File 264 of the magnificent CBT Tape collection of free MVS utilities, and a load module is on File 035. (See www.cbttape.org). LOOK is an old program from the pre-XA days, and it was extended to work in 31-bit mode. But even though LOOK is a bit outmoded in its coding style, it has features that make it so convenient to use, that if your (storage browsing) task is not beyond LOOK's capabilities, I think it is the preferred tool for the job. And that's why I'm writing my column about it this month. LOOK is a full screen TSO command. For browsing storage in your own address space, LOOK doesn't even have to run APF authorized. But if LOOK is APF authorized, it can go cross-memory too. LOOK was written in the old days, before convenient ESA cross-memory mechanisms were invented. So LOOK goes cross-memory by scheduling an SRB, which is one of it's weaknesses. By the time the SRB results get back to you, the storage in the other address space that you're examining, may be out of date. But in most cases, as long as you don't need absolutely accurate cross-memory storage information, LOOK has so many nice features that you'll always want to use LOOK, unless you absolutely can't, and you have to use another tool. What is so great about LOOK? The first thing, is that LOOK can FORMAT a control block's storage according to its descriptive macro. Many other storage browsing programs can't do that. In addition, if you do format the control block according to its macro, then you can navigate the storage, using the name of the control block's field, and thus, you don't even have to know the numerical displacement of the field within the control block. You just have to know its NAME. I'll show you how all of this works. Before I go on, I'd like to tell you about one more advantage (over other spool browsing programs) that LOOK has. That is, LOOK can run in non-APF-authorized mode. True, when LOOK is run non-authorized, it can only browse the storage in your own TSO address space. But I have to point out something. YOUR OWN TSO address space also includes COMMON STORAGE! This means you can look at EVERYBODY's CSA, PLPA, FLPA, MLPA, and SQA, from your own TSO address space, and you can do so while YOU'RE NOT AUTHORIZED... Not too many other spool browsing programs can lay claim to that. This means, that when you don't have full power, you can still find out an awful lot about your system's storage contents. STEPPING THROUGH CONTROL BLOCKS WITH "LOOK" Please take a look at Figure 1, which is the HELP screen for the LOOK TSO command. You invoke LOOK from TSO by simply entering LOOK at the READY prompt, or TSO LOOK from the ISPF command line. Then, pressing PF1 takes you to this HELP screen. We all know that when an Assembler program runs a chain of control block fields, mostly LOAD (L) and LOAD ADDRESS (LA) instructions are used. For example, suppose (to pick a control block) we want to access the IKJEESCB control block, which tells us all about where the Broadcast Dataset (usually SYS1.BRODCAST) is, which the system is using now. After z/OS 1.3, you can switch Broadcast Datasets, and they don't have to be named SYS1.BRODCAST and cataloged in the master catalog any more. But they can be named any valid dataset name, and they don't even have to be cataloged. So to find the Broadcast Dataset after z/OS 1.3, the system runs a chain of control blocks to access the IKJEESCB control block. IKJEESCB has all the information about which current Broadcast Dataset the SEND and LISTBC TSO commands are now accessing. Let's get going. When we type LOOK as a TSO command, we get the screen in Figure 2, which is Virtual address 00000000, or the PSA control block. But you'll notice that the fields are formatted. Why is that, and how does it work? Formatting uses the "O" subcommand in LOOK. Type "ONULL" and you'll turn off formatting. Type "OPSA" and you'll format the current storage, beginning at the current location, as though it were the beginning of the PSA control block. When you know which system control blocks that LOOK can format, you can enter these "Oxxx" commands yourself. To turn formatting off, anytime, just type ONULL. Some control blocks get formatted by LOOK automatically, if they start with an eyecatcher string, which can be programmed into the CBMACS macro that does the formatting. LOOK can automatically format a control block if the current storage (being looked at) contains some indicator which we know about. And you can code the formatting for any macro you want, using any macro, into the CBMACS source member yourself. Now how do we navigate control blocks? LOOK starts at storage location 00000000. But to get to the CVT, we have to look at the virtual storage in address 00000010 (hex). To see that, we have to go to virtual location X'10', look at the address in the fullword there, and load it. In other words, we point to the address that is located at address X'10'. In Assembler, this is done with a LOAD instruction, but the command in LOOK which is similar to the LOAD instruction is called "J". Therefore, if we want to display the storage pointed to at address X'10', we say (in LOOK) the command "J10". This will get us to the CVT, and all the storage there, is formatted according to the layout in the CVT macro in SYS1.MACLIB. In LOOK, if a control block is formatted already, and we want to point to the address that is in one of the fields, we use the "L" instruction which really means "link" to the address in the named field. For example, if we are pointing to the CVT (see Figure 3), and we want to point to the address at the named field TVT, we say the command "LTVT". Lo and behold, we are pointing to the TSVT control block (TSO Vector Table). Had we known a relative address (from the CVT start point) where the TSVT is pointed to, we could have entered it using a "J" command. In actuality, we thus could have said, "J+9C" and gotten to the same place. But when formatting of a control block is in place, and the "L" command is available, it saves you a lot of work to use the "L" notation, because you don't have to know all the absolute address displacements. A field name is sufficient to get to see the required storage. In LOOK, a Load Address (LA) instruction is simply entered by using a plus sign "+" and entering the hex quantity you want to jump to. For example, if you are pointing to the CVT start and you want to point to an address X'8' bytes higher, you simply say +8. To go to a lower address location, you use a minus sign "-" instead of the plus sign. So the LOAD and LOAD ADDRESS operations can easily be duplicated in the LOOK command, when you're trying to follow control block chains in virtual storage. If you've made a mistake, or just want to go back to the previous LOOK screen, just press PF9. That takes you back to the screen before, if there was one. If you see an location that contains an address you think you might be interested in, simply use a J command and point it at that address. For instance, when pointed at the TSVT (which is formatted by my copy of LOOK - see Figure 4) and you see the TPVT, you can point to it with LTPVT, but then, that is an OCO control block, and I might want to explore its contents some more. See Figure 5. There is an interesting address at +20 from the beginning of that control block. I want to see what is there, so I enter the command, J+20. Lo and behold, there appears the IKJEESCB control block. If I am interested in SYS1.BRODCAST related stuff, I have found what I want to see. If not, I press PF9 to go back one screen, and I try another address. In this way, I was able to explore the contents of most of the TSO/E-related control blocks in the system. See my February and March 2006 columns about TSO/E control blocks. All of the information found there, was obtained using the LOOK command, and exploring. Amazing, isn't it? WHAT YOU CAN DO, ONCE YOU'VE SEEN THE STORAGE Once you've seen the storage, you can simply remember what's there, for your own knowledge, or you can write programs to display or use the storage values in some way. To illustrate how I could use the knowledge that was available in the IKJEESCB control block, and also to show some related information that could be found in the TPVT, I wrote a display program which I called "EESCB". EESCB source code can be found on the CBT Tape File 731, along with some other related useful programs that came out of my TSO/E control block discoveries. Please look at Figure 7, to see some sample output from EESCB. I never do any programming in system control blocks, without using the LOOK program to see what was there in the first place. LOOK is my eyes and ears into system storage. Of course, we can go further and use other tools too, but for me, LOOK is always the place to start. I hope you have gained something from this article, whether you are an experienced programmer, a novice, or somewhere in between. I wish all the best of everything for all of you, and I hope to see you here again next month. * * * * * * * * * * * * * * * * * * * * * * * Figure 1. HELP screen to summarize the LOOK subcommands. LOOK COMMAND - DISPLAY VIRTUAL MEMORY DISPLAY ASID= 002A ENTER CMD - LAST CMD - LOOK is a real time core display and formatting program. It also has the capability of displaying memory in any address space (if authorized). The valid commands are: Iexp 24 bit indirect | Jexp 31 bit indirect > Forward | < Backward =sym Define current address as "sym" | ,sym Redisplay core at "sym" M0/M1 Flip between top and center | Lname Indirect thru control block field Ocb Format as "cb" control block | R Refresh displayed storage "cb" may be NULL to show as hex | where 'exp' is of the form: <+/->hhhh<+/-hhhh<+/-hhhh...>> and 'hhhh' is a 1 to 8 digit hex number. 1= HELP 2= 3= END 4= 5= REPEAT 6= 7= BACKWARD 8= FORWARD 9= HIST BWD 10= HIST FWD 11= 12= * * * * * * * * * * * * * * * * * * * * * * * Figure 2. LOOK pointing at location 00000000, which is formatted as the PSA control block. LOOK COMMAND - DISPLAY VIRTUAL MEMORY DISPLAY ASID= 001A ENTER CMD - LAST CMD - OPSA 00000000 PSA RNPSW 000A0000 ROPSW 0000000000000000 CVT 00FDDF00 EOPSW 7FFFF0007FFFF000 SOPSW 7FFFF0007FFFF000 POPSW 7FFFF0007FFFF000 MOPSW 0000000000000000 IOPSW 7FFFF0007FFFF000 CVT2 00FDDF00 ENPSW 000A0000 SNPSW 000A0000 PNPSW 000A0000 MNPSW 000A0000 INPSW 000A0000 EPARM 00000000 SPAD 0000 EICOD 1005 SVILC 02 SVCN 006B PIILC 02 EECOD 00 PICOD 11 TEAB3 01 MCNUM 00 PERCD 00 ATMID 00 PER 00000000 MTRCD 000000 TEARN 00 PERRN 00 ARCH 01 MPL 01367908 SID 0001003D IOFP 00F53590 FACL0 F1 FACL1 60 FACL2 FE FACL3 CB ESAR 00000000 CTSA 0000000000000000 CCSA 0000000000000000 MCIC 0000000000000000 FSA 00000000 FLA 00000000000000000000000000000000 ARSAV 00000000 FPSAV 00000000000000000000000000000000070420008000000000000000011FC52C GRSAV 00000000 CRSAV 04040000 PSA PSA CPUPA 0000 CPULA 0040 PCCAV 00F59008 PCCAR 1E6DA008 LCCAV 00F96000 LCCAR 1E717000 TNEW 008C9468 TOLD 008C9468 ANEW 00FDC400 AOLD 00FC9280 SUP1 00 SUP2 00 SUP3 00 SUP4 00 PTYPE 00 1= HELP 2= 3= END 4= 5= REPEAT 6= 7= BACKWARD 8= FORWARD 9= HIST BWD 10= HIST FWD 11= 12= * * * * * * * * * * * * * * * * * * * * * * * Figure 3. LOOK pointing at the CVT control block that was pointed to by virtual storage location X'10'. The CVT control block has been automatically formatted by the CBMACS section of the LOOK program. LOOK COMMAND - DISPLAY VIRTUAL MEMORY DISPLAY ASID= 001A ENTER CMD - LAST CMD - J10 00FDDF00 CVT TCBP 00000218 0EF00 00FED61C LINK 00FDDE7C AUSCB 00FDE4E8 BUF 00000000 XAPG 00FF5FF8 0VL00 00FF1896 PCNVT 00FE775E PRLTV 00FE7564 LLCB 019476D8 LLTRM 812FF600 XTLER 00FEBAD8 SYSAD 00F53500 BTERM 00FE9FB8 DATE 0107276F MSLT 00FDE510 ZDTAB 00F49000 XITP 00FF7DC8 0EF01 00FED63C VSS 0000 VPSM 0000 EXIT 0A03 BRET 07FE SVDCB 00FDDE84 TPC 00FD9488 FLGC0 00 FLGC1 00 ICPID 0000 CVT CVT CUCB 00FDEA78 QTE00 00FED65A QTD00 00FED662 STB 00F552F0 DCB 9B DCBA FE0D78 SV76M 0062001D IXAVL 00FE41C0 NUCB 00000000 FBOSV 813C0920 0DS 00FED554 ECVT 0195C9F8 DAIRX 8328B000 MSER 00FDE510 0PT01 00FED4C4 TVT 00CB0140 040ID 000000A4 MZ00 7F 1EF00 00000000 QOCR 00000000 QMWR 00FDE5F0 SNCTR 0000 OPTA A3 OPTB 20 QCDSR 00FE9328 QLPAQ 00FDDEB8 ENFCT 00FDE628 SMCA 80FCE0F0 ABEND 00FDD310 USER 00000000 MDLDS 00000000 QABST 0A0D LNKSC 0A06 TSCE 00000000 PATCH 00FDD238 RMS 0132C368 SPDME 0230FF44 0SCR1 00FE6BB8 1= HELP 2= 3= END 4= 5= REPEAT 6= 7= BACKWARD 8= FORWARD 9= HIST BWD 10= HIST FWD 11= 12= * * * * * * * * * * * * * * * * * * * * * * * Figure 4. LOOK pointing to the TSO Vector Table, as a result of using an "L" command in the previous display of the formatted CVT control block. LOOK COMMAND - DISPLAY VIRTUAL MEMORY DISPLAY ASID= 001A ENTER CMD - LAST CMD - LTVT 00CB0140 TSVT TSVT TSVT LEV . FLG1 NCT 1178D250 VACC 00CE0A4E ASF 00CCD1E0 LTBL 00D95B30 FLA1 83E1A000 CTIO 80D9A000 CTAB 83E16030 T440 83EA26AE T441 83EBC910 PUTL 83EB3028 PTGT 83EB3F18 GETL 83EB751E STCK 83EAE220 TSL 80CD0990 SCAN 83EC2000 PARS 83E81000 EF02 83E73000 TPVT 119C3198 RCVY 84A839B0 TRAN 83EC4000 BCMT ........ CAF 83E473D8 LVER 3 LREL 08 LMOD 0 CTDB 83274B88 RIF 8326A370 RAF 83E3D000 RTRP 83EBF000 TBLS 00CE0A30 ADTB 83681EB8 TBLR 83EDFD20 ESTK 84075E98 TVAR 840C65E8 INIT 84091910 OLAR 80D7E000 TO00 840C1000 T44X 83EA1CC8 FTS2 83E42000 EXE 8408E4E8 INOU 840908D8 LOA 84090CB0 TER 840BC7B0 SUBC 8408EE28 MSGI 840A91D0 EXCO 8408F1F8 TERM 840A6B90 ETVP 00C9BAD0 TSFI 83E40000 TSFT 82B0B868 PCN1 00001A00 SNTA 1197A490 SVTA 1197AE48 SYML 00000B70 XCFU 00000000 MSTR 00FDC400 BECB 808C9070 APPC 82887A40 URPS 83EC6000 PCN2 00001A01 MSR0 83E75000 MDT@ 831A0718 1= HELP 2= 3= END 4= 5= REPEAT 6= 7= BACKWARD 8= FORWARD 9= HIST BWD 10= HIST FWD 11= 12= * * * * * * * * * * * * * * * * * * * * * * * Figure 5. LOOK pointing at unformatted storage, which is the OCO control block IKJTPVT. In order to see what is here, we have to explore, using J+x commands. For example, J+20, which looks interesting. LOOK COMMAND - DISPLAY VIRTUAL MEMORY DISPLAY ASID= 001A ENTER CMD - LAST CMD - LTPVT 119C3198 >E3D7E5E3 00DC0200 C9D2D1E3 E2D6F0F0 *>TPVT....IKJTSO00* 119C31A8 00000000 11A6C018 0000003C 00000000 *.....w..........* 119C31B8 119BF3A0 11A6D008 119CB058 119BF2A0 *..3..w........2.* 119C31C8 11A2F018 00000000 00000000 119E4018 *.s0........... .* 119C31D8 00000000 00000000 00000000 00000000 *................* 119C31E8 C1C4C3C4 4BE9F1F8 E24BD7C1 D9D4D3C9 *ADCD.Z18S.PARMLI* 119C31F8 C2404040 40404040 40404040 40404040 *B * 119C3208 40404040 40404040 40404040 E2F8D9C5 * S8RE* 119C3218 E2F10000 C1C4C3C4 40404040 5C5CC9D7 *S1..ADCD **IP* 119C3228 D35C5C40 F0F97AF5 F97AF2F8 F2F0F0F7 *L** 09:59:282007* 119C3238 60F1F060 F0F30080 00000192 12470959 *-10-03.....k....* 119C3248 28102007 10038000 00000000 00000000 *................* 119C3258 00000000 00000000 00000000 00000000 *................* 119C3268 00000000 00000000 00000000 00000000 *................* 119C3278 C5D5C6D3 40000000 00000000 81238D82 *ENFL .......a..b* 119C3288 00000001 00000000 117F2380 00000000 *........."......* 1= HELP 2= 3= END 4= 5= REPEAT 6= 7= BACKWARD 8= FORWARD 9= HIST BWD 10= HIST FWD 11= 12= * * * * * * * * * * * * * * * * * * * * * * * Figure 6. A LOOK at the unformatted IKJEESCB control block. The macro describing this storage is in SYS1.MODGEN. LOOK COMMAND - DISPLAY VIRTUAL MEMORY DISPLAY ASID= 001A ENTER CMD - LAST CMD - J+20 119BF3A0 >C9D2D1C5 C5E2C3C2 030000C0 E8800000 *>IKJEESCB....Y...* 119BF3B0 5C404040 40404040 40404040 40404040 ** * 119BF3C0 40404040 40404040 40404040 40404040 * * 119BF3D0 40404040 40404040 40404040 40404040 * * 119BF3E0 40404040 0107276F 13592792 00010002 * ...?...k....* 119BF3F0 00140000 00000000 00000000 00000000 *................* 119BF400 30000000 0005000D E2E8E2F1 4BC2D9D6 *........SYS1.BRO* 119BF410 C4C3C1E2 E3404040 40404040 40404040 *DCAST * 119BF420 40404040 40404040 40404040 40404040 * * 119BF430 40404040 E2F8E2E8 E2F10000 E2E8E2C1 * S8SYS1..SYSA* 119BF440 D3D3C4C1 00000000 00000000 0107276F *LLDA...........?* 119BF450 13592821 00000000 00000000 00000000 *................* 119BF460 C9D2D1C5 C6E3C5F2 40D7C1D9 D4D3C9C2 *IKJEFTE2 PARMLIB* 119BF470 C1C44040 40404040 C1C4C4E2 C4404040 *AD ADDSD * 119BF480 C1C74040 40404040 C1C4C4C7 D9D6E4D7 *AG ADDGROUP* 119BF490 C1E44040 40404040 C1C4C4E4 E2C5D940 *AU ADDUSER * 1= HELP 2= 3= END 4= 5= REPEAT 6= 7= BACKWARD 8= FORWARD 9= HIST BWD 10= HIST FWD 11= 12= * * * * * * * * * * * * * * * * * * * * * * * Figure 7. Output of the EESCB command, which is a program that displays the contents of the IKJEESCB control block in detail. Current PARMLIB BRODCAST information - IKJEESCB ------- ------- -------- ----------- -------- The EESCB TSO command displays information concerning the TSO SEND and LISTBC command options. Information is obtained from the IKJEESCB and TPVT TSO control blocks, which are chained off the TSO Vector Table IKJTSVT. BROADCAST dataset switching is only available from IKJEESCB version 03 or later. --------------------------------------------- Parmlib member IKJTSOxx can be invoked: A - At IPL Time B - Under TSO using PARMLIB UPDATE(xx) C - Using Operator command SET IKJTSO=xx --------------------------------------------- Source of EESCB messages: --------------------------------------------- IKJEESCB - General SEND and LISTBC defaults from the IKJEESCB control block. PARMLIB - TPVT control block BRODCAST - BRODCAST section of IKJEESCB which is only present from IKJEESCB version 03 or later. --------------------------------------------- IKJEESCB Address : 119BF3A0 IKJEESCB Version : 03 IKJEESCB Flags : E8800000 IKJEESCB Opersend: On IKJEESCB Usersend: On IKJEESCB Save : On IKJEESCB Chkbrod : Off IKJEESCB Usebrod : On IKJEESCB Msgprot : Off IKJEESCB Sysplxshr Off IKJEESCB Spxshrxcf Off IKJEESCB Oprsewait On IKJEESCB Spxshrini Off IKJEESCB Lognmspec Off PARMLIB Dataset : ADCD.Z18S.PARMLIB PARMLIB Volser : S8RES1 PARMLIB Member : IKJTSO00 PARMLIB Activator **IPL** PARMLIB Swt Date: 2007-10-03 PARMLIB Swt Time: 09:59:28 PARMLIB System : ADCD PARMLIB CPUID : 0192 PARMLIB CPU Model 1247 This system does not write to TSO Userlogs. BRODCAST Dataset : SYS1.BRODCAST BRODCAST Volser : S8SYS1 BRODCAST Unit Name SYSALLDA BRODCAST Flags : 30 BRODCAST Timeout : 005 Seconds BRODCAST Operator: Prompt The BRODCAST dataset name is the default. BRODCAST Dataset volser not specified in IKJTSO00 BRODCAST Dataset name was set by System IPL BRODCAST Dataset switch required? No BRODCAST Dataset Name is an ALIAS? No