{Begin SubSec RAID}
{Title RAID}
{Text

{index Raid}

{Tag Raid}

{note RAID is going to be replaced by TELERAID.  What do I want to say here about TELERAID?  Where is it documented?   (nothing yet. -- bvm)}

{note READSYS?}

{Note VRAID?}

Raid is a low-level debugger that knows about the Interlisp-D stack and certain Interlisp-D objects.  It is principally a tool for those who maintain Interlisp-D and most users will not normally need its facilities.  Raid is entered when Interlisp-D encounters an error (generally a system bug) that cannot be handled in a normal break.  It can be entered explicitly by the control-C interrupt. 

Raid saves away the display and puts up its own.  It prints a message indicating why it was called (e.g. "control-C interrupt" or some error message), prints the prompt {lisp @}, and awaits input of one of the single-letter commands described below.

If Raid is called unexpectedly, stop and read the error message.  If the call occurred by typing control-C, type control-N to resume Interlisp-D transparently.  Otherwise, a system bug probably was encountered.  Do not type control-N in this case, as the bug may compound itself.  Use the {lisp L} command to look at the Interlisp-D stack to see where you were, and the {lisp F} command to look at individual frames.  Once enough information has been learned about the context to report the error, try typing control-D to reset the system (this clears the stack and starts over again at the top level).    This may allow the system to continue long enough to save your work.

The Raid commands are described below in case the user wishes to use Raid deliberately.  However, knowledge of the low-level implementation details may be necessary to make effective use of Raid.  The documentation provided here is not intended to be exhaustive, as Raid and the low-level system implementation are subject to change.



{Begin SubSec Using RAID}
{Title Using RAID}
{Text

This section describes the Raid commands in more detail, should the user wish to explore the context of an error further.  Typing "{lisp ?}" to Raid prints out a brief list of the commands.

Raid can be called from system errors and with the control-C interrupt.
(Note:  The control-C interrupt can be disabled with {lisp (INTERRUPTCHAR (CHARCODE ↑C) NIL)}, or assigned to control-Z with {lisp (INTERRUPTCHAR (CHARCODE ↑Z) 'RAID)}.  See {PageRef Fn INTERRUPTCHAR}.)


Raid can also be entered by calling the following function:

{FnDef {Name RAID} {Args MESS1 MESS2 {anonarg}}
{Text
Calls the Raid debugger, displaying the message {arg MESS1} (followed by a carriage return and {arg MESS2}, if it is specified).
}}



{Begin SubSec How Information is Displayed}
{Title How Information is Displayed}
{Text

Addresses

Raid knows about the form of lists, atoms, strings, and integers, and prints them in roughly the manner expected.  All other Interlisp-D structures, such as arrays and datatypes, print out as the address of the datum.  An Interlisp-D address consists of a {bracket {arg segment}, {arg wordoffset}} pair, where {arg segment} identifies the segment (high eight bits) which often indicates what kind of address it is (e.g. value space, statistics space, stack space, etc.) and {arg wordoffset} is a 16 bit word offset.  These are usually printed by Raid as two unsigned octal numbers enclosed in braces.

Stack frames

Raid displays stack frames as a series of two-word pairs.  Each two-word pair appears on a single line with the halves separated by spaces, and some interpretation (e.g., variable names) to the right.

}{End SubSec How Information is Displayed}


{Begin SubSec Commands}
{Title Commands}
{Text

Each command is listed by the letter that invokes it, followed (in {lbracket} {rbracket}) by the parameters that the command expects and a brief description of its behavior.  Parameters are denoted:

{Begin LabeledList}

{label {arg ADDRESS}}
{text Two octal numbers separated by space}

{label {arg ATOM}}
{text An unquoted character string}

{label {arg CONFIRM}}
{text Command requires confirmation (a carriage return)}

{label {arg DNUM}}
{text A decimal number}

{label {arg ONUM}}
{text An octal number}

{End LabeledList}



{Begin LabeledList}

{label control-B {bracket {arg ADDRESS}, {arg ONUM}}}
{text Displays {arg ONUM} bytes starting at {arg ADDRESS}.}

{label control-D {bracket {arg CONFIRM}}}
{text
Returns from Raid, flushing computation to top level.  This is similar, but not identical to the Interlisp-D control-D interrupt.  It clears all stack pointers.  This cannot be done when interrupts are off (e.g. if one entered Raid by typing control-C and Raid's message includes "Warning: interrupts off"), as the world might be left in an inconsistent state.
}

{label control-F {bracket {arg ONUM}}}
{text
Displays the basic stack frame at stack offset {arg ONUM}.
}

{label control-K {bracket {arg CONFIRM}}}
{text
Kills Interlisp-D and returns to the Exec.  The virtual memory image on the disk will probably not be resumable.
}

{label control-N}
{text
Returns from Raid, resuming the Interlisp-D computation with {lisp NIL} as the value of the call on Raid.
}

{label control-S {bracket {arg CONFIRM}}}
{text
Calls Swat (the Bcpl debugger).
}

{label control-T}
{text
Returns from Raid, resuming the Interlisp-D computation with {lisp T} as the value of the call on Raid.
}

{label control-U}
{text
Displays the Interlisp-D screen in place of the Raid screen.  The display will remain coupled to the Interlisp-D display until any character is typed.
}

{label control-V {bracket {arg ATOM}}}
{text
Sets the top-level value of the specified atom to {lisp NIL}.  This should be used only as a last resort, since it is {it NOT} completely equivalent to
{lisp (SETTOPVAL '{arg ATOM} NIL)}, and, of course, it is not undoable.
}

{label control-X {bracket {arg ONUM}}}
{text
Displays the frame extension at stack offset {arg ONUM}.
}

{label {lisp +} {bracket {arg ONUM}, {arg ONUM}}}
{text
Adds the two octal numbers and displays the result in octal.
}

{label {lisp ,} {bracket {arg ONUM}, {arg ONUM}}}
{text
Displays a 16-bit word whose bytes are the {arg ONUM}s.
}

{label {lisp ←} {bracket {arg ADDRESS}, {arg ONUM}}}
{text
Sets the contents of the 16-bit word at {arg ADDRESS} to {arg ONUM}.
}

{label {lisp ?}}
{Text
Displays a command summary.
}

{label {lisp A} {bracket {arg ATOM}}}
{Text
Displays the top level value of {arg ATOM}.
}

{label {lisp B} {bracket {arg ADDRESS}, {arg ONUM}}}
{text
Displays the contents of the cells starting at {arg ADDRESS} and proceeding for {arg ONUM} words.
}

{label {lisp C}}
{text
Displays a count, by segment, of how many virtual pages are resident, plus some summary information.
}

{label {lisp D} {bracket {arg ATOM}}}
{Text
Displays definition cell of {arg ATOM}.
}

{label {lisp E}}
{Text
Reprints the error message and object on which Raid was called.
}

{label {lisp F} {bracket {arg DNUM}, {lisp A} or {lisp C} if the access and control links differ}}
{Text
Displays the basic frame and extension for the function activation which is dnum deep along either the stack's access or control links, as specified by {lisp A} or {lisp C}.  Thus, {lisp F3 A} displays the basic frame for the third function call along the access chain from the top level.  {arg DNUM} can most easily be ascertained by displaying the stack entries using {lisp L}.
}

{label {lisp J} {bracket {arg DNUM}}}
{Text
Sets the maximum length of the list Raid will print before abbreviating the tail.
}

{label {lisp L} {bracket {lisp A} or {lisp C} if the access and control links differ}}
{text
Displays the Interlisp-D stack, one line per function.  {lisp LA} follows the access links; {lisp LC} follows the control links.  The frames can be examined in more detail using {lisp F}.
}

{label {lisp N} {bracket {arg DNUM}}}
{Text
Sets the maximum depth to which Raid will recurse while printing list structure before abbreviating.
}

{label {lisp P} {bracket {arg ATOM}}}
{text
Displays the property list of {arg ATOM}.
}

{label {lisp S} {bracket {arg onum1}, {arg onum2}}}
{text
Displays {arg onum2} words from the stack starting at offset {arg onum1}.
}

{label {lisp U} {bracket {arg DNUM}}}
{text
Sets the radix in which Raid displays numeric Interlisp-D data items to {arg DNUM}.
}

{label {lisp V} {bracket {arg ADDRESS}}}
{text
Displays the contents of the virtual address as a Interlisp-D object.
}

{End LabeledList}

}{End SubSec Commands}


}{End SubSec Using RAID}

}{End SubSec RAID}



{Begin SubSec SWAT}
{Title SWAT}
{Text

{index Swat}

{Tag Swat}

Swat is the debugger for Bcpl, the language in which Raid and some of the Interlisp-D system primitives are written.  Swat is entered as a result of an unexpected error condition arising in the Bcpl, and generally indicates that the Lisp world is in very bad shape.

When the system is in Swat, the Swat screen is displayed,
with the prompt {lisp #}.  To display the Interlisp-D screen, type control-U.  That will restore the Interlisp-D screen until the {lisp SWAT} key (the lowest of the three blank keys on the right side of the keyboard) is depressed.

If the system goes into Swat, the Interlisp-D image probably cannot be continued, at least not for long, but a salvage attempt can be tried by typing {lisp RAID}control-C.  This invokes Raid, from which the stack can be examined, and control-D can be tried to reset the system.  If the situation is beyond repair, type control-K to kill the program and return to the Executive. 

Swat can also be entered from Raid via the control-S command, in which case type control-P to return to Raid.

In some circumstances, the Lisp system may appear dead; control-C does not call Raid, but the cursor still tracks the mouse.  In this case, the system state can perhaps be saved by deliberately invoking Swat by typing {lisp CTRL-SHIFT-SWAT}.  Once inside Swat, type {lisp RAID}control-C to get into Raid and proceed as above.

It is possible that Swat will respond to an attempt to call Raid (using {lisp RAID}control-C) with the message "Stack dubious. Do you want to proceed with the call?".  Respond with {lisp N} (for No!).  Next, type "{lisp TOPLEVELFRAME}control-O"; this prints a number; then type "{lisp AC2}control-O{arg NNNN}{lisp {crsymbol}}", where {arg NNNN} is the number printed in the previous step.  Finally, try to call Raid again.

The very first time Swat is entered, load the symbol file.  The symbol file name is shown in the lower Swat window.  If it is not "Lisp.syms," type control-Y{lisp Lisp{crsymbol}} to load the correct file.

}{End SubSec SWAT}