MVS TOOLS AND TRICKS OF THE TRADE
                         November 1995

                                      Sam Golob
                                      MVS Systems Programmer
                                      sbgolob@cbttape.org


Sam Golob is a Senior Systems Programmer


WORKING WITH TSO - PART II

      Last time, we said a few things about TSO in general, and spoke
about TSO Command Processors in particular.  When most people talk of
TSO, they really have ISPF/PDF in mind.  While ISPF contains many
wonderful programmer productivity tools which are worth quite a few
separate studies in themselves, TSO-specific facilities and tools tend
to be neglected by the world at large.  Not enough attention is given
to your potentially powerful allies in native TSO.

      TSO Command Processors were treated briefly last time.  A TSO
Command Processor is a program (usually written in Assembler), which
is invoked from a TSO session by typing the name of its load module.
In order for the Command Processor to be executed, of course its load
library has to be accessible to your TSO session.  This usually means
that the program has to be in a TASKLIB, or in STEPLIB, or in ISPLLIB
(if you're running TSO commands from an ISPF screen), in the link
list, or in the LPA list.

      Most TSO commands accept parameters at initial execution time,
and additional "subcommands" later, during their execution.  Many TSO
Command Processors, such as IBM's ACCOUNT and TEST commands, do most
of their work long after the initial invocation, through the use of
their many subcommands.

      TSO Command Processors have enormous potential power, because
they can have access to as many system services as batch programs can.
IBM-distributed commands make only partial use of this power.  All of
the TSO commands distributed by IBM in SYS1.CMDLIB, such as ALLOCATE,
LISTC, SEND, LISTD, and the RACF commands, are really TSO Command
Processors.  TSO Command Processors are an integral part of all TSO
sessions.  Even ISPF itself is a huge TSO Command Processor.

      It is possible for users to write TSO Command Processors that
are as powerful or more powerful than IBM's distributed ones.  The
free software tape called the CBT MVS Utilities Tape, which can be
obtained through NaSPA, contains a vast collection of MVS software,
much in the form of user-written TSO commands.  A few of the many
useful TSO Command Processors on the CBT Tape are:  Fullscreen ZAP
and the REVIEW programs from File 134 (each of which was the subject
of a previous article in this column), the BLKDISK (disk space
calculator) command from File 296, the VTOC command from File 112,
and the various flavors of QUEUE commands which are JES2 spool
browsers, on Files 391 through 396.  The VSAMANAL command to analyze
VSAM space allocations automatically, is found in source code on
File 294, and is highly handy.

      The PDS command from File 182, which has hundreds of useful
system functions, was a precursor of the highly successful PdsTools
vendor product from Serena, that has thousands of functions.  Both of
these products are TSO Command Processors.  File 300 of the CBT Tape
is a collection of several hundred TSO Command Processors.  Many more
user-written TSO Command Processors are scattered throughout the rest
of the CBT Tape.  Free TSO commands give you the great advantage of
seeing their source code, so you can find out how they do their
"magic".


TSO-in-BATCH and TSSO.

      Let's spend a bit of time discussing TSO-in-Batch.  By
my observation, TSO-in-Batch is highly under-used by MVS systems
programmers.  Just because a program was especially written to run
under TSO, doesn't mean that it can't be extremely useful in the
batch environment as well.  For example, in recovery situations
when TSO (i.e. TCAS) itself might be down, but JES (2 or 3) is up, a
TSO-in-Batch job will still work, and will execute almost all of the
non-fullscreen TSO commands.  See Figure 1 for an example of
TSO-in-Batch invocation JCL.

      As one illustration, you might use a TSO-in-Batch job to execute
the TSO RENAME command, which doesn't produce any output.  But RENAME
will do its work--the dataset or pds members will be renamed.  Your
work can be checked by running the TSO LISTD command afterward.  LISTD
will produce printable output under TSO-in-Batch.  This technique might
just be what you need in order to save your system someday.  For some
other examples:  TSO LISTC, DEFINE, and DELETE will also run
beautifully under TSO-in-Batch, as though they were under TSO, and they
will produce printable output.  These three commands interface with
IDCAMS and VSAM.

      We mentioned last time that in order for a TSO command executed
under TSO-in-Batch to produce printed output, it has to perform its
terminal I/O through the TSO PUTLINE interface, rather than through
the simpler TPUT interface.  Most of the IBM-supplied TSO commands
use the PUTLINE, possibly with the associated GETLINE and PUTGET,
terminal I/O interfaces.

      Speaking of recovery situations, I can show you how to execute
TSO commands even when JES and TCAS are both down, and you can't
submit a batch job.  This idea is closely related to TSO-in-Batch.
There are products (even free ones) that create a TSO-like
environment, running as an MVS subsystem.  Subsystems can be invoked
independently of JES, if they are started from a proc using the
parameter SUB=MSTR.  While such a subsystem is running, you can
execute most TSO commands from an operator console, so you can perform
a large variety of recovery operations on a crippled system without
requiring a full IPL, and without requiring interactive TSO.

      The free subsystems which will accomplish this are various
versions of the product TSSO (Time Sharing Subsystem Option), that can
be found on several files in the CBT MVS Utilities Tape.  The original
version, by Bill Godfrey, is on File 306 of the CBT Tape.  A vastly
improved version that comes from Marc Schare and Bellcore, is on File
401.  Updates to File 401 by David Cartwright are found on File 402.
These were merged into File 401 by Guy Albertelli, and the final
product is on File 403.  If you plan on installing TSSO for recovery
or console automation purposes, it is probably best on newer systems,
to use the latest version from File 403.

      With TSSO installed and started, TSO commands can be executed
from the operator's console by prefixing them with the subsystem's
defined special character.  If TSSO was started with the parameter
SUB=MSTR, then all non-fullscreen TSO commands should work except those
which depend on JES, for example, SUBMIT, STATUS, or OUTPUT.  When TSSO
is started with SUB=JES2 so it runs under JES2, then even those three
commands will work perfectly well.  Now if the vendor product PdsTools
from Serena, or the PDS command from File 182 of the CBT Tape is
accessible to the TSSO task via its JCL, one can even expand the number
of directory blocks in a PDS without recreating it.  Or one can run
IEBCOPY (without JES or TCAS up), to compress a system library, or to
copy some JCL members from some other dataset to SYS1.PROCLIB, for
example.  You can begin to envision many possibilities for quicker
system recovery.

      All recovery procedures that will work under TSSO, will also
work under TSO-in-Batch, provided that JES is up, and the environment
will allow a batch job to run.  You might even try and set up a
started task to run TSO-in-Batch, rather than depending upon an
initiator.

      JCL for starting TSSO comes with the various TSSO packages, as
distributed on the CBT Tape.  Figure 2 contains some sample TSSO JCL.
You may be very surprised to notice its similarity to TSO-in-Batch
JCL.  This similarity is not coincidental, because TSSO was designed
to interface enough with "real TSO", so that a TSO Command processor
will "feel comfortable" executing in either environment.


SOME PRACTICAL APPLICATIONS.

      Now we'll quickly mention a few simple and practical applications
of this knowledge.  I recently had to delete a long list of datasets
with the same dataset prefix.  Having this list in a pds member, I
edited the member to enclose each dataset name in quotes.  Then I
shifted it to the right by a few bytes, to prefix each line with the
DELETE TSO command.  Thus, I had a long list of successive TSO commands:
DELETE 'dataset.name'.

      It is possible to execute this pds member as a CLIST, and it would
accomplish its job.  However, your terminal would be busy for a long
time, and if you weren't using the TSO Session Manager (see this column
in the December 1994 issue) you'd have to be pressing ENTER each time
the screen filled up.  An easier way would be to precede this dataset
with TSO-in-Batch JCL (see Figure 1) and submit the commands as a batch
job.  The commands will run much more quickly, and they won't tie up
your terminal.  Try it--you'll like it!

      I had a second practical application when I was trying to do a
mass ACCEPT of MVS maintenance.  This place had almost 500 Distribution
Libraries at the time.  Many of them had been allocated using IBM's
horrendous "device independent" block allocation that often comes as
the product's default.  Oftentimes, there aren't enough directory blocks
for expansion, and there are tiny secondary extents, so the 16-extent
limit runs out easily.  No one in the place was able to successfully
run a mass ACCEPT, because the job kept bombing either on a "directory
full" condition, or on a B37 abend when a few libraries ran to 16
extents, even with the compression turned on.

      Clearly, I had to fix a lot of datasets, without taking ten days
to do it.  TSO-in-Batch helped me again, but this time there was an
extra twist.  To change the secondary extent size, I had to use the
CDSCB TSO command from File 300 of the CBT Tape.  (See my February 1995
column for a description of CDSCB.  All my old columns are in File 120
of the CBT Tape.)  CDSCB has to run authorized, and I had an additional
restriction that I couldn't change the IKJTSOxx member on the fly.  No
problem.  I set up "private authorization" (see last month's column) in
an authorized STEPLIB, and put the CDSCB command in there too.
TSO-in-Batch will honor that, just as interactive TSO will.

      To add more directory blocks, I used the PDS TSO command from
File 182 of the CBT Tape.  PDS has a subcommand which refomats data
space at the beginning of a partitioned dataset's data area, as
additional directory blocks.  You just point PDS to the dataset and
enter the subcommand:  FIXPDS EXPANDDIR(nn), where nn is the number
of additional directory blocks you want to add.

      I had to do all of this to about 300 or 400 datasets.  So I
wrote the list of dataset names to a couple of files, and started
editing them.  The format of the CDSCB command I used was approximately:
CDSCB 'dataset.name' SHR SPACE(30) ALLOC(TR).  This assured that each
dataset would have a secondary extent size of at least 30 tracks per
extent.  I tried to leave the larger datasets off this list, or else
I tried to give them bigger secondary allocations than that, by
hand-editing the file.  Remember that I had a list which I could edit.

      Once this list was prepared, I headed it with TSO-in-Batch JCL,
using the authorized STEPLIB, and ran it as a batch job.  It worked
like a charm.  The other problem was a little different.  This was the
adding of more directory blocks.

      Since there were so many datasets, I had to use a bit of a brute
force approach.  I decided to add 8 directory blocks to all the datasets
on the DLIB pack, so at least there would be some breathing room.  This
had to be done with the PDS command.  I don't know of any other tool,
except for a specialized program that once was on the CBT Tape, which
does this.  The only commercial products I know of that have this
feature, are PdsTools of course, and DP Technician.  The PDS command has
to be set up in two lines.  First, you say:  PDS 'dataset.name', to
change the dataset which the PDS command is pointing to.  Then on the
next line, you have to say: FIXPDS EXPANDDIR(8).  You have to repeat
this for the 400-or-so datasets that you have.  Then you throw the
TSO-in-Batch JCL in front, and submit the batch job.

      All of this worked.  The ACCEPT job ran uneventfully, and
everything was fine.  Now you can do it too.

      In summary, I have to say that TSO-in-Batch really helps for
long jobs, and in a recovery situation.  TSSO helps for short jobs,
and in an even worse recovery situation, but TSSO will be very useful
under normal circumstances too.  For example, you may need to display
something at a system console, and a TSO command will do it.  Just
run the command from the console under TSSO.  The name of the game
is to learn how to use either IBM-supplied or user-written TSO
commands to do as many jobs as possible.  Then these techniques will
multiply your power, and help extricate your shop from some annoying
situations.  Good luck.  See you next month.



  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *


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.  The TSO
            RENAME command does not produce any printed output, but
            we are using LISTD to show the results of the renaming
            operation.



//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
//SYSPROC  DD DISP=SHR,DSN=your.clist.library
//         DD DISP=SHR,DSN=another.clist.library
//SYSPRINT DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*
//SYSTERM  DD SYSOUT=*
//SYSTSIN  DD *
 PROFILE NOPREFIX
 RENAME SYS1.PROCLIB(TSSO) SYS1.PROCLIB(TSSOOLD)
 RENAME SYS1.PROCLIB(TSSONEW) SYS1.PROCLIB(TSSO)
 LISTD SYS1.PROCLIB MEMBERS
/*
//


  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *


Figure 2.   Invocation of TSSO through its Started Procedure.

            TSSO is started by a proc that looks very much like a
            TSO-in-Batch job.  This example came from the CBT tape
            File 401, and was somewhat abridged because of space
            requirements.


//TSSO PROC
//*********************************************************************
//* A SUBSYSTEM STARTED TASK IS JUST LIKE ANY OTHER STARTED TASK, WITH*
//* TWO EXCEPTIONS. THEY ARE:                                         *
//*                                                                   *
//* 1) ALL DATASET NAMES MUST BE CATALOGUED IN THE MASTER CATALOG.    *
//*                                                                   *
//* 2) THE PROC MUST BE LOCATED IN SYS1.PROCLIB. THIS IS TRUE IF YOU  *
//*    DO NOT SPECIFY THE SUB= PARAMETER ON THE START COMMAND.  THE   *
//*    DEFAULT IS TO LET JES START TSSO.                              *
//*********************************************************************
//TSSO EXEC PGM=TSSO,REGION=3000K,DYNAMNBR=20
//STEPLIB  DD  DSN=SYS1.TSSOLOAD,DISP=SHR
//SYSPROC  DD  DSN=SYS1.TSSOPROC,DISP=SHR
//SYSUADS  DD  DSN=SYS1.UADS,DISP=SHR
//SYSTSIN  DD  DUMMY,DCB=(RECFM=FB,LRECL=80,BLKSIZE=80)
//*********************************************************************
//* TSSO DOES NOT USE THE SYSTSIN DATASET, BUT TSO WILL TRY TO GET    *
//* COMMANDS FROM HERE. TSSO PASSES COMMANDS TO TSO AND DOESNT REQUIRE*
//* SYSTSIN.
//*********************************************************************
//SYSTSPRT DD  UNIT=VIO,SPACE=(CYL,2),
//         DCB=(RECFM=VBA,LRECL=137,BLKSIZE=1370,DSORG=PS)
//*********************************************************************
//* W A R N I N G          W A R N I N G        W A R N I N G         *
//*
//* DO NOT CHANGE THE LRECL AND BLOCKSIZE OF THE SYSTSPRT DATASET.    *
//*
//* W A R N I N G          W A R N I N G        W A R N I N G         *
//*********************************************************************