#program-error

catch name

Purpose

#program-error is a built-in catch name that you can use to catch run-time errors in your OmniMark program. Errors in the logic of your OmniMark program generate a throw to #program-error. Errors generated by OmniMark's interaction with the outside world result in a throw to #external-exception.

If a throw to #external-exception, or a programmer-defined throw, is not caught, OmniMark will generate a throw to #program-error. If a throw to #program-error is not caught, the program will terminate with an error message sent to the log stream.

#program-error has three parameters:

  • code, an integer that contains the OmniMark error code
  • message, a stream that contains the OmniMark error message
  • location, a stream that contains the location of the error in the program, namely, line number and file path

When you create a catch for #program-error, it is only necessary to specify the parameters you will be using in the catch block. In the following example, none of the parameters of #program-error are used: 

  global stream foo variable initial-size 1
  
  process
     submit file "bar"
     repeat over foo
        output foo
     again
     catch #program-error
        output "Something went wrong somewhere.%n"
  
  find letter+ => a-word
     set new foo to a-word

This code will generate a throw to #program-error, because the first item on the shelf foo is unattached (foo should have been declared with initial-size 0).

The following code uses all the parameters of #program-error: 

  global stream foo variable initial-size 1
  
  process
     submit file "bar"
     repeat over foo
        output foo
     again
     catch #program-error code error-code message error-message location error-location
        output "This is what went wrong:%n"
            || "The error code is: " || "d" % error-code ||  ". %n"
            || "The OmniMark error message is: %n" || error-message || "%n"
            || "The location of the error is: " || error-location || "%n"

Note that XML and SGML error messages are not OmniMark program errors and do not constitute either program errors or external exceptions. You can deal with markup errors using a markup-error rule.

Related Syntax
Related Concepts