View source for Documentation/BASIC Guide/Error Handling

{{Documentation/BASICGuideTOC/v2
|ShowPrevNext=block
|ShowPrevPage=block
|PrevPage=Documentation/BASIC Guide/Procedures and Functions
|NextPage=Documentation/BASIC Guide/Other Instructions
|lang=block
}}
{{DISPLAYTITLE:Error Handling}}
__NOTOC__
Correct handling of error situations is one of the most time-consuming tasks of programming. {{OOo}} Basic provides a range of tools for simplifying error handling.

== The <tt>On Error</tt> Instruction ==

The <tt>On Error</tt> instruction is the key to any error handling:

<source lang="oobas">
Sub Test
  On Error Goto ErrorHandler
  ' ... undertake task during which an error may occur
  Exit Sub
  ErrorHandler: 
    ' ... individual code for error handling
End Sub
</source>

The <tt>On Error Goto ErrorHandler</tt> line defines how {{OOo}} Basic proceeds in the event of an error. The <tt>Goto ErrorHandler</tt> ensures that {{OOo}} Basic exits the current program line and then executes the <tt>ErrorHandler:</tt> code. 

== The <tt>Resume</tt> Command ==

The <tt>Resume Next</tt> command continues the program from the line that follows where the error occurred in the program after the code in the error handler has been executed:

<source lang="oobas">
ErrorHandler:
  ' ... individual code for error handling
  Resume Next
</source>

Use the <tt>Resume Proceed</tt> command to specify a jump point for continuing the program after error handling:

<source lang="oobas">
ErrorHandler:
  ' ... individual code for error handling
  Resume Proceed
 
Proceed:
  ' ... the program continues here after the error
</source>
The term Proceed is a label. It could be for example, A247. The syntax for label names is the same as for variable names.
 
To continue a program without an error message when an error occurs, use the following format: 

<source lang="oobas">
Sub Test
  On Error Resume Next
  ' ... perform task during which an error may occur
End Sub
</source>

Use the <tt>On Error Resume Next</tt> command with caution as its effect is global.

== Queries Regarding Error Information ==

In error handling, it is useful to have a description of the error and to know where and why the error occurred:

* The <tt>Err</tt> variable contains a number identifying the type of error that has occurred.
* The <tt>Error$</tt> variable contains a description of the error.
* The <tt>Erl</tt> variable contains the line number where the error occurred. 

The call

<source lang="oobas">
 MsgBox "Error " & Err & ": " & Error$ & " (line : " & Erl & ")"
</source>

shows how the error information can be displayed in a message window. 

{{Documentation/VBAnote|Whereas VBA summarizes the error messages in a global object called <tt>Err</tt>, {{OOo}} Basic provides the <tt>Err,</tt> <tt>Error$</tt>, and <tt>Erl</tt> variables.}}

The status information remains valid until the program encounters a <tt>Resume</tt> or <tt>On Error</tt> command, whereupon the information is reset. 

{{Documentation/VBAnote|In VBA, the <tt>Err.Clear</tt> method of the <tt>Err</tt> object resets the error status after an error occurs. In {{OOo}} Basic, this is accomplished with the <tt>On Error</tt> or <tt>Resume</tt> commands. }}

== Tips for Structured Error Handling ==

Both the definition command, <tt>On Error</tt>, and the return command, <tt>Resume</tt>, are variants of the <tt>Goto</tt> construct.

If you want to cleanly structure your code to prevent generating errors when you use this construct, you should not use jump commands without monitoring them.

Care should be taken when you use the <tt>On Error Resume Next</tt> command as this dismisses all open error messages.

The best solution is to use only one approach for error handling within a program - keep error handling separate from the actual program code and do not jump back to the original code after the error occurs.

The following code is an example of an error handling procedure:

<source lang="oobas">
Sub Example
  ' Define error handler at the start of the function 
  On Error Goto ErrorHandler   
    ' ... Here is the actual program code
  On Error Goto 0           ' Deactivate error handling
    ' End of regular program implementation
  Exit Sub

 ' Start point of error handling
 ErrorHandler:                
   ' Check whether error was expected
    If Err = ExpectedErrorNo Then   
      ' ... Process error
    Else
      ' ... Warning of unexpected error
    End If
 On Error Goto 0            ' Deactivate error handling 
End Sub
</source>

This procedure begins with the definition of an error handler, followed by the actual program code. At the end of the program code, the error handling is deactivated by the <tt>On Error Goto 0</tt> call and the procedure implementation is ended by the <tt>Exit Sub</tt> command (not to be confused with <tt>End Sub</tt>). 

The example first checks if the error number corresponds to the expected number (as stored in the imaginary <tt>ExpectedErrorNo</tt> constant) and then handles the error accordingly. If another error occurs, the system outputs a warning. It is important to check the error number so that unanticipated errors can be detected.

The <tt>On Error Goto 0</tt> call at the end of the code resets the status information of the error (the error code in the <tt>Err</tt> system variables) so that an error occurring at a later date can be clearly recognized.

 
{{InterWiki Languages BasicGuide|articletitle=Documentation/BASIC Guide/Error Handling}}
{{PDL1}}