Syntax

On Error {Goto label | Resume Next | Goto 0}

Description

Defines the action taken when a trappable runtime error occurs.

Comments

The form On Error Goto label causes execution to transfer to the specified label when a runtime error occurs.

The form On Error Resume Next causes execution to continue on the line following the line that caused the error.

The form On Error Goto 0 causes any existing error trap to be removed.

If an error trap is in effect when the script ends, then an error will be generated.

An error trap is only active within the subroutine or function in which it appears.

Once an error trap has gained control, appropriate action should be taken, and then control should be resumed using the Resume statement. The Resume statement resets the error handler and continues execution. If a procedure ends while an error is pending, then an error will be generated. (The Exit Sub or Exit Function statement also resets the error handler, allowing a procedure to end without displaying an error message.)

Errors within an Error Handler

If an error occurs within the error handler, then the error handler of the caller (or any procedure in the call stack) will be invoked. If there is no such error handler, then the error is fatal, causing the script to stop executing. The following statements reset the error state (that is, these statements turn off the fact that an error occurred):

  Resume
  Err=-1

The Resume statement forces execution to continue either on the same line or on the line following the line that generated the error. The Err=-1 statement allows explicit resetting of the error state so that the script can continue normal execution without resuming at the statement that caused the error condition.

The On Error statement will not reset the error. Thus, if an On Error statement occurs within an error handler, it has the effect of changing the location of a new error handler for any new errors that may occur once the error has been reset.

Example

This example will demonstrate three types of error handling. The first case simply by-passes an expected error and continues with program operation. The second case creates an error branch that jumps to a common error handling routine that processes incoming errors, clears the error (with the Resume statement) and resumes program execution. The third case clears all internal error handling so that execution will stop when the next error is encountered.

Sub Main()
  Dim x%
  a = 10000
  b = 10000

  On Error Goto Pass   'Branch to this label on error.
  Do
    x% = a * b
  Loop

Pass:
  Err = -1             'Clear error status.
  MsgBox "Cleared error status and continued."

  On Error Goto Overflow  'Branch to new error routine on any
  x% = 1000            'subsequent errors.
  x% = a * b
  x% = a / 0

  On Error Resume Next  'Pass by any following errors until
  x% = 1000            'another On Error statement is
  x% = a * b           'encountered.

  On Error Goto 0      'Clear error branching.
  x% = a * b         'Program will stop here.
  Exit Sub        'Exit before common error routine.

Overflow:              'Beginning of common error routine.
  If Err = 6 then
    MsgBox "Overflow Branch."
  Else
    MsgBox Error(Err)
  End If  

  Resume Next
End Sub

See Also

Error Handling (topic); Error (statement); Resume (statement).

O