MVS TOOLS AND TRICKS OF THE TRADE MARCH 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 2 Last month, we talked about some of the nice extensions to TSO/E which were developed by IBM to help avoid IPLs and give the systems programming staff better power and control over the system. Today, we'll continue that discussion and mention more of the details. The main focus of our attention centers around the PARMLIB member IKJTSOxx. Using either a TSO PARMLIB UPDATE(xx) command, or an Operator SET IKJTSO=xx command, the active member IKJTSOxx in PARMLIB can be either reloaded (from an edited version of the same member) or switched to the quantities and names specified in a new member. The internals of what is involved when this happens, are so interesting, that I feel compelled to show you some of the nice things that IBM's TSO developers have accomplished. Much of the motivation for putting these features into TSO/E, has been "avoiding unnecessary IPLs." Of course, the main idea in avoiding unnecessary IPLs is to convert fixed structures that were created in storage at IPL time, to structures that can be re-created (in a different storage location and pointed to) much later, long after the IPL, when the system is running normally. These new structures that were created later, should perform with exactly the same effectiveness as the original structures that were created at IPL time. Thus, a new IPL is avoided. So what kind of functionality are we dealing with here? Just take a quick look at a fully populated PARMLIB IKJTSOxx member, and let's see. We can go to SYS1.SAMPLIB on our system and look at the IKJTSO00 member which is there, for a typical example. The categories listed are: AUTHCMD, AUTHPGM, NOTBKGND, AUTHTSF, SEND, ALLOCATE, TRANSREC (Transmit and Receive), CONSOLE, PLATCMD, HELP, PLATPGM, and TEST. As far as I know, the entries under each of these categories can all be changed dynamically, by either a PARMLIB UPDATE(xx) command or an Operator SET IKJTSO=xx command. (We're talking TSO/E Version 3 here, from z/OS 1.3 and onward. Before that, this wasn't entirely true.) So this means that each of these entries must reserve a certain place in machine storage, where control information exists that is pointed to and referenced by whichever TSO/E component applies. Today I'm prepared to show you much of it. TSO/E CONTROL BLOCKS Last month, we talked quite a bit about the general TSO/E control block structure which applies to this area, so today I'm going to summarize what is going on. The main TSO/E control block is the TSO/E Vector Table, the TSVT, which is pointed to by address X'9C' off the beginning of the CVT. The TSVT is a public interface, which is described by the IKJTSVT macro in SYS1.MACLIB. The next important control block is the TPVT, which is a private control block whose details have not been publicized by IBM. The TPVT is pointed to at location X'4C' off the beginning of the TSVT. (This location is public knowledge, and part of the IKJTSVT macro in SYS1.MACLIB.) A description of the TPVT has been created, by guesswork, and can be found as macro IKJTPVT in the SHOWMVS source code in the SHOWMACS member of CBT Tape File 492. I have made a few corrections to this member, and my updated IKJTPVT member is found on the CBT Tape File 731, in the MODGEN member, that may currently be found on the Updates page of the CBT Tape website. You can easily locate the CBT Tape website by running a www.google.com search for "CBT Tape". The TPVT control block points to most of the rest of the necessary information. Please look at our sample picture of an active TPVT control block that is from a z/OS 1.6 MVS system. This picture was created using the LOOK TSO command that is very helpful for browsing system storage locations in a running MVS system. Source code for LOOK comes from File 264 of the CBT Tape collection. A load module for LOOK can be found on CBT Tape File 035. AUTHCMD, AUTHPGM, NOTBKGND, and AUTHTSF The dynamic storage which points to all of these authorization tables for TSO/E is pointed to from the CTLT control block at X'14' off the beginning of the TPVT. The CTLT +X'8' points to IKJEFTE2, followed by a fullword with the length of the control block, a halfword with the number of entries starting from the entry point, and another halfword containing the length of one table entry (which in this case is 8, the maximum length of a program name). This is followed by the CTLT +X'14', pointing to IKJEFTE8, followed by similar "length" information, then CTLT +X'20', pointing to IKJEFTNS, and CTLT +X'2C', pointing to IKJEFTAP. This is the "real global system information", unless it is overridden by an IKJTABLS member running in an authorized STEPLIB in your TSO session (or in the authorized STEPLIB of a TSO-in-batch job). If any of these four keywords, AUTHCMD, AUTHPGM, NOTBKGND, or AUTHTSF, is not coded in the active IKJTSOxx member, then the addresses in the CTLT will default to point to the entry points (respectively) IKJEFTE2, IKJEFTE8, IKJEFTNS, and IKJEFTAP that are in the copy of the IKJTABLS member in LPALIB, and the length information which follows them in the CTLT control block is set to zero. In that way, the TSO programs that need this information will "know" what to do. ALLOCATE, HELP, CONSOLE, AND TEST The ALLOCATE entry in the IKJTSOxx member of PARMLIB has only two possible settings: DEFAULT(OLD) or DEFAULT(SHR). The idea is that if you allocate a new dataset with no further specifications (say, if you use the TSO ALLOCATE command to do it), then this setting sets a system-wide default that the allocation be either DISP=OLD or DISP=SHR. The indicator is a single bit setting at X'C' off the ALPL control block that is at X'24' from the beginning of the TPVT. If the bit setting is X'80', then the default allocation attempts are DISP=OLD. If the bit setting is X'40' then the default allocation attempts are DISP=SHR. The default (if no ALLOCATE entry is present in the IKJTSOxx member) is DISP=OLD. The CONSOLE entry in the IKJTSOxx member sets the default capacity values for simulated MVS consoles which are opened by the TSO CONSOLE command. Default values are INITUNUM and INITSNUM of 1000, and MAXUNUM and MAXSNUM of 10000. You can change these by setting different quantities up, in your IKJTSOxx member of PARMLIB. The incore values for these quantities are present in the IKJCNPRM control block that is at X'30' off the beginning of the TPVT. A guesswork mapping of IKJCNPRM can be found in the SHOWMVS.MACLIB that is from the SHOWMACS member of CBT File 492. The HELP entry in the IKJTSOxx member supports National Language differences when it comes to TSO HELP. United States English (called ENU) is the default for the HELP dataset, and SYS1.HELP is the default for its name. But many national languages, together with their associated HELP datasets, can be supported under TSO, and their names and datasets can be specified here. Control Block information for the HELP entry in IKJTSOxx is located at X'3C' off the TPVT, which points to the IKJEFHCB (TSO Help Control Block). The TEST entry in the IKJTSOxx member contains two sets of name entries. These are the TSOCMD( ) entries and the SUBCMD(( )) entries. Both are pointed to by the TPT control block whose address is at X'28' off the beginning of the TPVT. TPT +X'C' points to the TCT which is the list of TSO commands that can be executed under the TEST command. TPT +X'14' points to the SCT which is the list user program names paired with their entry points, that can be run as subcommands under TEST. This capability extends the powers of the TEST command to include user-written interfaces. Defaults are blank table entries. PLATCMD and PLATPGM The PLATCMD and PLATPGM entries in IKJTSOxx can specify lists of TSO command names and program names (respectively) which can run under the TSO/E command/program invocation platform. These programs do not require task termination processing to clean up for them. If these parameters are not coded in the IKJTSOxx member, then the default is not to create any incore name lists, and the TPVT entries which are supposed to point to the FCVE (for PLATCMD) and PPVE (for PLATPGM) control blocks will contain binary zeros. If the PLATCMD and/or PLATPGM entries are found in the IKJTSOxx member, then these control blocks are created. The FCVE control block (PLATCMD) is pointed to by the address at X'34' off the TPVT, and the PPVE control block (PLATPGM) is pointed to by the address at X'40' off the TPVT. If these locations in the TPVT contain fullwords of binary zeros, it means that the PLATCMD and PLATPGM keywords had not been coded in the active IKJTSOxx member of PARMLIB. TRANSREC and SEND We've saved the best for last. These are the specifications for the TRANSREC (Transmit and Receive defaults) and SEND (SEND, LISTBC and BROADCAST dataset) keywords in the IKJTSOxx member of PARMLIB. If you've ever tried to TRANSMIT (XMIT) a large dataset, you've probably run into the warning messages about the TRANSMIT limits on the system. These are the INMX034I warning messages that tell you that nnnnnn messages have already been transmitted, and your installation limit is xxxxxxxxx records. If you don't code a TRANSREC statement in the IKJTSOxx member of PARMLIB, you'll find that the limits of the stuff you can TRANSMIT are very small: 10000 lines for the first warning, 5000 lines for the warning interval, and 30000 lines for the maximum. These numbers show up in the INMXPARM control block too. The INMXPARM control block, which contains the TRANSREC settings in storage, is pointed to by X'2C' off the TPVT. I have written a TSO command (non-authorized) to display all the INMXPARM values. This command is called INMXD and you can find it in CBT Tape File 731 on the Updates page (currently) at the CBT website. My INMXD command takes old TSO/E releases into account too, back (at least) to TSO/E 2.5. See Figure 2 for some typical output from the INMXD command. The INMXPARM control block doesn't have a publicized mapping macro from IBM. But in the MODGEN member on File 731, macro IKJXPRM, there is at least, for the current versions of TSO/E (2.6 and later) a pretty good guess at its contents. The format of the INMXPARM control block had changed, between TSO/E Versions 2.5 and 2.6. As we mentioned last month, the SEND keyword in the IKJTSOxx PARMLIB member contains the BROADCAST dataset information, and the BROADCAST dataset name. This keyword also contains information about whether the TSO Userlogs for user messages are enabled, and the Userlog naming conventions and default sizes. Control information about the current BROADCAST dataset, Userlogs (if any) and BROADCAST dataset switching is contained in the IKJEESCB control block that is pointed to at X'20' off the beginning of the TPVT. The IKJEESCB control block format is a public interface, with the IKJEESCB macro being located in SYS1.MODGEN. I have written a (non-authorized) TSO command called EESCB which we illustrated in this column last month. The EESCB command displays the current status of (pretty much) all of the SEND parameter information in IKJTSOxx, and it displays more information then does the D IKJTSO,SEND Operator command. My EESCB command will display available information about the BROADCAST dataset on older TSO/E releases as well, but before TSO/E Version 3.x, there was no BROADCAST dataset switching. At the TSO/E Version 3 level, EESCB will display just about all of the BROADCAST dataset switching information, except for the switching time information at the end of IKJEESCB. I figured that since BROADCAST dataset switching is usually done via a full PARMLIB member switch, displaying the time and date from the TPVT (which is formatted more nicely) would suffice. If you don't code a SEND parameter in IKJTSOxx, then SYS1.BRODCAST (as cataloged) is the default BROADCAST dataset name, and things are just about the same as they were before BROADCAST dataset switching was possible. SUMMARY IBM's developers have done a very good coding job in allowing TSO/E-controlled values to be reset at any time after an IPL, using the PARMLIB UPDATE(xx) TSO command, or the SET IKJTSO=xx Operator command to trigger the switching. All of the values which can be specified in the IKJTSOxx PARMLIB member will eventually show up in dynamically created TSO/E control blocks that the system uses. I find it quite amazing that these values (if they existed at all) in the old MVS releases, used to require an IPL to change, and now, they don't. MVS still has the look and feel of the way it used to be, but by clever coding, the IBM software developers have been able to make all the values dynamically adjustable without an IPL. For us, I feel that this discussion brings us back to earth, in a sense. As systems programmers, we spend a lot of time setting up the system, and precious little time thinking about how it is coded. So here we see a component of the system, which has existed for nearly four decades already. It has been re-coded in many very clever ways, and it still remains externally looking much the same as it used to look. My ` own creative juices get inspired when I see that, and it encourages me to think of clever innovations with the system that I can try to create myself. I wish you all a good month, and I hope to see you here again next time. * * * * * * * * * * * * * * * * * * * * * Figure 1. A Glimpse at the TPVT Control Block The TPVT Control Block, here illustrated using the LOOK TSO command from File 264 of the CBT Tape (load module on File 035), from z/OS 1.6, showing its active pointers. LOOK COMMAND - DISPLAY VIRTUAL MEMORY DISPLAY ASID= 004C ENTER CMD - LAST CMD - J+4C 11495670 >E3D7E5E3 00DC0200 C9D2D1E3 E2D6F0F0 *>TPVT....IKJTSO00* 11495680 00000001 114B5010 0000003C 00000000 *......&.........* 11495690 101CC1D8 114BC028 11231018 101CC0D8 *..AQ...........Q* 114956A0 11239010 101B4068 00000000 11232000 *...... .........* 114956B0 11255020 00000000 00000000 00000000 *..&.............* 114956C0 C1C4C3C4 4BE9F1F6 4BD7C1D9 D4D3C9C2 *ADCD.Z16.PARMLIB* 114956D0 40404040 40404040 40404040 40404040 * * 114956E0 40404040 40404040 40404040 E9F6D9C5 * Z6RE* 114956F0 E2F10000 C1C4C3C4 40404040 5C5CE2C5 *S1..ADCD **SE* 11495700 E35C5C40 F1F17AF0 F67AF5F6 F2F0F0F6 *T** 11:06:562006* 11495710 60F0F260 F0F80080 00009999 12471106 *-02-08..........* 11495720 56762006 02088000 00000000 00000000 *................* 11495730 00000000 00000000 00000000 00000000 *................* 11495740 00000000 00000000 00000000 00000000 *................* 11495750 00000000 00000000 80000000 00000000 *................* 11495760 00000000 00000000 00000000 00000000 *................* 1= HELP 2= 3= END 4= 5= REPEAT 6= 7= BACKWARD 8= FORWARD 9= HIST BWD 10= HIST FWD 11= 12= * * * * * * * * * * * * * * * * * * * * * Figure 2. TSO Command INMXD Example The INMXD command from CBT Tape File 731 shows the currently set values in the INMXPARM (Transmit and Receive) control block. This command does not have to be APF Authorized, because it does display only. Old releases of TSO/E (before 2.6) are also supported by this command. INMXPARM - Display of Field Values -------- ------- -- ----- ------ INMXPARM ADDR 1119E390 LENGTH 0100 NJE COUNT 0001 NJE START 1119E480 INMX VERSION 02 INIT WARN 50000 WARN INTRVL 15000 OUTLIMIT 5000000 VIO UNIT LNG 08 VIO UNIT SYSALLDA CIPHER FLAG 40 SYSOUT CLASS * LOG NAME MISC LOGSEL 1 . LOGSEL LOG. LOGSEL SIZE 0005 SYSCTL NAME SYSCTL SIZE 0000 USRCTL NAME .NAMES.TEXT USRCTL SIZE 000B SPOOL CLASS B NODE/SMF 0001 NODENAME SMF