Using the Visual LISP Environment 

> Debugging
Programs > 
Expand
All
Expand all
collapsed
sections.
Using the Visual LISP Debugging Features
Collapse
All
Collapse all
expanded
sections.
 
 
 

In addition to setting breakpoints and running in Animate mode, as described in the

Learning by Example section of this chapter, VLISP provides a number of other options
for controlling program execution.

Stop Once
Causes VLISP to break unconditionally when it evaluates the very first LISP
expression encountered. You turn on this mode of operation by choosing Debug

Break on Error from the VLISP menu.

Break on Error
Automatically activates the interactive break loop whenever your program
encounters a runtime error. You turn on this mode of operation by choosing

Debug Stop Once from the VLISP menu.

Note that if this option is selected, some errors that result from function calls
entered at the AutoCAD Command prompt will cause VLISP to get focus. That
is, the active window may switch from AutoCAD to the VLISP Console
window, where you will be in a break loop.

Break on Function Entry

Sets the Debug-on-Entry flag for a function's name symbol, causing a break to
occur every time you invoke that function. At the break, the source code for the
function will be shown in a special window. You can set or clear the Debug-on-
Entry flag interactively with the Symbol Service dialog box. See Using the
Symbol Service Dialog Box for information on setting this flag.
Top-Level Debugging Mode
Controls the loading of a program from a file or an editor window. If the option
is set, breaks occur before evaluating every top-level expression (such as defun).
The Top-Level debugging mode is turned on by switching off the Do Not Debug

Top Level option. To find the check box for this option, choose Tools

Environment Options General Options from the VLISP menu, then click
the Diagnostic tab.

If Top-Level debugging and Stop Once mode are turned on, VLISP will enter the
debugging mode every time you load a file because VLISP is debugging defun, setq,
and other functions defined within the file as they are loaded. This is usually not a
helpful debugging technique and should only be required in rare instances.

Topics in this section

 Starting a Debugging Session

 Understanding Break Loops
 Using Breakpoints

Please send us your comment about this page

Using Visual LISP Debugging Tools > Setting a Breakpoint

and Using More Watches > 
 Expand
All
Expand all
collapsed
sections.
Using the Debug Toolbar
Collapse
All
Collapse all
expanded
sections.
 
 
 

The Debug toolbar contains several tools you will employ as you work through this
section. By default, this toolbar is attached to the View and Tools toolbars, and appears
as a single VLISP toolbar.

The Debug toolbar is the left-most set of icons. Most of the items on the toolbar are
inactive until you run your program in debugging mode (that is, with one or more
breakpoints defined).

If you haven't done so already, detach the Debug toolbar from its position at the top of
the screen. To do this, grab and drag it by the two vertical grips at the left of the toolbar.
You can detach any of the VLISP toolbars and position them on your screen where they
are most effective for your style of work.

The Debug toolbar is divided into three main groups of buttons, each consisting of three
buttons. When you run a program in debugging mode, the toolbar looks like the
following:

 The first three buttons allow you to step through your program code.
 The next three buttons determine how VLISP should proceed whenever it has
stopped at a breakpoint or an error.
 The next three buttons set or remove a breakpoint, add a Watch, and jump to the
position within your source code where the last break occurred.

The last button on the Debug toolbar is a Step Indicator. It does not execute any
function but provides a visual indication of where your cursor is positioned as you step
through your code. When you are not running in debugging mode, this button appears
blank.

To set a breakpoint
 1. In the VLISP editor window containing gpmain.lsp, position your cursor just in
front of the opening parenthesis of the setq function of the following line of
code, within the gp:getPointInput function:

(setq HalfWidth (getdist EndPt "\nhalf-width of path: "))

2. Click the mouse once. The position is illustrated in the following screen
snapshot:

3. With the text insertion point set, choose the Toggle Breakpoint button on the
Debug toolbar.

The Toggle Breakpoint button acts as a toggle, alternating between on and off
states. If there is no breakpoint at the cursor position, it sets one; if there is
already a breakpoint there, it removes it.

4. Choose the Load Active Edit Window button on the Tools toolbar to load the
file.

5. Run the (C:GPath) function from the VLISP Console prompt.

VLISP executes the program normally up to the breakpoint. In this case, it will
prompt you for the first two points—the start point and endpoint of the path.

6. Specify the start point and endpoint when prompted.

After you specify the points, VLISP suspends execution of the program and
returns focus to the text editor window, highlighting the line of code at the
breakpoint position:

There are a couple of things to notice:

 The cursor is located right at the breakpoint. This may be difficult to notice, so
VLISP provides another clue.
 In the Debug toolbar, the Step Indicator icon displays a red I-beam cursor in
front of a pair of parentheses. This indicates the VLISP debugger is stopped
before the expression. Please send us your comment about this page
Using the Visual LISP Environment > Debugging
Programs > Using the Visual LISP Debugging
Features > Understanding Break Loops > 
Expand
All
Expand all
collapsed
sections.
Continuable Break Loops
Collapse
All
Collapse all
expanded
sections.
 
 
 

There are continuable and noncontinuable break loops in VLISP. You can enter the
continuable break loop at the very first break in program execution by any of the
following methods:

 Turning on the Stop Once mode and reaching an expression with debugging
information (that is, an expression that is loaded from source code, as opposed to
from a compiled .exe file)
 Reaching a function marked for Debug on Entry
 Reaching a breakpoint you set in the program
 Entering a break loop by pressing the Pause button
 Proceeding with a Step Over, Step Into, or Step Out command from the previous
break loop state

When the program is interrupted, you enter the break loop. This is apparent if the
VLISP Console window is active, because the prompt is changed to reflect the current
level of the break loop. In this suspended state, you have read-write access to all
variables in the environment in which the break occurred. For example, if the break
occurred within a function containing several local variable declarations, those variables
are accessible and you can change their values by issuing setq assignments at the
Console prompt.

When stopped at a breakpoint, you can control subsequent program execution by

choosing one of the following items from the Debug menu, or by pressing the
equivalent toolbar button:

 Reset to Top Level terminates all currently active break loops and returns to
the Console top-level (the top read-eval-print loop).
  Quit Current Level terminates the current break loop and returns to a break
loop one level up. This may be another break loop or the top-level read-eval-
print loop.

 Continue resumes normal program execution from the breakpoint.

The Step commands evaluate portions of program code before resuming suspended
mode:

 Step Over looks for the close parenthesis matching the open parenthesis
where the program is currently paused, and evaluates the expressions in
between.

 Step Into jumps into a nested expression, if any. If there are no nested
expressions, it jumps to the next expression in sequence.

 Step Out searches for the end of the function where the program is currently
paused, and evaluates all the expressions up to that point.

After you exit the break loop to the Console top-level, the Console prompt returns to its
original form (without a number prefix).
 
 
 Running in Animate Mode
Another debugging feature, animation, allows you to watch as VLISP steps through
your program code and evaluates each expression. In Animate mode, it's as if VLISP
repeatedly enters a Step Into command for you. Text editor windows highlight
expressions being evaluated, and the Watch window continuously updates its data.

To see how Animate mode works

1. Turn on Animate mode by choosing Debug Animate from the VLISP

menu.
2. Enter (yinyang) at the Console prompt to begin executing the program.

You'll see each function highlighted as VLISP evaluates the function. You'll be
prompted for input, as usual. Notice how the Watch window is updated
whenever a watched variable changes. Because you previously set a breakpoint
in the program, execution will halt at that breakpoint.

3. After you stop at the breakpoint, press the Continue button to resume execution;
VLISP resumes executing in Animate mode.

You can also interrupt animation by pressing BREAK (it's the key next to SCROLL-
LOCK on most keyboards). Once animation is paused you can add Watch values, set
variables to new values, and add breakpoints.

To adjust the rate of animation, choose Tools Environment Options General

Options, and select the Diagnostic tab. The Animation Delay setting defines the pause
between program steps, in milliseconds.

To turn off Animate mode, choose Debug Animate from the VLISP menu again.
 
 
 Starting a Debugging Session
The easiest way to start debugging is to choose Debug Stop Once from the VLISP
menu. When this item is selected, the evaluation of the first LISP expression will be
interrupted. After that you can resume program execution using various Debugger
commands. Another way to enter into the debugger mode is to set a breakpoint, as
shown in Setting a Breakpoint to Interrupt Program Execution.

When a break occurs, the corresponding VLISP text editor window will show the
current LISP expression at the point which the break took place. A break loop marker
will appear in the Console window. Using the Console window, you can access and
manipulate the program environment in which the break occurred. You can also
examine variables using the Watch window.
Compiled AutoLISP programs can be loaded and run from either the VLISP Console

window or the AutoCAD Command prompt, or by choosing Tools Load

Application from the AutoCAD menu. This is true of both .fas files and .vlx files, which
may contain multiple compiled programs. (See Making Application Modules for
information on creating .vlx files.)

To run a compiled program from the Visual LISP Console window

1. Load the program by invoking the load function from the Console prompt. For
example, to load the compiled yinyang program created in Walking through a
Compile Example, enter the following command:

(load "c:/program files/<AutoCAD installation directory>

/sample/visuallisp/yinyang.fas")

If you specify a file name without a path or extension, LOAD looks in the
current directory for a matching file name with a .vlx, .fas, or .lsp extension. If
LOAD does not find a match, it continues to search the rest of the AutoCAD
search path for a matching file name. The search stops in the first directory that
contains a matching file name with any of the valid extensions. In that directory,
if there are multiple matching files with valid extensions, the file with the most
recent timestamp is loaded. If there are multiple files with the same timestamp,
the preference order is VLX, FAS, LSP.

If you specify a path to LOAD but omit the file type, the function looks for
VLX, FAS, or LSP files with a matching name in the specified directory, and
loads the one with the most recent timestamp.

If you prefer less typing and more clicking, choose File Load File from the
VLISP menu, and use the Load Lisp File dialog box to select the file you want
to load. Remember to use the Files of Type pull-down list in this dialog box to
specify the type of file you want to load, otherwise VLISP lists only .lsp files in
the dialog box. You can select from the following types:

o Lisp Source Files (.lsp files)

o Compiled AutoLISP Files (.fas files)
o VL Packed Application (.vlx files)
o All files (lists all files in the specified directory)

Choose Open to load the selected files.

2. At the VLISP Console prompt, enter the name of the function you want to run,
enclosing the name in parentheses. For example:

(yinyang)

VLISP transfers control to AutoCAD to display program prompts and accept

user input.
Loading and Running Compiled Programs

Once you load a program, you can run it from either the AutoCAD Command prompt or
the VLISP Console window prompt. Note that if the name of the function you are
running begins with c:, you can invoke it from the AutoCAD Command prompt as if it
were an AutoCAD command, that is, without enclosing the name in parentheses. See for
more information on this feature.

Refer to the AutoLISP Reference for more information on the load function.

Topics in this section

 Loading Extended AutoLISP Functions

 Diagnostic Tab (General Options Dialog Box)
 
 

On the Visual LISP Tools menu, on the Environment Options submenu, the General
Options option displays the General Options dialog box. In the General Options dialog
box, on the Diagnostic tab, the options control how VLISP provides information about
AutoLISP syntax.

The Diagnostic tab's options are as follows:

Report Statistics During Syntax Checking

If this option is selected, the syntax checker and the file compiler report the
statistics after checking or compiling each top-level form and after each file.

Print Top Level Results On Load

If this option is selected, top-level expressions are evaluated and printed in the
Console window when the expressions are loaded.

A top-level expression is one that appears outside any other expression (for
example, an expression that appears outside of defun). For example, the
following call to list is a top-level expression:

(list 1 2 3)

(defun foo (x) x)

Loading a file containing this code results in the following being printed in the
Console window, if Print Top Level Results on Load is selected:

(1 2 3)

FOO

Print Notification Message After Load

If this option is selected, each call to the load function results in messages
printed to the VLISP Console window.

Echo PRINx Output to ACAD

If this option is selected, the default output of functions print, princ and prin1 is
echoed to the AutoCAD Command window and the VLISP Console window
instead of only to the VLISP Console window.
Inspect Drawing Objects Verbosely

If this option is selected, the elements of an object are included in the Inspect
window for a drawing database object. If the option is not selected, only the
object line (containing the entity name) appears in drawing object Inspect
windows.

Do Not Debug Top-Level

If this option is selected and Stop Once mode is set, the break will not occur
before evaluating every top-level form (such as defun) during the file load
process.

Animation Delay

Determines the pause length between program steps in Animate mode, measured
in milliseconds. The default is 100
.

 
Using the Visual LISP Environment > Building
Applications > Designing for a Multiple Document
Environment > Handling Errors in an MDI Environment > 
Expand
All
Expand all
collapsed
sections.
Handling Errors in a VLX Application Running in Its Own Namespace
Collapse
All
Collapse all
expanded
sections.
 
 
 

For VLX applications executing within their own namespace, you can either use the
default error function or you can define an error handler specifically for the application.

If you define an error handler for a VLX running in its own namespace, you can call the
vl-exit-with-error function to pass control from the VLX error handler to the document
namespace's *error* function. The following example uses vl-exit-with-error to pass a
string to the document's *error* function:

(defun *error* (msg)

... ; processing in VLX namespace/execution context
(vl-exit-with-error (strcat "My application bombed! "
msg)))

A VLX *error* handler can use the vl-exit-with-value function to return a value to the
document namespace from which the VLX was invoked. The following example uses
vl-exit-with-value to return the integer value 3 to the program that called the VLX from
the document namespace:

(defun *error* (msg)

 ... ; processing in VLX-T namespace/execution context
(vl-exit-with-value 3))
(vl-doc-export 'foo)
(defun foo (x)
(bar x)
(print 3))
(defun bar (x) (list (/ 2 x) x))

Any instructions pending at the time the error occurred are flushed.

If your VLX namespace error handler does not use either vl-exit-with-error or vl-exit-
with-value, then control returns to the command prompt after execution of the error
handler. You can only call vl-exit-with-error and vl-exit-with-value in the context of a
VLX application's error handler; it is an error to invoke these functions in any other
situation.
   *error*
A user-definable error-handling function

(*error* string)

If *error* is not nil, it is executed as a function whenever an AutoLISP error condition

exists. AutoCAD passes one argument to *error*, which is a string containing a
description of the error.

Your *error* function can include calls to the command function without arguments
(for example, (command)). This will cancel a previous AutoCAD command called with
the command function.

Return Values

This function does not return, except when using vl-exit-with-value.

Examples

The following function does the same thing that the AutoLISP standard error handler
does. It prints the word “error,” followed by a description:

(defun *error* (msg)

(princ "error: ")
(princ msg)
(princ)
Error-Handling Functions
 

The following table provides summary descriptions of the AutoLISP error-handling

functions.

Error-handling functions
Function Description
Displays an alert dialog box with the error or warning
(alert string)
message passed as a string
(*error* string) A user-definable error-handling function
(exit) Forces the current application to quit
(quit) Forces the current application to quit
(vl-catch-all-apply ' Passes a list of arguments to a specified function and traps
function list) any exceptions
(vl-catch-all-error-
message
Returns a string from an error object
error-obj)
Determines whether an argument is an error object returned
(vl-catch-all-error-p arg)
from vl-catch-all-apply