perm filename DECMAN[X,AIL] blob
sn#000801 filedate 1973-08-19 generic text, type T, neo UTF8
COMMENT ⊗ VALID 00045 PAGES
RECORD PAGE DESCRIPTION
00001 00001
00011 00002
00015 00003 SAILON NO. 57.1 SAIL 2-0
00017 00004 SAILON NO. 57.1 SAIL 2-0.5
00018 00005 SAILON NO. 57.1 SAIL 3-7.5
00019 00006 SAILON NO. 57.1 SAIL 3-18.5
00020 00007 SAILON NO. 57.1 SAIL 3-20.5
00022 00008 SAILON NO. 57.1 SAIL 5-8.5
00024 00009 SAILON NO. 57.1 SAIL 9-7.5
00025 00010 SAILON NO. 57.1 SAIL 9-11
00028 00011 SAILON NO. 57.1 SAIL 9-12
00031 00012 SAILON NO. 57.1 SAIL 9-13
00035 00013 SAILON NO. 57.1 SAIL 9-14
00039 00014 SAILON NO. 57.1 SAIL 9-15
00042 00015 SAILON NO. 57.1 SAIL 9-15.5
00046 00016 SAILON NO. 57.1 SAIL 11-3
00051 00017 SAILON NO. 57.1 SAIL 11-4
00053 00018 SAILON NO. 57.1 SAIL 11-4.5
00055 00019 SAILON NO. 57.1 SAIL 12-0
00057 00020 SAILON NO. 57.1 SAIL 12-3
00061 00021 SAILON NO. 57.1 SAIL 12-4
00064 00022 SAILON NO. 57.1 SAIL 12-4.5
00067 00023 SAILON NO. 57.1 SAIL 12-7.5
00068 00024 SAILON NO. 57.1 SAIL 12-13.5
00070 00025 SAILON NO. 57.1 SAIL 12-27
00073 00026 SAILON NO. 57.1 SAIL 12-28
00075 00027 SAILON NO. 57.1 SAIL 12-28.5
00078 00028 SAILON NO. 57.1 SAIL 12-32.5
00079 00029 SAILON NO. 57.1 SAIL 12-34.5
00082 00030 SAILON NO. 57.1 SAIL 14-6.5
00084 00031 SAILON NO. 57.1 SAIL 18-1
00087 00032 SAILON NO. 57.1 SAIL 18-2
00090 00033 SAILON NO. 57.1 SAIL 18-3
00091 00034 SAILON NO. 57.1 SAIL 18-4
00092 00035 SAILON NO. 57.1 SAIL 18-5
00094 00036 SAILON NO. 57.1 SAIL 18-6
00095 00037 SAILON NO. 57.1 SAIL 18-7
00098 00038 SAILON NO. 57.1 SAIL 18-8
00099 00039 SAILON NO. 57.1 SAIL 18-9
00102 00040 SAILON NO. 57.1 SAIL 18-10
00106 00041 SAILON NO. 57.1 SAIL 18-11
00108 00042
00111 00043
00114 00044
00118 00045
00120 ENDMK
⊗;
COVER LETTER TO USERS OF THE DECUS-DISTRIBUTED SAIL
This manual comprises four documents: the SAIL manual (SAIL.ON),
a description of recent changes (NEWMAN), an implementation
guide (TELLEM, the "SAILmaker's Guide"), and a manual describing
the FAIL assembler (FAIL.ON). The user of SAIL should only have
to be concerned with the first two. The latter reports should
be read FIRST by anyone responsible for installation or
maintainance of SAIL. TELLEM, in particular, hopefully provides
an adequate description of the procedures necessary for installing
or modifying any part of the SAIL system.
The SAIL manual was originally written as a reference for those
already familiar with ALGOL60, and to some extent with SAIL.
It will not be comprehensible to anyone who is tackling Algol-like
languages for the first time. In addition, the organization of
sections is not conducive to an easy first reading. the suggested
order of approach (the first time only, is):
a). Read Section 11, on basic constructs (identifiers,
numbers, reserved words, and the like).
b). Section 9, on expressions.
c). Sections 4 and 5, statements.
d). Sections 2 and 3, block structure and declarations.
e). The remaining sections in numerical order, skipping
LEAPish chapters for now if you desire.
Even in this case, there will be some forward references, but this
should introduce the maximum number of terms before they are used.
The system is ideally distributed on 7-track magnetic tape. In
this case you will also receive a paper tape with a MACRO program
on it which will enable you to get the files off the magtape (see
TELLEM). The names mentioned above are the file names of these
documents, which are duplicated on the tape. The distribution tape
contains .REL files to get you started, as well as text files for all
parts of the system.
The system can also be obtained on DECtape, although you may not
receive all of the marginally useful files, which are thrown in
on the magtape simply because there's room and they might help.
Best of luck with SAIL. Please don't hesitate to report bugs
or problems to DECUS. If all else fails, we are available for
telephone or mail consultation at the address given on the cover.
SAILON NO. 57.1 SAIL 2-0
SYNTAX CHANGES
2-0.
The following changes should be applied to the syntax specifications
in the specified paragraphs.
In paragraph 3-1, add
<declaration> ::= <synonym_declaration>
<type_qualifier> ::= SHORT
<synonym_declaration> ::= LET <synonym_list>
<synonym_list> ::= <synonym>
::= <synonym_list> , <synonym>
<synonym> ::= <identifier> = <reserved_word>
<space_spec> ::= PNAMES
<relfile_spec> ::= SOURCE_FILE
In paragraph 3-1, remove
<require_element> ::= PNAMES
In paragraph 5-1, change
<case_statement> ::= <case_statement_head> <compound_tail>
::= <case_statement_head> <selected_tail>
<case_statement_head> ::= CASE <algebraic_expression> OF BEGIN
::= CASE <algebraic_expression> OF
BEGIN <block_name>
and add
<selected_tail> ::= <selected_statement> END
::= <selected_statement> END <block_name>
::= <selected_statement> ; <selected_tail>
<selected_statement> ::= [ <constant_expression> ] <statement>
SAILON NO. 57.1 SAIL 2-0.5
In paragraph 9-1, change
<algebraic_relational> ::= <bounded_expression>
::= <algebraic_relational>
<relational_operator>
<bounded_expression>
then add
<bounded_expression> ::= <adding_expression>
::= <bounded_expression> MAX
<adding_expression>
::= <bounded_expression> MIN
<adding_expression>
In paragraph 14-1, add
<valid_switch_name> ::= K
::= H
SAILON NO. 57.1 SAIL 3-7.5
3-13.5. SHORT Integers and Reals may take on values between -2↑27
and 2↑27-1 (the limit imposed by the FSC instruction). See section
9-23 and following for use of SHORT values.
SAILON NO. 57.1 SAIL 3-18.5
Synonyms
3-54.5 The declaration `LET BEG=BEGIN' would tell the compiler that
BEG is now a reserved word with the same meaning as BEGIN. BEGIN can
subsequently be DEFINEd or declared as something else without
eliminating the opening of new blocks (use BEG for BEGIN). This
synonymity applies only over the scope of the declaration, as usual.
SAILON NO. 57.1 SAIL 3-20.5
3-58.5. (Replaces paragraph 3-57) "REQUIRE 100 PNAMES" will allow up
to 100 print names to be dynamically assigned to items (see Cvis,
New_Pname). PNAMES are not available at all (for declared items or
otherwise), unless some number are "REQUIRE"d.
3-61.3. The inclusion of REQUIRE "SYS:PREAMB.SAI" SOURCE_FILE (or,
perhaps, ... "PREAMB.SAI[1,3]" ...) will cause the compiler to save
the state of the current input file, then begin scanning from PREAMB.
When PREAMB is exhausted, SAIL will resume scanning the original file
on the line directly following the REQUIRE. SOURCE_FILEs may be
nested to a depth of about 10 levels.
3-61.6. Restrictions: A SOURCE_FILE request must be followed by a
semicolon (only one per REQUIREment), and must be the last text on
the line in which it appears. SOURCE_FILE switching must not be
specified from within a DEFINE body.
SAILON NO. 57.1 SAIL 5-8.5
5-18.3. The <selected_tail> form of the CASE statement is provided
to aid the creation of Case selection when the code used to select
an alternative is arbitrary, perhaps even symbolically defined. The
statement
CASE AE OF BEGIN
[3] S3; [0] S0; [n] Sn; ... [1] S1
END
will have the same result as the example in paragraph 5-18, provided
n is the largest expression to appear between brackets. If for some
i (0 ≤ i ≤ n) no entry appears, executions of the statement selecting
these cases will have no effect (dummy statements).
5-18.6. This construct, in other words, allows the explicit ordering
of statements within a CASE statement.
5-18.9. If a block name appears after the BEGIN, as described in the
new syntax, paragraph 2-0, then any name appearing after the matching
END will be checked for equality to the BEGIN name, as with blocks and
compound statements.
SAILON NO. 57.1 SAIL 9-7.5
9-13.5 MAX and MIN have a precedence higher than (are performed
before) ∧, but lower than + (see Bounded Expressions).
SAILON NO. 57.1 SAIL 9-11
9-22.
OPERATION ARG1 ARG2 ARG1' ARG2' RESULT
+ - INT INT INT INT INT*
* ↑ % REAL INT REAL REAL REAL
MAX MIN INT REAL REAL REAL REAL
REAL REAL REAL REAL REAL
LAND LOR INT INT INT INT INT
EQV XOR REAL INT REAL INT REAL
INT REAL INT REAL INT
REAL REAL REAL REAL REAL
LSH ROT INT INT INT INT INT
REAL INT REAL INT REAL
INT REAL INT INT INT
REAL REAL REAL INT REAL
/ INT INT REAL REAL REAL
REAL INT REAL REAL REAL
INT REAL REAL REAL REAL
REAL REAL REAL REAL REAL
MOD DIV INT INT INT INT INT
REAL INT INT INT INT
INT REAL INT INT INT
REAL REAL INT INT INT
* Unless ARG2 is <0 for the operator ↑
9-23. An Integer is converted to a Real number in such a way that
if this Real number is converted back to an Integer, the same Integer
value will result, unless the absolute value of the number is greater
than 134217728. Some low-order significance will be lost for
integers greater than this magnitude.
9-23.5 If the Integer is a SHORT INTEGER variable, or the Real is
SHORT REAL, the conversion is done with a FSC instruction, much more
efficiently (a factor of about 8) than the normal UUO.
SAILON NO. 57.1 SAIL 9-12
9-24. A Real number is converted to an Integer using the following
formula:
Integer ← SIGN(Real)*{largest integer I such that I≤ABS(Real)}.
This function will produce invalid results for Real numbers with a
magnitude greater than 134217728.
9-25. If a String is presented as an argument to any of these
operations, it is converted to an Integer. If an Integer or Real
argument is presented to the concatenation operator (&), it is
converted to a one-character string. Here are the rules:
String-Arithmetic Conversions
9-26. If a String is presented as an argument to an arithmetic
operator, as a (value) parameter to a procedure which expects a Real
or Integer value, or as an expression to be stored by an assignment
statement into a Real or Integer variable, an Integer value is
created for it as follows:
If the string is the null string (length=0), a 0 is returned as
its `Integer value'. Otherwise a word which has its lefthand 29 bits
0, the rightmost 7 bits containing the first character of the String,
is returned as its `Integer value'. For instance, the String "ABCDE"
has as its `Integer value' '101, the octal representation of the
letter `A'. This Integer will then be converted to a Real number, if
necessary.
SAILON NO. 57.1 SAIL 9-13
9-27. If an Integer or Real number is presented where a String is
expected, a one character String will be created whose character
consists of bits 29-35 (the rightmost seven bits) of the numeric
value. A Real number is not converted to an Integer before the
conversion. For instance, the expression
"STRING"& '15 & '12
will result in a String which is 8 characters long. The last two
characters are the ASCII codes for carriage return and line feed,
respectively.
Bounded Expressions
9-27.5 A MAX B (where A and B are appropriate expressions -- see
the Syntax) has the value of the larger of A and B (in the algebraic
sense). Type conversions are performed as if the operator were `+'.
0 MAX X MIN 10 is X if 0≤X≤10, 0 if X<0, 10 if X>10.
Adding Expressions
9-28. All the operators grouped in the semantic class
<add_operator> operate at the same precedence level. The user must
sometimes provide parentheses in order to make the meaning of such
expressions absolutely unambiguous. The + and - operators will do
integer addition (subtraction) if both arguments are integers (or
converted to integers from strings); otherwise, rounded Real addition
or subtraction, after necessary conversions, is done.
9-29. LAND, LOR, XOR, and EQV carry out bit-wise And, Or,
Exclusive Or, and Equivalence operations on their arguments. No type
conversions are done for these functions. The logical connectives ∧
and ∨ do not have this effect -- they simply cause tests and jumps to
be compiled. The type of the result is that of the first operand.
This allows expressions of the form X LAND '777777777, where X is
Real, if they are really desired.
9-30. Currently the values of the various overflow flags produced
by these operators (and those which follow) are not available to the
user.
SAILON NO. 57.1 SAIL 9-14
Terms
Arithmetic Multiplicative Operators
9-31. The operation * (multiplication), like + and -, represents
Integer multiplication only if both arguments are integers; Real
otherwise. Integer multiplication uses the IMUL machine instruction
-- no double-length result is available.
9-32. The / operator (division) always does rounded Real division,
after converting any Integer arguments to Real.
9-33. The % operator has the same type table as +, -, and *. It
performs whatever division is appropriate.
9-34. LSH and ROT provide logical shift operations on their first
arguments. If the value of the second argument is positive, a shift
or rotation of that many bits to the left is performed. If it is
negative, a right-shift or rotate is done. To obtain an arithmetic
shift (ASH) operation, multiply or divide by the appropriate power of
2; the compiler will change this operation to a shift operation.
9-35. DIV and MOD force both arguments to be integers before
dividing. X MOD Y is the remainder after X DIV Y is performed
(X MOD Y = X - (X DIV Y)*Y);
Concatenation Operator
9-36. This operator produces a result of type String. It is the
String with length the sum of the lengths of its arguments,
containing all the characters of the second string concatenated to
the end of all the characters of the first. The operands will first
be converted to strings if necessary as described in
String-Arithmetic Conversions, 9-27 above. The normal use of the &
operator is to collect lines of text, from several other string
sources, which will subsequently be sent to an output device.
Numbers can be converted to strings representing their external forms
(and vice-versa) through explicit calls on execution time routines
like CVS and CVD (see Execution Routines, 12-1 below).
SAILON NO. 57.1 SAIL 9-15
Factors
9-37. A factor is either a primary or a primary raised to a power
represented by another primary. As usual, evaluation is from left to
right, so that A↑B↑C is evaluated as (A↑B)↑C. In the factor X↑Y, a
suitable number of multiplications and additions is performed to
produce an "exact" answer if Y is a positive integer. Otherwise a
routine is called to approximate ANTILOG(Y LOG X). The result has
the type of X in the former case. It is always of type Real in the
latter.
Primaries
9-38. A primary represents an arithmetic or String value which
always acts as a unit in any binary operation. It is either an
expression surrounded by parentheses which indicates that all
internal operations should be performed before combining it with
other things, or one of myriad other constructs which will be
considered separately.
Variables and Constants
9-39. These are clearly primary objects. They are values
contained in specific core locations, or in parameter stacks, or in
the case of some numeric constants, they are immediate operands.
Substrings
9-40. A String primary which is qualified by a substring
specification represents a part of the specified string. ST[X FOR Y]
represents the Xth through the (X + Y - 1)th characters of the String
ST. ST[X TO Y] represents the Xth through Yth characters of ST.
SAILON NO. 57.1 SAIL 9-15.5
9-40.2. Consider the ST[X TO Y] case. If Y>LENGTH(ST), Y←LENGTH(ST).
if Y<0, Y←0; in either case the right half of the global Integer
_SKIP_ is set to TRUE. If X ≤ 1 it is set to 1. If X > (the
modified) Y, it is set to Y+1 (null string guaranteed). In either
case the left half of _SKIP_ is made TRUE. The ST[X FOR Y] operation
is converted to the ST[X TO Y] case before the substring operation is
performed.
9-40.4. To examine the above conditions, declare EXTERNAL INTEGER
_SKIP_, and look at it after any interesting substring operation.
Special Length Operator (∞)
9-41. This special primary construct is valid only within
substring brackets. It is an algebraic value representing the length
of the most immediate string under consideration.
Example:
9-42.
A[4 to ∞] throws out the first 3 characters of A.
A[3 for B[∞-1 for 1]] uses the next to the last character
of string B as the number of characters
for the A substring operation.
Function Designators
9-43. A function designator defines a single value. This value is
produced by the execution of a typed user Procedure or of a typed
execution-time routine (Execution Routines, 12-1). For a function
designator to be an algebraic primary, its Procedure must be declared
to have an algebraic type. Untyped Procedures may only be called
from Procedure statements (see Procedure Statements, 6-2). The value
obtained from a user-defined Procedure is that provided by a Return
Statement within that Procedure. If the Procedure does not execute a
Return Statement, the value might be anything at all. A Return
Statement in a typed Procedure must mention a value (see Return
Statement, 5-20).
9-44. The rules for supplying actual parameters in a function
designator are identical to those for supplying parameters in a
procedure statement (see Procedure Statements, 6-2).
SAILON NO. 57.1 SAIL 11-3
11-8. A SAIL letter is any of the upper or lower case letters A
through Z, or the underline character (_ or !, they are treated
equivalently). Lower case letters are mapped into the corresponding
upper case letters for purposes of symbol table comparisons (SCHLUFF
is the same symbol as Schluff). A digit is any of the characters 0
through 9. An identifier is a string of characters consisting of a
letter followed by virtually any number of letters and digits There
must be a character which is neither a letter nor a digit (nor either
of the characters "." or "$") both before and after every identifier.
In other words, if YOU can't determine where one identifier ends and
another begins in a program you have never seen before, well, neither
can SAIL.
11-9. There is a set of identifiers which are used as SAIL
delimiters (in the Algol sense -- that is, BEGIN is treated by Algol
as if it were a single character. Such an approach is not practical,
so a reserved identifier is used). These identifiers are called
Reserved Words and may not be used for any purpose other than those
given explicitly in the syntax, or in declarations (DEFINES) which
mask their reserved-word status over the scope of the declarations.
E.g., "INTEGER BEGIN" is allowed, but a Synonym (see Synonyms, 3-55)
should have been provided for BEGIN if any new blocks are desired
within this one, because BEGIN is ONLY an Integer in this block.
Another set of identifiers have preset declarations -- these are the
execution time functions. These latter identifiers may also be
redefined by the user; they behave as if they were declared in a
block surrounding the outer block. A list of reserved and
predeclared identifiers follows:
Sail Reserved Words
11-10.
ABS AND ANY ARRAY ARRAY_PDL ASSOC BBPP BEGIN BOOLEAN CASE COMMENT
CONTINUE COP CVI CVN DATUM DEFINE DELETE DIV DO DONE DPB ELSE END
ENTRY EQV ERASE EXTERNAL FALSE FIRST FOR FOREACH FORTRAN FORWARD FROM
GEQ GO GOTO IBP IDPB IF ILDB IN INF INTEGER INTER INTERNAL ISTRIPLE
ITEM ITEMVAR LABEL LAND LDB LENGTH LEQ LET LIBRARY LOAD_MODULE LNOT
LOP LOR LSH MAKE MAX MIN MOD NEEDNEXT NEQ NEXT NEW NEW_ITEMS NOT NULL
OF OR OWN PHI PNAMES PRELOAD_WITH PROCEDURE PUT QUICK_CODE REAL
RECURSIVE REFERENCE REMOVE REQUIRE RETURN ROT SAFE SECOND SET SETC
SETO SHORT SOURCE_FILE START_CODE STEP STRING STRING_PDL STRING_SPACE
SUCH SYSTEM_PDL THAT THEN THIRD TO TRUE UNTIL VALUE WHILE XOR
SAILON NO. 57.1 SAIL 11-4
11-10.5 Those who use Stanford's "Global Model" compiler will also
recognize:
GLOBAL MESSAGE SEGMENT_FILE SEGMENT_NAME
Sail Predeclared Identifiers
11-11.
ARRBLT ARRINFO ARRTRAN ARRYIN ARRYOUT BREAKSET CALL CLOSE CLOSIN
CLOSO CLRBUF CODE CVASC CVD CVE CVF CVFIL CVG CVIS CVO CVOS CVS CVSI
CVSIX CVSTR CVXSTR ENTER EQU FILEINFO GETCHAN GETFORMAT INCHRW INCHRS
INCHSL INCHWL INSTR INSTRL INSTRS INPUT INTIN INTSCAN LINOUT LOOKUP
MTAPE OPEN OUT OUTCHR OUTSTR REALIN REALSCAN RELEASE RENAME SCAN
SETBREAK SETFORMAT STRBRK TTYIN TTYINL TTYINS WORDIN WORDOUT USERCON
USERERR USETI USETO
11-11.5 These apply only to Stanford users (especially "Global
Model" users): BACKUP GET_BIT GET_DATA GET_ENTRY IFGLOBAL ISSUE LODED
PTCHRS PTCHRW PTIFRE PTOCNT PTOCHS PTOCHW PTOSTR PTYALL PTYGET PTYIN
PTYREL PTYSTR PUT_DATA QUEUE
SAILON NO. 57.1 SAIL 11-4.5
11-12.5 Some of the reserved words are equivalent to certain
special characters. These equivalences are:
CHARACTER RESERVED WORD (s)
∧ AND
≡ EQV
¬ NOT
∨ OR
⊗ XOR
∞ INF
ε IN
| SUCH THAT
≠ NEQ
≤ LEQ
≥ GEQ
{ SETO "set open"
} SETC "set close"
∪ UNION
∩ INTER
` ASSOC for derived sets
↔ SWAP
_ ! alternate underline
Arithmetic Constants
11-13.
12369 is an Integer with decimal value 12369
'12357 is an Integer constant with octal value 12357
123. is a Real constant with floating point value 123.0
0123.0 is a Real constant with floating point value 123.0
.524 is a Real constant with floating point value 0.524
5.3@4 is a Real constant with floating point value 53000.0
5.342@-3 is a Real constant with value 0.005342
11-14. The character ' (right quote) precedes a string of digits
to be converted into an OCTAL number.
SAILON NO. 57.1 SAIL 12-0
EXECUTION TIME ROUTINE OPTIONS
12-0. The Execution Time routines are available in many forms:
a. As a single file, RUNTIM.REL (not advised)
b. As a library of one-segment (low) files, LIBSAI.REL
c. As a library of HISEG files, HLBSAI.REL (for use with
programs compiled using /H)
d. As a sharable segment containing all the routines (SAISG1.SHR).
Methods for using and creating these files are described in detail
in the SAILmaker's Guide, which accompanies this manual. You should
ignore descriptions of the form of the runtimes (library, segment,
etc.) throughout the remainder of the manual; the definitive word
shall be found in the SAILmaker's Guide. This guide is on the
distribution tape as TELLEM.
SAILON NO. 57.1 SAIL 12-3
Function:
12-7. SAIL input/output operates at a very low level in the
following sense: the operations necessary to obtain devices, open and
close files, etc., are almost directly analogous to the system calls
used in assembly language. OPEN is used to associate a channel
number (0 to '17) with a device, to determine the data mode of the
I/O to occur on this channel (character mode, binary mode, dump mode,
etc.), to specify storage requirements for the data buffers used in
the operations, and to provide the system with information to be used
for input operations.
CHANNEL is a user-provided channel number which will be used in
subsequent I/O operations to identify the device. CHANNEL may
range from 0 to 15 ('17). If some file is already open on
this channel, a RELEASE will be performed for that channel
before the OPEN is executed.
DEVICE must be a String (i.e. "TTY", "DATA") which is recognizable
by the system as a physical or logical device name.
MODE is the data mode for the I/O operation. MODE 0 will always
work for characters ( see Input, 12-40 and Out, 12-45). Modes
8 ('10) and 15 ('17) are applicable for binary and dump-mode
operations using the functions WORDIN, WORDOUT, ARRYIN, or
ARRYOUT (see Wordin, 12-48 and following). For other data
modes, see [Moorer].
If any of bits 18-21 are on in the MODE word, the I-O routines
will not print error messages when data errors occur which
present the corresponding bits as a response to the GETSTS
UUO. Instead, the GETSTS bits will be reported to the user as
described under EOF below. If bit 23 is on, no error message
will be printed if an invalid file name specification is
presented to LOOKUP, ENTER, or RENAME, a code identifying the
problem will be returned (see Lookup, Enter, 12-17 and
following, Rename, 12-21 for details). If you don't
understand any of this, leave all non-mode bits off in the
MODE word.
SAILON NO. 57.1 SAIL 12-4
NUMBER_OF{INPUT/OUTPUT}_BUFFERS specifies the number of buffers to be
reserved for the I/O operations (see [Moorer] for details).
At least one buffer must be specified for input if any input
is to be done in modes other than '17; similarly for output.
If data is only going one direction, the other buffer
specification should be 0. Two buffers give reasonable
performance for most devices (1 is sufficient for a TTY, more
are required for DSK if rapid operation is desired).
The left half of the BUFFER parameter, if non-zero, specifies
the buffer size for the I/O buffers. Use this only if you
desire non-standard sizes.
12-8. The remaining arguments are applicable only for INPUT
(String input). They will be ignored for any other operations
(although their values may be changed by the Open function).
COUNT designates a variable which will contain the maximum number
of characters to be read from "DEVICE" in a given INPUT
call (see Input, 12-40, Breakset, 12-22). Fewer characters
may be read if a break character is encountered or if an
end of file is detected. The count should be a variable or
constant (not an expression), since its address is stored,
and the temporary storage for an expression may be re-used.
BRCHAR designates a variable into which the break character (see
INPUT and BREAKSET again) will be stored. This variable
can be tested to determine which of many possible
characters terminated the read operation.
SAILON NO. 57.1 SAIL 12-4.5
EOF designates a variable to be used for two purposes:
1) If EOF is 0 when OPEN is called, a SAIL error message will
be invoked if the device is not available. The user will
be given the options of retrying or terminating the
operation. If EOF is non-zero when OPEN is called, it will
be set to 0 if the OPEN is successful. Otherwise it will
not be changed. In this case (EOF non-zero on entry)
control will be returned to the user. This flag may then
be tested.
2) EOF will be made non-zero (TRUE) if an end of file
condition, or any error condition among those enabled (see
MODE, above) is detected during any SAIL input/output
operation. It will be 0 (FALSE) on return to the user
otherwise. Subsequent inputs after an EOF return will
return non-zero values in EOF and a null String result for
INPUT. For ARRYIN , a 0 is returned as the value of the
call after end of file is detected. If EOF is TRUE after
such an operation, it will contain the entire set (18 bits)
of GETSTS information in the left half. The EOF bit is
'20000, and is the only one you'll ever see if you haven't
specially enabled for others. A summary of the enable
bits, the EOF and error bits, and their meanings is
contained in the Appendix NON-FATAL ERROR, EXCEPTIONAL
CONDITION RETURN CODES, 18-11.
SAILON NO. 57.1 SAIL 12-7.5
12-19.5 An additional return code, '10, has been added to the
error return possibilities from LOOKUP, ENTER, and RENAME.
This code indicates that the punctuation or syntax of the file
name string was invalid. This code will be returned only if
the appropriate enable bit ('10000) was on in the MODE word at
OPEN time (see Open). It is possible that this code conflicts
with some recent DEC additions. For that I am sorry.
SAILON NO. 57.1 SAIL 12-13.5
NOTE CONCERNING EOF VARIABLE, ERROR CONDITIONS
12-39.5. In the Input Function whose description follows, an in all
subsequent I/O operation descriptions, you should amend any comments
concerning the value of the EOF variable to include possible error
conditions (if you are enabled for errors, you must specifically
check for the end of file bit). The full description of the changes
can be gleaned from the description of Open, 12-6, and from the
error condition summaries in Section 18. The changes should rightly
be distributed to all I/O discussions. Maybe some day they will.
SAILON NO. 57.1 SAIL 12-27
Function:
12-82. The decimal Integer representation of VALUE is produced as
an ASCII String with leading zeroes omitted (unless WIDTH has been
set by Setformat, 12-75 to some negative value). "-" will be
concatenated to the String representing the decimal absolute value of
VALUE if VALUE is negative.
Cvos
Form:
12-83. "ASCII_STRING" ← CVOS ( VALUE );
Function:
12-84. The octal Integer representation of VALUE is produced as an
ASCII String with leading zeroes omitted (unless WIDTH has been set
to some negative value by Setformat, 12-75). No "-" will be used to
indicate negative numbers. For instance, -5 will be represented as
"777777777773".
Cvis
Form:
12-85. "STRING" ← CVIS ( ITEM , @FLAG ) ;
Function:
12-86. The print name of ITEM is returned as a string. An Item's
print name is the identifier used to declare it, or that provided by
the NEW_PNAME function (see New_Pname, 12-88). FLAG is set to FALSE
(0) if the appropriate string is found. Otherwise it is set to TRUE
(-1), and you should not place great faith in the string result.
SAILON NO. 57.1 SAIL 12-28
Cvsi
Form:
12-87. ITEM ← CVSI ( "PNAME" , @FLAG ) ;
Function:
12-88. The Item whose identifier (or name provided by New_Pname,
12-88.2) is the same as the string argument. PNAME is returned and
FLAG set to FALSE if such an Item exists. Otherwise, something very
random is returned, and FLAG is set to TRUE.
New_Pname
Form:
12-88.2
NEW_PNAME (ITEM , "STRING" )
Function:
12-88.4 This function assigns to the Item the name "STRING". Don't
perform this twice for the same Item without first deleting the
previous one. The corresponding name or Item may be retrieved using
CVIS or CVSI (above). You must use the REQUIRE n PNAMES construct in
one of the files comprising your program for all this to work.
Del_Pname
Form:
12-88.6
DEL_PNAME ( ITEM )
SAILON NO. 57.1 SAIL 12-28.5
Function:
12-88.8 This function deletes any string PNAME associated with this
Item.
Cve, Cvf, Cvg
Form:
12-89.
"STRING" ← CVE ( VALUE ); "STRING" ← CVF ( VALUE ); "STRING" ← CVG (
VALUE );
Function:
12-90. Real number output is facilitated by means of one of three
functions CVE,CVG, or CVF, corresponding to the E,G, and F formats of
FORTRAN IV. Each of these functions takes as argument a real number
and returns a string. The format of the string is controlled by
another function SETFORMAT ( WIDTH,DIGITS) (see Setformat, 12-75)
which is used to change WIDTH from zero and DIGITS from 7, their
initial values. WIDTH specifies the minimum string length. If WIDTH
is positive leading blanks will be inserted and if negative leading
zeros will be inserted.
12-91. The following table indicates the strings returned for some
typical numbers. _ indicates a space and it is assumed that WIDTH←10
and DIGITS←3.
CVF CVE CVG
______.000 __.100@-3_ __.100@-3_
______.001 __.100@-2_ __.100@-2_
______.010 __.100@-1_ __.100@-1_
______.100 __.100____ __.100____
_____1.000 __.100@1__ __1.00____
____10.000 __.100@2__ __10.0____
___100.000 __.100@3__ __100.____
__1000.000 __.100@4__ __.100@4__
SAILON NO. 57.1 SAIL 12-32.5
12-107.5 The global variable _SKIP_ (accessed by declaring it as
EXTERNAL INTEGER _SKIP_) will be 0 if no errors occurred, ≠0 if an
invalid file name specification is presented.
SAILON NO. 57.1 SAIL 12-34.5
Usercon
Form:
12-117.2
USERCON ( @INDEX , @VALUE , FLAG )
Function:
12-117.4 This function allows inspection and alteration of the
"User Table" (see User Table, 17-1). Declare an index you are
interested in as an External Integer (e.g., EXTERNAL INTEGER REMCHR).
This will, when loaded, give an address which is secretly a small
Integer index into the User Table. When passed by reference, this
index is available to USERCON. The names and meanings of the various
User Table indices can be found in the file HEAD, wherever SAIL
compiler program text files are sold.
12-117.6 USERCON always returns the current value of the
appropriate User Table entry (the Global Upper Segment Table is used
if FLAG is negative and your system knows about such things). If
FLAG is odd, the contents of VALUE before the call replaces the old
value in the selected entry of the selected table.
12-117.8 By now the incredible danger of this feature must be
apparent to you. Be sure you understand the ramifications of any
changes you make to any User Table value.
SAILON NO. 57.1 SAIL 14-6.5
K If a listing file is also specified, it is written in a
special format. In addition, when the object program
runs, it will generate a special file whose name is the
same as the listing file name, and whose extension is
.KNT. These files may later be merged using the PROFIL
program to obtain execution counts for each line of the
program. More details will be found in the document
NEWMAN, which lists recent changes. NEWMAN is appended
to this document, and is contained on the distribution
tape.
H If this switch is on, and your installation supports
the feature, SAIL will generate a TWOSEG pseudo-op in
the beginning of the .REL file, and will thereafter
generate its output such that the code and constants
will be loaded into the upper segment, the data into
the lower. When the program is SSAVEd after loading,
it will constitute a sharable (re-entrant) program.
This feature is useful only if the program will be used
on a production basis, so that sharing becomes likely.
Again, see NEWMAN for more details.
SAILON NO. 57.1 SAIL 18-1
SECTION 18
APPENDIX -- USEFUL SUMMARIES
ARITHMETIC TYPE-CONVERSION TABLE
18-1.
OPERATION ARG1 ARG2 ARG1' ARG2' RESULT
+ - INT INT INT INT INT*
* ↑ % REAL INT REAL REAL REAL
MAX MIN INT REAL REAL REAL REAL
REAL REAL REAL REAL REAL
LAND LOR INT INT INT INT INT
EQV XOR REAL INT REAL INT REAL
INT REAL INT REAL INT
REAL REAL REAL REAL REAL
LSH ROT INT INT INT INT INT
REAL INT REAL INT REAL
INT REAL INT INT INT
REAL REAL REAL INT REAL
/ INT INT REAL REAL REAL
REAL INT REAL REAL REAL
INT REAL REAL REAL REAL
REAL REAL REAL REAL REAL
MOD DIV INT INT INT INT INT
REAL INT INT INT INT
INT REAL INT INT INT
REAL REAL INT INT INT
* Unless ARG2 is <0 for the operator ↑
SAILON NO. 57.1 SAIL 18-2
SAIL RESERVED WORDS
18-2.
ABS AND ANY ARRAY ARRAY_PDL ASSOC BBPP BEGIN BOOLEAN CASE COMMENT
CONTINUE COP CVI CVN DATUM DEFINE DELETE DIV DO DONE DPB ELSE END
ENTRY EQV ERASE EXTERNAL FALSE FIRST FOR FOREACH FORTRAN FORWARD FROM
GEQ GLOBAL GO GOTO IBP IDPB IF ILDB IN INF INTEGER INTER INTERNAL
ISTRIPLE ITEM ITEMVAR LABEL LAND LDB LENGTH LEQ LET LIBRARY
LOAD_MODULE LNOT LOP LOR LSH MAKE MAX MESSAGE MIN MOD NEEDNEXT NEQ
NEXT NEW NEW_ITEMS NOT NULL OF OR OWN PHI PNAMES PRELOAD_WITH
PROCEDURE PUT QUICK_CODE REAL RECURSIVE REFERENCE REMOVE REQUIRE
RETURN ROT SAFE SECOND SEGMENT_NAME SEGMENT_FILE SET SETC SETO SHORT
START_CODE STEP STRING STRING_PDL STRING_SPACE SOURCE_FILE SUCH SWAP
SYSTEM_PDL THAT THEN THIRD TO TRUE UNTIL VALUE WHILE XOR
SAIL PRE-DECLARED IDENTIFIERS
18-3.
ARRBLT ARRINFO ARRTRAN ARRYIN ARRYOUT BACKUP BREAKSET CALL CLOSE
CLOSIN CLOSO CLRBUF CODE CVASC CVD CVE CVF CVFIL CVG CVIS CVO CVOS
CVS CVSI CVSIX CVSTR CVXSTR ENTER EQU FILEINFO GETCHAN GETFORMAT
INCHRW INCHRS INCHSL INCHWL INSTR INSTRL INSTRS INPUT INTIN INTSCAN
LINOUT LODED LOOKUP MTAPE OPEN OUT OUTCHR OUTSTR PTCHRS PTCHRW PTIFRE
PTOCNT PTOCHS PTOCHW PTOSTR PTYALL PTYGET PTYIN PTYREL PTYSTR REALIN
REALSCAN RELEASE RENAME SCAN SETBREAK SETFORMAT STRBRK TTYIN TTYINL
TTYINS WORDIN WORDOUT USERCON USERERR USETI USETO
SAILON NO. 57.1 SAIL 18-3
CHARACTER-IDENTIFIER EQUIVALENCES
18-4.
CHARACTER RESERVED WORD
∧ AND
≡ EQV
¬ NOT
∨ OR
⊗ XOR
∞ INF
ε IN
| SUCH THAT
≠ NEQ
≤ LEQ
≥ GEQ
{ SETO
} SETC
∪ UNION
∩ INTER
` ASSOC
↔ SWAP
_ !
SAILON NO. 57.1 SAIL 18-4
PARAMETERS TO THE OPEN FUNCTION
18-5.
CHANNEL System Data Channel, 0-'17
DEVICE string giving device name
MODE data mode, bits 18-21, 23 enable error returns
INBUFS number of input buffers, lh buffer size if ≠0
OUTBUFS number of output buffers
COUNT text input count (reference)
BRCHAR break char variable (reference)
EOF end-of-file and IO error flag (reference)
SAILON NO. 57.1 SAIL 18-5
BREAKSET MODES
18-6.
I (Inclusion) string is set of break chars
X (eXclusion) string of all non-break chars
O (Omit) string of characters to be omitted from result
S (skip) break char appears only in BRCHAR variable
A (Append) break char is last char of result string
R (Retain) break char is first char of next string
P (Pass) line numbers appear in input without warning
N (No numbers) line numbers and the tabs that follow them
are removed.
L (Line no break) line numbers cause input break. BRCHAR
is negative. Next input gets line no characters.
E (Erman) line numbers cause input break. Negated line no
returned in BRCHAR. Line no removed from input.
D (Display) after this appears, each line no is listed on
the display (if TTY is a DPY) as it is dealt with.
SAILON NO. 57.1 SAIL 18-6
MTAPE COMMANDS
18-7.
MODE FUNCTION
"A" Advance past one tape mark (or file)
"B" Backspace past one tape mark
"F" Advance one record
"R" Backspace one record
"W" Rewind tape
"E" Write tape mark
"U" Rewind and unload
SAILON NO. 57.1 SAIL 18-7
COMMAND SWITCHES
18-8.
D double size of define pushdown stack
numL listing control -- num>0 becomes listing starting addr.
num=-1 starts listing after current DDT size. num=-2
starts listing after current RAID size.
numM initial debugging mode set to num
P double size of system pushdown list
Q double size of string pushdown list
R double size of parse pushdown list
numS set size of string space to num
C create CREF (cross-reference) input file.
numF enable various listing formats.
K (requires listing file) -- issue special listing file and
code to create .KNT file after object program execution
for later use with the PROFIL program analyzer.
H object code will be loaded and run in two segments. The
upper segment may be shared, making some savings possible.
DEBUGGING MODES
18-9.
1 display before executing each code generation routine
2 don't display, but remain enabled for asynchronous and
line breaks
3 display before each production is compared
4 continue from type 1 and 3 modes automatically
5 just display input file as it goes past
6 disable debugging mechanism (started in this mode unless
an M switch appears).
SAILON NO. 57.1 SAIL 18-8
VALID RESPONSES TO ERROR MESSAGES
18-10.
CR (carriage return) try to continue
LF (line feed) continue automatically -- don't stop for
user go-ahead after each message
S restart
X exit -- close all files, return to monitor
L look at stacks -- of interest only to compiler fixers
E edit. Follow by CR to get file the compiler is working
on (or last thing edited, for runtime routines). Follow
with <name> CR to edit <name>.
D go to DDT or RAID
SAILON NO. 57.1 SAIL 18-9
NON-FATAL ERROR, EXCEPTIONAL CONDITION RETURN CODES
18-11.
ROUTINE CODE LOCATION CONDITIONS, CODE VALUES
CALL _SKIP_ set TRUE if the UUO skips, FALSE otherwise
CODE _SKIP_ set TRUE if the constructed instruction
skips, FALSE otherwise
CVFIL _SKIP_ set TRUE if the file input is invalidly
specified (wrong punctuation, order, etc.),
FALSE otherwise.
CVIS FLAG param set TRUE if no PNAME exists for this Item,
FALSE if CVIS succeeds.
CVSI FLAG param set TRUE if no Item exists with this String
as PNAME, FALSE if CVSI succeeds.
ENTER FLAG param set FALSE if the ENTER succeeds. Otherwise,
the left half is made -1. Then if the file
name was invalid, the right half is made
'10. Otherwise it is set to some code from
0 to 7, depending on the type of ENTER
failure. These codes are the same as the
ENTER UUO codes in [Moorer]. If error '10
(invalid spec.) is returned, an error
message (non-fatal) will also be printed,
unless you are enabled for user handling of
this error (see I/O below).
GETCHAN result <0 if no channel is available.
INCHRS result <0 if no characters are waiting.
INCHSL FLAG param ≠0 if no characters are waiting.
INSTRS FLAG param ≠0 if no characters are waiting.
SAILON NO. 57.1 SAIL 18-10
I/O EOF vbl. 0 if no exceptional conditions occurred in
an I/O operation. Otherwise, the left half
has certain bits turned on, indicating the
error: 400000 is a catchall -- improper
mode.
200000 means parity error occurred.
100000 means a data error occurred.
40000 means "Record number out of bounds".
20000 means End of File (input only).
You are always enabled for bit 20000 (EOF).
However, to be allowed to handle any of the
others, you must turn on the corresponding
bit in the right half of the MODE word in
the OPEN for this channel. In addition, the
10000 bit is used to enable user handling of
invalid file specifications to ENTER,
LOOKUP, and RENAME (see above). '7500017 in
the MODE parameter would enable a dump mode
file for user handling of ALL I/O errors on
this channel. If you are not enabled for a
given error, an error message (which may or
may not be fatal) will be printed, and the
error code word set as indicated. In
addition, the number of words actually
transferred is stored in the right half of
this variable for ARRYIN, ARRYOUT.
LOOKUP FLAG param same as ENTER.
OPEN EOF vbl if 0 on entry, prints fatal error message if
OPEN fails. If ≠0 on entry, always returns
to user -- still ≠0 if OPEN failed, 0 if it
succeeded.
RENAME FLAG param same as ENTER.
TTYINS FLAG param same as INSTRS.
SAILON NO. 57.1 SAIL 18-11
substrings _SKIP_ consider ST[X TO Y]. If Y>LENGTH(ST), Y←
LENGTH(ST). If Y<0, Y←0; rh(_SKIP_)←-1 with
both. If X<1, X←1. If X>Y it is set to
Y+1 (guaranteeing a null String result). In
either case, lh(_SKIP_) is set to -1. The
ST[X FOR Y] case is first converted to the
other case, then executed.
You should also refer to the table for Input, 12-40, describing the
various combinations of the BRCHAR and EOF
variables and their meanings.
SUGGESTED CHANGES TO THE FAIL MANUAL.
These are not formal as was the case with SAIL, because it seemed
prudent to leave the method of modification up to you.
A. The version of FAIL on this tape has the TWOSEG and HISEG
pseudo-ops implemented. These behave identically to those in
MACRO, except that it is mandatory that they appear before any
instructions which cause code to be generated.
B. The LINK, LINKEND descriptions are terribly inadequate -- a shame,
because it's such a nice feature. I suggest that 2.4.16 be expanded
as follows, and that space be created by deleting parts 2, 3, and 5
of section 2.5, since these are Stanford-specific, and we already
have a manual.
****************
2.4.16 LINK-LINKEND
This feature provides a convenient non-symbolic communication method
between possibly independent assemblies.
LINK n,loc (0≤n≤17)
causes the Loader to place loc at the head of a linked list identified
by n (the previous list value for n is placed in loc, and the address
of loc is saved for list n).
LINKEND n,locend
directs the Loader to place the final address saved for list n in
locend, but only after loading is complete (therefore the order in
which the LINKs and the (single) LINKEND appear is unimportant).
Both loc and locend should be assembled as 0's. Locend may be used
at run time to access data adjacent to each loc which was LINKed to
list n.
**************
Isn't that nice?
Stanford AI Project
Computer Science Dept.
Stanford University
Stanford, Ca., 94305
16 September, 1971
(415) 321-2300 (x4971)
Ms. I. Ferne Halley
Digital Equipment Computer Users Society
Maynard, Mass. 01754
Dear Ms. Halley:
Under separate cover I have sent tapes, listings, and miscellaneous
paraphernalia representing the new SAIL system. Before I get to the
details of just what you're in for, I'd like to express my appreciation
for the help you've given me in this effort. Your SAIL manual (which,
by the way, arrived within two days after we talked) is of impressive
quality, with better contrast and paper quality than our latest offering.
I hope that what I've sent will allow you to upgrade the system with
minimum effort.
The listings represent revisions to previous documentats, or complete
replacements to a couple of them. The SAIL manual changes are done
as replacements to existing pages (the page numbers are indicated to
the right. There are cases where an insertion should go between the
pages printed on the same piece of paper. The choice of reprinting
the entire sheet, then printing the old back page on a new sheet, or
simply inserting the new page out of order is up to you. There are only
about thirty pages of changes; the resulting manual (along with NEWMAN)
represents totally up to date documentation.
NEWMAN is a description of a few changes which have not made their way
into the manual yet. It should replace a similar document in the old manual as shown on
the listing. TELLEM is a much-improved version of the implementation guide
found on pages 199-215 of the manual you sent; unfortunately, it is about
40 pages long. Sorry about that.
I have only indicated what sort of changes should be made in the FAIL
manual, since it was apparent that changes had been inserted there before
and I decided you might want control over the format. There are only a
couple of changes, but I think they are fairly important ones.
The cover letter should replace page 2 of the manual. Feel free to retype
it with modifications to suit your policy -- especially if you're not geared
for receiving bug reports, etc. In the latter case, shift them over to
me (us?). I thought some sort of general introduction of that nature was
needed there, though.
The magnetic tape I have sent is recorded at 556 bpi, on 7 tracks. It contains
everything anyone will need to implement a SAIL system, and somewhat more
in addition. The first few pages of the TELLEM document are devoted to the
retrieval of these files to disk. You should use the same procedures to
do any testing, or to distribute the system on DECTAPE. Once you have retrieved
SAVE.SAV using GETSAV, you should probably keep it in some convenient place
for future use.
To distribute SAIL on mag tape, you should use the COPY.MAC program, provided
on paper tape. It will copy a tape from MTA0: to MTA1:, as described in the
hard-copy listing. There is no reason to send this program to anyone else.
However, in addition to the other documents, the magtape user should be sent
the GETSAV listing and paper tapes.
If you distribute any DECtape systems, there are some files you should probably
leave out, to save tapes, since they are of marginal utility. Referring to
the parts list in TELLEM, they are:
GETSAV (of course), SAVE, SAVE.SAV, LOADER.052 (any Loader should work),
FAIL.ON, SAIL.ON
Send only PROFIL.SAI and SCNSER.SAI from the second group of files.
These files still will occupy four or five DECtapes.
We really don't have a mechanism for giving away or selling tapes, so I
guess I should ask you to send ours (or one like it) back. That will give
you a good opportunity to test the COPY program.
A couple of things come for free with this system. In particular, this version
of FAIL, and the document with the indicated changes, represent the very
latest we have of this program, including TWOSEG and HISEG. In addition, the
CREF on the tape is the newest we have of that (it handles block structure
as created by FAIL and SAIL). You might want to upgrade your files for these
programs, too.
I have to confess to ignorance of some of your services. In particular, people
often ask me for multiple copies of the SAIL manual (for classes, etc.). We
have no mechanism for helping them. Are the manuals you publish available in
quantity (presumably at some happily outlandish charge)? If not, could something
be arranged if the demand becomes great enough? I am also curious about your
willingness to collect complaints from users, and distribute their fixes to
current users of the system, and that sort of thing.
Again, thank you very much for your help. This thing has gotten quite beyond
my ability to keep up with it. Please let me know if I can do something else
to aid in the distribution of SAIL.
Sincerely,
Dan Swinehart