RCF sent. There is a similar problem when an author describes invoking something from CLIST, JCL or REXX, describes syntax and gets it wrong. That is an issue that has contined from OS/360 to z/OS.
-- Shmuel (Seymour J.) Metz http://mason.gmu.edu/~smetz3 ________________________________________ From: IBM Mainframe Discussion List [IBM-MAIN@LISTSERV.UA.EDU] on behalf of Tony Harminc [t...@harminc.net] Sent: Friday, February 4, 2022 7:20 PM To: IBM-MAIN@LISTSERV.UA.EDU Subject: Re: Does this make no sense or is it just me? On Fri, 4 Feb 2022 at 18:07, Charles Mills <charl...@mcn.org> wrote: > > Does the following make sense to anyone? From the JCL Reference, at least > several recent versions including V2R5, Chapter 6. Job control statements on > the output listing. It seems boggled to me on several levels. I don't think > it is true, and I think the references to specific programs are superfluous > (or alternatively, incomplete). Am I off base? > > EXEC overriding parameters: A procedure EXEC statement appears in the job > log listing exactly as it > appears in the procedure. Overridden parameters must be shown by the program > being executed: > > . For the EXEC statement that executes the assembler program, the Diagnostic > Cross Reference and > Assembler Summary produced by the assembler program shows the overriding > parameters. > > . For the EXEC statement that executes the linkage editor, the linkage > editor listing shows the overriding > parameters. I think this is probably a classic result of the interaction among product developers, tech writers, and support/change team people. Certainly it's not correct, but more than that, I think it just reflects this uneasy mix of people with the same high level goal but different understanding. I speculate: Someone probably complained to IBM that the EXEC statement in the JCL listing doesn't directly show the result of the various substitutions that are possible. (Of course there are the SUBSTITUTION JCL messages, but they're virtulaly unreadable.) Someone in JCL (what I think of as the IEF team) said "well of course we don't show that - it's up to the program being invoked to show its own arguments after everything is resolved. For example, the assembler shows that stuff right at the top." The tech writers didn't really understand that, but went to the ASM people and asked how to explain the example of showing the overriding parameters. Someone there told them it's under the rubric "Diagnostic Cross Reference and Assembler Summary" So they put that in the book as an example, and then someone else complained that there is no example for the linkage editor. So they put that in. Then someone complained about something else, and they thought, OK, enough, and stopped putting in examples. What's obviously missing is someone with the big picture who would understand that the level of explanation and examples is all wrong, and that a more general explanation of how *any* program you invoke *may* provide a listing of its arguments, but that what the JCL resolves to is found in those SUBSTITUTION JCL messages. Just maybe a reminder about MSGLEVEL would be appropriate. I see this all the time for much smaller products that I work on; the tech writers are forever trying to clean up and organize while responding to complaints and requests for clarification from customers and Support. They think of themselves as the core of the document production process, who refer to SMEs (Subject Matter Experts) for the technical nitty-gritty. But no amount of technical detail is enough by itself when the overall view is missing. Who should provide that? It depends on the sizee and nature of the organization. Ideally one needs a single senior developer who is very competent in written English as well as both the immediate subject matter and the larger environment both technical and documentary. And who isn't spending 120% of his/her time on writing code. So it goes. Tony H. ---------------------------------------------------------------------- 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
