MVS TOOLS AND TRICKS OF THE TRADE FEBRUARY 2006 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. TSO/E CONTROL BLOCKS - PART 1 TSO is a very old part of MVS, but it has to keep up with the times. Installations are trying to be up 24 hours a day, 7 days a week, and they are trying to avoid IPLs. Adjustments have to be made to the system while it is up and running and in the middle of doing productive work. (It would be nice to perform these adjustments using operator commands from the console.) Hard-coded quantities which need an IPL to change, are a no-no, and for the past twenty-or-so years, IBM has been trying to engineer them out of the system. But unfortunately, MVS, as originally designed, had a lot of these quantities built into it. So each one of these things had to be painstakingly redone and re-architected. For example, the control block which defined all the node names known to JES2, used to be located in one block of storage that was defined at IPL time. Such a structure would assume that you didn't mind doing an IPL. But that's intolerable now. So the control block was made dynamic. A block of storage was obtained and pointed to, and then all the node names were copied in, but the storage was extendable, so that each obtained piece of storage pointed to the next piece, and the node names themselves were chained to each other. This new kind of structure could be done over without an IPL, while the system was still running, and a new node could be added or deleted at any time, using an operator command. Same thing with TSO. In the original design of MVS, the APF authorized TSO command table was actually a CSECT that was linkedited into the terminal monitor program itself. When I first started in the business, you had to have your own copy of the IKJEFT02 program in an authorized STEPLIB, if you wanted your session to use a different APF list of programs (CSECT IKJEFTE2) than everybody else had. This was release-dependent too. The next time IBM came out with a new version of TSO, you had to re-do your CSECT IKJEFTE2 (and IKJEFTE8, etc.) and linkedit those tables into the later release level of the IKJEFT02 terminal monitor program. Otherwise, you'd get incompatibilities in the way your TSO session was run. You were running the old release, and the rest of the system was running the new release. If you wanted to be "special", it was quite a high price to pay. So when IBM came out with TSO/E (in the early to mid 80s) they got smarter and realized that tables of program names should not be associated with things that were release dependent. All of these CSECTs which contained the tables of names that are now associated with the IKJTSOxx PARMLIB member entries: AUTHCMD - CSECT IKJEFTE2, AUTHPGM - IKJEFTE8, NOTBKGND - IKJEFTNS, and AUTHTSF - IKJEFTAP, were now isolated into a new load module called IKJTABLS. This module only contained the four entry points and their corresponding tables of program names only. Such a table would never again be dependent on which release of TSO you were running. But even that wasn't enough for a 24x7 environment that could not tolerate IPLs. Changes to these tables that would truly be dynamic, wer- required. IBM's first stab at this was with the PARMLIB UPDATE(xx) TSO command. I guess they figured that since such system-wide changes were in the systems programmers' domain, they should give the systems programmers the ability to control the situation, and they designed a specially authorized TSO command (the PARMLIB command) that would allow systems programmers to perform PARMLIB member switches. With TSO/E Version 3 (z/OS 1.3 and later), even that wasn't enough. Sometimes the systems programmers will set up a change plan and then they'll go home, making an arrangement with the operators to enter some command that makes the adjustment at some ungodly hour in the middle of the night. You would never expect an operator to enter a TSO PARMLIB command. Their TSO ids do not (and should not) have that much authority. The operator's domain is the console, and therefore they should have a console command to do the adjustment. So with TSO/E Version 3, IBM introduced the SET IKJTSO=xx command that does essentially the same thing as the PARMLIB UPDATE(xx) command. This is the area that we are going to address today. When the system (during IPL time) or the programmer (using a PARMLIB command) or the operator (using the SET IKJTSO=xx command) sets up the TSO environment a certain way, what happens internally? Where is this information kept? How can we learn more about our own systems, and make proper adjustments if necessary, by peeking and poking (safely) in this area? To tell the truth, IBM has it pretty well covered with the great power that the PARMLIB TSO command has nowadays. But I think that it is still profitable for us to look around at what's there, and learn. LOOKING AT TSO CONTROL INFORMATION THE WAY THE SYSTEM DOES The heart and soul of modern TSO/E internal structure is the TSO/E Vector Table, mapped by the IKJTSVT macro in SYS1.MACLIB. It is a fitting testimony to the fact that IBM is "dynamic-izing" TSO, that at one time in not-so-distant MVS history, the TSO Vector Table didn't even exist. Everything in TSO really WAS very static. Since the TSO/E Vector Table mapping is public knowledge, I invite you to go to your systems and look at it. You should read all of the "Change Activity". Depending on your TSO Version level, you'll see that the support for various TSO/E facilities has kept growing, and the beginnings of the search for most control information relating to TSO/E operation starts here with the TSO/E Vector Table. My own interest in this area was initiated by the fact that I am writing and expanding a comprehensive BROADCAST dataset management tool. I started out by dealing with the SYS1.BRODCAST dataset itself, and I learned how to access the different parts of it, how to read, write and delete the messages myself, both in the user part and in the Notices part, and how to backup and copy the BROADCAST dataset in it's entirety, even across different device types. That was all well and good before, but in today's TSO environment, it's becoming downright exciting, because one of the latest TSO/E developments, begun in TSO/E Version 3, has been BROADCAST dataset switching. If I can make a copy of the SYS1.BRODCAST dataset, or even construct a completely new one using my own tools, and then the system can switch to it using a PARMLIB UPDATE(xx) TSO command or a SET IKJTSO=xx operator command, then I've given the system administrators very considerable control over the TSO messaging environment. So because of this, I had to expand my interest in the SYS1.BRODCAST dataset itself, to include all the goings-on involved in switching from one copy of it to another. This stuff starts taking place in the IKJTSVT control block (the TSO/E Vector Table) and continues in the TPVT (which officially is not a public interface, but as we'll see, you have to look at it), and it goes further, to the IKJEESCB control block (mapped in SYS1.MODGEN), which contains a good deal of the BRODCAST dataset information, and with TSO/E Version 3, it contains much of the BROADCAST dataset switching information. Today we'll get a glimpse of how exciting the knowledge of this information can be. BROWSING STORAGE AND FOLLOWING CONTROL BLOCK CHAINS I almost never write a system-level program that "chases control block chains" without using the free "LOOK" TSO command, which browses active storage. The LOOK command can be found (source code) in the free CBT Tape collection on File 264. An easily installed load module for LOOK can be copied from the load module library on CBT Tape File 035. So if you get this load module library from the CBT Tape web site (do a www.google.com search for "CBT Tape" and you'll find it easily), then just copy the LOOK module from the File 035 library to a load library that your TSO session can access. If you run LOOK unauthorized, you can browse storage in your own TSO session's address space. But that includes all COMMON STORAGE that is not fetch protected. Therefore you can use LOOK to examine Subpool 241, both below and above the 16M line, which is valid for the entire system, and which concerns us directly. So that's where we're going to begin. How does LOOK work? LOOK has a full screen display. The command J denotes 31-bit indirect addressing. So if you want to point to the CVT, whose address is at virtual storage location X'10', you say (in the LOOK screen) the command J10. This points you to the CVT. If you'll actually do that, you'll notice that the CVT is formatted by its fields. The field names correspond exactly to the names in the CVT macro from SYS1.MACLIB, because at assembly time, the formatting had been built from an actual copy of the CVT macro in SYS1.MACLIB. To get to the TSO/E control block areas we need, using LOOK, you do the following: Entering J+9C from the CVT, you get to the TSO Vector Table. Entering J+4C from the TSVT, you get to the TPVT. And entering J+20 from the TPVT, you get to the IKJEESCB control block that gives you very important information about the current status of the BROADCAST dataset. In an Assembler program, the corresponding instruction sequence would be: Load a register with 16 (which is X'10') to get to the CVT. Load a register with X'9C' off the CVT to get to the TSVT. And load a register with X'4C' off that register to get to the TPVT. Then load a register with X'20' off the beginning of the TPVT, to get to the IKJEESCB. To show you the kind of information about the BROADCAST dataset which the TPVT and IKJEESCB control blocks contain, I have written a TSO command which displays the current status of this information on your MVS system. This command is called EESCB, and it runs unauthorized because it just displays information, and doesn't try to change Subpool 241 storage. To show you some output from the the EESCB command, please look at Figure 1. You can find the EESCB command on File 731 of the CBT Tape collection. At this writing, File 731 is only on the Updates page of the CBT Tape web site; it isn't on the regular CBT Tape yet. THE TPVT CONTROL BLOCK The TPVT control block, which is at the heart of all the PARMLIB switching mechanisms, is officially not described to the public by IBM. But one glance at it using LOOK, will show you how important the TPVT is to TSO/E operation. The address at TPVT+X'14' points to the CTLT control block, which points to the incore addresses of the AUTHCMD, AUTHPGM, NOTBKGND, and AUTHTSF tables. TPVT+X'20' points to the IKJEESCB control block (with IS documented by IBM in SYS1.MODGEN). TPVT+X'24' points to the ALPL control block, which tells you if your default allocations in the system are OLD or SHR. (This is all PARMLIB IKJTSOxx information, folks!) TPVT+X'28' points to the TPT, which gives TCT and SCT information. TPVT+X'2C' points to the INMXPARM control block, that has all your TRANSMIT TSO command defaults for the system. TPVT+X'30' points to IKJCNPRM, which contains your CONSOLE TSO command PARMLIB quantities. TPVT+X'3C' points to IKJEFHCB, which contains the PARMLIB information about the HELP datasets and their language support. Additional information in the TPVT concerns the most recent status of PARMLIB IKJTSOxx switching, who did it, and when. Quite a bit of this information has to be figured out by guesswork. But much of the guesswork has already been done for you. The SHOWMVS TSO command (source on CBT File 492, load on File 614), which displays "everything but the kitchen sink" about your MVS system and your own TSO session, contains a macro library which has macros that attempt to map system areas by guesswork. All macros there which begin with the letters IKJ, will be helpful. I made a correction to the macro there (called IKJXPRM) that describes the INMXPARM control block. The corrected macro can be found on File 731 on the Updates page of the CBT web site, in the MODGEN member. I guess that does it for now, but we'll hopefully continue on this same topic next time. I think that this knowledge gives a person a real appreciation for the work that the IBM MVS developers have done, and continue to do, with such accuracy and reliability. Support for the newer MVS features does not come cheaply. It requires large effort from the MVS developers, and since the system works so nicely, we don't easily get to appreciate the detailed and extremely careful work which these fine people have done. Thanks, IBM Software Development! Please come back to these pages next month. Meanwhile, I wish all of you a most happy, healthy, and productive year. * * * * * * * * * * * * * * * * * * * * * * Figure 1. Sample Output from the EESCB TSO Command The EESCB command, from File 731 of the CBT Tape collection of free MVS materials, shows the status of the BROADCAST dataset (default is SYS1.BRODCAST) on the MVS system. The EESCB command attempts to be as self-explanatory as possible. 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 : 113D6770 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.Z16.PARMLIB PARMLIB Volser : Z6RES1 PARMLIB Member : IKJTSO00 PARMLIB Activator **IPL** PARMLIB Swt Date: 2005-10-03 PARMLIB Swt Time: 06:54:43 PARMLIB System : ADCD PARMLIB CPUID : 0192 PARMLIB CPU Model 1247 This system does not write to TSO Userlogs. BRODCAST Dataset : SYS1.BRODCAST BRODCAST Volser : Z6SYS1 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