You can create your own user-defined exception types from standard class user objects that inherit from Exception or RuntimeError or that inherit from an existing user object deriving from Exception or RuntimeError.
Normally, user-defined exception types should inherit from the Exception type or a descendant, since the RuntimeError type is used to indicate system errors. These user-defined objects are no different from any other nonvisual user object in the system. They can contain events, functions, and instance variables.
User-defined exception types are useful in cases where a specific condition, such as the failure of a business rule, might cause application logic to fail. If you create a user-defined exception type to describe such a condition and then catch and handle the exception appropriately, you can prevent a runtime error.
Exceptions can be thrown by the runtime engine to indicate an error condition. If you want to signal a potential exception condition manually, you must use the THROW statement.
Typically, the THROW statement is used in conjunction with some user-defined exception type. Here is a simple example of the use of the THROW statement:
Exception le_ex
le_ex = create Exception
Throw le_ex
MessageBox ("Hmm", "We would never get here if" &
+ "the exception variable was not instantiated")
In this example, the code throws the instance of the exception le_ex. The variable following the THROW reserved word must point to a valid instance of the exception object that derives from Throwable. If you attempt to throw an uninstantiated Exception variable, a NullObjectError is thrown instead, indicating a null object reference in this routine. That could only complicate the error handling for your application.
If you signal an exception with the THROW statement inside a method script—and do not surround the statement with a try-catch block that can deal with that type of exception—you must also declare the exception as an exception type (or as a descendant of an exception type) thrown by that method. However, you do not need to declare that a method can throw runtime errors, since PocketBuilder does that for you.
The prototype window in the Script view of most PocketBuilder painters allows you to declare what user-defined exceptions, if any, can be thrown by a function or a user-defined event. You can drag and drop exception types from the System Tree or a Library painter view to the Throws box in the prototype window, or you can type in a comma-separated list of the exception types that the method can throw.
Example catching a user-defined exception This code displays a user-defined error when an arccosine argument, entered by the application user, is not in the required range. The try-catch block calls a method, wf_acos, that catches the system error and sets and throws the user-defined error:
TRY
wf_acos()
CATCH (uo_exception u_ex)
MessageBox("Out of Range", u_ex.GetMessage())
END TRY
This code in the wf_acos method catches the system error and sets and throws the user-defined error:
uo_exception lu_error
Double ld_num
ld_num = Double (sle_1.text)
TRY
sle_2.text = string (acos (ld_num))
CATCH (runtimeerror er)
lu_error = Create uo_exception
lu_error.SetMessage("Value must be between -1" &
+ "and 1")
Throw lu_error
END TRY
