Looking for a clever way to display purpose and usage information to the caller of your REXX script? What I describe here is a way to use the documentation that may already be there for just this purpose.
A good programmer puts some effort in good documentation of the software. Scripts should be no exception. So, you start your REXX scripts with a couple of comment lines to describe the purpose of the script. You also document any parameters and exit values. Excellent.
Learn how to use this very description at the start of you REXX script to display usage information to the user. You might do this when required parameters are missing, or if there is any error in the parameters provided.
Provide a kind of DisplayHelp Subroutine
Every program must verify the parameters received. Every program should display some usage information, if there are any errors in parameters. Call a routine, e.g. DisplayHelp, from any places where you want to display such information. Using the REXX function sourceline(), we can make use of the description that might already be right at the tops of your script. Those code lines at the beginning are documentation for the programmer looking at the source code, as well as documentation shown to the user. No duplication of text. You still need to keep it up to date, though.
Download link at the bottom of this article.
Start the Script with a Block, or Multi-Line Comment
Firstly, format the decription a the start of you REXX script as block comment, or multi-line comment as follows:
/* REXX -------------------------------- start of block comment ------------
here goes your description.
don't close the comment in this part,
instead use a separate line to end it (see below)
---------------------------------------- End of block comment -------------*/The text between the lines starting and ending the block comment will be written to the terminal by the DisplayHelp routine. Make sure it has all the information the user of the REXX needs. Start with a short description of the program, then add information about parameters, if any, and their format and value range. Add information about exit conditions return values, etc.
Use the SOURCELINE in the DisplayHelp Routine
Secondly, add a DisplayHelp routine anywhere in your REXX script. The helpful function that will read the lines from the source is called sourcline(n). Sourceline(n) reads line n from the current module's source and returns it.
/*----------------------------------------------------------------------------
Display the first block comment found in the script as the help text
----------------------------------------------------------------------------*/
DisplayHelp: procedure
parse source . . PgmName .
/*----------------------------------------------------------------------------
Optionally, write some heading lines, if you find these helpful
----------------------------------------------------------------------------*/
say
say
say 'Help for rexx' PgmName
say '==============' || left( "", length( PgmName ), "=" )
say
/*-----------------------------------------------------------------------------
Search for the beginning of the description at the start of the REXX,
which must start within the (arbitrarily chosen) first ten lines.
----------------------------------------------------------------------------*/
do ii = 1 to 10
if pos( '/*', sourceLine( ii ) ) > 0
then leave
end
/*----------------------------------------------------------------------------
Don't continue if start of comment not found in the given range
----------------------------------------------------------------------------*/
if ii > 10
then do
say "Unexpected error in help: Help text not found."
return
end
/*----------------------------------------------------------------------------
Start displaying source lines as help text until the end of comment
is found. Note: The line ending the block comment is NOT shown.
----------------------------------------------------------------------------*/
do ii = ii + 1 until pos( '*/', sourceline( ii ) ) > 0
say strip( sourceline( ii ), 'T', ' ')
end
say
return
/*----------------------------------------------------------------------------
End of subroutine DisplayHelp
----------------------------------------------------------------------------*/
Include a Call to DisplayHelp at Appropriate Places
Finally, include a call to your DisplayHelp routine at appropriate places, such as after parameter checking if one or more errors have been detected.
if parameter1 == ""
then do
say "Error: Parameter 1 is missing."
call DisplayHelp
exit 1
end
You will never again have a description that does no longer match the text displayed by the help routine.
Download a fully working, minimal sample here: rexx-display-help-sample.txt