subject:"Gratuitous EXECIO Documentation"

On Fri, 5 Jun 2020 18:11:42 +, Seymour J Metz wrote:

>> Your statement implies that "sometimes" it is legitimate to not use quotes. 
>
>In fact, sometimes it is mandatory to not use them.
>
>Your suggested wording has the same issue as what is in the manual; it 
>prescribes rules that aren't always appropriate. The REXX Reference manual has 
>a perfectly adequate description of how REXX evaluates expressions: refer the 
>reader to that. Don't invent rules that sometimes don't apply.
>
>The root problem is that someone is writing code without understanding the 
>language.
> 
The PDFs and web pages are pretty good at handling internal references.
Imagine, instead, where appropriate:
" ... an expression (see 
)
which represents a [symbol|command|...].

-- gil

--
For IBM-MAIN subscribe / signoff / archive access instructions,
send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN

Re: Gratuitous EXECIO Documentation

The frequency is irrelevant, although there is a huge amount of REXX code that 
deals with the name of a variable. If you don't understand the language then 
you will inevitably shoot yourself in the foot, and that applies to more than 
REXX.


--
Shmuel (Seymour J.) Metz
http://mason.gmu.edu/~smetz3


From: IBM Mainframe Discussion List [IBM-MAIN@LISTSERV.UA.EDU] on behalf of 
Tony Thigpen [t...@vse2pdf.com]
Sent: Friday, June 5, 2020 2:29 PM
To: IBM-MAIN@LISTSERV.UA.EDU
Subject: Re: Gratuitous EXECIO Documentation

No, the problem is not an understanding of how REXX evaluates expressions.

The problem is that EXECIO is one of the few places that a variable NAME
is an operand, not the variable CONTENTS.

Tony Thigpen

Seymour J Metz wrote on 6/5/20 2:11 PM:
>> Your statement implies that "sometimes" it is legitimate to not use quotes.
>
> In fact, sometimes it is mandatory to not use them.
>
> Your suggested wording has the same issue as what is in the manual; it 
> prescribes rules that aren't always appropriate. The REXX Reference manual 
> has a perfectly adequate description of how REXX evaluates expressions: refer 
> the reader to that. Don't invent rules that sometimes don't apply.
>
> The root problem is that someone is writing code without understanding the 
> language.
>
>
> --
> Shmuel (Seymour J.) Metz
> http://mason.gmu.edu/~smetz3
>
> 
> From: IBM Mainframe Discussion List [IBM-MAIN@LISTSERV.UA.EDU] on behalf of 
> Tony Thigpen [t...@vse2pdf.com]
> Sent: Friday, June 5, 2020 2:03 PM
> To: IBM-MAIN@LISTSERV.UA.EDU
> Subject: Re: Gratuitous EXECIO Documentation
>
> Sorry, but I disagree.
>
> Your statement implies that "sometimes" it is legitimate to not use
> quotes. I would say that "sometimes you can get lucky and get away with
> not using quotes". :-)
>
> A very basic documentation statement would be:
>  Some formats of the EXECIO command may reference a variable
>  by the name of the variable. Such references should be
>  within quoted text. Such an example is the variable name
>  of a stem variable:
>  Correct:
>'EXECIO 5 DISKW' ddname '(STEM MYSTEM.'
>  Incorrect:
>'EXECIO 5 DISKW' ddname '(STEM' mystem.
>  Use without quotes can result in unpredictable results.
>
>
> I really think this is the root problem, not the fact that someone
> defined a variable with the same name as a common keyword, such as your
> example with "STEM". Such an example is just part of the language
> restriction and not directly related to EXECIO.
>
>
> Tony Thigpen
>
> Seymour J Metz wrote on 6/5/20 12:56 PM:
>> My problem with gratuitous documentation is that they invariably get it 
>> wrong. Describe the actual requirements and direct the reader to the 
>> appropriate places for details. In this case, something like:
>>
>>   As with any command issued to an external environment, ensure that the
>>   expression you use evaluates to the intended EXECIO command. In
>>   particular, it may be prudent to always quote keywords to avoid
>>   confusion with variables with the same name.  For example, if you 
>> assign
>>   the variable "stem" to a value other than 'STEM' and then use
>>
>>   EXECIO 5 DISKW ddname '(' STEM
>>
>>   instead of
>>
>>   EXECIO 5 DISKW ddname '( STEM'
>>
>>   in your code, you will not invoke the correct command.
>>
>> Would be reasonable if they have to spell it out.
>>
>>
>>
>> --
>> Shmuel (Seymour J.) Metz
>> http://mason.gmu.edu/~smetz3
>>
>> 
>> From: IBM Mainframe Discussion List [IBM-MAIN@LISTSERV.UA.EDU] on behalf of 
>> Paul Gilmartin [000433f07816-dmarc-requ...@listserv.ua.edu]
>> Sent: Friday, June 5, 2020 11:29 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
&g

Re: Gratuitous EXECIO Documentation

The inappropriate absence or use of quotes will break the code. I don't know 
whether ICCF is comparable, but with ISPF it is bog standard to use ISPEXEC and 
ISREDIT commands that require the names of variables.

With EXECIO, adding quotes will either fix *or break* the code, depending on 
what the code is doing. There is no substitute for understanding and 
*accurately* explaining the rules of the language, and that is by no means 
limited to REXX.


--
Shmuel (Seymour J.) Metz
http://mason.gmu.edu/~smetz3


From: IBM Mainframe Discussion List [IBM-MAIN@LISTSERV.UA.EDU] on behalf of 
Tony Thigpen [t...@vse2pdf.com]
Sent: Friday, June 5, 2020 2:35 PM
To: IBM-MAIN@LISTSERV.UA.EDU
Subject: Re: Gratuitous EXECIO Documentation

To say it another way.
Normally the use of quotes around a variable will *break* the code. With
EXECIO, use of quotes will *fix* the code.

Tony Thigpen

Tony Thigpen wrote on 6/5/20 2:29 PM:
> No, the problem is not an understanding of how REXX evaluates expressions.
>
> The problem is that EXECIO is one of the few places that a variable NAME
> is an operand, not the variable CONTENTS.
>
> Tony Thigpen
>
> Seymour J Metz wrote on 6/5/20 2:11 PM:
>>> Your statement implies that "sometimes" it is legitimate to not use
>>> quotes.
>>
>> In fact, sometimes it is mandatory to not use them.
>>
>> Your suggested wording has the same issue as what is in the manual; it
>> prescribes rules that aren't always appropriate. The REXX Reference
>> manual has a perfectly adequate description of how REXX evaluates
>> expressions: refer the reader to that. Don't invent rules that
>> sometimes don't apply.
>>
>> The root problem is that someone is writing code without understanding
>> the language.
>>
>>
>> --
>> Shmuel (Seymour J.) Metz
>> http://mason.gmu.edu/~smetz3
>>
>> 
>> From: IBM Mainframe Discussion List [IBM-MAIN@LISTSERV.UA.EDU] on
>> behalf of Tony Thigpen [t...@vse2pdf.com]
>> Sent: Friday, June 5, 2020 2:03 PM
>> To: IBM-MAIN@LISTSERV.UA.EDU
>> Subject: Re: Gratuitous EXECIO Documentation
>>
>> Sorry, but I disagree.
>>
>> Your statement implies that "sometimes" it is legitimate to not use
>> quotes. I would say that "sometimes you can get lucky and get away with
>> not using quotes". :-)
>>
>> A very basic documentation statement would be:
>>  Some formats of the EXECIO command may reference a variable
>>  by the name of the variable. Such references should be
>>  within quoted text. Such an example is the variable name
>>  of a stem variable:
>>  Correct:
>>'EXECIO 5 DISKW' ddname '(STEM MYSTEM.'
>>  Incorrect:
>>'EXECIO 5 DISKW' ddname '(STEM' mystem.
>>  Use without quotes can result in unpredictable results.
>>
>>
>> I really think this is the root problem, not the fact that someone
>> defined a variable with the same name as a common keyword, such as your
>> example with "STEM". Such an example is just part of the language
>> restriction and not directly related to EXECIO.
>>
>>
>> Tony Thigpen
>>
>> Seymour J Metz wrote on 6/5/20 12:56 PM:
>>> My problem with gratuitous documentation is that they invariably get
>>> it wrong. Describe the actual requirements and direct the reader to
>>> the appropriate places for details. In this case, something like:
>>>
>>>   As with any command issued to an external environment, ensure
>>> that the
>>>   expression you use evaluates to the intended EXECIO command. In
>>>   particular, it may be prudent to always quote keywords to avoid
>>>   confusion with variables with the same name.  For example, if
>>> you assign
>>>   the variable "stem" to a value other than 'STEM' and then use
>>>
>>>   EXECIO 5 DISKW ddname '(' STEM
>>>
>>>   instead of
>>>
>>>   EXECIO 5 DISKW ddname '( STEM'
>>>
>>>   in your code, you will not invoke the correct command.
>>>
>>> Would be reasonable if they have to spell it out.
>>>
>>>
>>>
>>> --
>>> Shmuel (Seymour J.) Metz
>>> http://mason.gmu.edu/~smetz3
>>>
>>> 
>>> From: IBM Mainframe Discussion List [IBM-MAIN@LISTSERV.UA.EDU] on
>>> behalf of Paul Gilmarti

Re: Gratuitous EXECIO Documentation

Well, maybe. If foo = 'DISKR' then foo is right and 'foo' is wrong.

I think that is the point that others are making: there is no way to
"explain how to code EXECIO" without explaining how Rexx works.

Charles

-Original Message-
From: IBM Mainframe Discussion List [mailto:IBM-MAIN@LISTSERV.UA.EDU] On
Behalf Of Tony Thigpen
Sent: Friday, June 5, 2020 11:35 AM
To: IBM-MAIN@LISTSERV.UA.EDU
Subject: Re: Gratuitous EXECIO Documentation

To say it another way.
Normally the use of quotes around a variable will *break* the code. With 
EXECIO, use of quotes will *fix* the code.

Tony Thigpen

Tony Thigpen wrote on 6/5/20 2:29 PM:
> No, the problem is not an understanding of how REXX evaluates expressions.
> 
> The problem is that EXECIO is one of the few places that a variable NAME 
> is an operand, not the variable CONTENTS.
> 
> Tony Thigpen
> 
> Seymour J Metz wrote on 6/5/20 2:11 PM:
>>> Your statement implies that "sometimes" it is legitimate to not use 
>>> quotes.
>>
>> In fact, sometimes it is mandatory to not use them.
>>
>> Your suggested wording has the same issue as what is in the manual; it 
>> prescribes rules that aren't always appropriate. The REXX Reference 
>> manual has a perfectly adequate description of how REXX evaluates 
>> expressions: refer the reader to that. Don't invent rules that 
>> sometimes don't apply.
>>
>> The root problem is that someone is writing code without understanding 
>> the language.
>>
>>
>> -- 
>> Shmuel (Seymour J.) Metz
>> http://mason.gmu.edu/~smetz3
>>
>> ____
>> From: IBM Mainframe Discussion List [IBM-MAIN@LISTSERV.UA.EDU] on 
>> behalf of Tony Thigpen [t...@vse2pdf.com]
>> Sent: Friday, June 5, 2020 2:03 PM
>> To: IBM-MAIN@LISTSERV.UA.EDU
>> Subject: Re: Gratuitous EXECIO Documentation
>>
>> Sorry, but I disagree.
>>
>> Your statement implies that "sometimes" it is legitimate to not use
>> quotes. I would say that "sometimes you can get lucky and get away with
>> not using quotes". :-)
>>
>> A very basic documentation statement would be:
>>  Some formats of the EXECIO command may reference a variable
>>  by the name of the variable. Such references should be
>>  within quoted text. Such an example is the variable name
>>  of a stem variable:
>>  Correct:
>>    'EXECIO 5 DISKW' ddname '(STEM MYSTEM.'
>>  Incorrect:
>>    'EXECIO 5 DISKW' ddname '(STEM' mystem.
>>  Use without quotes can result in unpredictable results.
>>
>>
>> I really think this is the root problem, not the fact that someone
>> defined a variable with the same name as a common keyword, such as your
>> example with "STEM". Such an example is just part of the language
>> restriction and not directly related to EXECIO.
>>
>>
>> Tony Thigpen
>>
>> Seymour J Metz wrote on 6/5/20 12:56 PM:
>>> My problem with gratuitous documentation is that they invariably get 
>>> it wrong. Describe the actual requirements and direct the reader to 
>>> the appropriate places for details. In this case, something like:
>>>
>>>   As with any command issued to an external environment, ensure 
>>> that the
>>>   expression you use evaluates to the intended EXECIO command. In
>>>   particular, it may be prudent to always quote keywords to avoid
>>>   confusion with variables with the same name.  For example, if 
>>> you assign
>>>   the variable "stem" to a value other than 'STEM' and then use
>>>
>>>       EXECIO 5 DISKW ddname '(' STEM
>>>
>>>   instead of
>>>
>>>   EXECIO 5 DISKW ddname '( STEM'
>>>
>>>   in your code, you will not invoke the correct command.
>>>
>>> Would be reasonable if they have to spell it out.
>>>
>>>
>>>
>>> -- 
>>> Shmuel (Seymour J.) Metz
>>> http://mason.gmu.edu/~smetz3
>>>
>>> 
>>> From: IBM Mainframe Discussion List [IBM-MAIN@LISTSERV.UA.EDU] on 
>>> behalf of Paul Gilmartin 
>>> [000433f07816-dmarc-requ...@listserv.ua.edu]
>>> Sent: Friday, June 5, 2020 11:29 AM
>>> To: IBM-MAIN@LISTSERV.UA.EDU
>>> Subject: Gratuitous EXECIO Documentation
>>>
>>> In: 
>>>
https://www.ibm.com

Re: Gratuitous EXECIO Documentation

2020-06-05 Thread Steve Smith

I think there are two issues:

1. REXX variables do not act like they do in any other language.  The
default of x == 'X' is an invitation to make land mines.

2. Documentation is really tough to get right.  Not enough, and it's
confusing; too much, and tl;dr kicks in.  And that's just the problem with
good, accurate documentation.  There's usually other issues, up to and
including the random GRXBIMG.

sas

--
For IBM-MAIN subscribe / signoff / archive access instructions,
send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN

Re: Gratuitous EXECIO Documentation


To say it another way.
Normally the use of quotes around a variable will *break* the code. With 
EXECIO, use of quotes will *fix* the code.


Tony Thigpen

Tony Thigpen wrote on 6/5/20 2:29 PM:

No, the problem is not an understanding of how REXX evaluates expressions.

The problem is that EXECIO is one of the few places that a variable NAME 
is an operand, not the variable CONTENTS.


Tony Thigpen

Seymour J Metz wrote on 6/5/20 2:11 PM:
Your statement implies that "sometimes" it is legitimate to not use 
quotes.


In fact, sometimes it is mandatory to not use them.

Your suggested wording has the same issue as what is in the manual; it 
prescribes rules that aren't always appropriate. The REXX Reference 
manual has a perfectly adequate description of how REXX evaluates 
expressions: refer the reader to that. Don't invent rules that 
sometimes don't apply.


The root problem is that someone is writing code without understanding 
the language.



--
Shmuel (Seymour J.) Metz
http://mason.gmu.edu/~smetz3


From: IBM Mainframe Discussion List [IBM-MAIN@LISTSERV.UA.EDU] on 
behalf of Tony Thigpen [t...@vse2pdf.com]

Sent: Friday, June 5, 2020 2:03 PM
To: IBM-MAIN@LISTSERV.UA.EDU
Subject: Re: Gratuitous EXECIO Documentation

Sorry, but I disagree.

Your statement implies that "sometimes" it is legitimate to not use
quotes. I would say that "sometimes you can get lucky and get away with
not using quotes". :-)

A very basic documentation statement would be:
 Some formats of the EXECIO command may reference a variable
 by the name of the variable. Such references should be
 within quoted text. Such an example is the variable name
 of a stem variable:
 Correct:
   'EXECIO 5 DISKW' ddname '(STEM MYSTEM.'
 Incorrect:
   'EXECIO 5 DISKW' ddname '(STEM' mystem.
 Use without quotes can result in unpredictable results.


I really think this is the root problem, not the fact that someone
defined a variable with the same name as a common keyword, such as your
example with "STEM". Such an example is just part of the language
restriction and not directly related to EXECIO.


Tony Thigpen

Seymour J Metz wrote on 6/5/20 12:56 PM:
My problem with gratuitous documentation is that they invariably get 
it wrong. Describe the actual requirements and direct the reader to 
the appropriate places for details. In this case, something like:


  As with any command issued to an external environment, ensure 
that the

  expression you use evaluates to the intended EXECIO command. In
  particular, it may be prudent to always quote keywords to avoid
  confusion with variables with the same name.  For example, if 
you assign

  the variable "stem" to a value other than 'STEM' and then use

  EXECIO 5 DISKW ddname '(' STEM

  instead of

  EXECIO 5 DISKW ddname '( STEM'

  in your code, you will not invoke the correct command.

Would be reasonable if they have to spell it out.



--
Shmuel (Seymour J.) Metz
http://mason.gmu.edu/~smetz3


From: IBM Mainframe Discussion List [IBM-MAIN@LISTSERV.UA.EDU] on 
behalf of Paul Gilmartin 
[000433f07816-dmarc-requ...@listserv.ua.edu]

Sent: Friday, June 5, 2020 11:29 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

Re: Gratuitous EXECIO Documentation


No, the problem is not an understanding of how REXX evaluates expressions.

The problem is that EXECIO is one of the few places that a variable NAME 
is an operand, not the variable CONTENTS.


Tony Thigpen

Seymour J Metz wrote on 6/5/20 2:11 PM:

Your statement implies that "sometimes" it is legitimate to not use quotes.


In fact, sometimes it is mandatory to not use them.

Your suggested wording has the same issue as what is in the manual; it 
prescribes rules that aren't always appropriate. The REXX Reference manual has 
a perfectly adequate description of how REXX evaluates expressions: refer the 
reader to that. Don't invent rules that sometimes don't apply.

The root problem is that someone is writing code without understanding the 
language.


--
Shmuel (Seymour J.) Metz
http://mason.gmu.edu/~smetz3


From: IBM Mainframe Discussion List [IBM-MAIN@LISTSERV.UA.EDU] on behalf of 
Tony Thigpen [t...@vse2pdf.com]
Sent: Friday, June 5, 2020 2:03 PM
To: IBM-MAIN@LISTSERV.UA.EDU
Subject: Re: Gratuitous EXECIO Documentation

Sorry, but I disagree.

Your statement implies that "sometimes" it is legitimate to not use
quotes. I would say that "sometimes you can get lucky and get away with
not using quotes". :-)

A very basic documentation statement would be:
 Some formats of the EXECIO command may reference a variable
 by the name of the variable. Such references should be
 within quoted text. Such an example is the variable name
 of a stem variable:
 Correct:
   'EXECIO 5 DISKW' ddname '(STEM MYSTEM.'
 Incorrect:
   'EXECIO 5 DISKW' ddname '(STEM' mystem.
 Use without quotes can result in unpredictable results.


I really think this is the root problem, not the fact that someone
defined a variable with the same name as a common keyword, such as your
example with "STEM". Such an example is just part of the language
restriction and not directly related to EXECIO.


Tony Thigpen

Seymour J Metz wrote on 6/5/20 12:56 PM:

My problem with gratuitous documentation is that they invariably get it wrong. 
Describe the actual requirements and direct the reader to the appropriate 
places for details. In this case, something like:

  As with any command issued to an external environment, ensure that the
  expression you use evaluates to the intended EXECIO command. In
  particular, it may be prudent to always quote keywords to avoid
  confusion with variables with the same name.  For example, if you assign
  the variable "stem" to a value other than 'STEM' and then use

  EXECIO 5 DISKW ddname '(' STEM

  instead of

  EXECIO 5 DISKW ddname '( STEM'

  in your code, you will not invoke the correct command.

Would be reasonable if they have to spell it out.



--
Shmuel (Seymour J.) Metz
http://mason.gmu.edu/~smetz3


From: IBM Mainframe Discussion List [IBM-MAIN@LISTSERV.UA.EDU] on behalf of 
Paul Gilmartin [000433f07816-dmarc-requ...@listserv.ua.edu]
Sent: Friday, June 5, 2020 11:29 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



--

Re: Gratuitous EXECIO Documentation

> Your statement implies that "sometimes" it is legitimate to not use quotes. 

In fact, sometimes it is mandatory to not use them.

Your suggested wording has the same issue as what is in the manual; it 
prescribes rules that aren't always appropriate. The REXX Reference manual has 
a perfectly adequate description of how REXX evaluates expressions: refer the 
reader to that. Don't invent rules that sometimes don't apply.

The root problem is that someone is writing code without understanding the 
language.


--
Shmuel (Seymour J.) Metz
http://mason.gmu.edu/~smetz3


From: IBM Mainframe Discussion List [IBM-MAIN@LISTSERV.UA.EDU] on behalf of 
Tony Thigpen [t...@vse2pdf.com]
Sent: Friday, June 5, 2020 2:03 PM
To: IBM-MAIN@LISTSERV.UA.EDU
Subject: Re: Gratuitous EXECIO Documentation

Sorry, but I disagree.

Your statement implies that "sometimes" it is legitimate to not use
quotes. I would say that "sometimes you can get lucky and get away with
not using quotes". :-)

A very basic documentation statement would be:
Some formats of the EXECIO command may reference a variable
by the name of the variable. Such references should be
within quoted text. Such an example is the variable name
of a stem variable:
Correct:
  'EXECIO 5 DISKW' ddname '(STEM MYSTEM.'
Incorrect:
  'EXECIO 5 DISKW' ddname '(STEM' mystem.
Use without quotes can result in unpredictable results.


I really think this is the root problem, not the fact that someone
defined a variable with the same name as a common keyword, such as your
example with "STEM". Such an example is just part of the language
restriction and not directly related to EXECIO.


Tony Thigpen

Seymour J Metz wrote on 6/5/20 12:56 PM:
> My problem with gratuitous documentation is that they invariably get it 
> wrong. Describe the actual requirements and direct the reader to the 
> appropriate places for details. In this case, something like:
>
>  As with any command issued to an external environment, ensure that the
>  expression you use evaluates to the intended EXECIO command. In
>  particular, it may be prudent to always quote keywords to avoid
>  confusion with variables with the same name.  For example, if you assign
>  the variable "stem" to a value other than 'STEM' and then use
>
>  EXECIO 5 DISKW ddname '(' STEM
>
>  instead of
>
>  EXECIO 5 DISKW ddname '( STEM'
>
>  in your code, you will not invoke the correct command.
>
> Would be reasonable if they have to spell it out.
>
>
>
> --
> Shmuel (Seymour J.) Metz
> http://mason.gmu.edu/~smetz3
>
> 
> From: IBM Mainframe Discussion List [IBM-MAIN@LISTSERV.UA.EDU] on behalf of 
> Paul Gilmartin [000433f07816-dmarc-requ...@listserv.ua.edu]
> Sent: Friday, June 5, 2020 11:29 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

Re: Gratuitous EXECIO Documentation


Sorry, but I disagree.

Your statement implies that "sometimes" it is legitimate to not use 
quotes. I would say that "sometimes you can get lucky and get away with 
not using quotes". :-)


A very basic documentation statement would be:
   Some formats of the EXECIO command may reference a variable
   by the name of the variable. Such references should be
   within quoted text. Such an example is the variable name
   of a stem variable:
   Correct:
 'EXECIO 5 DISKW' ddname '(STEM MYSTEM.'
   Incorrect:
 'EXECIO 5 DISKW' ddname '(STEM' mystem.
   Use without quotes can result in unpredictable results.


I really think this is the root problem, not the fact that someone 
defined a variable with the same name as a common keyword, such as your 
example with "STEM". Such an example is just part of the language 
restriction and not directly related to EXECIO.



Tony Thigpen

Seymour J Metz wrote on 6/5/20 12:56 PM:

My problem with gratuitous documentation is that they invariably get it wrong. 
Describe the actual requirements and direct the reader to the appropriate 
places for details. In this case, something like:

 As with any command issued to an external environment, ensure that the
 expression you use evaluates to the intended EXECIO command. In
 particular, it may be prudent to always quote keywords to avoid
 confusion with variables with the same name.  For example, if you assign
 the variable "stem" to a value other than 'STEM' and then use

 EXECIO 5 DISKW ddname '(' STEM

 instead of

 EXECIO 5 DISKW ddname '( STEM'

 in your code, you will not invoke the correct command.

Would be reasonable if they have to spell it out.



--
Shmuel (Seymour J.) Metz
http://mason.gmu.edu/~smetz3


From: IBM Mainframe Discussion List [IBM-MAIN@LISTSERV.UA.EDU] on behalf of 
Paul Gilmartin [000433f07816-dmarc-requ...@listserv.ua.edu]
Sent: Friday, June 5, 2020 11:29 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

Re: Gratuitous EXECIO Documentation

The problem comes in when a user has to update code that isn't laid out the way 
that the author describes. He'll spend a lot of time scratching his head 
instead of saying "Oh, this is an expression. How does it expand?"

Give examples, and refer the reader to the proper place for the actual rules.


--
Shmuel (Seymour J.) Metz
http://mason.gmu.edu/~smetz3


From: IBM Mainframe Discussion List [IBM-MAIN@LISTSERV.UA.EDU] on behalf of 
Paul Gilmartin [000433f07816-dmarc-requ...@listserv.ua.edu]
Sent: Friday, June 5, 2020 1:33 PM
To: IBM-MAIN@LISTSERV.UA.EDU
Subject: Re: Gratuitous EXECIO Documentation

On Fri, 5 Jun 2020 17:11:37 +, Seymour J Metz wrote:

>As a guy who has had to support users who acted based on incorrect material in 
>manuals, I would prefer that the writer refer the reader to another section 
>orto another manual rather than introducing garbled versions of what they say. 
>In particular, there is adequate coverage of issuing commands in Chapter 2. 
>REXX general concepts,
>
I strongly agree.

>Commands to external environments. If they must issue excess verbiage then 
>they should get it right.
>
>The verbiage he quoted is defective; they should drop or reword it.
>
I don't see the error, unless you mean that the example:
"EXECIO * DISKR MYINDD (FINIS STEM MYVAR"

might be replaced by:
Larry = "EXECIO"
Moe = "*"
Curly = "DISKR"
Larry Moe Curly "DISKR MYINDD (FINIS STEM MYVAR"

I'd expect "MYVAR.", but it works without the period, and I've used
it that way with ISPF LM Services which prohibit the period.

>-Original Message-
>From:  Paul Gilmartin
>Sent: Friday, June 5, 2020 8:30 AM
>
>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.

-- 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

Re: Gratuitous EXECIO Documentation

On Fri, 5 Jun 2020 17:11:37 +, Seymour J Metz wrote:

>As a guy who has had to support users who acted based on incorrect material in 
>manuals, I would prefer that the writer refer the reader to another section 
>orto another manual rather than introducing garbled versions of what they say. 
>In particular, there is adequate coverage of issuing commands in Chapter 2. 
>REXX general concepts, 
>
I strongly agree.

>Commands to external environments. If they must issue excess verbiage then 
>they should get it right.
>
>The verbiage he quoted is defective; they should drop or reword it.
>
I don't see the error, unless you mean that the example:
"EXECIO * DISKR MYINDD (FINIS STEM MYVAR"

might be replaced by:
Larry = "EXECIO"
Moe = "*"
Curly = "DISKR"
Larry Moe Curly "DISKR MYINDD (FINIS STEM MYVAR"

I'd expect "MYVAR.", but it works without the period, and I've used
it that way with ISPF LM Services which prohibit the period.

>-Original Message-
>From:  Paul Gilmartin
>Sent: Friday, June 5, 2020 8:30 AM
>
>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.

-- gil

--
For IBM-MAIN subscribe / signoff / archive access instructions,
send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN

Re: Gratuitous EXECIO Documentation

It's not enough that the writer wanted to aid human beings; the text has to 
actually do so. 

--
Shmuel (Seymour J.) Metz
http://mason.gmu.edu/~smetz3

From: IBM Mainframe Discussion List [IBM-MAIN@LISTSERV.UA.EDU] on behalf of 
Charles Mills [charl...@mcn.org]
Sent: Friday, June 5, 2020 12:46 PM
To: IBM-MAIN@LISTSERV.UA.EDU
Subject: Re: Gratuitous EXECIO Documentation

The documentation is written to aid human beings. It is not a hard-core 
exercise in logic.

In writing doc I am often struck by a contrast to coding. In coding, if you had 
to do the same three-line sequence at ten places in your code the right thing 
would be to factor it out into a subroutine and invoke it ten times. In writing 
doc OTOH the reader might be better served by your repeating the same three 
sentences ten times rather than ten times saying "See the note at the top of 
page 17" (which is roughly the documentation analog of a subroutine call).

It's a judgment call as to what will best help the reader. Sometimes following 
logic rigorously is what best serves the reader. Probably better to use a link 
to the JCL reference rather than doing a halfway job of explaining DD 
statements in a COBOL manual. But as @Tony says, EXECIO is a particular 
landmine for inexperienced Rexx coders. It is not wrong to make their lives 
easier.

And no, "therefore every technically similar feature should get the same note" 
is not a valid corollary.

Charles

-Original Message-
From: IBM Mainframe Discussion List [mailto:IBM-MAIN@LISTSERV.UA.EDU] On Behalf 
Of Paul Gilmartin
Sent: Friday, June 5, 2020 9:15 AM
To: IBM-MAIN@LISTSERV.UA.EDU
Subject: Re: Gratuitous EXECIO Documentation

On Fri, 5 Jun 2020 12:01:18 -0400, Tony Thigpen wrote:

>In my experience, over 30 years of using REXX on first VM, then VSE and
>now z/OS, I can't tell you how many times I have had to help people with
>the EXECIO syntax as it relates to "what is a keyword" and "what is a
>variable". I would put it at the top of the "common programming errors
>in REXX" list.
>
>I have seen the following error S many times:
>... "STEM" line.
>Which should be:
>... "STEM LINE."
>
>I would not consider this "gratuitous" documentation.
>
I'm outvoted.  I  shall submit one RCF for each command description
that does not contain such a caution asking that one be added.

(I haven't checked.  Perhaps they already exist.)

-- 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

Re: Gratuitous EXECIO Documentation

A note about quoting constants might be appropriate if it reflected a correct 
understanding of REXX. The quoted text should be fixed, made general and show 
an example.

BTW, would you repeat essentially the same verbiage for, e.g., EXECUTIL?


--
Shmuel (Seymour J.) Metz
http://mason.gmu.edu/~smetz3


From: IBM Mainframe Discussion List [IBM-MAIN@LISTSERV.UA.EDU] on behalf of 
Tony Thigpen [t...@vse2pdf.com]
Sent: Friday, June 5, 2020 12:01 PM
To: IBM-MAIN@LISTSERV.UA.EDU
Subject: Re: Gratuitous EXECIO Documentation

In my experience, over 30 years of using REXX on first VM, then VSE and
now z/OS, I can't tell you how many times I have had to help people with
the EXECIO syntax as it relates to "what is a keyword" and "what is a
variable". I would put it at the top of the "common programming errors
in REXX" list.

I have seen the following error S many times:
... "STEM" line.
Which should be:
... "STEM LINE."

I would not consider this "gratuitous" documentation.

Tony Thigpen

Paul Gilmartin wrote on 6/5/20 11:29 AM:
> 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

Re: Gratuitous EXECIO Documentation

foo = value('BAR',,baz)


--
Shmuel (Seymour J.) Metz
http://mason.gmu.edu/~smetz3


From: IBM Mainframe Discussion List [IBM-MAIN@LISTSERV.UA.EDU] on behalf of 
Charles Mills [charl...@mcn.org]
Sent: Friday, June 5, 2020 12:27 PM
To: IBM-MAIN@LISTSERV.UA.EDU
Subject: Re: Gratuitous EXECIO Documentation

It is SO counter-intuitive to put the name of a variable in quotes. You would 
not code ENQ ('MYMAJOR','MYMINOR',E,8).

Once you realize that EXECIO is an external command, not a language keyword, 
you start to get it.

Charles


-Original Message-
From: IBM Mainframe Discussion List [mailto:IBM-MAIN@LISTSERV.UA.EDU] On Behalf 
Of Tony Thigpen
Sent: Friday, June 5, 2020 9:01 AM
To: IBM-MAIN@LISTSERV.UA.EDU
Subject: Re: Gratuitous EXECIO Documentation

In my experience, over 30 years of using REXX on first VM, then VSE and
now z/OS, I can't tell you how many times I have had to help people with
the EXECIO syntax as it relates to "what is a keyword" and "what is a
variable". I would put it at the top of the "common programming errors
in REXX" list.

I have seen the following error S many times:
... "STEM" line.
Which should be:
... "STEM LINE."

I would not consider this "gratuitous" documentation.

Tony Thigpen

Paul Gilmartin wrote on 6/5/20 11:29 AM:
> 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

--
For IBM-MAIN subscribe / signoff / archive access instructions,
send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN

Re: Gratuitous EXECIO Documentation

As a guy who has had to support users who acted based on incorrect material in 
manuals, I would prefer that the writer refer the reader to another section 
orto another manual rather than introducing garbled versions of what they say. 
In particular, there is adequate coverage of issuing commands in Chapter 2. 
REXX general concepts, Commands to external environments. If they must issue 
excess verbiage then they should get it right.

The verbiage he quoted is defective; they should drop or reword it.


--
Shmuel (Seymour J.) Metz
http://mason.gmu.edu/~smetz3


From: IBM Mainframe Discussion List [IBM-MAIN@LISTSERV.UA.EDU] on behalf of 
Charles Mills [charl...@mcn.org]
Sent: Friday, June 5, 2020 11:50 AM
To: IBM-MAIN@LISTSERV.UA.EDU
Subject: Re: Gratuitous EXECIO Documentation

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.

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

Re: Gratuitous EXECIO Documentation

On Fri, 5 Jun 2020 16:56:06 +, Seymour J Metz wrote:

>My problem with gratuitous documentation is that they invariably get it wrong. 
>Describe the actual requirements and direct the reader to the appropriate 
>places for details. In this case, something like:
>
>As with any command issued to an external environment, ensure that the
>expression you use evaluates to the intended EXECIO command. In
>
That's more than enough.

>particular, it may be prudent to always quote keywords to avoid 
>confusion with variables with the same name.  For example, if you assign
>the variable "stem" to a value other than 'STEM' and then use
>
That's too much.

>EXECIO 5 DISKW ddname '(' STEM
>
>instead of
>
>EXECIO 5 DISKW ddname '( STEM'
>
>in your code, you will not invoke the correct command.
>
>Would be reasonable if they have to spell it out.
>
I'd prefer, for reasons that you know well:
 'EXECIO 5 DISKW' ddname '( STEM compound_symbol.'

The examples should be correct, nearly foolproof.  Beyond that,
presumption of familiarity with "General Concepts" should suffice.

The trees shouldn't hide the forest.

-- gil

--
For IBM-MAIN subscribe / signoff / archive access instructions,
send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN

Re: Gratuitous EXECIO Documentation

My problem with gratuitous documentation is that they invariably get it wrong. 
Describe the actual requirements and direct the reader to the appropriate 
places for details. In this case, something like:

As with any command issued to an external environment, ensure that the
expression you use evaluates to the intended EXECIO command. In
particular, it may be prudent to always quote keywords to avoid 
confusion with variables with the same name.  For example, if you assign
the variable "stem" to a value other than 'STEM' and then use

EXECIO 5 DISKW ddname '(' STEM

instead of

EXECIO 5 DISKW ddname '( STEM'

in your code, you will not invoke the correct command.

Would be reasonable if they have to spell it out.



--
Shmuel (Seymour J.) Metz
http://mason.gmu.edu/~smetz3


From: IBM Mainframe Discussion List [IBM-MAIN@LISTSERV.UA.EDU] on behalf of 
Paul Gilmartin [000433f07816-dmarc-requ...@listserv.ua.edu]
Sent: Friday, June 5, 2020 11:29 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

Re: Gratuitous EXECIO Documentation

On Fri, 5 Jun 2020 09:27:51 -0700, Charles Mills wrote:

>It is SO counter-intuitive to put the name of a variable in quotes. You would 
>not code ENQ ('MYMAJOR','MYMINOR',E,8).
>
It depends on your language background.  Most generally:
https://en.wikipedia.org/wiki/Use%E2%80%93mention_distinction

It the difference between:
"The Rexx Reference" contains 18 characters
and
The Rexx Reference contains 3332539 characters.

>Once you realize that EXECIO is an external command, not a language keyword, 
>you start to get it.
>
Yes.  I'd prefer:
An expression which is a fully-qualified data set name
over such as:
"'MY.FULLY.QUALIFIED.DATA.SET.NAME'"
... in the many places where the latter occurs and is over-explained.

The user should be familiar with the Rexx General Concepts chapter and
neither generalize nor instantiate, probably incorrectly, from the several
examples.

-- gil

--
For IBM-MAIN subscribe / signoff / archive access instructions,
send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN

Re: Gratuitous EXECIO Documentation

The documentation is written to aid human beings. It is not a hard-core 
exercise in logic. 

In writing doc I am often struck by a contrast to coding. In coding, if you had 
to do the same three-line sequence at ten places in your code the right thing 
would be to factor it out into a subroutine and invoke it ten times. In writing 
doc OTOH the reader might be better served by your repeating the same three 
sentences ten times rather than ten times saying "See the note at the top of 
page 17" (which is roughly the documentation analog of a subroutine call).

It's a judgment call as to what will best help the reader. Sometimes following 
logic rigorously is what best serves the reader. Probably better to use a link 
to the JCL reference rather than doing a halfway job of explaining DD 
statements in a COBOL manual. But as @Tony says, EXECIO is a particular 
landmine for inexperienced Rexx coders. It is not wrong to make their lives 
easier.

And no, "therefore every technically similar feature should get the same note" 
is not a valid corollary.

Charles

-Original Message-
From: IBM Mainframe Discussion List [mailto:IBM-MAIN@LISTSERV.UA.EDU] On Behalf 
Of Paul Gilmartin
Sent: Friday, June 5, 2020 9:15 AM
To: IBM-MAIN@LISTSERV.UA.EDU
Subject: Re: Gratuitous EXECIO Documentation

On Fri, 5 Jun 2020 12:01:18 -0400, Tony Thigpen wrote:

>In my experience, over 30 years of using REXX on first VM, then VSE and
>now z/OS, I can't tell you how many times I have had to help people with
>the EXECIO syntax as it relates to "what is a keyword" and "what is a
>variable". I would put it at the top of the "common programming errors
>in REXX" list.
>
>I have seen the following error S many times:
>... "STEM" line.
>Which should be:
>... "STEM LINE."
>
>I would not consider this "gratuitous" documentation.
> 
I'm outvoted.  I  shall submit one RCF for each command description
that does not contain such a caution asking that one be added.

(I haven't checked.  Perhaps they already exist.)

-- 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

Re: Gratuitous EXECIO Documentation

It is SO counter-intuitive to put the name of a variable in quotes. You would 
not code ENQ ('MYMAJOR','MYMINOR',E,8).

Once you realize that EXECIO is an external command, not a language keyword, 
you start to get it.

Charles


-Original Message-
From: IBM Mainframe Discussion List [mailto:IBM-MAIN@LISTSERV.UA.EDU] On Behalf 
Of Tony Thigpen
Sent: Friday, June 5, 2020 9:01 AM
To: IBM-MAIN@LISTSERV.UA.EDU
Subject: Re: Gratuitous EXECIO Documentation

In my experience, over 30 years of using REXX on first VM, then VSE and 
now z/OS, I can't tell you how many times I have had to help people with 
the EXECIO syntax as it relates to "what is a keyword" and "what is a 
variable". I would put it at the top of the "common programming errors 
in REXX" list.

I have seen the following error S many times:
... "STEM" line.
Which should be:
... "STEM LINE."

I would not consider this "gratuitous" documentation.

Tony Thigpen

Paul Gilmartin wrote on 6/5/20 11:29 AM:
> 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

Re: Gratuitous EXECIO Documentation

On Fri, 5 Jun 2020 12:01:18 -0400, Tony Thigpen wrote:

>In my experience, over 30 years of using REXX on first VM, then VSE and
>now z/OS, I can't tell you how many times I have had to help people with
>the EXECIO syntax as it relates to "what is a keyword" and "what is a
>variable". I would put it at the top of the "common programming errors
>in REXX" list.
>
>I have seen the following error S many times:
>... "STEM" line.
>Which should be:
>... "STEM LINE."
>
>I would not consider this "gratuitous" documentation.
> 
I'm outvoted.  I  shall submit one RCF for each command description
that does not contain such a caution asking that one be added.

(I haven't checked.  Perhaps they already exist.)

-- gil

--
For IBM-MAIN subscribe / signoff / archive access instructions,
send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN

Re: Gratuitous EXECIO Documentation

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

Re: Gratuitous EXECIO Documentation

In my experience, over 30 years of using REXX on first VM, then VSE and
now z/OS, I can't tell you how many times I have had to help people with
the EXECIO syntax as it relates to "what is a keyword" and "what is a
variable". I would put it at the top of the "common programming errors
in REXX" list.

I have seen the following error S many times:
... "STEM" line.
Which should be:
... "STEM LINE."

I would not consider this "gratuitous" documentation.

Tony Thigpen

Paul Gilmartin wrote on 6/5/20 11:29 AM:

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

Re: Gratuitous EXECIO Documentation

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.

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

Re: Gratuitous EXECIO Documentation

2020-06-05 Thread Jesse 1 Robinson

I resemble that example. But point taken. 

.
.
J.O.Skip Robinson
Southern California Edison Company
Electric Dragon Team Paddler 
SHARE MVS Program Co-Manager
323-715-0595 Mobile
626-543-6132 Office ⇐=== NEW
robin...@sce.com

-Original Message-
From: IBM Mainframe Discussion List  On Behalf Of 
Paul Gilmartin
Sent: Friday, June 5, 2020 8:30 AM
To: IBM-MAIN@LISTSERV.UA.EDU
Subject: (External):Gratuitous EXECIO Documentation

CAUTION EXTERNAL EMAIL

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

Gratuitous EXECIO Documentation