Syntax

  catch catch-parameter*

You can use catch to mark the point in your program where execution will resume following a throw. A catch has a name, so you can have multiple active catches with different names. Each throw must name the catch it throws to. A catch introduces a block of code which is executed once the throw is caught.

  declare catch no-planet
  global stream planet

  process
     output "Hello "
     throw no-planet when planet isnt attached
     output planet
     catch no-planet
     output "world!"

This program is designed to run with the value of the stream "planet" supplied on the command line. If this is not done, the throw transfers execution to the catch statement.

(Obviously this simple example would be better handled with a simple do when ... else ... done construct. Catch and throw is intended for large-scale flow control, just as "do when" is intended for small-scale flow control. We use simple examples to illustrate the syntax. We do not recommend using throw and catch where "do when" or other, simpler structures would do as well.)

For information on how catch and throw work together, see throw.

Since catches are named, you must declare the name, just like any other name you introduce into your OmniMark program. The catch declaration can also declare parameters, following the same form as function parameters. Read only, value, and remainder parameters are supported, but not modifiable. Parameters may not be declared optional. See declare function for a full description of function parameters.

The following is an example of a catch declaration with parameters:

  declare catch invalid-item
                value stream the-item
          error value stream the-error
          times value integer num-times

Catches can use either the heralded or parameterized form for declaring arguments, just like function definitions. The same considerations as for functions apply to choosing one or the other.

In addition to the catches you declare yourself, you can also catch two predefined OmniMark throws, #program-error and #external-exception.

A catch is active only when it is in the current execution scope of your program. OmniMark will look for the catch named in a throw in the current scope. If the named catch does not exist in the current scope, OmniMark looks for it in the parent scope, and so on. Once the named catch is found, OmniMark closes the current scope and all intervening scopes as required to reach the catch. Execution is then transferred to the catch.

If the named catch is not found, OmniMark raises an error which will be caught by the first available catch of #program-error.

It is a compile-time error to use a catch that has not been declared. It is also a compile-time error to declare the same catch twice.

You can catch the same catch name at different points in your program, but there can be only one catch of a particular catch name in any one lexical scope. Only the catch in the innermost execution scope is active at any given point in program execution.

Many OmniMark constructs can result in a rule or function being called recursively. Therefore, a single lexical catch may exist at many different levels of execution scope when a program is run.

Catch statements are always at the end of a scope. That is to say, a catch ends the current lexical scope and the body of the catch is outside the normal flow of that scope. Execution does not fall through into a catch body. The code in a catch body can only be executed as a result of a throw to that catch. A throw initiated inside a catch body or an associated always cannot be caught in the local scope. Throws within a catch or always block must be caught at a wider scope of execution.

Catch and throw versus function calls

Catch and throw has much in common with function calls. Both declare and use parameters to pass information, and both cause a transfer in execution to a new part of the program. They differ in the following principal ways:

• A function call causes the creation of a new execution scope. A throw initiates the collapsing of current execution scopes up to and including the scope in which the catch occurs.
• A function body can be defined only once for a given function name. Multiple different catch bodies can be defined for the same catch name, so long as they occur in different lexical scopes. Which catch is executed depends on which is active at the time a throw occurs. Only one catch of a given name is active at any given point in program execution.
• A catch does not have to use the full syntax of its declaration when it is defined in code. The names of the parameters used in a definition do not have to match those used in the declaration or any other definition -- only the position or the heralds have to match. A definition does not have to define any of the parameters, but must define any it intends to use.

Related Syntax    #program-error    #external-exception    always    throw    rethrow    declare catch

Related Concepts    Catch and throw

[ INDEX ] [ CONCEPTS ] [ TASKS ] [ SYNTAX ] [ LIBRARIES ] [ LEGACYLIBRARIES ] [ ERRORS ]