MVS TOOLS AND TRICKS OF THE TRADE
                            JUNE 2003

                                      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.


EXPLORING MVS SAMPLIBS

      Today's topic concerns IBM-supplied "sample libraries" for MVS.
As almost all of you know, a "SAMPLIB" is usually a semi-supported,
release-dependent collection of sample programs and possibly data,
usually written by IBM employees, which show you how to use certain IBM
facilities.  For example, the SYS1.SAMPLIB for a given MVS release might
contain sample SMF exits (currently in member SMFEXITS), that show you
how to write your own IEFACTRT (job termination), IEFUJV (job
validation), IEFUJI (job initiation), and IEFUTL (time limit) exits.
The supplied programs actually work.  Your own installation might have
modified these samples at one time, or someone there might have written
their own SMF exit from scratch.  But in either case, IBM will usually
keep their samples in shape to run on the distributed MVS release, and
these coding examples are almost always helpful to have, at least for
reference.

      In this article I can only give an overview.  My purpose for
writing, is to awaken your interest in looking at the IBM SAMPLIBs and
in raising your consciousness concerning them.  Obviously, even one
sample program, such as the TSO exits IKJEFF10 or IKJEFF53, could be
the subject for a complete article, and nowadays SYS1.SAMPLIB contains
over 1000 members.  So our discussion will have to be very general, in
the direction of suggesting useful places in SAMPLIB to look.

      I personally have access to SYS1.SAMPLIB libraries at several
levels, including one from the MVT days, circa 1974.  The MVT sample
library is public domain software, and it may be found on File 079 of
the CBT Overflow Tape, on the CBT Tape web site.  The latest copy of
SYS1.SAMPLIB that I have seen is for z/OS 1.4, and I have saved some
others from in between.  Part of the purpose of this article is to point
out a few ways in which SYS1.SAMPLIB has changed since the early days of
MVS and before.

      A fact to know:  SYS1.SAMPLIB is a dataset which is modified by
SMP/E.  In other words, the members of SYS1.SAMPLIB, for the most part,
are officially a part of the MVS operating system.  Therefore, when a
system component is enhanced in such a way that it runs differently
than before, its accompanying sample program illustrations might have
to change.  Therefore, SPE's (Small Programming Enhancements) from IBM
might also be accompanied by SMP/E modifications to SYS1.SAMPLIB
members.  Please keep this fact under your hat.

      Before we go on, I'd like to mention one more thing.  SYS1.SAMPLIB
has always been the home of the object deck for IEAIPL00.  This is the
bootstrap program which is loaded (via ICKDSF) into Track 0 of the disk
pack that you IPL MVS (or MVT) from.  And this is the program which
actually does the Initial Program Load.  Every SYS1.SAMPLIB library I
have seen, contains a level of the IEAIPL00 program which is appropriate
for the level of MVS with which it is distributed.  So besides all the
sample programs, JCL, and the like, SYS1.SAMPLIB will always contain a
copy of the current system's bootstrap program.


SYS1.SAMPLIB PROGRESS

      The MVT (OS/360 Release 21.8) SYS1.SAMPLIB library in my
possession contains just 42 members.  Some of them are sample programs
for testing the language compilers.  Of course there is the ubiquitous
IEAIPL00, because that is its home.  There are a few sample exits for
SMF (which was already in place at the end of the MVT days) and the SORT
program.  There are object decks to do standalone dump/restore of disk
packs--a necessary function.  There are some sample terminal handling
programs for the terminals which were available then.  And there are JCL
samples to uncatalog and recatalog the system datasets.  That's just
about it.  Maybe there are one or two other things I've overlooked.

      On the other hand, the current versions of MVS are a wee bit more
complicated, a fact reflected by the SYS1.SAMPLIB which comes with z/OS
Release 1.4.  The z/OS 1.4 version of SYS1.SAMPLIB which I have seen,
contains well over 1000 pds members.  What are they for?

      This current version of SAMPLIB, as were all previous versions, is
helpful to the extreme.  Illustrations abound for addressing the setup
of just about every MVS component, from the System Logger to UNIX
Services.  One thing that strikes the eye, when looking over a current
SYS1.SAMPLIB, is the abundance of REXX execs now to be found there.  If
you think about it, that comes as no surprise.

      Part of IBM's plan for MVS which was stated in the late 1980s, was
that CLISTs would be replaced by the REXX Command Language in TSO.  IBM
made a promise to enhance REXX, originally a VM tool, for TSO.  Part of
the direction was to make TSO REXX much richer in capability, and to
give it "programming language" status.  REXX execs can now address
system storage and control blocks.  They can also pretty much do all the
complicated TSO manipulations which CLISTs have traditionally done.  Of
course REXX execs can be run both in Batch, and under TSO.  So when it
comes to doing all the system setups, and exercising the capability of
the newer MVS components, IBM people are utilizing the REXX language
very much.  And this fact is reflected very abundantly in the members of
SYS1.SAMPLIB.

      But there are some more things we should notice as we tour the
members of the latest versions of SYS1.SAMPLIB, and this is especially
true if our installation's PARMLIB members were last tailored many MVS
releases ago.  Sometimes, you just haven't explicitly coded all the
options you can in some PARMLIB member, and the uncoded PARMLIB options
will revert to the defaults.  Many explicit samples of PARMLIB members,
showing all the new settings and options, can now be found in
SYS1.SAMPLIB, so they will jog your mind in suggesting what to change.

      You might say that is not important, because IBM tries to keep
as many option settings as upwardly-compatible as possible.  But my
experience has shown that a sysprog's head should not be kept in the
sand.  Periodically, you should review all your installation's PARMLIB
members to see if some of the newer options might be valuable to code.
Of course there is always the risk that you might "spoil something" in
the operation and efficiency of the system by experimenting.  But I am
not advocating experimenting--I am advocating investigating.  Don't
change a PARMLIB member, just because a new explicit option is now
available.  Rather, look in the current "MVS Initialization and Tuning
Reference" manual and learn what all the settings are supposed to do.
If you see a new setting that you think might help your installation
run better, investigate it carefully before trying it out.  Don't play
with it until you're pretty sure about it.  But you have to start the
progress somewhere, and glancing at the sample in SYS1.SAMPLIB might be
very helpful.

      You might think of taking this a step further and forgetting about
SYS1.SAMPLIB altogether, relying only on the MVS Initialization and
Tuning Reference when reviewing your PARMLIB members.  But I'm not
advocating that either.  Remember that SYS1.SAMPLIB is usually well
supported by IBM, and its members have usually been supplied by the MVS
programming staffs, not the "system packagers".  So the suggested
codings in the SAMPLIB members have to be given some consideration and
weight.  It is very possible that a PARMLIB option, in the sample
PARMLIB member from SAMPLIB, was coded a certain way for a very good
reason (which may or may not apply to your shop).  And because of this,
it behooves a sysprog to check SAMPLIB to see if a sample member exists,
whenever there seems to be a reason to change a PARMLIB member.


SAMPLE EXITS AND PROGRAMS

      In my experience, many shops will tend to propagate their system
exits from one MVS release to the next.  This makes perfect sense,
because you want your shop to look and run the same way, when the new
MVS release is deployed.  You don't want the Operations people and IT
management to shudder every time the system is changed.  Rather, you
want them not to notice any changes at all, except for advertised
improvements and perhaps, better efficiency.  To them, everything
should continue to look more or less the same.

      So a crucial part of achieving this is accomplished by keeping
all the system exits the same, or at least completely compatible.  And
therein lies a possible problem.  The MVS system will sometimes be
changed in critical areas.  And this is necessary.

      Let me illustrate.  At one point in time--I think it was around
the beginning to middle 1990s, IBM had a big push to allow data centers
to operate on a 24x7 basis.  In other words, IBM was under pressure from
their big customers to keep IPLs to a minimum.  So they had to redesign
certain internal components of the MVS operating system.  Old MVS'ers
know that many critical control blocks used to require an IPL to change
or renew them.  Nowadays, they don't need an IPL.  What was the
change required?

      Internally, the difference was in the "static-ness" or
"dynamic-ness" of a control block's (or table's) structure.  As
originally designed, if MVS needed some data in an area of storage,
that area would be GETMAINed at IPL time and filled during the IPL
processing with the necessary control block information.  Often, your
settings in PARMLIB would determine how much area would be GETMAINed
(i.e.  acquired).  If you later saw that the area was not big enough
for your needs, you'd have to change the PARMLIB setting, and re-IPL.
This is the kind of situation that IBM was under pressure to "seek and
eliminate".  After all, if you want to avoid IPLs, it is better to make
these control blocks adjustable "on the fly" with perhaps an operator
command.

      So IBM developers went about systematically looking for these
kind of statically structured control blocks, and replacing them with
dynamically maintained ones.  This would require restructuring of the
system data.  For example, suppose you had a table of system nodes,
that is, destinations of other computer systems which this computer was
connected to.  And all of a sudden, your computer's network was to be
merged with another network, and 150 new destinations had to be added
to all the connected MVS machines.  That would normally require an IPL
of each machine to rebuild the static "destination table" that resided
in a single block of data.  But no IPL would be required if the table
were redesigned, so the individual entries were chained to each other,
and if more table space had to be acquired, the new table entries in
the new space would just be chained to the old entries in the original
space.  It would not matter then, that the new table entries would
reside in a storage area non-contiguous with the original area.  That's
the idea.  This is the kind of redesign being done very often in MVS.
If you've been around MVS for the past eight or ten years, you're
familiar with it.

      Now what if one of your system exits read this table the old way,
that is, it would only look for one piece of storage, and it would
assume that each table entry was next to the previous one?  This would
clearly cause an error in the MVS system's operation.  Often, that kind
of error is very difficult to diagnose and causes mysterious problems.

      How do you fix it?  Often, the best way to fix it is to look in
SYS1.SAMPLIB at a newer sample version of that same system exit.  There,
you would find a piece of code, written by some IBM-er who should know,
that accesses the redesigned control block or system table "the new
way".  By looking in SYS1.SAMPLIB your work is minimized.  You don't
have to conduct an in-depth investigation of the new workings of that
system table or control block.  You just have to copy or modify the
IBM-er's new sample code that's waiting for you, right in SYS1.SAMPLIB.
System maintenance across MVS releases is thereby made much simpler and
more accurate.  It's done in far less time, and with fewer complaints
from management.

      So I hope that I've opened your eyes to one other area of this
vast MVS world which is our everyday domain.  A sysprog has to be ever
vigilant for the cause of errors, even if they don't occur very often,
and your system runs smoothly most of the time.  SYS1.SAMPLIB is another
of the many resources that IBM has supplied to help you, and it is very
good to be aware of it.  I wish all of you the best of everything, and
I'm looking forward to seeing you again next month.