<?xml version='1.0' encoding='ISO-8859-1' standalone='no'?>
<!DOCTYPE interface-description SYSTEM 'file:///usr/pkgsrc/lang/oo2c/work.macaroon/oo2c_32-2.0.11/rsrc/OOC/xml/interface-description.dtd'>
<interface-description name='Exception' id=''>
  <oberon-doc>
    <summary>The statement</summary>
    <p pad-after='yes' no-indent='yes'>The statement</p>
    <example pad-after='yes'>TRY
  S
CATCH T1(t1):
  C1
CATCH T2(t2):
  C2
END;
</example>
    <p pad-after='yes' no-indent='no'>is roughly equivalent to</p>
    <enumerate pad-after='yes' mode='number' start='1'>
      <item pad-after='yes'>
        <p pad-after='no' no-indent='yes'>Push exception handler for this <code>TRY</code> block (<oberon-proc href='#PushContext'>PushContext</oberon-proc>).</p>
      </item>
      <item pad-after='yes'>
        <p pad-after='no' no-indent='yes'>Evaluate <var>S</var>, followed by <oberon-proc href='#PopContext'>PopContext</oberon-proc>.  If there are any <code>RETURN</code> or <code>EXIT</code> statements within <var>S</var> that would cause control flow to leave the <code>TRY</code> statement, then they also do an implicit <oberon-proc href='#PopContext'>PopContext</oberon-proc> as part of the non-local exit.</p>
      </item>
      <item pad-after='no'>
        <p pad-after='yes' no-indent='yes'>If an exception is raised during <var>S</var>, then do</p>
        <example pad-after='no'>Exception.PopContext;
temp := Exception.Current();
WITH temp: T1 DO
  t1 := temp;
  C1;
| temp: T2 DO
  t2 := temp;
  C2;
ELSE
  Exception.ActivateContext;
END;
Exception.Clear;
</example>
      </item>
    </enumerate>
    <p pad-after='yes' no-indent='no'>An exception is raised by calling the predefined procedure <code>RAISE</code> with an instance of <oberon-type href='#Exception'>Exception</oberon-type>.  This passes control to the nearest <code>CATCH</code> clause whose type is an extension of the raised exception, if such a clause exist.  Otherwise, the exception is written to <var>stderr</var> and the program is aborted.</p>
    <p pad-after='yes' no-indent='no'>Within a <code>CATCH</code>, the optional name given in parenthesis refers to the current exception that triggered the <code>CACTH</code>.  Its type is the one from the <code>CATCH</code> clause.  The variable is read-only.</p>
    <p pad-after='yes' no-indent='no'>An exception <var>E</var> must either be caught within a procedure, or the procedure must declare that it may pass an exception of type <var>E</var> up to its caller.  For example,</p>
    <example pad-after='yes'>PROCEDURE P() RAISES E;
</example>
    <p pad-after='yes' no-indent='yes'>declares that evaluation of <samp>P</samp> may raise an exception of type <var>E</var>, or an extension thereof.</p>
    <p pad-after='yes' no-indent='no'>Within the module body no exceptions can be passed up, because there is no caller.  As a consequence, any exception that is not caught explicity is written to <var>stderr</var> and aborts the program.</p>
    <p pad-after='yes' no-indent='no'><emph>Note</emph>: A <code>TRY</code> block is mapped to C's <samp>setjmp()</samp> function by <code>oo2c</code>.  The amount of data stored by this function depends on the target architecture and may differ by a factor of ten or more.  For example, on a <samp>ix86</samp> processor, only 72 bytes are stored, while on a <samp>PPC</samp> this is 768 bytes.  As a consequence, the work done within a <code>TRY</code> should be large enough to amortize the costs of the <code>TRY</code> for all possible targets.</p>
  </oberon-doc>
  <import-decl name='SYSTEM' id='SYSTEM' export='no' module='SYSTEM'/>
  <import-decl name='RT0' id='RT0' export='no' module='RT0'/>
  <import-decl name='Object' id='Object' export='no' module='Object'/>
  <var-decl name='GetThreadState' id='GetThreadState' export='yes'>
    <oberon-doc>
      <summary>Return a pointer to the per-thread data area for exception state.</summary>
      <p pad-after='yes' no-indent='yes'>Return a pointer to the per-thread data area for exception state.  If the program uses threading, then this function returns a pointer to thread local storage.</p>
    </oberon-doc>
    <type>
      <formal-parameters>
        <result-type>
          <type-name name='ThreadStatePtr' href='#ThreadStatePtr'/>
        </result-type>
      </formal-parameters>
    </type>
  </var-decl>
  <procedure name='Raise' id='Raise' export='yes'>
    <oberon-doc>
      <summary>Raise exception <oberon-param href='#Raise.e'>e</oberon-param>.</summary>
      <p pad-after='yes' no-indent='yes'>Raise exception <oberon-param href='#Raise.e'>e</oberon-param>.  On systems that support it, the first time this procedure is called with a given exception it stores the first few entries of the call stack.  This procedure is the implementation of the predefined procedure <code>RAISE</code>.</p>
      <pre-cond pad-after='yes'>
        <p pad-after='no' no-indent='yes'><oberon-param href='#Raise.e'>e</oberon-param> is not <code>NIL</code>.</p>
      </pre-cond>
    </oberon-doc>
    <formal-parameters>
      <parameter-decl name='e' id='Raise.e' export='no' variable-parameter='no'>
        <type>
          <type-name name='Exception' href='#Exception'/>
        </type>
      </parameter-decl>
      <exceptions>
        <type-name name='Exception' href='#Exception'/>
      </exceptions>
    </formal-parameters>
  </procedure>
  <procedure name='Clear' id='Clear' export='yes'>
    <oberon-doc>
      <summary>Set the current exception marker to <code>NIL</code>.</summary>
      <p pad-after='yes' no-indent='yes'>Set the current exception marker to <code>NIL</code>.  This procedure is called at the very end of a <code>CATCH</code> block.  It should never be called directly.</p>
      <p pad-after='yes' no-indent='no'>Note: This procedure does <emph>not</emph> restore the value of <oberon-proc href='#Current'>Current</oberon-proc> to that of the beginning of a <code>TRY</code> statement.  That is, after a <code>TRY</code> <oberon-proc href='#Current'>Current</oberon-proc> is <code>NIL</code> if an exception was raised.</p>
    </oberon-doc>
    <formal-parameters/>
  </procedure>
  <procedure name='ClearFixed' id='ClearFixed' export='yes'>
    <oberon-doc>
      <summary>FIXME...</summary>
      <p pad-after='yes' no-indent='yes'>FIXME... Eliminate this procedure again.</p>
    </oberon-doc>
    <formal-parameters>
      <parameter-decl name='context' id='ClearFixed.context' export='no' variable-parameter='yes'>
        <type>
          <type-name name='Context' href='#Context'/>
        </type>
      </parameter-decl>
    </formal-parameters>
  </procedure>
  <procedure name='PushContext' id='PushContext' export='yes'>
    <oberon-doc>
      <summary>Push <oberon-param href='#PushContext.context'>context</oberon-param> on the stack of exception handlers, and make it point to the execution context <oberon-param href='#PushContext.jmpbuf'>jmpbuf</oberon-param>.</summary>
      <p pad-after='yes' no-indent='yes'>Push <oberon-param href='#PushContext.context'>context</oberon-param> on the stack of exception handlers, and make it point to the execution context <oberon-param href='#PushContext.jmpbuf'>jmpbuf</oberon-param>.  This procedure should never be called directly.</p>
    </oberon-doc>
    <formal-parameters>
      <parameter-decl name='context' id='PushContext.context' export='no' variable-parameter='yes'>
        <type>
          <type-name name='Context' href='#Context'/>
        </type>
      </parameter-decl>
      <parameter-decl name='jmpbuf' id='PushContext.jmpbuf' export='no' variable-parameter='no'>
        <type>
          <type-name module='SYSTEM' name='PTR' href='SYSTEM#PTR'/>
        </type>
      </parameter-decl>
    </formal-parameters>
  </procedure>
  <procedure name='PopContext' id='PopContext' export='yes'>
    <oberon-doc>
      <summary>Remove <oberon-param href='#PopContext.n'>n</oberon-param> entries from the top of exception handler stack.</summary>
      <p pad-after='yes' no-indent='yes'>Remove <oberon-param href='#PopContext.n'>n</oberon-param> entries from the top of exception handler stack.  This procedure should never be called directly.</p>
      <pre-cond pad-after='yes'>
        <p pad-after='no' no-indent='yes'><samp><oberon-param href='#PopContext.n'>n</oberon-param> &gt;= 1</samp>.</p>
      </pre-cond>
    </oberon-doc>
    <formal-parameters>
      <parameter-decl name='n' id='PopContext.n' export='no' variable-parameter='no'>
        <type>
          <type-name module='#predef' name='LONGINT'/>
        </type>
      </parameter-decl>
    </formal-parameters>
  </procedure>
  <procedure name='ActivateContext' id='ActivateContext' export='yes'>
    <oberon-doc>
      <summary>Activate the execution context on the top of the exception handler stack.</summary>
      <p pad-after='yes' no-indent='yes'>Activate the execution context on the top of the exception handler stack.  If the stack is empty, a message with details of the current exception is written to <var>stderr</var>, and the program is aborted.  This procedure should never be called directly.</p>
    </oberon-doc>
    <formal-parameters/>
  </procedure>
  <procedure name='Abort' id='Abort' export='yes'>
    <oberon-doc>
      <summary>Write data of exception <oberon-param href='#Abort.e'>e</oberon-param> to <var>stderr</var> and abort program.</summary>
      <p pad-after='yes' no-indent='yes'>Write data of exception <oberon-param href='#Abort.e'>e</oberon-param> to <var>stderr</var> and abort program.</p>
    </oberon-doc>
    <formal-parameters>
      <parameter-decl name='e' id='Abort.e' export='no' variable-parameter='no'>
        <type>
          <type-name name='Exception' href='#Exception'/>
        </type>
      </parameter-decl>
    </formal-parameters>
  </procedure>
  <procedure name='FatalError' id='FatalError' export='yes'>
    <oberon-doc>
      <summary>Raise an exception with message <oberon-param href='#FatalError.msg'>msg</oberon-param> and abort program.</summary>
      <p pad-after='yes' no-indent='yes'>Raise an exception with message <oberon-param href='#FatalError.msg'>msg</oberon-param> and abort program.</p>
    </oberon-doc>
    <formal-parameters>
      <parameter-decl name='msg' id='FatalError.msg' export='no' variable-parameter='no'>
        <type>
          <type-name name='STRING' href='#STRING'/>
        </type>
      </parameter-decl>
    </formal-parameters>
  </procedure>
  <import-decl name='-RT0' id='-RT0' export='no' module='RT0'/>
  <import-decl name='-Object' id='-Object' export='no' module='Object'/>
  <class name='Exception'>
    <type-decl name='Exception' id='Exception' export='yes'>
      <type>
        <pointer>
          <pointer-base>
            <type-name name='ExceptionDesc' href='#ExceptionDesc'/>
          </pointer-base>
        </pointer>
      </type>
    </type-decl>
    <type-decl name='ExceptionDesc' id='ExceptionDesc' export='yes'>
      <oberon-doc>
        <summary>An exception describes an anomalous condition that makes it impossible to complete a given task.</summary>
        <p pad-after='yes' no-indent='yes'>An exception describes an anomalous condition that makes it impossible to complete a given task.  It provides a short, human readable text describing the problem.  If supported, it also includes information on the top few entries of the procedure call stack.</p>
      </oberon-doc>
      <type>
        <record/>
      </type>
    </type-decl>
    <procedure name='INIT' id='ExceptionDesc.INIT' export='yes'>
      <oberon-doc>
        <summary>Initialize exception <oberon-param href='#ExceptionDesc.INIT.e'>e</oberon-param> and set <oberon-param href='#ExceptionDesc.INIT.msg'>msg</oberon-param> as its message.</summary>
        <p pad-after='yes' no-indent='yes'>Initialize exception <oberon-param href='#ExceptionDesc.INIT.e'>e</oberon-param> and set <oberon-param href='#ExceptionDesc.INIT.msg'>msg</oberon-param> as its message.  <oberon-param href='#ExceptionDesc.INIT.msg'>msg</oberon-param> may be <code>NIL</code>, but in this case <oberon-proc href='#ExceptionDesc.GetMessage'>Exception.GetMessage</oberon-proc> must be redefined to provide a non-<code>NIL</code> message.</p>
        <pre-cond pad-after='yes'>
          <p pad-after='no' no-indent='yes'><oberon-param href='#ExceptionDesc.INIT.e'>e</oberon-param> is not <code>NIL</code>.</p>
        </pre-cond>
      </oberon-doc>
      <formal-parameters>
        <receiver-decl name='e' id='ExceptionDesc.INIT.e' export='no' variable-parameter='no'>
          <type>
            <type-name name='Exception' href='#Exception'/>
          </type>
        </receiver-decl>
        <parameter-decl name='msg' id='ExceptionDesc.INIT.msg' export='no' variable-parameter='no'>
          <type>
            <type-name name='STRING' href='#STRING'/>
          </type>
        </parameter-decl>
      </formal-parameters>
    </procedure>
    <procedure name='Current' id='Current' export='yes'>
      <oberon-doc>
        <summary>Return the pointer to the currently active exception.</summary>
        <p pad-after='yes' no-indent='yes'>Return the pointer to the currently active exception.  This is <code>NIL</code> if no exception has been raised, or when a <code>CATCH</code> clause has been completed successfully for the last exception.  Within a <code>CATCH</code> block that includes a name in parenthesis, the name identifies a predefined read-only variable holding the same pointer value.</p>
        <p pad-after='yes' no-indent='no'><emph>Note</emph>: Within a <code>CATCH</code> block, this function's result becomes undefined at the start of the first <code>TRY</code> statement nested in the <code>CATCH</code>.  Catching into a name defines the value over the whole <code>CATCH</code> block.</p>
      </oberon-doc>
      <formal-parameters>
        <result-type>
          <type-name name='Exception' href='#Exception'/>
        </result-type>
      </formal-parameters>
    </procedure>
    <procedure name='GetMessage' id='ExceptionDesc.GetMessage' export='yes'>
      <oberon-doc>
        <summary>Return the message string describing the exception <oberon-param href='#ExceptionDesc.GetMessage.e'>e</oberon-param>.</summary>
        <p pad-after='yes' no-indent='yes'>Return the message string describing the exception <oberon-param href='#ExceptionDesc.GetMessage.e'>e</oberon-param>.</p>
      </oberon-doc>
      <formal-parameters>
        <receiver-decl name='e' id='ExceptionDesc.GetMessage.e' export='no' variable-parameter='no'>
          <type>
            <type-name name='Exception' href='#Exception'/>
          </type>
        </receiver-decl>
        <result-type>
          <type-name name='STRING' href='#STRING'/>
        </result-type>
      </formal-parameters>
    </procedure>
    <procedure name='WriteBacktrace' id='ExceptionDesc.WriteBacktrace' export='yes'>
      <oberon-doc>
        <summary>If available, write the top-most entries of the call stack to <var>stderr</var>.</summary>
        <p pad-after='yes' no-indent='yes'>If available, write the top-most entries of the call stack to <var>stderr</var>.  This function uses the GNU function <samp>backtrace_symbols()</samp> to produce its output.  Please see the documentation of GNU libc for more information on how to make function names available to the program.  The tool <samp>oobacktrace</samp> may also be able to add function names to the output.</p>
      </oberon-doc>
      <formal-parameters>
        <receiver-decl name='e' id='ExceptionDesc.WriteBacktrace.e' export='no' variable-parameter='no'>
          <type>
            <type-name name='Exception' href='#Exception'/>
          </type>
        </receiver-decl>
      </formal-parameters>
    </procedure>
    <procedure name='Name' id='ExceptionDesc.Name' export='yes'>
      <oberon-doc>
        <summary>Return the name of the execption's type as <samp><var>module</var>.<var>typename</var></samp>.</summary>
        <p pad-after='yes' no-indent='yes'>Return the name of the execption's type as <samp><var>module</var>.<var>typename</var></samp>.</p>
      </oberon-doc>
      <formal-parameters>
        <receiver-decl name='e' id='ExceptionDesc.Name.e' export='no' variable-parameter='no'>
          <type>
            <type-name name='Exception' href='#Exception'/>
          </type>
        </receiver-decl>
        <result-type>
          <type-name module='Object' name='String8' href='Object#String8'/>
        </result-type>
      </formal-parameters>
    </procedure>
  </class>
  <class name='Context'>
    <type-decl name='ContextPtr' id='ContextPtr' export='no'>
      <type>
        <pointer>
          <pointer-base>
            <type-name name='Context' href='#Context'/>
          </pointer-base>
        </pointer>
      </type>
    </type-decl>
    <type-decl name='Context' id='Context' export='yes'>
      <oberon-doc>
        <summary>Use by the run-time system to store an execution context for later (re)use.</summary>
        <p pad-after='yes' no-indent='yes'>Use by the run-time system to store an execution context for later (re)use.</p>
      </oberon-doc>
      <type>
        <record/>
      </type>
    </type-decl>
  </class>
  <class name='ParseError'>
    <type-decl name='ParseError' id='ParseError' export='yes'>
      <type>
        <pointer>
          <pointer-base>
            <type-name name='ParseErrorDesc' href='#ParseErrorDesc'/>
          </pointer-base>
        </pointer>
      </type>
    </type-decl>
    <type-decl name='ParseErrorDesc' id='ParseErrorDesc' export='no'>
      <type>
        <record>
          <field-decl name='offset' id='ParseErrorDesc.offset' export='read-only'>
            <oberon-doc>
              <summary>The offset relative to the beginning of the parsed text where the error was found.</summary>
              <p pad-after='yes' no-indent='yes'>The offset relative to the beginning of the parsed text where the error was found.  If this information is not available, then this field is <samp>-1</samp>.</p>
            </oberon-doc>
            <type>
              <type-name module='#predef' name='LONGINT'/>
            </type>
          </field-decl>
        </record>
      </type>
    </type-decl>
    <procedure name='INIT' id='ParseErrorDesc.INIT' export='yes'>
      <doc-inherited-from module='Exception' name='INIT' class='Exception' href='#ExceptionDesc.INIT'/>
      <oberon-doc>
        <summary>Initialize exception <oberon-param href='#ParseErrorDesc.INIT.e'>e</oberon-param> and set <oberon-param href='#ParseErrorDesc.INIT.msg'>msg</oberon-param> as its message.</summary>
        <p pad-after='yes' no-indent='yes'>Initialize exception <oberon-param href='#ParseErrorDesc.INIT.e'>e</oberon-param> and set <oberon-param href='#ParseErrorDesc.INIT.msg'>msg</oberon-param> as its message.  <oberon-param href='#ParseErrorDesc.INIT.msg'>msg</oberon-param> may be <code>NIL</code>, but in this case <oberon-proc href='#ExceptionDesc.GetMessage'>Exception.GetMessage</oberon-proc> must be redefined to provide a non-<code>NIL</code> message.</p>
        <pre-cond pad-after='yes'>
          <p pad-after='no' no-indent='yes'><oberon-param href='#ParseErrorDesc.INIT.e'>e</oberon-param> is not <code>NIL</code>.</p>
        </pre-cond>
      </oberon-doc>
      <formal-parameters>
        <receiver-decl name='e' id='ParseErrorDesc.INIT.e' export='no' variable-parameter='no'>
          <type>
            <type-name name='ParseError' href='#ParseError'/>
          </type>
        </receiver-decl>
        <parameter-decl name='msg' id='ParseErrorDesc.INIT.msg' export='no' variable-parameter='no'>
          <type>
            <type-name name='STRING' href='#STRING'/>
          </type>
        </parameter-decl>
        <parameter-decl name='offset' id='ParseErrorDesc.INIT.offset' export='no' variable-parameter='no'>
          <type>
            <type-name module='#predef' name='LONGINT'/>
          </type>
        </parameter-decl>
      </formal-parameters>
      <redefined-method module='Exception' name='INIT' class='Exception' href='#ExceptionDesc.INIT'/>
    </procedure>
    <base-class module='Exception' class='Exception' href='#Exception'>
      <inherited-method module='Exception' name='GetMessage' class='Exception' href='#ExceptionDesc.GetMessage'/>
      <inherited-method module='Exception' name='INIT' class='Exception' href='#ExceptionDesc.INIT'/>
      <inherited-method module='Exception' name='Name' class='Exception' href='#ExceptionDesc.Name'/>
      <inherited-method module='Exception' name='WriteBacktrace' class='Exception' href='#ExceptionDesc.WriteBacktrace'/>
    </base-class>
  </class>
  <class name='ThreadState'>
    <type-decl name='ThreadStatePtr' id='ThreadStatePtr' export='yes'>
      <type>
        <pointer>
          <pointer-base>
            <type-name name='ThreadState' href='#ThreadState'/>
          </pointer-base>
        </pointer>
      </type>
    </type-decl>
    <type-decl name='ThreadState' id='ThreadState' export='yes'>
      <oberon-doc>
        <summary>Holds thread local state for the exception module.</summary>
        <p pad-after='yes' no-indent='yes'>Holds thread local state for the exception module.</p>
      </oberon-doc>
      <type>
        <record/>
      </type>
    </type-decl>
    <procedure name='InitThreadState' id='InitThreadState' export='yes'>
      <formal-parameters>
        <parameter-decl name='ts' id='InitThreadState.ts' export='no' variable-parameter='yes'>
          <type>
            <type-name name='ThreadState' href='#ThreadState'/>
          </type>
        </parameter-decl>
      </formal-parameters>
    </procedure>
  </class>
  <module-ref name='Object'>
    <ref-target type='html' relative-uri='Object.html'/>
  </module-ref>
</interface-description>
