MVS TOOLS AND TRICKS OF THE TRADE April 1991 Sam Golob MVS Systems Programmer sbgolob@cbttape.org THE "LOOK" TSO COMMAND - AN EYE INTO THE OPERATING SYSTEM: This month, I'd like to feature a program that has far more value than it seems to show initially. The "LOOK" program allows a TSO user to display virtual storage in any address space, and to format any of that space according to the macro DSECT description of any desired control block. This amazing result is achieved in a surprisingly simple manner, and source code is available for all to examine. The "LOOK" TSO command is found on File 264 of the CBT MVS Tape, which can be obtained through NaSPA in Milwaukee, (414) 423-2420, or through SPLA at the University of Miami in Florida, (305) 284-6257. The "LOOK" command provides a fullscreen display of virtual storage, or "live machine core", to put it more excitingly. If it is run authorized, "LOOK" allows cross-memory examination of most virtual storage locations for any active address space. A few special commands make "control block hopping" very easy, with the actual core contents visible. The current version of LOOK is read-only (despite its screen heading), making it relatively safe to use. LOOK can be assembled either for XA and ESA, or for MVS/370 use. LOOK completely supports 31-bit addressing mode. The current version of LOOK is supported by Guy Albertelli of B.F. Goodrich, near Akron Ohio. Our current program is a distant descendant of the "LOOK" program in the old "DCMS" monitor system that used to reside on the public MVS tapes. I'll try to describe the structure and use of "LOOK", and to show some of its enormous value, in several example scenarios. BASIC USE OF THE "LOOK" COMMAND. Please refer to Figure Two, where a sample LOOK screen is displayed. In the input field that states: "ENTER CMD", the easiest thing to do is to enter an absolute address. The initial virtual address displayed by default upon entry to LOOK is address 00000000. This of course, is the Prefixed Save Area or PSA. The most recent version of LOOK will force a formatted version of the PSA, according to the macro IHAPSA. But through the use of the command, "ONULL", any macro formatting is suppressed. The virtual locations starting at 00000000 will then be displayed in Hex, similar to the format of Figure Two. If LOOK was assembled for XA, then any number from 00000000 to 7FFFFFFF will yield a displayable result, provided the virtual storage can actually be paged into real storage. Entering an absolute hex address number as input to LOOK, is equivalent to direct addressing of a virtual storage location. Entering "+" or "-", followed by a numeric hex value, will place the display forward, or backward, by the entered amount. PF7 will move the display backward to a screen-full of previous storage. PF8 will move the screen forward to the next contiguous following storage. The second skill in using LOOK is to try indirect addressing of a virtual storage location. Indirect addressing can be done in 24-bit mode or in 31-bit mode. To do indirect addressing in 24-bit mode, prefix an "I" to an absolute hex address such as "10", or to a relative address, such as "+58". The commands would be "I10", or "I+58". For 31-bit mode, use a "J" instead of the "I". Indirect addressing is like the "LOAD ADDRESS" or "LA" assembler instruction. Entering "I10" or "J10" will display the ADDRESS that's in storage at location "absolute hex 10". "I+58" or "J+58" will display the address contained in storage at "hex 58" off the current location. Indirect addressing allows for easy control block hopping. Of course, the address stored in "absolute location hex 10" is known to point to the CVT area in an MVS system, or the "Communication Vector Table". Both Figures Two and Three point to the beginning of the CVT. The CVT is the main control block from where most other control block pointers ultimately start. Note the great differences between Figure Two and Figure Three, even though they point to the same area of storage. Figure Two shows unformatted storage of the CVT area. Figure Three displays the same storage, but formatted according to the CVT mapping DSECT, described by the macro called "CVT" in the AMODGEN macro library. The formatted screen illustrated by Figure Three teaches us about another indirect addressing capability of LOOK. We can display further storage by going to the contents of a formatted field that contains an address. The letter "L" prefixed to a field name, allows us to do this. For example, in Figure Three, suppose we want to get to the ASCB or Address Space Control Block for the current address space. In the CVT, we must go the the TCB pointer field first. From the formatted screen, we can enter, "LTCBP" which will point us to location 00000218. At +8 from this location is the address of the ASCB, so we can then enter, "J+8", or "I+8", which will point us to the ASCB. This is very simple. If you have access to a working copy of LOOK, try it. PF9 and PF10, "history backward" and "history forward", allow us to review several previous screens and to step forward again to where we were. This facility makes us capable of retracing our steps in using LOOK. If you were following the previous exercise on a screen, press PF9 a couple of times and then PF10 a couple of times. You'll see how the old screens are brought back again. Starting from one of the restored screens, you can proceed forward in a different direction than before, if you wish. CHANGING ADDRESS SPACES. The LOOK load module should be linkedited with SETCODE AC(1). LOOK can be run either authorized or non-authorized. If LOOK is run non-authorized, it can only display virtual storage in your own TSO address space. However, if LOOK is running authorized, it is extremely simple to display the current virtual storage location in any active address space. Simply type the Hex value of the address space id over the current ASID value that comes after "DISPLAY ASID= " on the LOOK screen. (See Figures Two or Three.) For example, if you want to display the current virtual storage location, but in the MASTER address space, simply type the hex number "0001" over the current number, "003E", which is the ASID for our TSO address space. A cross-memory SRB is dispatched immediately to obtain the storage in address space 0001, corresponding to the storage location we're currently displaying. You see that we can attempt to display ANY storage location in any address space, and much of the time, we will be successful. I don't have to over-emphasize the power that is implicit in this facility. USING LOOK TO DIAGNOSE A SYSTEM DUMP. When I was a fledgling systems programmer, I was intimidated by the prospect of solving a system dump. Once I learned how to use LOOK, I realized that these dumps can be far simpler to solve than application program dumps. Let me explain. Problems in an application program are transient in nature. The application program is loaded into the address space's private area of virtual storage, and executes at "computer speed" there. If there is a malfunction or a bug, the storage involved will disappear soon after the abnormal end occurs, and the address space is cleared out of the system. That's why you need a dump, to preserve the contents of private areas (usually) and some system areas, before the whole scene goes away and you won't be able to see it again. Not so, for a problem occurring in a system area of storage. System modules are usually loaded into common areas of storage at IPL time. They occupy the same virtual storage locations, no matter what address space they are viewed from. Even if storage is overlaid, the "problem evidence" might remain in the system long after the system problem occurred. You may therefore use a core-browsing program such as "LOOK" to return to the problem areas much later, as long as there wasn't an intervening IPL (and often, even if there was one). One can even search the problem areas from one's own TSO address space (since they are common to all address spaces) to achieve the diagnosis. One does not usually need to go into the address space that was having the problem. How can we start? It is usually best to try and obtain a good set of registers and a PSW (which contains the instruction to be executed next). One of the best places to obtain a good set of registers and a PSW is in the RTM2 Work Areas of the dump, if they exist. Once we have a set of registers, we can use the MAPXA or MAPSP command, or some similar tool (see this column in the OCTOBER 1990 issue) to check which registers point to addresses in the system areas, such as CSA, PLPA, MLPA, and SQA. One can then use LOOK to browse the vicinity of each of these register contents (using absolute addressing). Often, the registers are pointing to the middle of a system module. You need only browse the eyecatcher of the module (or use SMP inquiry) to determine its PTF level. Then you can search IBM Link or call the IBM support center to see if a problem has been reported with that level of the module. Also, since you have access to all of this storage area, you can attempt to pinpoint a possible cause of the problem yourself. Your previous system knowledge and skill can then be put to good use. The main idea is that in a problem with system modules, the evidence usually remains around for a long time. USING LOOK TO FOLLOW A CONTROL BLOCK CHAIN ON A REAL SYSTEM. The LOOK program is of enormous help to programmers. When writing a system utility, or when asking your program to access system-level information, you'd like to know if the information is really there. Most control block contents in MVS are accessible through a sequence of address pointers, usually starting from the CVT (or Communication Vector Table) control block. For example, if your program is supposed to read a system date, and your code points to a certain displacement from the beginning of the CVT, you can get into LOOK, follow your code instructions, and see if the date is really there. This can be done for any simple, or complicated sequence of instructions that appear in a program. Let's say a program wants to find the current system date in packed decimal. The system maintains this information at displacement, X'38' from the beginning of the CVT. Some assembler instructions to access the system date would be as follows: LA R5,16 POINT TO CVT L R6,X'38'(,R5) PUT DATE INTO REGISTER ST R6,PACKDATE SAVE PACKED DATE . . . . . . PACKDATE DC F'0' STORAGE FOR DATE To verify if the current date is there, get into LOOK. To point to the CVT, enter "I10", or (in XA and ESA) "J10". To suppress the CVT control block formatting, enter "ONULL". Then enter "+38" on the command line. One can infer from Figure Two that a packed date indeed occupies this field. One might use another set of instructions to access the system date, this time using the DSECT mapping of the CVT control block. The instructions would read as follows: LA R5,16 POINT TO CVT USING CVT,R5 USE DSECT NAMES L R6,CVTDATE PUT DATE INTO REGISTER ST R6,PACKDATE SAVE PACKED DATE . . . . . . PACKDATE DC F'0' STORAGE FOR DATE . . . . . . CVT DSECT=YES This time, to verify if the current date is there, get into LOOK. Point to the CVT by entering "I10" or "J10". The CVT should be automatically formatted. If it isn't formatted, enter the command "OCVT", which will format the current storage as the CVT control block. Then browse the formatted control block display, and look for the field labelled "DATE". This is the CVT field called "CVTDATE" (prefixes are dropped in the fullscreen display). In Figure Three, you'll see the "DATE" field in the fifth line of the display. It is trivial to verify that the field contains the current date in packed format. TAGGING POINTS OF STORAGE, AND RERESHING A DISPLAY. It is easy to see that LOOK can be used in far more complicated storage and control block tracking. A further help in this regard is the tagging of storage labels. At any current point of storage, one can create a TAG. Simply enter an equal sign, followed by a name. This name will tag the currently displayed storage. The tagged storage can be redisplayed later by entering a comma, followed by the tagged name. For example, suppose we have pointed to the system date, at +38 hexadecimal from the beginning of the CVT. We can tag this point in storage by entering the command, "=DATE". Later, if we'd want to return to this storage place at any time, we need merely enter the command, ",DATE". This will immediately return us to the location tagged by the command of "=DATE". It is necessary to explain one more command, and then I'll send you on your way. This is the "R" command, which refreshes storage at your current location with a new copy from the system. If you have displayed storage at one location, and you try and redisplay the same location, you will not have obtained a new copy of the system's storage at that location. Your display will still show the storage from the first fetch. The "R" command, entered at this point, will initiate a new storage fetch from the system at the current location. Each time you want to re-access the system's storage at the current location, you have to enter "R". So if you're trying to track changes in storage at a single location, you have to repeatedly issue "R" commands, to keep getting new copies of the system's storage from that place. This is something that's necessary to know when using LOOK. CONCLUSION. It's not hard to see that LOOK, a simple-to-use TSO command, provides a powerful tool to see what's running in the system, especially in the common storage areas. Many problems that were baffling, will easily fall, when put under LOOK's scrutiny. LOOK will help the programmer also, to verify that the data being programmed for, is really there. One can now see virtual storage in any address space, and navigate through it. Good luck searching and LOOKing. See you next month. * * * * * * * * * * * * * * * * * * * * * * * FIGURE ONE. Online HELP for the LOOK Command. LOOK is a TSO command which will display virtual storage in the current address space if it is not run authorized, or IN ANY ADDRESS SPACE if it is being run authorized. To switch address spaces, merely type over the hex address space id field after "DISPLAY ASID=" in the screen header. LOOK is currently "read only", and does not change storage. 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 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 TWO. The "LOOK" Hex Display. This is the normal Hex Display that appears when a numeric hex address is entered next to the prompt: ENTER CMD- ". If no control block that is "known to LOOK" begins at a current address, then this Hex Display of storage is shown. One may also use indirect addressing to point to any memory location. For example: "I10" will point the display to the address that is contained in the location X'10' bytes virtual. "I+10" will point to the address in location hex 10 bytes OFF the CURRENT virtual location. This figure points to the beginning of the CVT on my system. See Figure Three for the formatted version of the same data. The command "ONULL" cancels automatic control block formatting, and forces the hex display. The command "Oblkname" forces formatting at the current address, according to the DSECT description of the control block "blkname". LOOK COMMAND - DISPLAY VIRTUAL MEMORY DISPLAY ASID= 003E ENTER CMD - OCVT LAST CMD - ONULL 00FDB1C0 >00000218 00FEF210 00FDB13C 00FDB790 *>......2.........* 00FDB1D0 00000000 00FFA0A8 00FF6C6E 00FEFC3E *..........%.....* 00FDB1E0 00FEFBAA 01175180 81063F50 00FF1320 *...........&....* 00FDB1F0 00FD14D8 00FEF3C0 0091027F 00FDB7B8 *...Q..3.........* 00FDB200 00FC0C28 00FFC368 00000000 00000000 *......C.........* 00FDB210 0A0307FE 00FDB144 00FDAF90 00000000 *................* 00FDB220 00000000 00FDD690 00FE68A2 00FE68C2 *......O........B* 00FDB230 00F80000 93FE09A8 00620001 00FFC858 *.8............H.* 00FDB240 00000000 81031330 00FF20EC 00000000 *................* 00FDB250 81B3A000 00FDB7B8 00FF3AE0 00D05F48 *..............^.* 00FDB260 00000000 7FFFFFFF 00000000 00000000 *...."...........* 00FDB270 00FDB890 000BA320 00FED318 00FDB178 *..........L.....* 00FDB280 00FDB8C8 80F825E0 00FD36E8 00000000 *...H.8.....Y....* 00FDB290 00000000 0A0D0A06 00000000 00FDAB48 *................* 00FDB2A0 010C6288 7F746F18 00FEF560 00FD9190 *....".?...5-....* 00FDB2B0 00000000 00000000 00F82D28 00FDB700 *.........8......* 1= HELP 2= 3= END 4= 5= REPEAT 6= 7= BACKWARD 8= FORWARD 9= HIST BWD 10= HIST FWD 11= 12= * * * * * * * * * * * * * * * * * * * * * * * FIGURE THREE. A Formatted Control Block Under LOOK. This shows the beginning of the CVT control block on an MVS/XA system, as formatted by "LOOK". LOOK uses an actual assembly macro expansion to produce this formatted picture. One can point to any address from a formatted control block picture by typing "L" followed by the name of any field, with no blanks. For example, to get to the TCB pointer, one enters: "LTCBP". Control block formatting is done automatically by "LOOK" when it recognizes a predetermined indicator at an address, indicating that it is the location of a certain control block. Intentional formatting for an address location to the map of a particular control block is done by the command letter "O" followed by the name of the control block. For example: "OCVT" will format the current address as the CVT control block. The command "ONULL" will force this formatting off unconditionally. LOOK COMMAND - DISPLAY VIRTUAL MEMORY DISPLAY ASID= 003E ENTER CMD - LAST CMD - j10 00FDB1C0 CVT TCBP 00000218 0EF00 00FEF210 LINK 00FDB13C AUSCB 00FDB790 BUF 00000000 XAPG 00FFA0A8 0VL00 00FF6C6E PCNVT 00FEFC3E PRLTV 00FEFBAA LLCB 01175180 LLTRM 81063F50 XTLER 00FF1320 SYSAD 00FD14D8 BTERM 00FEF3C0 DATE 0091027F MSLT 00FDB7B8 ZDTAB 00FC0C28 XITP 00FFC368 RS048 00000000 VSS 0000 VPSM 0000 SVDCB 00FDB144 TPC 00FDAF90 RS05C 0000 ICPID 0000 RS060 00000000 CUCB 00FDD690 QTE00 00FE68A2 QTD00 00FE68C2 STB 00F80000 DCB 93 DCBA FE09A8 SV76M 00620001 IXAVL 00FFC858 NUCB 00000000 FBOSV 81031330 0DS 00FF20EC RS08C 00000000 DAIRX 81B3A000 MSER 00FDB7B8 0PT01 00FF3AE0 TVT 00D05F48 SV76C 00000000 MZ00 7F 1EF00 00000000 QOCR 00000000 QMWR 00FDB890 SNCTR 000B OPTA A3 OPTB 20 QCDSR 00FED318 QLPAQ 00FDB178 ENFCT 00FDB8C8 SMCA 80F825E0 ABEND 00FD36E8 USER 00000000 MDLDS 00000000 TSCE 00000000 PATCH 00FDAB48 RMS 010C6288 SPDME 7F746F18 0SCR1 00FEF560 GTFST 00 GTFA FD9190 TCMFG 00 AQAVB 000000 RS0F4 00000000 1= HELP 2= 3= END 4= 5= REPEAT 6= 7= BACKWARD 8= FORWARD 9= HIST BWD 10= HIST FWD 11= 12=