AUTOLISP DEBUGGER version 2.02
(c) Jan Liska & Hynek Bures 1995-1996
Freeware for AutoCAD Release 13 c4

1. INTRODUCTION
AutoLISP Debugger (LD) is a program that can be used for debugging of 
programs written in AutoLISP. Debugger release 2.02 is meant for AutoCAD
Release 13 under DOS, Windows and Windows NT.

2. REQUIREMENTS
This paragraph defines the requirements for software and users of
AutoLISP Debugger.

2.1 SOFTWARE REQUIREMENTS
AutoLISP Debugger release 2.02 demands AutoCAD Release 13. It is written
partially in AutoLISP and partially as ARX application. So it should be
applicable at any hardware platform.

2.2 KNOWLEDGE OF AUTOLISP
As LD is used for debugging of programs under AutoCAD, this manual 
supposes basic knowledge of AutoLISP (Programmer's guide of AutoCAD). LD
is especially made for programmers of application programs under AutoCAD.

3. INSTALLATION OF AUTOLISP DEBUGGER

3.1 CONTENTS OF INSTALLATION FLOPPY DISK
Floppy disk comprises these files:
ld.arx - arx module of AutoLISP Debugger 
ld.dcl - dialogs of AutoLISP Debugger
ld.lsp - part of LD in LISP
example.lsp -
function.lsp - sample of a program

Note: The name of executable of AutoLISP Debugger under UNIX platforms is LD.
If you want more information about availability of AutoLISP Debugger please 
contact the company MiniSoft.

3.2 INSTALLATION OF AUTOLISP DEBUGGER
Installation can be done easily by copying of above mentioned files
into some directory in the path of AutoCAD (typically the
directory C\ACADR13\COMMON\SUPPORT).

If you want to use the example, copy its file there too.

4. DESCRIPTION OF AUTOLISP DEBUGGER
This paragraph describes abilities and main features of LD.

4.1 WHAT IS DEBUGGING
We can say casually that debugging is a process of looking for and
removing of errors. Usually just debugging is the most difficult part of the
creation of the program. You can make the job of your programmers more effective
by using of convenient debugging program. Just LD is such a tool. Let us mention
several of the features which are offered by AutoLISP Debugger.
a. watching of the progress of calculating
b. setting of breakpoints including conditions, pass count and evaluation of
   expressions
c. watching of value of variables (watch) and possibly their changing
d. displaying of the part of the program where the error probably occured
   during the run of the program

4.2 CUSTOM INTERFACE OF AUTOLISP DEBUGGER
LD is an AutoCAD application program. It uses dialog boxes and so its
custom interface is familiar to the user of AutoCAD.

5. NOTES ON RELEASE 2.02 AND KNOWN ERRORS
LD release 2.02 offers debugging of program that are formed of only
one file. In this release the possibility to step over traced function does not
exist.  LD uses temporary files which are placed in working directory and
have permanent names ($work.lsp, and tmp.$$$). Executable under UNIX  
platform is named LD to avoid confusion with Link Editor. Dialog box is big
and when you use VGA card with 640x480 resolution you can meet with problems
(this error will not be eliminated).
Release 2.02 is written mainly in AutoLISP. That influences its speed.
This list is not complete.

6. STARTINIG OF AUTOLISP DEBUGGER
This paragraph describes ways how to use LD -- how to load and how to
trace programs

6.1 LOADING OF AUTOLISP DEBUGGER
If AutoLISP debugger is installed correctly, you can load it from
graphics editor by a command (load "LD"). After succesful loading LD reads
"this is AutoLISP Debugger version 2.02. Use GET to load your program"
Note: On case sensitive platforms (UNIX), you have to write LD in upper-case
letters.

6.2 LOADING OF A FILE INTO AUTOLISP DEBUGGER
Text of the program that is to be traced can be loaded into LD with
a command GET in graphics editor. GET diaplays a standard dialog box of AutoCAD
for selecting of files. Choose a program you want to be traced. Then you will
get the main menu of AutoLISP Debugger.
Note: the command GET loads the content of the file with the program into
memory. Do not use the function (load ..).

6.3. HOW TO USE AUTOLISP DEBUGGER
This paragraph is a detailed description of functionality of AutoLISP
Debugger. LD uses AutoCAD dialog boxes. Therefore its usage is very similar to
the usage of AutoCAD. This paragraph explains only functionality of particular
controlling elements of AutoLISP Debugger. (The way of their usage see User's
guide of AutoCAD).
It would be useful you study this guide sitting at your computer.
The program EXAMPLE.LSP is included in the installation. You can load it and
try all next commands on it.

6.4 MAIN MENU
You will get main menu each time the run of the program is broken.
a. If tracing is set on and the interpret is to evaluate a function of the
   modul loaded by GET
b. Program reached a breakpoint
c. An error occured during the run of the program

For the first time, we get this menu when the command GET is evaluated
(said more exactly when first function of the traced program is evaluated).
If ,for instance, you trace the program EXAMPLE.LSP, it is when the function
defun is evaluated.

In next paragraph, individual controlling elements will be described

6.5 TEXT OF THE PROGRAM
LD displays text of the just traced program. Above it in the upper part,
there is edit field which reads the number of current line. If you want to go
to the line with known number, you can use this field.

Once more about displaying of the program. The line that is to be
interpreted in the next step is marked with the symbol >. Line where the
breakpoint is set is marked with the character +.

6.6. CONTROLLING OF THE RUN OF THE PROGRAM
There are four buttons in the bottom part of the window that directly
influences the run of the program.

6.7 STEP
Using of the button Step causes evaluating of the next line (it is just
the line marked with the symbol > ). If there is the function at this line that
was loaded by the command GET, it will be traced.

6.8 GOTO CURSOR
When you click on this button the program runs as long as
a. the program reaches the line chosen in the text window
b. the program reaches its end
c. the program reaches the breakpoint
d. the error of the program occurs

6.9 RUN
When you click on this button the program runs as long as
a. the program reaches its end
b. the program reaches the bteakpoint
c. the error of the program occurs

6.10 STOP
This button causes finishing of the traced program and calling of the
AutoLISP's function exit.
Note: Of course, warning dialog box of AutoLISP exit/abort appears immediately
after that. This is absolutely correct behaviour of AutoLISP and it does not
mean an error in your program!

6.11 BREAKPOINTS
There is a group of buttons marked Breakpoints in the right upper
corner of the main menu. These buttons operates with breakpoints.

Toggle Breakpoint
When you click at this button you place/remove a breakpoint on the
selected line in the text window of the program.

6.12 OPTIONS
This button is active if there is a breakpoint on the selected line.
After clicking on the button Options, dialog box for setting of properties of
the breakpoint appears.

6.13 SHOW LOG
This button opens record window. The content of the record will be
displayed and deletition of its content will be possible.

6.14 WATCH and DATA
In the bottom part of the main menu, there is a window for watching
values of symbols marked Watch and a group of three buttons marked Data.

6.15 ADD WATCH
The dialog box appears when you click on the button Add Watch. In which
you can insert the name of the symbol which value you want to watch.
Note: The expression have to be atomic.

6.16 DELETE WATCH
When you choose some item in the Watch window and click on the
button Delete Watch, this item will be deleted from the Watch window

6.17 EVAL/MODIFY
When you need to evaluate some expression during the progress of
tracing, click on this button. Dialog box appears.

6.18 OTHER
There is a group of three buttons marked Other in the right part of
the main menu.

6.19 SHOW GRAPH. SCREEN
By clicking on this button you delete (switch) the LD window and the
graphic screen will be displayed if you have one screen system. The main menu
of LD is displayed again after pressing of any key (with the exception of
Ctrl-C). By pressing of this key you delete the LD window. Small dialog box with
only one button appears. When you click on it, you will get again AutoLISP
Debugger. This option is useful especially when you debug the application 
program and want to see the graphical screen.

6.20 SHOW TEXT SCREEN
By clicking on this button you delete the LD window and the text
screen will be displayed if you have one screen system. The main menu of LD
is displayed again after pressing of any key (with the exception of Ctrl-C).

6.21 VIEW FILE
This button calls the offer of files. You can choose the file you
want to view.

6.22 BREAKPOINT OPTIONS
You can get into this window by clicking on the button Options. This
paragraph is a description of the function of individual controlling elements.

6.23 ACTION and ACTION EXPRESSION
Breakpoint activates every time when the line, where the breakpoint
is set and is not turned off by marking of the field Breakpoint Disabled, is
to be interpreted. By default, each time when the breakpoint is activated, the
run of the program is broken and you get the main menu of AutoLISP Debugger.

For changing of behaviour of the breakpoint is radio button Action and
edit field Action Expression in the left part of the dialog box.

Now we can analyse the behaviour of the breakpoint.

Breakpoint causes breaking of the run of the program (default), the field
Action Expression has no meaning in this case. During each activation of
the breakpoint, the expression written in the field Action Expression will
be evaluated. Log behaves similarly to the previous case with the exception
that the result of the expression will be saved and will be displayed using
the button View Log in the main menu.

It is useful when the value of the expression contains also the identification
of the place of its origin and/or the name of the variable. That can be reached
for instance by using the function strcat.
Be aware: if the expression causes an error, it will be reported as run time
error of the program, the program will be irretrievably canceled and you will
have to start again!

6.24 CONDITION and PASS COUNT
Radio button Condition and edit fields Condition and Pass Count in the right
part of the dialog box serve for changing of conditions of the activation
of the breakpoint, 


If the Pass Count is set on some value, the breakpoint will be activated for the
first time after given number of passes (said another way, the value of the
Count is decreased by one during each pass till it has the value equal one).

Second possibility how to influence the behaviour of the breakpoint is that 
you can set the condition which has to be fulfilled for its activation. That
can be done by switching the radio button Condition to have the value
Expression True and writting the condition in the field Condition. The
condition is evaluated and if it is not NIL, the breakpoint is activated.
Be aware: if the expression causes an error, it will be reported as run time
error of the program, the program will be irretrievably canceled and you will
have to start again!

6.25 EVAL/MODIFY
You can get this dialog box by clicking on the button Eval/Modify in
the main menu.

If you write some expression in the edit field Symbol, it will be evaluated and
its value will be displayed in the field Value. If additionally this expression
is an atom, the edit field Set to  activates and a value written here is set
to the symbol in the first field.
Be aware: if the expression causes an error, it will be reported as run time
error of the program, the program will be irretrievably canceled and you will
have to start again!

Checking of the parity of brackets
LD also allowes you to check corresponding brackets directly from the
environment of AutoCAD. This feature can be activated either with the command
testlsp and then you choose the name of the file. Or you will use the function
(testlsp). Its syntax is following (testlsp "filename"). Parametr is not
compulsory and in case that you do not use it, the AutoCAD dialog box for file
choosing will be offered.

After succesful choosing of the file, the window with the text of the program
is displayed. There is a number at the beginning of the line which tells you
the number of just open brackets.

Contact: Jan Liska, CAD Stduio s.r.o., Tylova 17, 370 01 Ceske Budejovice, Czech Republic
         e-mail: honza@cadstudio.cz