RxD (REXX source level debugger)

RxD - a REXX source level debugger by Patrick Mueller (c) Copyright International Business Machines Corporation 1993. All Rights Reserved. --------------------------------------------------------------------- Introduction --------------------------------------------------------------------- RxD is a Presentation Manager source level debugger for REXX programs. It has the following features: - 'single step' through a REXX program - set breakpoints on lines in a REXX program - 'watch' variables - customizable font and colors - save window sizes and positions - console window displays input and output from program The debugger takes the name of a REXX macro and parameters as it's parameters (for example "rxd myprog parm1"). When started, RxD will display the source file in a PM window. Two other windows are available; a watch window to display variables and their values, and a console window to display input and output from the macro. All windows used by RxD are multi-line edit controls - you can copy to the clipboard from them, and all the usual behaviours associated with multi-line edit controls are available. On-line help is available through standard PM help. --------------------------------------------------------------------- Quick Overview --------------------------------------------------------------------- Keys available in all windows ----------------------------- ctrl-w - display the watch window ctrl-s - display the source window ctrl-c - display the console window Settings available in all windows --------------------------------- Font - change the font used in the window Colors - change colors used in the window Window Size and Position - save the current window's size and positions When settings are changed, they are also saved in the system profile (os2.ini). Source Window ------------- The source window is where most of the action happens. You can set breakpoints on lines, add variables to the watch window, single step, restart, etc. When RxD stops at a breakpoint or during single step, it highlights the line that just executed. In most debuggers, the 'current' line (usually highlighted) is the next line to be executed. In RxD, the 'current' line (highlighted) is the line JUST executed. Alas, I'm abusing the REXX trace i/o system exits, and this is the best I could do. Another weird effect is that when single stepping, there are some lines which REXX executes but doesn't 'stop' at, so RxD will step through these lines during one step operation - it will appear to step through multiple lines at once. An example is the end statement. When you start a macro going with 'go', you can cause it to stop and return to single step mode by selecting the 'step' menu item. Keys ---- F5 - run program until next breakpoint or exit F6 - positions the cursor and scrolls to the line last executed F8 - single step F9 - set breakpoint on current line ctrl-a - add current selection to watch window. If nothing is selected, a dialog will prompt you for the variable to watch. Mouse behaviours ---------------- - Double clicking mouse button 1 will select the 'word' the pointer is pointing at. This is a quick way of selecting a variable to add to the watch window. - Double clicking mouse button 1 in the left margin will set or unset a breakpoint on that line. - Two menu buttons are available - one for single stepping, and another to add a variable to the watch window. Watch Window ------------ The watch window displays variables and their values. Values are separated from variables with a tab. Thus, most of the values should line up, but for long variable names, the value may be offset to the right. Values are 'scrubbed' to remove tabs, cr's, lf's, and hex 00's. These characters are replaced with the hex 01 character (smiley face). If 'illegal' variables are added to the window (i.e. "a + b"), they will not be displayed. Keys ---- ctrl-a - add a new variable to watch window ctrl-d - delete variable pointed to by cursor from the watch window Source Window ------------- The source window can display 5 types of input and output - say output - stdout output - stderr output - trace output - input from a pull statement Each type of in/output can be displayed in a different color, and can be captured and hidden. Capturing means placing the text into the source window. Because this can severely degrade performance, you can turn capture off, and the output won't be sent to the window. Capture is a toggle and can be turned on off. Capture is on if a check mark is next to the menu item under the Capture menu. The default is to capture everything but trace output. Capturing trace output severely degrades performance. Hiding means to not display that type of in/output in the source window. This can be used to hide pieces of the text when analyzing it. Hiding is a toggle. When a type of in/output is 'unhidden', it will be displayed in the source window again. The default is to hide nothing. --------------------------------------------------------------------- Limitations --------------------------------------------------------------------- RxD stops on a line AFTER it's executed, instead of BEFORE it's executed. Most program debuggers stop on a line BEFORE it's executed. RxD cannot read lines from the console with the linein() function. Since the console is normally closed by Presentation Manager when a PM application starts, it will appear to the macro that the console is at end of file. Note that 'pull' and 'parse pull' statements are caught by RxD, and will cause a line entry dialog to be displayed. Also note that if standard input is redirected to RxD, this input WILL be picked up by the macro with the linein() function. If the REXX macro being debugged calls another REXX macro which executes a trace statement, RxD will go haywire. What happens is that line number information is returned from the called macro, and that line number information is used to display the original macro. Execute a GO to return to the original macro. OS/2 commands normally handled by CMD.EXE internally, and that also change the state of CMD.EXE will not work properly under RxD. This include the "SET" and "CD" commands, as well as specifying a drive letter and colon to change drives. There are alternatives to these commands: /*----------------------------------------------------------- * return the value of the path environment variable in * the 'path' REXX variable *-----------------------------------------------------------*/ path = value("PATH",,"OS2ENVIRONMENT") /*----------------------------------------------------------- * set the environment variable PATH to the value of the * the 'path' REXX variable, prepended with "c:\;" *-----------------------------------------------------------*/ call value("PATH","c:\;"path,"OS2ENVIRONMENT") /*----------------------------------------------------------- * return current directory *-----------------------------------------------------------*/ currDir = directory() /*----------------------------------------------------------- * go to the c:\ directory *-----------------------------------------------------------*/ origDir = directory("c:\") --------------------------------------------------------------------- Installation --------------------------------------------------------------------- Copy the RXD.EXE to a directory on your path. Copy the RXD.HLP file to a directory in your HELP environment variable. Copy the .DLL file to a directory in your LIBPATH statement (in your CONFIG.SYS).