On Error Statement

---

Syntax 1

On Error GoTo label|0

label

Use: Either label or 0 is required

A valid label within the subroutine.

Syntax 2

On Error Resume Next

Description

Enables or disables error handling within a procedure. If you don't use an On Error statement in your procedure, or if you have explicitly switched off error handling, the Visual Basic runtime engine handles the error automatically. First, it displays a dialog containing the standard text of the error message, something many users are likely to find incomprehensible. Second, it terminates the application, so any error that occurs in the procedure produces a fatal runtime error.

Rules at a Glance

Syntax 1

• The argument disables error handling within the procedure until the next On Error statement is executed.

• The label argument specifies the name of the label defining an error-handling routine within the current procedure that will be branched to should an error occur.

• A subroutine label must be suffixed with a colon; furthermore, you can't use a VB, reserved word for a subroutine label name. For example:

  someroutine:

  
  

• label must be in the same procedure as the On Error statement.

Syntax 2

• When a runtime error occurs, program execution continues with the program line following the line that generated the error.

Programming Tips and Gotchas

• If you have no error handling in your procedure or if error handling is disabled, the VB runtime engine traces back through the call stack until a procedure is reached where error handling is enabled. In that case, the error is handled by that procedure. However, if no error handler can be found in the call stack, a runtime error occurs, and program execution is halted.

• On Error Resume Next is useful in situations where you are certain that errors will occur or where the errors that could occur are minor. The following example shows how you can quickly cycle through the controls on a form and set the Text property to an empty string without checking what type of control you're dealing with. Of course, you are aware that many of the controls don't have a Text property, so the attempt to access their Text property generates an error. By using the On Error Resume Next statement, you force your program to ignore this error and carry on with the next control.

  On Error Resume Next
  For Each Control In Me.Controls
      Control.Text = ""
  Next

  
  

• Use of the On Error Resume Next statement should be kept to a minimum, since errors are basically ignored, and their occurrence is silent to the user. This means that, should an unexpected error (that is, an error that you were not intending to handle when you chose to ignore errors) occur, or should your application behave unexpectedly, the job of finding and correcting the cause of the error becomes almost impossible.

• The following is a template for error handling within your procedures:

  Sub/Function/Property Name ()
      On Error Goto Name_Err
      ... 'procedure code

  
  

  Name_Exit:
    ... 'tidying up code - such as Set Object = Nothing
      Exit Sub/Function/Property

  
  

  Name_Err:
    ... 'error handling code e.g. a MsgBox to inform the user
      Resume Name_Exit

  
  

  End Sub/Function/Property

  
  

  If cleanup code isn't required within the procedure, you can simplify the template by removing the Name_Exit label and removing the Resume Name_Exit statement.

• If you are writing an error handling routine for use within a class module or a DLL, you should use the following template, which raises an error back to the client, thereby notifying the client of the error and allowing the client to handle it:

  Sub/Function/Property Name ()
      On Error Goto Name_Err
    ... 'procedure code
  								  ... 'tidying up code - such as Set Object = Nothing
      Exit Sub/Function/Property

  
  

  Name_Err:
    ... 'error handling and tidying up code 
      Err.Raise etc...

  
  

  End Sub/Function/Property

  
  

• Errors that occur within an error handler always generate a runtime error.

• The quality of error trapping, error handling, and error reporting within a program often determines the success or failure of the application. Attention to detail in this area can be the difference between a stable, well-behaved, and robust application and one that seems to generate nothing but hassle. Using logs like the NT application log within your error-handling routines can help you track down persistent problems quickly and efficiently. See Chapter 6, which details creating robust VB and VBA error handling routines.

See Also

Resume Statement, Chapter 6