X-Vmsmail-To: SMTP%"notis-l%tcsvm.bitnet@ricevm1.rice.edu"
Newsgroups: bit.listserv.notis-l
Date:         Tue, 26 Jan 1993 14:13:06 -0600
From:         LEIGH WILLIAMS <F_WILLIAMS@CCSVAX.SFASU.EDU>
Subject:      VSE JCL
Comments: To: notis-l%tcsvm.bitnet@ricevm1.rice.edu

WARNING!!!

Librarians and non-technical types can stop reading now if
you want.  This is a long message and we're speaking Greek
part of the time.

TECH1's, bear with me; I know this is lengthy, but it's a
very important issue and I *need* your input.

Read the following caveats and the history carefully so that
you can understand where we're coming from on this.

CAVEATS

Our concern here is with VSE, not MVS.  Some MVS programmers
wrote to say that they like the procs.  After working on
Michael's system, I can understand why.  VSE's problem is
that editing procs is a real pain in the ass -- you punch
the JC, get the first proc name, punch the proc, get more
proc names, punch them, etc.  You have to recatalog each
proc if you change it, too.  Feels like an infinite loop
most of the time.

NSI has *not* undertaken to accomodate us on this matter.
They are willing to listen to reasonable arguments.  It
will be difficult to convince them to maintain two sets
of JCL.

HISTORY

While I was VSE SIG chair, I became concerned at the
difficulty beginning sites were having in running the batch
jobs.  I was faxing out and posting a lot of JCL.

My second objective was to reduce the amount of time TECH1's
have to spend in rewriting JCL and in debugging.  I had become
very tired of having to punch source to see what the files were
doing, what printers were needed, etc.  These things were
part of the reason NOTIS was perceived as a labor-intensive
system, costing NSI sales.

I suggested the following points for a rewrite of the JCL:

     Include a comment section at the beginning of each
         job that contains the purpose of the program,
         lists the files that are input/output/updated,
         and explains how to restart or recover in the
         event of step failure.
     Use a block of SETPARMs at the beginning of the job
         to tailor it.
     Include printer assignments, sort work DLBLs, and
         such so that a beginner can see what system
         resources are required for the job.  These can
         be stubs (e.g., INCLUDE YOUR SORT WORK FILE DLBL HERE).

NSI agreed to rewrite the JCL, at considerable manpower cost.
What we got, however, was not exactly what I had envisioned.
At my site, at least, the time cost of supporting NOTIS has
gone up, not down, and I'm not finding the procs to be as flexible
as I had hoped.  A lot of this problem results from using the
MVS JCL as a model and taking VSE along for the ride.

Here is a summary of the suggestions, taken from the texts
you will find below.

1)  Stop nesting procs.  Stop using procs at all, except for
    the very few cases where they make some marginal sense.
    Use SETPARMs for customizing the job instead (see Jim Cobbs'
    example below).  Another way to say this:  Make all VSE
    JCL inline.

2)  Include the basic printer assignments needed for the job
    in the JCL.

3)  Give a choice of disk or tape input/output for each job.

4)  Put sort work files -- or at least a stub -- in each job
    stream that includes a sort.

5)  Generic parameters should be used consistently across PROCs
    (SPACE and SRTSPC are bad offenders).  This applies equally
    well to SETPARMs.

6)  All JCL that creates temp datasets should delete such
    datasets at the conclusion of a run, or perhaps at the
    end of the job step in which they're processed.

7)  Temp datasets should be created such that they're deleted
    only if the program doesn't bomb to facilitate restart.

8)  The temp dataset naming convention should be changed to
    include the HLQ to accomodate multiple institution groups.

9)  Each job should contain a comment, placed immediately after
    the JOB statement, that identifies what it does.  Each proc
    should also contain such a comment.

10) If a STEP normally completes with a non-zero code or has
    some other unusual feature this should be explained in
    a comment.

11) Make the JOB name the same name under which the JCL is
    cataloged to improve communications between TECHs and NSI.

12) A parameter should be included for a catalog for sort work
    files and for temp work files (maybe named WORKCAT?).

13) The parms and DDNAMEs (or DLBLs) should be listed in
    alphabetical order at the beginning of the job.

Please post your comments to the list.  Remember that I need
lots of voices in this discussion if I am to convince NSI
that they should do any rewriting, so LET YOUR VOICE BE HEARD!

Our subject line for this discussion is VSE JCL.  Please be
sure to include it on your postings so that our colleagues can
skip these messages and so that I can compile them.  Also,
please include the number of the item above when you discuss
it so that I can tabulate the results.

May the postings begin,

Leigh
F_WILLIAMS@CCSVAX.SFASU.EDU


TEXT OF THE COMMENTS SENT TO ME TO DATE:

--------------------------------------------------------------------------
From: "James A. Cobbs" <JAC%WRLCVM.BITNET@AUVM.AMERICAN.EDU>

VSE stands for:
        Very
        Secure
        Employment

1.   STOP NESTING PROCS.  Stop using procs at all, except for a very few cases
where they make some marginal sense.  Please, please, please, pretty please.
I have taken to just getting the main PROC, copying in the sub-PROCs and making
the whole mess into a single in-line job stream.  I do this by setting up the
job like an in-line PROC under MVS.  This is done by using the // SETPARM
statement for any overrides I want/need.  For example:

* $$ JOB JNM=OVERLAY1,CLASS=Z,DISP=D,NTFY=(WRLCVM,HEINZ),SYSID=1
* $$ LST CLASS=A,DEST=(,HEINZ),SYSID=2
* $$ PUN CLASS=A,DEST=(,HEINZ),SYSID=2
// JOB  OVERLAY1
// LIBDEF *,SEARCH=(T51LMS.L51SRC,N51LMS.L51SRC,N502LMS.N50CNV)
/* ------------------ JOB OVERRIDES -------------------------------- *
// SETPARM DHLQ='NOTIS.WRLC'
// SETPARM MARCDSN='MARC.INPUT'
// SETPARM SYSPARM='BKG3439'
// SETPARM INUNIT=DISK
// SETPARM OUTUNIT=DISK
// SETPARM INPTFMT=OCLC
// SETPARM INPTTYP=UNSPAN
// SETPARM DTETAGS=005
// SETPARM RECS='1000,100'
// SETPARM SIZE=512K
// SETPARM SRTSIZE=1024K
// SETPARM INVOL=999999
// SETPARM OUTVOL=999999
// SETPARM WRKCAT=NOTISUC
/* ------------------ SYSTEM OPTIONS ------------------------------- *
// OPTION NODUMP
// ON $ABEND  GOTO EOJ
// ON $CANCEL GOTO EOJ
// ON $RC > 4 GOTO EOJ
// ASSGN SYS000,SYSLST
// ASSGN SYS007,SYSLST
// ASSGN SYS013,SYSLST
/* ----------------------------------------------------------------- *

        The above is a rather extreme example, but you can see how I make the
thing work.  If you want a complete, or less complex, example let me know.

2.  Maybe this only works with VSE/ESA, but as you can see from the example
above I have made basic printer assignments under the SYSTEM OPTIONS section.
I can't tell you how many jobs I've had fail while we were trying to get
going under VSE because there was no SYS007 or SYS013 assignment in the
'as delivered' JCL.  Putting these statements up front makes them work for
any and all subsequent job steps and you can override them in any specific
steps or just add power statements as required.  If they are not needed then
they don't cause a problem (as they would under MVS) but if they are needed
and have been left off by NSI then your tush is covered.Have NSI put these
override printer assignments at the top of each and every piece of JCL.

3.   NSI has got to realize that VSE isn't just for small sites anymore.  IBM
pricing of MVS and monster improvements in VSE/ESA have make it a viable, but
unpleasant, alternative to budget tight sites (read us).  This means that
NOT EVERY SITE WANTS OR NEEDS TO USE TAPE.  For god's (and my sanity's) sake
make _every_ program able to take disk as well as tape input.  I can't tell
you how many programs I've had to change to accept disk input -- and how many
I'll have to change again and again and again and again as each new release and
sub-release comes out.

4.   This might be a little difficult, but couldn't NSI put sort works into
steps that use sorts.  Sure there is IBM Sort and SYNCSORT and they have
differences, but there MUST be some 'skeleton' type of sort work statement
that could be used.  Maybe this would be an honest place for a PROC:  one
for IBM sort one for SYNCSORT, etc.  I think I remember you saying in some
note or another that you use * $$ INCLUDE or * $$ SLI type statements to
achieve the same thing.  Be nice to have a 'model' to work from in the
'as delivered' JCL.  Makes a BIG difference when you work with files our size.

--------------------------------------------------------------------------
From:         "Colegate V. Spinks" <ZCVS@ADM.ANGELO.EDU>

My preference with respect to JCL follows:
  1) Jobs should be distributed in two forms, disk only and tape only.
         The disk only JCL would be sufficent to run demonstrations, etc, while
         the tape only would be more likely the JCL used in the production
         environment.  It is foolish to beleive all production sites would use
         the tape only version and the same goes for the disk only. Users could
         develope their own version from one of these two.  ADVANTAGE:
 Eliminates
         a massive amount of the conditional JCL found in the jobs.  It is
         dificult at best to weed through some of the more complex jobs with a
         screen or two of conditional JCL prior to each executable step in the
         job.  Just becasue conditional JCL is possible does not mean you have
         to use it. DISADVANTAGE: A maintenance issue for NSI, multiple JCLs
         need to be tested for each "production job". I am sure that some users
         like the extent to which NSI has gone to make conditional JCL. I do
 not.
  2) PROCs. I feel that many times the jcl becomes dificult when trying to
         trace down through the procs. The general statements made by NIS is
 that
         PROCS usually do not call other procs except in cases like a sort step.
         I feel that in general all proces should be eliminated or at least
         minimized. At a bear minimum, eliminate the procs that call procs. If
         jcl is produced to eliminate/minimize conditional JCL, many of the
 cases
         were procs call procs will also be eliminated. ADVANTAGE: Easer to work
         with JCL as each deck is a functional unit. We are a VM/VSE site a keep
         all of our JCL at the VM level. It is difficult to review and work with
         jobs that use procs as we have no mechanism other that maint to review
         library members. This is not the case for ICCF users and VSE only
 users.
         DISADVANTAGE: None come to mind. I have not found a second level proc
         that was ever used by another job, which is the only reason why I would
         use procs.
  3) Eliminate some of the common parms.  It is a common pactice in our shop
         to make local mods to incomming procs and JCL at install time. Parms
         such as the highlevel qualifiers, volumes, etc could easily be modified
         as part of the installation process. DISADVANTAGE: NSI may have
 dificulty
         supporting JCL that has had such GLOBAL modifications made. Users may
         think that this is just a lot of work. ADVANTAGE: I have yet to get a
         NSI job to function is my environment out of the box. I have to go
         through and review all the jobs. Perhaps I am the odd ball and everyone
         else is running stock code as distributed.

--------------------------------------------------------------------------
From:         Dan Gillett <ZZGILLET%UVVM.UVIC.CA@VM.TCS.Tulane.EDU>

The call for suggested VSE coding standards to suggest to NOTIS should
be extended to include MVS coding standards.  NOTIS should be commended
for continuing to improve the modules as they are being re-written BUT
the MVS JCL is in my opinion still not up to par.  The following is a
suggested MVS standard that also applies in many aspects to VSE.
This is essentially our local JCL standard for all production systems.
It would require a fair bit of work to get this going but it would make
the JCL into a much more useful tool.  Sorry for the long note but this
is one of the "hot buttons" for both MVS and VSE Techies. Cheers, Dan.
========================================================================
MVS JCL Coding Goals
- To obtain consistency in coding methods thereby improving the
  readability and understanding of the cataloged procedure and
  its resultant run-time generated output.
- To obtain consistency not only within a specific PROC but
  also across all PROCs.
- To simplify modifications and testing of system changes and
  minimize PROC statement overrides by the user in the JOB deck.

Default Symbolic Parameters in Job Members
- all of the symbolic parameters should be assigned valid default
  values in HLQ.L51.CNTL job members to allow the jobs to be run
  on the test system with the addition of a JOB card and changing
  the "HLQ" etc in the JOB member only.
- all JCL/PROCs should be TYPRUN=SCANed at NOTIS prior to sending
  out the release (to avoid JCL errors).

PROC Statement
- all of the symbolic parameters used should be included in the
  procedure (PROC) statement IN ALPHAMERIC ORDER.
- symbolic parameters should be minimized as it is possible to
  customize PROC usage through DDNAME JOB deck overrides.

DD Statement
- Data Definition (DD) statements should be ORDERED ALPHABETICALLY
  by DDNAME within a step.
- Generic Parameters should be used consistently across PROCS
  (the new SPACE= and SRTSPC= parameters are the worst offenders).
- the order in which any keywords used should appear on the DD
  statement should be: DSN, DISP, UNIT, VOL, LABEL, SPACE,
  DCB (LRECL,BLKSIZE,RECFM,...), AMP

Temporary Datasets
- all PROCs that use temporary datasets should have one step deleting
  datasets left over from previous runs.
- temporary dataset naming convention should be changed slightly
  to accommodate a multiple institution strategy (e.g. LB300PRC name
  &HLQ..LB300010.TEMP would become &HLQ..LB300010.TEMP&GROUP).
- temporary datasets not needed at the end of step for subsequent
  steps or PROCs should be consistently deleted.
- all dataset names should should conform to a consistent naming
  strategy (they definitely don't now across all PROCs).

Comment Statements
- each HLQ.L51.CNTL JOB member should contain a minimum comment
  identifying what the job does.
- each PROC should contain a minimum comment identifying what
  what the PROC or STEP within a PROC does.
- comment statements should be placed consistently directly after
  the PROC or EXEC statement.
- if a STEP normally completes with a non-zero completion code
  or has some other unusual feature, this should be noted in a comment.

-------------------------------------------------------------------------
From:         "James A. Cobbs" <JAC%WRLCVM.bitnet@VM.TCS.Tulane.EDU>

         The basis on a vast majority of NSI's NOTIS job streams is the use
of PROCs, with nested PROCs in VSE, and PDS members in MVS, suppling imbedded
parameters, sorts commands, etc.  I would bet quite a few drinks at the next
NUGUM that most, if not all, of this comes from a mentality (and coding habits)
that date back to those wonderful days of yesteryear when tab cards reigned
surpreme.  For anyone who has ever worked with a big stack of jobs on tab cards
you can understand why PROCs seemed like the greatest thing since sliced bread.

         The thrust of all this is to pose a question to the list:  is there
ANYONE out there in NOTISland that still uses tab cards for submitting jobs
via a card reader?  If there is _no one_ out there doing this then I think
NSI should very seriously rethink their use of PROCs in their JCL.

         Due to the klugey nature of MVS JCL getting rid of PROCs entirely is
difficult (I usually ended up with my PROCs sitting in-line so I didn't have
to guess what's in them).  With VSE (well, at least the VSE/ESA we are
using) PROCs are not needed or useful (I do overrides using a // SETPARM
line).  If no one is using tab cards, then why are we still being delivered
a tab card oriented system?

          Send general comments to the list, hate mail to my address.

-------------------------------------------------------------------------
From: "James A. Cobbs" <JAC%WRLCVM.BITNET@AUVM.AMERICAN.EDU>

        I promised not to nit pick, but here is one thing I would like to see
NSI add, because I add it to the end of the code in almost every IDCAMS step:

   IF MAXCC = 8 THEN SET MAXCC = 0

The number could be any 'expected' value (8 is most common where you have
a DELETE/DEFINE and there is no old file to delete).  This forces the step
to have a return code of zero if, and only if, any part of the preceeding
code gives a return code of 8.  This means that up front I can have a
lines that says

// ON $RC > 4 GOTO EOJ

and I know that I have control of the execution of subsequent steps.

From:         Lee Harris <LEEHAR%LIBRARY.LIB.USU.EDU@VM.TCS.Tulane.EDU>

It would be nice if Notis would quit using PROCS.

I have rewritten most of the Notis jobs, because I do not like the PROCS.
Now when ever Notis sends out a new release it is a pain to check to make
sure that they haven't changed one of the jobs.

-------------------------------------------------------------------------
From:         Warren Van Wyck <WVW%UVMVM.bitnet@VM.TCS.Tulane.EDU>

On Tue, 5 Jan 1993 09:51:27 EDT James A. Cobbs said:
>                           With VSE (well, at least the VSE/ESA we are
>using) PROCs are not needed or useful (I do overrides using a // SETPARM
>line).
         Or just VSE/SP.
         I heartily second this suggestion -- it's always on the top of my
         requested changes for the VSE SIG group.
         The first action I take with any VSE job is de-PROC it.
         What works well (or just works) for MVS is a pain for VSE --
         NSI should tailor the JCL for the target system (and when will
         donkeys fly?).

-------------------------------------------------------------------------
From:         "Colegate V. Spinks" <ZCVS@ADM.ANGELO.EDU>

continued observations...
   I do not rember any other major points regarding JCL.  I often wonder
if there is a method to the madness in the manor in which NSI does the
JCL.  It may be that they are following some internal standard that makes
perfect sense to them but because we do not know the standard we do not
understand. It appears to me that MVS folks have a similar attitude toward
the JCL also.  I know from my point of view, the most troublesome part
of the NSI jcl is the conditional JCL first and second the embedded procs.
I view procs as a JCL equivalent to program subroutines. If used in more
than one place, code as a subroutine/proc. If only one place, code inline.
   We also make extensive use of standard labels when possible, being able
to place all of the DLBLs in the standard labels for NSI files would be
of intrest to us and would greatly simplify the JCL. We also place all of
our NSI files in a NSI catalog. In doing this, we can eliminate the need
to code the CAT part of the DLBL and in most of the IDCAMS. We have seperate
catalogs for testing and production. By simply changing the user catalog
we can run on either with unmodified JCL, with the exception of a few IDCAMS.
Otherwise we would need to maintain a set of JCL for each environment as
the catalogs are different.
   Lastly, this is should probably be somewere else. The choice of library
names on NSI part for the new code to load down. Well, this is nice, but
I would prefer that all the library names be the same between releases and
and not reflect the release level.  This requries that all JCL using the
libraries be modified for every release. This can be a real hassel and add
several days to the project.
   If more thoughts come to mind, I will let you know. Any questions, drop
a line. Latter.

-------------------------------------------------------------------------
From:         Alan Alexander-Manifold <ALANAM%PURCCVM.bitnet@VM.TCS.Tulane.EDU>

I certainly endorse the comments made about the consistency and testing
of JCL, but I want to make a point that I haven't seen in this current
discussion.  In an informal survey made last year of TECH1s from a number
of NOTIS sites, it became clear that each site has a different way of
dealing with JCL.  Many sites have shop standards, which don't agree
with each other.  Many sites use the PROCs as shipped.  Many others
pull the PROCs in-line.  Some places get rid of the PROCs altogether
and use straight in-line JCL.

In other words, there is nothing NOTIS can do that will make it so most
of us don't have to touch their JCL.  Because of local practices, most
of us change the JCL into our own format.  Personally, I would be satisfied
if the stuff they send us is of high quality and is consistent, both in
format and in content.  I believe NOTIS has taken great strides toward
meeting these goals, but they still have a ways to go.  On the other hand,
every time they revise the JCL, even if it is an improvement, it makes all
of us have to go back and redo our local versions to have consistent
PARMs, etc.  Once they get through it all and make it all consistent, won't
it be wonderful?

-------------------------------------------------------------------------
From:         "Colegate V. Spinks" <ZCVS@ADM.ANGELO.EDU>

And another thing... well, I just encountered this one again, stirs up old
memories. I wish NSI would use the same job name as the member name under
which it is cataloged. Usually it is close, with the exception of the first
two characters indicating the analyist at NSI responsible for the job.
Sometimes it is in the vicenity, the numbers are the same but no other
characters match, and others, well, no relationship at all.

I rember your discussion about your names at NUGM being diferent from NSIs,
well depending on who you talk to a NSI, they will reference one or the
other names. Usually the member name. Well when most systems use the job
name to generate banner sheets, it is dificult to match up what you thought
you ran with what you got back when the names do not match.

-------------------------------------------------------------------------
From:         "John P. Hauck" <GG.JPH%ISUMVS.bitnet@VM.TCS.Tulane.EDU>

I agree that what is good for MVS sites is not necessarily good for VSE
sites, and vice-versa!  I, for one, am tired of spending my life changing
JCL every time NOTIS sends out a new release.  Now that we have the PROCS in
place, lets leave the JCL alone.  If PROCS are not a good situation for VSE
sites, lobby NOTIS to change the VSE distribution, but please leave the MVS
distribution alone.

-------------------------------------------------------------------------
From:         Dan Gillett <ZZGILLET%UVVM.UVIC.CA@VM.TCS.Tulane.EDU>

MVS sites that are just starting to look at 5.1 should be aware that the
proclib contains 6 PROCs with actual hard JCL errors: LB391PRC, LB480PRC,
LB610PRC, LB790PRC, LD300PRC and LIF790PR.  In addition the new parameters
SPACE= and SRTSPC= are used in 6 different ways so you will need to look
at each PROC to see how to code these parameters.

I would also like to add my vote to an endorsement of PROCs.  What I object
to is the rather inconsistent way NOTIS codes the PROCs they give us.
You would think that they could get 101 PROCs is order!

-------------------------------------------------------------------------
From:         VAUGHAN%VUCTRVAX.bitnet@VM.TCS.Tulane.EDU

   I believe NOTIS is aware of errors and inconsistencies in
the JCL, and they are trying to correct the problems. The
discussion at the VSE Sig meeting during NUGM began as a
result of a meeting the sig chairs had with TeamNOTIS. There
seems to be a problem for VSE sites using procs, and NOTIS
asked if we could first determine if this is the case for
most, or all, VSE sites, and then come up with a workable
alternative. I think this was the reason for Leigh's request
for input from VSE sites. We are trying to resolve the
problem of using procs on a VSE system, as opposed to defining
overall standards for all NOTIS JCL. If we ask NOTIS to eliminate
procs from the VSE JCL, this will also involve setting some
standards that will most likely be different from those in
the MVS JCL.

-------------------------------------------------------------------------
From:         "James A. Cobbs" <JAC%WRLCVM.bitnet@VM.TCS.Tulane.EDU>

        A long time ago when I first started working NOTIS in Release 4.5 (I
believe, but NOTIS tends to rot the memory) they shipped all the MVS
stuff with in-line PROCSs.  Silly me, I spent a bunch of time setting
up a PROCLIB and decanting the PROCs into it.  Then I spent a bunch
of time putting them back because they were so buggy that this was
the easyest way to handle test and debug.  Subsequent releases have
come and gone and while I worked with MVS I kept finding myself putting
the PROCs back in-line for easier modification/debug.  Since MVS's JCL, unlike
the superior VSE JCL, doesn't allow in-line data in PROCS, nor the calling
of PROCs from PROCs (a really dubious virtue) MVS sites have the
added problem of keeping up with hundred(s) of small PDS members that
supply job parms, sort commands, etc.  If I we were still a MVS shop I
would recommend going back to in-line PROCs as the easiest way for NSI
to distribute.  MVS, internally, may (or may not) be a great operating
system but the JCL still goes back to the Kennedy Administration and is
the ultimate in user-unfriendlyness:  good luck guys, you'll need it.

        NSI is going to have to face a cruel reality:  VSE is not MVS.  Some
things are very good; some very bad.  Access to members in a library (well,
library/sublibrary for you purists) is far more difficult than in MVS and
therefore maintaining cataloged PROCs is not a pretty picture.  As I
indicated in my earlier note, I've taken to doing the equivalent of in-line
PROCs in VSE to take advantage of override capabilities.  If we were a small
shop I doubt I would even do this;  but we are quite large and this has to
be taken into consideration.  NSI uses nested PROCs in VSE to _simulate_
the kludgey MVS PDS parm members: Boooo.

        The net of all this verbage is my feeling that NSI should:  (1) deliver
MVS with in-line PROCs; and in VSE they should at least stop using nested
PROCs as they are not needed and a real pain in the tush.  VSE's JCL needs
a lot more, but these thoughts have been sent to the appropriate TeamNOTIS
member as a personal note.

-------------------------------------------------------------------------
From:         "Colegate V. Spinks" <ZCVS@ADM.ANGELO.EDU>

and another thing...
  I realize this may be nit picking, but, it is considered sloppy
  programming in our shop to use implicite file definations.  We do
  all of our file definations using IDCAMs defines. It makes it
  easier to see what is going on rather than the implicite defines.

I wonder how others feel on this one?
-------------------------------------------------------------------------
Comments: Gated by NETNEWS@AUVM.AMERICAN.EDU