The problem with much computer documentation, including much of z/OS's, is
that it is feature- rather than task-oriented. That is, the documentation
does a perfect job of answering the question "so, what does the IEABRC
macro
do and how do you code it?" and a terrible job of answering the question
"so, you're facing base register constraint, what do you do?" and "okay,
you
converted your open code to use jump instructions but you are now getting
errors on the system macros, what do you do?"
You're right. I suspect that part of the solution is being attempted in the
"guides" and part of it in the Redbooks. There's no question that there is
a deficiency when a specific task is necessary to be performed. Looking for
an answer isn't always obvious.
Another problem, frankly, with the z/OS documentation is the
fragmentation.
The fragmentation of the documentation -- what is in MVS, what is in
JES2/3,
what is in DFSMS? -- only makes sense if you already know the answer to
the
question "does what I want to accomplish have an MVS solution or a JES
solution or a DFSMS solution?" Explain to me how anyone who didn't already
know would guess that the function to copy a dataset would not be a base
part of the operating system (i.e., a part of MVS rather than an "add-on"
product, DFSMS)? How would you guess that OPEN would be DFSMS but DYNALLOC
would be MVS?
Once again you're right, but your statement also contains a fragment of the
answer. Why are you "pondering" a systems programming "solution" if you
don't know which component controls the function? I'm presuming that if you
are coding in assembler and using OPEN or DYNALLOC that you should also know
which components are involved and where to look. In most cases, this
knowledge is gained from classes or mentors who also (presumably) are
indicating the source of the documentation.
I understand your point and agree with you in principle, but z/OS
documentation was never intended to be simply a cookbook of "how-to" tasks.
Given a sufficient degree of complexity, then the onus is on the user to
know where to look. I really don't think its a good idea to write assembler
programs and not know the instructions are in the Princ of OPs. I don't
think its a good idea to customize PARMLIB and not know about Init and
Tuning.
If you're experienced then you already know about the fragmentary nature of
documentation (for ALL vendors) and a search engine can quickly help you
narrow down the scope of your search. In other words, a quick search for
DYNALLOC will answer your question, as would a search for OPEN. You don't
need to know which component it belongs to. Only how to do a search. It
seems that the majority of my time in manuals is using search arguments,
since I can't assume that I'm always aware of every potential source of
documentation. A quick review of returned titles usually indicates in short
order which manual contains what I really need. The primary exception is
when the function isn't documented at all.
There are many ways in which the documentation might be improved. Certainly
some of the organization is bizarre (ie: DCB control block in DFSMS, rather
than Data Areas?). I would also like to see much more technical
documentation approaching that of the PLM's but that's just a fantasy on my
part these days.
In comparison to other vendors ... I'd be happy just to have a messages and
codes book for Windows :)
Adam
----------------------------------------------------------------------
For IBM-MAIN subscribe / signoff / archive access instructions,
send email to [EMAIL PROTECTED] with the message: GET IBM-MAIN INFO
Search the archives at http://bama.ua.edu/archives/ibm-main.html
