Re: QSHELL commands (was: Stmf copy with add)

["Simon Coulter" <shc@xxxxxxxxxxxxxxxxx>]

Hello Dennis,

You wrote:
>Good topic.  I see your point about keeping the related parameters
>together, but is it really all that important to do so, given that there is
>a "prompt position" specification available on the PARM command?

The "prompt position" value only affects F4Ùrompt.  It doesn't affect the
positional order i.e., the order in which parameters must be specified
without keywords therefore if you use MAXPOS(*NOMAX) new parameters MUST go
at the end of the existing parameters otherwise you risk breaking existing
CL programs by upsetting the positional order.  Usability issues suggest
that grouping related parameters together is a good thing.

Also, if I use "prompt position" and provide a syntax diagram do I show the
keyword order or the prompted order?  Either choice will confuse people who
habitually use the alternative (i.e., if the syntax diagram shows keyword
order it won't match the prompt and habitual pompters will get confused --
although they probably don't know what a syntax diagram is.  If the syntax
diagram shows propted order then I will hopelessly confuse the command line
addict because they'll never be able to determine the positional order
without the command source or by disassembling the CDO).  The correct choice
for a syntax diagram is the keyword order.

>Personally, I think IBM's done a fair job of deciding where to put the
>breaks between positional and non-positional parameters.  And when they
>haven't, I tend to just write a command like it with my choices, placed in
>SYSLIBL above QSYS.  But just for the sake of argument, is there another
>reason?

Here is a trivial command to illustrate my point.

             CMD        PROMPT('Test Positional Parameters')

             PARM       KWD(PARM1) TYPE(*CHAR) LEN(10) +
                          PROMPT('Position 3' 3)

             PARM       KWD(PARM2) TYPE(*CHAR) LEN(10) +
                          PROMPT('Position 4' 4)

             PARM       KWD(PARM3) TYPE(*CHAR) LEN(10) +
                          PROMPT('Position 1' 1)

             PARM       KWD(PARM4) TYPE(*CHAR) LEN(10) +
                          PROMPT('Position 2' 2)

Note that the keyword order is different from the prompt order.  The keyword
order is PARM1, PARM2, PARM3, PARM4 and the CPP will expect the parameters
in that order.  That is also the order in which I must specify the values if
I choose not to use the keywords.

However, the prompted order is PARM3, PARM4, PARM1, PARM2 and F4Ùrompt will
show them that way.  For example:

                      Test Positional Parameters (TEST_POS)

 Type choices, press Enter.

 Position 1 . . . . . . . . . . . PARM3 __________
 Position 2 . . . . . . . . . . . PARM4 __________
 Position 3 . . . . . . . . . . . PARM1 __________
 Position 4 . . . . . . . . . . . PARM2 __________

Suppose I write a CL program to use this command and I'm a lazy bastard so I
use positional notation and don't use the prompter to format the command.  I
type TEST_POS ABC 123 XYZ 789.  Is ABC the value for PARM1 or PARM3?  I know
it is PARM1 but what would a habitual prompter think?  If they maintain this
program and prompt it it will appear as:

 Position 1 . . . . . . . . . . . PARM3 XYZ_______
 Position 2 . . . . . . . . . . . PARM4 789_______
 Position 3 . . . . . . . . . . . PARM1 ABC_______
 Position 4 . . . . . . . . . .
 PARM2 123_______

which is possibly confusing.  Pressing Enter will format the command as
follows:

TEST_POS PARM3(XYZ) PARM4(789) PARM1(ABC) PARM2(123)

which is certainly confusing because that is not how I typed the original
values and it is not the keyword order but at least it is clear about which
value belongs with which keyword.

IBM have a lot more to think about when designing a command than the average
programmer (not that I count you in that number) and indeed have a CL
Guidelines document that was approaching 100 pages (if I recall correctly)
describing the rules they use to create or modify commands, keywords, and
parameter values -- not to mention the NLS Guidelines regarding word choices
and translation space.

If I as the designer of a command restrict the number of positional
parameters to only the required parameters or include the most common
default parameters I give myself more options in the future to improve or
enhance the command without breaking existing CL code.

>Thanks.
>Dennis, who wanted desperately to say, "Come on, Simon, tell us what you
>really think" regarding that QSHELL discussion... but felt it was already
>too late.  :)

And here was I holding myself in check.  I thought I was rather restrained
in my comments.  Now, if you want to know what I really think .... :)

Regards,
Simon Coulter.

«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»
«» FlyByNight Software         AS/400 Technical Specialists       «»
«» Eclipse the competition - run your business on an IBM AS/400.  «»
«»                                                                «»
«» Phone: +61 3 9419 0175   Mobile: +61 0411 091 400        /"\   «»
«» Fax:   +61 3 9419 0175   mailto: shc@flybynight.com.au   \ /   «»
«»                                                           X    «»
«»               ASCII Ribbon campaign against HTML E-Mail  / \   «»
«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»«»