On Fri, 5 Jun 2020 08:50:21 -0700, Charles Mills wrote:
>As a guy who has written a lot of documentation I think I would rather include
>some excess verbiage and save user frustration and/or a support call.
>
>It is a judgment call. You can overdo the redundancy. I have a VS COBOL manual
>and it includes thorough instructions for writing link editor DD statements.
>You certainly do not want to include redundant documentation that then becomes
>wrong when the "other product" changes.
>
>Perhaps the verbiage you quote should go in a "usage note" or something like
>that.
>
Or a cross-reference to the earlier Syntax description.
I disagree. This is akin to expecting every paragraph in a C Language reference
to aver, "All identifiers mentioned must be declared".
The paragraph could be included in the description of every command and most
functions. If it appears in some, but not all, the reader is invited to
presume by
"The Exception That Proves the Rule,"
https://en.wikipedia.org/wiki/Exception_that_proves_the_rule
that it does not apply to other commands.
-- gil
>Charles
>
>
>-----Original Message-----
>From: IBM Mainframe Discussion List [mailto:IBM-MAIN@LISTSERV.UA.EDU] On
>Behalf Of Paul Gilmartin
>Sent: Friday, June 5, 2020 8:30 AM
>To: IBM-MAIN@LISTSERV.UA.EDU
>Subject: Gratuitous EXECIO Documentation
>
>In:
>https://www.ibm.com/support/knowledgecenter/SSLTBW_2.3.0/com.ibm.zos.v2r3.ikja300/dup0037.htm
>
>I see the verbiage:
> When you use EXECIO, you must ensure that you use quotation marks
> around any operands, such as DISKW, STEM, FINIS, or LIFO. Using
> quotation marks prevents the possibility of the operands being substituted
> as variables. For example, if you assign the variable stem to a value in
> the exec and then issue EXECIO with the STEM option, if STEM is not
> enclosed in quotation marks, it is substituted with its assigned value.
>
>Sheesh! A similar caution might be included for any command in the Ref.,
>but it doesn't belong.
>
>"must ensure"? Well, not always.
>
>I infer the etiology: A troublesome user once coded:
> STEM=SKIP /* perhaps */
> EXECIO ...
>... got astonishing results; went to SR; got fully proper "REJ; RTFM";
>vindictively submitted RCF. A feckless tech writer acceded and added
>the paragraph.
>
>I strongly suspect the matter is covered properly earlier (citation needed)
>in the Ref., which shouldn't be cluttered with such errant rubbish.
>
>(I was reading that Ref. to see whether EXECIO assembles segments
>of V[B]S records. Didn't find it.)
>
>-- gil
>
>----------------------------------------------------------------------
>For IBM-MAIN subscribe / signoff / archive access instructions,
>send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN
>
>----------------------------------------------------------------------
>For IBM-MAIN subscribe / signoff / archive access instructions,
>send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN
----------------------------------------------------------------------
For IBM-MAIN subscribe / signoff / archive access instructions,
send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN
