8-CHARACTER TSO USERIDS IN Z/OS 2.3 (c) Copyright 2019 by Sam Golob. All rights reserved. THE SOURCE OF THE PROBLEM TSO userids, since "time immemorial", have been limited to 7 characters in length. In z/OS 2.3, IBM made (quite drastic) changes to TSO, to allow the use of 8-character TSO userids. Today we're going to talk about why, and how, this change was made. First, of course, we have to talk about some history. It seems odd that a userid should have been limited to 7 characters, when the lengths of most dataset name segments are 8 characters, and the names of pds members are also 8 characters long. It looks weird on the surface. So how did this happen? TSO (Time Sharing Option) in MVS, OS/390, and z/OS is quite ancient, having (I think) gotten its start in the late 1960's in MVT, or at the very latest, in the early 1970's. For all this time, the userids for users to LOGON to TSO have been restricted to 7 characters long. The reason for this is because the definition of a user account to TSO was traditionally done by means of the SYS1.UADS (User Attribute Data Set) partitioned dataset. And the programming around the UADS members is weird, and very "direct access like". Each TSO user LOGON (before definition of users by RACF, ACF2, or Top Secret, etc.) had to be defined by a member, or multiple members, of the SYS1.UADS pds. Creation of a TSO userid (and its maintenance), when based on SYS1.UADS, is done by the TSO ACCOUNT command. You can still look up how the ACCOUNT command works, because it has a HELP member in SYS1.HELP, and it is still supported by IBM. Sometimes, to define one TSO userid, you had to create more than one member of the SYS1.UADS pds. The reason for this (which shows how really ancient TSO is) is that each pds member in UADS needed to be EXACTLY ONE FULL BLOCK of SYS1.UADS, and it could not contain a partial block, or more than one block. So the definition of a TSO userid depended on the block size of the SYS1.UADS dataset. If the block size of SYS1.UADS was 800 bytes, or 10 80-byte card images, then the pds member(s) defining a TSO user were fixed in size to 800 bytes. But if more information was necessary in defining the user (for example if the user had 10 possible LOGON PROCs or multiple account numbers or multiple passwords), and the information overflowed 800 bytes, then to define the user, you would have to create more than one pds member. Therefore (for example) in defining userid USERXX, you might have pds members USERXX0, USERXX1, and USERXX2, which were necessary to hold the required information about the user. Since IBM was requiring an extra character in a SYS1.UADS pds member name, and member names in the SYS1.UADS pds were limited to 8 characters, as they always are, the actual id had to be limited to one character less, or to 7 characters. That's the history, folks, in a nutshell. Ever since then, TSO userids have been limited to 7 characters maximum, until now (maybe 50 years after TSO was created). Amazing. But true. And it was a thorn in IBM's side. THE CHANGE IS QUITE DRASTIC The developer who made most of these new changes to TSO for 8-character TSO ids, told me that this was one of the largest single changes that ever had to be made to the MVS (z/OS etc.) operating systems. We can understand this on the surface, because there was a lot of IBM code to change. You can comprehend the situation, because from time immemorial (from the beginning of TSO), it was assumed by IBM developers that the way to determine a TSO user's id, was to look at the PSCBUSER field, which just happens to be 7 characters long, and not expandable. This occurrence must have happened hundreds of times within IBM internal code. And every single instance of this practice, now had to be modified and fixed. (Same with the UPTPREFX field, which is also 7 characters, and not expandable. All IBM code which fills in the prefix in a dataset name, has to be fixed as well.) This was so great a change that it could not go in transparently, but it needed a switch, to tell the system whether it was in, or not in. This switch is located at +6 into the TSVT (TSO Vector Table) control block that is described by macro IKJTSVT. In pre-2.3 systems, the switch was a reserved field, and it had a value of X'00'. In a 2.3 or later system, the value of the switch would depend. If 8-character userid support was turned on, the value of the switch would be X'08'. And if 8-character userid support is turned off, then the value of the switch would be X'07'. In any case, X'00' says that the support is off. There is a mirror field in the TPVT at X'4D' into the TPVT control block, but I don't think that that is the actual switch. It is just an indicator to show how the real switch (TSVT+6) is set. How is this relevant to us, as systems programmers and (sometime) software developers? The point is that some of the places where your TSO userid shows up in the system, are 7-byte fields, and the way a program will find out what your userid is, will have to change. Some of the classic methods of programmatic discovery of userids have gone out the window, and they absolutely must to be modified. Of course, if you're running z/OS 2.3 (or later) and you don't turn the switch (for 8-character id support) on, then you're pretty safe with the old programs (for now). But one never knows whether IBM, a few releases later, will "turn on the switch permanently" (like they've done just now in 2.4 with userkey common storage--there's no switch anymore for that). And the bottom line points very strongly to the fact that everybody will eventually have to change and adjust to the presence of 8-character TSO userids. I don't foresee any escape from that. So our user-written programs will have to change. CONTROL BLOCKS THAT HAD TO BE CHANGED As proprietor of the CBT Tape collection of utilities (www.cbttape.org), I knew that many TSO commands find out the userid of the invoker, using the 7-byte PSCBUSER field, and other TSO commands find out the dataset prefix under TSO, using the 7-byte UPTPREFX field. Every one of these programs needs to be adapted to the 8-character id change. Besides that, my "commercial" product dealing with the Broadcast Dataset (aka SYS1.BRODCAST) also might be impacted by the 8-character id changeover. Therefore I was extremely interested in what was happening. I had to find out the details. I had some help from IBM, using my "developer" status with them, and having signed a non-disclosure agreement. One of the first things that I did, when I found out about this change, was to try and find out where in a modern z/OS system, your TSO userid is represented--in what control blocks. I came up (so far) with 15 different control blocks where your TSO userid shows up. To actually show them, I wrote a TSO command called ALLIDS, which displays all of these control block locations containing your userid. Output from the ALLIDS display is shown in Figures 1 and 2. You can obtain the source code for ALLIDS from CBT Tape File 731. The most important places where a program is looking for a TSO id, and which must change, are the PSCBUSER field (which many programs use to identify a userid), the UPTPREFX field (which determines the TSO prefix), and the userid field at +X'49' in the LWA (Logon Work Area). These fields have always been 7 characters long, and they are very heavily used by programs. New fields have had to be created for these areas, when the userid is 8 characters long. The contents of the old fields (if the userid is 8-characters) varies by which control block, but in the 8-character case, the contents of the 7-character field is always invalid, and is therefore useless for its original purpose. For example (see Figure 2), if the TSO userid has 8-characters, then the old PSCBUSER and UPTPREFX fields are artificially set to the string '>7BYTES', and the old length fields are set to X'07' (bytes). Meanwhile, the new userid field contains the full 8-byte userid, and there is a new length field, which contains the quantity X'08'. In contrast, in the LWA, the old userid field at X'49' is set to 7 blanks, and the old length field at X'48' is set to X'08'. There is no "new length" field in the LWA, but there is a new 8-byte userid field at X'1DC' which contains the full-length userid. All of this means that many programs have to be changed. Many of the other places where your userid is found in the system have already been set to 8 bytes in length. For example, RACF has always kept the userid (in the ACEEUSRI field) as 8 bytes, so there was no need to fix anything up, programmatically, there. TRYING TO PROGRAM THESE CHANGES IN A Z/OS 2.2 SYSTEM I had somewhat of a head start in trying to fix any programs that were under my control. Since I now have the status of a "developer", and I signed a non-disclosure agreement with IBM, I was able to find out SOME of the specifications of the 8-character userid change before General Availability of z/OS 2.3, and I was able to talk to the developer. Nevertheless, there were several obstacles. First, before General Availability, the system is still "plastic", and even the developers aren't sure which new fields and old fields should contain what. I had that problem with the old LWA userid field, because I didn't know what IBM would put there when the old field wasn't being used. The second problem (much bigger) was that even though I knew the specs, I didn't have a z/OS 2.3 system to work on. All my 8-character userid changes wouldn't have any real effect. So what did I do? I had to write some programs. These programs constituted what I called "my 8-character conversion toolkit". The first program I wrote was the program to throw the switch, and I called it TSVT8. TSVT8 is a TSO command that has a choice of three parameters, 0, 7, or 8. This sets the TSVT+6 field to either X'00', X'07', or X'08'. We have to have this program available first, because if the switch can't be turned on, you can't get anywhere else. I found out later, that the value in TSVT+6 is mirrored in TPVT+X'4D', but TSVT+6 is the real switch and the other field is just there as an indicator to show how the TSVT+6 switch is set. When I found out about TPVT+X'4D', I fixed the TSVT8 program to correspondingly change that field as well. Even after 8-character support in z/OS 2.3 is in effect, the TSVT8 command is still useful, because now you can feel its real effect when it works. So the programming was not in vain. I have a lasting tool which I can use for testing. TSVT8 source can be found on CBT File 731. Then, I had to write a program to make an 8-character TSO prefix. Why? In z/OS 2.2, or in a 2.3 system with the 8-character support turned off, the TSO PROFILE command will not create an 8-character TSO prefix. Since I had the specs, I wrote the CPFX program to modify the proper fields in the UPT control block and to correctly create an 8-character prefix, at least in the UPT control block itself. On a 2.2 system it wouldn't actually work, but at least the control block structure was there. Even now, with 8-character support fully in place, the CPFX program is also useful. And it can be used instead of the PROFILE PREFIX command whenever I want to use it. The source code for CPFX can also be found on CBT File 731. To see what I was doing, I needed to modify the LPSCB program from CBT File 300, which shows all the fields in the PSCB, UPT, and ECT TSO control blocks. I had to make LPSCB show the new PSCBUID8 and PSCBU8L (userid and length) fields, as well as the UPTPREF8 (prefix) and UPTPRF8L (prefix length) fields. See Figure 3 for sample LPSCB output. To show all of the three control blocks, you have to invoke LPSCB ALL. I followed this up with programs to change the userid in various places according to the new rules, and I tested those programs using the ALLIDS TSO command which displayed the results. These programs enabled me to simulate the effect of the 8-character userids, even on a 2.2 system where they weren't applicable. Then I was able to modify existing programs which depended on the old fields, so they would correctly respond to 8-character ids which filled the new control block fields, as well. I'm happy to report that the effort was successful. Of course, once z/OS 2.3 came out, I tested all these programs there as well, as well as all of the TSO commands and utility programs which needed to be modified to accommodate 8-character TSO ids. For illustrative purposes, to see how a program was converted from getting your userid from just the PSCBUSER field, to accommodating an 8-character userid, I've included a very short Assembler program which shows you the point. See Figure 4, and you should get the idea. So, other than bringing you illustrations of some of the programs and TSO command outputs mentioned here, we have come to the end of the discussion for now. We wish all of you the best of everything, and we hope to see you again in this space, the next time. ILLUSTRATIONS Figure 1. Output of the ALLIDS command for a TSO userid of 7 characters or less. This was run on a z/OS 2.3 system where the new fields are filled in. On an older system, the new fields are zeros. ALLIDS - SHOW TSO USERID OCCURRENCES - V1.3 ------ ---- --- ------ ----------- ---- cntl old len new len block field gth field gth ---- ----- -- ----- -- My PSCB Userid is IBMUSER 07 IBMUSER 07 My UPT Prefix is IBMUSER 07 IBMUSER 07 My JCT Userid is IBMUSER My JMR Userid is IBMUSER My TIOT Userid is IBMUSER My ASCB Userid is IBMUSER My ASXB Userid is IBMUSER My ACEE Userid is IBMUSER 07 My LWA Userid is IBMUSER 07 IBMUSER My TSBX Userid is IBMUSER My CSCB Userid is IBMUSER My CSCX Userid is IBMUSER My OUCB Userid is IBMUSER My JSAB Userid is IBMUSER Jobname IBMUSER My CAUB Userid is IBMUSER 8-CHARACTER USERID SUPPORT IS: ON Figure 2. Output of the ALLIDS command for a TSO userid of 8 characters. PSCB, UPT, and LWA needed new fields for the userid (and length). Note the values that are placed in the old fields. ALLIDS - SHOW TSO USERID OCCURRENCES - V1.3 ------ ---- --- ------ ----------- ---- cntl old len new len block field gth field gth ---- ----- -- ----- -- My PSCB Userid is >7BYTES 07 IBMUSERC 08 My UPT Prefix is >7BYTES 07 IBMUSERC 08 My JCT Userid is IBMUSERC My JMR Userid is IBMUSERC My TIOT Userid is IBMUSERC My ASCB Userid is IBMUSERC My ASXB Userid is IBMUSERC My ACEE Userid is IBMUSERC 08 My LWA Userid is 08 IBMUSERC My TSBX Userid is IBMUSERC My CSCB Userid is IBMUSERC My CSCX Userid is IBMUSERC My OUCB Userid is IBMUSERC My JSAB Userid is IBMUSERC Jobname IBMUSERC My CAUB Userid is IBMUSERC 8-CHARACTER USERID SUPPORT IS: ON Figure 3. Full output of the LPSCB TSO command, using its "ALL" parameter, and showing 8-character userid support. 8-character Userid Support is: ON 00006F80 PSCB Address +0 PSCBUSER C9C2D4E4E2C5D9 IBMUSER +7 PSCBUSRL 07 +8 PSCBGPNM E2E8E2C1D3D3C4C1 SYSALLDA +10 PSCBATR1 E100 OPER ACCT JCL CONS +12 PSCBATR2 0000 +14 PSCBLTIM D73AD3E63A5CF843 2019.360 10:23.29.588687 +1C PSCBSUBH 00 +1D PSCBSUBC 00 +1E PSCBSUBM 00 +1F PSCBSOUT 00 +20 PSCBU8L 07 +21 PSCBDRBA 00006C +24 RESERVED 00000000 +28 PSCBDEST 0000000000000000 +30 PSCBRLGB 00007EF8 +34 PSCBUPT 00008FC8 +38 PSCBUPTL 0038 +3A PSCBCHAR 00 +3B PSCBLINE 00 +3C PSCBRSZ 000F4240 +40 PSCBU 0000000000000000 +48 PSCBEXWD +48 PSCBEXK 00000000 +4C PSCBEXL 00000004 +50 PSCBEXD 00000000 +54 PSCBUID8 C9C2D4E4E2C5D940 IBMUSER +5C RESERVED 00000000000000000000000000000000 +6C End-PSCB 00008FC8 UPT from PSCB 00008FC8 UPT from CPPL +0 UPTLEN 0038 +2 UPTUSER C5E2C4C1E84040000000 +C UPTSWS 21 +D UPTCDEL 00 +E UPTLDEL 00 +F UPTVERS 01 +10 UPTPREFX C9C2D4E4E2C5D9 IBMUSER +17 UPTPREFL 07 +18 UPTPLANG C5D5E4 ENU +1B UPTSLANG C5D5E4 ENU +1E UPTLNGFL 0000 +20 UPTSWS2 00 +21 UPTPREF8 C9C2D4E4E2C5D940 IBMUSER +29 UPTPRF8L 07 +2A RESERVED 0000000000000000000000000000 +38 End-UPT 0000BB88 ECT Address +0 ECTRCDF 00 +1 ECTRTCD 000000 +4 ECTIOWA 009A4F10 +8 ECTMSGF 80 +9 ECTSMSG 000000 +C ECTPCMD D3D7E2C3C2404040 LPSCB +14 ECTSCMD 4040404040404040 +1C ECTSWS 00 +1D ECTDDNUM 000000 +20 ECTUSER 00000000 +24 ECTBKPB 00000000 +28 ECTSWS2 8C +29 ECTSWS22 00 +2A RESERVED 0000 +2C ECTHELP 009BDD6C +30 ECTENVBK 0C883C90 +34 ECTEXTPR 0C71CF80 +38 End-ECT Figure 4. An assembler program that used to display your own userid with PSCBUSER. Now it takes the 8-character fields into account. The reason that the displacements were used instead of macro fields from the IKJPSCB macro, was because the 2.3 macros weren't yet available, and this had to be assembled on a 2.2 system. * TSO COMMAND PROCESSOR TO DISPLAY THE USERID OF THE INVOKER. YREGS MYID CSECT STM R14,R12,12(R13) SAVE CALLER'S REGISTERS LR R12,R15 LOAD ENTRY POINT INTO BASE REGISTER USING MYID,R12 TELL THE ASSEMBLER R12 IS BASE LR R15,R13 SAVE CALLER'S SAVE ADDRESS LA R13,SAVE GET OUR SAVEAREA ADDRESS ST R15,SAVE+4 STORE HIS SAVEAREA INTO MINE + 4 ST R13,8(,R15) STORE MINE INTO HIS SAVEAREA + 8 RUNCHAIN L R3,16 POINT TO CVT. L R3,0(,R3) POINT TO TCB/ASCB WORDS L R3,4(,R3) POINT TO TCB. L R3,X'B4'(,R3) POINT TO JSCB. L R3,X'108'(,R3) POINT TO PSCB. MVC MSGLINE+13(7),0(R3) MOVE USERID IN FROM PSCBUSER CLC MSGLINE+13(7),=C'>7BYTES' IS THE NEW FIELD NECESSARY? BNE SEVENCHR NOT 8 CHARS, USE PSCBUSER MVC MSGLINE+13(8),X'54'(R3) MOVE USERID FROM PSCBUID8 SEVENCHR DS 0H TPUT MSGLINE,L'MSGLINE DISPLAY THE MESSAGE ON THE TUBE RETURN DS 0H RETURN TO CALLER L R13,SAVE+4 RELOAD CALLER'S SAVEAREA POINTER LM R14,R12,12(R13) RELOAD REGISTERS BR R14 RETURN TO CALLER SAVE DC 18F'0' MY SAVE AREA MSGLINE DC C'MY USERID IS ' LINE FOR MESSAGE LTORG END