perm filename BAIL.DOC[DOC,AIL]14 blob sn#506541 filedate 1980-05-01 generic text, type C, neo UTF8
COMMENT ⊗   VALID 00032 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00006 00002
C00008 00003	BAIL -- A debugger for SAIL                         TABLE OF CONTENTS
C00012 00004	BAIL -- A debugger for SAIL                              INTRODUCTION
C00017 00005	BAIL -- A debugger for SAIL                              INTRODUCTION
C00022 00006	BAIL -- A debugger for SAIL                              INTRODUCTION
C00025 00007	BAIL -- A debugger for SAIL                                  EXAMPLES
C00027 00008	BAIL -- A debugger for SAIL                                  EXAMPLES
C00028 00009	BAIL -- A debugger for SAIL                                  EXAMPLES
C00031 00010	BAIL -- A debugger for SAIL                                  EXAMPLES
C00033 00011	BAIL -- A debugger for SAIL                                  EXAMPLES
C00036 00012	BAIL -- A debugger for SAIL                                  EXAMPLES
C00038 00013	BAIL -- A debugger for SAIL                                  EXAMPLES
C00041 00014	BAIL -- A debugger for SAIL                                  EXAMPLES
C00042 00015	BAIL -- A debugger for SAIL                                  EXAMPLES
C00044 00016	BAIL -- A debugger for SAIL                                  EXAMPLES
C00046 00017	BAIL -- A debugger for SAIL                                  EXAMPLES
C00048 00018	BAIL -- A debugger for SAIL                       COMPILE-TIME ACTION
C00052 00019	BAIL -- A debugger for SAIL                       COMPILE-TIME ACTION
C00057 00020	BAIL -- A debugger for SAIL                           RUN-TIME ACTION
C00061 00021	BAIL -- A debugger for SAIL                           RUN-TIME ACTION
C00065 00022	BAIL -- A debugger for SAIL                           RUN-TIME ACTION
C00067 00023	BAIL -- A debugger for SAIL                           RUN-TIME ACTION
C00070 00024	BAIL -- A debugger for SAIL                           RUN-TIME ACTION
C00072 00025	BAIL -- A debugger for SAIL                           RUN-TIME ACTION
C00075 00026	BAIL -- A debugger for SAIL                           RUN-TIME ACTION
C00078 00027	BAIL -- A debugger for SAIL                           RUN-TIME ACTION
C00081 00028	BAIL -- A debugger for SAIL                            RESOURCES USED
C00084 00029	BAIL -- A debugger for SAIL                            CURRENT STATUS
C00087 00030	BAIL -- A debugger for SAIL                            CURRENT STATUS
C00090 00031	BAIL -- A debugger for SAIL                            CURRENT STATUS
C00092 00032	What does pdl ov as an error message mean??? f pdl ov on this file yields zilch!!
C00093 ENDMK
C⊗;



                     BAIL -- A debugger for SAIL



                           John F. Reiser
                     Computer Science Department
                         Stanford University


                            February 1976










                              ABSTRACT

BAIL is a debugging aid for SAIL programs, where SAIL is  an extended
dialect of ALGOL60 which runs on the PDP-10 computer.   BAIL consists
of a breakpoint package and an expression interpreter which allow the
user to stop his program  at selected points, examine and  change the
values  of  variables,  and evaluate  general  SAIL  expressions.  In
addition, BAIL can display text from the source file corresponding to
the current location  in the program.  In  may respects BAIL  is like
DDT or  RAID, except  that BAIL  is oriented  towards SAIL  and knows
about   SAIL  data   types,  primitive   operations,   and  procedure
implementation.







This  work was  supported in  part by  a National  Science Foundation
graduate  fellowship.   Computer  facilities  provided   by  Stanford
Artificial Intelligence Laboratory and by Institute  for Mathematical
Studies in the Social Sciences, Stanford.
BAIL -- A debugger for SAIL                         TABLE OF CONTENTS


  
                  T A B L E   O F   C O N T E N T S
                  _ _ _ _ _   _ _   _ _ _ _ _ _ _ _



SECTION                                                          PAGE


1    INTRODUCTION                                                   1


2    EXAMPLES                                                       4


3    COMPILE-TIME ACTION                                           15


4    RUN-TIME ACTION                                               17

     1    Debugging Requests                                       17
     2    ARGS                                                     18
     3    BREAK                                                    18
     4    COORD                                                    19
     5    DDT                                                      19
     6    HELP                                                     19
     7    SETLEX                                                   19
     8    SHOW                                                     20
     9    TEXT                                                     20
     10   TRACE                                                    20
     11   TRAPS                                                    21
     12   UNBREAK                                                  21
     13   UNTRACE                                                  21
     14   !!GO                                                     21
     15   !!GSTEP                                                  21
     16   !!STEP                                                   22
     17   GOGTAB                                                   22
     18   STRING TYPEOUT                                           22
     19   BAIL and DDT                                             22
     20   WARNINGS                                                 23
     21   FOR WIZARDS ONLY                                         24

5    RESOURCES USED                                                25


6    CURRENT STATUS                                                26
BAIL -- A debugger for SAIL                              INTRODUCTION


                             SECTION  1
                             _______  _

                            INTRODUCTION
                            ____________




The ideal way to debug a computer program is to write it correctly in
the  first place  and not  debug it  at all.   Experience  has shown,
however, that most programs of moderate size contain errors, and that
debugging is  a significant part of  software production.  BAIL  is a
tool  which is  designed to  be useful  for interactive  debugging of
programs written in SAIL  [4], a high-level ALGOL-based  language for
Digital Equipment Corporation (DEC) PDP-10 computers.

In  the very  early days  of  computing, debugging  was  done at  the
console  of  the  computer.    The  programmer manipulated  switches,
observed lights, and had complete control of the whole machine.   The
programmer could examine and change  any location in memory and could
start,  stop, and single-step the processor.   Console debugging soon
became uneconomical on medium and large-scale machines.   It is still
used on  minicomputers.   This type of  debugging is at  the machine-
language level; the lights and switches are direct representations of
bits inside the machine.

Debugging moved to  the assembly language level with  the development
of  interactive  time-sharing  systems  in  the  early 1960's.    The
programmer typed commands at a terminal, and a collection  of special
subroutines interpreted the  commands so that the  effect was similar
to  working at the console of the  machine.  Instead of communicating
in bits, the programmer and subroutines used character strings in the
format  of  octal   and  decimal  integers,  text,  symbolic  machine
instructions, and  symbolic addresses.   One  of the  most  important
features of  the debugging routines  was the  ability to suspend  the
execution  of   the  program  being  debugged,  enter  the  debugging
routines, communicate with the programmer, resume execution, and make
the  whole process  invisible to  the program  being debugged.   This
process  became known as  breakpointing; the location  where the main
program was stopped is  a breakpoint, and the debugging  routines are
called  a breakpoint  package.   The  premier example  of  a symbolic
debugging package is DDT [1], developed for use on the DEC PDP-1  and
subsequently extended for use  on the PDP-6 and PDP-10.   DDT and its
derivatives  are still  among the most  powerful tools  for debugging
assembly language programs.

BAIL is a high-level breakpoint package for  use with  SAIL programs.
(Swinehart  [3] and Satterthwaite  [2] contain  descriptions of other


                                  1
BAIL -- A debugger for SAIL                              INTRODUCTION


high-level debugging systems.)  Communication between the  programmer
and BAIL  is in character strings  which are the names  and values of
SAIL  objects.   BAIL  reads general  SAIL  expressions typed  by the
programmer, evaluates them in the context of the place in the program
where execution  was suspended, and prints the  resulting value in an
appropriate format.  The  evaluation and printing are  performed just
as  if the  programmer  had  inserted  an extra  statement  into  the
original  program at the point  where execution was  suspended.  BAIL
also provides  a  way  to  talk  about the  program,  to  answer  the
questions  "Where  was  execution  suspended?",  "By  what  chain  of
procedure  calls did execution proceed to  that point?", and "What is
the text of the program?"

In order to perform these functions, BAIL  must have some information
about  the program being  debugged.   The SAIL compiler  will produce
this information if the program is compiled with an appropriate value
supplied for the /B switch.  (See the technical portion of the manual
for  the  exact  meaning  of the  various  switch  values.)  In these
examples the compiler produces two files.  File PROG.REL contains the
relocatable code and  loader instructions, and file PROG.SM1 contains
the information for BAIL.   The PROG.SM1 information consists of  the
name,  type,  and   accessing  information  for  each   variable  and
procedure, the  location of the beginning and  end of each statement,
and a description of the block structure.

The code for BAIL itself is loaded  automatically when the program is
loaded.   In  order  for the  added  information and  code  to  be of
any  use,  it  must be  possible  to   give control  to  BAIL  at the
appropriate  time.    An  explicit  call   to  BAIL   is  possible by
declaring EXTERNAL  PROCEDURE  BAIL;  in the   program and  using the
procedure call  BAIL;.  This  works well  if it  can be  predicted in
advance  where BAILing  might be  helpful.  Runtime  errors,  such as
subscript overflow or CASE index errors, are not as  predictable; but
responding  "B"  to  the SAIL   error  handler  will   activate BAIL.
Interrupting  the  program  while it   is running  (to  investigate a
possible infinite loop, for example) can be achieved under  the TENEX
operating system  by typing control-B.    On a DEC  TOPS-10 operating
system, first  return to monitor mode by typing one or  more control-
C's, then activate BAIL by typing DD<cr>.

BAIL performs some initialization the first time  it is entered.  The
information  in the .SM1  file(s) is  collected and processed  into a
file PROG.BAI.  This  new file reflects  all of the information  from
the  .SM1   files  of  any  separately-compiled   programs,  and  the
relocation  performed by the loader.  If  the core image was SAVEd or
SSAVEd then in subsequent runs BAIL will use the .BAI file and bypass
much of the initialization.


                                  2
BAIL -- A debugger for SAIL                              INTRODUCTION


BAIL prompts the programmer for input by typing a number and a colon.
The number indicates how many times BAIL has been entered but not yet
exited, and thus is the recursion  depth inside BAIL.  Input to  BAIL
can be  edited using the  standard SAIL input-editing  characters for
the  particular operating system under which  the program is running.
[BAIL requests input via INCHWL on DEC TOPS-10 systems  and via INTTY
on TENEX systems.] Input is terminated whenever the editor activates,
string  quotation  marks  balance,  and  the  last  character  is   a
semicolon; otherwise  input lines  are concatenated  into one  string
before being processed further.

The  programmer may  ask  BAIL to  evaluate  any SAIL  expression  or
procedure call whose  evaluation would be legal at the point at which
execution of the  program being debugged  was suspended (except  that
expressions  involving  AND,  OR,  IF-THEN-ELSE,  and  CASE  are  not
allowed.)  BAIL evaluates the expression,  prints the resulting value
in an appropriate format, and requests further input.

Declared inside  BAIL  are several  procedures whose  values or  side
effects are useful in the debugging process.  These procedures handle
the insertion  and deletion of  breakpoints, display  the static  and
dynamic scope of the  current breakpoint, display selected statements
from  the  source  program, allow  escape  to  an  assembly- language
debugging  program,  and  cause  resumption  of  the  suspended  main
program.  These procedures are described in the technical  portion of
the manual.

The following examples illustrate  many of the features  available in
BAIL.  Text was recorded from an actual session on the computer.




















                                  3
BAIL -- A debugger for SAIL                                  EXAMPLES


                             SECTION  2
                             _______  _

                              EXAMPLES
                              ________




                                 This  is  a  test  program,  run  on
                                 TENEX.
@TYPE TEST1.SAI

;  <REISER>TEST1.SAI;1   SAT 10-MAY-75 2:37PM         PAGE 1


BEGIN "TEST"
EXTERNAL PROCEDURE BAIL;

INTEGER I,J,K;
STRING A,B,C;
REAL X,Y,Z;
INTEGER ARRAY FOO[0:15]; STRING ARRAY STRARR[1:5,2:6];
INTEGER ITEMVAR DAY; ITEMVAR QQ;

INTEGER PROCEDURE ADD(INTEGER I,J); BEGIN "ADD"
OUTSTR("
HI. GLAD YOU STOPPED BY."); RETURN(I+J) END "ADD";

RECURSIVE INTEGER PROCEDURE FACT(INTEGER N); BEGIN "FACT"
RETURN(IF N LEQ 1 THEN 1 ELSE N*FACT(N-1)) END "FACT";

SIMPLE PROCEDURE SIMPROC(REFERENCE INTEGER M); BEGIN "SBEG"
ADD(M,M←32) END "SBEG";

FOR I←0 STEP 1 UNTIL 15 DO FOO[I]←I*I;
FOR I←1 STEP 1 UNTIL 5 DO
    FOR J←2 STEP 1 UNTIL 6 DO
        STRARR[I,J]←64+8*I+J;
I←4; J←6; K←112;
A←"BIG DEAL"; B←"QED"; C←"THE LAST PICASSO";

X←3.14159265; Y←0; Z←23.;

BAIL;

ADD(7,45);
SIMPROC(J);

USERERR(0,1,"THIS IS A TEST");

                                  4
BAIL -- A debugger for SAIL                                  EXAMPLES


END "TEST";
↑L















































                                  5
BAIL -- A debugger for SAIL                                  EXAMPLES


                                 Compile and load with BAIL.
@SAIL.SAV;10
 TENEX SAIL 8.1 4-4-75  (? FOR HELP)
*TEST1,←
**/27B
**
TEST1.SAI;1 1
END OF COMPILATION.
LOADING

LOADER 6+9K CORE
EXECUTION

↑C

                                 Save the core image for later use.
@SSAVE (PAGES FROM) 0 (TO) 577 (ON) TEST1 [NEW FILE]
 [CONFIRM]

                                 Start the program.
@START

                                 BAIL identifies itself and the files
                                 involved.
BAIL VER. 10-MAY-75
TEST1.SM1;2
  TEST1.SAI;1
End of BAIL initialization.

1:45;

                                 The  "1:"  is  BAIL's   prompt.   It
                                 indicates  the  level  of  recursive
                                 invocations  of  BAIL  and  the fact
                                 that BAIL is awaiting input.

                                 See  how constants  are  entered and
                                 printed.  The "45;<cr>" is  typed by
                                 the user, and the next line  "45" is
                                 BAIL's reply.
   45
1:7.089;
    7.089000
1:"SOME RANDOM STRING";
   "SOME RANDOM STRING"

                                 An octal  constant; all  printout is
                                 decimal.

                                  6
BAIL -- A debugger for SAIL                                  EXAMPLES


1:'275;
   189

                                 Symbolic  constants  More  than  one
                                 expression requested
1:TRUE,FALSE,NULL;
   -1   0   ""

                                 Variables, assignment
1:I;
   4
1:J,X;
   6    3.141593
1:I←46;
   46
1:I;
   46

                                 Relational operators; remember  0 is
                                 FALSE.
1:I<J;
   0
1:I GEQ J;
   -1
1:98 LAND '17;
   2

                                 An undeclared identifier
1:XYZ;

UNKNOWN ID:  XYZ
                ;

                                 Usable as a desk calculator
1:45*(89.4-53.06);
    1635.300
1:X+J;
    9.141593

                                 Procedure call
1:ADD(3,4);

HI. GLAD YOU STOPPED BY.   7

                                 Argument list checking
1:ADD(3);

ADD TAKES 2 ARGUMENTS.:  ADD(3)

                                  7
BAIL -- A debugger for SAIL                                  EXAMPLES


                               ;

                                 Arrays.    Array  name   only  gives
                                 dimension   and   subscript   bounds
                                 information.
1:FOO;
   <ARRAY>[ 0:15]
1:FOO[4];
   16

                                 Substring notation has been extended
                                 to cover array elements.
1:FOO[5 FOR 3];
   25   36   49
1:STRARR;
   <ARRAY>[ 1:5 2:6]
1:STRARR[1 FOR 2, 4 TO 6];
   "L"   "M"   "N"   "T"   "U"   "V"

                                 Array accesses are interpreted
1:FOO[35];

SUBSCRIPTING ERROR.   INDEX    VALUE    MIN    MAX
                        1       35      0       15      :  FOO[35]
                                                                  ;

                                 LENGTH, LOCATION, and MEMORY
1:A;
   "BIG DEAL"
1:LENGTH(A);
   8
1:I;
   46
1:LOCATION(I);
   718
1:MEMORY[718]←64;
   64
1:I;
   64

                                 Substringing
1:A[2 TO INF];
   "IG DEAL"
1:B[3 TO 4];
   "D"

                                 Type-in  must  be  terminated  by  a
                                 semicolon

                                  8
BAIL -- A debugger for SAIL                                  EXAMPLES


1:B
;
   "QED"

                                 Tracing of procedure entry and exit
1:TRACE("FACT");

1:FACT(4);

 ENTERING FACT   4
  ENTERING FACT   3
   ENTERING FACT   2
    ENTERING FACT   1
    EXITING FACT=   1

   EXITING FACT=   2

  EXITING FACT=   6

 EXITING FACT=   24
   24
1:UNTRACE("FACT");

1:FACT(5);
   120

                                 Breakpointing
1:BREAK("ADD");

1:ADD(3,4);

                                 Now   one  level   deeper   in  BAIL
                                 recursion.     ARGS    prints    the
                                 arguments list.
2:ARGS;
   3   4

                                 Parameter  names evaluate  just like
                                 variables.
2:I;
   3
2:J;
   4
2:K;
   112

                                 To exit from one level of BAIL
2:!!GO;

                                  9
BAIL -- A debugger for SAIL                                  EXAMPLES


HI. GLAD YOU STOPPED BY.   7

                                 The message is from ADD  itself; the
                                 value 7 is from BAIL.

                                 Leave another level of BAIL.
1:!!GO;

                                 And come back again.  Where are we?
1:TEXT;

                                 Static block structure
LEXICAL SCOPE, TOP DOWN:
$RUN$
TEST
ADD

                                 Dynamic procedure  invocations.  The
                                 #4 means coordinate number 4.
DYNAMIC SCOPE, MOST RECENT FIRST:
ROUTINE         TEXT
ADD     #4      INTEGER PROCEDURE ADD(INTEGER I,J); BEGI
TEST    #24     ADD(7,45);
SIMPROC(J);

USERERR(0,1,"

1:ARGS;
   7   45

                                 Remove the breakpoint.
1:UNBREAK("ADD");

1:!!GO;

                                 Output  from  other  calls   in  the
                                 program
HI. GLAD YOU STOPPED BY.
HI. GLAD YOU STOPPED BY.
THIS IS A TEST
CALLED FROM 642124  LAST SAIL CALL AT 400303
↑B

                                 Entry to BAIL from the error handler
1:TEXT;

LEXICAL SCOPE, TOP DOWN:
$RUN$

                                 10
BAIL -- A debugger for SAIL                                  EXAMPLES


DYNAMIC SCOPE, MOST RECENT FIRST:
ROUTINE         TEXT
.SIMPLE.        '642124 %%% FILE NOT VIEWABLE
TEST    #26     USERERR(0,1,"THIS IS A TEST");

END "T

1:I;

UNKNOWN ID:  I
              ;

                                 The  static  scope needs  to  be set
                                 back one on the dynamic chain.
1:SETLEX(1);

LEXICAL SCOPE, TOP DOWN:
$RUN$
TEST

1:I;
   64
1:C;
   "THE LAST PICASSO"
1:!!GO;

END OF SAIL EXECUTION.






















                                 11
BAIL -- A debugger for SAIL                                  EXAMPLES


                                 Leap   and   records,   DEC  TOPS-10
                                 system.

.TYPE TEST2.SAI

BEGIN "TEST"
EXTERNAL PROCEDURE BAIL;
REQUIRE 500 SYSTEM!PDL, 10 PNAMES;

LIST L; SET S,S1,S2,S3,S4,S5;
INTEGER ITEM SUNDAY; ITEM MONDAY,TUESDAY,WEDNESDAY,THURSDAY,FRIDAY,
        SATURDAY;
INTEGER ITEMVAR DAY; ITEMVAR QQ;
ITEMVAR ARRAY P[1:10];

RECORD!CLASS CELL (RECORD!POINTER(CELL) CAR,CDR);
RECORD!POINTER(CELL) CX,CY;

CX←NEW!RECORD(CELL);
CY←NEW!RECORD(CELL);
CELL:CAR[CX]←NULL!RECORD; CELL:CDR[CX]←NULL!RECORD;
CELL:CAR[CY]←CX; CELL:CDR[CY]←NULL!RECORD;

P[1]←SUNDAY; P[2]←MONDAY;
L←{{SUNDAY}}; DATUM(SUNDAY)←0; DAY←SUNDAY;  QQ←MONDAY; S←{QQ};
S1←{SUNDAY,MONDAY,TUESDAY,WEDNESDAY,THURSDAY,FRIDAY,SATURDAY};
S2←{MONDAY,TUESDAY,WEDNESDAY,THURSDAY,FRIDAY};
S3←{MONDAY,WEDNESDAY,FRIDAY}; S4←{SATURDAY,SUNDAY};
S5←{SUNDAY,FRIDAY};

FOREACH DAY SUCH THAT DAY IN S1 DO MAKE DAY XOR SUNDAY EQV SATURDAY;

BAIL;

USERERR(0,1,"THIS IS A TEST");

END "TEST";


EXIT
↑C
.EXECUTE TEST2.SAI(27B,)
SAIL: TEST2  1
LOADING
LOADER 15K CORE
25K MAX 153 WORDS FREE
EXECUTION


                                 12
BAIL -- A debugger for SAIL                                  EXAMPLES


BAIL VER. 10-MAY-75
TEST2.SM1
  TEST2.SAI
END OF BAIL INITIALIZATION.

1:L;
   {{SUNDAY}}
1:S4;
   {SUNDAY, SATURDAY}
1:S5;
   {SUNDAY, FRIDAY}
1:S4 UNION S5;
   {SUNDAY, FRIDAY, SATURDAY}
1:FRIDAY IN S4;
   0
1:S2 LEQ S2;
   -1
1:DAY;
   SATURDAY
1:DATUM(DAY);
   0
1:CX;
   CELL.9231
1:CELL:CAR[CX];
   NULL!RECORD
1:CELL:CAR[CY];
   CELL.9231
1:SUNDAY ASSOC SATURDAY;
   {SUNDAY}
1:SUNDAY EQV SATURDAY;
   {SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY}
1:SUNDAY XOR SATURDAY;
   PHI
1:SUNDAY EQV SUNDAY;
   PHI
1:↑C













                                 13
BAIL -- A debugger for SAIL                                  EXAMPLES


                                 Go back to the earlier example
@TEST1.SAV;1

                                 Initialization  uses   file  created
                                 last time.
BAIL ver. 10-May-75 using TEST1.BAI
End of BAIL initialization.

                                 Switch  /27B  at  compile-time makes
                                 SAIL  predeclared  runtime  routines
                                 known to BAIL.
1:OPENFILE(NULL,"W");
TODAY.TMP
   4
1:OUT(4,"THIS IS A TEMPORARY FILE CREATED WHILE IN BAIL.");

1:CFILE(4);
   -1
1:OPENFILE("","RC");
TODAY.TMP [OLD VERSION]
   4
1:SINI(4,200,"Z");
   "THIS IS A TEMPORARY FILE CREATED WHILE IN BAIL."
1:ODTIM(-1,-1);
   "SATURDAY, MAY 10, 1975 17:19:29"

                                 Quickie review of BAIL capabilities
1:?

EXPRESSION;
PROCEDURE!CALL;
TRACE("PROCEDURE");
UNTRACE("PROCEDURE");
BREAK("PROCEDURE, BLOCK, OR LABEL");
UNBREAK("PROCEDURE, BLOCK, OR LABEL");
!!GO;
SETLEX(LEVEL);
TEXT;
ARGS;
HELP;
DDT;
?

1:↑C

                                 End of the examples.



                                 14
BAIL -- A debugger for SAIL                       COMPILE-TIME ACTION


                             SECTION  3
                             _______  _

                         COMPILE-TIME ACTION
                         ____________ ______




The  principal  result  of activating  BAIL  at  compile-time  is the
generation of a file of information about the source program  for use
by the run-time interpreter.  This file has the same name as the .REL
file produced by the compilation, except that the extension  is .SM1.
If requested, BAIL will also generate some additional code for SIMPLE
procedures to make them more palatable to the run-time interpreter.

The action of BAIL at compile time is governed by the value of the /B
switch passed to the compiler.   If the value of this switch  is zero
(the  default  if no  value  is specified)  then  BAIL  is completely
inactive.  Otherwise, the low-order bits determine the  actions which
BAIL performs.  [The value of the /B switch is interpreted as octal.]

bit  action

1    If this bit is on,  then the .SM1 file will contain  the program
     counter to source/listing text directory.

2    If  this bit  is  on, then  the  .SM1 file  will  contain symbol
     information for all SAIL symbols encountered in the  source.  If
     this bit is off,  then information is kept only  for procedures,
     parameters,  blocks, and  internals; i.e.,  non-  internal local
     variables are not recorded.

4    If this  bit is  on, then SIMPLE  procedures will  get procedure
     descriptors, and one additional instruction (a JFCL 0,  which is
     the  fastest  machine  no-op  instruction)  is  inserted  at the
     beginning of SIMPLE  procedures.  Except for these  two changes,
     all properties of SIMPLE  procedures remain the same  as before.
     The procedure descriptor is necessary if the procedure is  to be
     called interpretively or if the procedure is to be TRACEd.

'10  If this bit  is on, then BAIL  will not be  automatically loaded
     and  initialized,  although  all  other  actions  requested  are
     performed.   This is  primarily intended  to make  it  easier to
     debug   new   versions   of   BAIL   without   interfering  with
     SYS:BAIL.REL.  By using this switch the decision to load BAIL is
     delayed until load time.

'20  If this  bit is  on, then  a request  to load  SYS:BAIPDn.REL is


                                 15
BAIL -- A debugger for SAIL                       COMPILE-TIME ACTION


     generated.   This  file  contains  requests  to  load  procedure
     descriptors for most of the predeclared runtime routines, making
     it possible to call  them from BAIL.  The  procedure descriptors
     and their  symbols occupy about  6K. Subsets of  these procedure
     descriptors can  be loaded individually  to reduce  memory space
     requirements, at the  cost of not being  able to talk  about the
     routines omitted.  The subsets are BAICLC (containing SQRT, EXP,
     LOG,  SIN,  COS,  RAN,  CVOS,  CVSTR,  CVXSTR),   BAIIO1  (major
     input/output and string procedures), BAIIO2  (minor input/output
     and   string   procedures),  BAIMSC   (terminal   functions  and
     miscellaneous), and BAIPRC (process and interrupt routines).  To
     use  these  subsets,  request  them  explicitly  (e.g.,  REQUIRE
     "SYS:BAICLC" LOAD!MODULE; or on TENEX, "<SAIL>BAICLC") and leave
     the /20B bit off.

The B switch must occur on the binary term, not the listing or source
term.  Thus:
        .R SAIL                 or      .COM PROG(27B,)
        *PROG/27B←PROG

The  program counter  to  source/listing index  is kept  in  terms of
coordinates.  The  coordinate counter is  zeroed at the  beginning of
the compilation and is incremented  by one for each BEGIN,  ELSE, and
semicolon seen by the parser, provided at least one word of  code has
been compiled since the  previous coordinate was defined.   Note that
COMMENTs  are seen  only by  the scanner,  not the  parser,  and that
DEFINEs and many declarations merely define symbols and do  not cause
instructions  to be  generated.   For each  coordinate  the directory
contains the coordinate number, the value of the program counter, and
a file pointer  to the appropriate  place.  The appropriate  place is
the source file unless a listing file is being produced and  the CREF
switch is off,  in which case it  is the listing file.   [The listing
file produced for CREF is nearly unreadable.] On a  non-CREF listing,
the program counter is replaced by the coordinate number if bit  1 of
the /B switch is on.

The symbol table information consists of the block structure  and the
name, access information, and type for each symbol.

If a BEGIN-END pair has  declarations (i.e., is a true block  and not
just a compound statement) but  does not have a name, then  BAIL will
invent one.  The name is of the form Bnnnn where nnnn is  the decimal
value of the current coordinate.






                                 16
BAIL -- A debugger for SAIL                           RUN-TIME ACTION


                             SECTION  4
                             _______  _

                           RUN-TIME ACTION
                           ________ ______




The BAIL run-time interpreter is itself a SAIL program  which resides
on  the   system  disk   area.   This   program  is   usually  loaded
automatically,  and does  some  initialization when  entered  for the
first time. The initialization  generates a .BAI file  of information
collected from the .SM1  files produced by separate  compilations (if
any).  The  .SM1 files correspond  to .REL files,  and the  .BAI file
corresponds to the .DMP or .SAV file.  Like RPG or CCL, BAIL will try
to bypass much of the initialization and use an existing .BAI file if
appropriate.  During  initialization BAIL displays  the names  of the
.SM1  files it  is  processing.  For  each .SM1  file  which contains
program counter/text  index information, BAIL  displays the  names of
the text files and determines whether the text files are accessible.

The interpreter  is activated by  explicit call,  previously inserted
breakpoints, or the  SAIL error handler.   For an explicit  call, say
EXTERNAL PROCEDURE BAIL; ... BAIL;.  From the error  handler, respond
B.  Breakpoints will be described later in this section.



4.1 - Debugging Requests
      _________ ________


When entered, BAIL prints the debugging recursion level followed by a
colon, and awaits a  debugging request.  BAIL accepts ALGOL  and LEAP
expressions of the SAIL language.  A complete description is given in
[4] and in the addenda  describing the syntax of records  and record-
pointers.  The  following exceptions  should  be  noted.  Expressions
involving  control structure  are not  allowed, hence  BAIL  will not
recognize AND, OR, IF-THEN-ELSE, or CASE.  Bracketed triple items are
not allowed.   The TO  and FOR substring  and sublist  operators have
been extended  to operate  as array  subscript ranges,  FOR PRINT-OUT
ONLY.  If FOO is  an array, then FOO[3  TO 7]; will act  like FOO[3],
FOO[4],  FOO[5],  FOO[6],  FOO[7];  but  is  easier  to  type.   This
extension is for print-out  only; no general APL syntax  or semantics
are provided.

BAIL evaluates symbolic names according to the scope rules  of ALGOL,
extended to always recognize names which are globally unique and have


                                 17
BAIL -- A debugger for SAIL                           RUN-TIME ACTION


a fixed memory  location (everything except parameters  and recursive
locals).  For any activation of BAIL, the initial scope is  the ALGOL
scope of the statement from which BAIL was activated.   The procedure
SETLEX (see below) may be used to change the scope to that of any one
of the links in the dynamic activation chain.

Several procedures are predeclared  in the outermost block  to handle
breakpoints   and   display   information.    These   are   described
individually below.



4.2 - ARGS
      ____

STRING PROCEDURE ARGS;

The arguments to the procedure which was most recently called.



4.3 - BREAK
      _____

PROCEDURE BREAK("location","condition"(NULL),"action"(NULL),count(0))

BREAK inserts a breakpoint.  The syntax for the first argument is
        <location>::=<label>|<procedure>|<block name>|#<nnnn>
                        |<block name><delim><location>
        <delim>::=<any character not legal in an identifier>
        <nnnn>::=<decimal coordinate number>

If  the location  is specified  by the  <block name><delim><location>
construct then the blocks of the core image are searched in ascending
order of address of BEGINs  until the first <block name>  is matched.
The search continues until  the second <block name> is  matched, etc.
The breakpoint  is inserted  at the  label, procedure,  or coordinate
declared within the  scope of the  last <block name>.   This detailed
specification is  not usually  necessary, as  shown in  the examples.
The last three parameters are defaultable and need not  be specified,
again as in the examples.  The action taken at a breakpoint is

    IF LENGTH(condition) AND EVAL(condition) AND (count←count-1)<0 AN
        LENGTH(action) THEN EVAL(action);
    EVAL(TTY);

Here  EVAL is  a procedure  which evaluates  its string  argument and


                                 18
BAIL -- A debugger for SAIL                           RUN-TIME ACTION


returns the value of the last expression evaluated (similar  to PROGN
in LISP).



4.4 - COORD
      _____

INTEGER PROCEDURE COORD(STRING LOCATION);

Returns the coordinate number of the location given as  its argument.
LOCATION has the same syntax as in BREAK.



4.5 - DDT
      ___

PROCEDURE DDT;

This procedure  transfers control to  an assembly  language debugging
program (if one was loaded).



4.6 - HELP
      ____

PROCEDURE HELP;

A list  of options,  including short  descriptions of  the procedures
described in this section, is printed.  A question mark followed by a
carriage return is interpreted as a call to HELP.



4.7 - SETLEX
      ______

PROCEDURE SETLEX(level);

Evaluating SETLEX(n) changes the static (lexical) scope to  the scope
of the n-th entry in the dynamic scope list.  SETLEX(0) is  the scope
of  the  breakpoint;  SETLEX(1)  is  the  scope  of  the  most recent
procedure call in the dynamic scope, etc.



                                 19
BAIL -- A debugger for SAIL                           RUN-TIME ACTION


4.8 - SHOW
      ____

STRING PROCEDURE SHOW(first, last(0));

The text of the program from the source or listing file.  If  last is
less  than first  then set  last to  last+first.   Return coordinates
first  through last.   SHOW(5,3) gives  coordinates 5,  6, 7,  and 8;
SHOW(5,7) gives coordinates 5,  6, and 7; SHOW(5) gives  coordinate 5
only.

A plus sign ("+") following the coordinate number indicates  that the
values of some variables have been carried over in  accumulators from
the previous coordinate.  Changing  the value of variables  might not
be  successful in  such  a case,  because  BAIL will  not  change any
accumulator  value directly.   The MEMORY  construct can  be  used to
modify any location in a core image, including the accumulators.



4.9 - TEXT
      ____

STRING PROCEDURE TEXT;

The current static and dynamic  scopes, with text from the  source or
listing file.



4.10 - TRACE
       _____

PROCEDURE TRACE("procedure");

Special  breakpoints are  inserted at  the beginning  and end  of the
procedure  named.  On  entry, the  procedure name  and  arguments are
typed.  On exit, the name and value returned (if any) are typed.











                                 20
BAIL -- A debugger for SAIL                           RUN-TIME ACTION


4.11 - TRAPS
       _____

STRING PROCEDURE TRAPS;

A list of the current breakpoints and traces.



4.12 - UNBREAK
       _______

PROCEDURE UNBREAK("location");

The breakpoint at the location specified is removed.



4.13 - UNTRACE
       _______

PROCEDURE UNTRACE("procedure");

The breakpoints inserted by TRACE are removed.



4.14 - !!GO
       ____

pseudoPROCEDURE !!GO;

An immediate exit from the current instantiation of BAIL is taken and
execution of the  program is resumed.  !!GO  is a reserved  word (the
only one) in BAIL.



4.15 - !!GSTEP
       _______

pseudoPROCEDURE !!GSTEP;

Temporary breakpoints are inserted at all of the logical exits of the
current statement, and execution of the program is  resumed.  Logical
exits  are the  next  statement and  locations to  which  the current
statement  can  jump,  excluding any  procedure  calls.   All  of the
breakpoints which are inserted will be removed as soon as one of them
is encountered.
                                 21
BAIL -- A debugger for SAIL                           RUN-TIME ACTION


4.22 - !!STEP
       ______

pseudoPROCEDURE !!STEP;

Temporary  breakpoints are  inserted at  all locations  to  which the
current statement can jump, including procedure calls,  and execution
of the program is resumed.



4.17 - GOGTAB
       ______

EXTERNAL INTEGER ARRAY GOGTAB[0:'270];

This array is  the SAIL user table,  containing all kinds  of magical
information.  (The  procedure USERCON  was formerly  the only  way to
access  the user  table.) If  you are  a hacker,  pick up  a  copy of
SYS:GOGTAB.DEF (<SAIL>GOGTAB.DEF on  TENEX) and poke around.   Do not
change any values unless you know what you are doing.



4.18 - STRING TYPEOUT
       ______ _______


Strings are usually  typed so that the  output looks the same  as the
input, i.e., a string  is typed with surrounding quotation  marks and
doubled  internal quotation  marks.  For  SHOW, ARGS,  and  TEXT this
would  ordinarily create  confusion, so  they are  handled specially.
When these procedures  are evaluated they  set a flag  which inhibits
quotation mark  fiddling, provided that  no further  evaluation takes
place before the next typeout.  Thus SHOW(5,3); will be  typed plain,
but STR←SHOW(5,3); will have quotation marks massaged.



4.19 - BAIL and DDT
       ____ ___ ___


If BAIL is  initialized in a  core image which  does not have  DDT or
RAID, then things will be set up so that the monitor command DDT gets
you into BAIL in the right way.  That is, BAIL will be your  DDT.  To
enter BAIL from DDT  (provided that the SAIL  initialization sequence
has already been performed), use
    pushi P,<program counter>$X

                                 22
BAIL -- A debugger for SAIL                           RUN-TIME ACTION


    JRST BAIL$X
For example, if .JBOPC contains the program counter,
    PUSH P,.JBOPC$X
    JRST BAIL$X

The entry B. provides a path from DDT to BAIL which works  whether or
not the core image has been initialized.  One use of this  feature is
to  BREAK  a  procedure in  an  existing  production  program without
recompiling.  For example,
    @;  PROG originally compiled, loaded with BAIL and DDT, and SAVEd
    @GET PROG
    @DD
     B.$G
    BAIL initialization
            :
            :
    1:BREAK("procedure");
    1:!!GO;

    $G

To enter DDT from BAIL, simply say DDT;.  For operation  under TENEX,
control-B is a pseudo-interrupt character which gets you into BAIL.



4.20 - WARNINGS
       ________


Since BAIL is itself a  SAIL procedure, entering BAIL from  the error
handler  or  DDT  after  a push-down  overflow  or  a  string garbage
collection error will get you into trouble.

SIMPLE procedures cause headaches for BAIL because they do not keep a
display pointer.   [Indeed, the compiler  gets lost in  the following
example, and does not complain:
        BEGIN "LOST"
        PROCEDURE A(INTEGER I); BEGIN "A"
          SIMPLE PROCEDURE B; OUTSTR("THE VALUE OF I IS " & CVS(I));
          PROCEDURE C(INTEGER J); B;
        C(2);
        END "A";

        A(1);
        END "LOST";                                     ]



                                 23
BAIL -- A debugger for SAIL                           RUN-TIME ACTION


BAIL tries valiantly to do the right thing, but occasionally  it also
gets lost.  BAIL will try to warn you if it can.  In general, looking
at value string parameters of SIMPLE procedures does not work.



4.21 - FOR WIZARDS ONLY
       ___ _______ ____


pseudoPROCEDURE !!UP(level); This  procedure trims the  runtime stack
back to  level, then reenters  BAIL.  CLEANUPs and  deallocations are
performed  for  the  procedures  thus  killed.   Level  has  the same
interpretation as  in SETLEX,  and in addition  must not  designate a
SIMPLE procedure.  Suppose you ask BAIL to evaluate a procedure call,
the procedure hits an  error, and you want  to get back to  where you
were before the procedure was called.  Then !!UP will do the trick if
the value of level is correct.

pseudoPROCEDURE !!GOTO("location"); The return address is set  to the
location specified, and then a !!GO is done.  Note that  the location
should be in the same lexical scope as the most recent entry to BAIL,
or the program will probably get confused.

INTERNAL  STRING  !!QUERY;  [Declare as  EXTERNAL  in  your program.]
Whenever BAIL wants input, it checks this string first.  If it is not
NULL, then !!QUERY is used instead of asking the operating system for
input from the terminal.  (!!QUERY  is set to NULL each time  this is
done.) Thus a  program can simulate the  effect of typing to  its own
input buffer by stuffing the text into !!QUERY.  In  particular, file
input  to BAIL  and  various macro  hacks  can be  effected  by using
procedures which assign values to !!QUERY.

















                                 24
BAIL -- A debugger for SAIL                            RESOURCES USED


                             SECTION  5
                             _______  _

                           RESOURCES USED
                           _________ ____




I.  Compile-time

    A.  One channel.  This means that REQUIREd source files  may only
        be nested to a depth of about 9.

    B.  Memory.  Up to 11*(maximum lexical nesting depth)  more words
        of   memory   may   be   required   compared   with  previous
        compilations.

    C.  CPU time.  Approximately 0.3 seconds per page of dense text.

II.  Run-time

    A.   Channels.   Three  during  initialization,  two  thereafter.
        Channels are obtained via GETCHAN.

    B.  BAIL uses 7 of the privileged breaktables, obtaining them via
        GETBREAK.

    C.  REQUIRE 64 STRING!PDL.  Necessary if the  debugging recursion
        level will exceed 3 or 4.

    D.  Memory.  (9.5K +((# of  coordinates+127) DIV 128) + (2*  # of
        blocks) + (5* # of symbols)) words.

    E.  CPU time.

        1.   Initialization.   Typically  4  seconds  for  a  30 page
            program.

        2.   Debugging requests.   0.07 seconds  per  simple request.
            DDT response time.

III.  Disk space

    A.  The .SM1 file  for a /7B compilation is  typically one-fourth
        the size of the corresponding .REL file.

    B.  The .BAI  file for a group  of /7B compilations  is typically
        one-third the total size of the corresponding .REL files.


                                 25
BAIL -- A debugger for SAIL                            CURRENT STATUS


                             SECTION  6
                             _______  _

                           CURRENT STATUS
                           _______ ______




The  state  of  the  world  is  determined  by  the  values   of  the
accumulators and the value of the SAIL variable !SKIP!.

The run-time interpreter recognizes  only the first 15  characters of
identifier  names;  the  rest  are  discarded  without  comment.  The
characters which are legal in identifiers are

        ABCDEFGHIJKLMNOPQRSTUVWXYZ
        abcdefghijklmnopqrstuvwxyz
        0123456789!_αβπλ⊂⊃∀∃→~#$\|

Notable for its absence: period.

LOCATION of a procedure does not work.

PROPS is read-only.

Bracketed triple items are not allowed.

A  procedure  call  containing the  name  of  a  parametric procedure
(functional argument) is not handled properly.

Contexts are not recognized.

The run-time interpreter will not recognize macros.

External linkage: If an identifier is never referenced by code (i.e.,
has  an empty  fixup chain  at the  time fixups  are put  out  to the
loader) then that identifier is not defined by SAIL.   Thus variables
which are  never used  do not  take up  space, and  a request  to the
loader  is not  made for  EXTERNALS which  are not  referenced.  This
feature of SAIL is  cast in concrete and  will not be changed.   As a
result, the  following DOES NOT  WORK unless special  precautions are
taken:
        BEGIN
        EXTERNAL PROCEDURE BAIL;
        EXTERNAL PROCEDURE PLOT(REAL X0,Y0,X1,Y1);
        REQUIRE "CALCOM" LIBRARY;

        BAIL END


                                 26
BAIL -- A debugger for SAIL                            CURRENT STATUS


PLOT will not be defined by SAIL, hence BAIL will not know  about it.
However if there are any  references to PLOT (real or  "dummy" calls)
then BAIL will know.  The following trick can also be  used, assuming
that CALCOM  is a  SAIL-compiled library:  Compile CALCOM  with /10B,
which  says  "make  the  .SM1  file  but  don't   automatically  load
SYS:BAIL.REL".   Then the  above will  win (due  to  BAIL recognizing
things which are globally unique) and programs which do not  use BAIL
will not have it loaded just beacuse the library was used.  This same
problem occurs with  EXTERNAL RECORD!CLASS declarations.  Use  of the
subfield index information  does not cause  a reference to  the class
name but NEW!RECORD does.  Thus  the same /10B trick must be  used if
there are no NEW!RECORD calls.

BAIL and other language processors: If CALCOM in the  paragraph above
was compiled by  some processor other  than SAIL (e.g.   FAIL, MACRO,
BLISS, ...) then further steps must be taken if BAIL is to know about
the procedures  contained in the  file.  BAIL must  have access  to a
procedure descriptor  in order  to call any  procedure (cf.   the /4B
switch).  Thus a user who wishes to use assembly  language procedures
with BAIL must  provide appropriate procedure descriptors.   The file
SAILPD.FAI[S,AIL] defines  a FAIL  macro which  will generate  a SAIL
procedure  descriptor.  The  procedure  descriptors may  reside  in a
separate load module if desired;  but they must be in the  core image
when BAIL is being used.

























                                 27
BAIL -- A debugger for SAIL                            CURRENT STATUS


REFERENCES

[1]   _____,  DECsystem10 Assembly  Language  Handbook DEC-10-NRZC-D,
      Digital Equipment Corporation, Maynard, Massachusetts, 1973.

[2]   Edwin H. Satterthwaite  Jr., "Source Language  Debugging Tools"
      (Ph.D.   thesis),   Computer   Science   Department,   Stanford
      University, May 1975.

[3]   Daniel C. Swinehart,  "COPILOT: A Multiple Process  Approach to
      Interactive  Programming  Systems"  (Ph.D.   thesis),  Computer
      Science Department, Stanford University, August 1974.

[4]   Kurt  VanLehn  (ed.),  SAIL  USER  MANUAL,  Stanford Artificial
      Intelligence   Laboratory   memo   AIM-204   (Computer  Science
      Department report STAN-CS-73-373), July 1973.

































                                 28
What does pdl ov as an error message mean??? ⊗f pdl ov on this file yields zilch!!
	sail p290 push down list overflo Sail.jfr[aim,doc]/290P