Identifier: throw_level

Type

numeric

Description

The error severity level at which automatic exceptions are thrown. Any system error or warning (occurring in the current command frame) with a severity less than or equal to this level will throw a system exception automatically. The value is inherited by any new command frames e.g. (functions and procedures) invoked from the current command frame.

Any exceptions thrown can be caught by a try/catch language sequence in the current (or parent) command frame. If an exception is not caught then details of the exception will be printed in the error log similar to a normal (non-exception) error.

When a catchable exception (one which has a severity less than or equal to the value of throw_level) is thrown and not caught by the current command frame, the current command frame will be terminated and the exception passed up to the parent command frame where it will be caught or printed depending on the value of throw_level in that parent command frame.

System errors have a severity level of 1 through 6. System warnings have a severity level of 10. Therefore setting a throw_level of 6 will throw error exceptions, but not warning exceptions. A throw_level of 10 will throw both.

User macros can throw exceptions (known as user exceptions) with an appropriate severity level to enable them to be caught or not as desired. This can be done with the throw command.

Examples

Code to throw an exception which is not caught:

throw_level = 6
rubbish;# A bad command

Because the offending command is not within a try/catch sequence the exception is printed immediately in the error log, with something like:

System Error Exception, Code: 2011, Severity: 2:
    Invalid command: rubbish
    Stack Trace:
        Command Macro, C:/mymacro.cmd(2)
        Master Polling

Code to throw an exception which is caught:

throw_level = 6
try {
   rubbish;# A bad command
# We will never get here
}
catch exc {
	tell <'We have caught the exception, code:',exc.code>
}

The offending command is executed within a try block, the system error is caught by a catch block and processed appropriately. Part of the exception gets printed, thus:

We have caught the exception, code: 2011

Code to catch warning as well as error exceptions:

throw_level = 10
try {
   numeric x = 100/0;# A mathematical anomaly
# We will never get here
}
catch exc {
# Just list the error details
    list exc
}

The offending maths computation gets executed within a try block, the system warning is caught by a catch block and listed, thus:

exception ~local.exc
    numeric exc.code: 4003
    numeric exc.severity: 10
    string exc.style: warning
    numeric exc.system: 1
    string exc.text: Warning: Division by zero
    string exc.trace[2]: Command Macro, c:/mymacro.cmd(20), Master Polling

If throw_level is set to less than 10, the warning will never get caught.

See Also