The catch Statement

Syntax

try {
    ...
}
catch [ <return-codes> ] {
    [ statements ]
}

The catch statement runs a series of substatements in a block, but only if the previous try failed.

<return codes>: Zero or more return codes. Multiple return codes are separated by spaces.
[ statements ]: The unlang commands which will be executed. A catch block can be empty.

Multiple catch statements can be placed one after the other, to catch different errors. Only one of the statements will be executed. Once a catch statement is finished, the interpreter will skip all trailing catch statements, and continue execution with the next statement.

As a special case, the final 'catch' statement can list no return codes. i.e catch { … }. In that case, it will match all return codes which were not listed in previous 'catch' statements.

Example

try {
    sql           # returns "fail"
}
catch disallow {  # skipped when "fail"
    ...
}

catch fail {
    # ... run only if sql failed

    ok            # over-ride the "fail" code
}

catch invalid {   # skipped after "catch fail" is run.
	...
}

The catch block executes on all rcodes such as ok, noop, etc., and not just on failures.

try / catch versus redundant

There is some overlap in functionality between try / catch and redundant. The main difference is that a catch statement can catch specific failure codes.

The redundant statement should be used to run one of many similar modules. For example, the redundant statement could be used to choose one of four different sql modules in a fail-over fashion.

In contrast, the try / catch statements should be used for more complex policies, when the intention is to run one policy, and then do something completely different if a failure occurs.

The try / catch statements can also run different statements for each failure code, which is not possible with redundant.