MVS TOOLS AND TRICKS OF THE TRADE NOVEMBER 2001 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 BASICS, REVISITED Some of us go back to the days when system support consisted of punching cards, and running batch jobs. Anybody who remembers that, will appreciate how important it is, to have to ability to work interactively from terminals, using IBM's TSO (Time Sharing Option). Most of us do have a very great appreciation of the value of TSO. But today I'd like to underline and reemphasize some aspects of TSO that are not so uppermost in our minds. One should not picture TSO as merely a way to submit jobs using a terminal. A TSO session actually has full access to the MVS Operating System, the same way a batch job, or a started task, has. Let me elaborate a bit. Years ago, I used to work on a DOS/VSE system part time. We had to punch cards and run batch jobs on that system, in order to do anything. Then we got an early version of ICCF (Interactive Control and Computing Facility), which was IBM's DOS/VSE terminal interface at that time. To use ICCF was a vast improvement over punching cards and reading them. But, to my knowledge, ICCF was only a better way of storing 80-byte card images, and in order to do any real work in the operating system, you still had to submit a separate batch job. True interactivity of the terminal interface, with the innards of the operating system, was not there yet. Not so TSO! Each TSO session runs in an MVS address space, and has full access to everything in the operating system, the same way a batch job has. The only restriction to that, is imposed by the security system (RACF, or whatever security package you have), and by TSO itself. I'll tell you about TSO's main security mechanism. Within TSO, there is a control block that's established for each user, called the PSCB (Protected Step Control Block). Within the PSCB are bit settings to establish the "authority level" of that TSO user. Such properties as OPER authority (the ability to issue operator console commands from TSO), JCL authority (the ability to submit batch jobs), ACCOUNT authority (the ability to create and alter other TSO userids), and MOUNT authority (the ability to authorize a tape mount from the TSO session), are among those powers controlled by these PSCB bit settings. These controls are TSO's way of saying whether one userid is more "powerful" than another. But my point is, that a "fully empowered" TSO userid can "get anywhere" in the system. TSO does not merely store card images. The PSCB control block is created for each TSO session at LOGON time. The initial bit settings in a particular TSO user's PSCB come from one of two places: Either they are derived from settings in SYS1.UADS, or from the settings in the TSO segment of the security system's (RACF or equivalent) profile for that userid. But once the TSO session has been established and is running, the PSCB may be altered, using an authorized command. The truth is, that the PSCB settings are the ones which are used by TSO, not the RACF or UADS settings. TSO uses the PSCB as the reference point for all subsequent "TSO authority" checking, once the session has started, and does not re-refer to RACF or UADS later for the TSO-specific things. TSO only refers to RACF later, in the same way as a batch job does, to do "RACF-specific things". For example, a TSO session would consult RACF to verify whether it should have access to a dataset, and so forth. There are two free tools, available in the CBT MVS Utilities Tape collection on File 300, that give you, the system doctor, the ability to control the PSCB settings. These are called LPSCB ("look at the PSCB") and CPSCB ("change the PSCB"). Of course, CPSCB must run as an "authorized command". But LPSCB can be run by anyone, because all LPSCB does, is to read and display the contents of the PSCB control block. The IBM macro which describes the contents of the PSCB is called IKJPSCB, and on an OS/390 2.10 system, IKJPSCB can be found in SYS1.MACLIB. It is a very profitable activity to take ten minutes to look at the IKJPSCB macro, and to see the kind of things in TSO, which the PSCB controls. WHAT CLISTS AND REXX EXECS DO I mentioned before, that TSO sessions can interact with the MVS Operating System in the same way, and to the same extent, that a batch job can. This means that potentially, using TSO alone, you shouldn't have to run batch jobs. Avoiding batch jobs isn't always practical, but I have to explain how it is possible to do the task of a batch job, using only TSO. What are the parts of a batch job, as defined by its JCL? First, there's the JOB card. The TSO equivalent of the JOB card is the session itself. All the activities of that TSO session are included under its auspices, as though they were running as part of one job, which is the TSO session. Next comes the EXEC card, which denotes the execution of a particular program, and which defines the "JOB STEP". Under TSO, the user issues a "CALL" TSO command to execute a batch program, or the user issues any other TSO command, which is a load module that was specifically designed to run under TSO. The execution of such programs or commands under TSO, defines the equivalent of a job step. Finally, just as files are defined to a batch job through the use of DD cards in the JCL, so files are made known to a TSO session through the use of ALLOC and ATTRIB TSO commands, which dynamically allocate any files needed by the program to be run under the TSO session. When these files are no longer needed to do the task (job step) at hand, the FREE command is executed against them, to dynamically deallocate them from the TSO session. The truth is, that it's hard to enter all the ALLOC commands and CALL commands necessary, every time you want to run a program under TSO, the same way you would run it in batch. It would be as if you had to retype all the JCL by hand, every time you wanted to run a program in batch. Under TSO, IBM made it possible to collect the TSO commands and data, necessary to run a task, the same way you keep the JCL to run a job, in a file, and submit it. This "bundle of TSO commands" to perform a certain purpose, is called a CLIST, or "Command List". You can either execute the CLIST as a single sequential file, or you can execute it as a member of a partitioned dataset, using the EXEC TSO command. A typical CLIST that simulates a batch job, would contain ALLOC commands to allocate files, and then it would contain a CALL command, to execute a program that runs against the allocated files. The program would then run in the region of the TSO address space. Outputs would be directed to the files previously defined by the ALLOC commands in the CLIST. Finally, at the end of program execution, the CLIST would issue FREE TSO commands against the allocated files, to make them available for others to use. Actually, CLISTs have access to an interactive programming language, besides their just being vehicles to execute programs and pre-allocate the files. Using the CLIST programming language, you can execute programs conditionally under the CLIST's control, and you can insert PARM data into the programs conditionally, as well. The CLIST language, besides being suited to executing batch-type programs, is also tailored for executing TSO-specific programs, called TSO Commands. All in all, CLIST files, executing under TSO, allow for much more flexibility and conditional execution, than batch programs do, with their COND statements in the EXEC cards. But it doesn't stop there. As good as the CLIST language is, in providing programming flexibility to complicated chains of TSO command executions, its successor, the REXX language, is far better. REXX is a full-blown programming language, which can access and manipulate MVS storage, and follow control block chains, as well as conditionally calling programs to execute against files. TSO in MVS, equipped with the CLIST and REXX languages as well, provides very full capability of doing all kinds of system processing and system manipulations. Now you can see that TSO under MVS, is far more advanced than being just a system to store a stack of cards for job submission. TSO COMMANDS "TSO Commands" are programs which have been designed specifically to run in a TSO environment. TSO Commands are load modules, and they are executed by typing their actual name, during a "raw TSO session". That is, if a TSO session is in READY mode, you execute a TSO command by just typing its name, and pressing ENTER. IBM's ISPF developers have added a facility to execute TSO Commands from an ISPF command line, during an ISPF session running under TSO. Under ISPF, you type the word "TSO" on the command line, and then type the name of the TSO command afterwards. The TSO command program then uses the region available to the TSO session, and executes. The feature which distiguishes a "TSO Command" program from any other executable load module, is that it expects Register 1, upon entry, to point to a TSO control block (created by the control program of the TSO session) called the CPPL (or Command Processor Parameter List). The CPPL contains four address pointers, the first one points to the buffer containing the command itself (and possible parameters), called the Command Buffer, and the other three point to the 3 TSO control blocks, the UPT, the PSCB, and the ECT. The CPPL is mapped by the macro IKJCPPL in SYS1.MACLIB. What's important to know here, is that a TSO command program can do anything that a batch program can do, and additionally, it is more suited to running applications that interact with the terminal. A user can write TSO commands to do highly sophisticated specialized tasks, such as zapping disk storage interactively, changing the attributes of load modules, and browsing the contents of datasets in full screen mode. If you have a large collection of such specialized TSO command programs, combined with the availability of CLISTs and REXX, with their programming features, then the TSO environment then becomes a super mega-powerhouse to control and fix computer processing on the MVS system. TSO-IN-BATCH In this discussion, I have to mention why you might want to run a batch job, instead of doing all your work under TSO. The problem with running a program under TSO, is that it usually ties up your terminal while it is executing. For this reason, you would rather run a batch job, which quietly runs in its own address space, using general system resources, but it keeps your terminal free to do other work. Under certain circumstances, you can get the best of both worlds, by running TSO as a batch job, called "TSO-in-Batch". TSO-in-Batch is very suitable for running long-executing TSO commands, which don't require a lot of user interaction. Or TSO-in-Batch would come in handy if you're running a long succession of TSO commands, say several hundred of them, one after the other. You run TSO-in-Batch by setting up a pseudo-TSO environment in a batch region, using JCL. The EXEC card executes the program IKJEFT01, which is the TSO control program. DD cards that are required, are SYSTSPRT, to print (what would be) the terminal output, and SYSTSIN, to enter the TSO commands and their parms, which you want to run in the batch job. Additionally, you could specify the TSO commands to be run, in the PARM field of the EXEC card, when you're executing PGM=IKJEFT01. When running a TSO-in-Batch job, you may need to specify other DD names, such as SYSPROC, to specify a CLIST library, or SYSEXEC, to specify a pds containing REXX execs. Additionally, if the programs that you're executing require files, you allocate them using suitable DD cards in the IKJEFT01 step. To execute TSO commands out of a load library that isn't in the Link List or LPA List, you might include a STEPLIB DD card in the JCL, to point to the load library needed. FINDING OUT MORE You might want to ask where to find out more information, so you can begin to exploit the vast capabilities of TSO as a productive MVS environment. First, you can refer to the IBM CLIST and REXX books that are in the TSO collection for your release of MVS, OS/390, or z/OS. Second, you can look at the CBT MVS Utilities Tape collection, available on the Internet at the CBT Tape web site, to find and install some of the many specialized TSO commands that can be found there. Files 300, 134, 182, 183, and 296 of the CBT Tape collection are especially suitable for beginners, although advanced practitioners will gain from those files as well. Don't ignore the TSO/E Users Guide, which will tell you about basic IBM-supplied TSO commands which supply necessary services. TSO/E Customization contains valuable knowledge about how your TSO environment is set up. And finally, if you want to learn how to write TSO commands yourself, the TSO/E Programming Guide is the manual for you. I sincerely hope that all of you have gained some knowledge from this month's article, even though it looks like it's coming from a very basic viewpoint. Experienced MVS practitioners will see a lot of depth that is implicit in the subjects I've mentioned. TSO is a vast world. Use it well!