Error Object

class Error extends Object

Call

Creates an Error object.

ErrorObj := Error(Message , What, Extra)
ErrorObj := Error.Call(Message , What, Extra)

Error may be replaced with one of the subclasses listed under Error Types, although some subclasses may take different parameters.

The parameters directly correspond to the Message, What, and Extra properties, but may differ for Error subclasses which override the __New method.

Message and Extra are converted to strings. These are displayed by an error dialog if the exception is thrown and not caught.

What indicates the source of the error. It can be an arbitrary string, but should be a negative integer or the name of a running function. Specifying -1 indicates the current function, -2 indicates the function which called it, and so on. If the script is compiled or the value does not identify a valid stack frame, the value is merely converted to a string and assigned to NewError.What. Otherwise, the identified stack frame is used as follows to determine the other properties:

• NewError.What contains the name of the function.
• NewError.Line and NewError.File indicate the line which called the function.
• NewError.Stack contains a partial stack trace, with the indicated stack frame at the top.

Use of the What parameter can allow a complex function to use helper functions to perform its work or parameter validation, while omitting those internal details from any reported error information. For example:

MyFunction(a, b) {
    CheckArg "a", a
    CheckArg "b", b
    ;...
    CheckArg(name, value) {
        if value < 0
            throw ValueError(name " is negative", "myfunction", value)
    }
}

try
    MyFunction(1, -1)  ; err.Line indicates this line.
catch ValueError as err
    MsgBox Format("{1}: {2}.`n`nFile:`t{3}`nLine:`t{4}`nWhat:`t{5}`nStack:`n{6}"
        , type(err), err.Message, err.File, err.Line, err.What, err.Stack)

try
    SomeFunction()
catch as e
    MsgBox(type(e) " in " e.What ", which was called at line " e.Line)

SomeFunction() {
    throw Error("Fail", -1)
}

Extra

Gets or sets a string relating to the error.

CurrentExtra := ErrorObj.Extra

ErrorObj.Extra := NewExtra

The standard error dialog displays a line with "Specifically:" followed by this string.

File

Gets or sets the full path of the script file containing the line at which the error occurred, or at which the Error object was constructed.

CurrentFile := ErrorObj.File

ErrorObj.File := NewFile

Line

Gets or sets the line number at which the error occurred, or at which the Error object was constructed.

CurrentLine := ErrorObj.Line

ErrorObj.Line := NewLine

Message

Gets or sets the error message.

CurrentMessage := ErrorObj.Message

ErrorObj.Message := NewMessage

Stack

Gets or sets a string representing the call stack at the time the Error object was constructed.

CurrentStack := ErrorObj.Stack

ErrorObj.Stack := NewStack

Each line may be formatted as follows:

File (Line) : [What] SourceCode`r`n

Represents a call to the function What. File and Line indicate the current script line at this stack depth. SourceCode is an approximation of the source code at that line, as it would be shown in ListLines.

> What`r`n

Represents the launching of a thread, typically the direct cause of the function call above it.

... N more

Indicates that the stack trace was truncated, and there are N more stack entries not shown. Currently the Stack property cannot exceed 2047 characters.

What

Gets or sets the source that threw the exception.

CurrentWhat := ErrorObj.What

ErrorObj.What := NewWhat

This is usually the name of a function, but is blank for exceptions thrown due to an error in an expression (such as using a math operator on a non-numeric value).