#external-exception

catch name

Purpose

#external-exception is a built-in catch name that you can use to catch errors generated by OmniMark's interaction with the outside world. OmniMark will generate a throw to #external-exception when it encounters a problem dealing with the file system, for instance. Many OmniMark external function libraries will also throw to #external-exception when they encounter an error.

If a throw to #external-exception is not caught, OmniMark will generate a throw to #program-error.

#external-exception has three parameters:

  • identity, a stream that contains an identifying error code,
  • message, a stream that contains a description of the error, and
  • location, a stream that contains the location of the error in the OmniMark source code.

When you write a catch clause for #external-exception, it is only necessary to specify the parameters you will be using in the catch clause.

  process
     local stream my-stream
  
     open my-stream as file "/just/not/there"
  
   catch #external-exception 
     output "Something went wrong. Don't know what it was.%n"

The following code uses all the parameters of #external-exception.

  process
     local stream my-stream
  
     open my-stream as file "/just/not/there"
  
   catch #external-exception identity error-code message error-message location error-location
     output "I know what went wrong:%n"	
         || "The error code is: " || error-code || "%n"
         || "The error message is: " || error-message || "%n"
         || "The error location is: " || error-location || "%n"