home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / rdebug21.zip / RDEBUG.HLP < prev    next >
Text File  |  1993-03-27  |  10KB  |  229 lines
  1.  m
  2. *
  3. *
  4. *
  5. *
  6. *
  7. rDEBUG
  8.       WJ Gil Gagnon & Associates IncW0
  9.       25-814 Glenn Hawthorne Boulevard
  10.       Mississauga, Ontario L5R 3E6
  11.       416-568-3105
  12.  
  13.  
  14.  
  15.  
  16.                                        rDEBUG
  17.  
  18.  
  19.       Procedure to interactively debug REXX procedures or KEDIT macros.
  20.  
  21.   Syntax:
  22.  
  23.       The format of the rDEBUG command is:
  24.  
  25.       +---------+-----------------------------------------------+
  26.       | rDEBUG  | command/macro_name <source program_parameters>|
  27.       +---------+-----------------------------------------------+
  28.       | defaults| none                                          |
  29.       +---------+-----------------------------------------------+
  30.   Introduction
  31.     Overview:
  32.  
  33.       rDEBUG is a source level debugger of REXX language programs
  34.       and macros, using all common functions of debuggers such as:
  35.       built-in editor, breakpoints, watchpoints, stepping  single
  36.       lines  or  stepping  over  procedures,  selective  tracing,
  37.       logging, restart capabilities, pulldown menus, context help,
  38.       a profiler and a demo program.  The system features fault
  39.       tolerant coding to maintain debugging in spite of coding
  40.       errors.
  41.  
  42.       rDEBUG will facilitate debugging a REXX procedure or KEDIT
  43.       macro in an Integrated Development Environment.  The
  44.       built-in editor is KEDIT on the PC and XEDIT on VM/CMS and
  45.       refered to simply as the Editor.  A debugging macro will be
  46.       generated by placing a copy of the source program to be
  47.       debugged in a special file ( called the d-file), adding
  48.       special commands (or prefix calls) on the left side of most
  49.       lines and appending run time routines.  Then the whole macro
  50.       is invoked.
  51.  
  52.       Program variables may  be examined and  set to new  values.
  53.       Breakpoints may  be set,  instructions may  be skipped  and
  54.       code may be excluded  from being traced.   Automatic breaks
  55.       will occur before any EXIT and after every 50 or  specified
  56.       number of instructions to avoid looping problems.  A  break
  57.       may be  set to  occur when  named variables  change or when
  58.       specified conditions are met.  A count is maintained of the
  59.       number of times  each line in  the source program  has been
  60.       executed.
  61.  
  62.       Most OS/2 and Editor commands may be executed in the command
  63.       line at  a breakpoint  to, for  example, examine  or set  a
  64.       variable.    Other  files  may  be  edited  and may even be
  65.       executed.   In fact, almost all features of  Editor may  be
  66.      
  67.  
  68.  
  69.  
  70.  
  71.                                  rDEBUG                         2
  72.  
  73.       used.  Code may be added, deleted or changed in the  source
  74.       program at any time but RESTART must be invoked to  execute
  75.       it. rDEBUG saves all prefix  calls in a profile which  will
  76.       be reloaded when the program is debugged later.
  77.  
  78.       During a  session all  commands and  messages (except those
  79.       that are made in other than the d-file ) are captured in  a
  80.       file called SESSION.LOG.   At the start of a  new debugging
  81.       session, if a previous  session's LOG file already  exists,
  82.       it  will  be  displayed.    It  can be modified and 'RERUN'
  83.       selected from the menu to  signal to rDEBUG that this  file
  84.       is to be  read and it's  commands are to  be re-executed to
  85.       get to the same point where testing was interrupted.   Keep
  86.       in mind, that this file is renamed INCLUDE.LOG so that  the
  87.       current session may now be captured in SESSION.LOG.
  88.  
  89.     Advantages of rDEBUG over REXX's TRACE:
  90.       1. REXX's TRACE doesn't have true breakpoints only ones that
  91.          occur every nth time.
  92.       2. there is no need to embed TRACE statements in source, then
  93.          remove them later when testing is complete (you may not
  94.          actually be finished yet).  If you do, rDEBUG ignores them.
  95.       3. avoids the cycle of editing source to place TRACE statements,
  96.          then exiting and testing, and re-editing source for
  97.          corrections, etc.
  98.       4. able to immediately retest since profile is automatically
  99.          kept up to date if modified in rDEBUG.
  100.       5. able to avoid SAY command output on an already busy
  101.          screen.
  102.       6. able to isolate REXX's PULL, or Editor's READV commands
  103.          from TRACE's prompt for input.
  104.       7. able to selectively test or not test large or
  105.          long-running sections of code.
  106.       8. able to scroll backward through the session log or d-file to
  107.          see any information that TRACE would have scrolled off screen.
  108.       9. able to stop execution when a specified condition is met.
  109.      10. rDEBUG provides fault tolerance, which logs all error
  110.          conditions connected with event trapping, and ensures
  111.          that the IDE can continue to be used.
  112.  
  113.     Scope of rDEBUG:
  114.  
  115.       A. Tracing:
  116.         1. line-by-line tracing.
  117.         2. excluding the tracing of already debugged code.
  118.         3. optionally, stepping-over user functions and
  119.            procedures.
  120.  
  121.       B. Breakpoints:
  122.         1. automatically at every exit statement.
  123.         2. selectively at every subroutine entry.
  124.         3. you may activate for a single line or range of lines.
  125.         4. automatically at every 50th line or specified number of lines
  126.            executed.
  127.         5. whenever a variable, you designate, changes value or when
  128.            a specified condition is met.
  129.         6. when you press CTRL-BREAK.
  130.  
  131.  
  132.  
  133.  
  134.  
  135.                                     rDEBUG                      3
  136.  
  137.         7. upon leaving the source program, a breakpoint is
  138.            automatically given so that the program can
  139.            be re-executed if so desired.
  140.  
  141.       C.  Editting:
  142.         1. rDEBUG splits the screen vertically with the session log at
  143.            the top and the d-file at the bottom.
  144.         2. you may scroll the source program and session log
  145.            both vertically and horizontally.
  146.         3. most Editor commands will work at any breakpoint.
  147.         4  you may even access other files.
  148.         5. user interface is both via the Editor commandline and
  149.            a menu/shell complete with pulldown menus and dialog
  150.            boxes.
  151.  
  152.       D.  Logging:
  153.         1. each instruction is logged before it is executed.
  154.         2. the results of each variable are displayed.
  155.         3. however, if you work in a file other than the d-file,
  156.            that activity is not captured in the log.
  157.         4  you may embed in the log your own notes or even
  158.            portions of other files.
  159.         5. the log can subsequently be used to recreate
  160.            the last testing session.
  161.  
  162.       E.  Profiling:
  163.         1. each instruction is tallied as it is executed.
  164.         2. the counts can be displayed in a special file
  165.            showing the tally along with each corresponding
  166.            program instruction.
  167.  
  168.       F.  Event trapping:
  169.         1. syntax errors
  170.         2. uninitialized variables
  171.         3. error codes from other external programs are
  172.            reported if non-zero and is a condition that the
  173.            program would normally be prepared to handle.
  174.         4. failure, a command failure is a condition that
  175.            would not normally be recoverable.
  176.         5. halt or user termination via CTRL-BREAK key.
  177.  
  178.       G.  Variables:
  179.         1. any variable may be examined.
  180.         2. variables may be modified
  181.  
  182.       H.  Integrated software tools
  183.         1. Pretty code formatter
  184.         2. Cross reference lister
  185.         3. Syntax checker (or recognizer)
  186.         4. Case formatter (to make programs easier to read)
  187.         5. Tool to show only lines containing REXX flow-of-control
  188.            keywords like 'if', 'then' or 'select'.
  189.         6. Delimiter matching (for comments, quotes and parenthesis
  190.  
  191.  
  192.  
  193.  
  194.                                     rDEBUG                      4
  195.  
  196.       I.  Control of Program Flow
  197.         1.  You may change program flow by using the 'GO no' command,
  198.             where no is a numeric label at the left of an instruction
  199.             in the d-file .
  200.  
  201.   Limitations of rDEBUG:
  202.  
  203.       1. rDEBUG will not operate properly if the source program
  204.          contains a PROCEDURE statement since it causes all
  205.          variables in rDEBUG to be ignored. Therefore, either put
  206.          the procedure in a separate file or remove  the
  207.          statement altogether.
  208.       2. If the source uses the stack to pass information
  209.          to a called program, this information will be read by
  210.          Editor which is the file management engine for rDEBUG.
  211.       3. Routine & program names should not begin w/ 'RD' and
  212.          variable names should not begin with 'DB' as there is only
  213.          one global variable pool shared between your program and rDEBUG.
  214.       4. Only one session of rDEBUG may be run per drive where a
  215.          rDEBUG directory has been set up.
  216.       5. The contents of the function arg() is corrupted by rDEBUG but
  217.          has been simulated so that the values are valid only while
  218.          used in the main (or root) section of the source file.
  219.       6. Certain operating system commands will not work in rDEBUG,
  220.          the following rexx equivalents may be used instead:
  221.          a. 'set' -  use: call value "USERID","Gil","OS2ENVIRONMENT"
  222.          to set USERID to Gil.
  223.          b. 'cd'  -  use: call directory('\rDEBUG') to change to rDEBUG
  224.          directory on current drive.
  225.          c. drive letter and colon - use: call directory('d:\') to
  226.          change to root directory of drive d:.
  227.       7. The linein and lines functions do not work in rDEBUG since OS/2
  228.          make it appear as the file is at end of file.
  229.