PPWIZARD is a free preprocessor for HTML, REXX, Visual Basic or any text files.
\ -> Rexx -> Rexx Subroutines in PPWIZARD

 Rexx Subroutines in PPWIZARD

Due to limitations in the rexx language you can't create rexx subroutines within PPWIZARD. This is one of the reasons that PPWIZARD supplies quite a large list of inbuilt PPWIZARD functions which you can use.

There are however ways around this as listed below.

 Call External Rexx Subroutines

Basically you create a rexx file per function and then call it from within a PPWIZARD script.

As a very simplistic example (with no validation of parameters etc), to sum 2 numbers together you could create "sum.rex" which looks like:

exit(arg(1) + arg(2));


And call it within a PPWIZARD script like:

#DefineRexx ''
Sum = "extrexx\sum.rex"(4, 7);  ;;Call "sum" code in the "extrexx" directory
call Say "SUM = " || Sum;
#DefineRexx


OS/2 users would name the external rexx file "sum.cmd" and could also use the #MacroSpace command to improve performance.

The main disadvantage of this approach is that it is slower, has no access to rexx variables, requires a separate file and can not make use of any PPWIZARD subroutines or other integrated features.

Note that it may pay to "complicate" the function slightly to make it possible to test it from the command line. As written above the function takes arg(1) and arg(2) (parameters are never passed this way when called from the command line). PPWIZARD (rexx) may not detect syntax errors in rexx code called as shown above. Code which can be tested from the command line might look like:

parse value arg(1) with Num1 Num2
exit(Num1 + Num2);


Unfortunately the call to this must also change and would now look like:

#DefineRexx ''
Sum = "extrexx\sum.rex"('4 7');
call Say "SUM = " || Sum;
#DefineRexx


 Use Macros in Place of Subroutines

All a subroutine is is basically a piece of code which takes input and returns some output. Its other major advantage is that it is defined in one place to make maintenance easier. Sounds like a macro to me...

To use a macro you basically define some rexx code with all the inputs and outputs as parameters (some possibly defaulting). The best way is to write the macro as so that outputs are rexx variables and inputs can be expressions (a rexx variable name would be a simple expression), for example the "sum" macro could be written as:

#DefineRexx 'SUM'
{$ANSWER} = {$NUM1} + {$NUM2}; #DefineRexx  To use this macro: #DefineRexx '' <$SUM Answer="SUM" NUM1="4" NUM2="7">
call say "SUM = " || Sum
#DefineRexx


For the "sum" macro as written above the "answer" parameter is likely to be overkill, but if the implementation is to be kept transparent (no matter what changes you might wish to make in future - for example adding debugging code) it would probably be a good idea to always do it this way.

Of course you could simply hard code the operation of the macro and not use parameters at all for specific purposes and this might have some slight performance benefit.

Note that if the macro "function" requires temporary variables to do its processing then the code might look more like this:

#NextId PUSH             ;;Save "callers" state
#NextId                  ;;Create new namespace
#DefineRexx 'SUM'
@@Num1 = {$NUM1}; ;;Create 2 temp variables @@Num2 = {$NUM2};
#DefineRexx
#NextId POP              ;;Restore "callers" state


 Build a version of PPWIZARD containing your Functions!

If you have many common subroutines or fragments of rexx code that you are always reusing then you may wish to consider adding them to PPWIZARD and effectively customising it.

As PPWIZARD makes extensive use of global variables it is recommended that "procedure" not be used even if your code does not access any PPWIZARD code or variables (by default PPWIZARD will try to handle any traps that may occur in your code).

This is easy to do as the PPWIZARD runtime is simply a text file. I recommend that functions be placed on the end of the existing PPWIZARD and that the resultant file be called something else (maybe "MyPPWIZARD").

This will work in all operating systems (unlike #MacroSpace) and has the added advantage of having full access to PPWIZARD (or our own) variables and functions.

I recommend you create a batch file containing a command something like:

copy /a ppwinstalldir\PPWIZARD.REX+yoursrcdir\MyExtraBit.rex runtimedir\MyPPWIZARD.rex


The above would be run after every PPWIZARD upgrade. Of course you could just cut and paste in an editor but that is error prone. OS/2 users will of course change the above to use ".CMD" but this will work in DOS, Windows and OS/2. Unix users will have similar capability (let me know the command and I'll add it here!).

email me  any feedback, additional information or corrections.