On Error Statement

On Error Statement

---

Syntax 1

 On Error GoTo   label   0-1 

label (Either label , , or -1 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 or a Try...Catch block in your procedure, or if you have explicitly switched off error handling, the Visual Basic runtime engine will automatically handle the error. First, it will display a dialog box containing the standard text of the error message, something that many users are likely to find incomprehensible. Second, it will terminate the application. So any error that occurs in the procedure will produce 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 -1 argument disables an enabled exception in the current procedure. (It resets the exception to Nothing .)

• The label argument specifies the label that defines an error-handling routine within the current procedure. Should an error occur, the procedure will be branched to this error-handling routine.

• A label must be suffixed with a colon . In addition, you cannot 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 will trace back through the call stack until a procedure is reached where error handling is enabled. In that case, the error will be 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 either 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 that the attempt to access their Text property will generate 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 using the On Error statement:

   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 are passed up the call chain. To illustrate this, consider the following code:

   Public Function Test(  ) As Integer     On Error Goto Err_Test     Dim iTest(  ) As Integer = {1, 2}     Test = iTest(3) ' error     Exit Function Err_Test:     MsgBox(iTest(4))  ' error End Function Sub Test2(  )     On Error Goto Err_Test2     Test(  )     Exit Sub Err_Test2:     MsgBox("Error handled") End Sub 

  When Test2 is run, the message "Error handled" is displayed. This indicates that the error that occurs in the error handler of Test is passed to Test2.

• For more on both unstructured and structured error handling, see Chapter 9.

VB.NET/VB 6 Differences

In VB 6, the label in On Error GoTo label can be either a label or a line number. In VB.NET, the use of line numbers is not supported.

See Also

Err Object