 m
*
*
*
*
*
rDEBUG
      WJ Gil Gagnon & Associates IncW0
      25-814 Glenn Hawthorne Boulevard
      Mississauga, Ontario L5R 3E6
      416-568-3105




                                       rDEBUG


      Procedure to interactively debug REXX procedures or KEDIT macros.

  Syntax:

      The format of the rDEBUG command is:

      +---------+-----------------------------------------------+
      | rDEBUG  | command/macro_name <source program_parameters>|
      +---------+-----------------------------------------------+
      | defaults| none                                          |
      +---------+-----------------------------------------------+
  Introduction
    Overview:

      rDEBUG is a source level debugger of REXX language programs
      and macros, using all common functions of debuggers such as:
      built-in editor, breakpoints, watchpoints, stepping  single
      lines  or  stepping  over  procedures,  selective  tracing,
      logging, restart capabilities, pulldown menus, context help,
      a profiler and a demo program.  The system features fault
      tolerant coding to maintain debugging in spite of coding
      errors.

      rDEBUG will facilitate debugging a REXX procedure or KEDIT
      macro in an Integrated Development Environment.  The
      built-in editor is KEDIT on the PC and XEDIT on VM/CMS and
      refered to simply as the Editor.  A debugging macro will be
      generated by placing a copy of the source program to be
      debugged in a special file ( called the d-file), adding
      special commands (or prefix calls) on the left side of most
      lines and appending run time routines.  Then the whole macro
      is invoked.

      Program variables may  be examined and  set to new  values.
      Breakpoints may  be set,  instructions may  be skipped  and
      code may be excluded  from being traced.   Automatic breaks
      will occur before any EXIT and after every 50 or  specified
      number of instructions to avoid looping problems.  A  break
      may be  set to  occur when  named variables  change or when
      specified conditions are met.  A count is maintained of the
      number of times  each line in  the source program  has been
      executed.

      Most OS/2 and Editor commands may be executed in the command
      line at  a breakpoint  to, for  example, examine  or set  a
      variable.    Other  files  may  be  edited  and may even be
      executed.   In fact, almost all features of  Editor may  be
     




                                 rDEBUG                         2

      used.  Code may be added, deleted or changed in the  source
      program at any time but RESTART must be invoked to  execute
      it. rDEBUG saves all prefix  calls in a profile which  will
      be reloaded when the program is debugged later.

      During a  session all  commands and  messages (except those
      that are made in other than the d-file ) are captured in  a
      file called SESSION.LOG.   At the start of a  new debugging
      session, if a previous  session's LOG file already  exists,
      it  will  be  displayed.    It  can be modified and 'RERUN'
      selected from the menu to  signal to rDEBUG that this  file
      is to be  read and it's  commands are to  be re-executed to
      get to the same point where testing was interrupted.   Keep
      in mind, that this file is renamed INCLUDE.LOG so that  the
      current session may now be captured in SESSION.LOG.

    Advantages of rDEBUG over REXX's TRACE:
      1. REXX's TRACE doesn't have true breakpoints only ones that
         occur every nth time.
      2. there is no need to embed TRACE statements in source, then
         remove them later when testing is complete (you may not
         actually be finished yet).  If you do, rDEBUG ignores them.
      3. avoids the cycle of editing source to place TRACE statements,
         then exiting and testing, and re-editing source for
         corrections, etc.
      4. able to immediately retest since profile is automatically
         kept up to date if modified in rDEBUG.
      5. able to avoid SAY command output on an already busy
         screen.
      6. able to isolate REXX's PULL, or Editor's READV commands
         from TRACE's prompt for input.
      7. able to selectively test or not test large or
         long-running sections of code.
      8. able to scroll backward through the session log or d-file to
         see any information that TRACE would have scrolled off screen.
      9. able to stop execution when a specified condition is met.
     10. rDEBUG provides fault tolerance, which logs all error
         conditions connected with event trapping, and ensures
         that the IDE can continue to be used.

    Scope of rDEBUG:

      A. Tracing:
        1. line-by-line tracing.
        2. excluding the tracing of already debugged code.
        3. optionally, stepping-over user functions and
           procedures.

      B. Breakpoints:
        1. automatically at every exit statement.
        2. selectively at every subroutine entry.
        3. you may activate for a single line or range of lines.
        4. automatically at every 50th line or specified number of lines
           executed.
        5. whenever a variable, you designate, changes value or when
           a specified condition is met.
        6. when you press CTRL-BREAK.





                                    rDEBUG                      3

        7. upon leaving the source program, a breakpoint is
           automatically given so that the program can
           be re-executed if so desired.

      C.  Editting:
        1. rDEBUG splits the screen vertically with the session log at
           the top and the d-file at the bottom.
        2. you may scroll the source program and session log
           both vertically and horizontally.
        3. most Editor commands will work at any breakpoint.
        4  you may even access other files.
        5. user interface is both via the Editor commandline and
           a menu/shell complete with pulldown menus and dialog
           boxes.

      D.  Logging:
        1. each instruction is logged before it is executed.
        2. the results of each variable are displayed.
        3. however, if you work in a file other than the d-file,
           that activity is not captured in the log.
        4  you may embed in the log your own notes or even
           portions of other files.
        5. the log can subsequently be used to recreate
           the last testing session.

      E.  Profiling:
        1. each instruction is tallied as it is executed.
        2. the counts can be displayed in a special file
           showing the tally along with each corresponding
           program instruction.

      F.  Event trapping:
        1. syntax errors
        2. uninitialized variables
        3. error codes from other external programs are
           reported if non-zero and is a condition that the
           program would normally be prepared to handle.
        4. failure, a command failure is a condition that
           would not normally be recoverable.
        5. halt or user termination via CTRL-BREAK key.

      G.  Variables:
        1. any variable may be examined.
        2. variables may be modified

      H.  Integrated software tools
        1. Pretty code formatter
        2. Cross reference lister
        3. Syntax checker (or recognizer)
        4. Case formatter (to make programs easier to read)
        5. Tool to show only lines containing REXX flow-of-control
           keywords like 'if', 'then' or 'select'.
        6. Delimiter matching (for comments, quotes and parenthesis
 



                                    rDEBUG                      4

      I.  Control of Program Flow
        1.  You may change program flow by using the 'GO no' command,
            where no is a numeric label at the left of an instruction
            in the d-file .

  Limitations of rDEBUG:

      1. rDEBUG will not operate properly if the source program
         contains a PROCEDURE statement since it causes all
         variables in rDEBUG to be ignored. Therefore, either put
         the procedure in a separate file or remove  the
         statement altogether.
      2. If the source uses the stack to pass information
         to a called program, this information will be read by
         Editor which is the file management engine for rDEBUG.
      3. Routine & program names should not begin w/ 'RD' and
         variable names should not begin with 'DB' as there is only
         one global variable pool shared between your program and rDEBUG.
      4. Only one session of rDEBUG may be run per drive where a
         rDEBUG directory has been set up.
      5. The contents of the function arg() is corrupted by rDEBUG but
         has been simulated so that the values are valid only while
         used in the main (or root) section of the source file.
      6. Certain operating system commands will not work in rDEBUG,
         the following rexx equivalents may be used instead:
         a. 'set' -  use: call value "USERID","Gil","OS2ENVIRONMENT"
         to set USERID to Gil.
         b. 'cd'  -  use: call directory('\rDEBUG') to change to rDEBUG
         directory on current drive.
         c. drive letter and colon - use: call directory('d:\') to
         change to root directory of drive d:.
      7. The linein and lines functions do not work in rDEBUG since OS/2
         make it appear as the file is at end of file.
