Raise, Throw, Clear Methods

Purpose

Methods and property to cause a runtime error to be thrown.

Syntax

Err.Raise Number[, Source[, Description[, HelpFile[, HelpContext]]]]

Err.Throw

Err.Clear

Description

The Raise method allows you to generate an user-defined error in your code.

number - A Long integer that identifies the nature of the error. GFA-BASIC 32 errors are in the range 0-141.

source - A string expression naming the object or application that originally generated the error.

description - A string expression describing the error. If unspecified, the value in number is examined. If it can be mapped to a GFA-BASIC 32 run-time error code, a string provided by GFA-BASIC 32 is used as description. If there is no GFA-BASIC 32 error corresponding to number, a generic error message is used.

helpfile - The fully qualified path to the Help file in which help on this error can be found.

helpcontext - The context ID identifying a topic within helpfile that provides help for the error.

Note that only the first parameter, Number, is required. If you use Raise, however, without specifying some arguments, and the property settings of the Err object contain values that have not been cleared, those values become the values for your error.

When setting the Number property to your own error code, you may add your error code number to the constant basObjectError ($800A0000) to simulate a COM error. For example, to generate the error number 10, assign basObjectError + 10 to the Number property.

Use Clear to explicitly clear the Err object after an error has been handled, for example, when you use deferred error handling with On Error Resume. The Clear method is called automatically whenever any of the following statements is executed: Try, Resume, Exit Sub, Exit Function, On Error statement

The Throw method throws the error back to the next Try/Catch block. This method allows you to throw a locally created exception in a subroutine. If you try to throw an error that you have just caught, it will normally go out of scope and be deleted. With Throw, the error is passed correctly to the calling subroutine.

Note - Throw doesn't work as documented. It does generate an error, but the content of Err is cleared (which isn't strange in the context of the implicitly invoked Clear method on subroutine exit!).

Example

OpenW # 1

Try

RaiseMe

Catch

MsgBox Err & " - " & Err.Description, MB_OK, "Error in " & Err.Source

EndCatch

CloseW 1

Procedure RaiseMe

Dim a$ = "1"

Prompt "Raise an Error", "Which error should be shown?", a$

Try

Err.Raise Val(a$), "RaiseMe"

Catch

MsgBox Err & " - " & Err.Description & #10 _

"Throw again.", , "Error in " & Err.Source

Err.Throw

EndCatch

EndProc

Remarks

The Source property returns or sets a string specifying the name of the object or application that originally generated the error. For GFA-BASIC 32 runtime errors it is "GFA-BASIC 32", for OLE Automation errors it is the COM program name. When generating an error from code, Source is your application’s program name.

See Err$ for a list of errors and exception codes.

See HResult for a list of COM error codes.