Recovering and Altering Execution after an Error

There is nothing more frustrating to end users than a program that misbehaves or terminates without warning and provides them with no information about what went wrong. No program is ever perfect, but you should make every attempt to ensure the users of your custom program the best possible experience by adding proper error handling.

The On Error statement is what you will be using to catch and handle any errors that occur during the execution of a custom procedure. There are two variants of the On Error statement:

• On Error Resume Next instructs VBA to ignore any error it encounters and continue execution with the next code statement.
• On Error GoTo <Line Number or Label> instructs VBA to move execution to a specific label or line number in the current procedure when an error occurs.

The On Error Resume Next statement is the most frequently used variant of the On Error statement, as you typically want to execute the next code statement in a procedure to try to recover from the error.

The following is an example of a procedure that tries to get a layer named ACP-Doors:

Private Function GetLayerACP_Doors() As AcadLayer
  Set GetLayer = ThisDrawing.Layers("ACP-Doors")
End Function

In this procedure, if the layer doesn't exist, the function suddenly terminates and VBA displays an error message. This isn't ideal because the VBA program doesn't perform the expected task and the default error message displayed isn't helpful (see Figure 13.1).

If the On Error Resume Next statement is added to a procedure and inserted before a code statement that could generate an error, no error message is displayed. The procedure that calls the GetLayerACP_Doors procedure would need to check the value that is returned for a valid AcadLayer object or a value of Nothing. Here is what the function would look like with an On Error Resume Next statement added:

Private Function GetLayerACP_Doors() As AcadLayer
  On Error Resume Next
  Set GetLayer = ThisDrawing.Layers("ACP-Doors")
End Function

The On Error GoTo <Line Number or Label> statement can be helpful when you don't want execution to continue to the next code statement in a procedure after an error occurs. The statement On Error GoTo <Line Number> is used to move execution to a code statement within the procedure that starts with a specified line number. VBA does not automatically assign line numbers, and not all code statements need to have a line number. To use this statement, you must manually enter the line number in front of each code statement that should have a line number. The lines don't need to be numbered sequentially, but the numbers specified must be greater than 0; a line number of 0 indicates that error handling should be disabled in the procedure.

The following shows an example of the On Error GoTo <Line Number> statement. An error is generated in the procedure when the Add method of the AcadLayers collection object is executed as a result of the < and > characters, which are not valid, in the layer name. When the error occurs, execution is moved to the code statement with line number 9 to its left.

Public Sub CreateLayer()
1  On Error GoTo 9
   Dim sName As String
3  sName = "<Bad Name>"
5  ThisDrawing.Layers.Add sName
   MsgBox "Layer " & sName & " was added."
   Exit Sub
9  Err.Clear
   ThisDrawing.Utility.Prompt _
       vbLf + "Error: Layer couldn't be created."
   GoTo 1
End Sub

As an alternative to using line numbers to specify a location within a procedure, you can use labels that have more meaningful names than 1, 5, 9, and so on. A label starts on a new line in a procedure and ends with a colon. For example, you could create labels with the names LayerNotFound, BadName, and ErrHandler. LayerNotFound might contain code statements that should be executed if a layer wasn't found, BadName might contain code statements to handle an invalid name passed to the Add method of the AcadLayers collection, and ErrHandler might be a generic label to handle all other errors that are generated. Although multiple labels can be used in a procedure, only one can be used with the On Error GoTo <Label> statement in a procedure.

The following shows an example of the On Error GoTo <Label> statement. In this case, an error could be generated by the code statement Set oLayer = ThisDrawing.Layers(sName) as a result of the layer ACP-Door not being found in the drawing. When the error occurs, execution is moved to the label LayerNotFound in the procedure where the layer is added to the drawing. The newly added layer is assigned to the oLayer variable. Once the layer is added, execution is returned to the oLayer.color = acBlue statement using the Resume Next statement.

Public Sub GetLayer()
  On Error Resume Next
  Dim sName As String
  sName = "ACP-Door"
  On Error GoTo LayerNotFound
  Dim oLayer As AcadLayer
  Set oLayer = ThisDrawing.Layers(sName)
  oLayer.color = acBlue
  Exit Sub
LayerNotFound:
  Set oLayer = ThisDrawing.Layers.Add(sName)
  Resume Next
End Sub

Getting Information About the Recent Error

The Err object is part of the VBA programming language, and it holds information about the most recent error that was generated during the execution of a procedure. If you want to learn more about the Err object, you can look up ErrObject (not Err) in the VBA Help system or the Object Browser of the VBA Editor. You can use a combination of the On Error and If statements to determine whether an error occurred. The value of the Err object's Number property is 0 by default, and is changed to a nonzero number when an error occurs.

The value of the Number property isn't always very helpful or decipherable by us humans. For example, the value of 5 could mean “Invalid procedure call or argument” for one software vendor's object library but have a different meaning for another library from a different vendor. You will want to contact the software vendor or use your favorite Internet search engine to see if you can obtain a listing of error values and their meaning. For humans, the Err object also has a Description property. The Description property of the Err object provides a basic explanation of the error that occurred, but even this can be a bit cryptic if you don't understand the terminology used.

The following example first tries to get the layer 10101 in the AcadLayers collection object of the current drawing. If the layer exists, no error is generated and nothing happens. If the layer doesn't exist, an error is returned and the code statements in the If statement are executed.

Private Sub CreateLayer10101()
  On Error Resume Next
  Dim obj As AcadLayer
  Set obj = ThisDrawing.Layers("10101")
  If Err.Number <> 0 Then
    MsgBox "Number: " & CStr(Err.Number) & vbLf & _
           "Description: " & Err.Description
    ThisDrawing.Layers.Add "10101"
  End If
End Sub

The first time the procedure is executed, an error occurs and a message, shown in Figure 13.2, is displayed, indicating that the key (the layer in this case) wasn't found. As part of the If statement, the layer is added to the drawing, and executing the procedure a second time results in no error or message being displayed because the layer already exists.

Table 13.1 lists the other properties of the Err object that can be used to get information about the most recent error.

The Err object supports two methods: Clear and Raise. The Clear method allows you to reset the Err object to its default state so that you can continue execution of your procedure and handle additional errors. Though not used as frequently, the Raise method can be used to generate an error from a custom procedure within a program. The error that is generated can then be caught with the On Error statement by the calling procedure.

The following example shows two custom procedures, a subroutine and a function, that are used to create a new layer. The On Error and Err objects are used to handle the errors that might occur.

Public Sub AddLayer()
  On Error Resume Next
  ' Call the CreateLayer function with a bad layer name
  CreateLayer "<BadName>", acBlue
  ' If an error occurs in the CreateLayer function,
  ' display a message
  If Err.Number <> 0 Then
    MsgBox "Number: " & CStr(Err.Number) & vbLf & _
           "Description: " & Err.Description
  End If
End Sub
' Creates a new layer and returns the AcadLayer object
Private Function CreateLayer(sName As String, _
                             nClr As ACAD_COLOR) As AcadLayer
  On Error Resume Next
  ' Try to get the layer first and return it if it exists
  Set CreateLayer = ThisDrawing.Layers(sName)
  ' If layer doesn't exist create it
  If Err.Number <> 0 Then
    Err.Clear
    On Error GoTo ErrHandler
    Set CreateLayer = ThisDrawing.Layers.Add(sName)
    CreateLayer.color = nClr
  End If
  ' Exit the function if it gets this far
  Exit Function
' If an error occurs when the layer is created, raise an error
ErrHandler:
  Err.Raise Err.Number, Err.Source, Err.Description, _
            Err.HelpFile, Err.HelpContext
End Function

In the previous example, the AddLayer procedure passes the CreateLayer procedure a name and color. The layer name that is passed is invalid and causes an error to occur in the Add method of the AcadLayers collection object. The On Error Resume Next statements are used to keep execution going, whereas the On Error GoTo <Label> statement allows execution to be moved to the general error handler. The general error handler in the CreateLayer procedure uses the Raise method of the Err object to pass an error up to the AddLayer procedure so that it can handle what should be done next.

Debugging Through Messages

One of the simplest forms of debugging a program is to display messages at the AutoCAD^® Command prompt or in a message box during execution. These messages are displayed periodically as your program executes to let you know which code statements are about to be executed next. You can think of this form of debugging much like the children's game “Red Light, Green Light.” Every so often you use a unique message in your program so you have an understanding of progress during the execution of the program. In the game “Red Light, Green Light,” you randomly shout out “Red Light” or “Green Light” to ensure people are paying attention and to keep the game moving.

To debug through messages, you place a messaging function every 5 to 10 statements in a custom procedure; place the debugging messages too frequently (or infrequently), and they become less useful. The Prompt method of the AcadUtility object and the VBA MsgBox functions are the most commonly used techniques for displaying a message; I tend to lean away from the MsgBox function as it adds unnecessary extra steps to executing a procedure. Once debugging is completed, you can comment out the messaging code statements so they are not displayed to the end user.

The following is an example of a custom procedure that contains two errors and demonstrates how messaging functions can be used to help identify the bad statements. You will step through this code as part of the exercise later in this chapter under the “Stepping Through the BadCode VBA Project” section.

Sub BadCode()
  ' Prompt for string
  Dim sVal As String
  sVal = ThisDrawing.Utility.GetString(True, vbLf & "Enter a string: ")
  ' If str is not empty, continue
  If IsEmpty(sVal) = False Then
    ThisDrawing.Utility.Prompt vbLf & "DEBUG: Inside IF"
    ' Error 1, - should be &
    ThisDrawing.Utility.Prompt vbLf & "Value entered: " - sVal
    ' Prompt for integer
    Dim nVal As Integer
    nVal = ThisDrawing.Utility.GetInteger(vbLf & "Enter an integer: ")
    ThisDrawing.Utility.Prompt vbLf & "DEBUG: Ready to divide"
    ' Error 2, if the user enters 0, cannot divide by 0
    ThisDrawing.Utility.Prompt vbLf & "Divisor: " & CStr(2 / nVal)
  Else
    ThisDrawing.Utility.Prompt vbLf & "DEBUG: If…Else"
  End If
  ThisDrawing.Utility.Prompt vbLf & "DEBUG: Outside IF"
End Sub

If you execute the previous example, the following prompts are displayed the first time you execute the procedure:

Enter a string: Hello World!
DEBUG: Inside IF

If you change "Value entered: " - sVal to "Value entered: " & sVal and execute the procedure again, the following messages are displayed at the AutoCAD Command prompt if 0 is entered when prompted for an integer:

DEBUG: Inside IF
Value entered: Hello World!
Enter an integer: 0
DEBUG: Ready to divide

If a value other than 0 is entered, the following messages are displayed:

DEBUG: Inside IF
Value entered: Hello World!
Enter an integer: 2
DEBUG: Ready to divide
Divisor: 1
DEBUG: Outside IF

Using the VBA Editor Debug Tools

Although the On Error statement and Err object are useful in catching and handling errors during execution, the VBA Editor offers several tools that can be helpful in determining what happened during the execution of a procedure that led to an error. The VBA Editor offers the following features that can be used to debug a program:

• Output values to and execute a code statement using the Immediate window
• Interrupt the execution of a procedure and step through the code statements of a procedure in real time using breakpoints
• Check the value of a variable during the execution of a procedure and get notified of when the value changes by establishing a watch on a variable

Outputting Information to the Immediate Window

The Immediate window of the VBA Editor allows you to view the debug output from a program. You can display the Immediate window by pressing Ctrl+G or by clicking Immediate Window in the View menu or Debug toolbar. Although the Immediate window is used primarily to output debug information, it can also be used to execute a single code statement. To execute a code statement in the Immediate window, type a code statement such as MsgBox ThisDrawing.WindowTitle and press Enter.

When you use the VBA Debug object, the resulting values and messages are output to the Immediate window, where they aren't visible to the user running the VBA project from the AutoCAD user interface. The Debug object supports two output methods: Print and Assert. The Print method accepts most data types with the exception of an object and displays the value to the Immediate window.

The following shows an example of using the Print method to output values and messages to the Immediate window:

Sub DivByZeroDebug()
  Debug.Print "Start DivByZeroDebug"
  Dim nVal As Integer, nDiv As Integer
  nVal = ThisDrawing.Utility.GetInteger(vbLf & "Enter an integer: ")
  Debug.Print "User entered: " & nVal
  If nVal <> 0 Then
    nDiv = nVal / 2
    MsgBox nDiv
    Debug.Print "Calculated value: " & nDiv
  End If
  Debug.Print "End DivByZeroDebug"
End Sub

Figure 13.3 shows the results of the Debug.Print statements in the Immediate window before the error occurred. Using this technique, you can then deduce that the error occurred after the last message output in the Immediate window and before the next Debug.Print statement.

Stepping Through a Procedure

The VBA Editor enables you to step through a program while it is being executed with the use of a feature known as breakpoints. Breakpoints allow you to specify a position in a VBA program at which execution should be suspended. While the program is suspended, you can check the current values of a variable and move execution forward one code statement at a time using the code stepping tools, where execution is currently suspended.

While you are in the code editor window, you can set breakpoints quickly by doing any of the following:

• Clicking in the left margin adjacent to a code statement
• Placing the cursor on the desired line and pressing F9
• Right-clicking on a code statement and choosing Toggle Breakpoint from the context menu

When a breakpoint is placed, a circle is displayed in the left margin and the code statement is highlighted; see Figure 13.4. (By default, the circle and highlight are maroon colored; you can change the color using the Options dialog of the VBA Editor.) Click a breakpoint that is set in the left margin to remove it.

Once one or more breakpoints have been set, you can execute the procedure from the VBA Editor or the AutoCAD user interface with the vbarun command. Execution starts and is suspended when the first breakpoint is encountered. The VBA Editor moves to the foreground and the code editor receives focus when execution is suspended. A yellow arrow—known as the execution point—and highlighted code indicate the code statement that will be executed next (see Figure 13.4).

While execution is suspended, you can position the cursor over a variable to see its current value in a tooltip (see Figure 13.4). You can also see the current values of all variables in the current procedure using the Locals window or those that are being watched in the Watches window. I discuss the Locals and Watches windows in the next section.

Execution of the procedure can be continued by stepping into, over, or out of a code statement. To step through the code statements of a procedure, you choose one of the following options on the Debug menu or toolbar.

1. 
   Choose Step Into when you want to step through each code statement in a procedure and continue stepping into other procedures that are called.
2. 
   Use Step Over when you want to step through each code statement in a procedure but don't want to continue stepping into other procedures that are called.
3. 
   The Step Out tool resumes normal execution for the code statements in the current procedure. If execution is suspended in a procedure that was called from the original procedure, normal execution is resumed for the called procedure and is suspended when execution returns to the calling procedure.
4. 
   Normal execution can be restored by choosing Continue on the Run menu or Debug toolbar.
5. 
   Debugging can be terminated by choosing Reset on the Run menu or Debug toolbar.

Watching Variable Values

Many people like to watch birds or go whale watching. As a programmer, I have often found watching variable values enjoyable. The VBA Editor allows you to view the current value of one or more variables or see the result of a code statement while a program is executing. It can also let you know when the value of a variable changes or evaluates to True.

In the VBA Editor, either the Locals window or the Watches window can be used to view the current value of the variables in a procedure while execution is suspended using a breakpoint or when an assertion occurs:

1. 
   Locals WindowThe Locals window, shown in Figure 13.5, allows you to view the value of each local variable in the procedure that currently has execution focus. (The procedure that has the execution focus is the procedure that contains the next code statement to be executed.) You don't need to follow any extra steps to get the variables to display in the window. You can display the Locals window by choosing Locals Window from the View menu or by clicking the Locals Window icon on the Debug toolbar. When the Locals window is displayed, click the ellipsis button in the upper-right corner of the window to open the Call Stack window. The Call Stack window allows you to view the variables dimensioned in either the procedure that has execution focus or the calling procedure that is currently executing.
2. 
   Watches WindowThe Watches window, shown in Figure 13.6, allows you to view the value of a specific variable or the return value of a statement in a similar fashion to how the Locals window does. However, the Watches window displays the values only for the variables you are interested in knowing more about. You can also use the Watches window to be notified when the value of a variable changes or whenever the value of a variable or code statement evaluates to True. Display the Watches window by choosing Watch Window from the View menu or by clicking the Watches Window icon on the Debug toolbar.
3. To add a variable or statement to the Watches window, use the following steps:
   1. In the code editor window, select a variable or code statement to add to the Watches window.
   2. Right-click the highlighted text and click Add Watch.
   3. When the Add Watch dialog box (see Figure 13.7) opens, verify that the variable or statement is displayed in the Expression text box. If not, close the Add Watch dialog box and try again. As an alternative, you can simply type into the Expression text box the code statement or variable name you want to watch.
   4. Optionally, you can change the context in which the value of the variable or code statement should be evaluated. The default context is based on where you highlighted the text in your project. You can set the procedure or module settings to (All Procedures) or (All Modules) to display the current value of a variable or code statement no matter what procedure is currently being executed.
   5. Optionally, you can change the watch type. The default is Watch Expression, which displays the current value of the variable or returns the value of the code statement in the specified context. Choose Break When Value Is True or Break When Value Changes if you want to debug your program when the value either is True or changes while executing the program.
   6. Click OK.

      You can modify a watch by selecting it in the Watches window and right-clicking. When the context menu opens, choose Edit Watch (to make changes to the watch entry) or Delete Watch (to remove the watch).

Loading a VBA Project

VBA programs are stored in DVB project files that must be loaded into AutoCAD before they can be used. A number of methods can be used to load a DVB file. These methods fall into one of two categories: manual or automatic. Most DVB files are loaded using one of the manual techniques.

<?xml version="1.0" encoding="utf-8"?><!DOCTYPE component PUBLIC "-//JWS//DTD WileyML 20110801 Vers 3Gv2.0//EN" "Wileyml3gv20-flat.dtd"><Components Description="Windows OSs">
    <ComponentEntry Description="Loader file"
       AppName="DrawPlateMainLoader"
       Version="1.0"
       ModuleName="./Contents/DrawPlateLoader.lsp">
    </ComponentEntry>
    <ComponentEntry Description="Main file"
       AppName="DrawPlateMain"
       Version="1.0"
       ModuleName="./Contents/DrawPlate.dvb">
    </ComponentEntry>
  </Components>
</ApplicationPackage>

DrawPlate_VBA.bundle
      PackageContents.xml
   Contents
      DrawPlate.dvb
      DrawPlate_VBA.htm
      DrawPlateLoader.dvb

Specifying the Location of and Trusting a Project

The DVB files that you create or download from the Internet can be placed in any folder on a local or network drive. I recommend placing all your custom files in a single folder on a network drive so they can be accessed by anyone in your company who might need them. Placing the files in a network location makes rolling out changes easier as well. You might consider using the name DVB Files or VBA Project Files for the folder that contains your DVB files.

I also recommend marking any folder(s) that contain custom files on the network as read-only for everyone except for those designated to make updates to the files. Marking the folders as read-only helps prevent undesired or accidental changes.

Regardless of the folder name you use or where you choose to place your DVB files, you need to let AutoCAD know where these files are located. To do so, add each folder that contains DVB files to the Support File Search Path and the Trusted Locations settings accessible through the Options dialog box.

The support file search paths are used by AutoCAD to locate custom files, such as those that contain block definitions, linetype patterns, AutoLISP programs, and VBA projects. Use the Options dialog box to add the folders that contain DVB files to the support file search paths of AutoCAD.

If you are using AutoCAD 2013 SP1 or later, when you try to load a DVB file AutoCAD checks to see if the DVB file being loaded is from a trusted location. A folder that you identify as a trusted location contains DVB files that are safe to be loaded without user interaction. The Trusted Locations setting in the Options dialog box or the trustedpaths system variable are used to specify trusted locations. Any DVB file that isn't loaded from a trusted location results in the File Loading - Security Concern message box (see Figure 13.8) being displayed.

The File Loading - Security Concern message box indicates why it might not be a good idea to load the file if its origins aren't known. Loading files with an unknown origins could introduce malicious code. The end user then must decide to load (or not load) the file before the AutoCAD program can complete the load. When adding new trusted locations, make sure you limit the number of folders you trust. Further, trusted folders should be marked as read-only to avoid the introduction of unknown DVB files or other custom programs to the folders. For more information on trusted paths, see the trustedpaths system variable in the AutoCAD Help system.

The following steps explain how to add a folder to the support file search paths and trusted locations used by AutoCAD:

1. Click the Application menu button Options (or at the Command prompt, type options and press Enter).
2. When the Options dialog box opens, click the Files tab.

The following steps explain how to add a folder to the AutoCAD support file search paths:

1. Select the Support File Search Path node. Click Add and then click Browse.
2. In the Browse For Folder dialog box, browse to and select the folder that contains your DVB files.
3. Click OK.

The following steps explain how to add a folder to the AutoCAD trusted locations:

1. Select the Trusted Locations node and click Add, and then click Browse.
2. In the Browse For Folder dialog box, browse to and select the folder that contains your DVB files.
3. Click OK.
4. If the selected folder is not read-only, the Trusted File Search Path - Security Concern dialog box will be displayed. Click Continue to add the folder.
5. Click OK to save the changes to the Options dialog box.

If the location of your custom programs changes, you can replace an existing folder in the Options dialog box by expanding the Support File Search Path or Trusted Paths node and selecting the folder you want to replace. After selecting the folder you want to replace, click Browse and then select the new folder.

Starting a Macro with AutoLISP or a Command Macro

Executing a VBA macro from the Macros dialog box can be a bit overwhelming to an end user since the dialog box lists all the available macros from each of the VBA projects that are currently loaded into the AutoCAD drawing environment. Most end users are accustomed to starting a command from the user interface or even typing a command at the AutoCAD Command prompt.

A VBA macro can be executed from a command macro in the user interface or at the Command prompt using the AutoLISP vl-vbarun function or the -vbarun command. Both methods achieve the same result and can be used interchangeably.

The following examples show how to execute the CLI_DrawPlate procedure defined in the basDrawPlate code module of the DrawPlate.dvb file with the vl-vbarun function and the -vbarun command using the AutoLISP command function:

; Execute macro with vl-vbarun
(vl-vbarun "DrawPlate.dvb!basDrawPlate.CLI_DrawPlate")
; Execute macro with command function and -vbarun command
(command "._-vbarun" "DrawPlate.dvb!basDrawPlate.CLI_DrawPlate")

The following shows how to execute the CLI_DrawPlate procedure defined in the basDrawPlate code module of the DrawPlate.dvb file with the -vbarun command at the AutoCAD Command prompt:

Command: -VBARUN
Macro name: DrawPlate.dvb!basDrawPlate.CLI_DrawPlate

(vl-vbarun "c:\users\lee\documents\mycustomfiles\DrawPlate.dvb!basDrawPlate.CLI_DrawPlate") instead of (vl-vbarun "DrawPlate.dvb!basDrawPlate.CLI_DrawPlate")

Although VBA doesn't allow you to create a custom command that end users can enter at the Command prompt like AutoLISP, ObjectARX^®, or Managed .NET does, you can use AutoLISP as a wrapper to execute a VBA procedure.

The following shows how to use AutoLISP to define a custom command named -drawplate_vba that an end user could use to execute the CLI_DrawPlate macro:

(defun c:-drawplate_vba ( )
  (vl-vbarun "DrawPlate.dvb!basDrawPlate.CLI_DrawPlate")
)

Grouping Actions into a Single Undo

When a VBA macro is executed, users tend to expect certain things to occur before or after the use of any custom program. Users expect that any changes to system variables will be restored if those variables affect drawings, and they expect that when they type u and press Enter any changes to the drawing will be rolled back. A single undo record isn't always created when a VBA program is executed, especially when the SendCommand or PostCommand method of the AcadDocument object is used. I discussed these methods in Chapter 3, “Interacting with the Application and Documents Objects.”

It is good practice to call the StartUndoMark and EndUndoMark methods of the AcadDocument object when a VBA program makes changes to a drawing. The StartUndoMark method should be called before the first change is made, and the EndUndoMark method should be called after the last change is made. The methods instruct AutoCAD to group the operations between the two methods into a single undo record, making it easier for the user to roll back any changes made by a VBA program.

Protecting a Project

A lot of time and effort can go into developing a VBA project, and a VBA project may include information about proprietary processes or intellectual property. The VBA Editor offers a way to password-protect the code and components of a VBA project. When a VBA project is password-protected, the VBA project can be loaded and macros can be executed without entering a password. But when anyone wishes to edit the code and components, the password must be entered.

The following steps explain how to password-protect a VBA project:

1. Load a DVB file into the AutoCAD drawing environment.
2. In the VBA Editor, click Tools <Project Name> Properties.
3. When the <Project Name> - Project Properties dialog box opens, click the Protection tab.
4. On the Protection tab, check the Lock Project For Viewing check box and enter a password in the Password and Confirm Password text boxes.
5. Click OK.

Stepping Through the BadCode VBA Project

In this exercise, you'll work with the badcode.dvb file that came with this book and was shown in the “Debugging Through Messages” section. Stepping through a program code statement by code statement allows you to identify what is happening in your code, determine whether it is executing as expected or if an error occurs, and see which branches of a program are being followed based on the results of the logical tests. Additionally, you can view the current values of the variables in the program at specific times to ensure they have the correct data before they are passed to a function.

The following steps explain how to set a breakpoint and add watches to the Watches window:

1. Open the VBA Editor and load the badcode.dvb file.
2. In the Project Explorer of the VBA Editor, double-click the basBadCode component.
3. In the code editor window, locate the statement that is below the comment ' Error 1, - should be &. Click in the left margin adjacent to the code statement to set a breakpoint.

   The code editor window should now look like Figure 13.9.

4. In the code editor window, in the first few code statements of the BadCode procedure locate the variable sVal.
5. Double-click the sVal text to select it and then right-click the selected text. Choose Add Watch from the context menu.
6. When the Watches window opens, in the Watch Type section choose Break When Value Changes and click OK.
7. If the Watches window is in the way, drag it away from the code editor window.
8. In the code editor window, right-click and choose Add Watch.
9. When the Watches window opens, replace the text in the Expression text box with CStr(2 / nVal) and click OK.

   The Watches window should now look like Figure 13.10.

The following steps explain how to step through the code statements of the BadCode procedure:

1. Switch to AutoCAD.
2. At the Command prompt, type vbarun and press Enter.
3. When the Macros dialog box opens, select the BadCode procedure from the Macros list. Click Run.
4. At the Enter a string: prompt, type Hello World! and press Enter.

   Execution of the BadCode procedure is suspended as a result of the watch setup for the sVal variable. The If IsEmpty(sVal) = False Then code statement is also highlighted, indicating which code statement will be executed next when execution resumes.

5. Review the current value of the sVal variable in the Watches window. The value of the sVal variable in the Watches window should now be listed as “Hello World!”

   

6. In the VBA Editor, click Run Continue to resume normal execution.

   Execution is suspended again when the breakpoint is reached.

   

7. In the VBA Editor, click Debug Step Into to execute the highlighted code statement and move execution to the next code statement.
8. When the Microsoft Visual Basic error message is displayed, click Debug.

   The type mismatch error is the result of the text - sVal in the code statement.

9. In the highlighted statement, change the text "Value entered: " - sVal to "Value entered: " & sVal.
10. Press F8 to execute the highlighted code statement and move execution to the next code statement.
11. Click Debug Clear All Breakpoints to remove the breakpoint that was set.
12. Click Run Continue to resume normal execution.
13. Switch to AutoCAD.
14. At the Enter an integer: prompt, type 4 and press Enter.
15. Press F2 to expand the Command Line history.

    The Command Line history shows the following messages:

DEBUG: Inside IF
Value entered: Hello World!
Enter an integer: 4
Command:
DEBUG: Ready to divide
Divisor: 0.5
DEBUG: Outside IF

Implementing Error Handling for the Utility Procedures

As you make changes to the procedures in the clsUtilities class module, notice how easy it can be to implement error handling for your utility functions.

The following steps explain how to update the CreateLayer procedure to handle general problems and pass the error to the calling procedure:

1. Load the drawplate.dvb file that you last updated in the exercises for Chapter 11, or rename the file ch13_drawplate.dvb to drawplate.dvb and then load the renamed file.
2. In the Project Explorer, double-click the clsUtilities component.
3. In the code editor window, scroll to the CreateLayer procedure and add the bold text:

   Public Function CreateLayer(sName As String, _
                               nClr As ACAD_COLOR) As AcadLayer
     On Error Resume Next
     ' Try to get the layer first and return it if it exists
     Set CreateLayer = ThisDrawing.Layers(sName)
     ' If layer doesn't exist create it
     If Err Then
       Err.Clear
       On Error GoTo ErrHandler
       Set CreateLayer = ThisDrawing.Layers.Add(sName)
       CreateLayer.color = nClr
     End If
     ' Exit the function if it gets this far
     Exit Function
   ' If an error occurs, raise an error
   ErrHandler:
     Err.Raise Err.Number, Err.Source, Err.Description, _
               Err.HelpFile, Err.HelpContext
   End Function

4. Click File Save.

The following steps explain how to update the CreateRectangle, CreateText, and CreateCircle procedures to handle general problems and pass the error to the calling procedure:

1. In the code editor window, scroll to the procedures in the code and add the bold text:

   Public Function CreateRectangle(ptList As Variant) As AcadLWPolyline
     On Error GoTo ErrHandler
     Set CreateRectangle = ThisDrawing.ActiveLayout.Block. _
                           AddLightWeightPolyline(ptList)
     CreateRectangle.Closed = True
     ' Exit the function if it gets this far
     Exit Function
   ' If an error occurs, raise an error
   ErrHandler:
     Err.Raise Err.Number, Err.Source, Err.Description, _
               Err.HelpFile, Err.HelpContext
   End Function
   Public Function CreateText(insPoint As Variant, _
                              attachmentPt As AcAttachmentPoint, _
                              textHeight As Double, _
                              textRotation As Double, _
                              textString As String) As AcadMText
     On Error GoTo ErrHandler
     Set CreateText = ThisDrawing.ActiveLayout.Block. _
                      AddMText(insPoint, 0, textString)
     ' Sets the text height, attachment point, and rotation of the MText object
     CreateText.height = textHeight
     CreateText.AttachmentPoint = attachmentPt
     CreateText.insertionPoint = insPoint
     CreateText.rotation = textRotation
     ' Exit the function if it gets this far
     Exit Function
   ' If an error occurs, raise an error
   ErrHandler:
     Err.Raise Err.Number, Err.Source, Err.Description, _
               Err.HelpFile, Err.HelpContext
   End Function
   Public Function CreateCircle(cenPt As Variant, circRadius) As AcadCircle
     On Error GoTo ErrHandler
     Set CreateCircle = ThisDrawing.ActiveLayout.Block. _
                        AddCircle(cenPt, circRadius)
     ' Exit the function if it gets this far
     Exit Function
   ' If an error occurs, raise an error
   ErrHandler:
     Err.Raise Err.Number, Err.Source, Err.Description, _
               Err.HelpFile, Err.HelpContext
   End Function

2. Click File Save.

Implementing Error Handling and Undo Grouping for the Main Procedures

The following steps explain how to update the CLI_DrawPlate procedure to handle general problems when drawing the objects that form the plate and use undo grouping to make rolling back changes easier:

1. In the Project Explorer, double-click the basDrawPlate component.
2. In the code editor window, scroll to the CLI_DrawPlate and add the text in bold:

   Public Sub CLI_DrawPlate()
     Dim oLyr As AcadLayer
     On Error Resume Next
     ' Start an undo mark here
     ThisDrawing.StartUndoMark
     Dim sysvarNames As Variant, sysvarVals As Variant
     sysvarNames = Array("nomutt", "clayer", "textstyle")

3. Scroll to the If IsNull(basePt) = False Then statement and add the text in bold:

   ' If a base point was specified, then draw the plate
   If IsNull(basePt) = False Then
     On Error GoTo ErrHandler
     ' Create the layer named Plate or set it current
     Set oLyr = myUtilities.CreateLayer("Plate", acBlue)
     ThisDrawing.ActiveLayer = oLyr

4. Scroll to the Dim insPt As Variant statement and add the text in bold:

   myUtilities.CreateCircle cenPt4, 0.1875
   On Error Resume Next
   ' Get the insertion point for the text label
   Dim insPt As Variant
   insPt = Null
   insPt = ThisDrawing.Utility.GetPoint(, _
           removeCmdPrompt & "Specify label insertion point " & _
                             "<or press Enter to cancel placement>: ")
   ' If a point was specified, placed the label
   If IsNull(insPt) = False Then
     On Error GoTo ErrHandler
     ' Define the label to add
     Dim sTextVal As String

5. Scroll to the Loop Until IsNull(basePt) = True And sKeyword = "" statement and add the text in bold:

         myUtilities.CreateText insPt, acAttachmentPointMiddleCenter, _
                                0.5, 0#, sTextVal
       End If
     End If
     On Error Resume Next
   Loop Until IsNull(basePt) = True And sKeyword = ""
   ' Restore the saved system variable values
   myUtilities.SetSysvars sysvarNames, sysvarVals

6. Scroll to the End Sub statement and add the text in bold:

     ' Save previous values to global variables
     g_drawplate_width = width
     g_drawplate_height = height
     ' End an undo mark here
     ThisDrawing.EndUndoMark
     Exit Sub
   ErrHandler:
     ' End an undo mark here
     ThisDrawing.EndUndoMark
     ' Rollback changes
     ThisDrawing.SendCommand "._u "
   End Sub

7. Click File Save.

The following steps explain how to update the cmdCreate_Click procedure to handle general problems when drawing the objects that form the plate and use undo grouping to make rolling back changes easier:

1. In the Project Explorer, right-click the frmDrawPlate component and choose View Code.
2. In the code editor window, scroll to the cmdCreate_Click procedure, or select cmdCreate from the Object drop-down list and then choose Click from the Procedure drop-down list to the right of the Object drop-down list at the top of the code editor window.
3. Add the text in bold:

   Private Sub cmdCreate_Click()
     Dim oLyr As AcadLayer
     ' Hide the dialog so you can interact with the drawing area
     Me.Hide
     On Error Resume Next
     ' Start an undo mark here
     ThisDrawing.StartUndoMark
     Dim sysvarNames As Variant, sysvarVals As Variant
     sysvarNames = Array("nomutt", "clayer", "textstyle")

4. Scroll to the If IsNull(basePt) = False Then statement and add the text in bold:

   ' If a base point was specified, then draw the plate
    If IsNull(basePt) = False Then
     On Error GoTo ErrHandler
     ' Create the layer named Plate or set it current
     Set oLyr = myUtilities.CreateLayer("Plate", acBlue)
     ThisDrawing.ActiveLayer = oLyr

5. Scroll to the If Me.chkAddLabel.Value = True Then statement and add the text in bold:

   myUtilities.CreateCircle cenPt4, 0.1875
   If Me.chkAddLabel.Value = True Then
     On Error Resume Next
     ' Get the insertion point for the text label
     Dim insPt As Variant
     insPt = Null
     insPt = ThisDrawing.Utility.GetPoint(, _
             removeCmdPrompt & "Specify label insertion point " & _
                               "<or press Enter to cancel placement>: ")
     ' If a point was specified, placed the label
     If IsNull(insPt) = False Then
       On Error GoTo ErrHandler
       ' Define the label to add
       Dim sTextVal As String

6. Scroll of the End Sub statement and add the text in bold:

     ' Save previous values to global variables
     g_drawplate_width = width
     Me.txtWidth.Text = Format(g_drawplate_width, "0.0000")
     g_drawplate_height = height
     Me.txtHeight.Text = Format(g_drawplate_height, "0.0000")
     g_drawplate_label = Me.chkAddLabel.Value
     ' End an undo mark here
     ThisDrawing.EndUndoMark
     ' Show the dialog box once done
     Me.show
     Exit Sub
   ErrHandler:
     ' End an undo mark here
     ThisDrawing.EndUndoMark
     ' Rollback changes
     ThisDrawing.SendCommand "._u  "
     ' Show the dialog box once done
     Me.show
   End Sub

7. Click File Save.

Configuring the AutoCAD Support and Trusted Paths

If you can't or don't plan to use a bundle to deploy your custom programs, you must let AutoCAD know where your DVB files are stored and whether they can be trusted. Without the trusted file designation, AutoCAD will display the File Loading - Security Concern message box each time a custom program is loaded in AutoCAD 2013 SP1 or later. And consider this: How can AutoCAD run a program it can't find?

The following steps explain how to add the folder named MyCustomFiles to the support file search paths and trusted locations used by AutoCAD:

1. Click the Application menu button Options (or at the Command prompt, type options and press Enter).
2. When the Options dialog box opens, click the Files tab.
3. Select the Support File Search Path node. Click Add and then click Browse.
4. In the Browse For Folder dialog box, browse to the MyCustomFiles folder that you created for this book in the Documents (or My Documents) folder, or browse to the folder that contains your DVB files.
5. Select the folder that contains your DVB files and click OK.
6. With the new path still highlighted, press F2. Press Ctrl+C, or right-click and choose Copy.
7. Select the Trusted Locations node. Click Add.
8. With focus in the in-place text editor, press Ctrl+V, or right-click and choose Paste. Then press Enter to accept the pasted path.
9. If the Trusted File Search Path - Security Concern message box appears, click Continue.
10. Click OK to save the changes to the Options dialog box.

Creating DrawPlate_VBA.bundle

Plug-in bundles are a relatively new concept in AutoCAD, but they make deploying your custom programs much easier. After all, a bundle is simply a folder structure that you can copy between machines no matter which operating system you are using. Bundles are supported in AutoCAD 2013–based products and later.

The following steps explain how to create a bundle named DrawPlate_VBA.bundle:

1. Launch Windows Explorer or File Explorer based on your version of the operating system. Right-click the Windows Start button in Windows XP or Windows 7, or right-click in the lower-left corner of the screen on Windows 8. Click Windows Explorer or File Explorer.
2. Browse to the MyCustomFiles folder under the Documents (or My Documents) folder. Right-click in an empty area and choose New Folder.
3. Type DrawPlate_VBA.bundle and press Enter.
4. Double-click the DrawPlate_VBA.bundle folder.
5. Create a new folder under the DrawPlate_VBA.bundle folder and name the new folder Contents.
6. From the sample files that are available with this book and those that you created, copy the following files into the appropriate folder (see Table 13.2).

The drawplateloader.lsp file loads the drawplate.dvb file and then defines two custom functions named -drawplate_vba and drawplate_vba. The -drawplate_vba function also supports contextual help; when the function is active, you can press F1 to display the drawplate_vba.htm file.

Deploying and Testing DrawPlate_VBA.bundle

Plug-in bundles must be placed within a specific folder before they can be used. You learned which folders a bundle can be placed in earlier in the section “Loading a Project with a Plug-in Bundle.”

The following steps explain how to deploy a bundle named DrawPlate_VBA.bundle:

1. In Windows Explorer or File Explorer, browse to the DrawPlate_VBA.bundle folder you created in the previous exercise.
2. Select the DrawPlate_VBA.bundle folder and right-click. Choose Copy.
3. In the Location/Address bar of Windows Explorer or File Explorer, type one of the following and press Enter:
   • In Windows XP, type %ALLUSERSPROFILE%Application DataAutodeskApplicationPlugIns.
   • In Windows 7 or Windows 8, type %ALLUSERSPROFILE%AutodeskApplicationPlugIns.
4. Right-click in the file list and choose Paste.

The following steps explain how to test DrawPlate.bundle:

1. In AutoCAD, create a new drawing.
2. At the Command prompt, type -drawplate_vba and press Enter.

   You should see the familiar Specify base point for plate or [Width/Height]: prompt. Before you created the bundle, you had to load the drawplate.dvb file and then start the macro with the vbarun command to access the functionality. As a reminder, the -drawplate_vba function is defined as part of the drawplateloader.lsp file that is used to also load the DrawPlate.dvb file.

3. When the -drawplate_vba function starts, press Esc to end the function.
4. At the Command prompt, type drawplate_vba and press Enter.

   You should see the Draw Plate UserForm that you defined in Chapter 11, “Creating and Displaying User Forms.”

5. Click Cancel to exit the dialog box.