27th International Rexx
Language Symposium
28-31 August 2016
Tampa, Florida USA
Sponsored by
Rexx Language Association

SHOWIT - An ooRexx tool
to collect data from many
sources into an output file

Les Koehler
29 August 2016

Table of Contents

• Abstract
• Contributors
• History
• Syntax
• Substitution
• Uses
• Code
• Help
• Summary and Conclusion

Abstract

The inputs can contain variables in the html style of &varname which are defined with arguments and substitued as the output is created.

Its likely uses include:

• Extracting and displaying Help from code.
• Changing report headers and footers to another language.
• Aggragating multiple raw data files into a single report, with headers and footers added.

Contributors

• Gil Barmwater - ooRexx code and consulting.
• Walter Pachl - Consulting and testing
• Jon Wolfers - Bug resolution code and consulting

I am deeply indebted to all of them.

History

Eventually, that code was moved to a single macro, thus reducing the size of each macro and ensuring consistency.

Then, in October of 2015, I had to write some .rex code and realized I didn't have a similar tool for .rex code as I did for .the code. By the end of the month showit.rex was basically functional.

It wasn't until mid July of 2016 that my attention returned to it and I asked Walter for feedback. That resulted in a flurry of work to clean everything up and add some new features, with additional help from Gil and Jon.

Syntax

   Call Showit .context~name , [output file] , item [ , item ...] 

Note: The output file defaults to .context~name with "_help.txt" appended.

An item is one of the following, with an example for each:

• A whole file:
• '1 * C:\Files\My_file'
• '1 eof C:\Files\Your_File'
• A piece of a file:
• ' 2 8 C:\Files\Another_File'
• '20 * C:\Files\Another_File'
• A Classic stemname:

  mystem.

  Where the stem is numeric and mystem.0=the number of stems.

• An Object stemname:

  mystem.

  where mystem.0 is missing or not a whole number. The stemname will be sorted.

• A simple literal string:

'Report header for XYZ Corp'

• A variable name and definition:
  • '&me='.context~name
  • '&me= Some prose'

  to be substituted in the output. If the argument starts with "&,then substitution is not done. This allows you to show the definition required for substitution. See the Help for an example.

• Options

  A string that starts with ':' triggers Options processing. Valid options to change the defaults are:

  • NOShow - Don't display the output file
  • Quiet - Skip the Exit message when NOSHOW is used
  • NOTepad - Allow testers to use NotePad

  Any number of Options arguments can be used and any option can be negated by starting it with 'NO' (or not) as needed.

Substitution

Variable definitions are saved in the order encountered as the arguments are processed. Everything from the & to the '=' becomes the varname. There are no restrictions on a varname, other than an exact match must be found for substitution to occur.

Each output line is examined for every variable, in the same order they were collected, and if found the substitution is made on the line using changestr() for all occurences.

This allows the clever programmer to have a variable contain another variable!

Uses

Its likely uses include:

• Extracting and displaying Help from code.
• Changing report headers and footers to another language.
• Collecting multiple raw data files into a single report, with headers and footers added.
• Tailoring email boiler-plate for the recipient.

I do this with the THE editor for RexxLA Join/Renew and symposium Registration. That, however, preceeds this work.

Code

Here is the code: showit.rex.html

Help

When run from the command line, this is the result: showit.rex_help.txt.html

Summary and Conclusion

Summary

You've seen:

• The generous contributions of RexxLA members.
• Some history that inspired me.
• The syntax details, with examples.
• Defining variables and substitution.
• Some possible uses for showit.
• The code.
• The Help result. Where showit calls itself.

Would Anyone like to explore any of the above in more detail, or have a question?

Conclusion

Its been quite an adventure expanding showit beyond its original requirement to display a single piece of its own file and substitute variables.

However, the ultimate test of its usability rests with those who try it. Until the code gets posted on RexxLA.org, it can be requested from me.

Thank you for your attention and participation!