USING Z/OS SYSTEM SERVICES MACROS, OR NOT (c) Copyright 2020 by Sam Golob. All rights reserved. Today we'll talk about a situation which occurs frequently in system Assembler coding work, but which is seldom talked about explicitly. IBM helps the programmer in many instances by supplying what is termed "system services". System services make Assembler programming much easier, but they also serve other purposes. They also hide the truth of where necessary pieces of information occur in the system. How does a system services macro work? I'll show you the way IBM "talks": You want to know how to find some information? Then execute this macro, and we'll hand the information to you. The macro will dig the information out and hand it to you on a silver platter. But what does the macro itself do? Why do we need a macro? Can't we just nose into the system and get the same information for ourselves? The answer is, "not always". There are several reasons why system macros are provided by IBM, and that's what we're going to talk about now. But I'll summarize a few of them, so you see where we're going. 1. It's much easier to code a system service macro, and have the information served up to you "on a silver platter". 2. IBM wants to hide where in the system, that the information really is located. 3. A "normal user" wants to access some information, that IBM knows is located in a protected control block, and which you need APF-authorization to access. So IBM gives you a "service" so you can get it. 4. A "normal user" wants to do a normal service. However the service requires APF-authorization internally, and IBM wants to give the capability to ordinary users: Example: The TSO SEND command. 5. IBM is worried about something that ordinary users don't usually care about. For example, if you try and run a UCBSCAN to find out about DASD devices, and someone is in the middle of running a dynamic I/O reconfiguration. IBM has to worry about that, but we usually don't care. A dynamic I/O reconfiguration is a very rare occurrence, and you are usually informed when one is being run. 6. There's always the downward compatibility issue. IBM doesn't want you to have to change your programs, every time they make a change in the operating system. So they adjust the system service to the change, upward or downward. A SYSTEM SERVICES MACRO EXAMPLE IBM provides many assembler macros in SYS1.MACLIB and SYS1.MODGEN which "perform services". For example, the GTSIZE macro tells you how big your terminal is. When you issue a GTSIZE macro in an assembler program, Register 0 returns the number of rows in the terminal, and Register 1 returns the number of columns. To display these values, you just have to convert them to decimal, and EDit them into a report. The program is very simple. See Figure 1 for the entire program code. But the catch is this. The information about the number of rows and the number of columns that your terminal has, is kept in a protected control block, the TSB (Terminal Status Block) which occupies Fetch Protected storage (subpool 231). This storage can only be viewed by an APF-authorized program. The reason for that, is not the column size or the row size, but because of other information which is stored in the TSB control block, and security is required for that other information. You don't want one user nosing into private information about another user's terminal. So what did IBM do? They provided a service, which gets the required authorization via an SVC, and which pulls out this "non-classified" part of the "classified" TSB, for us to see. The "user-type" people can access the information without being authorized (because the SVC does the real work), and even though they don't tell you WHERE in the system the information was kept, they DO get you what you need. To see the content of the GTSIZE macro code, see Figure 2. Its generated code is very simple. It just loads in the required parameters and executes the SVC. I decided to dig out that exact information directly from the TSB control block itself. The code for that, is in Figure 3. Of course, my program has to be APF-authorized, but it produces the same result as the code in Figure 1. See Figures 4 for the outputs of both programs. The two outputs are identical, except for the titles, where I wanted to point out where the information came from. ANOTHER EXAMPLE OF SYSTEM SERVICES MACROS I wrote some code to handle "SYS1.BRODCAST full" conditions, and to do other functions concerning the SYS1.BRDDCAST dataset. The SYS1.BRODCAST dataset, or (since z/OS 1.3) the "Active Broadcast Dataset" holds "job completion messages" and other user messages to display to TSO users. My "free" code which I wrote for this, is on CBT File 247. Among the programs I wrote for File 247, are two programs called BCMUSADD and BCMUSDEL. I also wrote two other programs for a "commercial product" ("owned" by me), that perform the same function. These are called BDMUSADD and BDMUSDEL. Their purpose is to ADD, or DELETE, userid record slots from the SYS1.BRODCAST dataset. In other words, BCMUSADD or BDMUSADD can add a userid so SYS1.BRODCAST can keep track of its messages. And BCMUSDEL or BDMUSDEL can delete any userid record slot from the SYS1.BRODCAST dataset, and get rid of all the user messages attached to that userid. Usually these functions are performed by the IBM SYNC command, which you issue as a subcommand of the IBM ACCOUNT command. But if you want to add an extra userid, or delete one, you can use these programs that I wrote. The IBM SYNC command has the disadvantage that it deletes ALL user messages from SYS1.BRODCAST, while in the process of initializing all of the userid slots, to synchronize them either with UADS or RACF or both. What is the difference between the "BCM" and "BDM" programs? The "free" programs BCMUSADD and BCMUSDEL use an IBM system service macro called IKJIFRIF to perform their functions. The BDMUSADD and BDMUSDEL perform these functions directly, using direct I/O to the Broadcast Dataset, without the intervention of the IBM system service macro. Why change? Answer is, that IBM makes assumptions, which aren't necessarily true in a user environment. IBM assumes that you only want to change the userid configuration in the "active Broadcast Dataset". In my package, I make backup copies of the Broadcast Dataset, (which IBM assumes that you won't normally do), and I assume that I may want to manipulate the userids in the backup copy, rather than in the active dataset. That's why I "do it directly", with I/O to the Broadcast Dataset, and I don't use the system service macro from IBM. For the purpose of this article, I've copied my BDMUSADD and BDMUSDEL programs to CBT File 247, so you can see the differences in the coding. Also, see Figure 5 to compare the outputs of these two programs. In this case, doing direct I/O to the Broadcast Dataset has allowed me to manipulate any formatted Broadcast Dataset, new or old, original or backup copy. IBM's system service macro IKJIFRIF does not allow me to do this. IKJIFRIF can only manipulate the active Broadcast Dataset, and cannot reach a copy of it. OTHER USE OF IBM SYSTEM SERVICE MACROS If you look into the code of the SHOWzOS program from CBT File 492, you'll probably see one of the most extensive uses of IBM system services macros available anywhere in the public domain. SHOWzOS displays a tremendous number of "system quantities" and "system status indicators". SHOWzOS is a colossal program, originally written by the late Gilbert Saint-flour, and currently maintained by Roland Schiradin. SHOWzOS gets its results, almost entirely, from IBM system services macros. It is one of the wonders of the "public domain code" world. Have a peek. I have written my own code to display "small bits and pieces" of this stuff directly. My code works, but SHOWzOS does a monumental job using (if you really look into it) a minimum of coding. Just about all of its work is done through IBM system services macros. They shorten things, a lot. So you see that IBM system services macros are useful, most of the time. If you want to get into the nitty-gritty though, you have dig deeper, and do it yourself. I hope this has been an instructive session, and I'm looking forward to seeing you here next time. ILLUSTRATIONS Figure 1. This is the complete code of the TERMSIZE program which displays the size of your TSO terminal. The TERMSIZE program takes advantage of the IBM GTSIZE system service macro, which uses an SVC to obtain the correct quantities. See Figure 2 for the very simple GTSIZE code (the SVC does all the work). SP000 EQU 0 * TERMSIZE CSECT TERMSIZE AMODE 31 TERMSIZE RMODE 24 YREGS NOW IBM HAS DONE IT STM R14,R12,12(R13) SAVE REGISTERS USING TERMSIZE,R12 LR R12,R15 BASE REGISTER L R0,WORKDL GETMAIN RU,LV=WORKDL,SP=SP000,LOC=BELOW LR R9,R1 USING WORKD,R9 ST R9,GOTADDR LA R2,SAVE NEW SAVE AREA ST R2,8(,R13) PUT IT AWAY ST R13,SAVE+4 OLD SAVE AREA LR R13,R2 POINT R13 TO NEW SAVE AREA * GET TERMINAL SIZE GTSIZE * ST R0,ROWS STORE NUMBER OF ROWS ST R1,COLS STORE NUMBER OF COLUMNS LR R6,R0 GET NUMBER OF ROWS CVD R6,DWORK CONVERT TO PACKED MVC MESROWS,LITROWS MOVE LITERAL PART MVC MESCOLS,LITCOLS OF MESSAGES MVC NUMROWS,MASK7A EDIT MASK ED NUMROWS,DWORK+5 DISPLAY NUMBER IN MESSAGE MVI NUMROWS+6,C' ' MVC MESROWS+18(7),NUMROWS LR R6,R1 GET NUMBER OF COLUMNS CVD R6,DWORK CONVERT TO PACKED MVC NUMCOLS,MASK7A EDIT MASK ED NUMCOLS,DWORK+5 DISPLAY NUMBER IN MESSAGE MVI NUMCOLS+6,C' ' MVC MESCOLS+18(7),NUMCOLS TPUT TITLEA,L'TITLEA PUT OUT THE ENTIRE DISPLAY TPUT TITLEU,L'TITLEU TPUT MESROWS,L'MESROWS TPUT MESCOLS,L'MESCOLS * L R13,SAVE+4 LOAD OLD SAVE AREA L R9,GOTADDR POINT TO ADDRESS TO FREEMAIN FREEMAIN RU,LV=WORKDL,A=(R9),SP=SP000 DROP R9 LM R14,R12,12(R13) PUT REGISTERS BACK BR R14 RETURN TO CALLER * TITLEA DC C'* GTSIZE-BASED TERMINAL DISPLAY *' TITLEU DC C' ------------ -------- ------- ' MASK7A DC XL7'40202020212020' LITROWS DC C'THIS TERMINAL HAS ROWS' LITCOLS DC C'THIS TERMINAL HAS COLUMNS' LTORG * WORKD DSECT DS 0D SAVE DS 18F SAVE AREA GOTADDR DS F ROWS DS F COLS DS F NUMROWS DS CL7 NUMCOLS DS CL7 MESROWS DC C'THIS TERMINAL HAS ROWS' MESCOLS DC C'THIS TERMINAL HAS COLUMNS' DWORK DS D WORKDL EQU *-WORKD END Figure 2. The GTSIZE macro code. After getting rid of the conditional assembly, etc., here is what remains. All the work is done inside the SVC, which also obtains the APF-authorization necessary to extract the information from the protected TSB control block. SR R1,R1 PREPARE PARM LA R0,11 LOAD ENTRY CODE SLL R0,24 PUT ENTRY CODE IN LEFT MOST SVC 94 ISSUE SVC Figure 3. The Assembler code for the TERMSZ program, which does not use the GTSIZE system service but which obtains all the same information "by hand", directly from the place in the system where it resides. The TERMSZ program needs to be APF-authorized, because the required information is in fetch protected storage. See the inside of the code for details. TERMSZ CSECT TERMSZ AMODE 31 TERMSZ RMODE 24 YREGS NOW IBM HAS DONE IT STM R14,R12,12(R13) SAVE REGISTERS USING TERMSZ,R12 LR R12,R15 BASE REGISTER L R0,WORKDL GETMAIN RU,LV=WORKDL,SP=SP000,LOC=BELOW LR R9,R1 USING WORKD,R9 ST R9,GOTADDR LA R2,SAVE NEW SAVE AREA ST R2,8(,R13) PUT IT AWAY ST R13,SAVE+4 OLD SAVE AREA LR R13,R2 POINT R13 TO NEW SAVE AREA * ------------------------------------------------------------------- * * GET TERMINAL SIZE * GTSIZE * SEE EXPLANATION BELOW * ------------------------------------------------------------------- * * PERFORM THE FUNCTION OF THE GTSIZE MACRO, BUT GET THE * * INFORMATION DIRECTLY FROM THE TSB. UNFORTUNATELY, THE * * TSB IS IN PROTECTED STORAGE, KEY 6, SP 231. AND WE HAVE * * TO BE APF-AUTHORIZED AND GET INTO KEY 0 TO ACCESS IT. * * ------------------------------------------------------------------- * * SINCE THE GTSIZE MACRO CALLS AN SVC (94), IT CAN GET * * INTO SUPERVISOR STATE AND DO THE STORAGE FETCH, RETURNING * * TO PROBLEM STATE. SO THE "GTSIZE" VERSION OF THIS PROGRAM * * DOES NOT HAVE TO BE APF-AUTHORIZED, WHILE THIS PROGRAM HAS * * TO BE APF-AUTHORIZED. * * ------------------------------------------------------------------- * * TO CONVERT THIS PROGRAM TO THE NON-AUTHORIZED FORM, JUST * * UNCOMMENT THE GTSIZE MACRO, AND COMMENT OUT ALL THE LINES * * BELOW, IN-BETWEEN THE ARROW COMMENTS (BELOW AND ABOVE). * * ------------------------------------------------------------------- * * PERFORM THE GTSIZE MACRO FUNCTIONALITY * * ------------------------------------------------------------------- * * ----------------------------------- >>>>> BELOW <<<<< --------- * TESTAUTH FCTN=1 Are we authorized? LTR R15,R15 Test the return code. BNZ NOTAUTH Not zero, tell not authorized. L R5,X'224' POINT TO ASCB L R5,X'3C'(,R5) POINT TO TSB XR R0,R0 CLEAR R0 AND R1 AS XR R1,R1 WORK REGISTERS STM R0,R1,SAVER01 PRESERVE R0 AND R1 MODESET KEY=ZERO LM R0,R1,SAVER01 RESTORE R0 AND R1 IC R0,X'66'(,R5) RETRIEVE NUMBER OF ROWS IC R1,X'67'(,R5) RETRIEVE NUMBER OF COLUMNS STM R0,R1,SAVER01 PRESERVE R0 AND R1 MODESET KEY=NZERO LM R0,R1,SAVER01 RESTORE R0 AND R1 * ----------------------------------- >>>>> ABOVE <<<<< --------- * ST R0,ROWS STORE NUMBER OF ROWS ST R1,COLS STORE NUMBER OF COLUMNS LR R6,R0 GET NUMBER OF ROWS CVD R6,DWORK CONVERT TO PACKED MVC MESROWS,LITROWS MOVE LITERAL PART MVC MESCOLS,LITCOLS OF MESSAGES MVC NUMROWS,MASK7A EDIT MASK ED NUMROWS,DWORK+5 DISPLAY NUMBER IN MESSAGE MVI NUMROWS+6,C' ' MVC MESROWS+18(7),NUMROWS LR R6,R1 GET NUMBER OF COLUMNS CVD R6,DWORK CONVERT TO PACKED MVC NUMCOLS,MASK7A EDIT MASK ED NUMCOLS,DWORK+5 DISPLAY NUMBER IN MESSAGE MVI NUMCOLS+6,C' ' MVC MESCOLS+18(7),NUMCOLS TPUT TITLEA,L'TITLEA PUT OUT THE ENTIRE DISPLAY TPUT TITLEU,L'TITLEU TPUT MESROWS,L'MESROWS TPUT MESCOLS,L'MESCOLS * RETURN DS 0H L R13,SAVE+4 LOAD OLD SAVE AREA L R9,GOTADDR POINT TO ADDRESS TO FREEMAIN FREEMAIN RU,LV=WORKDL,A=(R9),SP=SP000 DROP R9 LM R14,R12,12(R13) PUT REGISTERS BACK BR R14 RETURN TO CALLER * NOTAUTH DS 0H TPUT AUTHMSG,L'AUTHMSG B RETURN TITLEA DC C'* TERMINAL SIZE DIRECTLY FROM TSB *' TITLEU DC C' -------- ---- -------- ---- --- ' *TITLEA DC C'* GTSIZE-BASED TERMINAL DISPLAY *' *TITLEU DC C' ------------ -------- ------- ' MASK7A DC XL7'40202020212020' LITROWS DC C'THIS TERMINAL HAS ROWS' LITCOLS DC C'THIS TERMINAL HAS COLUMNS' AUTHMSG DC C'THIS COMMAND MUST BE APF-AUTHORIZED.' LTORG * WORKD DSECT DS 0D SAVE DS 18F SAVE AREA SAVER01 DS 2F GOTADDR DS F ROWS DS F COLS DS F NUMROWS DS CL7 NUMCOLS DS CL7 MESROWS DC C'THIS TERMINAL HAS ROWS' MESCOLS DC C'THIS TERMINAL HAS COLUMNS' DWORK DS D WORKDL EQU *-WORKD END Figure 4. Here we display the outputs of (first) the GTSIZE based program TERMSIZE, which uses the system service macro GTSIZE. * GTSIZE-BASED TERMINAL DISPLAY * ------------ -------- ------- THIS TERMINAL HAS 43 ROWS THIS TERMINAL HAS 132 COLUMNS And here we display the output of the TERMSZ program which obtains the information directly from the TSB control block. You see that the outputs are identical, except that the titles are different, so you can tell the outputs apart from each other. * TERMINAL SIZE DIRECTLY FROM TSB * -------- ---- -------- ---- --- THIS TERMINAL HAS 43 ROWS THIS TERMINAL HAS 132 COLUMNS Figure 5. Outputs of the BCMUSADD and BCMUSDEL programs, which use the IBM service macro IKJIFRIF to do the work of adding or deleting userid slots in SYS1.BRODCAST. By comparing to the later display, you see that IBM does not report the location of the userid record in the Broadcast Dataset. You don't know what is really going on--just if the record was "added" or "deleted". The executed commands were: BCMUSADD XXXX BCMUSADD - VER. 1.5 - 01/15/06 - 14.45 USERID XXXX ADDED TO BRODCAST DATASET And BCMUSDEL XXXX , executed after BCMUSADD. BCMUSDEL - VER. 1.5 - 01/15/06 - 14.45 USERID XXXX AND ITS MESSAGES DELETED FROM BRODCAST DATASET Next, we display the output of commands, BDMUSADD and BDMUSDEL, which do direct I/O to the dataset allocated with DD name of BRODCAST. This can be ANY dataset that is formatted like a SYS1.BRODCAST dataset. With the direct I/O coding, we are not restricted to doing this against IBM's "Active" Broadcast Dataset in the system. BDMUSADD PROGRAM - Broadcast Master Version 1.4.0A Copyright (c) 1995-2009 Sam Golob Systems Programming LLC - All Rights Reserved USERID XXXX WAS ADDED IN RECORD 00006B SLOT 06 BDMUSDEL PROGRAM - Broadcast Master Version 1.4.0B Copyright (c) 1995-2016 Sam Golob Systems Programming LLC - All Rights Reserved --> MESSAGES DELETED FOR THE FORMER USERID XXXX . USER XXXX HAD 0 DEFERRED TSO MESSAGES * - - - - END OF MESSAGES FOR THIS USER - - - - * --> USERID XXXX HAS BEEN DELETED FROM THE BROADCAST DATASET.