The catch Statement

Syntax

try {
    ...
}
catch [ rcodes ] {
    [ statements ]
}

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

[ rcodes ]: Zero or more module return codes. The return codes can be disallow, fail, invalid, or reject.
[ statements ]: The unlang commands which will be executed. A catch block can be empty.

If no rcode is given the catch statement matches all of the codes listed above. Otherwise, the catch statement matches one of the listed rcodes.

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

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.