home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / RXD.ZIP / rxd.doc < prev    next >
Text File  |  1993-01-29  |  9KB  |  215 lines
  1.  
  2.                    RxD - a REXX source level debugger
  3.  
  4.                            by Patrick Mueller
  5.  
  6.    (c) Copyright International Business Machines Corporation 1993.
  7.    All Rights Reserved.
  8.  
  9. ---------------------------------------------------------------------
  10. Introduction
  11. ---------------------------------------------------------------------
  12.  
  13.    RxD is a Presentation Manager source level debugger for REXX programs.
  14.    It has the following features:
  15.  
  16.       - 'single step' through a REXX program
  17.  
  18.       - set breakpoints on lines in a REXX program
  19.  
  20.       - 'watch' variables
  21.  
  22.       - customizable font and colors
  23.  
  24.       - save window sizes and positions
  25.  
  26.       - console window displays input and output from program
  27.  
  28.    The debugger takes the name of a REXX macro and parameters as it's
  29.    parameters (for example "rxd myprog parm1").  When started, RxD will
  30.    display the source file in a PM window.  Two other windows are
  31.    available; a watch window to display variables and their values,
  32.    and a console window to display input and output from the macro.
  33.  
  34.    All windows used by RxD are multi-line edit controls -
  35.    you can copy to the clipboard from them, and all the usual
  36.    behaviours associated with multi-line edit controls are
  37.    available.
  38.  
  39.    On-line help is available through standard PM help.
  40.  
  41. ---------------------------------------------------------------------
  42. Quick Overview
  43. ---------------------------------------------------------------------
  44.  
  45.    Keys available in all windows
  46.    -----------------------------
  47.       ctrl-w - display the watch window
  48.       ctrl-s - display the source window
  49.       ctrl-c - display the console window
  50.  
  51.    Settings available in all windows
  52.    ---------------------------------
  53.       Font                     - change the font used in the window
  54.       Colors                   - change colors used in the window
  55.       Window Size and Position - save the current window's size and
  56.                                  positions
  57.  
  58.       When settings are changed, they are also saved in the system
  59.       profile (os2.ini).
  60.  
  61.  
  62.    Source Window
  63.    -------------
  64.  
  65.       The source window is where most of the action happens.  You can
  66.       set breakpoints on lines, add variables to the watch window,
  67.       single step, restart, etc.  When RxD stops at a breakpoint or
  68.       during single step, it highlights the line that just executed.
  69.  
  70.       In most debuggers, the 'current' line (usually highlighted) is the
  71.       next line to be executed.  In RxD, the 'current' line
  72.       (highlighted) is the line JUST executed.  Alas, I'm abusing the
  73.       REXX trace i/o system exits, and this is the best I could do.
  74.       Another weird effect is that when single stepping, there are some
  75.       lines which REXX executes but doesn't 'stop' at, so RxD will step
  76.       through these lines during one step operation - it will appear to
  77.       step through multiple lines at once.  An example is the end
  78.       statement.
  79.  
  80.       When you start a macro going with 'go', you can cause it to stop
  81.       and return to single step mode by selecting the 'step' menu item.
  82.  
  83.       Keys
  84.       ----
  85.          F5     - run program until next breakpoint or exit
  86.          F6     - positions the cursor and scrolls to the line last
  87.                   executed
  88.          F8     - single step
  89.          F9     - set breakpoint on current line
  90.          ctrl-a - add current selection to watch window.  If nothing is
  91.                   selected, a dialog will prompt you for the variable
  92.                   to watch.
  93.  
  94.       Mouse behaviours
  95.       ----------------
  96.          - Double clicking mouse button 1 will select the 'word' the
  97.            pointer is pointing at.  This is a quick way of selecting a
  98.            variable to add to the watch window.
  99.  
  100.          - Double clicking mouse button 1 in the left margin will set
  101.            or unset a breakpoint on that line.
  102.  
  103.          - Two menu buttons are available - one for single stepping,
  104.            and another to add a variable to the watch window.
  105.  
  106.  
  107.    Watch Window
  108.    ------------
  109.  
  110.       The watch window displays variables and their values.  Values are
  111.       separated from variables with a tab.  Thus, most of the values
  112.       should line up, but for long variable names, the value may be
  113.       offset to the right.
  114.  
  115.       Values are 'scrubbed' to remove tabs, cr's, lf's, and hex 00's.
  116.       These characters are replaced with the hex 01 character (smiley
  117.       face).
  118.  
  119.       If 'illegal' variables are added to the window (i.e.  "a + b"),
  120.       they will not be displayed.
  121.  
  122.       Keys
  123.       ----
  124.          ctrl-a - add a new variable to watch window
  125.          ctrl-d - delete variable pointed to by cursor from the watch
  126.                   window
  127.  
  128.    Source Window
  129.    -------------
  130.  
  131.       The source window can display 5 types of input and output
  132.          - say output
  133.          - stdout output
  134.          - stderr output
  135.          - trace  output
  136.          - input from a pull statement
  137.  
  138.       Each type of in/output can be displayed in a different color, and
  139.       can be captured and hidden.
  140.  
  141.       Capturing means placing the text into the source window.  Because
  142.       this can severely degrade performance, you can turn capture off,
  143.       and the output won't be sent to the window.  Capture is a toggle
  144.       and can be turned on off.  Capture is on if a check mark is next
  145.       to the menu item under the Capture menu.  The default is to
  146.       capture everything but trace output.  Capturing trace output
  147.       severely degrades performance.
  148.  
  149.       Hiding means to not display that type of in/output in the source
  150.       window.  This can be used to hide pieces of the text when
  151.       analyzing it.  Hiding is a toggle.  When a type of in/output is
  152.       'unhidden', it will be displayed in the source window again.  The
  153.       default is to hide nothing.
  154.  
  155. ---------------------------------------------------------------------
  156. Limitations
  157. ---------------------------------------------------------------------
  158.  
  159.    RxD stops on a line AFTER it's executed, instead of BEFORE it's
  160.    executed.  Most program debuggers stop on a line BEFORE it's
  161.    executed.
  162.  
  163.    RxD cannot read lines from the console with the linein() function.
  164.    Since the console is normally closed by Presentation Manager when
  165.    a PM application starts, it will appear to the macro that the
  166.    console is at end of file.  Note that 'pull' and 'parse pull'
  167.    statements are caught by RxD, and will cause a line entry dialog
  168.    to be displayed.  Also note that if standard input is redirected
  169.    to RxD, this input WILL be picked up by the macro with the
  170.    linein() function.
  171.  
  172.    If the REXX macro being debugged calls another REXX macro which
  173.    executes a trace statement, RxD will go haywire.  What happens
  174.    is that line number information is returned from the called macro,
  175.    and that line number information is used to display the original
  176.    macro.  Execute a GO to return to the original macro.
  177.  
  178.    OS/2 commands normally handled by CMD.EXE internally, and that
  179.    also change the state of CMD.EXE will not work properly under
  180.    RxD.  This include the "SET" and "CD" commands, as well as
  181.    specifying a drive letter and colon to change drives.  There are
  182.    alternatives to these commands:
  183.  
  184.        /*-----------------------------------------------------------
  185.         * return the value of the path environment variable in
  186.         * the 'path' REXX variable
  187.         *-----------------------------------------------------------*/
  188.        path = value("PATH",,"OS2ENVIRONMENT")
  189.  
  190.        /*-----------------------------------------------------------
  191.         * set the environment variable PATH to the value of the
  192.         * the 'path' REXX variable, prepended with "c:\;"
  193.         *-----------------------------------------------------------*/
  194.        call value("PATH","c:\;"path,"OS2ENVIRONMENT")
  195.  
  196.        /*-----------------------------------------------------------
  197.         * return current directory
  198.         *-----------------------------------------------------------*/
  199.        currDir = directory()
  200.  
  201.        /*-----------------------------------------------------------
  202.         * go to the c:\ directory
  203.         *-----------------------------------------------------------*/
  204.        origDir = directory("c:\")
  205.  
  206.  
  207. ---------------------------------------------------------------------
  208. Installation
  209. ---------------------------------------------------------------------
  210.  
  211.    Copy the RXD.EXE to a directory on your path.  Copy the RXD.HLP
  212.    file to a directory in your HELP environment variable.  Copy the
  213.    .DLL file to a directory in your LIBPATH statement (in your CONFIG.SYS).
  214.  
  215.