Using the raise exception Instruction

Use the Jade raise exception instruction to raise an exception using a previously created exception object. This enables you to record extra information with the exception before raising it.

The optional internal or precondition keyword specifies the type of exception, which is precondition by default. You can use the optional internal or precondition keyword of the raise exception instruction to specify whether an exception is an internal error or a precondition violation on the raise instruction. The default type is precondition. A precondition exception is used to report precondition contract violations where the caller has failed to satisfy precondition requirements of the invoked method.

When a method raises a precondition violation, it signifies that its caller has failed to meet certain requirements such as passing valid parameters or ensuring a required state in objects used by the invoked method for the called method to do its job.

When a precondition exception is raised at run time, the exception object contains two method descriptor references: currentMethodDesc, which describes the calling method, and the reportingMethodDesc, which describes the reporting method (that is, the method that raised the exception).

When an internal exception is raised, currentMethodDesc describes the method raising the exception and reportingMethodDesc contains a null reference. The default exception handler and dialog display information from the current method descriptor and the reporting method descriptor, if present.

The following example shows the method that creates an object of the UserException class, defines the properties for this object, and then raises the exception. (See also "Creating an Exception Handler" and "Examples of Arming an Exception Handler", earlier in this chapter.)

method4();
vars
    userException : UserException;
begin
    create userException;
    userException.errorCode   := 64000;
    userException.continuable := true;
    userException.resumable   := true;
    raise userException;
    status.caption := "Resuming execution after raising exception";
end;

The following example shows a method used to raise an exception of type MyException.

raiseMyException(code: Integer; categ: Integer);
vars
    exObj : MyException;
begin
    create exObj;
    exObj.errorCode := code;
    exObj.category  := categ;
    raise exObj;
end;

The following example shows a method used to raise an exception for a variable exception class. The primitive type or class of the exception is passed as a parameter to the method.

myRaiseException(exClass: ExceptionClass; error: Integer; text: String);
vars
    exObj : Exception;
begin
    create exObj as exClass;
    exObj.errorCode         := error;
    exObj.extendedErrorText := text;
    raise exObj;
end;