#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 string that contains the OmniMark error message, and
  • location, a string 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 clause. In the following example, none of the parameters of #program-error are used: 

  global string words variable initial-size 1
  
  process
     submit file "bar"
  
     repeat over words as word
        output word
     again
  
   catch #program-error
     output "Something went wrong somewhere.%n"
  
  find letter+ => word
     set new words to word
This code will generate a throw to #program-error, because the first item on the shelf words is unattached (words should have been declared with initial-size 0).

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

  global string words variable initial-size 1
  
  process
     submit file "bar"
  
     repeat over words as word
        output word
     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