Table 20–1 lists system PROCEDUREs, variables, and macros for dealing with exceptions.

In order to be an exception, a condition must have been caused by the operations being performed when the condition occurred. Asynchronous interrupts and events occurring in other tasks or processes are not considered to be exceptions, and are not dealt with directly by the MAINSAIL exception mechanism.

Exceptions are divided into two categories: those predefined by MAINSAIL (see Section 20.8) and those known only to user programs. User exceptions must be explicitly caused by the user program by means of the system PROCEDURE $raise; predefined exceptions are caused by the MAINSAIL runtime system.

Exceptions are denoted by STRINGs. Section 20.7 describes conventions supported by MAINSAIL to help ensure that exception names are unique.

A program can “register” its exceptions with MAINSAIL using the system PROCEDURE $registerException. The system PROCEDURE errMsg allows a user, in response to the Error response: prompt, to obtain a list of the exceptions that have been registered and to raise any registered exception.

By default, the system PROCEDURE errMsg raises a predefined exception before writing its message to logFile. This may cause the execution of a handler that recovers from the exception by aborting the call to errMsg, in which case the message is not written to logFile. If no such handler is found, the message is written as if no exception had been raised.

20.1. $HANDLE Statement

The general form of the $HANDLE statement is:

$HANDLE s1 $WITH s2

where s1 and s2 are statements. The statement s1 is the handled statement and s2 is the handler.

MAINSAIL provides the abbreviations $HANDLEB for $HANDLE BEGIN and $WITHB for $WITH BEGIN.

When a $HANDLE statement is executed, its handled statement s1 is initiated. If an exception occurs during s1's execution (which may involve several levels of PROCEDURE calls), and the exception has not been handled by another $HANDLE statement initiated during s1's execution, then s1's execution is suspended and the exception handler s2 is executed. Otherwise, s2 is ignored.

A handler can either recover from an exception (unless the exception disallows it) or it can propagate the exception to another exception handler. In the first case, the handler is said to have handled the exception.

20.2. Handling Exceptions

• If the exception that occurred was caused by an explicit call to the system PROCEDURE $raise, the handler can resume execution at the place in s1 where the exception occurred by calling the system PROCEDURE $raiseReturn. This terminates the handler's execution. When s1 terminates after its execution is resumed, s2 is ignored. If the exception that occurred was not caused by an explicit call to $raise, a runtime error occurs if $raiseReturn is called to continue from the exception.

• The handler can terminate the $HANDLE statement's execution in one of three ways:
  1. It can resume execution at the statement following the $HANDLE statement, if any, by having control fall out of the handler.

  2. If the $HANDLE statement is contained within an iterative statement, the handler can terminate the $HANDLE statement's execution and either repeat or terminate the execution of the iterative statement using a CONTINUE or DONE statement.

  3. The handler can terminate the $HANDLE statement's execution and return from the PROCEDURE containing the $HANDLE statement by means of a RETURN statement.

When a handler terminates the execution of its $HANDLE statement, the handled statement s1, whose execution was suspended by the occurrence of the exception, is aborted, along with all other statements initiated as a result of s1's execution (and all PROCEDUREs thus invoked). When a PROCEDURE is aborted in this manner, if it contains any active handled statements, MAINSAIL raises the predefined exception $abortProcedureExcpt and executes the handlers associated with the handled statements. This gives each procedure a chance to do any “cleaning up” that might be necessary before it is aborted; see Section 20.6.

20.3. Propagating Exceptions

When an exception is caused by means of the system PROCEDURE $raise (see Section 46.1), more information about the exception can be passed by means of the $raise parameters exceptionStringArg1, exceptionStringArg2, and exceptionPointerArg. A handler can access the values passed for these parameters as $exceptionStringArg1, $exceptionStringArg2, and $exceptionPointerArg, respectively.

20.5. Nested Exceptions

$HANDLE
    $HANDLE $raise("first exception")
    $WITH $raise("second exception")
$WITH;  # Abort both $HANDLE statements

20.5.1. Exceptions Raised While an Exception with $cannotFallOut Set Is Being Handled

For example, in the following $HANDLE statement, $cannotFallOut would be set when the second exception's handler is invoked for exception "y", even though the call to $raise that raised that exception does not explicitly set it:

$HANDLE
    $HANDLE $raise("x","","",NULLPOINTER,$cannotFallOut)
    $WITHB $raise("y"); $raiseReturn END
$WITHB
    write(logFile,"$cannotFallOut set: ",
        $exceptionBits TST $cannotFallOut,eol); # Writes TRUE
    $raiseReturn END;

Note that in the following example, $cannotFallOut would not be set when the handler for exception "b" is raised, since falling out of this handler would not abort the one for exception "a":

$HANDLE $raise("a","","",NULLPOINTER,$cannotFallOut)
$WITHB
    $HANDLE $raise("b")
    $WITH write(logFile,"$cannotFallOut set: ",
            $exceptionBits TST $cannotFallOut,eol); # Writes FALSE
    $raiseReturn END;

• MAINSAIL initiates handlers only in PROCEDUREs that are about to be aborted. When the exception is propagated to a handler in a PROCEDURE that is not being aborted, MAINSAIL intercepts it, marks it as handled, and finishes aborting the PROCEDUREs' execution.

• MAINSAIL requires each handler for this exception to propagate the exception to the next handler (the bits $cannotReturn and $cannotFallOut are set in $exceptionBits). If a handler attempts to handle the exception either by calling the system PROCEDURE $raiseReturn or by terminating the execution of its $HANDLE statement, a runtime error occurs.

• It is an error for the user to raise $abortProcedureExcpt explicitly.

If a PROCEDURE must perform certain actions to “clean up” after itself before it is aborted, such as closing files, disposing of dynamic objects, or releasing scan bits, it should contain a handler that catches the exception denoted by $abortProcedureExcpt, does the required cleaning up, and propagates the exception to the next PROCEDURE being aborted; for example:

PROCEDURE compiler;
BEGIN
POINTER(textFile) inputFile;

inputFile := NULLPOINTER;
$HANDLE
    WHILE open(inputFile,"compile: ",input!prompt!errorOK)
    DOB compileModule(inputFile); close(inputFile) END
$WITHB
    IF $exceptionName = $abortProcedureExcpt THEN
        IF inputFile THEN close(inputFile);
    $raise END END;

"s₁:s₂: ... :s_n"

According to this convention, the last phrase describes the actual exception and the first phrases serve to distinguish the exception from other exceptions having the same last phrase. Typically, the first phrases would contain the name of the company owning the rights to the system in which the exception is embedded, or the name of a product of the company, as in:

"MAINSAIL compiler: Abort compilation"

All predefined exceptions begin with the substring "MAINSAIL". Programmers should avoid choosing exception names that begin with that substring.

The system PROCEDURE $newException (see Section 42.3) returns a STRING consisting of a unique decimal integer followed by a colon. To avoid conflicts with names created from STRINGs returned by $newException, users should avoid choosing an exception name that begins with a decimal integer and a colon unless that prefix was obtained by calling $newException.

20.8. Predefined Exceptions

The predefined exceptions and the identifiers by which they are known are given in Appendix C. The conditions under which these exceptions can be raised are described at the relevant points in this manual.

XIDAK reserves the right to create new predefined exceptions. MAINSAIL programmers should be aware that system predefined exceptions, or undocumented exceptions used internally by the MAINSAIL runtime system, may be raised by many MAINSAIL constructs. Since exception handlers may not recognize the names of all the exceptions they handle, they must therefore be written to deal with unknown exceptions by examining $exceptionBits and taking appropriate action.

20.8.1. $abortProgramExcpt and $systemExcpt

The exception denoted by $systemExcpt includes all errors not covered by the other predefined exceptions, in which case the specific error is described by the STRINGs returned by $exceptionStringArg1 and $exceptionStringArg2. $systemExcpt is usually raised by calling errMsg.

The exceptions denoted by $abortProgramExcpt and $systemExcpt are the only predefined exceptions that may be handled by resuming execution at the place where the exception occurred.

The exception denoted by $abortProgramExcpt is the only predefined exception that is registered.

20.9. Informational Exceptions

Some exceptions, however, do not necessarily require any action, but merely inform the ancestral PROCEDUREs of something that has occurred. The system exception $descendantKilledExcpt falls into this category. System exceptions that are informational can be distinguished because they have both the $cannotReturn and $cannotFallOut bits set in $exceptionBits (although $abortProcedureExcpt also has both these bits set, $abortProcedureExcpt is not considered an informational exception).

General-purpose error handlers should be written so as to handle informational exceptions properly, i.e., to call $raise with no parameters to propagate the exception.

20.10. errMsg Response Abbreviations

In a response to the Error response: prompt, distinctions between upper- and lowercase letters are ignored when comparing a specified response to one of the expected responses.

Responses may be abbreviated, but an abbreviation must be unambiguous. A response's text is divided into phrases separated by colons. By convention, the last phrase describes the action to be taken as a result of the response. Any preceding phrases serve to distinguish the response from other responses having the same last phrase; for example, the response "MAINSAIL: Abort program" consists of the phrases "MAINSAIL" and "Abort program".

Responses may be abbreviated by omitting leftmost phrases (and the colons that follow them). The phrases present may be abbreviated by omitting trailing words and, within the words present, by omitting trailing characters. A blank or tab between words in a specified response is equivalent to any number of blanks or tabs in an expected response.

If a specified response is an abbreviation for more than one expected response, then:

• If the specified response exactly matches one of the expected responses, it is assumed to denote the expected response it exactly matches.

• If a phrase in the specified response exactly matches a corresponding phrase in only one expected response and none of its other phrases exactly matches the corresponding phrases in any of the other expected responses, then the specified response is assumed to denote the one expected response.

• Otherwise, the specified response is ambiguous, in which case errMsg writes to logFile the expected responses for which the specified response is an abbreviation and reads another response from cmdFile.

For the following set of expected responses:

MAINSAIL: Abort program
MAINSAIL compiler: Abort compilation
Abort

the following responses are valid and invalid, as described:

20.10.1. Sample Use of Registered Exceptions

$registerException
    ("KILL","Kill process p",useKeyWord,"p");
$registerException
    ("KILL","Kill current process",$doNotMatch);

(parameters to $registerException are described in Section 46.10). If errMsg is called and the user types ?, errMsg displays:

KILL p          Kill process p
KILL            Kill current process

There are two instances of the exception KILL, but the second one (the one registered with $doNotMatch set) is used only by errMsg when it displays the registered exceptions.

If the user types k main<eol>, k matches the exception KILL and main is set aside as the response's argument. errMsg raises the exception KILL and passes main as the $raise argument exceptionStringArg1. The program is expected to have a handler for the exception KILL and gets the name of the process to be killed by calling $exceptionStringArg1. If the user types just k, the empty STRING is passed as the $raise argument exceptionStringArg1.

A call to $registerException might look like:

$registerException("DEBUG","to enter the debugger")

In order for an exception to be raised from errMsg, it must have been registered; exceptions that are not to be raised from errMsg need not be registered.

The system PROCEDURE $deregisterException (see Section 33.18) causes an exception to be no longer registered.

20.11. Known Exception Handling Problems

The exception mechanism contains the following known bugs:

• $HANDLE statements statically nested in a $WITH clause do not always see $abortProcedureExcpt. For example, in:

  PROCEDURE p;
  $HANDLE # P0
      $raise("X")
  $WITH
      $HANDLE # P1
          $raise("Y")
      $WITH
          $raise;
  
  PROCEDURE q;
  $HANDLE # Q0
      p
  $WITH
      ; # fall out of Y and X

  the $HANDLE statement P1 does not see $abortProcedureExcpt when Q0 falls out, although P0 does. Both should see $abortProcedureExcpt because both are aborted by Q0 falling out.

• An exception raised in a suspended frame (like $almostOutOfMemoryExcpt or $overheadTooHighExcpt) is always supposed to have $cannotFallOut and $cannotReturn set in $exceptionBits, but sometimes does not. Falling out or calling $raiseReturn from an exception that should have these bits set but does not has undefined effects.

These bugs may be fixed in a future relase of MAINSAIL.

20.12. Visualizing Exceptions

Figure 20–2 shows a picture of the PROCEDURE stack in the absence of exceptions and exception handlers. In this simple case, the only things on the stack are PROCEDURE frames (one for each PROCEDURE invocation).

Figure 20–3 shows how a handle frame is depicted. A handle frame is conceptually pushed onto the stack whenever a $HANDLE statement is entered. The handler part of the handle frame is then marked as “ready” (meaning ready to handle any exception that occurs in the stack above it).

A handle frame is popped off when one of the following things happens:

• The handled statement finishes execution (the handler is not invoked in this case).

• Control falls out of the handler (thereby aborting the handled statement).

• The $HANDLE statement is aborted (because control fell out of some other exception handler farther down the stack).

(Handle frames are a conceptual tool only. In the actual implementation of $HANDLE statements, nothing is pushed on the stack; the implementation of $HANDLE statements is more efficient than the diagrams imply.)

Figure 20–4 shows how an exception is raised and caught by the first ready exception handler below it on the stack. Once a handler is handling an exception, its status changes from “ready” to “busy”, meaning that it cannot handle any additional ordinary exceptions. All the PROCEDURE frames and handle frames above the handler are grayed out in the diagrams, meaning that the execution of the corresponding code is suspended.

Figure 20–5 shows how an exception is propagated to the next ready handler down the stack when $raise is called with no arguments.

Figure 20–6 shows how PROCEDURE or handle frames invoked from an exception handler are depicted: they are placed on the stack above the frames suspended by exception handling with a large arrow pointing from the exception handler to the frame it invoked. The handler from which the arrow points is the one to which control will return if the new frames complete execution normally. An exception can, of course, occur within the PROCEDURE or handle frame.

Figure 20–7 shows what happens when an exception is raised in an exception handler: the exception is propagated to the next ready handler on the stack below the handler in which it was raised. The handler in which the exception was raised is busy, and therefore cannot handle the exception. This figure also shows the use of $raiseReturn, which “undoes” an exception: it returns control to the place where the exception was raised, unsuspends any code suspended because of the exception, and makes ready any handlers that were made busy by the exception.

Figure 20–8 shows how the special exception $abortProcedureExcpt is raised in all handlers on the stack, even those that are currently busy. Other system exceptions with this characteristic are:

$overheadTooHighExcpt
$almostOutOfMemoryExcpt
$descendantKilledExcpt