OnError statement - MapBasic - 2023

Purpose

Enables an error-handling routine.

Syntax

OnError Goto{ label | 0 }

label is a string representing a label within the same procedure or function.

Restrictions

You cannot issue an OnError statement through the MapBasic window.

Description

The OnError statement either enables an error-handling routine, or disables a previously enabled error-handler. (An error-handler is a group of statements executed in the event of an error).

BASIC programmers should note that in the MapBasic syntax, OnError is a single word.

An OnError Goto label statement enables an error-handling routine. Following such an OnError statement, if the application generates an error, MapBasic jumps to the label line specified. The statements following the label presumably correct the error condition, warn the user about the error condition, or both. Within the error-handling routine, use a Resume statement to resume program execution.

Once you have inserted error-handling statements in your program, you may need to place a flow-control statement (for example, Exit Sub statement or End Program statement) immediately before the error handler's label. This prevents the program from unintentionally "falling through" to the error handling statements, but it does not prevent MapBasic from calling the error handler in the event of an error. See the example below.

An OnError Goto 0 statement disables the current error-handling routine. If an error occurs while there is no error-handling routine, MapBasic displays an error dialog box, then halts the application.

Each error handler is local to a particular function or procedure. Thus, a sub procedure can define an error handler by issuing a statement such as:

OnError Goto recover 

(assuming that the same procedure contains a label called "recover" ). If, after executing the above OnError statement, the procedure issues a Call statement to call another sub procedure, the "recover" error handler is suspended until the program returns from the Call statement. This is because each label (for example, "recover") is local to a specific procedure or function. With this arrangement, each function and each sub procedure can have its own error handling.

Example

OnError GoTo no_states
Open Table "states"

OnError GoTo no_cities
Open Table "cities"

Map From cities, states
after_mapfrom:
	OnError GoTo 0 
	' 
	' ... 
	' 
End Program 

no_states: 
	Note "Could not open table States... no Map used." 
	Resume after_mapfrom

no_cities: 
	Note "City data not available..."
	Map From states
	Resume after_mapfrom

See Also:

Err() function, Error statement, Error$() function, Resume statement