On Jul 1, 2005, at 7:51 AM, Shmuel Metz (Seymour J.) wrote:
In <[EMAIL PROTECTED]>, on 06/30/2005
at 10:55 PM, Joe Zitzelberger <[EMAIL PROTECTED]> said:
TSO/ISPF is about as least common denominator as you can get.
The Sun rises in the East. ISPF is not the issue. The issue is the
contents of the listing file. Which, by the way, is normally a SYSOUT
file viewed through SDSF.
Viewing output datasets in SDSF can be done in four ways. There is
the SE command that opens the spool dataset using ISPF Edit. There
is the SB command that opens the spool dataset using ISPF Browse.
There is the S command that formats the dataset for a line printer
and browses it in an SDSF specific, but ISPF work-alike browser. And
there is the V command that formats the dataset for a page printer
and browses it in the same SDSF specific, ISPF work-alike browser.
For purposes of online viewing V, S and SB are identical in
function. There is one quirk that is germane to the discussion -- in
ISPF browse the command to show hex is "hex on" -- in the S and V
browse the command is "set hex on". Otherwise, when used to browse a
listing they are identical. The only visual indication of difference
between the two browsers is some slightly different stuff in the
first two header rows -- one says something like "ISPF Browse" and
the other doesn't.
The ISPF Edit, SE, makes the data editable, though not save-able.
The various ISPF edit commands like CREATE, REPLACE, CUT, EXCLUDE,
etc are available as well as the users custom edit macros, like the
ever-present INCLUDE (props to D.Lowe).
Anyway, those are the minimum you will have with TSO or ISPF. There
is no circumstance where a programmer is unable to easily see the hex
values of any byte in the listing.
(FYI -- If you can't get these functions working with SDSF, if you
get an "EDIT NOT AVAILABLE" message, try starting SDSF via ISPEXEC
instead of TSO)
Here is a brief example of the problem, viewed through the eyes of
ISPF, with a spool dataset listing:
That's not something that a COBOL programmer would be likely to do;
he's either direct it to DASD or view it with SDSF. Further, if he
didn't know about DBCS, he'd have no idea what SI and SO were and
wouldn't know to use a hexadecimal editor.
That was viewing it with SDSF.
The shift is included in the literal in the listing and the messages
are shown following the offending line and the column is clearly
described.
I don't what the column clearly described, and want the error and
programmer response clearly described.
There is an old joke -- A man walks in to a doctors office and twists
his arms above his head. He says "Doc, it hurts when I go like
this". The doctor says "So don't go like that". Not very funny --
it really depends on delivery.
Syntax errors are like this -- an END-IF without an IF, an unmatched
quote, unmatched apostrophe, unbalanced parenthesis or unbalanced
shift. The compiler is simply saying that your source didn't match
it's syntax -- when your source does match it's syntax, the compiler
will stop complaining.
The solution is in the message: "don't go like that".
The questioner was not necessarily conversant with Cobol at all.
Many people writing COBOL (not Cobol) are not conversant with COBOL;
they're part of the target audience.
Pronounceable acronyms tend to become "worded" after many years of
common use. I will cite the Merriam-Webster dictionary to support
the word-like usage. See also radar, laser and scuba.
If a person writing Cobol is not conversant with Cobol then the best
thing that can happen to them is a "Read the LRM" message. It is not
unusual, or unreasonable, to expect people who are using any tool to
briefly scan the instructions first. Compilers are not chain-saws,
but the do offer the opportunity to injure ones foot in the
figurative sense.
I'm not sure if non-Cobol programmers would qualify as a
representative sample of people who should understand Cobol compiler
messages. If they do, then all messages should be annotated --
"programmer response: learn Cobol".
That would be singularly unhelpful, which is no surprise. Programmers,
including COBOL programmers, typically learn only the parts of the
language that they use. They are often unprepared for error messages
referring to language features that they did not intend to use or
don't even know about.
That is what IBM makes, freely available and electronically
searchable, the Language Reference Manual and Programmers Guide.
One can become so incapacitated trying to remember every little
detail of everything that they completely miss the big picture. The
old forest for the trees syndrome. SHIFT-IN and SHIFT-OUT are
special registers that are well described in the above guides. One
doesn't need to know anything about eastern character sets or DBCS to
know that they operate in pairs -- just like QUOTE, APOS and parens.
Using your theory above, one would think that a programmer moving
from an APOS to a non-APOS shop would be paralyzed with fear at the
sight of "" characters?
What more could possibly be said in a message manual?
Can you read? I've repeatedly explained what more could be included in
the message.
You have repeatedly asked for things that are already provided by the
current message.
The message could provide context for a programmer who
doesn't know about DBCS.
The message does provide context for the programmer, it is placed at
the source of the error and no knowledge of DBCS is required.
The message could provide the bad text in hexadecimal.
The listing already provides the 'bad text' with the message. You
seem unwilling to look at it, but the compiler has placed it there
nonetheless.
For that matter, the message could point to the SI
instead of expecting a COBOL program to properly offset it in a
hexadecimal display. You do understand that the column in the listing
is not generally the same as the column in the source, don't you?
I'm not sure what sort of Cobol listings you are looking at -- you
mentioned COBOL-E a few times -- the listing might have changed
slightly since that release. There is no trouble finding the source
column offset in the listing. The current offering has those little
area-A/area-B/cols/ruler thingies in the listing.
The message points you to the exact byte in error and says "this
looks funny to me, but I'll trust you want it there and accept it as
written". What could you say about it?
Any competent technical writter could tell you that.
Competent technical writers are a rare breed...
"Read the LRM" seems like the only polite thing that could be
written.
Indeed, to one who doesn't understand how to do documentation. I and
others have described other things that could be written, e.g.,
1. Brief explanations of DBCS and related compiler options
2. Suggestion to read the literal in hexadecimal
The LRM provides both of these in Chapter 3, "Character Strings" has
two related sections that would provide more than enough information.
The first section is "Special-Registers" where SHIFT-IN and SHIFT-OUT
are documented, discussed and shown in paired usage.
The second section is "Literals" that is pretty much required reading
for anyone using any kind of literals. It briefly discusses how
numeric, null-terminated, DBCS, alphanumeric, hex and national
literals are constructed and where they can be used. It also has
examples like <example>"this is right"</example> and <example>'this
is wrong"</example>.
Either of these sections will provide any programmer, and some non-
programmers, plenty of information about SI and SO in literals. And
it is very hard to code useful Cobol without having viewed this
chapter, or one like it, at some point in time.
Just for fun I took a look at the over-hyped PL/I messages and codes
manual. I don't have a PL/I compiler handy, but I searched for
"shift-in" and "shift-out" and this is what I found.
IBM3974S Every shift-in character after the left
margin of a source line must have a matching shift-out
character before the right margin of the same line.
Explanation: DBCS shift codes must be paired.
IBM3975S Every shift-in character within a string
generated for rescan must have a matching shift-out
character within that same string.
Explanation: DBCS shift codes must be paired.
It seems that the best the PL/I technical writers were able to do was
to restate the message.
No explanation of DBCS and related compiler options.
No suggestion to view the literal in hexadecimal.
Just a simple restatement of the original message in different
terms. Not very useful.
Either their technical writers are as dumb as the average Cobol
programmer or there truly are 'self-evident' message in the problem
space of computer programming.
(I might need to open a ticket with IBM though, that part about
"rescan" in IBM3975S. It is confusing to non-PL/I programmers.)
There is a tendency to use message manuals as a crutch to avoid
thinking about problems. Had this been a PL/I program the only
result of looking at the manual would have been wasted time learning
what the message had already said. All the information is in the
listing, someone just needs to read it.
If a magic book with all the answers was possible in software
development, people would be unnecessary...
----------------------------------------------------------------------
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
