MVS TOOLS AND TRICKS OF THE TRADE June 1997 Sam Golob MVS Systems Programmer P.O. Box 906 Tallman, New York 10982 Sam Golob is a Senior Systems Programmer. TIMING OUT Probably, most of you have not always had the System Programmer's "silver spoon" in your mouths for your entire career in data processing. In other words, you probably have not had "PC Status" (Privileged Character Status). One of the features of PC Status is that your own TSO Session does not "time out" and get logged off with a System 522 abend, after a designated number of minutes of inactivity. You can leave the office and stay logged on, all day. From the administrator's point of view, this privilege of "not timing out" is undesirable for the "average" TSO user to have. Therefore, in most installations, such power is not given to them. Why is it better that an average TSO user should not time out? First, any logged-on TSO user allocates a certain number of datasets, and ties them up with a shared enqueue, so no one else can get an exclusive enqueue to these datasets if that is needed. Second, even a swapped-out TSO user is tying up an address space and some system resources; this user might even stop a new user from logging on, if the MAXUSERS number (of logged-on users) is being approached. Third, if that TSO session is being hung while no one skilled is around, it would be very difficult to free the session. An automatic session time-out would be helpful. There are probably several other reasons you can think of. For most TSO users, a forced time-out after a period of inactivity would be very desirable. Of course for us PC's, none of these reasons apply, since all of us can fix any problem we might cause. Yeah, right. Anyway, for the rest of this article, I'd like to talk about this idea of timing out. X22-TYPE ABENDS. Where does the subject start? I'd say it starts with a talk about purposely killing an address space. IBM has graciously provided us with several means of "chopping off" jobs, started tasks, and TSO sessions in the middle of their activity. We've all heard of cancelling or forcing jobs and TSO sessions. When a job produces excessive output, we might want to chop it off before it floods our printing resources or JES spool space. CPU time excession abends have occasionally been part of our experience. Sometimes, we run a big SMP job in the wrong class, and it exceeds that class' allowable CPU time, getting cut short in the middle. All of these "cutoffs" are related by the fact that the system abends which result, nearly all end with the characters '22'. What are some of these System X22-type abends. A system abend 122 occurs when the operator cancelled a job, requesting a dump. A system 222 is an operator cancel, without a dump. This is very common. A system 322 is a CPU time excession cancel of a job. A system 422 is new, and is similar to a 222, but it is done by an Open Systems MVS application. A system 522 results from excession of the Job Wait Time (JWT) parameter in the SMF parms in SYS1.PARMLIB. This is the "timing out" abend we are considering today. A system 622 abend happens when something goes wrong with TSO, or your session gets disconnected from the terminal and the reconnect limit time passes. A system 722 abend happens if the job puts out a lot of output, exceeding the JES or JOB card output limits, and the OUTLIM parameter was not coded in the job's JCL to override these limits. A system 822 abend happens when the region requsted for a job step cannot be obtained. A system 922 abend occurs if the INITIATOR is now in control of a job, before or after the job step has taken place, and an ABEND or other interruption occurs. A system A22 abend occurs after a FORCE operator command was issued, and the address space was "burned", or chopped off forcibly, no matter what it had been doing before. We have faced nearly all of these abends in our careers. Sometimes we are happy when one occurs. Other times, we can be very disappointed. Today we'll talk about some tricks we can do, to avoid the situations in which we are disappointed. Please remember that, by and large, we are PC's (Privileged Characters) in our profession. But sometimes, the management in a shop might even think that we PC's have to be restricted. Nevertheless, we still are the system doctors, and we still need our tools to do the job that this same management asks from us. It's like what the parent demanded of the school bus driver: "Be careful and drive slowly, but get my child to school quickly." The bus driver still has to get that child to school, safely, despite the parent's protests. And we have to do the job that our management requires of us, safely, but quickly too, without unnecessary hassles and interruptions. So if management does not allow us to stop our sessions from timing out with a S522 abend, and the job requires that we have to run several parallel sessions on one or more systems for an extended period of time, without their timing out, what advice do we have? How can we circumvent our management's restrictions and still do the job that they ask of us? This is today's subject. WAYS OF AVOIDING SYSTEM 522 ABENDS. A system 522 abend is caused, often, by a TSO session's inactivity. How long it takes to trigger the time-out depends on the setting of the Job Wait Time (JWT) parameter in the SMFPRMxx member of SYS1.PARMLIB (in minutes). All non-altered TSO sessions will time out in this number of minutes. How can we override this time-out in our own TSO session, and not affect the average TSO user? One way to avoid the time-out is to have your own TSO logon procedure in a PROC library. This would also require that SYS1.UADS or the security package (RACF, ACF2, Top Secret, etc.) be set up so that the use of your own procedure would be allowed, when your id is used to logon to TSO. Your own logon procedure, which in effect, is JCL, can be then coded with TIME=1440 or TIME=NOLIMIT in the EXEC card which invokes the terminal monitor program (usually IKJEFT01 or ADFMDF03). This will override a short JWT setting and will keep your own TSO session "on the air". Some installations do not allow this, although nowadays it is unusual to find such "backward" places. These installations, while recognizing that systems programmers have different requirements in their TSO sessions than do application programmers, will allow one logon PROC for application programmers and another one (or several) for systems programmers. They will not allow, however, a systems programmer to have a private logon PROC. And they will also not allow TIME=1440 or TIME=NOLIMIT to be coded in any of these PROCs. In many places, the systems programmers are not the security administrators. What can we do now? A common solution is to have (or write) a program which runs continuously in a TSO session if nothing else is running, and which has a timer built in. For example, the timer will pop every five minutes. When the timer pops, the program triggers some small TSO activity, to fool the session into thinking that the session is not inactive. Therefore, the session will never time out. If your installation sufficiently recognizes the importance of certain users not timing out, there is another possible approach. This is via the SMF exit IEFUTL, which can be used to control the effect of Job Wait Time on jobs, started tasks, or TSO sessions. An interesting and general solution that can be implemented with management approval, operates through RACF, or whatever security package you have. I'll show an example using RACF. You define an entity to RACF in the FACILITY class called TSOWAIT. Those users who will not time out, are given READ access to this entity. Then an IEFUTL exit can be coded, which does a RACROUTE call for the TSO user, to ask if READ access is granted to this entity, and if so, an infinite time extension is given to the TSO session. Management administers this solution officially, through the security administrators, and everything is above board. This IEFUTL exit can be quite easily coded. An example can be found on File 245 of the CBT MVS Utilities Tape, a huge, independently produced tape of MVS goodies available through NaSPA. The IEFUTL exit found there, can be simplified even further. Besides the RACROUTE call, there is very little to it, just either a time extension or a bypass of the time extension, based on the result of the RACROUTE call. If you have other IEFUTL exits in use at your installation, don't worry. SMF exits can be very easily piggybacked, so they all run in succession. Another solution which is very clever, can be found on File 183 of the CBT MVS Tape. This solution requires that ISPF be running in your TSO session. To implement this solution judiciously, not including too many people in the timeout exemption, you should have a restricted or a private load library to put into the ISPLLIB concatenation. This can be done dynamically in a CLIST using the ALLOCATE TSO command, even if your TSO session is using a public logon proc. Just get out of ISPF, FREE FILE(ISPLLIB), and issue an ALLOCATE command with the proper ISPLLIB libraries concatenated in the proper order. That can all be done in one CLIST. Finally, assemble and linkedit the source code for the ISPTASK module on File 183, non-reentrant and non-reusable, into this private library. With ISPF running, your TSO session will not time out during weekdays, until 7 PM on Friday evening. Examine the source code of the ISPTASK module on File 183 to see how this works. You can alter the source code if you have different timeout exemption requirements. I'll explain it better. The user version of the ISPTASK module from File 183, is designed to front-end IBM's ISPTASK module, which is either in the link list, or in LPA. IBM's ISPTASK module is reentrant. This user front-end is not. The user ISPTASK, as coded, works as follows: First, upon getting control, it pre-loads a bunch of ISPF modules into the Job Pack Queue for more efficient operation if these modules were not put in LPALIB, but were running from the link list. This is not important for our purpose, but I'm just mentioning it for completeness. Afterwards, our user ISPTASK determines what day of the week it is (Monday through Friday) and conditionally passes control to the STIMER routine that jogs the TSO session into "activity" every 10 minutes. It only does this from Monday at 12 midnight until Friday at 7 PM. Finally, it does a lot of searching through TCB's, looking for IBM's actual copy of ISPTASK, avoiding ISPLLIB and STEPLIB, looking for a re-entrant module. Upon finding the proper copy of ISPTASK, it XCTL's to it. Meanwhile, the STIMER keeps popping itself every 10 minutes, and the TSO session does not time out, because of this "activity". I hope today's discussion has been interesting and helpful to you. Maybe you yourselves can find other ways to do this job. I've always thought that systems programmers were a clever bunch. Good luck, and keep those timers popping. See you next month.