PPWIZARD is a free preprocessor for HTML, REXX, Visual Basic or any text files.

Switch /$Trace[:YesOrNo]

This is a PPWIZARD command line switch. You can set up your own default switches in the "PPWIZARD_OPTIONS" environment variable or in project files.

This switch sets the default "$trace" state for all #DefineRexx blocks.

When $tracing is used rexx tracing code is inserted before most rexx lines (not statements). This inserted code will display the line of your code that is about to be executed and the current value of any variables that it references (also shows variables referenced by immediately previous statement).

If the "YesOrNo" parameter is not specified then it defaults to "Y", otherwise one of the following values is expected:

• Y
• N
• YES
• NO

PPWIZARD REXX TRACING

Please be careful using this feature, a rexx command is generated to support the tracing so always use do/end blocks when tracing within true or false "if" blocks etc. To provide an example, the following code will fail!:

       if  x = 1 then
           A = X;
       else
           A = 2;
    

To be able to trace this code you will need to change it to:

       if  x = 1 then
       do
           A = X;
       end;
       else
       do
           A = 2;
       end;
    

The addition of tracing code is fairly primative, however the rule is basically simple, it must be valid and not break your code for a rexx statement to be inserted between any lines of your code. There are a few exceptions, ppwizard will not insert code before any lines that are known "dangerous" ones such as "then", "do" and "else". If you don't wish to follow the "rules" then do not use any "$trace" facility. You will probably get a rexx trap (unexpected "do" or similar) if a line is incorrect trapped but I'm not going to guarantee this...

This type of tracing can be much easier to understand than normal rexx tracing and also allows you to specify breakpoints (see below). Also unlike OS/2 rexx tracing, Regina's tracing is almost useless. For these reasons and to reduce clutter it is suggested that the PPWIZARD macro "REXXTRACE" be set to "OFF".

To make things easier to understand I'd suggest that you use /beep and /color to turn on beeping on error and color highlighting.

SETTING BREAKPOINTS

You can set a breakpoint so that tracing stops (you are given a rexx debug command prompt) when the trace output contains specified text. You must not be redirecting output when a breakpoint expires otherwise you will of course not be able see anything and ppwizard will be halted (waiting for your replies)!

Before rexx code is executed ppwizard looks to see if the "REXX_BP" macro exists, if it does then this value is used as an initial breakpoint value. The value can be one of the following:

1. A value of "?" indicates that you wish to set a breakpoint that matches all traced lines.

2. A value of "=MacroName" indicates that you wish to call some rexx code you have defined. It could dump variables and/or indicate that you wish to stop (bring up a debug command prompt). Rexx variables that you may wish to use are:

   • rtStop
     Set this variable to "Y" to cause ppwizard to stop (breakpoint expires).

   • RtSearchText
     This variable contains the text that you can compare with to see if a breakpoint should expire. You are more likely to look at the variables directly yourself, if so then please be careful not to try to display variables that don't exist or your tracing code will trap (ppwizard will display the error and continue). You can use the rexx 'symbol()' routine to determine if a variable exists.

3. Any other value indicates that you wish to break on all lines that contain the text you provided (case sensitive). You probably determined a good value by looking at the rexx trace output from a previous run.

   Note that the string "{SOL}" represents the start of a line and "{EOL}" represents the end of a line. All leading and trailing spaces have been removed and there is never two or more spaces in a row.

When a breakpoint expires the current line will be displayed, it will not have been executed and won't be until you press enter at the prompt.

BREAKPOINT COMMAND PROMPT

When a breakpoint expires you will be given a command prompt where you can type:

• Empty Command
  If you don't enter any command (that is simply press [enter]), ppwizard continues until the breakpoint expires again.

• ?
  In case you have forgotten the step you are up to or it scrolled off the screen then you can redisplay just the text of the message again (no variables are dumped).

• ?a[liases]
  This command shows you all aliases that you have created in the past.

• ?#[aliases]
  All commands that you type in are automatically remembered. This command is used to list the commands, to reuse a remembered command you need to specify it by number (which changes as you enter new commands - but not as you use previous ones).

• ?v[ariables]
  This dumps all known variables, for the entire user script. Note that this won't dump whole arrays, just variables that are easily recognisable by looking at the rexx code.

• /alias
  This executes a previously set up command. It's a shorthand way of specifying frequently used commands. If the alias is numeric or begins with '#' then this is referring to an automatic alias and not one that you created.

• /alias=value
  This allows you to specify a command. Do not use an alias that begins with '#' or is numeric.

• BP
  This will prompt you for a new breakpoint. Type "" for none.

• None of the Above
  You have supplied a rexx command which will be executed. If the command is "exit" then ppwizard will terminate! PPWIZARD protects you from syntax errors in this prompt.

  You could use this prompt to "say" the values of rexx variables or anything else you require (run programs or anything else you can normally do in a rexx program).

Example of use is:

    ;--- Define some code that can be called to detect a breakpoint -------
    #DefineRexx TestBreakpointCode "$TRACE_OFF"
                ;--- Simple test (same as simpler REXX_BP value) ----------
                if pos('{SOL}x = 2{EOL}', RtSearchText) <> 0 then
                   rtStop = 'Y';               ;;Want debug prompt!
    
                ;--- Also stop if variable 'FRED' exists and equals '1' ---
                if symbol('FRED') = 'VAR' then
                do
                   if  Fred = 1 then
                       rtStop = 'Y';           ;;Want debug prompt!
                end;
    #DefineRexx
    
    
    ;--- Other possible settings for below --------------------------------------
    ;#define REXX_BP       {SOL}x = 2{EOL}      ;;Set break point for when x = 2 (whole line ie not "x=22" etc)
    ;#define REXX_BP       =TestBreakpointCode  ;;Stop where my code says
    ;#define REXX_BP_ALIAS ;project.a;global.a  ;;Define alias files used (changes NOT saved)
    
    ;--- Define rexx code to be debugged (Execute it) ---------------------
    #define RexxTrace      OFF                  ;;Don't want to see interpreters output
    #define REXX_BP        ?                    ;;Stop anywhere (first $trace)
    #define REXX_BP_ALIAS  project.a;global.a   ;;Define alias files used (changes saved to "project.a")
    #DefineRexx ''
       Fred = 1;
       do x = 1 to 3
          $trace                  ;;trace next command
          y = x; fred2 = Fred;
       end;
    
       ;--- Dump all vars now ---
       $trace Finished, dumping all vars
    #DefineRexx
    

Some sample output (without breakpoint output):

    ---------- REXX TRACE - START(OFF) ----------
    $TRACE: @4 -> y = x; fred2 = Fred
          |    x = 1
          | Fred = 1
    $TRACE: @4 -> y = x; fred2 = Fred
          |     y = 1
          |     x = 2
          | fred2 = 1
          |  Fred = 1
    $TRACE: @4 -> y = x; fred2 = Fred
          |     y = 2
          |     x = 3
          | fred2 = 1
          |  Fred = 1
      $SAY: Finished,dumping all vars
          |  Fred = 1
          |     x = 4
          |     y = 3
          | fred2 = 1
    ---------- REXX TRACE - END(OFF) ----------
    

COMMAND PROMPT ALIASES

If ppwizard finds the "REXX_BP" macro then it also looks for the "REXX_BP_ALIAS" macro. The value of this macro is a list of alias files separated by semicolons.

You as a user are allowed to create your own aliases from the command prompt, these are saved to the first file in the list, if you don't wish to allow saving then begin the list with a semicolon.

All blank lines and lines that begin with ';' are ignored, otherwise the line contains a set alias command of the same format that you use on the command prompt, that is "/alias=value".

Alias names can contain virtually any characters and if duplicated all but the first is ignored when read from a file. An alias specified on the command prompt overwrites any stored.

If you do a lot of ppwizard rexx debugging you will probably want to set up at least project and global level aliases for frequently used commands.

Note that there is no editing of alias commands at the command prompt, if you make a mistake you will need to either recreate the alias or modify the saved file when debugging complete.

AUTOMATIC ALIASES

These aliases are created automatically as you enter new commands. Only successful commands that did not trap are remembered. This facility allows you to refer to previously entered long commands with a short simple number. As you will see below it will also allow you to give "good" commands a decent name at the end of a debug session.

As these aliases are also saved along with normal aliases you can edit the alias file after a debug session to give what you believe will be handly common commands "decent" names. When an alias file is read in the auto alias number is completely ignored so you don't have to worry about creating "holes" etc.

You can control how many commands ppwizard remembers with the "REXX_BP_MAX_AUTO_CMD" macro. This macro should specify the number of commands, if it contains an invalid value or does not exist it will default.

PPWIZARD Manual

Thursday January 17 2002 at 6:27pm