RapidDBG v1.37  28 August 2010

RapidDBG.exe is a gui wrapper that controls a debugging "session".

The bulk of the work in parsing the users source code is done
using fbDBGParser.dll.  The dll source has been compiled/tested
using FreeBasic v0.21.0 dated 07-24-2010.

The actual "running debugger" is the compiled <users source code> WITH
<debug code> PLUS <RapidDBG.dat> PLUS <some "on the fly" code> generated
by the dll.

The zip file contains all of the source files necessary to create
the new dll and RapidDBG.exe (including example "make" batch file).
A pre-made fbDBGParser.dll is also included.

Unzip all files to an empty folder and check/modify the "make" file.
Create the dll (or use supplied one, after virus check of course!).
Create RapidDBG.exe.
You can move the exe file to any folder you wish.  The dll can be moved
to the same folder, or, you can place it in your RapidQ LIB folder.

When RapidDBG.exe is run for the very FIRST time, you will be asked for your
RapidQ environment. A small "ini" file will be created for all future calls.
The toolbar bitmap and the RapidDBG icon will be extracted into the same
folder as RapidDBG.exe (if they do not exist already).

Usage:
[Stand-alone]
    RapidDBG.exe with no parameters
    Select a file to debug from the File Select Dialog box.

[IDE or Editor or Batch file]
    RapidDBG.exe <switch> <filename> [-b]

    Parameters:
    filename: <bas> or <rqb> file and MUST include the FULL path   

    switch: one of the following (case non-sensitive)
        -c = TEST the original source file (display results on errors)
        -r = compile to exe and run the original source file (if no errors)
        -d = compile debug+source code, if no errors, run the debugger

    Optional switch to -d:
        -b = Preset breakpoints in the form of a string of line numbers
        comma separated, order is not important, but see limitations note 1 below
        eg -b 237,126,1348,23456 sets four breakpoints

RapidDBG will NOT debug source code with line numbers.
RapidDBG does NOT debug "$INCLUDE ....." files.
RapidDBG, currently, will NOT halt at code outside of subs or functions
which means that it is possibly limited for some console applications.
Re-arranging code in console applications can assist in debugging.

_______________________________________________________________________________
Debugging:

RapidDBG will FIRST compile YOUR source code, using rc.exe, and ensure that
there are NO errors (the resultant exe is deleted).
ANY ERRORS WILL BE DISPLAYED AND RapidDBG WILL TERMINATE.

RapidDBG, using the supplied dll, will then parse your source code into a
temporary file (in the same folder as your source code), adding debug
information. RapidDBG will then compile this temporary file, and if no errors,
run the resultant executable.

If your debug+source code compiles and runs successfully, it will either
pause at the first line of the FIRST sub or function executed, or, IF
valid preset breakpoints have been set (with the -b switch), will pause at
the FIRST breakpoint encountered during execution.

Pausing the debugger may involve a user action (eg button click) depending
on the source code you are debugging!
If RapidDBG does not stop (when you think it should) try the Function F4 key
(HALT), if unsuccessful try a user action (eg button click).
In certain circumstances nothing may work, and the process may have to be
"killed" via Task Manager.

On exit, by default, RapidDBG will "clean-up" the temporary files it has created.
To examine these temporary files, you can "comment out" the line
 "$DEFINE TIDY_TEMP_FILES" in RapidDBG.bas and re-compile it.


Error message "### RapidDBG FAILURE ###" displayed:
IF there is a problem compiling the debug+source file (a bug in RapidDBG), this
temporary file will NOT be deleted.  An extract from this file around the designated
error line, emailed to me, would be invaluable, and appreciated, for the benefit of all.
_______________________________________________________________________________
For the novices:

The "$OPTIMIZE ON" directive is not recommended (personal preference).

The "$ESCAPECHARS ON" directive ONLY if your code actually uses "escape" chars in
strings eg DEFSTR mystring="This is a newline\r\nThis is a backslash \\"

The "$TYPECHECK ON" directive is HIGHLY recommended.
This forces you to declare your variables at the expense of some extra typing,
however with copy/paste the little extra effort can save you a lot of time in
finding those "typo" errors!

Local variables:
When the debugger FIRST stops inside a sub/function, any local variables (variables
declared inside the sub/function) will display RANDOM DATA (whatever "junk" is on
the stack). This is NORMAL.
Until your sub/function initialises these variables that "junk" is real and valid,
but it IS random, hence, do NOT count on it being the same, on every call to the
sub/function!  The obvious exception to this is when you declare & initialise a
variable in the same step eg DEFINT a=1

Arrays in RapidQ (and the debugger):
1.  There are no bounds checking in RapidQ when writing/reading to/from arrays, and
    hence there will be no syntax error generated, if your code steps outside of the
    array bounds.

2.  MyArray(1 to 5) indicates that you are using ONLY 5 elements and the debugger
    will ONLY display 5 elements.
    If you choose to write to MyArray(0), or anything above MyArray(5), RapidQ will
    allow this, and will also allow you to read back this data, as well!
    However, you are corrupting the memory of some other variable(s), which could
    give some weird results. Care, especially in loops, should be taken to prevent this.
   
3.  MyArray(5) and MyArray(0 to 5) are equivalent and indicates that you may use
    6 elements for this array. The debugger will display all 6 elements.
    If you do not choose to use MyArray(0) in your code, then it will contain random
    "junk" data, and the debugger will display this, but there will not be any problems.

4.  The above applies to array dimensions 1,2 & 3 (current max limit of 3)

5.  The debugger does NOT parse (nor display) arrays that have a variable as one
    of its dimensions (compare this to a REDIM statement, which equally is not parsed).

6.  Initialised arrays.
    Initialisation starts at the first element, hence:
    DEFINT MyArray(5)={1,2,3,4,5} => MyArray(0)=1, MyArray(1)=2,...,MyArray(5)=undefined
    Whereas:
    DEFINT MyArray(1 to 5)={1,2,3,4,5} => MyArray(1)=1, MyArray(2)=2,...,MyArray(5)=5
   

Window "on top":
If your source code does not set the "minimize" function of your form correctly,
your form will remain on top (of the debugger), and you will need to manually
minimize it, to see the full debugger screen.  I have not found a "fix" for this.
Adding the following to your source file, at the appropriate place, with your form
name, WILL fix the problem.

    SetWindowLong(Your_Form_Name.Handle, -8, 0)
    SetWindowLong(Application.Handle, -8, Your_Form_Name.Handle)

If you get this far, hit the F1 key (or mouse click "Help") for commands available.
_______________________________________________________________________________

KNOWN LIMITATIONS (BUGS?):

1. Any preset breakpoints passed to RapidDBG, using the "-b" switch, that are
   outside of subs/functions will be ignored.
   Any preset breakpoints that are set on non-executable lines of source code,
   inside a sub/function (eg a "DIM" statement), will be ignored.
   If none of these breakpoints are valid then RapidDBG will default to act
   as if NO preset breakpoints were set.

2. Objects and structs (user types) are NOT parsed.

3. "$INCLUDE ...." files, within your source code, are not parsed!
   Generally speaking, you should never NEED to debug these.
   However, to debug an include file, copy the entire code into a "bas" file,
   add some "wrapper" code (to test the include code), and then proceed to
   debug this "bas" file created.
   When you are happy with the results, write the debugged include code back
   into the original "inc" file.
   Note: RapidQ2.inc is ~7500 lines with 1000+ constants & defined constants.
   Not a good idea trying to debug this AND some creation of your making.

4. NO "watch points" as these would definitely slow down the running code.
   Maybe later.

5. Unable to change any variable value "on the fly". Maybe later.

6. REDIM is not parsed. Only the ORIGINAL array bounds are displayed.

7. NO debugging of "in-line" code prior to FIRST Sub/Function eg initialisation
   code mixed with globals at the top of your source code.
   FIX: Create a Sub/Function with all this code in, forward declare it,
   and then call it before you continue with the rest of your code.
   Not hard, I do it in MOST of the code that I write, as a matter of course.

8. SELECT CASE .. END SELECT anomaly
   Any "case" statement line, with multi-statement code separated by the ":"
   character, is not parsed by the debugger and it will NOT pause at this line.
   If you must debug these lines you will need to "split" them in your source code.
        eg SELECT CASE something
                CASE 1: do stuff: do more stuff      ' Debugger will NOT pause here
                CASE 2
                    do even more stuff               ' Debugger WILL pause here...
                    and lastly do more stuff         ' ...and here
                CASE .....etc
    I am not sure why, but believe it is the way that RC.EXE optimises the
    "Select case .. end select" block as a whole, for the interpreter.
    Apologies to William if this is not the case!
    Anyway, the debugger skips these lines when detected.


Finally:
If you haven't already - check out JohnK's IDE (FreeQ IDEa) - available from
http://rapidq.phatcode.net/FreeQ/
FreeQ IDEa is based on the scintilla codebase and tailored for RapidQ. If you
are serious about developing code, get this great IDE.
Currently, RapidDBG is the default debugger for the IDE.

Bugs, comments, suggestions etc welcome.
Contact: d_homans@yahoo.com.au

Happy coding (and bug fixing?)
Rgds to all
Don