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