TSO AUTHORIZATION TABLES - Part 2 (c) Copyright 2009 by Sam Golob. All rights reserved. TOOLS TO MANIPULATE OR REBUILD THE AUTH TABLES: ASUB, TSUB, LLWA, and LWATMGR In our last article, we discussed the TSO authorization tables in general, the fact that they consist of lists of program names, and we said something about what each of the lists accomplishes. There are four main lists: These are AUTHCMD (module IKJEFTE2), AUTHPGM (module IKJEFTE8), AUTHTSF (module IKJEFTAP), and NOTBKGND (module IKJEFTNS). AUTHCMD lists all TSO commands that are allowed to run APF authorized under your TSO session. AUTHPGM lists all programs that can run APF authorized when called by your TSO session. AUTHTSF lists all programs that can get authorized using the TSO Service Facility. And NOTBKGND lists all TSO commands that cannot be run under TSO-in-batch. As systems programmers, we all know how to set the lists of program names in each of these categories, by creating or modifying an IKJTSOxx PARMLIB member. Then, once the member is created, we issue a PARMLIB UPDATE(xx) TSO command or a SET IKJTSO=xx operator command to put that member into effect. What happens to the system as a result of these commands, is what most people don't know about. This is part of what we're going to talk about. What comes next, though, will be some instructions about how we can directly manipulate the in-core program tables that are constructed from the PARMLIB IKJTSOxx member. When a PARMLIB UPDATE(xx) command, or an IPL, or a SET IKJTSO=xx operator command is issued, in-core tables: IKJEFTE2, IKJEFTE8, IKJEFTAP, and IKJEFTNS are created in common storage. These become templates for the corresponding tables that will belong to (almost) every TSO session that will LOGON afterwards. These common storage tables are pointed to by the CVT, the TSO Vector Table, the TSO PARMLIB Vector Table, and the IKJCTLT control block. Once you get to the IKJCTLT control block, you have the pointers to all of the in-core TSO authorization tables. The exact addresses are: TSO Vector Table is X'9C' off the CVT. The TSO PARMLIB Vector Table is X'4C' off the TSVT. And the CTLT is X'14' off the TPVT. A map of the TPVT and the CTLT can be obtained from the SHOWMACS member of CBT File 492 or the MODGEN member of CBT File 731. Maps of these last two control blocks are not distributed by IBM. We had to figure them out. MANIPULATING THE IN-CORE COPIES OF THE AUTH TABLES - THE ASUB COMMAND I wrote an authorized TSO command called ASUB, which goes directly into the in-core TSO auth tables created from the IKJTSOxx PARMLIB member, and manipulates its table entries, which are program names. The ASUB program can be found on CBT Tape File 185, where the TSUB program can also be found. The ASUB program works as follows: ASUB has three functions: DISPLAY an entry, or the entire table. REPLACE a numbered entry in the table, and BLANK the last entry in the table. The syntax of the ASUB command is: ASUB tta nnn pgmname where tt is the table name: E2, E8, AP, or NS. a is the action code, D for display, R for replace, B for blank. nnn is the specific numbered table entry you want to display or change. pgmname is the new program name you want to Replace, for the existing name that is in that table slot now For example, ASUB E2D will display the entire IKJEFTE2 table and list all its entries. ASUB E2D 55 will list only one entry in the IKJEFTE2 table, the 55th one. ASUB E2R 55 CQX will replace whatever name was in the 55th entry of the IKJEFTE2 table, with the program name of CQX. ASUB E2B will erase whatever program name was in the last entry of the IKJEFTE2 table, and will replace it with a blank entry consisting of all spaces. A blank entry always delimits the entire table, causing any entries after the blank entry, to be ignored. For that reason, I did not allow the B function of ASUB, to blank any entry in the middle of the table, but if I had filled in the last entry of the table with a non-blank program name, using the ASUB Replace function, the B function will blank out this non-blank entry that I had put at the end of the table. This concept is very important for us, because when I discuss the similar TSUB program later, I'll show you how TSUB can blank out any table entry even in the middle of the table, and not just the last entry. This is a VERY significant concept for us to grasp. Since the ASUB program has to run as an APF authorized TSO command, its name has to be entered in the IKJEFTE2 (AUTHCMD) table list of program names, and its load module has to reside in an APF authorized load library. Again, I must emphasize that ASUB does not modify a copy of the tables that is used directly by your TSO session. The copy of the tables that ASUB modifies, is the "common storage" copy of the table that TSO LOGON uses to create your session's tables at LOGON time. So if your TSO session was logged on, and you used ASUB to change one or more table entries, the changes will only affect your TSO session after you re-LOGON. The effect of ASUB in manipulating the TSO auth tables is GLOBAL, and it affects the entire LPAR until another PARMLIB UPDATE command, or SET IKJTSO= command is issued, or until you IPL. Every NEW TSO session to LOGON, will copy the table version which ASUB has modified. GETTING YOUR TSO SESSION'S TABLES FROM STEPLIB The TSO designers have created another way to build your TSO session's "auth" tables at LOGON time. If you are a sysprog or another "special-type" user, who was allowed by management to have a LOGON PROC in your TSO session with a STEPLIB DD to an APF-authorized load library, then this is a special case, different from ordinary TSO users. One other condition must be satisfied to create the special case. The APF-authorized STEPLIB must contain a linkedited copy of a load module called IKJTABLS, that contains CSECTs IKJEFTE2, IKJEFTE8, IKJEFTAP, and IKJEFTNS, or some of these. In this special case, at LOGON time, the LOGON processing will not copy your session's auth tables from the PARMLIB-created copies in common storage. But it will do a BLDL for the CSECTs from the STEPLIB, and if the CSECTs are there, LOGON will copy them from the authorized STEPLIB instead of from the "common storage" PARMLIB-created copies. In this way, a "special" user can have different "auth tables" than everybody else. At LOGON time, there are differences to how the STEPLIB-created tables look, as opposed to the PARMLIB-created tables. In the LWA, the STEPLIB-created tables are marked as having zero length. This has the effect of forcing the only delimiter to the tables, to be the first blank entry. The system (in that case) has no other way of knowing how long each table is. On the other hand, when the tables are copied from the PARMLIB-created "common storage" copy, the length of each table is filled in, in an appropriate field in the LWA (Logon Work Area) for that particular table and that TSO session. One other difference exists between STEPLIB-created auth tables and PARMLIB-created auth tables for your TSO session. This is, that the LWA for your TSO session contains a flag bit for each of the four tables, which is 1 if the table came from STEPLIB, and it is 0 if the table came from PARMLIB. The effect of this bit is as follows: If the bit for that table is 0, then when some TSO session does a PARMLIB UPDATE(xx) command, or the operator issues a SET IKJTSO=xx command, all TSO sessions which have their tables marked as coming from PARMLIB, will get their tables overlaid and re-created, according to the new IKJTSOxx member that is in effect. If a table is marked as coming from STEPLIB, with the bit set to 1, then overlay from a PARMLIB UPDATE(xx) or SET IKJTSO=xx command DOES NOT OCCUR. This is understandable. If a "special user" has special authorization permissions, he/she does not want them overlaid by a global change for the rest of the TSO users. So that's why IBM designers put the STEPLIB bit there, in the LWA. MANIPULATING YOUR TSO SESSION'S OWN TABLES - THE TSUB COMMAND To manipulate YOUR TSO SESSION's auth tables, or to change the characteristics of your TSO session's existing tables, I have written the authorized TSO command called TSUB. Except for its Display function, TSUB has to be APF-authorized, so its name has to be entered in your session's IKJEFTE2 (AUTHCMD) table. The TSUB command is like the ASUB command, but with more added capability, owing to the difference in the nature of the "common storage" copy of the tables (created by PARMLIB) and the individual users' copy of the tables, pointed to by the LWA. ASUB works on the "common storage" copy of the TSO auth tables. TSUB works locally, on YOUR OWN SESSION's copy of the TSO auth tables, pointed to by the LWA. As a consequence, other differences between TSUB and ASUB are: 1. If you make a change to a table with ASUB, your TSO session will only get the changes if you re-LOGON. When you make table changes with TSUB, the effect (to your TSO session) is immediate. If you re-LOGON after TSUB has made changes, all changes will be lost. 2. ASUB only deals with tables that were created from PARMLIB members, and which therefore are marked with a length. TSUB can get its tables either from PARMLIB or from STEPLIB. If your session's tables came from STEPLIB, they do not have length values (in the LWA) attached to them. Therefore, TSUB can not easily "blank" a "last member" of a table, because we don't really know where the "last member" is. So I allow TSUB to blank ANY member of a table. This is potentially dangerous, but also potentially useful and creative. It depends on how much knowledge you have, and on how responsible you are. Fortunately, if you mess up with TSUB, you can re-LOGON and set things back to the beginning state. Not so with ASUB. With ASUB you have to re-issue PARMLIB UPDATE(xx) or SET IKJTSO=xx to set things straight again. 3. ASUB only manipulates tables in common storage. TSUB can ALSO manipulate LWA fields that are connected to each of the tables. The effect of a TSUB change is IMMEDIATE, but it only affects your own TSO session. Therefore, TSUB has extra action codes possible. Extra action codes associated with TSUB, which you don't have with ASUB, are: H - Alter the header of the table to make it look like it came from PARMLIB. L - Measure the table, to put a "length" field for it, in the LWA. Z - Zero out the length field for the table in the LWA. Force it to be delimited only by the first blank entry. S - Turn on the STEPLIB bit for the table in the LWA. This has the effect that a PARMLIB UPDATE(xx) or SET IKJTSO=xx command will not overlay your session's table. P - Turn off the STEPLIB bit for the table in the LWA. Then a PARMLIB UPDATE(xx) or SET IKJTSO=xx command will overwrite the existing table when those commands are issued. B - Blank any table entry. With ASUB, you say E2B and you can only blank out the "last table entry". With TSUB, the B action must be followed by a "slot number" to blank out, and it can be ANY SLOT, even one in the middle of the table. The effect of this blanking, is to nullify ALL SUBSEQUENT NON-BLANK entries in the table, and to stop reading the table at the blank entry. That is dangerous if you don't know what you're doing, but I can think of some very creative ways of using this capability. MAKING COMPLETELY NEW TABLES WITH LLWA, LWATMGR, AND LWATEDIT TSUB (and ASUB) deal with MODIFYING ALREADY EXISTING tables. What if you wanted to forget about the existing table and load a completely new one, with a whole set of new and/or different and extra entries? If you're dealing with your own TSO session's LLWA-pointed auth tables, this is entirely possible, using a set of TSO commands: LLWA and/or LWATMGR from CBT Tape File 797. LLWA was written by me. LWATMGR and its ISPF interface program, LWATEDIT were written by Dan Dalby. To replace an existing table with a new table, a program has to GETMAIN some Key 0, Subpool 252 storage (for that, it has to be APF authorized), the new table has to be constructed in storage and copied into the GETMAINed area, and the field in the Logon Work Area, which points to the requisite table, has to be re-pointed to the new table. To modify the LWA, you also have to be APF authorized. And before a new table location is finalized, there are two more modifications that have to be made. If the table has a length value associated with it, that length has to be plugged into the proper field in the LWA, and also there is a bit in the LWA which states that this table came from STEPLIB and not from PARMLIB. Our programs LLWA and LWATMGR set this bit on, because if it is not on, a future PARMLIB UPDATE(xx) or SET IKJTSO=xx command would overlay our new table in our address space, erasing our changes. The LLWA program, written by me, will replace one table, or all four tables, from either of three sources. The LWATMGR program, written by Dan Dalby, will deal with one table at a time only, but LWATMGR can also create an entirely new table from the same three sources. These sources are: An IKJTABLS load module, similar to the one that you put in an APF authorized STEPLIB, or, an FB-80 IKJTSOxx PARMLIB-like member, or, an FB-8 (that is, LRECL=8) list of program names. The FB-8 list of program names is headed by a "header record" that looks like "---E2---", or "---E8---" or "---AP---" or "---NS---", which tells you which table to build from the names that follow the header. LLWA will create a new table with 30 blank entries at the end, which is my preference. The extra blank entries allow you to add more names with the TSUB program, one at a time. Dan Dalby's LWATMGR program adds only one blank entry at the end, because his program can repeatedly FREEMAIN and GETMAIN storage for new tables as needed. And LWATMGR has facility to add or delete one program name at a time also. Dan's LWATEDIT facility for creating a new table is quite amazing. You execute the TSO command LWATEDIT under ISPF, and a panel comes up, asking you which table you want to update. When you pick a table, you get the list of program names which that current table contains. You then can edit the list as you wish, copy names in and out, and then you SAVE it. After you SAVE the list and when you exit it, LWATEDIT calls LWATMGR to automatically build a new table with just those entries. So you can actually EDIT your auth tables and customize them as your current needs dictate. LWATEDIT makes its table updates by calling LWATMGR, which must be APF authorized. Since LWATEDIT operates under ISPF, and ISPF does NOT "like" to be authorized, LWATEDIT must authorize LWATMGR using the AUTHTSF facility. So when you use LWATEDIT, the name LWATMGR must reside in BOTH the AUTHCMD and the AUTHTSF tables. When you use LWATMGR as a TSO command only, it need only reside in the AUTHCMD table. Either LLWA or LWATMGR, whichever one you use, will have to be in the AUTHCMD list, from the beginning. Or else, TSUB has to be in the AUTHCMD list from the beginning. Then TSUB can be used to put LLWA or LWATMGR in the AUTHCMD list, and after that, LLWA or LWATMGR will be used, to build a completely new list, with everything you want in it. This is how you escalate your ability to do useful work for your installation. Once you authorize TSUB as a TSO command, you can get all the other commands and programs authorized. SUMMARY The four TSO authorization tables, AUTHCMD (IKJEFTE2), AUTHPGM (IKJEFTE8), AUTHTSF (IKJEFTAP), and NOTBKGND (IKJEFTNS) that your TSO session uses, are pointed to by fields in the LOGON WORK AREA (LWA) which is unique to your TSO session. The LWA is created at LOGON time. Once we authorize one program, for example the TSUB program, to modify an existing table, we can get all our other programs authorized, to our heart's desire. This is done either by modifying one of the auth tables with either TSUB or LWATMGR, or by building completely new tables using either the programs LLWA or LWATMGR. The TSUB program can also modify any of the existing tables' characteristics, as reflected by fields in the LWA which refer to that table. These may be either the table's length (whether it has a length or not, and if it has, what the length is). Or, it may be whether the table is marked as coming from STEPLIB or not. If the table is not marked as coming from STEPLIB, then it is at risk of being overlaid by a future PARMLIB UPDATE(xx) command or a SET IKJTSO=xx operator command. The LLWA and LWATMGR programs can be used to create a completely new auth table. The LWATEDIT ISPF interface to the LWATMGR program allows you to ISPF EDIT your existing table entries, SAVE the EDIT, and build a completely new table from the EDIT. This is an extremely amazing capability, which I believe, never existed before.