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.
[ statements ]: The unlang commands which will be executed. A catch block can be empty.

If no return code is given, then the catch statement will match all of the return codes. Otherwise, the catch statement matches only the return codes which were listed.

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.

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.
	...
}

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.