SSMacro

Sales Pitch

The Saxman Software Macro Processors - collectively known as SSMacro - are pre-processors or dynamic file generators. They read input files containing script and execute the script to generate output files. Script can control conditional generation or insert dynamic data into the output file.

The processors and embedded scripts are all standard REXX. REXX is a terrific string handling language, ideal for this kind of file processing. SSMacro and the Regina REXX interpreter are both free, so you can hardly beat the price.  

Overview

The Saxman Software Macro Processors read text files that contain REXX language scripts. They pass the text to output unchanged, and execute the REXX code. The REXX macros may control conditional generation or write dynamic content to the output. You might use the REXX code to write out the current date and time or write out data from disk files or databases. You can also use built-in REXX functions to embed one file in another, or append a file to the end of another.

REXX scripts may call out to external REXX programs or other command line programs. (I tried not to say "DOS"). These external programs may return strings that the script may write into the output.

I use SSMacro to generate web pages for SurfScranton. SSMacro reads my database of links and generates consistent menus and footers. SSMacro input files look like Microsoft's Active Server Pages or Sun's Java Server Pages. Those technologies execute on a web server to generate dynamic content as the page is being served. In contrast, SSMacro executes on a developer's workstation to generate dynamic content as a development step. The output is static HTML that my service provider can host without ASP or JSP technologies.

Versions

There are two versions of SSMacro. SSMacro1 is simpler and faster, older and better tested. REXX script fragments are interpreted as they are found. They must be complete REXX statements, like say "Hello". SSMacro2 is more powerful in that one script fragment may start a REXX statement and another may finish it. This lets you put REXX control structures such as if-then-else or do-end around text sections.

The two programs are very similar in usage (though not quite interchangeable) and the documentation covers both unless otherwise noted.

Running SSMacro

Start SSMacro with your REXX interpreter. I use Regina. The command line syntax is:

    regina ssmacro1 filespec '(' arguments
    regina ssmacro2 filespec '(' arguments

FileSpec may include global and wildcard characters to process multiple files in one run.

Arguments are passed to the REXX script. Using SSMacro1 your script may reference a provided variable _UserData. Using SSMacro2 your script may use the standard REXX parse arg.

The output of SSMacro has the same directory and name as the input, with the extension changed to "out". You can configure a different output extension, say "html".

Configuration

You can configure SSMacro behavior at two levels. SSMacro looks for global or product configuration in a file SSMacro.cfg in the same directory as SSMacro itself. It then looks for project configuration in a file SSMProj.cfg in the same directory as the input. 

Configuration files contain REXX code, of course. The defining comment /* */ on line one is not required, but won't hurt either. Each line must end with a semi-colon. This is standard REXX, but an option than almost no one ever uses. Configuration options:

   _ExtOut  = 'out'; /* Output file extension */
   _ScriptB = '<%';  /* Beginning delimiter for script */
   _ScriptE = '%>';  /* Beginning delimiter for script */ 

Provided Variables

Script code may read the following special variables:

    _FileIn    = d:\path\name.ext of the input
    _FileOut   = d:\path\name.ext of the output
    _UserData  = arguments from command line. SSMacro1 only

In SSMacro1 only, script may also read and write variables based on the stem Global. This variable is carried across all files processed in one invocation of SSMacro1, so script in one file may add variables and script in another file may read them.

SSMacro1 does a parse arg statement for you, loading up _UserData. SSMacro2 does not do this for you. You may parse arg in your own script. SSMacro2 passes the same arguments to the generated exec, i.e. everything after an open paren on the SSMacro2 command line.

Provided Functions

The following provided functions return an empty string, so they may be called as a function or procedure.

EmbedFile reads another file and (logically) inserts it at the current point in the input. SSMacro then processes the contents of that file as if they had been there all along, so an embedded file may contain more script and more EmbedFile calls. 

    EmbedFile( FileName )
    or
    call EmbedFile FileName

AppendFile reads another file and writes it to the output unchanged. The appended file is not processed for script. 

    Append( FileName )
    or
    call Append FileName

Write writes a string to the output. Write uses charout() and does not append a newline character.

    Write( String )
    or
    call Write String

WriteLine writes a string to the output using lineout(), so it does append a newline character. This is in SSMacro2 only for now.

    WriteLine( String )
    or
    call WriteLine String

Log writes a string to the console and to a logfile. This is in SSMacro1 only for now.

    Log( String )
    or
    call Log String

Equal Sign is shorthand for Write. This is not standard REXX and is included only because ASP and JSP have it. This must be the only statement in a script fragment. This is in SSMacro2 only for now. 

    = value

Writing Script

Script in the input file is bracketed by delimiters. The default syntax is <% script %> but the delimiters may be overridden in configuration files. Script may be on one line or span multiple lines. In SSMacro1 multiple REXX statements must be separated by semicolons. This is standard REXX, but because REXX normally assumes a semicolon at end of line, it is almost never seen. In SSMacro2 this is not required, but being standard, still works.

Examples:

    This is normal text. It was generated on <% write Date('U') %>.
    I could say <% =Date() %> in SSMacro2.
    Call another program <% a = OtherProgram(); write a %>

SSMacro2 allows partial REXX statements in a script fragment. Here we call an external program that returns a set of lines delimited by exclamation points.

    Some lines are coming up.
    <% Data = ExternalProgram()
       do i = 1 while Data <> ''
          parse var Data Line '!' Data %>
    This is Line <%=i%>. It says <%=Line%>.
    <% end %>
    That's all.

If you wrap SSMacro2 script around conditional lines of input, be sure to use do and end to mark of the block of lines.

    <% if Condition then do %>
    Conditional text.
    <% end %>

How It Works

The two versions have fundamentally different algorithms. Each seems to me to be the other turned inside out. 

SSMacro1 reads input and processes script as it goes. When it finds normal text in the input, it copies the text to the output unchanged. When it finds script, it interprets the script. SSMacro1 script must be valid for interpret: complete statements, separated by semicolons, no labels. 

SSMacro2 generates a temporary exec. When it finds normal text in the input, it generates lineout or charout statements in the generated exec. It copies any script unchanged into the temporary exec. Finally it executes the temporary exec. SSMacro2 script winds up in a complete exec, and may use any valid REXX structures.

Which one to use?  If SSMacro2 meets your performance needs, use it. It is more capable in most ways, missing only the Global. stem. It is not as thoroughly tested. I've been using SSMacro1 for a year, and just made SSMacro2 recently.

Bugs

• EmbedFile must be the only statement in a fragment.

• AppendFile must be the only statement in a fragment.

• SSMacro2 input lines that end in script do not generate newline characters correctly. See how my looping example above has a period after the script?  It says <%=Line%>. The period is enough to work around this bug.

Debugging

SSMacro1 loads the entire input into one string, and has no concept of line numbers. If there is a REXX error in your script, it will be reported as happening in the interpret statement in SSMacro1. This is not the most helpful. Sorry.

SSMacro2 generates a new exec. If there is a REXX error in the generated code, it will be reported using the line number in the generated exec. You may read the generated code or even add trace and display statements to it to find the problem line, but it may be hard to trace this back to your original input files.

Licensing

Please distribute SSMacro freely as a complete package, including documentation. If you make improvements, please distribute the original unchanged along with your revisions.

Support

Please get in touch if you have questions or problems. I would love to hear from you, and would like to collect useful external programs. For example, do you have one that returns information about an image?  Size in bytes, dimensions in pixels, etc.

Revisions

Author

SSMacro software and documentation is all by Jim Standley, Clarks Summit, PA.