perm filename NEWMAN[S,AIL] blob sn#000829 filedate 1972-05-13 generic text, type T, neo UTF8
 00001 00001
 00002 00002	
 00006 00003	CHAPTER 1 -- Version 15 Changes to SAIL -- 7-9-71
 00011 00004	Chapter 1 (cont). Statement Counter System  
 00023 00005	Chapter 2, Introduction to Version 16.
 00029 00006	Chapter 6 -- Other Changes for Version 16
 00038 00007	
 00052 00009	Chapter 7 -- How to use the new system D. Swinehart
 00054 ENDMK


	 This  document  describes   changes   which   have
         occurred  (or  will soon occur) to the SAIL system
         since the last manual, SAILON 57.2, was published.
         Most of the text is concerned with descriptions of
         a new system which is  now  available,  and  which
         will  become  the standard system in the middle of
         June, 1972.

   Table of Contents:

   Chapter 1 -- Documentation for Version 15, installed in July,
		1971, which does not appear in the manual.
		 by Dick Sweet and Dan Swinehart.

   Chapter 2 -- Introduction to Version 16 (the new stuff).
		 by Dan Swinehart.

   Chapter 3 -- Internal Data- and Control- Structure Improvements --
		and ramifications for the user.
		 by Russ Taylor.

   Chapter 4 -- Improvements to the Associative (LEAP) Features.
		 by Jim Low.
   Chapter 5 -- Improvements to the Macro System -- Introduction of
		a Conditional Compilation Facility.
		 by Hanan Samet.

   Chapter 6 -- Other Modifications, Chapter and Verse.
		 by Dan Swinehart.

   Chapter 7 -- How to Use It.

   We  urge  people to begin using this system as soon as possible --
   for their benefit as well as ours.

   Dan Swinehart
   11 May, 1972
CHAPTER 1 -- Version 15 Changes to SAIL -- 7-9-71
 D. Swinehart


1. CASE J OF BEGIN [3]S1; [4]S2; [1]S3; [5]S4 END

	is equivalent to

      S3;	COMMENT CASE 1;
      S1;	COMMENT CASE 3;
      S2;	COMMENT CASE 4;
      S4	COMMENT CASE 5;

   The former is slightly more efficient in space and time if any cases
    are omitted -- identical otherwise.  The total space used by either
    method is approximately linear to the largest bracketed value.

2. WARNING about Dump Mode IO (modes '15 through '17).  Any Dump Mode input
    which does not specify an n*128-word count will have the effect of losing
    the words up to the next 128-word boundary -- you'll get the first word(s)
    of the next 128-word record on the next input.  Similarly, any Dump Mode
    output fills out the file with 0's until a 128-word boundary is reached.
   Therefore, Dump Mode IO is not practical for sizes other than 128-word
    transfer multiples, in general.

   For this reason, the fact that WORDIN and WORDOUT no longer operate 
    correctly in Dump Mode should be no cause for concern.  However, we will
    soon try to make their illegality explicit.

3. It is also not clear whether ARRYIN or ARRYOUT return the number of words
    actually read when EOF terminates a transfer early, either in Dump or 
    Buffered modes. This should be corrected.

4. A long-standing bug which forced users to insert a dummy first argument
   in IBP calls has been fixed.  Recently, both forms (with and without)
   were accepted as valid syntax, but only IBP(dummy,BP) generated valid
   code.  Now everything is beautiful.
5. If your program calls any LEAP runtime routines, you will get various
   tables allocated for LEAP constructs (several K) the first time you
   call LEAP.  This is true even if no reference will be made to any data
   in the lower (local) segment.  Allocation of this storage may be inhibited
   by the REQUIRE -1 NEW_ITEMS special construct.  Although this works in
   any SAISEG-type segment system, it should only be used by those who use
   the (hand-eye) global-model features.

6. CASE n OF BEGIN "name" .... END "name" is now legal.

7. REQUIRE n VERSION (n a non-zero integer) will flag the resultant RELfile
   as version n.  When a program loaded from several such RELfiles is started,
   the SAIL allocation code will verify that all specified versions are equal.
   A non-fatal error message will be displayed if any disagree.  As much as will
   fit of the version number is also stored in lh(JOBVER), where JOBVER is
   location 137.
Chapter 1 (cont). Statement Counter System  
 R. Sweet


	The new SAIL compiler contains a feature which allows you  to
determine  conveniently  the frequency of execution of each statement
in your SAIL program.

	This is implemented by inserting an  array  of  counters  and
placing  AOS  instructions  at  various  points in the object program
(such as in loops and conditional statements). A routine is called to
zero  the  counter  array  before your program is entered and another
routine is called to write out the array before calling EXIT.

	Since not all programs  exit  in  the  normal  fashion  (i.e.
falling  out  the  bottom),  it  is  possible to call either the zero
routine or the output routine as an EXTERNAL PROCEDURE.

	Another program, called PROFIL, is used to merge the  listing
file produced by the SAIL compiler with the file of counters produced
by the execution run of your program.    The  output  of  the  PROFIL
program  is  an  indented listing of your SAIL program with execution
counts in the right hand margin.  The  output  format  of  PROFIL  is
reasonably flexible, with several "switches" to control it.

	Since  the  AOS instructions access fixed locations, and they
are placed only where needed to determine program flow,  they  should
not  add  much overhead to the execution time.   Although I have made
no large study, the counters do seem to contribute about  2%  to  the
execution  time  of  the  profile  program, which has a fairly deeply
nested structure.


	The mechanism for  inserting  counters  is  controlled  by  a
compiler switch.    To tell the compiler to insert counters, you give
it a /K switch. (/C was already used for something else.) It is  also
necessary  to  produce a listing file, since the PROFIL program needs
it.    In fact, the /K switch is ignored unless a listing  is  called
for.    Specifying  /K has several effects on the listing.     First,
macros are expanded and macro names not listed. This is necessary  so
that  PROFIL  will know about block structure, etc. Also, the listing
of PC and line numbers is suppressed.  The current version of  PROFIL
is  confused by all those numbers and anyway, the lines of the PROFIL
listing can differ somewhat from the lines of  the  original  source.
The  final  change in the listing is the inclusion of markers telling
where counters have been inserted.   Most of these are ignored by the
present  PROFIL  since it is smart enough to know where they are from
the program context.  The ones that it does use are the  markers  for
counters inserted into conditional and case expressions.

	At  the  end of each program (i.e. each separate compilation)
is the block of counters, preceeded by a small data block used by the
zero  and  output  routines.  This block contains such information as
the number of counters, the name of the list  file,  and  a  link  to
other  such  blocks  of counters. The first counter location is given
the name .KOUNT,  which  is  accessable  from  RAID,  but  cannot  be
referenced by the SAIL program itself.

	The  routine  K.ZERO  is  called to zero the counters. If for
some reason you wish to zero them  yourself,  (like  if  you're  only
interested  in  steady state execution counts) you can reference this
routine by including the declaration:

	The  outputting of the counters is done by the routine K.OUT.
It uses the SAIL routine GETCHAN to find  a  spare  channel,  does  a
single dump mode output which writes out all the counters for all the
programs loaded having counters, and then releases the channel.   The
file  which  it  writes is xxx.KNT, where xxx is the name of the list
file of the first program loaded having counters (usually the name of
the  SAIL  source  file).   If  there  are  no counters, K.OUT simply
returns.      This routine can also be referenced  by  including  the


	The program PROFIL is used to produce  the  program  profile,
i.e.  the  listing complete with statement counts. It operates in the
following manner.  First it reads in the file xxx.KNT created by  the
execution  of  the user program. This file contains the values of the
counters and the names of the list files of the programs loaded which
had  counters.  It  then  reads  the  the list files and produces the
profile.   Currently, the SAIL compiler has a  non-trivial  bug:  the
last  line  of  the source file is not written into the listing file.
Since this is not an easy bug to fix, it's still in the new compiler.
To  get  around this, the scanner of PROFIL returns an "END" whenever
it gets an end-of-file condition.  This works fine  unless  you  have
executable  statements on the last line.  This will probably be fixed
sometime, but for now, ignore the "(supplied by scanner)"  after  the
last "END".

	The  format  of  the  listing  is  such  that only statements
executed the same number of times are listed on a  single  line.   In
the  case  of conditional statements, the statement is continued on a
new line after the word  THEN.    Conditional  expressions  and  case
expression, on the other hand, are still listed on a single line.  In
order that you might know the execution  counts,  they  are  inserted
into the text surrounded by two "brokets" (e.g. <<15>>).

	PROFIL  expects  a  command  string  of the standard form for
CUSP's, i.e.
	<output>←<input>  {switches} where the <input> is the name of
the .KNT file created from the program execution.   The extension  of
.KNT  is  assumed.  If  the output device is the DSK, the output file
will have a default extension of .PFL.   Although  the  line  spacing
will probably be different from the source, PROFIL makes an effort to
keep any page spacing that was in the source.  Thus, if you happen to
be  using  the "T" editor, you can edit the profile successfully with
T.     There are several possibilities for switches,  for  which  the
pertinent ones are:
	/nB	Indent n spaces for blocks (default 4)
	/nC	Indent n spaces for continuations (default 2)
	/F	Fill out every 4th line with ".   .   ." (default ON)
	/I 	Ignore comments, strip them from the listing
	/nK	Make counter array of size n (default 200)
	/nL	Maximum line length of n (default 120)
	/N	Suppress /F feature
	/S	Stop after this profile
	/T	TTY mode = /1C/2B/F/80L


	Suppose that you have a SAIL program named FOO.SAI for  which
you desire a profile.  The following statements will give you one.

.EX /LIST FOO(K)   (or TRY or DEB or what have you)
. . . any input to FOO  . . .




.  At this point, the file FOO.PFL contains the profile, suitable for
     typing on the TTY or editing.
Chapter 2, Introduction to Version 16.
 D. Swinehart


A  new  system version of SAIL will be installed on or about June 15,
1972. For the month beginning May 10 this system  will  be  available
for  use.  You  should  confine  your  experiments at first to simple
one-compilation programs.  Later in the trial period  you  should  be
able  to  run  all your systems under the new regime. We suggest that
you read this document early, since there are a few incompatibilities
(mostly  pertaining to START_CODE sequences, to adjust for changes in
internal structures).

Major improvements have been made in three areas,  described  briefly

1)  Russ  Taylor has implemented a new runtime stack-structure, which
immediately will provide extended  variable-referencing  capabilities
("up-level"  references  to non-local procedures), and the ability to
jump out of procedures. Later this structure will  allow  coroutines,
multiple  processes, and interrupt facilities.  In collaboration with
Jim Low, Russ has implemented "Procedure Items", to which  procedures
may  be bound dynamically, and deferred arguement lists.  Using this,
you  can decide  the procedure  to call,  and/or what  to feed it, in
advance of the actual invocation.

2)  Jim  Low  has  made  important  modifications  to the associative
features of  SAIL.   He  has  implemented  a  new  data  type,  LIST,
providing  ordered  lists  of  items,  and  syntactic  constructs for
manipulating them.  In addition, Datums of Items now will  have  type
information stored with them, so that the data type of a Datum can be
changed and queried dynamically. String Datums have been  introduced,
and the PNAME structures have been improved.

3)  Hanan  Samet  has made extensive (but compatible) improvements to
the macro facilities of SAIL, including:

a.  Optional, user-supplied delimiters for denoting macro  body  text
   and  actual  parameters,  removing  much  of  the  strain  on  the
   beleaguered  quote  (")  character.   Other  changes   to   actual
   parameter  scanning  and passing combine to make the whole process
   more civilized.

b. A modified DEFINE statement, which effectively  allows  assignment
   of  arbitrary  expressions  to  compile-time  variables.   This is
   particularly useful in combination with the next feature.

c. A conditional-compilation language, allowing sections of  programs
   to  be  conditionally  omitted or repeated.   A variety of control
   structures is provided by the  conditional-compilation  statements
   IFC,  WHILEC, FORC, and FORLC.  An implementation which causes the
   parser to be "interrupted" when these  keywords  are  seen  allows
   conditional-compilation  statements  to  begin  and  end  anywhere
   within a program.

These gentlemen have  created  documents  describing  their  efforts.
Said  documents  are  included  here as an interim manual supplement.
Following them is a description of  other  modifications  which  have
been made, some in support of the changes I've described, some not.
Chapter 6 -- Other Changes for Version 16
 D. Swinehart

These are presented in the order in which they would  appear  in  the
SAIL manual.  They are keyed to paragraph numbers in SAILON 57.2.


3-58.  REQUIRE Additions and Modifications

a)  The  special  case:  REQUIRE  -1   NEW_ITEMS,   causes   complete
   suppression of the allocation of local data spaces for LEAP.  This
   is provided for programs which manipulate GLOBAL data, but have no
   local actions.

b)  REQUIRE  <integer  constant  expression>  VERSION  will cause the
   number (low-order 18 bits)  you  specify  to  be  checked  against
   similar  Version numbers provided in any other compilations loaded
   at the same time.  If any do not match, the start-up routine  will
   issue  a  warning  error  message.   A  program  without a Version
   Requirement in it will never cause this error.

   The  Version  comparison  includes  18  bits  of  system   Version
   information. This will clearly always match in the comparison just
   described, but it is useful when the GLOBAL system is  used.   The
   entire  version number (system's bits and your bits) are placed in
   location JOBVER (137).  This can be used  to  check  that  several
   jobs  which  are  cooperating  via  a  shared  second segment data
   structure are compatible.  The  Hand-Eye  monitor  currently  does


5-24. Done, Next, Continue

The long-awaited DONE,  NEXT,  and  CONTINUE  extensions  are  almost
ready.  The syntax has been modified slightly:  if you want to escape
from a loop which is not the innermost loop, label the loop statement
(L1, for example), then use, for instance: DONE L1. This replaces the
block-name argument, a feature which was  never  implemented  anyway.
As  of  this instant, these changes have not been installed (but I've
been assured that they have been designed).  Hopefully we  will  soon
allow  certain  labels  (including all labels used in this way) to be
placed without first declaring them.


8-1. Syntax

a)   The  `⊗'  character  is  no  longer  a  substitute  for  `@'  in
   instructions (this character is used to cause the indirect bit  to
   be   assembled).   Continued  use  of  `⊗'  will  cause  (probably
   inadequate) error messages.

b)  The  manual  very  handily  omits  the  syntax  for  labeling  an
   instruction. An instruction is, therefore, heretofore, henceforth,
   and among other things, a label, followed by a colon, followed  by
   an  instruction,  which is, therefore, heretofore, henceforth, and
   among other things, a la.....

c) Facilities for causing expressions to be evaluated withing START_-
   CODE blocks will soon be announced.  Look for it in this space.


9-15. Boolean Expressions

a)  Boolean  expressions  which contain nothing but constants are now
   evaluated at compile-time (as arithmetic expressions  have  always
   been),  and their constant values substituted.  This was necessary
   to  allow  for  Boolean  expressions  in   conditional-compilation
   statements.   Some of the statements which use Boolean expressions
   have been slightly  modified  to  produce  better  code  when  the
   Booleans  are constants. For instance, WHILE TRUE DO BEGIN ... END
   produces a simple loop, with no test at the top.  Some sort of  GO
   TO  or  DONE  or RETURN should appear in such a loop, or you might
   miss dinner.

b) The syntax attempts (and fails) to say that a  Boolean  expression
   will  be converted to a TRUE (non-zero) or FALSE (0) Integer value
   whenever it is used in a place which requires a number.  Until now
   the  compiler  has  kept  pace  with the syntax.  Only in certain,
   fortunately most common, instances  did  intention  coincide  with
   actuality.  It  is  my  belief  that  Boolean expressions now work
   entirely as they were intended to be advertised.   WARNING:  Since
   Boolean  EXPRESSIONS are turned into arithmetic PRIMARIES in these
   instances, you must parenthesize  them  correctly  or  they  still
   won't work.  This is not a bug.  It's not even a feature.  This is
   just how it is.

9-38.  Concatenation

Concatenation of constants is done  at  compile-time  when  possible.
This  has  always  been  true,  but  not  widely  advertised.  Avoid,
however, constructs like: STRVAR&"abc"&"cde" (or STRVAR&'15&'12,  for
that  matter.)  In  this case the compiler handles the concatenations
from left to right and entirely misses the fact that  there  are  two
constants there.  Use, instead: STRVAR&("abc"&"cde".)

9-42. Substrings
Substrings of constants, with constant  indices,  are  also  done  at

compile  time.   I think it is still necessary to parenthesize string
constants before applying substring operators to them, but this is  a

9-47. Function Designators

Many built-in functions, which return numeric or  string  values  and
have  no  side  effects, now are evaluated at compile time.  This was
again done to aid the conditional-compilation effort.  The ones  that
I  can  think  of  which work this way are: CVS, CVOS, CVE, CVF, CVG,
CVD, CVO, EQU.  There may be more.
9-39. Factors

a)  Negative  integer exponents do not work.  They have never worked.
   Instead of wasting my time writing about it, I  should  be  fixing
   it. Maybe I will.

b)  There  is  a  table in the manual which tells you this, but it is
   hard to find unless you know it's  there  already:  the  resultant
   type  of  an  exponentiation  (↑)  operation  is that of the first
   argument (the exponentiand?) Is this the  right  thing  to  do?  I
   don't know.

9-59. Precedence

Here is a `Precedence of Operators' table.  It  will  appear  in  the
next  manual.  Cut it out.  Put it in your purse or wallet. Operators
in the same line have the same precedence.  If op1 appears in a  line
above  op2,  op1  will  be  performed  first  (wherever  it makes any
difference).  Use parentheses to alter this order.

	* / % & MOD DIV LSH ROT
	+ - ⊗ ≡ LAND LOR
	= ≠ < ≤ > ≥
	∧ ∨


a) A lot of things in LEAP which haven't worked in the past will work
   in the future.  Try them out if you have been avoiding them.

b) IFGLOBAL will return TRUE for all item numbers in the GLOBAL range
   (7777  down  to the lowest Global Item used), even for those items
   which have since been deleted.

c) See Jim Low's opus for more LEAP changes.


12-7. Open (I/O buffer sizes)

A  note  about  I/O  buffer  sizes  is  in order here.  An I/O buffer
contains two words of system information (bits, links, etc.),  and  a
Data  Area.   The  data area includes a Word Count as its first word.
The system always arranges it so that the word count is not  confused
with  data,  if  you  do the standard thing (as SAIL does).  The word
count is irrelevant for DSK (and nearly so for magtape), since it  is
always (usually) a fixed value ('200 for DSK these days.)

The  size  which  you  specify  in  the  left  half of the `number of
buffers' parameter is interpreted as  the  size  of  the  Data  Area,
INCLUDING  THE  WORD  COUNT entry.  The maximum number of actual data
words which can fill the buffer  is  one  fewer  than  this.   As  an
example,  if  you  do  not  specify  a  buffer  size for DSK, and you
shouldn't, the default parameter is '201.  For  DECtapes,  since  the
word  count  is  actually  stored  as the first word of the '200 word
records, the default parameter is '200.

It is not necessary for you to do anything  about  this  word  count.
Just provide a space for it.

12-22. Fileinfo(Integer Array Infotab[1:6])

This  function has been in the system for some time.  I was surprised
to find that it was not documented.  The argument to  Fileinfo  is  a
6-word  Integer  Array (no more, no less).  This array is filled with
the 6 words obtained as a result of the last LOOKUP, ENTER, or RENAME
operation.   Unless  the  channel is open in a special mode, only the
first 4 words mean anything  (Name,  Ext  in  SIXBIT,  Dates,  Sizes,
etc.).   This  function  was originally provided for the File Purger,
which needs to know more about files  than  most  programs  do.   You
should only use it if you have a similar need.

12-53. Wordout

Wordout  should  now  accept arguments of both INTEGER and REAL type.
It will write  them  without  performing  any  conversions  on  them.
WORDIN  and  WORDOUT  will work in dump mode, but the results will be
terrible (one word per '200-word record).

12-69. Outstr

Outstr will stop typing either when the end of its  string  has  been
reached,  or  when  a  null  character  is encountered in the string.
Sometimes in the past this has been true, and  sometimes  it  hasn't.
Outstr has been rewritten an incredible number of times.

12-69. Inchwl

Inchwl  will  now  be  terminated  by any activation character.  That
character will be available in _SKIP_.  If it is  a  line  feed,  the
carriage-return  which  preceded it will have been discarded.  In the
past, only carriage-return line-feed combinations would terminate  an

14-2. What the Compiler Types

As each source page is encountered, SAIL will type its number on your
console.  This will be a bit confusing if your program REQUIRES other
source files, but it gives you something to do while waiting. If this
is irritating to anyone, we'll have to make it an option.

14-13. Legal Source Files

SAIL  now continues scanning past the final END token in your program
(in order to check the block name, if it's there, and  to  allow  the
last  line  to  print  in the listing file.) Everything which appears
after the final END must now be a valid token, although it  need  not
make sense syntactically (except for the block name, of course).

14-13.  Sharable Object Programs.

Include  the  /H  switch  in  your  compile  options if you wish your
program to be sharable.  When loaded, the code and constants will  be
placed in the second (write-protected) segment, while data areas will
be allocated in the lower, non-shared segment.  You  must  avoid  RPG
when  loading  these  programs,  and must use the HLBSAI library (see
Section 15 discussion).

14-20. Error Message Responses

The response: T {file name} will cause  the  TV  editor  to  be  used
instead  of  SOS.   The line in error will be CURRENT (see TV manual)
when you get control.  The syntax for the  (optional)  file  name  is
identical to that for the `E' response.


15-1. Sharable Object Programs

To  load  a program which has been compiled using /H (see 14-20), run
the LOADER directly,  then  respond:  *{ddt  switches}progname{,other
prog  names},/LSYS:HLBSAI/G<crlf>  The  sharable  library  HLBSAI  is
identical to LIBSAI, except that it expects  to  run  mostly  in  the
upper (shared) segment.

When  you  have  finished  loading,  in  order  to  write-protect the
sharable (second segment) portion, you'll have to deposit  (by  hand)
the following instructions:
134/	        211000 1	(MOVNI 0,1) INDICATES PROTECTION DESIRED
135/		47000 36	(CALLI 36)  SETS THE PROTECTION
136/		254200 0	(HALT)	    IN CASE IT DOESN'T SKIP (FAILED)
137/		47000 12	(CALLI 12)  EXIT ON COMPLETION

Then type: START 134, and SSAVE it when it exits (worry if it HALTS).
This feature should be used only if you have a program which is likely
to be used by a lot of people at once.


16-12. Assembly Language Procedures

This is probably an echo of a warning issued in Russ's document,  but
it  should be repeated here.  Register '12 has been commandeered as a
system register.  It should be  preserved  during  execution  of  any
procedure which doesn't need it for variable access.  In addition, it
MUST be stored in the User Table entry RACS+12  whenever  the  String
garbage  collector  (STRNGC) might be called.  Other runtime routines
(CAT, etc.) do this by storing '12 into this  location,  so  if  your
routine calls CAT, etc., it should be sure that '12 is correct.  SAIL
procedures will take care of all this automatically.


17-15.  Strings

The string number in the left half of the  first  word  of  a  string
descriptor  has  lost  much of its significance.  In fact, it is only
necessary for string constants (whose byte pointer addresses  do  not
lie  in  string  space)  to  have zero string numbers, and for string
non-constants to have non-zero string numbers.  In fact, many of  the
runtime routines now will set the string number to -1 (777777), since
this is often more economical than any other action.

17-31. Long Live Topstr

The User Table entry TOPSTR has been eradicated.  As such, you should
not  try to modify it.  Any procedures which you have written to keep
TOPSTR honest should be removed. It's always honest now.

			- 30 and Good Luck -
Chapter 7 -- How to use the new system D. Swinehart

The compiler will be available as SAIL.DMP[S,AIL] until it supercedes
the new one.  We may well invent a dummy processor name soon, so that
you can use RPG to invoke the new system, but we've not done it yet.

You   can   obtain   runtime   routines   from   the  new  libraries,
LIBSAI.REL[S,AIL] or HLBSAI.REL[S,AIL], or by  connecting  to  a  new
segment (SAISG3.SEG[S,AIL]).


To load with the LIBSAI library, type:
*{ddt options}filename{,filename...},/LLIBSAI[S,AIL]/G<crlf>

To load with the segment, type:
*SAILOW[S,AIL],{ddt options}filename{,filename ...}/G<crlf>.

An <altmode> can always be substituted for the /G<crlf> sequence.

Report any problems to Russ Taylor, Hanan  Samet,  Jim  Low,  or  Dan
Swinehart,  not  necessarily  (preferably?)  in  that  order.   We'll
guarantee about a two-day turnaround, or better -- if we can find the