Difference between revisions of "Documentation/BASIC Guide/Error Handling"

Revision as of 13:20, 2 April 2008

>]]

Correct handling of error situations is one of the most time-consuming tasks of programming. Apache OpenOffice Basic provides a range of tools for simplifying error handling.

The On Error Instruction

The On Error instruction is the key to any error handling:

Sub Test
  On Error Goto ErrorHandler
  ' ... undertake task during which an error may occur
  Exit Sub
  ErrorHandler: 
    ' ... individual code for error handling
End Sub

The On Error Goto ErrorHandler line defines how Apache OpenOffice Basic proceeds in the event of an error. The Goto ErrorHandler ensures that Apache OpenOffice Basic exits the current program line and then executes the ErrorHandler: code.

The Resume Command

The Resume Next 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:

ErrorHandler:
  ' ... individual code for error handling
  Resume Next

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

ErrorHandler:
  ' ... individual code for error handling
  Resume Proceed
 
Proceed:
  ' ... the program continues here after the error

To continue a program without an error message when an error occurs, use the following format:

Sub Test
  On Error Resume Next
  ' ... perform task during which an error may occur
End Sub

Use the On Error Resume Next 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 Err variable contains the number of errors that has occurred.
• The Error$ variable contains a description of the error.
• The Erl variable contains the line number where the error occurred.

The call

 MsgBox "Error " & Err & ": " & Error$ & " (line : " & Erl & ")"

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

Template:Documentation/Note

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

Template:Documentation/Note

Tips for Structured Error Handling

Both the definition command, On Error, and the return command, Resume, are variants of the Goto 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 On Error Resume Next 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 is an example of an error handling procedure:

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

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 On Error Goto 0 call and the procedure implementation is ended by the Exit Sub command (not to be confused with End Sub).

The example first checks if the error number corresponds to the expected number (as stored in the imaginary ExpectedErrorNo 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 On Error Goto 0 call at the end of the code resets the status information of the error (the error code in the Err system variables) so that an error occurring at a later date can be clearly recognized.