THE VALUE OF TOOLS, NEW AND OLD - PART 1

(c) Copyright 2019 by Sam Golob.  All rights reserved.


INTRODUCTION - GETTING THE JOB DONE

      Our job involves keeping a z/OS installation running well.
Usually we do this for a large business or institution or government
agency which depends on this computer system to run the company's
operation.  Downtime means a disaster to some degree, small or large.
Downtime almost always involves a considerable loss of money for the
installation.  The computer system is the pulse of the business, and
its "money maker".

      Therefore, we have a big responsibility.  If there is a problem,
we have to get it fixed.  If there is a system upgrade, we have to do it
flawlessly.  Glitches happen, but we are required to be the "geniuses"
that "head them off at the pass".  In other words, if there are
problems, we have to get to the bottom of the situation as fast as
possible, and FIX THEM.

      IBM gives us a lot of tools, but they are limited.  At bottom,
IBM (as big as they are) is a software house.  Their programmers have to
be paid, and therefore scheduled, and the work planned out.  They can't
code anything they want, or take as much time as they want.  As a
result, IBM tools will often "cover the ground", but frequntly not quite
as well as we'd like.  Therefore, systems programmers have written their
own tools for as long as we can remember.  Let's explore a few of these
tools, that may be new to you, and maybe not.


TYPES OR CLASSES OF TOOLS, AND WHERE DO WE GET THEM?

      Many of the tools that we need in our work, have to do with
finding out what is happening in the operating system, as it is in the
midst of working.  A good example of such a tool is the SHOWzOS TSO
command, (in CBT File 492.  See later in this article about the CBT
collection of tools.)  Another class of tools, has to do with finding
out what kind of data we are looking at, whether it be (1) system data,
or (2) application data, or (3) data in computer storage.  We then get
to the difference between "looking at data", and "changing data".

      Some of our tools will first look at the data, and then, when we
see the data, we may decide to change some of it.  When a tool can
change data, it might need more authority.  We'll discuss this later in
the article, where we explain what the concept of "APF-authorized"
means.  Certain tools have been designed only to look at the data, but
once we find out what's there, we can start doing something appropriate,
because we now have a better idea what is really going on.  We may not
need to change the data.  In that case we only need to find out what
data is there.

      I'll digress a bit about where to get tools.

      When there is a need, we try to either find a tool, or write a
tool.  It is easier (usually) to find a ready-made tool, which already
does the job we want to do, than to write the appropriate tool yourself.
But we try and do both, and we let the other people (in the case of a
free tool) use the tool for themselves as well.  This makes everybody's
job easier.

      Some shops, which are more "wealthy", will buy vendor-supplied
tools besides those written or supplied by IBM.  Other shops, which
don't have as much money to invest, have to scrounge for tools, and they
have to try to find them or write them for themselves.  Whatever the
shop, if they have access to "free tools" that don't require licensing,
then they can ALWAYS run the free tools, as well as the vendor-supplied
tools or IBM's tools.  But "rich shop" or "poor shop", the free tools
will work there.  So if you know how to use free tools, you will have a
considerable skill advantage wherever you work.

      So where do we find free tools?  A great repository of free tools
can be found in the CBT Tools collection at www.cbttape.org.  There are
thousands of tools there, all written by people with specific needs,
which have solved the problems for them.  With proper application, they
can solve the problems for you too.  And you can download anything there
for free.  (There is a "Disclaimer Section" on the web site.)

      My teacher Jeff Broido taught me many years ago, to try and take a
half hour each working day, to learn something new.  The knowledge thus
acquired over time, will help your both shop, and you yourself, to
handle future problem situations that will come up later.  I've done it,
and it is good advice.  Often, I use that "learning time" to search
around the CBT tool collection to try and find tools which I can use to
make my life easier later.


"LOOKING" TOOLS OR "CHANGING" TOOLS

      I'll give you a few examples of tools that either look at data, or
they can change data.  Some tools can do both.  Others can only "look",
but not "change".  The borderlines between these two classes are fuzzy.
I'll show you how and why.

      First (for simplicity), consider a program that can read magnetic
tapes.  Magnetic tapes are "linear" in nature, or one-dimensional. To
put it differently, all their data lies in a straight line.  There is a
beginning of a tape, an end of a tape, and everything in between.  You
read the data either "forward" (normally) or "backward", but there is no
such thing as sideways.  All of the tape data can be pictured as lying
on one line.  We will now shou you what it means to "read a tape".

      To illustrate the point better, let's assume that we are giving
the program the power to read tape labels as well as tape data, so we
will invoke the program with DD tape JCL as LABEL=(,BLP) (which means
"Bypass Label Processing").  This makes the program able to consider the
tape labels as purely data, and then we can get a truer picture of what
is really on the tape.

      Now to start.  The program will OPEN the tape file, and start to
read the blocks of data, usually into a buffer in storage, one block at
at time.  So when that block of data is in storage, you have access to
it, and you can do anything you want to do, with it.  You have a choice
as to what you will want to do next.  To merely COPY the tape, all you
have to do is to write the contents of that buffer to another tape, and
then re-do the process of reading a block of data and copying it, one
block at a time, until you get to the end of the volume.  When you
encounter a "tape mark", which constitutes a boundary betwen tape files,
you write a tape mark to the copied tape at that point.  You continue
this cycle until you encounter the end of the input tape, or possibly
you can also stop this process at some time in the middle, perhaps after
reading a certain number of tape files.  Or you can skip some files
after reading them, and copy some of the following files from the middle
of the tape, leaving out the ones at the beginning.

      To MAP the contents of the tape, you can report on the data that
is in the buffer.  If it is a label, you can report on the contents of
the label.  If it is a data block, then you can measure the data, or
print it out, or even change it in place.  With tapes, if you want to
change any data, it is probably best to make a duplicate copy of the
tape with the changed data, rather than to alter the original tape
itself, which usually isn't too safe.

      So you see the flexibility.  With tape programs, you can either
MAP the tape, to see what is on it, or COPY the tape to make a
duplicate, or alter the contents of the tape in some other way, doing
the alteration in the process of making a copy, so that only the copied
tape is altered.  You can also collect statistics about the tape files,
or do something else.  You are only limited by your imagination.  You
can either make one program to do it all, or you can make several
programs, each one of which performs part of the process.

      There are at least eight different tape copying or tape mapping
programs on the CBT Tape.  Examples are:  TAPEMAP from File 299,
COPYMODS from File 229, or the COPYFILE family of programs from File
316, including COPYSLNL and COPYNLNL.

      So much for tapes.  Now let's consider looking at disk data.

      Disk data is specialized.  It can be of many formats.  For
example, if you have a load library, that, of course, is on disk.  But
the layout of the data, being executable programs, has a specialized
structure.  What I am considering now, is to just look at RAW disk data.
And to do so, we have an excellent tool, the source code of which is on
File 134 of the CBT Tape, and which is called "Fullscreen ZAP".
Incidentally, Fullscreen ZAP is also an excellent tool for looking at
load modules, but right now I want to emphasize its ability to look at
raw disk data as well.

      Fullscreen ZAP is a TSO command which shows a full screen (208
bytes) of data at a time, anywhere on a disk.  Under many circumstances,
Fullscreen ZAP does not even need to be run APF-authorized, but to see
ANY data, ANYWHERE on a disk pack, it needs to be authorized.

      Fullscreen ZAP can also CHANGE any data on a disk, (doing it in
place, up to 8 characters at a time).  The advantage of Fullscreen ZAP
over an IBM program like MVS DITTO (great to have if you are licensed
for it), is that with Fullscreen ZAP, you can look at a large bunch of
surrounding data, next to the data you want to see, or change.  And you
can do it in real time.  It's nice to have Fullscreen ZAP in your
pocket, and to know how to use it.  Fullscreen ZAP has a complete
tutorial, accessible through PF1, which tells you how to use all of its
subcommands.  It pays to take the time to learn it well.  You can even
disassemble small parts of load modules with it, in the vicinity where
you are looking.

      What about data in virtual storage?

      We have a marvelous command, named LOOK (CBT File 264), to look
at virtual storage in any address space (LOOK goes cross-memory by
scheduling an SRB).  LOOK was recently enhanced to be able to see
64-bit storage as well.

      LOOK can "look at storage" but cannot change it.  I use LOOK when
I am programming, to actually "see" the data that is in the system.
I can also use LOOK when I am debugging a program with TEST, to go
cross memory into the address space running TEST, and to survey storage
that is in that address space.  (TEST and TESTAUTH stop the action in
that address space, at a breakpoint, and then I can leisurely use LOOK
to peek and search around over there).

      LOOK is an amazing tool.  Besides being able to see raw storage
with it, you can easily format the data you are looking at, if it is
within a known control block.  And when you assemble LOOK, you can even
customize which control blocks you want LOOK to be able to format.
Since this article is only an overview, and I don't have time here to
talk about LOOK in depth, I would recommend that you go to CBT File 264
or CBT File 035 (to get a load module for LOOK, to try out) and
experiment with it yourself.  You'll be super-glad that you did.


AUTHORIZING YOUR TOOLS, IF AUTHORIZATION IS NEEDED

      Here's a situation where you should check with your management.
Once you authorize a tool with APF-authorization, it can potentially "do
anything" on the system, although there may be some other safeguards
there.  Nevertheless, APF-authorization is not generally something that
application programmers should have, and if you are a systems
programmer, you need to be "responsible" and you need to know what you
are doing.  Don't risk any "production data" unless you are absolutely
sure, and if you're a "junior person", you should have a "senior person"
watching you.  The company's money (read "big bucks") is at stake, and
you don't want them to lose any of it.  They pay your salary to keep the
system up and running "healthy".

      Now that this disclaimer is over with (and you'd better take it
seriously), we can get down to the nitty-gritty.  I'm assuming you're
doing this on a "test system".

      In order for a program (or TSO command) to run with
APF-authorization, it needs several prerequisites.  First, it needs to be
linkedited with the option:  SETCODE AC(1).  This is actually a setting
in the pds directory entry for the load module, at X'27' (field
PDSAPFAC), and the value has to be X'01'.  If the program was not
linkedited this way, you can always throw the bit on, using the PDS
command (CBT File 182), using subcommand:  ATTRIB modname AUTH.

      Next, the program (or TSO command), has to be executed (fetched)
from an APF-authorized library, or an APF-authorized concatenation of
libraries.  If one library in a concatenation (say a STEPLIB
concatenation or a TSOLIB) is not authorized, then the entire
concatenation is not authorized, even if ALL the OTHER libraries there
ARE authorized.  For a load library or a PDSE containing program objects
to be APF-authorized, it must either be in the LINKLIST, when
LNKAUTH=LNKLST is set in the IEASYSxx member of PARMLIB.  Or it must be
in the system authorization table of libraries (called the APF list),
which is created from the APF ADD portion of the PROGxx PARMLIB member.
Each entry of APF ADD, which adds a library into the APF list, and makes
its programs eligible to be run APF-authorized, must specify two things:
the library name, and the volser of the disk pack that the library is
on.  It does not matter that the library is cataloged to its pack.  For
the APF list to be in effect for the library, its volser must be
explicitly stated.

      If you want to add a library to the APF list dynamically, you can
enter a console command:  SETPROG APF,ADD,DSN=dataset.name,VOLSER=volser

      There is one more prerequisite for APF-authorization if you are
either executing the program or TSO command under TSO (including
TSO-in-batch) and not in a batch job.  In the case of running authorized
programs (e.g. via CALL) under TSO, or running a TSO command processor,
which is intended to be APF authorized, you must include the program
name (exactly) in the proper special name table.  To be straightforward,
there are three separate tables which are defined in a the PARMLIB
member called IKJTSOxx.

      Three possible name lists can be used to authorize load modules
in the IKJTSOxx PARMLIB member.  The first category is the AUTHCMD
entry, which specifies all of the TSO command names which are allowed
to run APF-authorized in your session.  The second category is the
AUTHPGM entry, which contains the names of all programs called from
TSO, which are to be run APF-authorized.  Finally there is the AUTHTSF
list, which contains the names of a few programs that need the TSO/E
service facility (TSF) to gain authorization, because they may need
(for example) too many parameters for a normal CALL to handle.  IBM
says that you should not put program names in the AUTHTSF list unless
they absolutely need to be there.

      The IKJTSOxx PARMLIB member can be updated in your LPAR, by the
console commeand:  SET IKJTSO=xx

      The APF list can be dynamically updated by entering the console
command:  SET PROG=(xx,yy,zz,...)

      With that done, we can now refer you to CBT File 185 for more
fine points about getting APF-authorization under TSO for your lists
of programs and TSO commands.  And with that, we bid you adieu,
goodbye, and auf wiedersehen, etc. till next time.

      Best of everything to all of you...........