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!