MVS TOOLS AND TRICKS OF THE TRADE October 1995 Sam Golob MVS Systems Programmer sbgolob@cbttape.org Sam Golob is a Senior Systems Programmer WORKING WITH TSO - PART I Most of us systems programmers do our work in interactive terminal sessions. I have yet to find any one of us in this age, who still operates by running a succession of batch programs only. If we indeed worked without a terminal, we'd need to have a means of setting up our JCL, and none of us seems to punch cards any more. Thus, to my knowledge, all of us MVS systems programmers have to work with TSO. There are some shops who don't use ISPF under TSO, but use Wylbur or Roscoe (or maybe even FSE) instead. However, I feel fairly safe in saying that for almost all cases, TSO, which is a part of the operating system, is also a part of our working lives. For this discussion, I want to separate those parts of our TSO work which specifically belong to TSO, from those other parts which more rightfully belong to ISPF/PDF. More specifically, I'd like to begin with a talk about TSO command processors, and then branch out from there. I find it hard to believe that there are MVS systems programmers who don't know the difference between a TSO command processor, a CLIST, a REXX exec, an ISPF dialog that is run from panels, and an ISPF dialog that is driven by a program. But I do get the feeling that the working details and scope of each type of TSO utility are not sufficiently well known by most people. And I am certain that we all have plenty to learn, concerning the awesome power available through utilities belonging in each of these five categories. SOME MISCELLANY. It is worth spending a short time discussing the distinction between TSO and TSO/E. TSO is the terminal monitor interface which comes with the MVS operating system. Base TSO has not been enhanced much in many years, but has been brought to compatibility with the rest of MVS, at least to the ESA Release 3 level. Almost all real enhancements to TSO have been added to the separately billed replacement known as TSO/E. The TSO-VTAM interface has been vastly improved in TSO/E, as have many of the basically supplied TSO commands, such as the ALLOCATE command. I believe that from the ESA Release 4 level, TSO/E is mandatory, and you can't order free base TSO any more. Our convention for the rest of this series, will be to use the term TSO to refer to both base TSO and TSO/E, unless we need to clearly make a distinction. Next, we'll make mention of TSO-in-Batch. It is possible to create a TSO-like environment in a background job by executing the terminal monitor program IKJEFT01 in a batch job. TSO commands are entered through the SYSTSIN ddname, and output is obtained through the SYSTSPRT ddname. See Figure 1 for an example of a TSO-in-Batch job which executes a TSO command. We must carefully note at this point, that in a batch job, a TSO command can only create printed output if the PUTLINE output interface is used by the command, and not if the simpler TPUT interface was used. I've had the jolting experience early in my career, that a TSO command did not print any output at all when I ran it under TSO-in-Batch. That command had only used the TPUT macro for its output, and not PUTLINE. It is also appropriate to mention the free Automated Operations package from File 403 of the CBT MVS Utilities Tape which is called TSSO. As part of its design, the MVS subsystem TSSO creates a TSO-like environment, and it runs with almost the same JCL as a TSO-in-Batch job. The only difference is in the program being executed, and the execution parms. TSSO is a very interesting product and is worth your time to study and learn from. The purpose of TSSO, as conceived in the original package by its author Bill Godfrey, was to enable an MVS console operator to enter TSO commands at the console. Bill's version of TSSO is still available unchanged on the CBT Tape, on File 306. TSSO was later expanded by Bellcore to include both Automated Operations and Console Security capabilities, long before these features became a part of the MVS scene. As for the CBT MVS Tape, it is free software, independently produced, and copies are orderable from the NaSPA office. TSO COMMAND PROCESSORS. A TSO Command Processor is a program which accepts input and parameters from a terminal, and which performs actions. When ENTER is pressed and a command is executed at the terminal, its associated TSO Command Processor program is attached by the Terminal Monitor Program (TMP) that manages the TSO session. Although a TSO command which executes a TSO Command Processor looks different from a batch program, it is in fact not much different at all. The range of power in a TSO command is enormous. All of the capability of an enabled system-level program can potentially be brought to bear in a TSO Command Processor program. Many "famous" products that run under TSO are in fact TSO Command Processors, or are started by Command Processors. For example, ISPF itself is started as a TSO Command Processor. The enormously powerful PdsTools vendor product, as well as its distant ancestor the PDS command from File 182 of the CBT MVS Tape are TSO Command Processors. Each of these TSO Command Processors can perform hundreds, if not thousands, of separate functions. IBM-supplied commands in SYS1.CMDLIB, such as TEST, LISTC, LISTD, or the RACF commands, are all TSO Command Processors. Simple and complicated, TSO Command Processors are used by all of us, very frequently during a day's work. At this point, I'd like to say a word about the special execution of some of the programs designed to run under TSO. From XA 2.2.0 onward, you can create a list of special programs in the SYS1.PARMLIB member IKJTSOxx. This list of programs has actually been part of TSO from time immemorial, but it was formerly kept in a different place. There are four categories of such programs. One is a list of all APF Authorized TSO Command Processors which can be run. Another is a list of all called programs (not TSO Command Processors) which can be run APF Authorized under your TSO session. A third list contains authorized commands that can be run from non-authorized programs under TSO. And finally the fourth list contains TSO Command Processors which cannot be run in the background, that is, they will not be allowed to work under the TSO-in-Batch facility. In former releases of TSO, these lists were kept as tables in four separate CSECTs. The APF Authorized TSO commands were listed in CSECT IKJEFTE2. The called programs which could be run APF Authorized under TSO were listed in CSECT IKJEFTE8. The list of authorized commands that could be run by non-authorized commands is in CSECT IKJEFTAP. And finally, the list of TSO Command Processors not allowed to run in the background, is in CSECT IKJEFTNS. Under very old releases of TSO, these CSECTs were part of the main terminal monitor program IKJEFT02. Later (and currently) these CSECTs have been separated out into their own load module called IKJTABLS. Normally, the active SYS1.PARMLIB member IKJTSOxx overrides the load module IKJTABLS. But if IKJTABLS is in an authorized STEPLIB in your TSO session, IKJTABLS overrides the active PARMLIB member IKJTSOxx. This is a very useful fact for systems programmers who can use their own LOGON procedures. They can set up a private environment completely separate from the public one. For more help in this area, see Files 185 and 186 of the CBT MVS Tape if you have a fairly recent version. Initialization of the effective set of program tables normally takes place at LOGON time, but with the newest releases of TSO/E, the globally effective IKJTSOxx PARMLIB member can be changed using the TSO PARMLIB command. STRUCTURE OF A TSO COMMAND PROCESSOR. Now we will talk about how a TSO Command Processor is structured, at least in Assembler Language. For detailed information, the "TSO/E Customization" and "TSO/E Programming" manuals are very helpful. When a TSO command is entered at the terminal, the TSO Terminal Monitor Program (or TMP) attaches the appropriate TSO command processor program, whose load module has the same name as the command. At this point, Register 1 is made to point to a control block called the CPPL or Command Processor Parameter List. The CPPL contains four fullwords, each containing an address pointing to somewhere else. In order, the four addresses point to: the Command Buffer, the UPT (User Profile Table), the PSCB (Protected Step Control Block) and the ECT (Environment Control Table). These control blocks contain user-specific information necessary for the Terminal Monitor Program to authorize and process your request for action. Immediately after your TSO command processor gets control, it must save the address of the CPPL, since Register 1 gets reused by many system macros. You usually save the pointer in another register (using the LR - Load Register instruction) or in a fullword of storage (using the ST - Store instruction) at the beginning of the program. For a reentrant program, the "LR" method must be used initially, because the GETMAIN macro which obtains dynamic storage needed by the reentrant program reuses Register 1. Now we'll conclude with some information about the Command Buffer and the other three TSO control blocks. The Command Buffer contains command input which was entered at the terminal, or in the SYSTSIN ddname file if the command was run with TSO-in-Batch. This input can be interrogated by the program. To make life easier, the actual buffer content is prefixed by two halfword binary quantities. The first quantity contains the total length of the data in the buffer, including the 4 bytes of the prefixes. The second quantity is called the offset. This is the displacement from the beginning text byte of the buffer, to where the first parameter of the command begins. With such information, our program can contain appropriate logic to evaluate the command entered. TSO also has a specially designed facility whose use is optional, called the "TSO Parser" or IKJPARS. Properly set up, IKJPARS can check the syntax of any parameters in the command. Setting up IKJPARS is a bit involved, but once you've done it, you can usually copy much "standard code" from one program to another. Detailed information about IKJPARS is found in the "TSO Programming" manual from IBM. I think the most important of the other three control blocks is the PSCB, or Protected Step Control Block. Settings in the PSCB heavily determine how much power your session has. One of our previous columns (October 1994) was devoted to a detailed treatment of the PSCB's power. The PSCB contains the USERID and its length, the session "attribute" flags, the logon time for the session in TOD Clock format, and some pointers to other control blocks. The PSCB is mapped by macro IKJPSCB in SYS1.MACLIB, where you can read about what else it contains. The UPT (User Profile Table) largely contains the information which is controlled by the TSO PROFILE command. The user's dataset prefix, if it has been defined, is contained in the UPT, as well as other user-specific and user-settable information. The UPT is mapped by macro IKJUPT from SYS1.MACLIB. The ECT (Environment Control Table) contains information that mostly is related to what this TSO user is doing now. One of the ECT fields is the name of the last command entered. The ECT has three bytes of binary switches that tell you a lot about the current command environment. Among these are flags to indicate whether operands (other than the command itself) exist in the command buffer, whether various abnormal conditions have occurred, or whether this command is running from a terminal or in the background (TSO-in-Batch). The ECT is mapped by macro IKJECT in SYS1.MACLIB, and from the macro, you can read all about it. We have come to the end of our time for this issue, and we hope to continue further on this same topic next time. I trust that this basic information will enhance your knowledge in dealing with TSO. Good luck. * * * * * * * * * * * * * * * * * * * * * * * Figure 1. Layout of a TSO-in-Batch Job. Note that the actual TSO commands to be executed, are placed in a list in the SYSTSIN ddname. Only TSO commands which write their output using the PUTLINE interface (and not the TPUT interface) will show output under TSO-in-Batch. Standard IBM-supplied commands, such as the one shown, usually use the PUTLINE interface. //TSOBATJB JOB (insert your job card information here) //* - - - - Job to execute TSO-in-Batch (background) - - - - *// //STEP01 EXEC PGM=IKJEFT01,REGION=4096K,DYNAMNBR=50 //STEPLIB DD DISP=SHR,DSN=your.steplib.name //SYSPRINT DD SYSOUT=* //SYSTSPRT DD SYSOUT=* //SYSTERM DD SYSOUT=* //SYSTSIN DD * LISTC LEV(SYS1) ALL LISTC LEV(SYS2) ALL /* //