-----------------------------------------------------------------------------
====                   RI Debug Library V2.1 (C)1994/5                   ====
-----------------------------------------------------------------------------

                        Written By Stephen McNamara
                       ©1994/5 Leading Edge Software


This library is an extension for the Blitz Basic runtime error debugger by
Leading Edge Software.  It allows your program to give the debugger a set
of simple instructions that are invaluable whilst debugging a program.  They
can only be used in conjunction with version 1.9+ of Blitz Basic 2, and the
updated Acid library debug.obj.

You should note that these commands can *ONLY* be used in amiga mode since
they require the debugger to immediately respond to them.  When in Blitz
mode, multitasking is disabled so the debugger is unable to react to the
commands.  When compiling, Blitz will tell you if you try and use the
commands in Blitz mode.

Additional commands in this library require the related update of the
debugger.  Currently this libraries version number is 2.1, you should have
a debugger version greater than or equal to this number.


A note about variable tracing
-----------------------------

Variable tracing is only performed whilst the debugger is either single
stepping a blitz program, or TRACING a program.  When a program is running
on its own, no update of any windows in the debugger is performed.

Command list:
               AddvarTrace variable,variable$,display_mode
               DelVarTrace variable$
               VarTraceWindow
               DisAsmWindow

New commands:
               CopperTrace address[,offset]

New commands (V1.21):
		ProcControl On/OFf


Statement : AddVarTrace
------------------------------------------------------------------------------
Modes  : Amiga
Syntax : AddVarTrace var,variable$,display_mode

This command adds a variable trace to the debuggers list of traces.  The
parameter 'var' is the actual variable to add to the list, variable$ is the
name which will be printed in the variable window in the debugger (usually
the same as the variable name) and display_mode is the prefered output mode
for the variables value.

The string variable$ will be displayed inside the variable trace window.
This will normally be the name of your variable, but on occasion you might
want some extra info with the name.  In these cases, you can make the
variable$ anything you like, for example "a (counter)" means that we're
tracing variable a but we want to remember that is being used as a counter
inside the program.

The output mode can take the following values, depending of course on the
type of variable:

Bytes/Words/Longs:        0=nocare (default output will be selected)
                          1=decimal
                          2=hexadecimal
                          3=binary

Quicks/Floats:            0=nocare
                          1=decimal

Strings:                  0=nocare (defaults to no length/maxlen data)
                          1=no length/maxlen data
                          2=length/maxlen data displayed

The command will automatically work out the 'type' of your variable and
ensure that the proper output mode is selected.

You should note that you can add the same variable more than once if you
like.  This will be useful if you want to display a variables value in more
than output mode.  For example, you could display the byte sized variable
MYVAR in both decimal and hexadecimal by 'adding' it twice.


Statement : DelVarTrace
------------------------------------------------------------------------------
Modes  : Amiga
Syntax : DelVarTrace variable$

This command instructs the debugger to remove a variable, identified by the
string variable$, from its trace list.  The debugger will look for the name
variable$ and delete *ALL* occurences of this name from the list.  If you
added the variable trace with a different name from the actual name of the
variable, you must ensure that the variable$ matchs that which you used to
add the variable.


Statement : VarTraceWindow
------------------------------------------------------------------------------
Modes  : Amiga
Syntax : VarTraceWindow

This command instructs the debugger to open its variable trace window.
This can save the bother of going to the debugger separately and opening
the window yourself.


Statement : DisAsmWindow
------------------------------------------------------------------------------
Modes  : Amiga
Syntax : DisAsmWindow

This command instructs the debugger to open its disassembly window.  The
disassembly window will open at the address of the command following
DisAsmWindow.  This can be helpful in cases like statements/functions that
are totally assembly since you cannot evaluate the address of a label thats
inside a statement/function.


Statement : CopperTrace
------------------------------------------------------------------------------
Modes  : Amiga
Syntax : CopperTrace address[,offset]

This command instructs the debugger to open its copper window.  If the
offset parameter is passed with the command, the library assumes that
'address' points to a coplist object (e.g. address=addr coplist(0)), it
then adds the offset and takes the longword at that address as the start
position for the window.  Thus, if you wanted to open the copper window
right at the start of coplist 0 you'd do:

		CopperTrace Addr Coplist(0),4

See the coplist object in the debugger for more information about offsets.


Statement : ProcControl
------------------------------------------------------------------------------
Modes  : Amiga
Syntax : ProcControl On/Off

  This command allows you to switch the debuggers procedure control on or
off.  If on, the debugger will not step/trace inside of statements and
functions.  Instead it will execute them as single commands.
  This command is actually the same as toggling the gadget on the debugger
screen.