#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.