Documentation/BASIC Guide/Error Handling

BASIC Guide

{{{parttitle}}}

[[{{{PrevPart}}}|< Previous Section ]]

[[{{{NextPart}}}|Next Section >]]

• The Language of Apache OpenOffice Basic

• Overview of a Basic Program
• Working With Variables
• Strings
• Numbers
• Boolean Values
• Date and Time
• Arrays
• Scope and Life Span of Variables
• Constants
• Operators
• Branching
• Loops
• Procedures and Functions
• Error Handling
• Other Instructions

• Runtime Library

• Conversion Functions
• Strings
• Date and Time
• Files and Directories
• Message and Input Boxes
• Other Functions

• Introduction to the API

• Universal Network Objects (UNO)
• Properties and Methods
• Modules, Services and Interfaces
• Tools for Working with UNO
• Overview of Central Interfaces

• Working with Documents

• The StarDesktop
• Styles and Templates

• Text Documents

• The Structure of Text Documents
• Editing Text Documents
• More than Just Text

• Spreadsheet Documents

• The Structure of Spreadsheets
  • Rows and Columns
  • Cells and Ranges
  • Formatting Spreadsheet Documents
• Editing Spreadsheet Documents

• Drawings and Presentations

• The Structure of Drawings
• Editing Drawing Objects
• Presentations

• Charts (Diagrams)

• Using Charts in Spreadsheets
• The Structure of Charts
• Chart Types

• Databases

• SQL: a Query Language
• Types of Database Access
• Data Sources
• Database Access

• Dialogs

• Working With Dialogs
• Properties
• Events
• Dialog Control Elements

• Forms

• Working With Forms
• Control Element Forms
• Database Forms

< Previous Page

Next Page >

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

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:

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 a number identifying the type of error 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.

VBA : Whereas VBA summarizes the error messages in a global object called Err, Apache OpenOffice Basic provides the Err, Error$, and Erl variables.

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

VBA : In VBA, the Err.Clear method of the Err object resets the error status after an error occurs. In Apache OpenOffice Basic, this is accomplished with the On Error or Resume commands.

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 code 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.

Content on this page is licensed under the Public Documentation License (PDL).