perm filename NEWMAN[S,AIL] blob
sn#000829 filedate 1972-05-13 generic text, type T, neo UTF8
COMMENT ⊗ VALID 00009 PAGES
RECORD PAGE DESCRIPTION
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
00045 00008 SECTION 14. COMPILER OPERATION
00052 00009 Chapter 7 -- How to use the new system D. Swinehart
00054 ENDMK
⊗;
RECENT SAIL CHANGES
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
RECENT CHANGES TO SAIL
1. CASE J OF BEGIN [3]S1; [4]S2; [1]S3; [5]S4 END
is equivalent to
CASE J OF BEGIN
; COMMENT CASE 0 OMITTED;
S3; COMMENT CASE 1;
; COMMENT CASE 2 OMITTED;
S1; COMMENT CASE 3;
S2; COMMENT CASE 4;
S4 COMMENT CASE 5;
END.
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
GENERAL DISCUSSION:
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.
SAIL EXTENSION:
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:
EXTERNAL PROCEDURE K_ZERO;
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
declaration:
EXTERNAL PROCEDURE K_OUT;
PROFILE PROGRAM:
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
SAMPLE RUN:
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 . . .
EXIT
↑C
.R PROFIL
*FOO←FOO/T/S
EXIT
↑C
. 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
IMPENDING NEW SAIL SYSTEM
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
here:
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.
SECTION 3. DECLARATIONS
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
this.
SECTION 5. STATEMENTS
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.
SECTION 8. START_CODE
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.
SECTION 9. ALGEBRAIC EXPRESSIONS (sic)
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
bug.
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
MAX MIN
= ≠ < ≤ > ≥
∧ ∨
SECTION 10. ASSOCIATIVE EXPRESSIONS
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.
SECTION 12. EXECUTION TIME ROUTINES
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
Inchwl.
SECTION 14. COMPILER OPERATION
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.
SECTION 15. PROGRAM OPERATION
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:
LOCATION INSTRUCTION EXPL
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.
SECTION 16. PROGRAM STRUCTURE
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.
SECTION 17. IMPLEMENTATION INFORMATION
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]).
Examples:
To load with the LIBSAI library, type:
R LOADER
*{ddt options}filename{,filename...},/LLIBSAI[S,AIL]/G<crlf>
To load with the segment, type:
R LOADER
*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
bug.