MVS TOOLS AND TRICKS OF THE TRADE
                          MARCH 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.


ISPF INTERFACES FOR MVS PROGRAMS

      Deploying our utilities is one of the main tricks of our trade.
A given software tool might be potentially available, but how can we
make it easily accessible to ourselves, should we ever need it?  It's
obvious to any Systems Programmer, that convenient setup of our tools
is critical to the efficiency with which we can do our jobs.

      Sometimes we know that a certain tool exists which does a specific
job.  That tool's setup process may consist of finding its source code,
assembling it, setting up some ISPF panels or CLISTs or REXX execs, and
then figuring out what JCL, or TSO command, or ISPF panel entry, is
needed to run it.  Only after we've done the setup process properly,
will the tool be available for us to use.  Often, especially when we
have to set up our own working environment, a considerable amount of
time must be initially invested in setting up each tool that we're going
to need later on.  As we all know, spending time in advance to prepare a
tool, just in case you'll need it later, is always time well spent.

      Once we have a tool set up, we can use it.  However, in our
business, we use a large variety of different tools, and our working
efficiency, how usefully we'll be spending our time, will often depend
on how quickly any given tool can be deployed.  So we all try to
organize our collection of tools, so we know how to find them.

      There's another factor though, which can greatly affect our
working efficiency.  That factor is a native inefficiency in the way a
tool executes.  For example, a raw TSO command displays its output to
us, one screen at a time.  Under raw TSO, we can't scroll up and down
to see more than a screen's worth of data.  Trying to sift through a
large amount of TSO output that way, could cost us a lot of extra time.

      Suppose, for example, that the output of some tool is written to
a native TSO screen (i.e. a screen in TSO READY mode).  A good example
of this, is the TSO HELP processor.  When using TSO HELP, for example,
the fact remains that once a TSO screen fills up and you've gone to the
next screen, the first screen has disappeared.  On a normal native TSO
screen, you can't scroll back upward, to see data that has already
passed by.  Therefore, if you want to see data on a screen that has
already passed, you have to interrupt the current execution of the TSO
HELP command (using PA1 or the Attention key), and you have to
re-execute HELP.  This is a major pain in the neck, and a cause for
great inefficiency in using this tool.  Anyone who has used TSO HELP to
look at a large HELP member, knows exactly what I mean.

      Today, our concentration will be in improving the efficiency of
tools we already have, by trying to put their output into more
convenient form.  Most ISPF outputs, for example, are fullscreen
displays which can be scrolled upward or downward, as you need.
Therefore, we could make an immediate improvement in our working
efficiency, if we would somehow convert our TSO output into ISPF
BROWSE or VIEW form.  This would make the output far more convenient
to use, than if it were merely displayed under TSO READY mode, the way
the tool was originally designed.  Imagine how much easier it would be,
to view a (several hundred line) TSO HELP command, if the whole thing
could be BROWSEd, and you could scroll up and down to look at any of
the information you needed?  (Of course, you could use the HEL command
processor, from File 134 of the CBT Tape collection, which is a full
screen TSO HELP browser.  I've personally used the HEL command for
many years.  But just now, we're emphasizing more IBM-style means of
doing this.)

      In this discussion, we'll see many of the things we can do,
to improve the output formats of our tools, so they'll be easier
and quicker for us to use.


TSO SESSION MANAGER MODE.

      IBM's original solution to the problem of TSO output filling one
screen at a time, and then disappearing, is called the TSO Session
Manager.  The TSO Session Manager gets rid of the one-screen-at-a-time
limitation, by creating a large screen buffer area, 255 characters wide
by several thousand lines long.  Instead of writing the TSO output
directly to a screen, under TSO Session Manager, TSO writes its output
to this large buffer.

      TSO Session Manager mode has some primitive screen positioning and
splitting capability, which can be customized.  PF9 takes you to the top
of the buffer.  PF12 takes you to the bottom.  PF7 scrolls half a screen
up, and PF8 scrolls half a screen down.  PF10 and PF11 help you scroll
sideways.  All of this is customizable by the user.  So with TSO Session
Manager mode, you can save a lot of TSO output at the same time, and you
can scroll up, down, and sideways to view it.  What about saving this
output and putting it someplace else?  It's easy, but also primitive.
Just use the IBM-supplied command SMCOPY to copy the entire contents of
the Session Manager buffer to an output file or to SYSOUT.

      Setting up TSO Session Manager Mode, in its default configuration,
is a piece of cake.  All you have to do is to substitute the program
name ADFMDF03 in your LOGON PROC, instead of the program name IKJEFT01.
There's more to it, of course, but that's the easy and painless way to
get to TSO Session Manager without having to know much.  On File 136 of
the CBT MVS Utilities Collection, there is a command processor (that has
to run authorized) called SM, which toggles you into and out of Session
Manager Mode.  In other words, if you are running TSO in Session Manager
mode, having used program name ADFMDF03 in your LOGON PROC, you can just
enter the command SM, and you'll be running in ordinary TSO mode.  Enter
command SM again, and you'll be back in Session Manager mode.  Once that
is set up, you have no trouble running native TSO either way.

      IBM also supplies a way to toggle into and out of Session Manager
mode, which uses ISPF, but in my opinion it's nowhere nearly as good as
the SM command processor that was contributed by Howard Dean.  You use
the IBM method by setting up an alternate panel for the ISPF Option 6
panel, and that panel has a switch to toggle you into or out of Session
Manager mode.  Howard Dean's SM command is better, because (first), SM
runs directly under TSO, and doesn't need ISPF.  And (second), the ISPF
method sometimes simply doesn't work; it just doesn't switch your TSO
execution mode, which can be very frustrating.

      You can execute a TSO command under Session Manager mode and
capture very long output.  It's unwieldy, but the capability is there.
Just get into Session Manager mode, execute the command, go to the top
of the buffer with PF9, and to the bottom with PF12, to make sure all of
the output is there, and just use the SMCOPY PRINT(to.dsn) option to
copy the entire buffer, from top to the end-of-output, to an external
file.  Then use ISPF EDIT to chop up the file the way you want it.

      I like to run my TSO sessions in Session Manager mode nearly all
the time.  If I really need only one-screen output, I have the SM
command ready and waiting.  The SM command does not destroy the Session
Manager buffer--it merely disables it temporarily.  When Session Manager
mode is turned on again, the old buffer contents are there.  Session
Manager mode also has the advantage that if you're running something
which fills up many TSO screens, it's not delayed after each screen
fills up.  The command or program runs to its full execution without
delays.  For example, if you're copying a pds under TSO, using IEBCOPY,
and the pds contains several hundred members, the copy runs to
completion at once under Session Manger mode.  Under regular TSO
execution mode, you may have to press Enter several dozen times before
IEBCOPY completes.  Nowadays, you'll see this advantage of Session
Manager mode when you invoke the TSO XMIT command against a pds, which
runs IEBCOPY under the covers, and it might generate a long output.

      What happens when the Session Manager buffer fills up?  The TSO
programs that are executing keep running.  There is a rather long period
after which there is a pause--it's something like one and a half
minutes--and you have to press Enter again.  But by and large, under
Session manager, the output keeps pouring out without much delay.  But
when Session Manager overruns its buffer, it merely pushes off the top
of its buffer space, and wipes out the first output that came out.  You
(only) get the last several thousand lines of the command output.  In
that sense, Session Manager behaves like regular TSO, but instead of
showing 24, 27, or 43 lines, it shows several thousand lines before the
output rolls off.  Session Manager mode is, in many cases, a large
improvement over native TSO output.


TRAPPING SYSOUT FROM TSO COMMANDS

      At this point, I'd like to talk about one of today's main topics,
which is how to trap some TSO output and BROWSE, VIEW, or EDIT it, so
that it can be handled as one entity.  Not all TSO output can be so
trapped.  Only TSO output that was produced by the TSO PUTLINE facility
can be trapped.  TSO output that was produced by the TSO TPUT facility
cannot be trapped.  Fortunately, when a CLIST produces output by saying
WRITE, or a REXX exec produces output by saying SAY, this output gets
created by the TSO PUTLINE facility.  So most of the output of our TSO
CLISTs and EXECs can be trapped, to be re-displayed under ISPF.

      There's one new out-of-the-box way to perform this operation.
It's a REXX exec called DISP, by Robert Bridges.  You can find DISP on
File 487 of the CBT Tape collection.  Just install the DISP exec in your
SYSPROC or SYSEXEC concatenation of libraries under ISPF, and execute
the TSO command whose display is to be captured, as follows:  TSO DISP
followed by the command.  For example, you can say:  TSO DISP LISTC
LEV(SYS1) .  DISP will capture the output of the LISTC command, allocate
a temporary work file, write the output to the work file, and ISPF VIEW
the command output.  You can scroll up and down, or copy off chunks of
the TSO output to another file.  It works like a charm.

      You can look at the outputs of large TSO HELP members, by simply
saying something like TSO DISP HELP XMIT, and you'll VIEW the entire
HELP member for the XMIT command, instead of having to painfully look
at it one screen at a time, as before.  This DISP exec is a great thing.


TABLE-izing THE OUTPUT OF PROGRAMS

      I'll illustrate this concept with an example.  I'm the author of
a set of utilities which can do amazing things with SYS1.BRODCAST user
messages, (and also some pretty novel things with the entire
SYS1.BRODCAST dataset).  This entire package of utilities is free, and
it can be obtained from File 247 of the CBT MVS Tape collection.  One
of these utilities is a TSO command program called BCMUSERS.  If you
allocate the BRODCAST ddname to DATASET(SYS1.BRODCAST) and execute
BCMUSERS under TSO, you get a list of all TSO userids with outstanding
SYS1.BRODCAST messages, plus the number of messages waiting for each
user.  It's a cool program, and it's quick.  You can execute the
BCMUSERS command on each LPAR or MVS system that you're running.

      The problem is, once you've found out that a userid has 2000
outstanding broadcast messages, and they're clogging up SYS1.BRODCAST,
you want to know if the messages are important, so you also want the
capability of displaying and/or deleting them.  My programs BCMLIST
(to display a user's messages without deleting) and BCMDEL2 (to display
and delete a user's messages) accomplish this purpose, but deploying
BCMLIST and BCMDEL2 against a large group of users can be an unwieldy
administrative task.

      I wanted to do the following:  If I could display a user list of
all users with outstanding messages (produced by the BCMUSERS program)
as an ISPF table, so I could execute line commands against each user
(display from BCMLIST or display/delete from BCMDEL2), then
administering SYS1.BRODCAST for outstanding user messages could be a
breeze, and SYS1.BRODCAST would never be allowed to fill up!  You could
set up one of these gizmos for each LPAR or MVS system that you run.

      Not having time to develop this myself, I asked my friend Vinh Vu,
whose utility collection is on File 166 of the CBT Tape, and who is a
whiz at this kind of stuff, to develop an ISPF application which manages
SYS1.BRODCAST user messages in this way.  Vinh whipped up a REXX exec
which drives several ISPF panels.  You can find Vinh's package on File
247 of the CBT Tape under member BCMISPF, and if you want, you can study
his code.

      Or you can just use it.  Just install his BCMUTIL REXX in a
SYSPROC or SYSEXEC library, copy his panels into an ISPPLIB library,
execute the BCMUTIL REXX, and you'll immediately get a display of all
userids with outstanding SYS1.BRODCAST messages on that system.  You
have the option to place an S next to a user to see that user's
messages, or a D next to the user name, to display and delete those
messages.  ISPF-izing these programs makes them very quick to use.

      I hope you've enjoyed today's discussion, and I hope it has helped
each of you, in some way.  Much of an MVS Sysprog's work is done under
TSO, and the faster you can deploy your TSO tools, the quicker you can
get your work done.  Best of luck to all of you, and I'm looking forward
to talking with you again, next month.