Sections
Use On Error	Leave Error Handlers	Define Error Constants
Keep Error Handlers Separate	Understand Error Handler Scope	Don't Nest Error Handlers
Error Handling Slides

This chapter explains the family of On Error statements Visual Basic uses to handle errors. It tells how a program installs and removes error handlers, and it explains some of the idiosyncrasies of error handling code. After reading this chapter you will be able to write basic error handlers to protect your programs from the unexpected.

Use On Error

• On Error GoTo 0
• On Error Resume Next
• On Error GoTo line

On Error GoTo 0

On Error Resume Next

Many programs use On Error Resume Next when they present a common dialog to the user. The CommonDialog control's CancelError property indicates whether the control should raise an error if the user cancels the dialog. The following code fragment shows how a program can use CancelError to decide whether to continue an action such as loading a file.

' Generate an error if the user cancels. dlgOpenFile.CancelError = True ' Ignore errors for now. On Error Resume Next ' Present the dialog. dlgOpenFile.ShowOpen ' See if there was an error. If Err.Number = cdlCancel Then ' The user canceled. Do nothing. Exit Sub ElseIf Err.Number <> 0 Then ' Unknown error. Take more action. : End If ' Resume normal error handling. On Error GoTo 0

On Error GoTo Line

The following code shows a simple error handler that catches unexpected errors and describes them to the user.

Private Sub DoSomething() ' Install the error handler. On Error GoTo UnexpectedError ' Do stuff. : ' Do not pass through into the error handler code. Exit Sub UnexpectedError: ' Describe the error to the user. MsgBox "Unexpected error" & _ Str$(Err.Number) & _ " in subroutine DoSomething." & _ vbCrLf & _ Err.Description Exit Sub End Sub

Leave Error Handlers

• Resume
• Resume Next
• Exit Sub/Function/Property
• End Sub/Function/Property
• Err.Raise

Resume

For example, the following code tries to load a file that might be stored on a floppy disk. If it fails, the code reports the error and asks the user if it should try again. If the disk is not in the floppy drive, the user can insert it and click the Retry button. The program then uses the Resume statement to try to open the file again. If the program fails again, it returns to the error handler to give the user another chance to fix the problem. The program continues looping from the Open statement to the error handler and back until the user fixes the problem or clicks the Cancel button. If the user clicks Cancel, the error handler exits the subroutine without opening the file.

Private Sub LoadData(ByVal filename As String) Dim fnum As Integer ' Open the file. fnum = FreeFile On Error GoTo OpenError Open filename For Input As fnum ' Read the data. On Error GoTo ReadError : ' Close the file. On Error GoTo CloseError Close fnum Exit Sub OpenError: ' We could not open the file. Ask the user ' if we should retry. If MsgBox("Error" & _ Str$(Err.Number) & _ " opening file " & filename & "." & _ vbCrLf & Err.Description & vbCrLf & _ "Check that the disk is properly " & _ "inserted and click the Retry button.", _ vbRetryCancel, _ "Error opening file") = vbRetry _ Then ' Try again at the same statement. Resume End If ' Otherwise cancel the file loading. Exit Sub ReadError: MsgBox "Error" & _ Str$(Err.Number) & _ " reading file " & filename & "." & _ vbCrLf & Err.Description ' Close the file. Close fnum Exit Sub CloseError: ' Error closing the file. MsgBox "Error" & _ Str$(Err.Number) & _ " closing file " & filename & "." & _ vbCrLf & Err.Description Exit Sub End Sub

Resume Next

For example, the following code tries to convert a string value into a date using the CDate function. If it fails, the error handler assigns the current date to the start_date variable and uses that as a default value.

Private Sub ValidateStartDate(ByVal date_string As String) Dim start_date As Date ' Install the error handler. On Error GoTo InvalidDate ' Convert the string into a date. start_date = CDate(date_string) ' Do something with the date. : ' Do not pass through into the error handler code. Exit Sub InvalidDate: ' It's an invalid date string. Use today. start_date = Date Resume Next End Sub

Note that this is probably not the best way to handle this situation because it silently handles the error instead of making it obvious. If the user entered the invalid value, the program should politely tell the user there is a problem and ask for a new value. If the string was passed to this routine from another part of the program, the program may contain a bug. It should stop during design mode or raise an error in the final compiled version so someone can fix the problem.

Exit Sub/Function/Property

Private Sub ValidateStartDate(ByVal date_string As String)
Dim start_date As Date

    ' Install the error handler.
    On Error GoTo InvalidDate

    ' Convert the string into a date.
    start_date = CDate(date_string)

    ' Do something with the date.
        :

    ' Do not pass through into the error handler code.
    Exit Sub

InvalidDate:
    ' It's an invalid date string. Tell the user and leave.
    MsgBox "The start date """ & _
        date_string & _
        """ is invalid. Please enter a new one."
    Exit Sub
End Sub

End Sub/Function/Property

InvalidDate:
    ' It's an invalid date string. Tell the user and leave.
    MsgBox "The start date """ & _
        date_string & _
        """ is invalid. Please enter a new one."
End Sub

InvalidDate:
    ' It's an invalid date string. Tell the user and leave.
    MsgBox "The start date """ & _
        date_string & _
        """ is invalid. Please enter a new one."

ReadFileError:
    ' Error reading the data file.
    MsgBox "Error reading the data."
        :
End Sub

Err.Raise

Err.Raise Number, [Source], [Description], [Helpfile], [Helpcontext]

Number

The error number. To create a new error code in a class module, add vbObjectError to your number. For example, vbObjectError + 1001.

Source

The name of the object or application generating the error. For objects, use the format Project.Class. For routines, use the format Project.Routine. For example, MyProgram.LoadData.

Description

A string describing the error. If you set Number to a standard Visual Basic error code like 9 for subscript out of range, you can omit Description to make Visual Basic use a standard description string.

Helpfile

The full name of a help file that gives more information on the error.

Helpcontext

The context ID for this error's topic in the help file.

' Define application error constants.
Private Const myappErrNoInputFile = vbObjectError + 1000
    :
' Define Visual Basic error constants.
Private Const vbErrFileNotFound = 53
    :
Private Sub ReadInputData(ByVal file_name As String)
Dim file_number As Integer

    ' Open the file.
    file_number = FreeFile
    On Error GoTo FileOpenError
    Open file_name For Input As file_number

    ' Process the file.
    On Error GoTo FileReadError
        :
    ' Process the file here.
        :
    ' Close the file.
    Close file_number
    Exit Sub

FileOpenError:
    ' There was an error opening the file.
    If Err.Number = vbErrFileNotFound Then
        ' It's a file not found error. Convert it
        ' to myappErrNoInputFile.
        Err.Raise myappErrNoInputFile, _
            "MyApp.ReadInputData", _
            "Could not open input file """ & _
                file_name & """."
    Else
        ' It's some other error. Reraise it so some
        ' other routine can catch it.
        Err.Raise Err.Number, _
            Err.Source, _
            Err.Description, _
            Err.HelpFile, _
            Err.HelpContext
    End If
    Exit Sub

FileReadError:
    ' There was an error reading the file.
        :
    Exit Sub
End Sub

    On Error GoTo DataInputError
    ReadInputData "c:\mydata.dat"
    Exit Sub

DataInputError:
    ' There was an error loading the data.
    MsgBox "Error" & Str$(Err.Number) & _
        " loading the input data." & vbCrLf & _
        Err.Description

Err.Raise myappErrNoInputFile, _
    "MyApp.ReadInputData", _
    "Error" & Str$(myappErrNoInputFile) & _
    " opening the input file."

    Error -2147220504 loading the input data.
    Error -2147220504 opening the input file.

Unfortunately, this does not guarantee that your error code will not collide with other error constants defined by other developers or libraries you use. One method for preventing confusion is to define a base value similar to vbObjectError for your constants. Then define error codes in terms of that constant. For example, a ray-tracing package might define error codes as in the following code:

Public Const rayErrorBase = 45300 Public Const rayParametersNotSet = rayErrorBase + 1 Public Const rayInvalidSphereFormat = rayErrorBase + 2 Public Const rayLightAtEye = rayErrorBase + 3 :

If you later discover that your error codes collide with those of another developer or library, you can quickly redefine all of the error codes by changing the error base value.

Keep Error Handlers Separate

For example, the following code falls through its error handlers to close the file it has opened.

Private Sub LoadData(ByVal filename As String) Dim fnum As Integer ' The file is not yet open. On Error GoTo FileIsClosed ' Open the file. fnum = FreeFile Open filename For Input As fnum ' The file is now open. On Error GoTo FileIsOpen ' Read the data. : ' Fall into the error handlers to close the file. On Error Resume Next FileIsOpen: ' Close the file. Close fnum FileIsClosed: ' Perform any final tasks. : ' Fall through to the End Sub. End Sub

This code has a number of problems. First, it is confusing. Another developer who tries to add a new error handler would be likely to make a mistake and cause a bug. This code also does not signal its errors. Instead, it quietly continues as if nothing has gone wrong. It hides bugs that might otherwise be easy to fix. Prevent confusion and possible bugs by keeping error handlers separate.

Understand Error Handler Scope

If no error handler is in effect, Visual Basic moves up the call stack to the calling routine to see if an error handler is currently installed there. If so, the system resumes execution at that error handler.

If no error handler is installed in the calling routine either, Visual Basic continues moving up the call stack until it finds a routine with an error handler installed. If it runs off the top of the stack before it finds an active error handler, the program crashes.

Execution of all Visual Basic code begins with either an event handler or the Main subroutine. That means you can guard against almost all errors if you place error handlers in every event handler and the Main subroutine (if the program uses one). Then, no matter where the program encounters an error, control eventually passes up through the call stack to the event handler or Main subroutine that started the code. The error handler installed at that point can handle the error.

Don't Nest Error Handlers

This sort of thing can be very confusing. If Subroutine2 raises an error in the following code, it is not clear whether control passes to the Error1 or Error2 error handler. Control passes to Error1 if Subroutine1 ran correctly, but it passes to Error2 if Subroutine1 also generated an error.

On Error GoTo Error1 Subroutine1 Subroutine2 Exit Sub Error1: On Error GoTo Error2 MsgBox "Error1:" & Str$(Err.Number) & "." & vbCrLf & _ Err.Description Resume Next Error2: MsgBox "Error2:" & Str$(Err.Number) & "." & vbCrLf & _ Err.Description Resume Next

Avoid this confusion by not using On Error statements within error handler code. Keep all On Error statements in the main code sequence.

(This ends approximately the first half of Chapter 12, Error Handling Fundamentals)

Error Handling Slides

This material originally appeared in the book Bug Proofing Visual Basic by Rod Stephens, 1998, John Wiley & Sons. If you like the article, visit the books's Web page to learn more.