PLEASE back up your execs before converting them!
Discussion of pros and cons of USEMYSAY
What is USEMYSAY?
A Rexx edit macro that converts each line of your Rexx exec that contains a 'say' to use 'mysay'.
'say blah' statements in your exec become calls like
Why use USEMYSAY on my execs?
You will be grateful for USEMYSAY if your exec contains hundreds of 'say' statements.
Why NOT use USEMYSAY on my execs?
You will be very ungrateful for USEMYSAY if your exec is stuffed up by my logic errors.
MYSAY and Top-level execs.
Your exec is a top-level exec if you invoke it from a menu or from the command line, or by naming it as the parameter in an IKJEFT JCL step.
Otherwise it is what I call a low-level exec.
A top-level exec should make exactly one initialisation call to mysay0 before issuing any mysays,
and exactly one finalisation call to mysay9() after issuing its last mysay.
Any low-level execs called by this exec should issue their Mysay() but never a mysay0 or mysay9.
Converting top-level execs with USEMYSAY
As well as converting (perhaps hundreds) of 'say' statements, this tells USEMYSAY to insert mysay0()and mysay9() calls.
Mysay0 is inserted at the top of the exec:
aboutme = execname "Does stuff. This is a blurb that is displayed in the header part of the supplied panel",
You next need to edit the contents of 'aboutme' to whatever you want to see displayed while your exec is running.
Note: mysay interprets aboutme to set the contents of a pool variable. Therefore two limitations:
- You cannot presently display an 'aboutme' blurb exceeding 250 chars, despite there being 4*74 = 296 chars of available space in the 'aboutme' dynamic field of panel 'scroller'. Anything over 250 chars is trimmed off.
- If you include any apostrophes/single quotes/double quotes inside 'aboutme', the interpret will fail with an obscure message from inside 'mysay'. So until I rewrite this part of mysay. DON'T include apostrophes/single quotes/double quotes inside 'aboutme'.
aboutme = execname "Ransacks the DB2 catalog and constructs a tree of RI relationships for display by ZtreeRI."
The above will work. It fits the 250-char limit, and it contains no apostrophes or double quotes.
aboutme = execname "Reads dsn 'yourprefix.user.exec' and inserts documentation in 'XML' format in the beginning of each member"
The above will fail to interpret and crash 'mysay' due to the imbedded single quotes.
USEMYSAY will also have a stab at inserting
at the end of the main routine, hopefully just BEFORE any final "exit" or "return" instruction. Mysay9 will trigger an invitation to the online user to review all the displays that have been scrolled past during the run of this exec.
(In batch, it will not prompt of course)
Note that the lexically first 'say' in your program might not be the logically first. In this case, USEMYSAY has misplaced the above lines of code. It is your job to recognise this and move these lines to just before the TRULY FIRST program display.
If you forget to do this, you will see a line-mode message (red 'say') from inside 'mysay' advising that 'mysay0' has not been called.
This is a dead giveaway that a vanilla 'mysay' has been executed prior to the initialising 'mysay0'.
What do I have to do after running USEMYSAY on my top-level exec?
Check the placement of the mysay0 and mysay9 calls.
Edit the 'aboutme' blurb.
What do I have to do after running USEMYSAY on my low-level exec?
Nothing much, except ensure that you have converted the parent top-level exec with the TOP option so that mysay0 has been called before your exec is run.
And read the warnings below!
Because USEMYSAY has to muck with your valuable Rexx code, no matter how much I test it, it really doesn't prove that USEMYSAY is safe to use on YOUR code.
Therefore ALWAYS BACK UP YOUR REXX EXEC SOURCE before running USEMYSAY!
- USEMYSAY must squeeze in 6 extra characters per 'say' statement.
Thus a long 'say' statement such as this MIGHT NOT BE HANDLED CORRECTLY!
say 'This is quite a long line of output that runs up very nearly to column 72'
SHOULD be converted to
rv=mysay('This is quite a long line of output that runs up very nearly to'||,
So CHECK your converted code!
- There are unlimited variations in coding styles and what people have managed to squeeze into a single line of Rexx. Therefore it is almost inevitable that USEMYSAY will ,er, not succeed 100% on a line or two of YOUR CODE!
- On the other hand, I have successfully converted ISPDTLC with USEMYSAY. This is one of the biggest Execs around, 35,000+ lines from IBM, used to compile ISPF DTL (GML) into ISPF panel code.
What USEMYSAY seems to do well:
- USEMYSAY correctly handles multi-statement Rexx lines, by breaking them on the semicolon.
Thus a line like
a = 1; b = 2; say 'a='a',b='b; c = a*2; call fred; say 'after call to fred, c='c; d = 0
will be broken by USEMYSAY into single Rexx statements, and the line with 'say' will become
rv=mysay('after call to fred, c='c)
- USEMYSAY does not attempt to change phrases containing 'say' which occur inside comments.
- USEMYSAY even handles occurrences of 'say' inside double-quoted strings which I set up for 'interpret' statements.
What USEMYSAY may NOT do properly:
- It may NOT yet ALWAYS correctly handle embedded ';' semicolons inside of hollerith strings - it may break some of these on the semicolon and thus break the logic.
- USEMYSAY assumes a Rexx source file 80 chars wide, with no meaningful code going past column 72. I have not tested in on 255-wide Rexx source.