catch

The page content contained within the [catch]...[/catch] block will be executed if a runtime error is detected in the correspondingly-labelled [try]...[/try] block.

Summary

[catch label] Error handlers [/catch]

Parameter	Description	Default
label	The label shared by the paired [try] and [catch] blocks.	default
error_scratch	Set the named scratchpad variable true	None
error_set	Associate the trapped error with a named form variable.	None
hide	Suppress any output from this tag.	No
interpolate	Parse Interchange tags, included in the body text, before this container tag executes.	Yes

Examples

Tag usage example

The [try] tag will run a block of Interchange tags and trap any errors found.

[try my_label]
Body text to parse (and return if no error)
[/try]

The [catch] tag can then handle any errors that were trapped by the [try].

[catch label=my_label other_named_attributes]
[/Pattern matching error message 1/]
Return this if error 1 occurs
[/Pattern matching error message 1/]

[/Pattern matching error message 2/]
Return this if error 2 occurs, etc.
[/Pattern matching error message 2/]

Default body text to process if try block caused an error

[else]
Optional body text to process if there was no error
[/else]
[/catch]

Description

The page content contained within the [catch label]...[/catch] block executes if the correspondingly labelled [try] block fails. The catch block executes in place on the page if triggered (i.e. it does not return its result in place of the try block).

You can also return a result based on the error message caught in the try block with paired sub-tags, like this:

[/error message/]
Special catch block for the error
[/error message/]

The error message to use in the special block will generally be part of the entry the error generates in the error.log file. For example, a division by zero error would generate something like the following in the error log file:

127.0.0.1 4cU3Pgsh:127.0.0.1 - [24/May/2001:14:45:07 -0400] tag /cgi-bin/tag72/tag Safe: Illegal division by zero at (eval 526) line 2.

Note that this feature excises all tag/end-tag pairs if interpolation is turned off, so the catch tag interpolates its body text by default.

Ignoring whitespace, the following would return the result if the division was successful, 0 on a division by zero or an error message:

[set divisor]0[/set]
[try label=div]
[perl] 1 / $Scratch->{divisor} [/perl]
[/try]
[catch div]
[/Illegal division by zero/]
Division by zero
[/Illegal division by zero/]

[/eval "string" trapped by operation mask/]
Perl Safe error
[/eval "string" trapped by operation mask/]

Other error: $$ERROR$$

[else] You're in the clear [/else]
[/catch]

The "$$ERROR$$" token will be replaced with the actual error message that was caught.

If no error was detected then the optional [else] block will be used. If there was an error then the [else] block will be discarded.

Parameters

label

This is the label specifying the corresponding [try] block. Defaults to "default".

error_scratch

The scratchpad variable, named by this parameter, will be set true if an error was caught.

error_set

Associate the error with the named form variable. See the [error] tag's set parameter, which is called upon to create the association.

hide

Setting hide=1 suppresses the tag's return value, which can be useful with the set attribute.