set-voluntary-end-exception

function

Library: I/O exception support (OMIOE legacy)
Include: omioe.xin

Declaration

define external function set-voluntary-end-exception
       value io-exception ex

Purpose

This function allows you to set the "voluntary end" status in an "io-exception" status. The "voluntary end" status allows an OmniMark program to signal an external source that it is to immediately return end-of-input, causing the OmniMark program to exit from any submit, scan, or set that may be using the source. This means that OmniMark programs don't have to consume large sources beyond the point at which they determine that they've found what they're looking for.

Argument:

"ex". This is the "io-exception" object for which you want to set the "voluntary end" status.

Example:

  ; Using "set-voluntary-end-exception" to recognize and act on a data-encoded
  ; stream end mark (in this case "Control-Z"). The global declaration and
  ; process rule indicate how the source scanned by the find rule, and the
  ; io-exception used by it would be set up.
  ; This example also uses "get-exception-status" and "io-exception-text" to report
  ; errors (exceptions other than the voluntary end) in using the source.
  
  global io-exception input-exception
  process
     submit input-file "myfile.txt" exceptions-to input-exception
     do when get-exception-status input-exception != (0 | IOException_VoluntaryEOF)
        put #error "Error on myfile.txt:%n" ||
                   io-exception-text get-exception-status input-exception
     done
  
  find "%26#" ; Control-Z
     set-voluntary-end-exception input-exception

Other Library Functions