perm filename SAIL.DOC[DOC,AIL]1 blob sn#075606 filedate 1973-12-08 generic text, type T, neo UTF8
SAIL Addendum  1                                    TABLE OF CONTENTS


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



SECTION                                                          PAGE



1    INTRODUCTION



2    NUMERICAL ROUTINES

     1    OVERFLOW                                                  3
     2    ENTRY POINTS                                              4


3    PROCESS: NEW FEATURES

     1    SPROUT APPLY                                              5
     2    SPROUT_DEFAULTS                                           5
     3    SUSPEND                                                   7
     4    FAIL AND SUCCEED                                          7


4    ERROR HANDLING

     1    ERROR MODES                                               8
     2    USER ERROR PROCEDURES                                     8


5    INEXHAUSTIBLE STRING SPACE



6    MISCELLANEOUS NEW FEATURES

     1    NEW MTAPE OPTION                                         12
     2    INITIALIZATION PHASES                                    12
     3    CHNCDB                                                   13
     4    ARRCLR                                                   13
     5    SETPL                                                    13
     6    EVALREDEFINE                                             14
     7    CVPS                                                     14
     8    EXPRESSIONS IN REQUIRES                                  14
     9    RELEASE                                                  14
SAIL Addendum  1                                         INTRODUCTION


                             SECTION  1
                             _______  _

                            INTRODUCTION
                            ____________





The following short manual  describes the changes that  have happened
to  SAIL  since  the  publishing  of  the  Manual  in  July  1973. It
accurately reflects the state of SAIL, version 7, which was put up on
December 4, 1973.  The reader should be warned that many of these new
features were designed for veteran SAIL hackers.

The reader may also want  to refer to the following  documents, which
are usually kept updated.

MACLIE.WRU[DOC,AIL] A  summary  of commonly  made  errors  when using
                    macros and what to do about them.

TUTOR.DOC[DOC,AIL]  In introduction to LEAP.

LEAP.WRU[DOC,AIL]   A detailed description of the runtime environment
                    of LEAP for the  hardy few who want  to interface
                    to LEAP in assembly language.

SAIL.DOC[AIM,DOC]   The  July  '73  manual  (AIM-204)  in  LPT  form.
                    Warning: this  version is the  Stanford character
                    set.  It is also almost 300 pages long.   You can
                    get a  120 page  version, set  in two  columns of
                    nice type from the National Technical Information
                    Service, Springfield, Virginia 22151.

LIES[DOC,AIL]       This  file  contains  the  know  mistakes  in the
                    Manual.  Soon  it  will  also  contain  the known
                    mistakes in this document.













                                  1
SAIL Addendum  1                                   NUMERICAL ROUTINES


                             SECTION  2
                             _______  _

                         NUMERICAL ROUTINES
                         _________ ________





A collection of numerical routines has been added to SAIL.  These are
pre-declared in the compiler,  and are loaded from the  standard SAIL
library.   The  functions  are  quite  standard;  following  are  the
equivalent definitions:

1.  The standard trigonometric functions.  ASIN, ACOS, ATAN and ATAN2
    return results in radians.   The ATAN2 call takes  arc-tangent of
    the  quotient  of  its  arguments;  in  this  way,  it  correctly
    preserves sign information.

        REAL PROCEDURE SIN (REAL RADIANS);
        REAL PROCEDURE COS (REAL RADIANS);
        REAL PROCEDURE SIND (REAL DEGREES);
        REAL PROCEDURE COSD (REAL DEGREES);

        REAL PROCEDURE ASIN (REAL ARGUMENT);
        REAL PROCEDURE ACOS (REAL ARGUMENT);
        REAL PROCEDURE ATAN (REAL ARGUMENT);
        REAL PROCEDURE ATAN2 (REAL NUMERATOR,DENOMINATOR);


2.  The hyperbolic trigonometric functions.

        REAL PROCEDURE SINH (REAL ARGUMENT);
        REAL PROCEDURE COSH (REAL ARGUMENT);
        REAL PROCEDURE TANH (REAL ARGUMENT);

3.  The square-root function:

        REAL PROCEDURE SQRT (REAL ARGUMENT);

4.  A pseudo-random number  generator.  The argument specifies  a new
    value for the seed (If the  argument is 0, the old seed  value is
    used.  Thus to get differing random numbers, this argument should
    be zero.)  Results are normalized to lie in the range [0,1].

        REAL PROCEDURE RAN (INTEGER SEED);




                                  2
SAIL Addendum  1                                   NUMERICAL ROUTINES


5.  Logarithm and exponentiation functions.  These functions  are the
    same ones used by the SAIL exponentiation operator.  The  base is
    e  (2.71828182845904).  The  logarithm  to the  base 10  of  e is
    .4342944819.

        REAL PROCEDURE LOG (REAL ARGUMENT);
        REAL PROCEDURE EXP (REAL ARGUMENT);

These functions may occasionally be asked to compute numbers that lie
outside the range of legal floating-point numbers on the  PDP-10.  In
these cases,  the routines  issue sprightly  error messages  that are
continuable.



2.1 - OVERFLOW
      ________


In order  to better  perform their tasks,  these routines  enable the
system interrupt facility  for floating-point overflow  and underflow
errors.  If  an underflow is  detected, the results  are set to  0 (a
feat not  done by  the PDP-10  hardware, alas).   Be aware  that such
underflow fixups will be done to every underflow that occurs  in your
program.

If you would like to be informed of any numerical exceptions, you can
call the runtime:

        TRIGINI ( LOCATION(simple-procedure-name) );

Every floating-point exception that is not expected by  the interrupt
handler (the numerical routines use a special convention  to indicate
that  arithmetic exception  was  expected) will  cause  the specified
simple procedure to  be called.  This  procedure may look  around the
world as  described in  the Manual  for 'export'  interrupt handlers,
page 79.   If no  TRIGINI call  is done,  the interrupt  routine will
simply dismiss unexpected floating-point interrupts.












                                  3
SAIL Addendum  1                                   NUMERICAL ROUTINES


2.2 - ENTRY POINTS
      _____ ______


In order to avoid confusion (by the loader) with older trig packages,
the  entry points  of the  SAIL arithmetic  routines all  have  a "$"
appended  to the  end.   Thus, SIN  has  the entry  point  SIN$, etc.
WARNING:  If a  program  plans to  use the  SAIL  intrinsic numerical
routines, it should NOT include external declarations to  them, since
this will probably cause the FORTRAN library routines to be loaded.

                                  3






































                                  4
SAIL Addendum  1                                PROCESS: NEW FEATURES


                             SECTION  3
                             _______  _

                        PROCESS: NEW FEATURES
                        ________ ___ ________







3.1 - SPROUT APPLY
      ______ _____


The <procedure call> in a SPROUT statement may be an APPLY construct.
In  this case SPROUT will  do the "right" thing  about setting up the
static link  for  the  APPLY. That is,  "up-level" references  by the
process will  be made to  the same variable  instances that  would be
used if the APPLY did not  occur in a SPROUT statement. (See  page 77
of the manual.)

However, there  is a glitch.  The sprout mechanism  is not  yet smart
enough to find out the block of the declaration of the procedure used
to define the procedure item. It would be nice if it did,  since then
it could warn the user when that block was exited and yet the process
was still alive,  and thus potentially  able to refer  to deallocated
arrays and etc. What the sprout does instead is assume  the procedure
was declared in the outer  block. This may be fixed   eventually, but
in the meantime  some extra  care should be taken  when  using  apply
in   sprouts  to    avoid    exiting  a    block    with  dependents.
Similarly,  be warned   that the  "DEPENDENTS  (<blockid>)" construct
may  not give  the  "right"  result  for  sprout applies. Page  68 of
the Manual contains the description of this protection  mechanism for
non-APPLY Sprouts.



3.2 - SPROUT_DEFAULTS
      _______________


SAIL  now provides  a mechanism  by which  the user  may specify  the
"default" options to be used when individual procedures are sprouted.








                                  5
SAIL Addendum  1                                PROCESS: NEW FEATURES



Syntax:
        PROCEDURE <procid> ...
         BEGIN
         <some declarations>;
         SPROUT_DEFAULTS <integer constant>;
         <perhaps some more declarations>;
         :
         :
         <statements>
         :
         END;


In other words, SPROUT_DEFAULTS is a declaration.

Semantics:

If  one of the "allocation" fields of  the options word passed to the
SPROUT routine -- i.e. QUANTUM,STRINGSTACK,PSTACK, or  PRIORITY -- is
zero,   then  SPROUT  will look  at  the corresponding  field of  the
specified <integer constant> for the procedure being sprouted. If the
field is  non-zero,   then  that value  will be  used; otherwise  the
current "system" default will be used.

NOTE:  SPROUT_DEFAULTS  only  applies  to  "allocations",  i.e.   the
process status control bits (e.g. SUSPME) are not affected.
Example:

        RECURSIVE PROCEDURE FOO;
         BEGIN
         SPROUT_DEFAULTS STRINGSTACK(10);
         INTEGER XXX;
         :
         :
         END;
        :
        SPROUT(P1,FOO,STRINGSTACK(3));
        SPROUT(P2,FOO);
        COMMENT P1 will have a string stack of 3*32 words.
         P2 will have a string stack of 10*32 words;








                                  6
SAIL Addendum  1                                PROCESS: NEW FEATURES


3.3 - SUSPEND
      _______


SUSPEND now behaves like RESUME in that it returns an item.

        itm ← SUSPEND(<process item>)

Frequently, one is suspending some other process than the one that is
executing the SUSPEND statement.  In this case, the item  returned is
ANY.   However, in cases like:

        X ← SUSPEND(MYPROC);

where the process suspends itself, it might happen that  this process
is  made running  by a  RESUME from  another process.  If so,  then X
receives the <return_item>  that was an argument to the RESUME.



3.4 - FAIL AND SUCCEED
      ____ ___ _______


FAIL and SUCCEED now behave like RESUME and SUSPEND in that they also
return  an  item.   The  item returned  is  ANY  unless  the Matching
Procedure  containing  the FAIL  or  SUCCEED was  (1)  sprouted  as a
process, and (2) made running  by a RESUME construct.  In  the latter
case, the item returned is the <return_item> that was an  argument to
the RESUME.  [Note that the  only case in which a  Matching Procedure
can be reactivated at a FAIL is by being RESUMEd.]




















                                  7
SAIL Addendum  1                                       ERROR HANDLING


                             SECTION  4
                             _______  _

                           ERROR HANDLING
                           _____ ________







4.1 - ERROR MODES
      _____ _____


SAIL's error  handler has at  long last been  modified to do  what is
claimed it will do  in Section 20 of the manual (pgs 95 - 97), and in
the description of USERERR (pg 42).  In brief, it allows one to  have
error  messages automatically  sent  to  a "log"  file  while one  is
compiling, and to use USERERR as a trace statement.

The description given in the manual differs from reality in two ways:
"Keep" mode has not  been implemented (the error handler   will flush
all type-ahead except  a <lf>);   all  of the  other  modes ("Quiet",
"Logging",  and "Numbers")  are  implemented ONLY   IN  THE COMPILER.
However, one  can get the effect of error modes at runtime by using a
brand new feature called user error procedures.



4.2 - USER ERROR PROCEDURES
      ____ _____ __________


A  user error  procedure is a  user procedure  that is run  before or
instead of  the  SAIL error  handler  everytime  an error  occurs  at
runtime.  This  includes all array errors, IO  errors, Leapish errors
and all USERERRs.  It does not include system errors, such as Ill Mem
Ref or Ill UUO.

The  procedure one uses  for a  user error procedure  must be  of the
following type:

    SIMPLE INTEGER PROCEDURE proc (INTEGER loc; STRING msg, rsp);


Only the names  proc, loc,  msg, and rsp  may vary  from the  example
above, except  that one  may declare  the procedure  INTERNAL if  one
wishes to use it across files.



                                  8
SAIL Addendum  1                                       ERROR HANDLING


Whenever  the external integer _ERRP_  is loaded with LOCATION(proc),
the error handler will  call proc before it  does anything else.   It
will set loc to  the core location of the call  to the error handler.
Msg  will be  the message  that it  would have  printed.  Rsp will be
non-NULL only  if the  error was  from a  USERERR which  had response
string argument.  Proc can  do anything that  a simple  procedure can
do.  When it  exits, it should  return  an  integer which   tells the
error handler  if  it should do anything more.  If the integer  is 0,
the  error  handler will  (1)   print the   message,  (2)   print the
location,  and  (3)  query  the  tty  and  dispatch  on  the response
character (i.e ask for a <cr>, <lf>, etc.).  If the right half of the
integer is  non-zero, it  is taken as  the ascii  for a  character to
dispatch upon.  The left half may have two bits to  control printing.
If bit 17  in the integer is  on, message printing is  inhibited.  If
bit 16 is on, then  the location printing is inhibited.  For example,
"X"+(1 LSH 18) will cause the location to be printed and  the program
exited.  "C"+(3 LSH  18)  will cause  the error  handler  to continue
without printing anything.

Note that simple  procedures can not do  a non-local GOTO.   However,
the  effect of  a non-local  GOTO  can be  achieved in  a  user error
procedure by loading the external integer _ERRJ_ with the LOCATION of
a label. The label  should be a on  a call to a  non-simple procedure
which does the desired GOTO.  The error handler clears  _ERRJ_ before
calling the procedure  in  _ERRP_.  If  _ERRJ_  is non-zero  when the
user procedure returns, and continuing was specified, then  the error
handler's exit  consists of a simple transfer to  that location.

WARNING! Handling errors from strange places like the  string garbage
collector and  the core  management routines will  get you  into deep
trouble.


















                                  9
SAIL Addendum  1                           INEXHAUSTIBLE STRING SPACE


                             SECTION  5
                             _______  _

                     INEXHAUSTIBLE STRING SPACE
                     _____________ ______ _____





The string garbage collector has been modified to expand string space
(using discontiguous blocks) whenever necessary to satisfy the demand
for places to put strings. To take advantage  of  this  feature,  one
need not change his programs.

Here are some points which might be of interest, however:

1)  Although  we  are  going  to  provide  user control over all size
    parameters  eventually,  currently  only   the   initial   string
    space size  is   settable  by  the   user, either via  REQUIRE or
    the ALLOC  sequence, as  before.  The size  of each  string space
    increment will be  the same as the original size, which  need not
    be monstrous  any more  unless you   know that  all runs  of your
    program  will  need   a monstrous   string  space   anyhow.   The
    threshold  (see below)  for  expanding will  be set  at  1/8  the
    string  space  size  (increment size).

2)  One can, in his program, modify these values independently, if he
    is  willing  to use  the  USERCON function,  and  to  follow this
    format:

     USER TABLE ENTRY NAME              VALUE
        STINCR          lh: number of chars. in increment
                        rh: number of words in increment + 4

        STREQD          lh: number of chars. in threshold
                        rh: number of words in threshold.


3)  The threshold.   After garbage  collection, let  us say  that M-1
    discontiguous string spaces  are   full,  and  the  M'th   has  n
    free  characters in it (available for new strings).  The  garbage
    collector  was  called because   some routine wanted to  create a
    string R characters long, and there were not that many  available
    (free).      After    garbage  collection,   the   new  algorithm
    requires  that N  be greater  than R+LH(STREQD).   If it  is not,
    expansion  takes  place  (to  M+1  spaces),  to    satisfy   this
    requirement.    In other words, if STREQD is 1/8 the size  of the
    current space, that space  will not be  allowed  to  become  more


                                 10
SAIL Addendum  1                           INEXHAUSTIBLE STRING SPACE


    than   about   7/8   full.   This  helps  avoid  frequent, nearly
    useless calls on the garbage collector when  space is about gone.
    All  but the  current  space are  allowed  to become  as  full as
    possible, however.

4)  New  statistics  are  maintained  by  the    garbage   collector.
    Soon there   will  be  a built-in  routine you  can use  to print
    them.  For now, you may look at them using USERCON, although this
    document   does  not   say  what   they   are.      In   order to
    activate timing  of the  garbage collector  (slows it  down), set
    SGCTIME in the  user  table to -1.

5)  Future plans.  The  new  structure  not only allows  expansion of
    string  space,  it  also  will   allow   for    partial   garbage
    collections   (no   visible  benefits   except   increased speed,
    since  a partial  collection  will be  almost as  effective  as a
    complete one,  and  much   faster),  and  the  ability   to  move
    string  space  blocks, in order to compact memory.  Push  on your
    local representative  to  get  these  things done.






























                                 11
SAIL Addendum  1                           MISCELLANEOUS NEW FEATURES


                             SECTION  6
                             _______  _

                     MISCELLANEOUS NEW FEATURES
                     _____________ ___ ________







6.1 - NEW MTAPE OPTION
      ___ _____ ______


In export SAIL, MTAPE(chnl,"I") sets the 'IBM compatible' mode  for a
tape drive.  (It does an MTAPE chnl,101.)



6.2 - INITIALIZATION PHASES
      ______________ ______


User initializations  are  now done  in successive  phases, with  all
initializations   required   for   one   phase   being  done   before
initializations required for the next phase.

Syntax:

        REQUIRE <procid> INITIALIZATION;
        REQUIRE <procid> INITIALIZATION [<phase no>];

where <phase no> is an integer constant.

Semantics:

<phase no> specifies  the number  of the user   initialization phase.
If  it is left out,   then one is used.   Currently, there  are three
phases,  numbered 0,  1, and   2.  If  the  demand  is  great enough,
additional phases may  be added later.   (Note for assembly  language
hackers: internally, user phases are numbered '400000, '400001, etc.)










                                 12
SAIL Addendum  1                           MISCELLANEOUS NEW FEATURES


6.3 - CHNCDB
      ______


val←CHNCDB(channel)

This integer procedure returns a pointer to the three word block used
to open the  specified channel.   It is provided  for the benefit  of
assembly language procedures that may want to do I/O inside some fast
inner loop, but which may want to live in a SAIL core image & use the
SAIL OPEN, etc.



6.4 - ARRCLR
      ______


This new runtime routine clears any kind of array. That is, arthmetic
arrays get filled with  zeros, string arrays with NULLs,  and itemvar
arrays with ANYs.  One may  use ARRCLR with set and list  arrays, but
the set  and list space  will be lost  (i.e. un-garbage-collectable).
The syntax is

        ARRCLR ( ARRY )



6.5 - SETPL
      _____


        SETPL(channel, @linnum, @pagnum, @sosnum)

This new runtime routine allows one to keep track of the string input
from CHANNEL.  Whenever a '12 is encountered, LINNUM  is incremented.
Whenever a '14 is  encountered, PAGNUM is incremented, and  LINNUM is
zeroed.  Whenever  an SOS  line number is  encountered, it  is placed
into SOSNUM.  When  fully implemented (soon),  this will work  on the
INPUT, INTIN, and REALIN functions as well.












                                 13
SAIL Addendum  1                           MISCELLANEOUS NEW FEATURES


6.6 - EVALREDEFINE
      ____________


EVALREDEFINE bears  the same relationship  to REDEFINE  as EVALDEFINE
does to DEFINE.  See pages 47 and 50 of the Manual.



6.7 - CVPS
      ____


CVPS(<macro_parameter>)  converts <macro_parameter>  to a  string and
returns the  string. See  about macro  parameters on  page 48  of the
manual.



6.8 - EXPRESSIONS IN REQUIRES
      ___________ __ ________


Previously,  all REQUIRE  constructs had  to have  only  constants in
them. Now  SAIL allows  compile time expressions  as well.  See about
compile time expressions on page 47 of the Manual.



6.9 - RELEASE
      _______


RELEASE  now takes  an optional  second argument,  the  CLOSE inhibit
bits.  These are described in the UUO manual (Stanford System). These
are defaulted to zero when  not specified so that old  programs which
did not specify them will work as before.
















                                 14