spittext.gpm

{Hl 1,Introduction}{Ls 1}
MACRO~SPITBOL is an implementation of the SNOBOL4 computer
language which was coded during 1974/75. In speed and external style
{Index IBM}{Index UNIVAC}
it resembles the earlier SPITBOL implementations for the IBM~360 and
UNIVAC~1100 series computers but internally it differs considerably
from
these since the source code is converted to a reverse polish string
which is then used to drive interpretive routines.
 MACRO~SPITBOL is available with a high degree of compatibility
on a range of computers running under widely differing operating systems.
 This report reflects the above fact by providing in its first nine
sections
such documentation and information for users as is substantially machine
independent, with a final section giving essential information peculiar
to each particular implementation.  It is assumed that the reader is
familiar
with the standard version, referred to simply as SNOBOL4 in the remainder
of the report and described in the essential reference book
"The SNOBOL4 Programming Language" by Griswold, Poage and Polonsky,
Addison Wesley, 1971.  Version 3.4 of SNOBOL4 is the reference version for
comparison.  There are several minor incompatibilities and some
features are not implemented.  There are several additions to the language
in this implementation.
{p}
{Ls 1}In general an attempt has been made to retain upward compatibility
wherever possible.  Most SNOBOL4 programs which operate correctly using
SNOBOL4 should operate correctly when compiled and executed using
MACRO~SPITBOL.  For brevity,
in the remainder of the report MACRO~SPITBOL
will be referred to simply as SPITBOL.
{Ls 2}{nfj}
SPITBOL was initially designed and implemented by:-
{Ls 1}
Professor Robert B. K. Dewar,
Courant Institute of Mathematical Sciences,
251 Mercer Street,
NEW YORK, N.Y. 10012.
U.S.A.
{Ls 1}
It has been further developed and is now maintained by:-
{Ls 1}
Dr.  Anthony P. McCann,
Department of Computer Studies,
University of Leeds,
LEEDS, LS2 9JT,
England.
{Ls 2}
The VAX/VMS Version is the work of and is maintained by:
{Ls 1}Steven G. Duff
c/o Dewar Information Systems Corporation
221 West Lake Street
Oak Park, Illinois  60302
{fj}{Ls 1}Which should be contacted to report problems or
for information on distribution.
{Ls 1}The implementor gratefully acknowledges the assistance of
Thagard Research in providing development facilities for the
VAX/VMS Version of SPITBOL.
{Set Subtitle,Summary of Differences}
{p}
{Hl 1,Summary of Differences}
{Ls 1}The principal differences between SPITBOL and SNOBOL4
are summarised here.
{Hl 2,<Features not Implemented>}
{List 1}
{Listelem Redefinition}The capability to redefine
standard system functions and predefined operators.
{index  pre-evaluation}
This restriction permits compile time pre-evaluation of a wider range
of expressions
and patterns than would otherwise be possible.
 It affects the OPSYN function (see {SEC_FUNC} for details).
{index  VALUE}
{index  BACKSPACE}
{Listelem VALUE and BACKSPACE Functions}The VALUE  and BACKSPACE functions.
{index  &STFCOUNT}
{index  &FULLSCAN}
{Listelem &STFCOUNT and &FULLSCAN}The keywords &STFCOUNT and &FULLSCAN .
{index  QUICKSCAN}
The heuristics associated with the QUICKSCAN mode of pattern matching
are complex and for many programs do not result in a significant increase
{index  FULLSCAN}
in speed.  Accordingly only FULLSCAN matching is provided and no
heuristics are applied.
 In particular deferred expressions are not assumed to match at least
one character.
{index  BLOCK}
{index  SNOBOL4B}
{Listelem BLOCK Datatype}The BLOCK datatype as in SNOBOL4B .
{index  PUNCH}
{Listelem PUNCH Association}The
variable PUNCH has no predefined association to a punch
stream.  If required, the programmer should include a
statement such as OUTPUT(.PUNCH,3) in his program.
{Listelem Real Exponentiation}SPITBOL
does not permit exponentiation of two real numbers.
{Listelem Real Arithmetic}For small machines, versions of SPITBOL in which all
real arithmetic capability is omitted are available - see {SEC_IMPL}.
{index  real arithmetic}
{Listelem Features Omitted}Some
implementations may omit a few features.  A list is given in
{SEC_IMPL}.
{Endlist}
{p}
{Hl 2,<Features Implemented Differently>}
{Ls 1}Some of the differences here may necessitate program changes.
{List}
{index  &ANCHOR}
{Listelem &ANCHOR}In SPITBOL the value of &ANCHOR is obtained only at the start
of
the match.  In SNOBOL4, changing the value during a match can lead
to unexpected results.
{index  ABORT}
{index  ARB}
{index  BAL}
{index  FAIL}
{Listelem Pattern-Valued Variables}The
pattern valued variables ABORT, ARB, BAL, FAIL
{index  FENCE}
{index  REM}
{index  SUCCEED}
FENCE, REM, SUCCEED are write protected so that attempts
to assign to them will fail.
{Listelem Pattern Stack}The
same stack is used for pattern matching and for function calls.
 Thus the
diagnostic issued for an infinite pattern recursion is simply the
standard
stack overflow message.
{index  SETEXIT}
{Listelem Execution Error Recovery}Recovery from execution errors (see function SETEXIT ).
{Listelem I/O}Input/Output.  In particular, FORTRAN I/O is not provided.
 Dynamic association to files is possible through the third argument
and statement failure is possible if a file cannot be found as in
-
{brk}
~~~~~INPUT(.IN,3,'INFIL')                :F(NOFILE)
{index  TABLE}
{Listelem Tables}The TABLE function is implemented so that table elements
can be rapidly accessed by the efficient technique of hashing.
{index  hashing}
In order to set a suitable
size for the hash table it is important to choose a reasonable value
for the argument of TABLE.  Use of an inappropriate value will not
cause program failure but may delay access to elements or waste memory.
{Listelem Datatype Conversions}SPITBOL
allows some datatype conversions not allowed in SNOBOL4.
{index  datatype conversions}
For example a real value may be used in patterns and
is converted to a string.  In general objects will be converted to
an appropriate
datatype if at all possible.
{Listelem Name Operator}The
unary . (name) operator applied to a natural variable yields
{index  NAME}
a NAME rather than a
STRING.  Since this NAME is converted to a STRING when
necessary, the difference is not normally noticed.  The only points
at which
{index  IDENT}
{index  DIFFER}
the difference will be apparent is in use of the IDENT, DIFFER
{index  DATATYPE}
and DATATYPE functions
{index  TABLE}
and when used as a TABLE subscript.
{Listelem Numeric Conversion}SPITBOL
permits leading and trailing blanks on numeric strings
which are to be converted to
{index  NUMERIC}
NUMERIC .
{Listelem Built-in Functions}Several
of the built-in functions are slightly different.  They
are identified
by a * on their names in {SEC_FUNC}.
{Listelem Statement Counting}The
count of statements executed includes labelled null statements
and
{index  END}
the END statement.
{Listelem Optimization}Constant
sub-expressions and patterns are pre-evaluated at compile
time.
{index pre-evaluation}
This may occasionally result in execution errors (e.g. integer overflow)
being reported during compilation.  Significant speed increases may
be
obtained by ensuring that in-line patterns are constant so that they
may be pre-evaluated.  Patterns built from pattern valued variables
(e.g. ARB)
and pattern functions with constant arguments (e.g. ANY(*ARG),
RTAB(0)) are themselves constant.
{Listelem &MAXLNGTH}A
compact and fast garbage collector is used which needs to distinguish
{index  garbage collection}
between small integers and memory addresses.  This effectively restricts
the
maximum size
{index  maximum size}
of any SPITBOL object (string, array, table, code or expression block)
{index  MXLEN}
to be less than a value subsequently referred to as MXLEN .
 This is in practice little restriction on most host computers.
 Where, because of implementation needs, it might prove restrictive,
a run time option is generally
provided for setting this value to suit a user's requirements (see
{SEC_IMPL}.
where an indication of the default initial setting of MXLEN is also
given).
{index  &MAXLNGTH}
Since the value of MXLEN is used to initialise &MAXLNGTH ,
printing &MAXLNGTH during execution gives its exact value.
 A user may subsequently assign a smaller value to this keyword but
values exceeding that of MXLEN may not be assigned to it.
{index  &TRIM}
{Listelem &TRIM}A value of zero for &TRIM does not necessarily imply that
trailing blanks will be added to records in which they are not originally
present - see {SEC_IMPL}.
{Endlist}
{Hl 2,<Additional Features>}
{Ls 1}The following SPITBOL features are not found in SNOBOL4.
{List}
{index  BREAKX}
{index  EJECT}
{index  EXIT}
{index  HOST}
{index  LEQ}
{index  LGE}
{Listelem Additional Functions}The
functions BREAKX, EJECT, EXIT, HOST, LEQ, LGE,
{index  LLE}
{index  LLT}
{index  LNE}
{index  LPAD}
{index  REVERSE}
{index  RPAD}
LLE, LLT, LNE, LPAD, REVERSE, RPAD,
{index  RSORT}
{index  SETEXIT}
{index  SORT}
{index  SUBSTR}
RSORT, SETEXIT, SORT, SUBSTR  .
 The sorting functions, the
extended break pattern BREAKX, and the output formatting
functions LPAD and RPAD are especially useful.  See {SEC_FUNC} for details
of all these functions.
{index  &ERRTEXT}{index &PROFILE}
{Listelem &ERRTEXT}The keywords &ERRTEXT and &PROFILE.
{Listelem Dumping}The
symbolic dump optionally includes elements of arrays, tables
{index  DUMP}
and programmer defined datatypes. (See DUMP ).
{Listelem Access Trace}An
access trace mode is provided in addition to the other standard
modes.
{index  TRACE}
(See TRACE ).
{index  selection}
{index  alternative}
{Listelem Selection}A selection or alternative feature is provided.
{index  CONVERT}
{Listelem NUMERIC Datatype}The second argument of CONVERT may be 'NUMERIC'.
{index  =}
{Listelem Additional Operators}The
assignment symbol , = , is treated as an ordinary binary
operator
{index  ?}
and the binary operator , ? , is given a defined meaning as a pattern
matching operator.
{index  pattern matching operator}
{Listelem Listing Options}If
running SPITBOL from an on-line terminal, options may be selected
{index  on-line terminal}
to reduce the amount of listing information sent to the terminal or to
restrict this to compilation errors only. (See {SEC_IMPL} for details).
{Listelem TERMINAL}Reflecting the fact that many current computer systems
{index  TERMINAL}
have good online terminal capabilities, the name TERMINAL
is available with pre-association for input and output to a
terminal on such systems - see {SEC_IMPL}.
{brk}
T~~~~~TERMINAL = EVAL(TERMINAL)     :S(T)
{brk}
acts as a desk calculator.  TERMINAL may be
detached but may not then be re-associated.  If this
feature is unimplemented,
TERMINAL acts as an ordinary variable.
{Index Control Cards}
{Listelem Control Cards}Several
additional control cards may be used to select various
compile time and run time options.
{Index Character Set}
{Listelem Character Set Extensions}An
extended character set is available in some implementations.
 Where lower case letters are provided names such as "INPUT" and "input"
{index  gotos}
are distinct.  In gotos :f and :s mean the same as :F and :S.
{index  Tab character}
The Tab character, if available, is syntactically identical with blank.
 See {SEC_IMPL}.
{index  &STLIMIT}
{Listelem Statement Count Checking}The
assignment &STLIMIT = -1 inhibits all checks on
numbers of statements executed.
{index SORT}{index RSORT}
{Listelem SORT & RSORT}Built-in functions are available for sorting
the elements of tables and arrays.
{Endlist}
{p}
{Hl 2,<Syntax Differences>}{Ls 1}
This section describes differences in syntax
between SPITBOL and SNOBOL4. such differences should not
generally affect existing SNOBOL4 programs.
{List}
{Listelem ITEM}Reference to elements of arrays which are themselves elements of
{index  ITEM}
arrays is possible without using the ITEM function.  Thus the following
are equivalent --
{brk}
~~A<<J>><<K>> = B<<J>><<K>>;~~~~~~~ITEM(A<<J>>,K) = ITEM(B<<J>>,K)
{Listelem Real Constants}The
compiler permits real constants to be followed by a FORTRAN
style
exponent E+xxx.
{index  selection}
{index  alternative}
{Listelem Selection}A
selection or alternative construction may be written anywhere
that a value is permitted.  It consists of a series of expressions
separated by
commas and enclosed in parentheses:
{brk}
~~(e1,e2,e3,....,en)
{brk}
The semantics is to evaluate the expressions from left to right until
one succeeds
and then use its value.  Failure is signalled if all evaluations fail.
 This feature trivially provides an "or" function for predicates and
also has
many other uses as shown by the following examples:
{brk}
{nfj}
~~A     = (EQ(B,3),GT(B,20)) B + 1
~~NEXT  = (INPUT,'%EOF')
~~MAXAB = (GT(A,B) A,B)
{brk}
{fj}
{index  IF-THEN-ELSE}
The alternative structure provides an IF-THEN-ELSE capability,
and as such is a useful programming feature.  Note incidentally that
the semantics of ordinary
parentheses is a correct degenerate case of an alternative structure
with one alternative.
{index  []}
{index  <<>>}
{Listelem Array Brackets}The
array brackets [] may be used instead of <<>> if desired.
 Thus X[I,J] and X<<I,J>> are equivalent.
{index  =}
{Listelem Assignment Operator}By
treating = as a right associative operator of lowest priority,
multiple assignments within a single statement may be coded.  The value
returned
by an assignment is that of its right hand side.  After obeying
{brk}
~~A[I = INPUT] = INPUT
{brk}
I is the index of the element of the array into
which data has been read.
{index  ?}
{Listelem Pattern-Matching Operator}?
is defined to be an explicit pattern matching operator.
 It is left associative and has priority lower than that of all operators
except = .
 It returns as its value the substring matched from its left argument
(a string)
by its right argument (a pattern).
 Thus
{nfj}
~~'ABCD' ? LEN(3) $ OUTPUT ? LEN(1) REM $ OUTPUT
causes printing of
~~ABC
~~BC
{fj}
{Endlist}
{Set Subtitle,Datatypes and Conversion}
{p}
{Hl 1,Datatypes and Conversion}
{Ls 1}This section details the datatypes available in SPITBOL
and the conversions which may be performed amongst them.
{Hl 2,<Available Datatypes>}
{List}
{index  STRING}
{Listelem STRING}STRING
{brk}
{index  MXLEN}
Strings range in length from 0 (null string) to MXLEN characters
{index  &MAXLNGTH}
(subject to the setting of &MAXLNGTH).  Any characters from the
hardware set of the computer used to run SPITBOL can appear in a string.
{index  INTEGER}
{Listelem INTEGER}INTEGER
{brk}
Integers are generally stored in the hardware complement form for
the computer used to run SPITBOL and usually occupy a single word.
 See {SEC_IMPL} for range.
{index  REAL}
{Listelem REAL}REAL
{brk}
Available if floating point hardware is available
(sec 10.2.4).
 Stored according to the usual hardware conventions of the computer
on which SPITBOL is run.
{index  ARRAY}
{Listelem ARRAY}ARRAY
{brk}
{index  MXLEN}
Arrays may not exceed MXLEN words in total size. 10 to 15
words must be allowed for housekeeping information.
{index  TABLE}
{Listelem TABLE}TABLE
{brk}
{index  MXLEN}
A table may have up to MXLEN elements.  Any SPITBOL object may
be used as the name of a table element, including the null string.
 See {SEC_FUNC} for details.
{index  PATTERN}
{Listelem PATTERN}PATTERN
{brk}
Pattern structures may be arbitrarily large within the limits imposed
by
total available memory.
{index  NAME}
{Listelem NAME}NAME
{brk}
A name can be obtained from any variable.  Note that in SPITBOL
, the name operator (unary dot) applied to a natural variable yields
a name,
not a string as is the case with SNOBOL4.
 Use of names as arguments to the indirection operator (unary $) is
much faster than the use of string arguments.  Names can also be
used advantageously in statements such as~~INPUT(.IN)
{p}
{index  EXPRESSION}
{Listelem EXPRESSION}EXPRESSION
{brk}
Any expression may be deferred by using the unary * operator.
{index  CODE}
{Listelem CODE}CODE
{brk}
A string representing a valid program can be compiled at
execution time.  The resulting CODE object
may be executed in the same manner as the original program.
{Endlist}
{p}
{Hl 2,<Possible Datatype Conversions>}
{Ls 1}As far as possible SPITBOL converts from one datatype to another
as required.
 The following table shows which conversions are possible.
{index  datatype conversions}
Blank entries indicate that the conversions are impossible,
A indicates that conversion is always possible, and U indicates conversion
is usually possible, depending on the value involved.
{nfj}
{Ls 1}
                    ~~CONVERT TO:
{Ls 1}
                ~~~S I R A T P N E C
                 +-----------------<->
                S! A U U     A A U U
                I! A A A     A A A
                R! A U A     A A A
        CONVERT A!       A U
         FROM:  T!       A A
                P!           A
                N! U U U     U A U U
                E!               A
                C!                 A
{Ls 1}
        S       STRING
        I       INTEGER
        R       REAL
        A       ARRAY
        T       TABLE
        P       PATTERN
        N       NAME
        E       EXPRESSION
        C       CODE
{fj}
{p}
{Hl 2,<Conversion Details>}
{Ls 1}This section gives detailed descriptions for each of the possible
conversions.
{index  datatype conversions}
{List}
{index  STRING}
{Listelem STRING->INTEGER}STRING --> INTEGER
{Ls 1}Leading and trailing blanks are ignored.  A leading sign is
optional.  The sign, if present, must immediately precede the digits.
 A null or all blank string is converted to zero.
{Listelem STRING->REAL}STRING --> REAL
{Ls 1}Leading and trailing blanks are ignored.  A leading sign if present,
must immediately precede the number.  The number itself may
be written in standard FORTRAN type format with an optional exponent.
 The conversion is always accurate, the last bit being correctly rounded.
 A null or blank string is converted to 0.0 .
{Listelem STRING->PATTERN}STRING --> PATTERN
{Ls 1}A pattern is created which will match the string value.
{Listelem STRING->NAME}STRING --> NAME
{Ls 1}The result is the name of the natural variable which has the given
string as its name.  This is identical to the result of applying the
unary dot operator to the variable in question.  The null string
cannot be converted to a name.
{Listelem STRING->EXPRESSION}STRING --> EXPRESSION
{Ls 1}The string must represent a legal SPITBOL expression.  The compiler
is used to convert the string into its equivalent expression and the
result can be used anywhere an expression is permitted.
{Listelem STRING->CODE}STRING --> CODE
{Ls 1}The string must represent a legal SPITBOL program, complete with
labels, and using semicolons to separate statements.  The compiler
is used to convert the string into executable code.  The resulting
code can be
executed by transferring to it with a direct GOTO or by a normal
transfer to a label within the code.
{p}
{index  INTEGER}
{Listelem INTEGER->STRING}INTEGER --> STRING
{Ls 1}The result has no leading or trailing blanks and leading zeros
are suppressed.  A minus sign is prefixed to negative values.
 Zero is converted to "0".
{Listelem INTEGER->REAL}INTEGER --> REAL
{Ls 1}A real number is obtained by adding a zero fractional part.
 Note that it is possible to lose significance in this conversion if
the mantissa of the real representation has fewer digits than are
available for an integer.
{Listelem INTEGER->PATTERN}INTEGER --> PATTERN
{Ls 1}First convert  to a STRING and then treat as STRING to PATTERN.
{Listelem INTEGER->NAME}INTEGER --> NAME
{Ls 1}First convert to STRING and then treat as STRING to NAME.
{Listelem INTEGER->EXPRESSION}INTEGER --> EXPRESSION
{Ls 1}The result is an EXPRESSION which when evaluated yields the INTEGER
as its value.
{index  REAL}
{Listelem REAL->STRING}REAL --> STRING
{Ls 1}The real number is converted to its standard character representation.
 Fixed type format is used if possible, otherwise an exponent (using
E)
is supplied.  Seven significant digits are generated, the last being
correctly
rounded for all cases.  Trailing insignificant zeros are suppressed
after
rounding has taken place.
{Listelem REAL->INTEGER}REAL --> INTEGER
{Ls 1}This conversion is only possible if the REAL is in the range permitted
for integers.
 in this case, the result is obtained by truncating the fractional
part.
{Listelem REAL->PATTERN}REAL --> PATTERN
{Ls 1}First convert to STRING and then treat as STRING to PATTERN.
{Listelem REAL->NAME}REAL --> NAME
{Ls 1}First convert to STRING and then treat as STRING to NAME.
{Listelem REAL->EXPRESSION}REAL --> EXPRESSION
{Ls 1}The result is an expression which when evaluated yields the
REAL as its value.
{index  ARRAY}
{Listelem ARRAY->TABLE}ARRAY --> TABLE
{Ls 1}The array must be two dimensional with a second dimension of 2
or an error occurs.  For each value of the first subscript, J ,
a table entry using the (J,1) entry as name and the (J,2) entry
as value is created.  The table built has a number of hash headers
(see TABLE in {SEC_FUNC}) equal to the first dimension.
{index  TABLE}
{Listelem TABLE->ARRAY}TABLE --> ARRAY
{Ls 1}The table must have at least one element which is non-null otherwise
statement failure occurs.
 The array generated is two dimensional with the first dimension
equal to the number of non-null entries in the table and the second
dimension is two.  For each entry, the (J,1) element in the array
is the the name and the (J,2) element is the value.
{index  NAME}
{Listelem NAME->STRING}NAME --> STRING
{Ls 1}A NAME can be converted to a STRING only if it is the name of a natural
variable.
 The resulting string is the character name of the variable.
{Listelem NAME-><INTEGER, REAL, PATTERN, EXPRESSION, CODE>}NAME --> INTEGER,
REAL, PATTERN, EXPRESSION, CODE
{Ls 1}The NAME is first converted to a STRING (if possible)
and then the conversion proceeds as described for STRING.
{Endlist}
{Set Subtitle,Operators and Functions}
{p}
{Hl 1,Operators and Functions}
{Hl 2,<Operators>}
{index  operators}
{Ls 1}SPITBOL operators are listed without any detailed descriptions since
they correspond, with a few exceptions noted in the description
of differences, to those of SNOBOL4.
{Hl 3,Unary Operators}
{Ls 1}Unary operators all have equal priority which is greater than that
of any binary operator.
{Ls 1}
{nfj}
OPERATOR                DESCRIPTION
{Ls 1}
{index  ?}
?                Interrogation - null if operand succeeds
{index  &}
&                Keyword
{index  +}
+                Indicates postive numeric operand
{index  -}
-                Negates numeric operand
{index  *}
*                Defers evaluation of expression
{index  $}
$                Indirection
{index  .}
.                Returns a name
{Tset Hs,`}
{index  ~}
~                Negates failure or success of its operand
{Restore Hs}
{index  <@>}
@                Assigns cursor position to its operand
{Ls 1}
{index  !}
{index  %}
{index  /}
{index  ~}
{index  =}
     Unused unary operator symbols are   ! % / # =
{fj}
{p}
{Hl 3,Binary Operators}
{Ls 1}Several of the associativites and priorities differ from those of
SNOBOL4.
{nfj}
{Ls 1}
OP.     ASSOCY. PRIO.           DEFINITION
{Ls 1}
=       right   0       Assignment
?       left    1       Pattern match
{index  |}
|       right   3       Pattern alternation
blank   right   4       Concatenation or pattern match
+       left    6       Arithmetic addition
-       left    6       Arithmetic subtraction
/       left    8       Arithmetic division
*       left    9       Arithmetic multiplication
{index  !}
! or ** right   11      Arithmetic exponentiation
$       left    12      Immediate pattern assignment
.       left    12      Conditional pattern assignment
{Ls 1}
&       left    2       Undefined
@       right   5       Undefined
{Tset Hs,*}
~       left    7       Undefined
{Restore Hs}
%       left    10      Undefined
_       right   13      Undefined
{fj}
{p}
{Hl 2,<Functions>}
{index  functions}
{Ls 1}This section defines the built-in functions of SPITBOL, the descriptions
being given in alphabetical order.  In most cases, the arguments
are pre-converted to some particular datatype.  This is indicated in
the function header by the notation --
{brk}
~~FUNCTION(STRING,INTEGER,....)
{brk}
If the corresponding argument cannot be converted to the indicated
datatype,
an error occurs.  Sometimes the range of arguments permitted is restricted,
in which case arguments outside the range cause an error.  The usage
"ARGUMENT" implies that the argument can be of any datatype.
"NUMERIC" implies that either REAL or INTEGER arguments are acceptable.
{index  ARRAY}
{index  DATA}
{index  DEFINE}
{Ls 1}In functions such as ARRAY, DATA, DEFINE with a string
prototype argument, the string should not contain non-significant
blanks.
{index  ANY}
{Hl 3,ANY -- Pattern to Match Selected Character}
{Ls 1}
ANY(STRING) or ANY(EXPRESSION)
{Ls 1}This function returns  a pattern which will
match a single character selected from the characters in the argument
string.
 A null argument is not permitted.
 If an expression argument is used, then the expression is evaluated
during pattern matching and must yield a non-null string result.
{index  APPLY}
{Hl 3,APPLY * -- Apply function}
{Ls 1}
APPLY(NAME,ARG,ARG,...)
{Ls 1}The first argument is the name of a function to be applied to the
(possibly null) list of arguments following.  Unlike SNOBOL4,
SPITBOL does not require the number of arguments to match the function
definition, extra arguments being ignored and missing arguments being
supplied
as null strings.
{index  ARBNO}
{Hl 3,ARBNO -- Pattern for Iterated Match}
{Ls 1}
ARBNO(PATTERN)
{Ls 1}This function returns a pattern which will match an arbitrary number
of
occurrences of the pattern argument, including zero occurrences (this
resulting in matching of the null string).
{p}
{index  ARG}
{Hl 3,ARG * -- Obtain Argument Name}
{Ls 1}
ARG(NAME,INTEGER)
{Ls 1}The first argument represents the name of a function.
 The integer is the index of a formal argument to this function.
 The NAME of the selected argument is returned (this is converted
to a string on output).
 ARG fails if the integer is out of range of the number of formal arguments.
{index  ARRAY}
{Hl 3,ARRAY -- Generate Array Structure}
{Ls 1}
ARRAY(STRING,ARG) or ARRAY(INTEGER,ARG)
{index  arrays}
{Ls 1}The string represents the protoype of an array to be allocated.
 This is in the form
{brk}
~~~"LBD1:HBD1,LBD2:HBD2,...."
{brk}
where LBD1,HBD1 etc.  are integers specifying low and high bounds.
 The low bound (LBD) may be omitted for some or all of the dimensions,
in
which case the colon may also be omitted and a low bound of 1 is assumed.
 The second argument (of any datatype) is the initial value of all
the
elements in the array.  If it is omitted, the initial value of all
the
elements will be the null string.
 The second form of the call may be used to create one dimensional
arrays (vectors) with a low bound of 1. SPITBOL optimises accesses
to elements
{index  vectors}
of vectors.
{index  BREAK}
{Hl 3,BREAK -- Construct Scanning Pattern}
{Ls 1}
BREAK(STRING) or BREAK(EXPRESSION)
{Ls 1}This function returns a pattern which will match any string up
to the point preceding any character which occurs in the argument
string.
 A null argument is not permitted.
 If an expression argument is given, the resulting pattern causes
the expression to be evaluated during pattern matching.  In this case,
the evaluated result must be a non-null string.
{p}
{index  BREAKX}
{Hl 3,BREAKX * -- Construct Scanning Pattern}
{Ls 1}
BREAKX(STRING) or BREAKX(EXPRESSION)
{Ls 1}BREAKX returns a pattern whose initial match is the
same as a corresponding
BREAK pattern.  However, BREAKX has implicit alternatives which on
subsequent match failure permit scanning past the first break character
found
and up to the next break character.  Note that BREAKX may be used to
{index  ARB}
replace ARB
in many situations where BREAK cannot be used easily.  For example
the following replacement can be made --
{brk}
~~~ARB ('CAT' ! 'DOG')  -->  BREAKX('CD') ('CAT' ! 'DOG')
{Brk}In the case of an expression argument, the expression is evaluated
during
pattern matching and must yield a non-null string.  Note that evaluation
of the expression is not repeated on rematch attempts by extension.
{index  CLEAR}
{Hl 3,CLEAR * -- Clear Variable Storage}
{Ls 1}
CLEAR(STRING)
{Ls 1}This function causes the values of variables to be set to null.
 In the simple case, where the argument is omitted or null, the action
is
the same as in SNOBOL4 (i.e. all variables cleared to null).
 An extension is available in SPITBOL.  The first argument may be a
string
which is a list of variable names separated by commas.  These represent
the
names of variables whose values are to be left unchanged.  For example
--
{brk}
~~~CLEAR('ABC,CDE,EFG')
{brk}
would cause the value of all variables except ABC, CDE, EFG
to be set to the null string.
{index  CODE}
{Hl 3,CODE * -- Compile Code}
{Ls 1}
CODE(STRING)
{Ls 1}The effect of this function is to convert the argument to type CODE
as described
in the section on type conversion.  The STRING must represent a valid
SPITBOL
program complete with labels and using semicolons (;) to separate
statements.
 The call to CODE fails if syntactic errors are found.
{index  &ERRTEXT}
In this case it is possible to inspect &ERRTEXT to find the
error message.  e.g.
{brk}
~~~~~~~C = CODE(CD)     :F<<CODE(' OUTPUT = &ERRTEXT')>>
{brk}
{index  SETEXIT}
SETEXIT may also be used to intercept these errors.
 Another extension over SNOBOL4 is that the code string may contain
{index  -LIST}
embedded control cards (notably -LIST to cause listing of the
code) and comments
delimited by semicolons.
{p}
{index  COLLECT}
{Hl 3,COLLECT -- Initiate Storage Regeneration}
{Ls 1}
COLLECT(INTEGER)
{index  garbage collection}
{Ls 1}The COLLECT function forces a garbage collection which retrieves
unused storage
and returns it to the block of available storage.  The integer argument
represents a minimum number of words to be made available.
 If this amount of storage cannot be obtained, the COLLECT function
fails.
 On successful return, the result is the number of words actually obtained.
 Although the implementation of COLLECT is the same as in SNOBOL4,
the values obtained will be quite different due to different internal
data representations.
 Furthermore, the organization of SPITBOL is such that forcing garbage
collections
to occur before they are required increases execution time.
{index  CONVERT}
{Hl 3,CONVERT * -- Convert Datatypes}
{Ls 1}
CONVERT(ARGUMENT,STRING)
{Ls 1}The returned result is obtained by converting the first argument
to the type indicated by
the string name of the datatype given as the second argument.
 The permitted conversions are described in the section on
type conversion.
 Any conversions which are not permitted cause failure of the CONVERT call.
 The second argument may be 'NUMERIC' , in which case the argument
is converted to INTEGER or REAL according to its form.
{index  COPY}
{Hl 3,COPY * -- Copy Structure}
{Ls 1}
COPY(ARGUMENT)
{Ls 1}The COPY function returns a distinct copy of the object presented
as its argument.
 This is only useful for arrays, tables and
program defined datatypes.  Note that SPITBOL permits copying of TABLES
unlike SNOBOL4.
{p}
{index  DATA}
{Hl 3,DATA -- Create Datatype}
{Ls 1}
DATA(STRING)
{index  program defined datatypes}
{Ls 1}The argument to DATA is a prototype for a program defined datatype
in the form of a function
call with arguments e.g. DATA('CMPLX(RE,IM)').
 The function name in the string is the name of the new datatype.
 The argument names in the string are the names of field selector
functions used to access the fields of the new datatype.  Increased
efficiency is obtained by avoiding the use of duplicate field names
for different
datatypes, although such multiple use is not forbidden.
{index  DATATYPE}
{Hl 3,DATATYPE * -- Obtain Datatype}
{Ls 1}
DATATYPE(ARGUMENT)
{Ls 1}DATATYPE returns the formal identification of the datatype of its
argument.
{index  DATE}
{Hl 3,DATE * -- Obtain Date}
{Ls 1}
DATE()
{Ls 1}DATE returns a string giving the current date and
possibly also clock-on-the-wall-time (see {SEC_IMPL}.)
{index  DEFINE}
{Hl 3,DEFINE -- Define a Function}
{Ls 1}
DEFINE(STRING) or DEFINE(STRING,NAME)
{Ls 1}The DEFINE function is used to create program defined functions
according to the prototype supplied as the argument.
 The second argument if supplied, names the label at the entry to the
function.
{index  DETACH}
{Hl 3,DETACH -- Detach I/O Association}
{Ls 1}
DETACH(NAME)
{Ls 1}NAME is the name of a variable which has previously been input or
output associated
{index  INPUT}
{index  OUTPUT}
by appearing as the first argument of INPUT or OUTPUT.
 DETACH cancels the association of the variable but does
not affect the file to which it was associated.
{p}
{index  DIFFER}
{Hl 3,DIFFER * -- Test for Arguments Differing}
{Ls 1}
DIFFER(ARGUMENT,ARGUMENT)
{Ls 1}DIFFER is a predicate function which fails if its two arguments are
identical objects.
 In SPITBOL
{brk}
~~~DIFFER(.ABC,'ABC')
{brk}
succeeds since .ABC is a NAME.  DIFFER and IDENT are the only functions
in which the different implementation of the name operator (unary
dot) may give rise to problems.
{index  DUMP}
{Hl 3,DUMP * -- Dump Storage}
{Ls 1}
DUMP(INTEGER)
{Ls 1}The DUMP function causes a dump of current values to occur.
 After the dump is complete, execution continues unaffected (the DUMP
function returns the null string). If the argument is 1, then the
dump includes values of
all non-constant keywords and all non-null natural variables.
 If the argument is 2, then the dump also includes values of all  non-null
array
and table elements and non-null field values of program defined datatypes.
 The format of the latter dump is self explanatory and avoids printing
any structure
more than once.
 A call to DUMP with a zero argument is ignored.  This allows use of
a switch
value which can be turned on and off globally.
 A call to DUMP with an argument greater than 2 produces a core dump
in the same
format as that produced by a system abnormal end and should
therefore be used with discretion.
{index  DUPL}
{Hl 3,DUPL * -- Duplicate String or Pattern}
{Ls 1}
DUPL(STRING,INTEGER) or DUPL(PATTERN,INTEGER)
{Ls 1}DUPL returns a result obtained by duplicating the first argument
the number of
times indicated by the second.
 A null string is returned if INTEGER is zero and statement
failure occurs if it is negative.
{index  EJECT}
{Hl 3,EJECT * -- Eject to new page}
{Ls 1}
EJECT(INTEGER) or EJECT(STRING)
{Ls 1}The argument must have previously appeared as the second argument
of a call of
{index  OUTPUT}
OUTPUT to identify an output channel.  An eject to the top of the
next
page of the output file occurs.
 A null or absent argument causes an eject on the standard output file.
{p}
{index  ENDFILE}
{Hl 3,ENDFILE * -- Close a File}
{Ls 1}
ENDFILE(INTEGER) or ENDFILE(STRING)
{Ls 1}The argument must have previously appeared as the second argument
of a call of
{index  INPUT}
{index  OUTPUT}
INPUT or OUTPUT
to identify an input/output channel.  The file attached to the channel
is closed, associated storage is
released and all variables associated with the file are detached.
 Thus ENDFILE
should be used only when no further use is to be made of the file.
 If the file is to be reread or rewritten, use REWIND (if the implementation
supports this function - see {SEC_IMPL}).
{Hl 3,EQ -- Test for Equal}
{Ls 1}
EQ(NUMERIC,NUMERIC)
{Ls 1}EQ is a predicate function which succeeds if its two arguments are
equal.
{index  EVAL}
{Hl 3,EVAL * -- Evaluate Expression}
{Ls 1}
EVAL(EXPRESSION)
{Ls 1}EVAL returns the result of evaluating its expression argument.  Note
that a string
can be converted into an expression by compiling it into CODE.  Thus
EVAL
in SPITBOL is compatible with SNOBOL4 and handles strings in the same
way.  If an error occurs in evaluating the argument,
{index  &ERRTEXT}
&ERRTEXT is set and EVAL fails.  To avoid such errors passing
{index  SETEXIT}
unnoticed, it may be well to use SETEXIT to intercept them,
{index  -NOFAIL}
or use a FAIL goto, or evaluate in -NOFAIL  mode.
{index  EXIT}
{Hl 3,EXIT * -- Exit to Save Load Module or to JCL}
{Ls 1}
EXIT(INTEGER) or EXIT(STRING)
{Ls 1}This function resembles that introduced by Gimpel in SITBOL.
 It permits the saving of a core image at any point in the execution
of a SPITBOL
program to produce a  load module
{index  load module}
and in some implementations
it may be permissible to exit from SPITBOL into another program.  For
an often executed program
use of a load module saves translation and initialisation time.
{index garbage collection}
 A garbage collection is performed
in order to compact store before it is saved.  If initialising code
is label free,
it is collectable after it has been executed, giving a further opportunity
for economy.
 The argument, N, may have the following values --
{p}
{List}
{Listelem}N > 0 ~~Save the whole core image (includes all the pure SPITBOL
code and unused stack space, so is wasteful). The resulting load module
is free-standing and is not made obsolete by changes to SPITBOL.
{Listelem}N = 0~~ Interrupt program execution and return to JCL level so
that
user can issue JCL commands and then resume execution if wished.
 Does not save a core image.
{Listelem}N < 0~~Save the impure areas of memory only so that program can
be restarted by loading pure SPITBOL code + the saved areas.  The resulting
load modules
are considerably smaller than for the case N = 1, but are made obsolete
and must be
regenerated as new versions of SPITBOL are released.
{Listelem}N = "string".  If this feature is available, (see {SEC_IMPL}),
then SPITBOL execution is terminated and the program named by "string"
is entered.
{Endlist}
{Ls 1}EXIT returns the null string and may occur in the program at any
position
syntactically valid for a function call.  No mechanism is provided
for automatic
re-attaching of files which are in use at the time an EXIT call terminates
a run.
 Hence EXIT calls are most commonly placed after initialising code
and before the opening of input/output files for the program proper.
 In general no standard input file is available when a load module
is run,
so references to variable INPUT will fail unless it has been detached
or a file
is explicitly associated to it.
 The absence of a standard output file may create problems (in reporting
run time errors in particular). SPITBOL implementors will usually
provide a
means of attaching such a file at load time.  Alternatively a user
may prefer to include a statement
{brk}
{Ls 1}
~~~~~OUTPUT(.OUTPUT,,'FILENAME')
{Ls 1}
Failing these possibilities, either a default output file name should
be allocated
or execution should end with a special error code if printing to a
non-existent standard file is attempted.  {SEC_IMPL} gives
details for this implementation.
 Certain listing options may be selected by choice of the argument
value.
{brk}
~~N = +1 or -1. The output file will be given a heading and
in some implementations it may be possible to re-specify record length
(only to a smaller value than during compilation) and other options.
{brk}
~~N = +2 or -2. Heading omitted but re-specification of options may
be possible.
{brk}
~~N = +3 or -3. Heading omitted and no option re-specification.
{p}
{index FENCE}
{Hl 3,FENCE * -- Generate Fenced Pattern}
{Ls 1}
FENCE(PATTERN)
{Ls 1}FENCE(pattern) returns a pattern value which is the same as the given
pattern, except that alternatives within the pattern are only seen
by the scanner when it is moving in the forward direction.
 Pattern backup will always pass through FENCE(pattern).
 Note that backup through FENCE(pattern) does {ul not} cause the match
to abort, as does the &FENCE pattern,
it is that alternatives within the Fenced pattern are not
examined when the scanner is backing up.
For example, this pattern will match a string of
text up to the next comma, or if there is no comma, to the end of the string.
 The text is put in STR, and the match will only succeed if STR is non-null.
{Center <P = FENCE( BREAK(',') | REM ) $ STR  *DIFFER(STR)>}
{Brk}Without the FENCE, failure of the DIFFER(STR) would cause the scanner
to try the REM alternative regardless of whether or not a comma is found.
{Ls 1}FENCE is not available in all implementations.
 See {SEC_IMPL}.
{index  FIELD}
{Hl 3,FIELD * -- Get Field Name}
{Ls 1}
FIELD(NAME,INTEGER)
{Ls 1}FIELD returns the NAME of the selected field of the program defined
datatype whose name is the first argument.
 If the second argument is out of range (less than 1, or greater than
the number
of fields), the FIELD function fails.
{index  GE}
{Hl 3,GE -- Test for Greater or Equal}
{Ls 1}
GE(NUMERIC,NUMERIC)
{Ls 1}GE is a predicate function which succeeds if the first argument
is greater than or equal to the second.
{index  GT}
{Hl 3,GT -- Test for Greater}
{Ls 1}
GT(NUMERIC,NUMERIC)
{Ls 1}GT is a predicate function which succeeds if the first argument
is greater than the second.
{index  HOST}
{Hl 3,HOST * -- Obtain Information about Host Computer}
{Ls 1}
HOST(ARGUMENT,ARGUMENT,ARGUMENT)
{Ls 1}SPITBOL runs on different mainframes with differing file formats,
file naming conventions etc.  which makes it desirable in some
programs to know on what machine the program is running.
 HOST called with null arguments returns a string of the form
{nfj}
   "<<COMPUTER NAME>>:<<OPERATING SYSTEM NAME>>:<<SITE NAME>>"
{fj}
which satisfies most requirements of this kind.
 At the discretion of the SPITBOL implementor, non-null arguments may
be
used to specify other features specific to the host.  See {SEC_IMPL}
for details.
{index  IDENT}
{Hl 3,IDENT * -- Test for Identical}
{Ls 1}
IDENT(ARGUMENT,ARGUMENT)
{Ls 1}IDENT is a predicate function which succeeds if its two arguments
are identical.
 In SPITBOL,
{brk}
~~~IDENT(.ABC,'ABC')
{brk}
fails since .ABC is a NAME in SPITBOL.
 Apart from this, IDENT is compatible with SNOBOL4.
{p}
{index  INPUT}
{Hl 3,INPUT * -- Set Input Association}
{Set Sec_Inputfunc,@Hlval}
{Ls 1}
INPUT(NAME,INTEGER,STRING) or INPUT(NAME,STRING,STRING)
{index  OUTPUT}
{Ls 1}Rather than give a separate description of OUTPUT which would be
almost exactly parallel with that for INPUT, a joint description is
given here.
 Some machine dependency is likely in these functions - see 
{SEC_IMPL} for details relating to this implementation.
{Ls 1}The first argument is the name of a variable which is to be input/output
associated and is required, whereas the others are optional.
 The second argument identifies a channel which may subsequently
be used to refer to the association.
 It is recommended that, as in SNOBOL4, the second argument be an integer
but the use of a more
general string is not excluded.  Different channel identifiers are
required for
accessing different files.
 The second argument may be omitted in which case association is to
the standard input or output file.
 The chief divergence between SNOBOL4 and SPITBOL is in the use
of the third argument, where SPITBOL permits the very useful feature
of dynamic file assignment.
 The general form of the third argument is a string
{Ls 1}~~~~<<f>>,R<<r>>,C<<c>>,I<<i>>,X<<x>>...~~~~~~where
{Ls 1}{Lin 4}
{Outdent 4}<<f>>~is an optional file name which is placed first;
{Ls 1}
{Outdent 4},~~~is a delimiter used to mark off
remaining items which are optional and
may occur in any order;
{Ls 1}{Outdent 4}<<r>>~is the maximum record length in characters for the file
(default values are documented in {SEC_IMPL});
{Ls 1}
{Outdent 4}<<c>>~is a carriage control character or string needed
in some implementations;
{Ls 1}{Outdent 4}<<i>>~is additional channel identification
needed in some implementations
in the absence of <<f>> to associate the variable with a file attached by
job control commands at the start of a SPITBOL run;
{Ls 1}{Outdent 4}<<x>>~symbolises additional
fields needed in particular implementations.
{Ls 1}{Restore lmg}
If <<f>> is non-null, when the statement is obeyed file <<f>> is
opened and assigned to the channel corresponding to the second
argument and normally this assignment should be performed once only.
 If several variables are to be associated to the same channel,
<<f>> should be omitted from all but the first of the INPUT/OUTPUT
calls.
{p}
Alternatively <<f>> can be omitted from all INPUT/OUTPUT
statements relating to a channel provided the necessary
assignments are performed by suitable job control commands before
execution starts.  Thus --
{brk}
~~~INPUT(.IN,2,'INFILE');~~~~OUTPUT(.OU,7,'OUF')
{brk}
~~~INPUT(.IN,2);~~~~~~~~~~~~~OUTPUT(.OU,7)
{brk}
will have the same effect if in the latter case INFILE
, OUF have been suitably attached by JCL commands.
 A call in which <<f>> is omitted but some other item is present in
the
third argument, alters the association of the channel in respect of
that
item only.  E.g. INPUT(.X,,',R72') sets the maximum
record length to 72 characters.
{Ls 1}
Error messages are given for syntactically invalid third arguments but
in the case where the file corresponding to a syntactically
valid file name cannot be found, then statement failure occurs and
may be tested
for in the usual way by a conditional goto.
 For the sake of portability and compatibility, programmers are strongly
urged to use integer second arguments (as in SNOBOL4) and short
alphanumeric file names in the third argument.
 Further details, particular to an implementation, are given in {SEC_IMPL}.
{index  INTEGER}
{Hl 3,INTEGER * -- Test for Integer}
{Ls 1}
INTEGER(NUMERIC)
{Ls 1}INTEGER is a predicate function which succeeds if its argument is
integral.
 It fails if the argument cannot be converted to numeric or has a non-integral
value.
{index  ITEM}
{Hl 3,ITEM -- Select Array or Table Element}
{Ls 1}
ITEM(ARRAY,INTEGER,INTEGER,....) or  ITEM(TABLE,ARGUMENT)
{Ls 1}ITEM returns the selected array or table element by name.  Note that
the
use of ITEM is never necessary in SPITBOL because of the extended
syntax for
array references.
{index  LE}
{Hl 3,LE -- Test for Less or Equal}
{Ls 1}
LE(NUMERIC,NUMERIC)
{Ls 1}LE is a predicate function which succeeds if its first argument is
less than or equal to the second argument.
{p}
{index  LEN}
{Hl 3,LEN -- Generate Specified Length Pattern}
{Ls 1}
LEN(INTEGER) or LEN(EXPRESSION)
{Ls 1}LEN generates a pattern which will match any sequence of characters
of length given
by the argument which must be a non-negative integer.
 If the argument is an expression, it is evaluated during pattern
matching
and must yield a non-negative integer.
{index  LEQ}
{Hl 3,LEQ * -- Test for Lexically Equal}
{Ls 1}
LEQ(STRING,STRING)
{Ls 1}LEQ is a predicate which succeeds if its arguments are lexically
equal.
 LEQ differs from IDENT in that its arguments are
converted to strings so that both the following succeed
{brk}
~~~LEQ(10,'10') ~~~~~~~~~~~~LEQ(.ABC,'ABC')
{index  LGE}
{Hl 3,LGE * -- Test for Lexically Greater or Equal}
{Ls 1}
LGE(STRING,STRING)
{Ls 1}LGE is a predicate which succeeds if the first argument is lexically
greater than or equal to the second argument.
{index  LGT}
{Hl 3,LGT * -- Test for Lexically Greater}
{Ls 1}
LGT(STRING,STRING)
{Ls 1}LGT is a predicate which succeeds if the first argument is lexically
greater than the second argument.
{index  LLE}
{Hl 3,LLE * -- Test for Lexically Less or Equal}
{Ls 1}
LLE(STRING,STRING)
{Ls 1}LLE is a predicate which succeeds if the first argument is lexically
less than or equal to the second argument.
{p}
{index  LLT}
{Hl 3,LLT * -- Test for Lexically Less}
{Ls 1}
LLT(STRING,STRING)
{Ls 1}LLT is a predicate which succeeds if the first argument is lexically
less than the second argument.
{index  LNE}
{Hl 3,LNE * -- Test for Lexically Not Equal}
{Ls 1}
LNE(STRING,STRING)
{Ls 1}LNE is a predicate which succeeds if its arguments are lexically
unequal.
 LNE differs from DIFFER in that its arguments are
converted to strings so that both the following fail
{brk}
~~~LNE(10,'10') ~~~~~~~~~~~~~~~~LNE(.ABC,'ABC')
{index  LOAD}
{Hl 3,LOAD -- Load External Function}
{Ls 1}
LOAD(STRING,STRING)
{Ls 1}LOAD is used to make external functions available to SPITBOL programs.
 The first STRING is a prototype of the form:
{Ls 1}~~~"function-name(type,type,...)result-type"{Ls 1}
The indicated types can be any of "INTEGER", "REAL" (if implemented)
or "STRING" in which case the value is converted to the designated type
before being passed to (returned from) the external function.
 Any other name for a type leaves the value in an unconverted form.
{Ls 1}The second argument to LOAD is a library name where the
function is to be found.
{Ls 1}LOAD is highly implementation specific and is not available
in all implementations.
 See {SEC_IMPL} for details.
{index  LOCAL}
{Hl 3,LOCAL * -- Get Name of Local}
{Ls 1}
LOCAL(NAME,INTEGER)
{Ls 1}The value returned is the NAME of the indicated local of the function
whose name is given by the first argument.
 LOCAL fails if the second argument is out of range (less than 1, or
greater than the number of locals).
{p}
{index  LPAD}
{Hl 3,LPAD * -- Left Pad}
{Ls 1}
LPAD(STRING,INTEGER,STRING)
{Ls 1}LPAD returns the result obtained by padding out the first argument
on the left
to the length specified by the second argument, using the pad character
supplied
by the one character string third argument.  If the third argument
is null
or omitted, a blank is used as the pad character.  If the first argument
is already
long enough or too long, it is returned unchanged, this always being
the case if the second argument is negative or zero.  LPAD is useful for
constructing columnar output.
{index  LT}
{Hl 3,LT -- Test for Less}
{Ls 1}
LT(NUMERIC,NUMERIC)
{Ls 1}LT is a predicate function which succeeds if its first argument is
less than the second.
{index  NE}
{Hl 3,NE -- Test for Not Equal}
{Ls 1}
NE(NUMERIC,NUMERIC)
{Ls 1}NE is a predicate function which succeeds if its two arguments are
unequal.
{index  NOTANY}
{Hl 3,NOTANY -- Build Character Select Pattern}
{Ls 1}
NOTANY(STRING) or NOTANY(EXPRESSION)
{Ls 1}NOTANY returns a pattern which will match any single character in
the subject
string, provided it does not occur in the string argument.
 A null argument is not permitted.
 If the argument is an expression, it is evaluated during pattern
matching
and must yield a non-null string.
{p}
{index  OPSYN}
{Hl 3,OPSYN * -- Equate Functions and Operators}
{Ls 1}
OPSYN(NAME,NAME,INTEGER)
{Ls 1}In contrast with SNOBOL4, the second argument must always be an already
defined function name.  If the third argument is omitted or zero, the
first
argument must be a function name.  If the third argument is 1 or 2
, the
first argument must be resp.  one of the undefined unary or binary
operators (sec 4.1).
 In all three cases, subsequent use of the first argument
results in calling of the function corresponding to the second argument
with the appropriate arguments.
 Note that names of system functions or operators cannot appear as
the first argument.
{index  OUTPUT}
{Hl 3,OUTPUT * -- Set Output Association}
{Ls 1}
OUTPUT(NAME,INTEGER,STRING) or OUTPUT(NAME,STRING,STRING)
{Ls 1}This function has similar arguments and behaves similarly
to INPUT, which should be consulted for a detailed description
({SEC_INPUTFUNC}).
{index  POS}
{Hl 3,POS -- Define Positioning Pattern}
{Ls 1}
POS(INTEGER) or POS(EXPRESSION)
{Ls 1}POS returns a pattern which matches the null string provided the
value of
the cursor is equal to the non-negative integer argument.
 If the argument is an expression, it is evaluated during pattern
matching
and must yield a non-negative integer.
{p}
{index  PROTOTYPE}
{Hl 3,PROTOTYPE -- Retrieve Prototype}
{Ls 1}
PROTOTYPE(ARRAY) or PROTOTYPE(TABLE)
{Ls 1}PROTOTYPE returns the first argument used in the ARRAY or TABLE function
call which created the argument.
{index  REMDR}
{Hl 3,REMDR -- Remainder}
{Ls 1}
REMDR(INTEGER,INTEGER)
{Ls 1}REMDR returns the remainder of dividing the first argument by the
second.
 This has the same sign as the first argument.
{index  REPLACE}
{Hl 3,REPLACE -- Translate Characters}
{Ls 1}
REPLACE(STRING,STRING,STRING)
{Ls 1}REPLACE returns the result of applying the transformations represented
by the
second and third arguments to the first argument.  REPLACE fails
if the second and third arguments are unequal in length or null.
{index  REVERSE}
{Hl 3,REVERSE * -- Reverse String}
{Ls 1}
REVERSE(STRING)
{Ls 1}REVERSE returns the result of reversing its argument.  Thus
{brk}
~~~REVERSE('ABC') ~~~~~~~~~~~produces~~~~~~~~~~'CBA'
{index  REWIND}
{Hl 3,REWIND -- Reposition File}
{Ls 1}
REWIND(INTEGER) or REWIND(STRING)
{Ls 1}The argument must have previously appeared as the second argument
of a call of
{index  INPUT}
{index  OUTPUT}
INPUT or OUTPUT.
 The file attached to the channel is repositioned so that the next
read or write operation starts at the first record of the file.
 Existing associations to the file are unaffected.
 REWIND may not be provided in all implementations - see {SEC_IMPL}.
{p}
{index  RPAD}
{Hl 3,RPAD * -- Right Pad}
{Ls 1}
RPAD(STRING,INTEGER,STRING)
{Ls 1}RPAD returns the result obtained by padding out the first argument
on the right
to the length specified by the second argument, using the pad character
supplied
by the one character string third argument.  If the third argument
is null
or omitted, a blank is used as the pad character.  If the first argument
is already
long enough or too long, it is returned unchanged, this always being
the case if the second argument is negative or zero.  RPAD is useful
for
constructing columnar output.
{index  RPOS}
{Hl 3,RPOS -- Define Positioning Pattern}
{Ls 1}
RPOS(INTEGER) or RPOS(EXPRESSION)
{Ls 1}RPOS returns a pattern which matches the null string provided
the indicated number of characters remain to be matched in the subject
string.
 If the argument is an expression, it is evaluated during pattern
matching
and must yield a non-negative integer.
{index  RSORT}
{Hl 3,RSORT -- Reverse Sort}
{Ls 1}
RSORT(ARRAY or TABLE,INTEGER or NAME)
{Ls 1}Performs a sort in descending (reverse) order of key
on the first argument.  Consult SORT for details.
{index  RTAB}
{Hl 3,RTAB -- Create Tabbing Pattern}
{Ls 1}
RTAB(INTEGER) or RTAB(EXPRESSION)
{Ls 1}RTAB returns a pattern which matches from the current location up
to the
point where the indicated number of characters remain to be matched.
 The argument must be a non-negative integer.
 If the argument is an expression, it is evaluated during pattern
matching
and must yield a non-negative integer.
{p}
{index  SETEXIT}
{Hl 3,SETEXIT * -- Set Error Exit}
{Ls 1}
SETEXIT(NAME) or SETEXIT()
{Ls 1}SETEXIT allows interception of  execution errors, including any
{index  CODE}
{index  EVAL}
detected during calls of CODE and EVAL .
 The argument is a label to which control is passed if a subsequent
error occurs,
providing that the value of the keyword &ERRLIMIT is non-zero.
 The value of &ERRLIMIT is decremented when the error trap occurs.
 A SETEXIT call with a null argument causes
cancellation of error intercepts.
 A subsequent error will terminate execution as usual with an error
message.
 The result returned by SETEXIT is the previous intercept setting
(i.e. a label name or null if no intercept was set). This can be used
to save
and restore the SETEXIT conditions recursively.
 The error routine may inspect the error code and text
{index  &ERRTYPE}
{index  &ERRTEXT}
in &ERRTYPE and &ERRTEXT , and take one of the actions --
{List}
{Listelem}Terminate execution by transferring to the special system label,
{index  ABORT}
ABORT .
 This causes error processing to resume as though no error intercept
had been set.
{index  CONTINUE}
{Listelem}Branch to the special system label CONTINUE .
 This causes execution to resume by branching to the failure exit of
the statement
in error.
{Listelem}Continue execution elsewhere by branching to another section of
the program.
 If the error occurred inside a function, execution is still
'down a level'.
{index  RETURN}
{index  FRETURN}
{index  NRETURN}
{Listelem}Branch to label RETURN , FRETURN , NRETURN provided
{index  &FNCLEVEL}
&FNCLEVEL is non-zero.  This avoids possible difficulties with 3.
{Endlist}
The occurrence of an error cancels the intercept.
 An error routine must reissue a SETEXIT call if error interception
is to continue.
{p}
{index  SIZE}
{Hl 3,SIZE -- Get String Size}
{Ls 1}
SIZE(STRING)
{Ls 1}SIZE returns an integer count of the length of its argument.
{index  SORT}
{Hl 3,SORT * -- Sort}
{Ls 1}
SORT(ARRAY or TABLE,INTEGER or NAME)
{index  ARRAY}
{Ls 1}This routine sorts the contents of the ARRAY or
{index  TABLE}
TABLE first argument in ascending order of key.  It differs from
{index  RSORT}
RSORT only in that the latter sorts in descending order
of key.  If the first argument is an ARRAY it must be of one dimension
{index  VECTOR}
{index  MATRIX}
(subsequently referred to as a VECTOR ), or two dimensions (a MATRIX~).
{index  TABLE}
Where the argument is a TABLE , it is converted by SORT
to an array of 2 dimensions, the first column containing the reference
or key item and the second the value, in exactly the same way as
{index  CONVERT}
results from a call to CONVERT . This is then sorted just as
any other two dimensional array.
 In all cases, the items
to be sorted may be of mixed dataypes and the sorting is done primarily
on datatype of key, using lexical ordering of datatype names,
and secondarily on value.  Thus items of similar
datatypes become contiguously grouped
in sorted order.  The only deviation from this rule is that mixed
{index  INTEGER}{index  REAL}{index  NUMERIC}
INTEGER and REAL (NUMERIC~) items are sorted as a single group
and strings which can be converted to NUMERIC are compared numerically
against NUMERIC keys.  In particular the NULL
string is regarded as 0 or 0.0 in comparison with them.
{index  <NULL string>}
Note that compared numerically, 100 > "20" but compared
lexically "100" < "20".
 A second argument, if specified for an ARRAY or TABLE, must be an integer
corresponding to a column index (1 or 2 for a TABLE). The keys are
then taken from this column, and during the sort,
complete rows are permuted to the order determined by key values.
 If the second argument is omitted, the default column used is that
corresponding to the smallest value of the second index (e.g
-2 in M = ARRAY('10,-2:+2')).
 The sorting method used is stable with respect
to non-interchange of items having equal keys, so that repeated
sorting on successive columns may be used to effect a total ordering.
{index  NAME}
{Ls 1}In the case of a VECTOR, the optional second argument may be the NAME
{index  DATA}
of a field of a programmer defined datatype created by DATA . In this
case, if any of the values in the VECTOR are of this type, the contents
of the field corresponding to NAME  are used as the key.
 If the second argument is omitted, the sorting is carried out
by using the values the VECTOR contains as keys.
{p}
The sort method used is Heapsort (see for instance Horowitz and Sahni,
"Fundamentals of Data Structures", Pitman 1977) modified
so that no interchanging of equal keys occurs.
 It is efficient in usage of
both space and time, the time taken to sort N items being proportional
to N~*~log(N).
 The aggregate
obtained is always a sorted copy of the original.
 No extra store is used for the sort except in the case of a TABLE,
where space sufficient for conversion to an ARRAY is taken.
 Examples of calls are -
{brk}
{nfj}
*  Assume USERS is an ARRAY of programmer defined datatypes
*  of the type created by ~~~~~~DATA('COMPUSER(NAME,TYME)')
~~~~~~SUS = RSORT(SORT(USERS,.NAME),.TYME)
{fj}
which creates an array sorted primarily by tyme in descending
order  and secondarily by name in alphabetic order.
{nfj}
~~~~~~MATX = SORT(SORT(SORT(MATX,3),2))
which sorts MATX respectively by columns 3, 2, 1.
~~~~~~V = SORT(V)
which sorts V  by its elements.
{fj}
{index  SPAN}
{Hl 3,SPAN -- Create Spanning Pattern}
{Ls 1}
SPAN(STRING) or SPAN(EXPRESSION)
{Ls 1}SPAN creates a pattern which, starting from the current cursor position,
will match the longest non-null sequence of characters
drawn from the character set contained in the argument.
 The argument is not permitted to be null.
 If the argument is an expression, it is evaluated during pattern matching
and must yield a non-null string.
{index  STOPTR}
{Hl 3,STOPTR * -- Stop Trace}
{Ls 1}
STOPTR(NAME,STRING)
{Ls 1}STOPTR terminates tracing for the name given by the first argument.
 The second argument
designates the respect in which the trace is to be stopped
and consists of one of the strings listed under the description of
TRACE.
{p}
{index  SUBSTR}
{Hl 3,SUBSTR * -- Extract Substring}
{Ls 1}
SUBSTR(STRING,INTEGER,INTEGER)
{Ls 1}Extracts a substring from the first argument.  The second argument
specifies the first character (1 = start of string) and the third
argument
gives the number of characters.
 An omitted third argument specifies all remaining characters of the
string.
 Improper substrings cause statement failure.
{index  TAB}
{Hl 3,TAB -- Create Tabbing Pattern}
{Ls 1}
TAB(INTEGER) or TAB(EXPRESSION)
{Ls 1}TAB returns a pattern which matches from the current location up
to the
point where the indicated number of characters have been matched.
 The argument must be a non-negative integer.
 If the argument is an expression, it is evaluated during pattern matching
and must yield a non-negative integer.
{index  TABLE}
{Hl 3,TABLE * -- Create Table}
{Ls 1}
TABLE(INTEGER,,ARG)
{Ls 1}The TABLE function creates an associative table as in SNOBOL4.
 However in SPITBOL, the table is implemented internally using an efficient
{index  hashing}
hashing algorithm.
 The integer argument is the number of hash headers used.
 If it is omitted, 11 is used by default.
 If N is the number of entries in the table, and H is the number of hash
headers, the average number of probes to find an entry rises from
about 1.0 for small N, to N/2H if N is large compared with H.
 Since the overhead for hash headers is small compared to the
size of a table element, a useful guide is to use as argument
an estimate
of the number of entries to be stored in the table.
 Any second argument (permitted for SNOBOL4 compatibility) is always
ignored.  The optional third argument is a value which it is desired
to have returned instead of the default NULL, when
table look-up is performed using a key which has not been entered
into the TABLE.  This is similar in effect to the usage of the
{index  ARRAY}
second argument of ARRAY.
 In contrast with SNOBOL4, where the first reference to an
entry automatically creates a table entry, in SPITBOL an
entry is inserted in a table only when an assignment is explicitly
made.  Thus table look-up for a currently missing key does not
create an entry for that key and may be freely used.
{p}
{index  TIME}
{Hl 3,TIME -- Get Timer Value}
{Ls 1}
TIME()
{Ls 1}TIME returns the integer number of milliseconds of processor time
since the start of execution.
{index  TRACE}
{Hl 3,TRACE * -- Initiate Trace}
{Ls 1}
{index  debugging}
{Ls 1}The TRACE function, which is quite invaluable as a debugging aid,
initiates a trace of the item whose name is given by the first argument.
 The second argument specifies the sense of the trace as follows --
{Ls 1}
{nfj}
{Ls 1}
        'A' or 'ACCESS'               access
        'V' or 'VALUE' or null        value
        'K' or 'KEYWORD'              keyword
        'L' or 'LABEL'                label
        'F' or 'FUNCTION'             function call and return
        'C' or 'CALL'                 function call
        'R' or 'RETURN'               function return
{fj}
{Ls 1}The access trace mode introduced in SPITBOL consists of producing
trace output
each time an access traced item is referenced.
 Attempts to trace a function before a DEFINE statement for it has
been executed will fail.
{index  &STLIMIT}
If &STLIMIT is negative, STCOUNT may not be traced.
 To give a visual impression of depth of nesting, a letter "I" is
included in the trace output for each additional level of function
call.
{index  TRIM}
{Hl 3,TRIM -- Trim Trailing Blanks}
{Ls 1}
TRIM(STRING)
{Ls 1}TRIM returns the result of trimming trailing blanks from the argument
string.
{index  UNLOAD}
{Hl 3,UNLOAD * -- Unload Function}
{Ls 1}
UNLOAD(NAME)
{Ls 1}NAME is the name of an external function which is to be unloaded.
 The names of user defined functions may also appear in calls
to UNLOAD in which case the function becomes undefined.
{Set Subtitle,Keywords}
{p}
{Hl 1,Keywords}
{index  keywords}
{Ls 1}The following is a list of the keywords implemented in SPITBOL.
 The notation (R) after the name indicates that the keyword may only
be read
so that attempts to assign to it will result in an error.
 With the exception of &STLIMIT, values assigned to numeric keywords
{index  MXLEN}
must be in the range 0 to MXLEN .
{List}
{index  &ABEND}
{Listelem &ABEND}&ABEND :
Normally set to zero.  If it is set to a non-zero value at the end
of execution,
{index  ABEND}
an ABEND dump is given.  This should normally only be used for system
checkouts.
{index  &ABORT}
{Listelem &ABORT}&ABORT (R) :
{index  ABORT}
Contains the pattern ABORT .
{index  &ALPHABET}
{Listelem &ALPHABET}&ALPHABET (R) :
Contains the full character set of the host computer in natural collating
sequence.
{index  &ANCHOR}
{Listelem &ANCHOR}&ANCHOR :
Set to one for anchored pattern matching mode and to zero
for unanchored mode.  Initial value is zero to correspond with SNOBOL4.
 However unanchored matching is needed only rarely and is liable to
be
very expensive in runtime unless carefully used, so in general it
is
good practice to start programs with the statement
{brk}
{index  ANCHOR}
~~~~&ANCHOR = 1
{index  &ARB}
{Listelem &ARB}&ARB (R) :
{index  ARB}
Contains the pattern ARB .
{index  &BAL}
{Listelem &BAL}&BAL (R) :
{index  BAL}
Contains the pattern BAL .
{index  &CODE}
{Listelem &CODE}&CODE :
Initially zero.  In implementations where the concept makes sense,
values in the range 1 to 900 found to be in &CODE at termination
are used as ending codes ({SEC_IMPL}).
{index  &DUMP}
{Listelem &DUMP}&DUMP :
The standard value is zero.  If the value is zero at the end of execution,
then
no symbolic dump is given.  A value of one gives a dump including values
of keywords
and natural variables.  If the value is two, the dump includes
non-null array, table and program defined datatype elements as well.
 The dump format is self explanatory and deals with the case of branched
structures including circular lists.  If the value exceeds two, an
{index  ABEND}
ABEND dump is produced as well.
{p}
{index  &ERRLIMIT}
{Listelem &ERRLIMIT}&ERRLIMIT :
{index  SETEXIT}
The maximum number of errors which can be trapped using the SETEXIT
function.
&ERRLIMIT is initially zero and when set non-zero by assignment,
it is decremented each time a SETEXIT trap occurs.
 SETEXIT has no effect on normal error processing if &ERRLIMIT is
zero.
{index  &ERRTEXT}
{Listelem &ERRTEXT}&ERRTEXT :
If an execution error occurs, then
the error message text corresponding to the error code is stored as
a string in &ERRTEXT.
 It is possible to assign a string to &ERRTEXT which is then used
in a subsequent
error report if &ERRTYPE is assigned a value out of the range used
by SPITBOL itself.
 Such an assignment does not signal an error as is the case with &ERRTYPE.
{index  &ERRTYPE}
{Listelem &ERRTYPE}&ERRTYPE :
If an execution error occurs, then
the error code is stored as an integer in &ERRTYPE.
&ERRTYPE may be assigned a value in which case an immediate error
is signalled.
 This may be useful in reporting program detected errors.
 Error codes used by SPITBOL all fall below 300.
{index  SETEXIT}
Values in &ERRTEXT and &ERRTYPE are useful in SETEXIT error
intercept routines.
{index  &FAIL}
{Listelem &FAIL}&FAIL (R) :
{index  FAIL}
Contains the pattern FAIL .
{index  &FENCE}
{Listelem &FENCE}&FENCE (R) :
{index  FENCE}
Contains the pattern FENCE .
{index  &FNCLEVEL}
{Listelem &FNCLEVEL}&FNCLEVEL (R) :
Contains the current function nesting level.
{index  &FTRACE}
{Listelem &FTRACE}&FTRACE :
The standard value is zero.
 If it is set positive, each function call and return is traced.
 The value of &FTRACE is decremented  for each trace line printed
until the value reaches zero again.
{index  &INPUT}
{Listelem &INPUT}&INPUT :
Set to one for normal input (standard value). If set to zero, all
input
associations are ignored.
{index  &LASTNO}
{Listelem &LASTNO}&LASTNO (R) :
Contains the number of the last statement executed.
{index  &MAXLNGTH}
{Listelem &MAXLNGTH}&MAXLNGTH :
Contains the maximum permitted string length.  At the start of execution
its value is that given by MXLEN ({SEC_IMPL}). It may be set to
{index  MXLEN}
smaller values but not to a value exceeding MXLEN .
{index  &OUTPUT}
{Listelem &OUTPUT}&OUTPUT :
Set to one for normal output (standard value). If set to zero, all
output associations are ignored.
{index &PROFILE}
{Listelem &PROFILE}&PROFILE~:
When set to zero (the default), statement profiling is disabled.
 When set to one, statement profiling is enabled.
 When statement profiling is enabled, SPITBOL keeps track of
 the count of each statement executed, and the amount of central
processor time accumulated for executing each statement.
 If profiling is enabled at any time during an execution, the
accumulated profile is printed on the standard output channel
when the program terminates.
 The profile also indicates the average time for executing each statement.
{Ls 1}If &PROFILE is set to two, it acts as in the case for &PROFILE=1,
except that function calls are charged to the statements which contain
them.
{Ls 1}&PROFILE is not available in all implementations, and for
some machines where processor time is not available, the time indicated
may be wall time.
 In all cases, the enabling of the profile adds additional time to the
execution, so the times indicated should be viewed as relative.
{index  &REM}
{Listelem &REM}&REM (R) :
{index  REM}
Contains the pattern REM .
{index  &RTNTYPE}
{Listelem &RTNTYPE}&RTNTYPE (R) :
Contains 'RETURN', 'FRETURN' or 'NRETURN' depending on the type of
function return most recently executed.
{index  &STCOUNT}
{Listelem &STCOUNT}&STCOUNT :
Contains a count of the number of statements executed unless &STLIMIT
is negative.
{index  &STLIMIT}
{Listelem &STLIMIT}&STLIMIT :
The maximum number of statements permitted to be executed.
 Initially 50000 and with an implementation dependent maximum ({SEC_IMPL})
beyond which it cannot be set.
 To inhibit this check on numbers of statements executed, assign a
negative
value to the keyword.  Thus
{brk}
~~~~~~~~&STLIMIT = -1
{brk}
is equivalent to &STLIMIT = "infinity". This will result in a marginal
execution speed up since count updating and checking is omitted.  The
value
of &STCOUNT remains frozen at the value reached when &STLIMIT was
set negative
and the number of statements executed is omitted from the execution
statistics.
 Tracing of STCOUNT becomes no longer possible since its value is not
incremented.
{index  &STNO}
{Listelem &STNO}&STNO (R) :
The number of the current statement.
{index  &SUCCEED}
{Listelem &SUCCEED}&SUCCEED (R) :
{index  SUCCEED}
Contains the pattern SUCCEED .
{index  &TRACE}
{Listelem &TRACE}&TRACE :
Initial value of zero suppresses trace output.  If assigned a positive
value, trace output is generated and for each line printed &TRACE
is decremented by one until the value reaches zero again.
{index  &TRIM}
{Listelem &TRIM}&TRIM :
Set to zero for normal input mode (default value). If the value is
set non-zero, all input records are automatically trimmed (trailing
blanks are removed).
 For operating systems having file formats in which variable length
records may have trailing blanks suppressed, a setting of zero does
not imply
that padding to a standard size occurs, merely that
any trailing blanks which are actually present will be preserved.
 For most applications, initialising the value to 1 is to be recommended.
{Endlist}
{Set Subtitle,Program Listing and Control Cards}
{p}
{Hl 1,Program Listing and Control Cards}
{index  Control cards}
{index  Listing}
{Ls 1}
Normally a listing of the source program is produced in
which statements are prefixed with a statement number.  This listing
usually starts with a heading identifying the SPITBOL version, and
giving date and time of run.  Where this is considered inappropriate
it may be suppressed ({SEC_IMPL}). Many of the control cards
to be described permit choice of other listing options.
 Control cards
are identified by a minus sign in column one.
 They may occur anywhere in a source program and take effect when they
are encountered.
 Most of them are special features of SPITBOL and are not available
in SNOBOL4.
 The full names are given for each of them, but they may be abbreviated
since only the first four characters
are significant to the compiler.
{Hl 2,<Listing Control Cards>}
{Ls 1}Listing control cards are used to alter the appearance of the listing.
 They have no other effect on compilation or execution.
 Listing control cards always occur individually.
{brk}
{Ls 2}
{index  -EJECT}
{Hl 3,-EJECT}
{Ls 1}The -EJECT control card causes the compilation listing to be skipped
to the
top of the next page.
 The current title and subtitle (if any) are printed at the top
of the page.
{Ls 2}
{index  -SPACE}
{Hl 3,-SPACE}
{Ls 1}The -SPACE control card causes spaces to be skipped on the current
page.
 If -SPACE occurs with no operand, then one line is skipped.  Alternatively,
an
unsigned integer can be given in columns 8-72
which represents the number of lines to be skipped.  If there is insufficient
space
on the current page, -SPACE acts like -EJECT and the listing is spaced
to the top of the next page.
{Ls 2}
{index  -TITLE}
{Hl 3,-TITLE}
{Ls 1}This card supplies a title for the source program listing.
 The text of the title is taken from columns 8-72 of the -TITLE card.
 The subtitle is cleared to blanks, and an eject to the next page occurs
next time a line is listed.
{index  STITL}
{Hl 3,-STITL}
{Ls 1}The -STITL card is used to supply a subtitle for the source program
listing.
 The text of the subtitle is taken from columns 8-72 of the -STITL
card.
 An eject occurs to the top of the next page
next time a line is listed and the current title (if any)
and the newly supplied subtitle are printed.  If both title and subtitle
are to be changed, then the -TITLE card should precede the -STITL
card.
{p}
{Hl 2,<Option Control Cards>}
{Ls 1}The option control cards allow selection of various compiler options.
 In each case, there are two modes and a pair of control cards which
permit repeated flipping back and forth of the mode within a program.
 Several control options
may be specified on the same control card by separating the names
with commas,
leaving no intervening blanks.  For example
{brk}
-FAIL,LIST,PRINT
{brk}
In the list below, the default option is named first.
{Ls 2}
{index  -LIST}
{index  -NOLIST}
{Hl 3,-LIST -NOLIST}
{Ls 1}The -NOLIST option causes suppression of the normal
statement listing.
 This may be useful for established program, or for terminal output.
 If compilation errors are detected, the offending statements are printed
regardless of the setting of the list mode.
 Some implementations provide a run time option to select NOLIST mode
initially
without the need to insert -NOLIST into the program being run ({SEC_IMPL}).
{Ls 2}
{index  -NOPRINT}
{index  -PRINT}
{Hl 3,-NOPRINT -PRINT}
{Ls 1}Normally control cards are not printed.
 The -PRINT option causes them to be listed, provided the -LIST option
is in effect.
 This option may be useful if serialization is used for updating.
{Ls 2}
{index  -SINGLE}
{index  -DOUBLE}
{Hl 3,-SINGLE -DOUBLE}
{Ls 1}The compilation listing is normally singly spaced.  The -DOUBLE option
causes double spacing to be used, with a blank line folowing each
listed line.
{p}
{index  -IN}
{Hl 3,-INXXX}
{Ls 1}XXX in the above stands for an integer indicating the number of characters
to be read from each record of the SPITBOL source file.
 The normal default is for the compiler to read SPITBOL statements
from columns 1-72 of the input image.
 Longer or shorter input records may be read by specifying
alternative values for XXX.
 If any value other than 72 is in use at the
end of translation, it is used as the maximum record length for data
read from the standard input file.
 For historical reasons, a -IN72 card in effect at the end of compilation
is taken to imply a maximum record length of 80 for execution
time data.
 There is however no need to restrict records to lengths of 72 or 80.
{Ls 2}
{index  -NOERRORS}
{Hl 3,-ERRORS -NOERRORS}
{Ls 1}Normally execution is allowed even when compilation errors occur.
 If it is wished to inhibit execution if compilation errors are detected
then the -NOERRORS option should be selected.
{Ls 2}
{index  -FAIL}
{index  -NOFAIL}
{Hl 3,-FAIL -NOFAIL}
{Ls 1}In SNOBOL4 and in SPITBOL with the -FAIL mode set,
a failure in a statement with no conditional goto is ignored and the
program
execution resumes with the next statement in sequence.  This convention
often leads to
errors going undetected, particuarly in the case of array references
with out of bound subscripts and pattern matches which the user anticipates
will always succeed.  The -NOFAIL option changes this convention.
 If a statement lacking a conditional goto is compiled under the -NOFAIL
option,
then if a failure occurs when the statement is executed, this produces an
execution error with a suitable message.  This option is especially useful
for student jobs and other situations where many small programs are
being debugged.
{Ls 2}
{index  -EXECUTE}
{index  -NOEXECUTE}
{Hl 3,-EXECUTE -NOEXECUTE}
{Ls 1}Normally execution is initiated following compilation.  The -NOEXECUTE
option,
if in force at the end of compilation, inhibits execution.
 A run time option may be provided for the same purpose ({SEC_IMPL}).
{Set Subtitle,Errors}
{p}
{Hl 1,Errors}
{Hl 2,<Compilation Error Messages>}
{Ls 1}When the compiler detects an error, the offending line is printed
with a
marker under the point at which the error was actually detected
and an error code and self-explanatory message is printed.
 Processing of the statement is discontinued and compilation
continues with the next statement.  Execution of a program containing
{index  -NOERRORS}
errors is not suppressed unless the -NOERRORS option has been set.
 If an attempt is made to execute a statement found erroneous
by the compiler, an execution error occurs.
{Hl 2,<Execution Error Messages>}
{index errors}
{Ls 1}Extensive error checking is performed at run time.
 When an error is detected, execution is terminated with an error message
which refers to the number of the erroneous statement.  However,
as described in {SEC_FUNC}, it is possible to avoid automatic execution
termination
and to obtain user error handling facilities by means of the SETEXIT
function.
{Ls 1}In addition to the errors listed here, the implementation may
have additional system errors.
 See {SEC_IMPL}.
{Hl 2,<Error Codes and Messages>}
{Ls 1}The following list details all error messages with the exception
of any which may be particular to certain implementations.
{Ls 1}{Ul <Code                       Message>}{Ls 1}
{Tset input,,Endtext=!**,Fill=False,Just=False,Informat=False}
~~1   Addition left operand is not numeric
~~2   Addition right operand is not numeric
~~3   Addition caused integer overflow
~~4   Affirmation operand is not numeric
~~5   Alternation right operand is not pattern
~~6   Alternation left operand is not pattern
~~7   Compilation error encountered during execution
~~8   Concatenation left opnd is not string or pattern
~~9   Concatenation right opd is not string or pattern
~10   Complementation operand is not numeric
~11   Complementation caused integer overflow
~12   Division left operand is not numeric
~13   Division right operand is not numeric
~14   Division caused integer overflow
~15   Exponentiation right operand is not numeric
~16   Exponentiation left operand is not numeric
~17   Exponentiation caused integer overflow
~18   Exponentiation result is undefined
~19   Exponentiation right operand is negative
~20   Goto evaluation failure
~21   Function called by name returned a value
~22   Undefined function called
~23   Goto operand is not a natural variable
~24   Goto operand in direct goto is not code
~25   Immediate assignment left operand is not pattern
~26   Multiplication left operand is not numeric
~27   Multiplication right operand is not numeric
~28   Multiplication caused integer overflow
~29   Undefined operator referenced
~30   Pattern assignment left operand is not pattern
~31   Pattern replacement right operand is not string
~32   Subtraction left operand is not numeric
~33   Subtraction right operand is not numeric
~34   Subtraction caused integer overflow
~35   Unexpected failure in -NOFAIL mode
~36   Goto ABORT with no preceding error
~37   Goto CONTINUE with no preceding error
~38   Goto undefined label
~39   External function argument is not string
~40   External function argument is not integer
~41   FIELD function argument is wrong datatype
~42   Attempt to change value of protected variable
~43   ANY evaluated argument is not string
~44   BREAK evaluated argument is not string
~45   BREAKX evaluated argument is not string
~46   Expression does not evaluate to pattern
~47   LEN evaluated argument is not integer
~48   LEN evaluated argument is negative or too large
~49   NOTANY evaluated argument is not string
~50   POS evaluated argument is not integer
~51   POS evaluated argument is negative or too large
~52   RPOS evaluated argument is not integer
~53   RPOS evaluated argument is negative or too large
~54   RTAB evaluated argument is not integer
~55   RTAB evaluated argument is negative or too large
~56   SPAN evaluated argument is not string
~57   TAB evaluated argument is not integer
~58   TAB evaluated argument is negative or too large
~59   ANY argument is not string or expression
~60   APPLY first arg is not natural variable name
~61   ARBNO argument is not pattern
~62   ARG second argument is not integer
~63   ARG first argument is not program function name
~64   ARRAY first argument is not integer or string
~65   ARRAY first argument lower bound is not integer
~66   ARRAY first argument upper bound is not integer
~67   ARRAY dimension is zero,negative or out of range
~68   ARRAY size exceeds maximum permitted
~69   BREAK argument is not string or expression
~70   BREAKX argument is not string or expression
~71   CLEAR argument is not string
~72   CLEAR argument has null variable name
~73   COLLECT argument is not integer
~74   CONVERT second argument is not string
~75   DATA argument is not string
~76   DATA argument is null
~77   DATA argument is missing a left paren
~78   DATA argument has null datatype name
~79   DATA argument is missing a right paren
~80   DATA argument has null field name
~81   DEFINE first argument is not string
~82   DEFINE first argument is null
~83   DEFINE first argument is missing a left paren
~84   DEFINE first argument has null function name
~85   Null arg name or missing ) in DEFINE first arg.
~86   DEFINE function entry point is not defined label
~87   DETACH argument is not appropriate name
~88   DUMP argument is not integer
~89   DUMP argument is negative or too large
~90   DUPL second argument is not integer
~91   DUPL first argument is not string or pattern
~92   EJECT argument is not a suitable name
~93   EJECT file does not exist
~94   EJECT file does not permit page eject
~95   EJECT caused non-recoverable output error
~96   ENDFILE argument is not a suitable name
~97   ENDFILE argument is null
~98   ENDFILE file does not exist
~99   ENDFILE file does not permit endfile
100   ENDFILE caused non-recoverable output error
101   EQ first argument is not numeric
102   EQ second argument is not numeric
103   EVAL argument is not expression
104   EXIT argument is not suitable integer or string
105   EXIT action not available in this implementation
106   EXIT action caused irrecoverable error
107   FIELD second argument is not integer
108   FIELD first argument is not datatype name
109   GE first argument is not numeric
110   GE second argument is not numeric
111   GT first argument is not numeric
112   GT second argument is not numeric
113   INPUT third argument is not a string
114   Inappropriate second argument for INPUT
115   Inappropriate first argument for INPUT
116   Inappropriate file specification for INPUT
117   INPUT file cannot be read
118   LE first argument is not numeric
119   LE second argument is not numeric
120   LEN argument is not integer or expression
121   LEN argument is negative or too large
122   LEQ first argument is not string
123   LEQ second argument is not string
124   LGE first argument is not string
125   LGE second argument is not string
126   LGT first argument is not string
127   LGT second argument is not string
128   LLE first argument is not string
129   LLE second argument is not string
130   LLT first argument is not string
131   LLT second argument is not string
132   LNE first argument is not string
133   LNE second argument is not string
134   LOCAL second argument is not integer
135   LOCAL first arg is not a program function name
136   LOAD second argument is not string
137   LOAD first argument is not string
138   LOAD first argument is null
139   LOAD first argument is missing a left paren
140   LOAD first argument has null function name
141   LOAD first argument is missing a right paren
142   LOAD function does not exist
143   LOAD function caused input error during load
144   LPAD third argument not a string
145   LPAD second argument is not integer
146   LPAD first argument is not string
147   LT first argument is not numeric
148   LT second argument is not numeric
149   NE first argument is not numeric
150   NE second argument is not numeric
151   NOTANY argument is not string or expression
152   OPSYN third argument is not integer
153   OPSYN third argument is negative or too large
154   OPSYN second arg is not natural variable name
155   OPSYN first arg is not natural variable name
156   OPSYN first arg is not correct operator name
157   OUTPUT third argument is not a string
158   Inappropriate second argument for OUTPUT
159   Inappropriate first argument for OUTPUT
160   Inappropriate file specification for OUTPUT
161   OUTPUT file cannot be written to
162   POS argument is not integer or expression
163   POS argument is negative or too large
164   PROTOTYPE argument is not table or array
165   REMDR second argument is not integer
166   REMDR first argument is not integer
167   REMDR caused integer overflow
168   REPLACE third argument is not string
169   REPLACE second argument is not string
170   REPLACE first argument is not string
171   Null or unequally long 2nd, 3rd args to REPLACE
172   REWIND argument is not a suitable name
173   REWIND argument is null
174   REWIND file does not exist
175   REWIND file does not permit rewind
176   REWIND caused non-recoverable error
177   REVERSE argument is not string
178   RPAD third argument is not string
179   RPAD second argument is not integer
180   RPAD first argument is not string
181   RTAB argument is not integer or expression
182   RTAB argument is negative or too large
183   TAB argument is not integer or expression
184   TAB argument is negative or too large
185   RPOS argument is not integer or expression
186   RPOS argument is negative or too large
187   SETEXIT argument is not label name or null
188   SPAN argument is not string or expression
189   SIZE argument is not string
190   STOPTR first argument is not appropriate name
191   STOPTR second argument is not trace type
192   SUBSTR third argument is not integer
193   SUBSTR second argument is not integer
194   SUBSTR first argument is not string
195   TABLE argument is not integer
196   TABLE argument is out of range
197   TRACE fourth arg is not function name or null
198   TRACE first argument is not appropriate name
199   TRACE second argument is not trace type
200   TRIM argument is not string
201   UNLOAD argument is not natural variable name
202   Input from file caused non-recoverable error
203   Input file record has incorrect format
204   Memory overflow
205   String length exceeds value of MAXLNGTH keyword
206   Output caused file overflow
207   Output caused non-recoverable error
208   Keyword value assigned is not integer
209   Keyword in assignment is protected
210   Keyword value assigned is negative or too large
211   Value assigned to keyword ERRTEXT not a string
212   Syntax error.  Value used where name is required
213   Syntax error.  Statement is too complicated.
214   Syntax error.  Bad label or misplaced continuation line
215   Syntax error.  Undefined or erroneous entry label
216   Syntax error.  Missing END line
217   Syntax error.  Duplicate label
218   Syntax error.  Duplicated goto field
219   Syntax error.  Empty goto field
220   Syntax error.  Missing operator
221   Syntax error.  Missing operand
222   Syntax error.  Invalid use of left bracket
223   Syntax error.  Invalid use of comma
224   Syntax error.  Unbalanced right parenthesis
225   Syntax error.  Unbalanced right bracket
226   Syntax error.  Missing right paren
227   Syntax error.  Right paren missing from goto
228   Syntax error.  Right bracket missing from goto
229   Syntax error.  Missing right array bracket
230   Syntax error.  Illegal character
231   Syntax error.  Invalid numeric item
232   Syntax error.  Unmatched string quote
233   Syntax error.  Invalid use of operator
234   Syntax error.  Goto field incorrect
235   Subscripted operand is not table or array
236   Array referenced with wrong number of subscripts
237   Table referenced with more than one subscript
238   Array subscript is not integer
239   Indirection operand is not name
240   Pattern match right operand is not pattern
241   Pattern match left operand is not string
242   Function return from level zero
243   Function result in NRETURN is not name
244   Statement count exceeds value of STLIMIT keyword
245   Translation/execution time expired
246   Stack overflow
247   Invalid control card
248   Attempted redefinition of system function
249   Expression evaluated by name returned value
250   Insufficient memory to complete dump
251   Keyword operand is not name of defined keyword
252   Error on printing to interactive channel
253   Print limit exceeded on standard output channel
254   Erroneous argument to HOST
255   Error during execution of HOST
256   SORT/RSORT 1st arg not suitable ARRAY or TABLE
257   Erroneous 2nd arg in SORT/RSORT of vector
258   SORT/RSORT 2nd arg out of range or non-integer
259   FENCE function argument is not pattern
261   Addition caused real overflow
262   Division caused real overflow
263   Multiplication caused real overflow
264   Subtraction caused real overflow
265   External function argument is not real
266   Exponentiation caused real overflow
267   Exponentiation right operand is real not integer
268   Inconsistent value assigned to profile keyword
!**
{Set Subtitle,Programming Notes}
{p}
{Hl 1,Programming Notes}
{Ls 1}The internal organization of SPITBOL is qite different from that
of SNOBOL4.
 Consequently the relative speed of various operations differs.  This
section attempts
to give some idea of how to obtain high efficiency in SPITBOL programs.
{Hl 2,<Space Considerations>}
{index  ANY}
{index  NOTANY}
{index  BREAK}
{index  BREAKX}
{index  SPAN}
{Ls 1}The ANY, NOTANY, BREAK, BREAKX, SPAN functions
use translate and test tables for arguments longer than one character.
 A table allocated for this purpose will be M words long by N bits
wide, where
M is 64, 128 or 256 (machine dependent) and N is the word length in
bits of the host computer.
 For each function call a bit column is used so that a single table
suffices for N calls.
 With a constant argument, the table entry is precomputed at compile
time thus
avoiding erosion of space by repeated calls in a run time loop.
 Single character arguments incur no
{index  space overhead}
space overhead
.
{index  integers}
{index  reals}
{Ls 1}Integers and reals have an overhead of one word above that needed
by the usual hardware representation.
{index  arrays}
{Ls 1}Multidimensional arrays have a space overhead of
8~+~2D words where D is the number of dimensions.
{index  vectors}
One dimensional arrays with a low bound of 1 (vectors ) are treated
specially
and have an overhead of only three words.
{index  tables}
{Ls 1}The space needed for non-null elements of tables
is 4 words in addition to space for the element itself.  Each table
{index  hash}
hash header is one word.
 Thus the number of headers can be made reasonably large without using
much additional space.
{index  Program defined datatypes}
Program defined datatypes
require 3~+~F words, where F is the
number of fields.  They are thus quite compact and can be used freely.
 Each variable block requires 8 words plus space for the variable
name, the characters of which
are packed several to a word, usually using 6, 7 or 8 bits for each
character.
 This space is constant irrespective of whether the name has a single
use
{index  label}
{index  function}
{index  variable}
or is used multiply as a label, function, variable etc.
 This space is never reclaimed once it has been  allocated.  It is thus
inefficient to
{index  $}
use variables to build tables with the unary $ operator.
{index  TABLE}
Instead use the TABLE datatype.
 The interpretive code produced by the compiler is held in code blocks
{index  code blocks}
and is subject to garbage collection when no longer accessible.
{index  garbage collection}
Advantage can be taken of this by writing label-free initialising
code at the head of
a program.  Even if labels are present it is possible to make initialising
code
{index  CODE}
collectable by the artifice of calling CODE with a string argument
in which the labels are redeclared.
{p}
{Ls 1}Considerable amounts of store are used in repeatedly building  patterns.
 They should either be pre-assigned to variables outside program loops
or alternatively if written in-line in loops, should be constant so
that
they may be precomputed at compile time in order to avoid this overhead.
{index  &TRIM}
{Ls 1}Setting &TRIM non-zero ensures that memory is not wasted in storing
trailing
blanks in strings.
{index  COLLECT}
{Ls 1}The COLLECT function can be used to obtain very detailed
information of memory utilization for various structures.
{Hl 2,<Speed Considerations>}
{index  speed considerations}
{Ls 1}To a greater extent than is the case with SNOBOL4, there is a loss
of
efficiency in encoding complex structures as strings.
{index  arrays}
{index  tables}
Use arrays, tables and
{index  program defined datatypes}
program defined datatypes
where possible since all of these are highly efficient in SPITBOL.
 The fast
{index  associative lookup}
associative lookup
{index  TABLE}
{index  hashing}
(hashing ) feature of the TABLE makes it a particularly recommended
feature to be exploited in a wide range of applications.
 Programmers frequently do not appreciate that execution speeds may
be reduced by
an order of magnitude if poorly designed patterns  fruitlessly scan
data in
{index  unanchored mode}
unanchored mode. With the pattern matching primitives of SPITBOL,
it is rare that unanchored matching is necessary and since
{index  anchored matching}
anchored matching
is much less expensive it is worth
{index  &ANCHOR}
acquiring the habit of initially setting &ANCHOR non-zero.
 If unanchored matching is needed
for some purpose, take care that it is not unduly wasteful with data for
which match failure is common.
{index  $}
{Ls 1}The binary $ pattern assignment is rather faster than the binary
{index  .}
. pattern assignment
and may be used freely.
 SPITBOL precomputes constant expressions before execution.  No efficiency
is lost by
writing pre-evaluable patterns in-line rather than predefining them.
{index  pre-evaluation}
{index  *}
Use of the unary * to defer computation is useful in some cases.
 For example, consider the in-line matches --
{brk}
~~~~X ANY('PQR') BAL PAT 'X' RPOS(0)
{brk}
~~~~X ANY('PQR') BAL *PAT 'X' RPOS(0)
{brk}
The second form is more efficient, since the compiler can precompute
the entire pattern
where PAT occurs as a deferred expression.
{index  deferred expression}
{p}
{index  ANY}
{index  NOTANY}
{index  BREAK}
{index  BREAKX}
{index  SPAN}
{Ls 1}The ANY, NOTANY, BREAK, BREAKX, SPAN,
{index  RSORT}
{index  SORT}
RSORT, SORT functions
are fast and highly recommended.
{index  ARB}
{index  ARBNO}
{Ls 1}ARB and ARBNO are slow and can very often be avoided by using
other constructions.
 Time for datatype conversions may be significant.
 Where efficiency is important, avoid repeated unnecessary conversions.
{index  datatype conversions}
{Ls 1}The SETEXIT error intercepts are fast and may be used for program
{index  debugging}
control as well as for debugging.
{index  Tracing}
{Ls 1}Tracing or
{index  <I/O association>}
I/O associating
a variable  substantially slows down references to it
but there is no residual access penalty if the trace or I/O associations
{index  STOPTR}
{index  DETACH}
are removed by STOPTR or DETACH.
{index  $}
{Ls 1}The unary $ (indirect) operator applied to a string argument
in SPITBOL corresponds to a hash search of existing variables.
{index  NAME}
The process of applying $ to a NAME (including the name of a natural
variable), is much faster, which
is why  unary dot (name operator) returns a NAME instead of a string.
 It is thus better to use names rather than strings in applications
such as passing
variable names or labels indirectly as in
{brk}
~~~~F(.X)~~~~~~~~~~~~rather than
{brk}
~~~~F("X") .
{index  REPLACE}
{Ls 1}Use of the REPLACE function is optimised when, on repeated calls,
the second and
third arguments are found to be unchanged, since in this case
the previously constructed replace table is re-used.
{Hl 2,<Other Notes>}
{Ls 1}The pattern match
{brk}
{index  &ALPHABET}
~~~&ALPHABET LEN(N) LEN(1) $ CHAR
{brk}
is useful to put into "CHAR" the Nth character of the host machine
character set.
{Ls 1}
{index  interrogation}
{index  ?}
{Ls 1}The interrogation operator, unary ? , is useful to annihilate an
expression which
is evaluated for its side effects rather than for its value.  For example
{brk}
~~~S BREAK(*DELIM) $ K *?(TABLE<<K>> = TABLE<<K>> + 1)
{Set Subtitle,Specimen Programs}
{p}
{Hl 1,Specimen Programs}
{Ls 1}Specimen programs of several different types are listed.
 The first one is especially simple and uses no special facilities.
 The second and third are a little more ambitious and make use of program
defined datatypes and tables respectively.
 Program 4 serves no function apart from showing some
of the techniques for producing trace output and providing
user handling of errors.
 The job control commands needed to run these programs are implementation
dependent and hence are listed in {SEC_IMPL}.
{Ls 5}
{Hl 2,<Program 1>}
{Ls 1}This program reads data appended to
its end and scans each record to count the number of vowels it
contains.  A listing of all records constituting
the program and data is shown and this is followed by a copy of the
output
produced on compilation and execution.
 The -NOLIST card indicates that no listing of the program
is required.
 Note the use of the SPITBOL selection feature in
the statement labelled NOMORE and the plus used as a statement
continuation symbol in column 1 of the next card.  The data for
the run  follows the END
label of the program.
 The output includes  the version number of the SPITBOL compiler
which will be updated as new versions are introduced.
 Compile time statistics, output from the program execution
and statistics relating to the run are listed.
{p}
{nfj}
{Tset Lmg,3}{Tset Rmg,80}
-NOLIST
-TITLE  P R O G R A M   1
*
*    PROGRAM TO COUNT THE VOWELS IN LINES OF TEXT
*
          &ANCHOR  = &TRIM = 1
          VOWELS   = BREAK('AEIOU') LEN(1)
*
*    LOOP TO READ NEXT LINE OF INPUT
*
INP       INP      = COPY = INPUT                     :F(END)
          N        = 0
*
*    LOOP TO SEARCH FOR VOWELS
*
FINDVWLS  INP VOWELS =                                :F(NOMORE)
          N        = N + 1                            :(FINDVWLS)
*
*    ALL VOWELS HAVE BEEN FOUND
*
NOMORE    OUTPUT   = RPAD(N,2) (EQ(N,1) ' VOWEL ' , ' VOWELS')
+           ' FOUND IN "' COPY '"'                    :(INP)
END
QWERTY
1900 AND DECSYSTEM-10 SPITBOL
THE SLITHY TOVES DID GYRE AND GIMBLE IN THE WABE
12 * 2 = 24
{Ls 3}
 
STORE USED     1360
STORE LEFT     4477
COMP ERRORS    0
REGENERATIONS  0
COMP TIME-MSEC 160
{Ls 2}
1  VOWEL  FOUND IN "QWERTY"
5  VOWELS FOUND IN "1900 AND DECSYSTEM-10 SPITBOL"
13 VOWELS FOUND IN "THE SLITHY TOVES DID GYRE AND GIMBLE IN THE WABE"
0  VOWELS FOUND IN "12 * 2 = 24"
{Ls 2}
NORMAL END
IN STATEMENT   8
STMTS EXECUTED 58
RUN TIME-MSEC  100
MCSEC / STMT   1724
REGENERATIONS  0
{fj}
{restore lmg}{Restore rmg}
{p}
{Hl 2,<Program 2>}
{Ls 1}This is a somewhat more complex program for sorting a set
of records.
 There is no -NOLIST card present and so a listing of the program is
produced by the compiler with statement numbers placed on the left.
 The output includes the sorted list and then following the
execution statistics is a dump resulting from the assignment
to keyword &DUMP in statement 2.  This illustrates the excellent
diagnostic assistance available should a program not behave as
expected.  The structure of the trees is readily
discernible in the dump of the NODEs of which they are constituted.
{Ls 2}
{nfj}
{Tset Lmg,3}{Tset Rmg,80}
{Ls 1}P R O G R A M   2                                               PAGE 1
{Ls 1}
        *    PROGRAM TO SORT A SET OF RECORDS ON A KEY USING A TREE SORTING
        *    TECHNIQUE.
        *
        *    DATATYPE WITH THE NECESSARY 4 FIELDS
        *
1                 DATA('NODE(KEY,DAT,PRED,SUCC)')
2                 &DUMP    = 2; &ANCHOR = &TRIM = 1
        *
        *    ROUTINE TO ADD "DATA" TO A TREE SORTED BY "KEY".
        *    "ROOT" IS PASSED BY REFERENCE (IT IS A SPITBOL NAME)
        *    AND POINTS TO THE TREE TO BE USED.
        *
4                 DEFINE('ADNODE(KEY,DATA,ROOT)PTR')          :(ADNEND)
        *
        *    CREATE TREE INITIALLY IF NOT YET IN EXISTENCE
        *
5       ADNODE    $ROOT    = IDENT($ROOT) NODE(KEY,DATA)      :S(RETURN)
6                 PTR      = $ROOT
        *
        *    SEARCH TO FIND INSERTION POINT IN TREE
        *
7       SEARCH    LLE(KEY,KEY(PTR))                           :S(BEFORE)
        *
        *    HERE IF NODE FOLLOWS THAT IN TREE
        *
8       AFTER     PTR      = DIFFER(SUCC(PTR)) SUCC(PTR)      :S(SEARCH)
9                 SUCC(PTR) = NODE(KEY,DATA)                  :S(RETURN)
        *
        *    HERE IF KEY PRECEDES THAT IN TREE
        *
10      BEFORE    PTR      = DIFFER(PRED(PTR)) PRED(PTR)      :S(SEARCH)
11                PRED(PTR) = NODE(KEY,DATA)                  :(RETURN)
12      ADNEND
{restore lmg}{restore rmg}
{p}
{tset lmg,3}{tset rmg,80}
        *
        *    ROUTINE TO PRINT A SORTED BINARY TREE
        *
13                DEFINE('PRINTREE(TREE)')                    :(ENDPRT)
14      PRINTREE  DIFFER(PRED(TREE)) PRINTREE(PRED(TREE))
15                OUTPUT   = KEY(TREE) '  ' DAT(TREE)
16                DIFFER(SUCC(TREE)) PRINTREE(SUCC(TREE))     :(RETURN)
17      ENDPRT
        *
        *    RECORDS OF WHICH
        *    '1609   GALILEO :   TELESCOPE'
        *    IS TYPICAL ARE TO BE SORTED BY DATE AND BY INVENTOR.
        *    SPLIT OUT THE RECORDS AND ADD TO TWO SORTED TREES.
        *
18      SORT      INP      = INPUT                            :F(PRINT)
19                INP LEN(4) $ DATE SPAN(' ') (BREAK(':') ':') $ INVR
        .               SPAN(' ') REM $ INVN
20                ADNODE(DATE,RPAD(INVR,16) INVN,.DATREE)
21                ADNODE(RPAD(INVR,16),DATE '  ' INVN,.INVRTREE) :(SORT)
        *
        *    JOB DONE APART FROM PRINTING THE SORTED TREES
        *
22      PRINT     OUTPUT   = 'INVENTIONS SORTED BY DATE'; OUTPUT =
24                PRINTREE(DATREE) ; OUTPUT =
26                OUTPUT   = 'INVENTIONS SORTED BY INVENTOR'; OUTPUT =
28                PRINTREE(INVRTREE)
29      END
{Ls 2}
INVENTIONS SORTED BY DATE
{Ls 1}
1609  GALILEO :         TELESCOPE
1835  TALBOT W F :      PHOTOGRAPHY
1876  BELL A G :        TELEPHONE
1896  DIESEL R :        DIESEL ENGINE
1896  MARCONI G :       RADIO
1903  WRIGHT O & W :    POWERED FLIGHT
{Ls 1}
INVENTIONS SORTED BY INVENTOR
{Ls 1}
BELL A G :        1876  TELEPHONE
DIESEL R :        1896  DIESEL ENGINE
GALILEO :         1609  TELESCOPE
MARCONI G :       1896  RADIO
TALBOT W F :      1835  PHOTOGRAPHY
WRIGHT O & W :    1903  POWERED FLIGHT
{Ls 2}
NORMAL END
IN STATEMENT   29
STMTS EXECUTED 146
RUN TIME-MSEC  160
MCSEC / STMT   1095
REGENERATIONS  0
{restore lmg}{Restore Rmg}
{p}
DUMP OF NATURAL VARIABLES
{tset lmg,3}{tset rmg,80}
{Ls 1}
DATE = '1896'
DATREE = NODE `1
INP = '1896    DIESEL R :          DIESEL ENGINE'
INPUT = '1896    DIESEL R :          DIESEL ENGINE'
INVN = 'DIESEL ENGINE'
INVR = 'DIESEL R :'
INVRTREE = NODE `2
OUTPUT = 'WRIGHT O & W :    1903  POWERED FLIGHT'
REM = PATTERN
{Ls 2}
DUMP OF KEYWORD VALUES
{Ls 1}
&ANCHOR = 1
&CODE = 0
&DUMP = 2
&ERRLIMIT = 0
&ERRTEXT = ''
&ERRTYPE = 0
&FNCLEVEL = 0
&FTRACE = 0
&INPUT = 1
&LASTNO = 28
&MAXLNGTH = 3104
&OUTPUT = 1
&RTNTYPE = 'RETURN'
&STCOUNT = 146
&STLIMIT = 50000
&STNO = 29
&TRACE = 0
&TRIM = 1
{Ls 2}
NODE `1
KEY(DATREE) = '1876'
DAT(DATREE) = 'BELL A G :      TELEPHONE'
PRED(DATREE) = NODE `5
SUCC(DATREE) = NODE `3
{Ls 1}
NODE `2
KEY(INVRTREE) = 'BELL A G :      '
DAT(INVRTREE) = '1876  TELEPHONE'
SUCC(INVRTREE) = NODE `4
{Ls 1}
NODE `3
KEY(NODE `3) = '1896'
DAT(NODE `3) = 'MARCONI G :     RADIO'
PRED(NODE `3) = NODE `11
SUCC(NODE `3) = NODE `7
{restore lmg}{restore rmg}
{p}
{tset lmg,3}{tset rmg,80}
NODE `4
KEY(NODE `4) = 'MARCONI G :     '
DAT(NODE `4) = '1896  RADIO'
PRED(NODE `4) = NODE `6
SUCC(NODE `4) = NODE `8
{Ls 1}
NODE `5
KEY(NODE `5) = '1609'
DAT(NODE `5) = 'GALILEO :       TELESCOPE'
SUCC(NODE `5) = NODE `9
{Ls 1}
NODE `6
KEY(NODE `6) = 'GALILEO :       '
DAT(NODE `6) = '1609  TELESCOPE'
PRED(NODE `6) = NODE `12
{Ls 1}
NODE `7
KEY(NODE `7) = '1903'
DAT(NODE `7) = 'WRIGHT O & W :  POWERED FLIGHT'
{Ls 1}
NODE `8
KEY(NODE `8) = 'WRIGHT O & W :  '
DAT(NODE `8) = '1903  POWERED FLIGHT'
PRED(NODE `8) = NODE `10
{Ls 1}
NODE `9
KEY(NODE `9) = '1835'
DAT(NODE `9) = 'TALBOT W F :    PHOTOGRAPHY'
{Ls 1}
NODE `10
KEY(NODE `10) = 'TALBOT W F :    '
DAT(NODE `10) = '1835  PHOTOGRAPHY'
{Ls 1}
NODE `11
KEY(NODE `11) = '1896'
DAT(NODE `11) = 'DIESEL R :      DIESEL ENGINE'
{Ls 1}
NODE `12
KEY(NODE `12) = 'DIESEL R :      '
DAT(NODE `12) = '1896  DIESEL ENGINE'
{fj}
{restore lmg}{restore rmg}
{p}
{Hl 2,<Program 3>}
{Ls 1}This program reads a set of keywords and then processes
a file in order to count the number of occurrences of the
keywords in the text held in the file.
 Notice the simple method of making input and output
associations to the various input and output files
in statements 2, 3 and 4.  A table created in statement 7 is
initialised with the keywords at statement 8.  The pattern used
to break out words is written out of line since this ensures
that matching in the inner loop at label WORDLOOP executes at
maximum speed.  In a similar application where an in-line
pattern must be used (e.g. if the string value of PUNCTUATION
were subject to change during execution), then the statement
would best be written using deferred expressions as
{index  deferred expression}
{Ls 1}
~~WORDLOOP INP BREAK(*PUNCTUATION) . WORD SPAN(*PUNCTUATION) =
{Ls 1}
since, being constant, the pattern can be pre-evaluated at
{index  pre-evaluation}
compile time.  This saves repeatedly building the pattern in
the loop, leaving only the necessary processing of the current
string in PUNCTUATION as additional work to be done compared
with the version in the program.  The searching for and
counting of keywords in statement 11  is done using the
inherently efficient, system-provided hashing capability of the
TABLE datatype.
 To economise in table lookups, the table entry is assigned to
a temporary variable in statement 10 whilst a check is made to ensure
that it is non-null.
 The call of CONVERT used to access non-null
entries in the table does not sort the keys, so that a separate
sorting process would be necessary if sorted output were
required.  A listing of the filed output is given.
{p}
{Ul <Contents of file KEYWDS>}
{nfj}
{Ls 1}
BREEZE
DAY
MOON
OCEAN
SEA
SHIP
SUN
THE
TWAS
WATER
{Ls 1}
{Ul <Contents of file KEYTXT>}
{nfj}
{Ls 1}
THE FAIR BREEZE BLEW, THE WHITE FOAM FLEW,
THE FURROW FOLLOWED FREE:
WE WERE THE FIRST THAT EVER BURST
INTO THAT SILENT SEA.
{Ls 1}
DOWN DROPT THE BREEZE, THE SAILS DROPT DOWN,
'TWAS SAD AS SAD COULD BE;
AND WE DID SPEAK ONLY TO BREAK
THE SILENCE OF THE SEA!
{Ls 1}
DAY AFTER DAY, DAY AFTER DAY,
WE STUCK, NOR BREATH NOR MOTION;
AS IDLE AS A PAINTED SHIP
UPON A PAINTED OCEAN.
{Ls 1}
WATER, WATER, EVERY WHERE,
AND ALL THE BOARDS DID SHRINK;
WATER, WATER, EVERY WHERE,
NOR ANY DROP TO DRINK.
{Ls 1}
        SAMUEL TAYLOR COLERIDGE
{Ls 2}
{Ul <Contents of file KEYOUT at end of run>}
{Ls 1}
     KEYWORD    NUMBER OF OCCURRENCES
     -------    ---------------------
{Ls 1}
         SUN .  .  .  .  . 0
        MOON .  .  .  .  . 0
        SHIP .  .  .  .  . 1
        TWAS .  .  .  .  . 1
         DAY .  .  .  .  . 4
         SEA .  .  .  .  . 2
         THE .  .  .  .  . 9
      BREEZE .  .  .  .  . 2
       OCEAN .  .  .  .  . 1
       WATER .  .  .  .  . 4
{nfj}
{p}
{tset lmg,3}{tset rmg,80}
{Ls 1}P R O G R A M   3                                               PAGE 1
{Ls 1}
        -PRINT
        -IN80
        *    PROGRAM TO COUNT THE OCCURRENCES OF KEYWORDS IN A PIECE
        *    OF TEXT.  THE SEARCH FOR KEYWORDS IS EFFICIENTLY PERFORMED
        *    BY HASHING INTO A TABLE.
        *
1                 &ANCHOR = &TRIM = 1
2                 INPUT(.KEYS,1,'KEYWDS')                     :F(NOFILE)
3                 INPUT(.INPUT,2,'KEYTXT')                    :F(NOFILE)
4                 OUTPUT(.OUT,3,)
5                 PUNCTUATION = " .,;:'!"
6                 WORDPAT  = BREAK(PUNCTUATION) $ WORD SPAN(PUNCTUATION)
7                 KEYTABLE = TABLE(31)
        *
        *    LOOP IN WHICH KEYWORDS ARE READ IN AND HASHED INTO KEYTABLE
        *
8       KEYLOOP   KEYTABLE<<KEYS>> = 0                          :S(KEYLOOP)
        *
        *    A SPACE IS ADDED TO LINES OF TEXT TO ENSURE MATCH SUCCESS
        *
9       READLOOP  INP      = INPUT ' '                        :F(CONVERT)
        *
        *    INDIVIDUAL WORDS ARE EXTRACTED BY PATTERN MATCHING
        *
10      WORDLOOP  INP WORDPAT =
11                KEYTABLE<<WORD>> = DIFFER(ENTRY = KEYTABLE<<WORD>>) ENTRY + 1
12                DIFFER(INP)                       :S(WORDLOOP)F(READLOOP)
        *
        *    FAILURE POINT
        *
13      NOFILE    OUTPUT  = 'MISSING INPUT FILE'              :(END)
14      CONVFL    OUTPUT  = 'NO KEYWORDS FOUND'               :(END)
        *
        *    EXTRACT THE ENTRIES FROM THE TABLE INTO AN ARRAY
        *
15      CONVERT   A        = CONVERT(KEYTABLE,'ARRAY')        :F(CONVFL)
16                OUT      = '     KEYWORD    NUMBER OF OCCURRENCES'
17                OUT      = '     -------    ---------------------'
18                OUT      =
        *
        *    PRINT THE ENTRIES
        *
19                 I        = 1
20      PRINT    OUT   = LPAD(A[I,1],13) DUPL(' . ',5) A[I,2] :F(END)
21                I        = I + 1                            :(PRINT)
22      END
{restore lmg}{restore rmg}
{p}
{fj}
{Hl 2,<Program 4>}
{Ls 1}This program is included merely to show how errors may be
handled, use of the -NOFAIL option and the nature of trace
output.
{Ls 1}
{Ls 1}Statement 1 sets the keyword &TRACE to permit printing of up to
40
lines of trace output and the next two statements indicate the
items to be traced.  In statement 4 a limit of 10 is set on
the number of errors to be intercepted and processed by the
program itself, whilst the destination label in the event of
an error occurring is identified in the next statement.  The
next line contains a syntax error which results in the printing
of an error message.  Following statement 14 is a -NOFAIL
control card, the effect of which is to cause generation of
special code for subsequent statements containing no conditional
goto so that if such a statement does, contrary to the implied
expectation, actually fail, an error message is produced.  This
can be of great diagnostic value.
 The output from the run illustrates various points.  Execution
of the program was not inhibited by the compilation error.  The
number of any statement where a trace association is active is
embedded in asterisks and printed on the left so that starting
with statement 4, we can trace the flow of control through the
program on account of the trace intercept set on the keyword
&STCOUNT.  It will be seen that the compilation error in statement
6 results in an execution error and that this in turn causes
a transfer of control to statement 18 where user processing of
the error message is provided.  At statement 7 the ACCESS trace
of the INPUT variable produces lines of trace output indicating
the value which it currently holds.  The jump to statement 10
followed by the STOPTR statement results in turning off the
&STCOUNT trace.   An attempt to jump to the non-existent label
L100 produces a failure, followed immediately by another when an
attempt is made to form the sum 3 + 'L200'.  The loop at statements
16 and 17 reads 10 elements into the array A and then as
the array is accessed outside its bounds, a statement error occurs
which is converted to a run time failure because the statement was
compiled in -NOFAIL mode.  Had this not been the case the loop
could have run for many seconds before the integer value in I
finally overflowed.  A correct program of course would have had
a conditional goto such as
{Ls 1}
{nfj}
                          :F(ARRAY.FULL.OR.DATA.USED.UP)
{fj}
{Ls 1}
in statement 16.  The failure terminates execution because at
statement 13 the limit on the number of errors to be tolerated
was reset to zero.
{nfj}
{p}
{tset lmg,3}{tset rmg,80}
  P R O G R A M   4                                              PAGE 1
{Ls 1}
        -PRINT
        *
        *    PROGRAM TO DEMONSTRATE TRACING AND ERROR HANDLING
        *
1                 &TRACE   = &ANCHOR = &TRIM = 40
2                 TRACE(.INPUT,'ACCESS')
3                 TRACE(.STCOUNT,'K')
4                 &ERRLIMIT = 10
5                 SETEXIT(.ERROR)
6                 STATEMENT , WHICH SHOULD FAIL TO COMPILE
                            ^
ERROR 223 -- SYNTAX ERROR.  INVALID USE OF COMMA
{Ls 1}
7       LOOP                                             :S($INPUT)F(FAIL)
8       L1        OUTPUT   = '"L1"'                           :(LOOP)
9       L2        OUTPUT   = '"L2"'                           :(LOOP)
10      STOPTR    OUTPUT   = 'STOPTR'
11                STOPTR(.STCOUNT,'K')                        :(LOOP)
12      FAIL      X        = 3 + INPUT
13                &ERRLIMIT =
14                A        = ARRAY(10);     I = 1
        -NOFAIL
16      READ      A<<I>>     = INPUT
17                I        = I + 1                            :(READ)
        *
        *    ERROR INTERCEPT ROUTINE
        *
18      ERROR     OUTPUT   = 'ERROR NO.  '  &ERRTYPE '  IN STATEMENT'
        .            &LASTNO
19                OUTPUT   = 'REASON FOR FAILURE :- '  &ERRTEXT
20                OUTPUT   =
21                SETEXIT(.ERROR)                             :(CONTINUE)
22      END
{restore lmg}{restore rmg}
{Ls 2}
{Tset Lmg,3}{Tset Rmg,80}
STORE USED     1279
STORE LEFT     4558
COMP ERRORS    1
REGENERATIONS  0
COMP TIME-MSEC 400
{p}
****4*******  &STCOUNT = 4
****5*******  &STCOUNT = 5
****6*******  &STCOUNT = 6
****18******  &STCOUNT = 7
ERROR NO.  7  IN STATEMENT  6
****19******  &STCOUNT = 8
REASON FOR FAILURE :- COMPILATION ERROR ENCOUNTERED DURING EXECUTION
****20******  &STCOUNT = 9
{Ls 1}
****21******  &STCOUNT = 10
{Ls 1}
****7*******  &STCOUNT = 11
****7*******  INPUT = 'L2'
****9*******  &STCOUNT = 12
"L2"
****7*******  &STCOUNT = 13
****7*******  INPUT = 'STOPTR'
****10******  &STCOUNT = 14
STOPTR
****11******  &STCOUNT = 15
****7*******  INPUT = 'L1'
"L1"
****7*******  INPUT = 'L100'
 
 
ERROR NO.  38  IN STATEMENT  7
REASON FOR FAILURE :- GOTO UNDEFINED LABEL
{Ls 1}
****12******  INPUT = 'L200'
ERROR NO.  2  IN STATEMENT  12
REASON FOR FAILURE :- ADDITION RIGHT OPERAND IS NOT NUMERIC
{Ls 1}
****16******  INPUT = '1.111111'
****16******  INPUT = '2.2'
****16******  INPUT = '3.3'
****16******  INPUT = '4.4'
****16******  INPUT = '5.5'
****16******  INPUT = '6.6'
****16******  INPUT = '7.7'
****16******  INPUT = '8.8'
****16******  INPUT = '9.9'
****16******  INPUT = '10.10'
{Ls 2}
ERROR 035 -- UNEXPECTED FAILURE IN -NOFAIL MODE
{Ls 1}
IN STATEMENT   16
STMTS EXECUTED 51
RUN TIME-MSEC  280
MCSEC / STMT   5490
REGENERATIONS  0
{restore lmg}{restore rmg}
{Set Subtitle,Implementation Information}
{p}
{fj}
{Hl 1,Implementation Information}{Ls 1}SPITBOL is implemented
on a wide variety of computers.
 Condsiderable efforts have been made to achieve compatibility
and portability between versions but inevitably there are
features, values or limitations particular to each implementation.
 This section gives details for the VAX/VMS implementation.
{Hl 2,Variances}
{Ls 1}
This section lists significant features that are omitted, added
or altered in VAX/VMS SPITBOL.
 Note that version ABAA of SPITBOL or higher requires at least
VMS version 2.
{index exit}
{Hl 3,EXIT}The SPITBOL EXIT(...) function available for all arguments
except positive integers (image save).
 Its use is described below.
{index &STLIMIT}
{Hl 3,&STLIMIT}The default value for &STLIMIT is one billion.
{index FENCE}
{Hl 3,FENCE(PATTERN)}VAX/VMS SPITBOL contains an additional intrinsic
pattern matching function called FENCE.
 This function is described in {SEC_FUNC} in detail.
{index &CODE}
{HL 3,&CODE}The default value for &CODE in VAX/VMS SPITBOL is one.
 This avoids a "successful completion" message from VMS which
occurs when &CODE is zero on exit.
{index &ERRTEXT}{Index /LOAD}{Index EXIT}
{Hl 3,&ERRTEXT}The initial value of &ERRTEXT contains the startup
command line text, excluding the command name and any trailing comment.
 When reloading from a saved EXIT(n) file, if the value of n was -2 or
-1, the new command line will replace the value of &ERRTEXT.
{index stack overflow}
{Hl 3,Stack Overflow}Because of the mechanism used in VMS for
signalling stack overflows,
 stack overflow is a fatal condition, and causes SPITBOL to
exit immediately.
{Ls 1}In general, as stack space is allocated on demand, the
only realistic method by which a program can overflow the stack
is with an infinitely recursive pattern or function call chain.
 If trapping of unbounded recursion is required, tracing &FNCLEVEL
is recommended as a last resort.
{P}
{Hl 2,Machine Dependent Features}
{index MXLEN}
{Hl 3,MXLEN}The mimimum value of MXLEN is approximately 1,000,000.
 This is controlled by the "BASE=..." option in the SPITBOL.OPT
 linker options file.
 It is not recommended that this value be reduced, as it will limit
the size of objects, and reduce the virtual space available for
mapping in external (LOAD) images.
{index &TRIM}
{Hl 3,&TRIM}Records are never implicitly padded with blanks on output.
 For input, any trailing blanks received depend on the file and
the value of &TRIM.
{index TERMINAL}
{Hl 3,TERMINAL}TERMINAL is available and is associated with SYS$INPUT
and SYS$OUTPUT.
 The first assignment or access to TERMINAL opens this channel.
{index Real Arithmetic}
{Hl 3,Real Arithmetic}Available in single precision with a printing
accuracy of 6 digits.
{index Character Set}
{Hl 3,Extended Character Set}All 256 8-bit ASCII codes are in &ALPHABET.
 The tab character may be used lexically in place of the space.
{index REWIND}
{Hl 3,REWIND}Available.
{index HOST}
{Hl 3,HOST}The only defined entry to HOST is when all arguments are null,
in which case, HOST() returns the identifying string of the form:
{Ls 1}
{Center VAX:VMS:sitename:username:accountname}{Ls 1}
"Sitename" is derived from a translation of the logical name "SYS$SITENAME"
to obtain a site name both for HOST and for the banner.
 The translated string must be 28 or fewer characters.
{index Listing Options}
{Hl 3,Terminal Listing Options}If the standard output channel
is a terminal device, an abbreviated listing format is used by default.
See below for details.
{index &CODE}
{Hl 3,&CODE}The value of &CODE is used on exit as the return code to VMS.
 There are two exceptions:
{lin 2}{Ls 1}{Outdent 2}-~&CODE = 998 will print a message on termination
to the effect that the standard output channel is not available.
{Ls 1}{Outdent 2}-~&CODE = 999 will print a message on termination
to the effect that execution was suppressed (either via startup switch
or control card).
{brk}{restore Lmg}
{index &STLIMIT}
{Hl 3,&STLIMIT}Maximum value is 2,147,403,647.
 Note that statement counting and checking can be disabled by setting
the value of &STLIMIT to -1.
 The initial value of &STLIMIT is 1,000,000,000 .
{index CPU Time}{index time}
{Hl 3,Time}All execution times in the VAX/VMS Macro SPITBOL system are
in CPU time increments of 10 (milliseconds).
 This covers both the times shown in the statistics, and the time
retrieved via the system TIME function.
 Wall time is available through DATE.
{index Integers}
{Hl 3,Range of Integers}Integers are represented in a single VAX
32-bit longword.
 The range for integers is: [~-2,147,483,648~,~+2,147,483,647~].
{index DATE}
{Hl 3,Form of DATE String}DATE() returns an 22 character string
of the form:
{Ls 1}{Center <MM-DD-YYYY HH:MM:SS.CC>}
{Ls 1}These wall-time components designate respectively:
{Ul M}onth, {Ul D}ay, {Ul Y}ear, {Ul H}our, {Ul M}inute, {Ul S}econd and
Hundredths ({Ul C}enti-) seconds.
{P}{index I/O}
{Hl 3,INPUT/OUTPUT}All VAX/VMS Macro SPITBOL I/O is processed through
RMS (Record Management Services).
 The general form of the INPUT/OUTPUT call in Macro SPITBOL is:
{Ls 1}{Center <XXXPUT(Var,Filearg1,Filearg2)>}{Ls 1}
"Filearg1" may be any Macro SPITBOL object that can be converted
to a name (e.g. number or string).
 It has no significance to the I/O system as such,
however it represents a unique binding to this I/O channel,
{index INPUT}{index OUTPUT}{index REWIND}{index ENDFILE}{index EJECT}
and it can thus be used in subsequent calls to INPUT, OUTPUT,
REWIND, ENDFILE and EJECT.
 If Filearg1 is null, an INPUT call refers to the standard input
channel association, and an OUTPUT call similarly refers to the
standard output channel.
 It is permitted to reassign these channels via INPUT/OUTPUT, but
note that SPITBOL does not allow null arguments to REWIND or ENDFILE.
{Ls 1}"Filearg2" differs slightly from the form shown in {SEC_FUNC}
for the INPUT and OUTPUT functions, and has the form:
{Ls 1}{Center <"Filespec/Switch/Switch/...">}{Ls 1}
where all components, including "Filespec" are optional.
 If Filespec is given, the current channel (if any) is closed out
and a new association to the given Filespec is created.
 "Filespec" is given in standard VMS/RMS form for a device/file
specification.
 If the Filespec is omitted then any switches specified are processed
for the association, but the present association to the channel remains
unchanged.
 If the entire Filearg2 is null, then this reduces to simply I/O associating
"Var" to the channel designated by Filearg1.
{Ls 1}Any given "Filearg1" channel can be associated for both INPUT
and OUTPUT, however any such dual associations must be formed prior
to opening the channel in order to avoid an RMS error when the
channel is used in a manner for which is was not originally opened.
 A channel is opened for I/O activity indirectly due to the first
I/O reference to it.
 The call to INPUT or OUTPUT by itself causes no I/O activity, but
only establishes the nature of the variable-to-channel and channel-to-file
associations that can be used later.
 The first I/O reference to a channel or channel-associated variable
causes either an OPEN or CREATE to be issued.
 The OPEN (an existing file)
is issued unless an OUTPUT association to the channel has
been made, in which case a CREATE (new file) will be issued.
 The occurrence of some switches can modify this default action.
{Ls 1}Note that all I/O sequential in nature;
the default mode of file creation is variable-length, carriage return
delimited record attributes.
{index RMS}
 It is possible to process existing indexed files transparently
through RMS, however, sequential access is the only processing mode
available, regardless of the file's characteristics.
{index I/O Switches}
{p}
{HL 4,FILEARG2 SWITCHES}The following
switches are available for specification on Filearg2.
 They must be specified in upper-case.
 In many cases, it is possible to precede the switch name by the prefix
"NO" which indicates that the condition indicated by the switch
is to be inverted for this channel.
 For switches which apply only to terminal I/O, their presence is
ignored when dealing with other devices or files.
{Setq swd,{index /{1}}{outdent 7}{Rpad /{Caps @1},7}}
{Ls 1}
~~~~{Ul SWITCH}~~~~~~~~~~~{OS D E S C R I P T I O N,_____________________}
{Ls 1}
{Lin 12}
{index Terminal I/O}
{swd CCO}Cancel terminal control O on subsequent output operations.
{Swd CIF}If the named file already exists, it is used.
 Otherwise, a new file is created.
 Note that if an existing sequential variable-length
file is being processed, /EOF
must also be specified since RMS cannot rewrite records in such files.
 This restriction does not apply to indexed files.
{swd CR}Set CR/LF file attributes for CREATE operations.
 Note that an output association to "TT:/-CR" will thus suppress the usual
carriage return and line feed after each output assignment to the terminal.
{swd DLT}Delete the file when it is closed.
{swd EOF}Position to end-of-file on open.
 If an OUTPUT association has been made, the presence
of /EOF will cause an OPEN to be issued rather than a CREATE.
{swd FTN}Set FORTRAN-type carriage control attributes for CREATE.
 This switch is mutually exclusive with the "CR" switch.
{swd MXV}Maximize the version number of the file on a CREATE between
any specified version and one higher than the highest existing verion.
{Swd PTA}Purge the terminal type-ahead buffer for subsequent terminal
input on this channel.
{Swd RNE}For a terminal input-associated channel, subsequent input
is not to be echoed.
{swd RNF}For terminal-associated input, control-U, control-R and
DELETE characters are passed in the input string and are not taken as
control characters.
{swd SCF}Submit this file to the system standard batch stream when it
is closed.
{swd SPL}Submit this file to the system standard spool queue when it
is closed.
{swd SUP}Supercede any existing file on CREATE.
{swd TEF}Truncate the file to actual EOF when it is closed.
{brk}{restore lmg}{p}
{HL 4,I/O EXAMPLES}Here are a few examples of INPUT/OUTPUT calls.
 The colons (":") represent code sequences which are not shown.
{Ls 1}{Lin 3}{Outdent 3}1.~Attach the user's
terminal for input without
echoing the first line read in.
{Ls 1}{Nfj}
     INPUT(.TTNE,1,'TT:/RNE')
              :
     FIRST_LINE = TTNE
     INPUT(.TTNE,1,'/NORNE')
              :
{Ls 2}{Fj}{Outdent 3}2.~Write to a new file OUT.DAT and spool it
when SPITBOL terminates.
{Ls 1}{Nfj}
     OUTPUT(.OUTFILE,1,'OUT.DAT/SPL')
{Ls 2}{Fj}{Outdent 3}3.~Write to an intermediate file,
then rewind it, read through it, and delete it.
{Ls 1}{Nfj}
     INPUT(.INTER,1,'SCRATCH.DAT/DLT')
     OUTPUT(.INTER,1)
             :
WRITELOOP
     INTER = X
             :
     REWIND(1)
READLOOP
     X = INTER   :F(EXIT)
             :
EXIT
     ENDFILE(1)
END
{Ls 2}{Fj}{Outdent 3}4.~Append the record "***END***" to an
existing file:
{Ls 1}{Nfj}
     OUTPUT(.OLDFILE,1,'OLDFILE.DAT/EOF/CIF')
     OLDFILE = '***END***'
END
{Brk}{RESTORE LMG}{fj}
{P}{index EXIT}
{Hl 3,EXIT Function Usage}-
{Li}The EXIT function has been implemented in all forms except positive
integer arguments (that is to say, there is no total image save).
 Each of the forms is described below.
{Hl 4,EXIT(0) Usage}-
 EXIT(0) will pause the program with a message;
 a DCL "CONTINUE" command will continue execution.
 The message can be suppressed with the /NOWARN command line option.
{Hl 4,EXIT(String) Usage}EXIT(string) will cause
SPITBOL to exit and "string" will be given
to the command interpreter as the
next command.
 Note that this subsumes the normal SPITBOL semantics of EXIT(string)
for chain execution if the string is of the form "RUN image".
 It is also possible to initiate a command file (including one written
by the program itself) if the string is of the form: "@command-file".
{HL 4,EXIT(-n) Usage}EXIT(-n) is implemented,
and will save the impure segments of the
interpreter in a specially formatted block mode file.
 The name for this file is the same as the standard input file, with an
{index .SEX}
extension ".SEX" ({Dbl S}PITBOL {Dbl EX}it!) under the default directory.
 If such a file already exists, it will be reused
(with an extension of space if required),
otherwise a new file is allocated.
{index /LOAD}
 The startup switch "/LOAD[=filename]" can be used to load a
previously saved .SEX file.
 If the "=filename" is not specified on the load, the default LOAD name
is the same as that described above.
 Specification of /LOAD does not
obviate the need to specify a standard input file,
although it need not have the same name as the save file,
{index NL:}
and trivially could be "NL:" if no use is to be made of the standard input
channel.
{Ls 1}Certain remarks are in order regarding this form of EXIT.
 When a previously saved .SEX file is loaded, SPITBOL performs a number
of fairly extensive checks to verify that the impure segment is
compatible with the version of SPITBOL being used.
 If it is not, the file will not be loaded and one of a number of
fatal errors will be issued.
 Even if the SPITBOL version is compatible, it is possible
that stack utilization changes in new VMS releases could render a previously
operable exit module unloadable.
 Again, a fatal error would be issued.
 The general conclusion should be that the file created by EXIT is not
analogous to a "permanent" object or executable binary.
 The original source and data
must be retained in the event that a retranslation is indicated.
{index LOAD}
{Ls 1}One other point should be noted as regards EXIT(-n).
 Neither the status of open files,
nor the contents of LOAD(...) functions is preserved across an EXIT(-n);
 this includes the
standard input and output files,
which are instead associated anew when the exit module is reloaded
using the filenames given on the /LOAD startup line.
{Index INPUT}{Index OUTPUT}{Index LOAD}
 In general, INPUT(...), OUTPUT(...) and LOAD(...) calls must be made
after the call to EXIT(-n).
{Index /MINT}{Index /MINC}
 In addition, the load-time values (default or explicit) of /MINC and
/MINT override whatever values were in effect when the exit module
was saved (SPITBOL will, however, always attempt to obtain
enough virtual space to
hold the impure data of the exit module,
regardless of the setting of /MINT.)
 If the EXIT(-1) or EXIT(-2) forms are used, then the load-time values
of the other startup command line switches override the values at
the time of the EXIT.
{index LOAD}
{Hl 3,LOAD Function Usage}The LOAD function is implemented
with the general philosophy of permitting a true dynamic load
of externally linked images without any necessity for resorting to
{Index MACRO-32}MACRO-32 or similar machine-level coding.
 The first argument to LOAD is as described in {SEC_FUNC}.
 The second argument string is the name of the image to be loaded.
 The usual defaults (those of the process) apply to this name;
{Index .EXE}
the default extension is ".EXE".
 This string should never be null, that form is reserved for
a future implementation of a static LOAD.
{Ls 1}The general process for creating a LOADable image can be
summarized as follows:
{Ls 1}{Lin 5}{Outdent 3}1.~Prepare and debug the external
subroutine(s) you want to link into a loadable function.
 The code should be as thoroughly checked out as possible.
{index Debugging}
 Debugging under control of SPITBOL is difficult, and in
extreme cases, bugs can corrupt the interpreter's store,
making them all but impossible to locate.
{Ls 1}Any language(s) can be used to program the subprograms,
however users of high-level languages usually need to follow
some special guidelines (see below).
{Ls 1}{Outdent 3}2.~Link an image consisting of the modules
required.
 The image must be linked at a suitable base address
if it contains positionally dependent content (see below).
 The link should generally incorporate a search of SPITBOL's
symbol table to avoid duplication of the
run-time library in the image's virtual space.
 The image must have a defined transfer address in user space.
{Ls 1}{Outdent 3}3.~Run the SPITBOL program and issue the LOAD call.
 The function can now be used as an ordinary SPITBOL function.
{Ls 1}{RESTORE LMG}Details on each of these steps follow.
{Hl 4,High-Level Languages and LOAD}Images invoked by
LOAD are not entered via the image activator.
 Instead, SPITBOL gets to them via an ordinary CALL-type instruction
to the entry point of the image.
 Note that most "high-level languages" do not support the declaration of
a parameterized subprogram as an image entry point.
{Ls 1}To permit the use of such languages for LOAD functions,
a module to solve the problem just described is provided with
{index SPITHLS}{Index SYS$LIBRARY}
the SPITBOL delivery in SYS$LIBRARY:SPITHLS.OBJ.
 This module defines an entry point, and then jumps one word past
the global label SPIT$LOAD_ENTRY.
 (The one word is to bypass the procedure's register save mask.)
 This means that the entry subprogram of any LOADable function
{index SPIT$LOAD_ENTRY}
which uses SPITHLS.OBJ must be named SPIT$LOAD_ENTRY.
{Hl 4,Calling Conventions for LOAD}Insofar as practicable,
arguments to LOAD functions are transmitted by value on the
stack.
{index string descriptor}
 The one exception to this is string data.
 While the string descriptor is passed by value, the actual
string resides in SPITBOL's store (it is not copied for efficiency).
 As it is a cardinal rule that an active element of SPITBOL's
store never be altered, except for a technique described below,
it is {dbl vital} that the LOADed function
never attempt to modify the contents of any argument string.
 Failure to heed this caveat can lead to subsequent, arbitrary,
potentially bizarre behavior of the SPITBOL program or the interpreter.
 Note that some system strings are in write-protected pages (e.g. the null
string).
 An attempt to modify these strings will cause an access violation.
{Ls 1}Some programs require one or more "string buffers" of dynamic
length to work in, or in which to return their result.
 This can be done (carefully) by providing, in the call to the
external function, a string block which is otherwise unreferred to
by the program.
 For example, if you have an external function "SQUEEZE" which
takes a string and returns another string whose length is, at most, the same as
the length of the input string, you can load SQUEEZE with a prototype such as:
{Ls 1}{Center <"LOAD('SQUEEZE(STRING,STRING)STRING','SQUEEZE')">}{Ls 1}
and call it with a statement such as:
{Ls 1}{Center <"SQUEEZE(STR,COPY(STR))">}{Ls 1}
The second string is a buffer for the external function to
use, and which it may, if it wishes, return as its value.
 Use of the COPY (or other string generating function such as DUPL) is
absolutely necessary to insure that there are no other references
to the string which could inadvertently be disturbed.
 It goes without further comment that in no case should an attempt
ever be made to store characters outside the defined length of the string
block.
{Ls 1}It may, for some applications, be helpful to be aware that
arbitrary binary data can be stored as strings.
{Hl 4,Return Conventions for LOAD}When an external function is
ready to return, it may signal success or failure, and if it
succeeds, it must return an appropriate result of the type
described by the LOAD prototype for the function.
{Ls 1}Success or failure is indicated on return by the low order
bit of R0, according
to the normal VAX/VMS convention (the remainder of the register is ignored).
{Ls 1}If the low bit of R0 is set on return, this indicates
success, and R1 points to an integer value, real value, or
string descriptor as appropriate for the function.
 This is the value that will be returned to SPITBOL as the
result of the call.
{Ls 1}Many high-level languages do not have the capability of
{index SPIT$SUCCESS_RETURN}{index SPIT$FAIL_RETURN}
{Index SYS$LIBRARY}{Index SPITHLS}
returning values in this manner, so SYS$LIBRARY:SPITHLS.OBJ
contains two additional entry points, SPIT$SUCCESS_RETURN(obj)
and SPIT$FAIL_RETURN().
 These are co-routine entry points that can be called using
the VAX/VMS standard calling conventions, and will make adjustments
to the stack, R0 and R1 and return to SPITBOL.
 "Obj" is the address of the returned value when success is to
be indicated.
 Both of these entry points {dbl must} be called from the
same level as when the function was originally entered,
that is, at the same point in execution where the function would
normally return.
{Hl 4,Linking External Functions}Like the old saw about
{index gorilla}
how to shave a gorilla, linking an function image for LOAD must
be done {ul very} carefully.
 As a rule, you will have an easier time of it if the image to
be linked contains solely position independent content (PIC),
though this is not absolutely necessary.
{Ls 1}SPITBOL reserves a set of pages between
an address defined by the global symbol LOAD_BASE,
and the bottom of the interpreter
for loading images.
{index LOAD_BASE}
 LOAD_BASE is defined in the SPITBOL.OPT link
options file and is normally hex 2FE00.
{Ls 1}When requested by a LOAD(...) call to load an external
image, SPITBOL first allocates the next available page in this
area for image information, and maps the image itself directly above
this page, taking as many pages as required.
 The base address (if any) specified to the linker when the
image was generated has no effect on the base address of the load.
{index PIC}{index Position Independence}
 So even if the image is not PIC,
it is possible to predict in advance where the image will be loaded.
 Knowing this, the image can be linked with this location as the
base address.
 Note that if several non-PIC images are to be loaded with different
LOAD(...) calls, the order of the loading is significant.
{Ls 1}As an example, suppose you have an object module called
PROCSTATS produced by VAX/VMS Fortran V2 (non-PIC) which you wish to
use as a LOAD function.
 You would link the image with a linker command such as:
{Index SYS$SYSTEM}{Index SYS$LIBRARY}{Index SPITHLS}
{Ls 1}
{Center <$ LINK/MAP PROCSTATS,SYS$LIBRARY:SPITHLS,-~~~~~~~~~~>}
{Center <~ SYS$SYSTEM:SPITBOL/SELECTIVE_SEARCH,PROCSTATS/OPT>}
{Ls 1}
The reason for linking against SPITBOL's symbol table is to avoid
including the VMS shareable run-time library in the image.
 If this were not done, when the image were loaded,
PROCSTAT's code would be
in effect 'biased up' past your calculated load address to make
room for the shareable library linked in the virtual space below it.
 In many cases, there are also global symbols of interest in
the interpreter to which the program may need access.
 The PROCSTATS.OPT options file would contain at least one statement
to define the base address of the image of the form:
"BASE=%X30000".
{Index LOAD_BASE}
 This is one page above LOAD_BASE (%X2FE00) to leave room for
the image data page allocated first by SPITBOL.
{Ls 1}If additional non-PIC images were to be linked, the total
amount of virtual space used by images to be loaded first would
have to be calculated, in order to determine the actual load (base)
address.
{Index PIC}For images which are entirely PIC, the base address is irrelevant.
 Note that for languages such as Fortran, the code is PIC but
the pure data is not.
{hl 4,Unconverted Values and Results for LOAD}If a type other
than "INTEGER", "STRING", or "REAL" is indicated in the first
argument of the call to LOAD, the value is said to be "unconverted."
{Ls 1}In the case of passed arguments, a pointer to the internal
block for the argument is given to the program.
 The first longword of any such block is a SPITBOL block-type word.
 The remainder of the block is vertically encoded depending on the
block-type.
 No discussion of the internals of the interpreter are
provided here.
 The source listing gives a complete description of the storage blocks
for SPITBOL and should be consulted by anyone contemplating using
unconverted values.
{Ls 1}In the case of returned values, a pointer to the unconverted result
must be in R1 (returned value register).
 The block pointed to must be in SPITBOL-correct format, including the
value of the block-type word.
 It will be copied by SPITBOL into dynamic memory upon return.
{P}
{Hl 2,Linking SPITBOL}{Ls 2}
SPITBOL is delivered pre-linked and ready for use.
 Some sites or users may wish to link their own copies.
 (Modifications to the source are not encouraged, as it renders
much more difficult the process of diagnosing trouble reports.
 If trouble reports are submitted, the implementor requests that
the original, unmodified interpreter be used to provide the
necessary information.)
{index SYS$LIBRARY}{index LINKER}{index OPTIONS FILE}
{Index LOAD_BASE}
{Ls 1}The normal link command is:{Ls 1}
{Center {Ul $} LINK/SYMB=SYS$SYSTEM:SPITBOL/EXE=SYS$SYSTEM:SPITBOL -}
{Center {Ul $}_     SYS$LIBRARY:SPITBOL/OPT~~~~~~~~~~~~~~~~~~~~~~~~~}
{Ls 1}
The recommended SPITBOL.OPT linker options file is:{Ls 1}{Nfj}{Lin 5}
SPITV35,SPITGO,SPITMSGS,SPITSYS,SPITIOSYS,-
SYS$SYSTEM:SYS.STB/SELECT
BASE=1000000
IOSEGMENT=128
STACK=20
SYMBOL=LOAD_BASE,%X2FE00
PSECT_ATTR=CONSSECS,PAGE
PSECT_ATTR=CONSSECT,PAGE
PSECT_ATTR=PROGSECS,PAGE
PSECT_ATTR=PROGSECT,PAGE
PSECT_ATTR=WORKSECS,PAGE
PSECT_ATTR=WORKSECT,PAGE
{Ls 1}{Restore Lmg}{Fj}
Note that VAX/VMS SPITBOL is a licensed product and
sources, objects and executable images are for use only on the
system(s) where the license applies.
 This applies both to the delivered files as well as any modified
versions of them.
{Hl 2,Running SPITBOL}{Ls 2}
{index command line}
SPITBOL must be started with a command line
in order to specify filenames for the standard channels, and to
explicitly override any default processing options.  This means
that SPITBOL must be installed as a foreign command so that it
can recieve a command line.
 If SPITBOL has not been installed as a foreign command, this
can be done individually by the user by entering the VMS command:
{Ls 1}
{Center {Ul $} SPIT*BOL :== $SPITBOL}{Ls 1}
The system manager normally adds this to the systemwide login
command file as a part of the SPITBOL delivery process, so the
above should not be necessary.
{index switches}
{Ls 1}The general form of the SPITBOL startup command line is:
{Ls 1}{Center <$ SPITBOL/switch... input-file/switch... "Any Text>}{Ls 1}
The input-file sets the identity of the standard
input channel for SPITBOL.
{index .SPT}
 The default extension for this file is ".SPT".
 The standard input channel represents the program source, and
any data for the preassociated INPUT variable.
 Such data input should thus immediately follow the END statement of the
source.
 All switches are optional.
{index SYS$INPUT}
{Ls 1}If no input-file is given, or if SPITBOL is unable to
get a command line, the default input-file will be SYS$INPUT.
{Ls 1}The initial value of the startup command line as provided by
the VMS Command Line Interpreter (CLI) is assigned to the &ERRTEXT keyword.
This makes it possible to examine the command line as it is given to
SPITBOL, in order to determine filenames, switches and the like.
{index &ERRTEXT}
 (The assignment to &ERRTEXT is made just prior to execution, and is
not affected by any preceeding compilation errors.)
 Note that the CLI will compress runs of tabs and blanks into single
blanks, and place all unquoted text in upper case.
 Also note that the command string begins with the first non-blank
character {Ul following} the VMS command name.
{Index CLI}
 CLI "comments" (text following an unquoted "!" on the command line) are
not passed either.
{Ls 1}SPITBOL recognizes a double-quote (") as an end-of-command line
delimiter.
 Any text following the double-quote will be ignored by SPITBOL, but
will appear intact in the initial value of &ERRTEXT.
 This provides a mechanism for passing arbitrary text into the program
from the command line.
 The CLI will not alter the text following this double quote.
{Ls 1}It should be pointed out that the availability of startup command line
text in &ERRTEXT is an addition in VAX/VMS SPITBOL, and is not
necessarily portable to other implementations of the language.
{Ls 1}In some cases, there may be a SPITBOL application or utility program
for which a "custom" command may be desired.
 This is easily achieved with a definition something like:
{Ls 1}
{Center {Ul $} SPUTIL :== $SPITBOL/OUT=TT:/LOAD=SYS$LIBRARY:SPUTIL NL:}
{Ls 1}
Typing "{UL $}SPUTIL" as a VMS command will then load the saved EXIT
file named SPUTIL in SYS$LIBRARY and execute it with the standard output
file assigned to the terminal.
 Other permutations will be useful depending on the particular application.
{Hl 3,Startup Switches}Startup switches are optional
in the sense that there are
defined defaults for all of them that should be adequate most of the time.
 Switch names can be abbreviated to the minimum unambiguous length.
A syntax error in the startup command line will cause the interpreter
to exit with a message.
{Ls 1}Switches may appear at any point in the command line;
 they are processed left-to-right.
 There are no 'file-specific' switches as with some VMS languages,
all switches are global.
 The use of multiple input files separated either by commas or
plus signs is {ul not} supported.
{Ls 1}These are the switches provided on the SPITBOL startup
command line:
{List}
!
{Listelem /CRC /NOCRC}/CRC /NOCRC{brk}
{index /CRC}{index /NOCRC}
This switch is only meaningful on a /LOAD=... operation, where the
specification of /NOCRC will bypass the cyclic reducdancy check of
the SPITBOL code region.
 The purpose of this check is to insure that the version of SPITBOL
being used is the same as the version under which the exit module was
saved.
 As SPITBOL also checks version identification data and other parameters,
the overhead for this check may be considered unnecessary for frequently
used load modules.
 In such cases, /NOCRC can be profitably specified.
!
{Listelem /CSTATS /NOCSTATS}/CSTATS /NOCSTATS{brk}
{index /CSTATS}{index /NOCSTATS}
This switch will suppress the printing of compilation
statistics on the output file.
 "/CSTATS" is the default.
 If /NOLIST has been specified, the default is /NOCSTATS.
!
{Listelem /ESTATS /NOESTATS}/ESTATS /NOESTATS{brk}
{index /ESTATS}{index /NOESTATS}
This switch will suppress the printing of execution
statistics on the output file.
 "/ESTATS" is the default.
 If /NOLIST has been specified, then the default is /NOESTATS.
{Listelem /EXECUTE /NOEXECUTE}/EXECUTE /NOEXECUTE{brk}
{index /EXECUTE}{index /NOEXECUTE}
This switch has the same logical effect as a
{index -NOEXECUTE}
-NOEXECUTE control card in the source program.
 SPITBOL will process the source program, and then exit with a
message that Execution Was Suppressed.
 The default is "/EXECUTE".
!
{Listelem /LIST /NOLIST}/LIST[=filename] /NOLIST{brk}
{index /LIST}{index /NOLIST}
The /LIST switch allows specification of the filename for the
standard output channel.
 If a terminal device is specified for the /LIST switch,
then form feeds in the program listing will be suppressed.
 The default device and account for this file is the same as that under
which SPITBOL is being run.
 The default name for the output file is the input file's name, and
the default extension is ".LIS".
 The program listing and compilation statistics are sent to this file.
 If neither of /OUTPUT=... or /NOOUTPUT are also specified on the command
line, then execution output is also directed to this file.
 This includes OUTPUT assigned text and TRACE and DUMP output.
{Ls 1}The /NOLIST switch indicates that source listing is not to be generated.
/NOLIST also causes an implicit /NOESTATS and /NOCSTATS.
 Note that the appearance of /NOLIST does not mean that
no output will be sent to the standard output channel.
 However, if the program makes no reference to the standard output channel,
then if /NOLIST is specified, this channel will never be opened.
{Ls 1}/LIST with no filename inverts the effect of a previous /NOLIST spec.
 That is, enables source listing and compilation statistics.
!
{Listelem /MINC}/MINC=nnn{brk}
{index /MINC}
This switch controls the number of pages by which
SPITBOL's working store is expanded when it becomes exhausted.
 Under normal circumstances, it should not be necessary to specify
this switch, however, "/MINC=0" will prevent any additional allocation
to SPITBOL past the MINT allocation, and may thus be useful in
preventing the unrestrained growth of the interpreter.
{Ls 1}Even if MINC is non-zero, there are three cases which could
concievably cause dynamic allocation of a SPITBOL object to fail.
 These are:
{Ls 1}{Lin 5}
{index &MAXLNGTH}{index MXLEN}
{Outdent 2}-~The size of the object exceeds &MAXLNGTH (MXLEN).
 As this is initially greater than one million, this fault is very
unlikely to occur except as the result of a programming error.
{Ls 1}{Outdent 2}-~If allocation would cause the virtual memory
quota to be exceeded, SPITBOL will print a MEMORY OVERFLOW error, and
terminate execution.
 This is also unlikely on most systems.
{index RMS}
{Ls 1}{Outdent 2}-~If SPITBOL has been linked allowing RMS buffers to extend in
{Index P0BUFS}
P0 space (linker option P0BUFS - the default), then with a large number of
simultaneously open files an RMS space extension would block the
contiguous growth of the dynamic area and cause a memory overflow.
{Ls 1}{Restore Lmg}
The default for this switch is "/MINC=20" which is 10K bytes
or about 2,000 SPITBOL 'words.'
!
{Listelem /MINT}/MINT=nnn{Brk}This switch controls the amount of
{index /MINT}
virtual memory
(in 512 Byte pages) that will be initally allocated for SPITBOL's
working storage areas.
 The SPITBOL VMS interface is designed to permit these working storage
areas to grow indefinitely, as long as the region remains contiguous,
and there are pages available in the process' virtual quota.
 However, SPITBOL will not request additional memory from VMS unless
it cannot get enough by regenerating its existing store.
 So, this switch may be useful in some situations
to avoid garbage collector thrashing.
 A thrashing situation can usually be spotted from the "REGENERATIONS"
count on the statistics sheets.
 The default for this switch is "/MINT=200" which is equivalent to
{index word}{index longword}
about 100K bytes, or 25,000 SPITBOL 'words' (VAX Longwords).
{index garbage collection}
{Ls 1}For most applications, the performance will increase quite dramatically
as real memory is made available.
 Past that point, additional working set will improve performance only
marginally.
 As the dynamic space is allowed to become increasingly virtual,
performance will very gradually deteriorate because of the thrashing
caused (principally) during garbage collection.
 Thus as a general guide, it is usually best to minimize garbage collection
at the expense of additional memory.
{index stack}
{Ls 1}Stack space is not included in the MINT allocation, instead,
stack is allocated by SPITBOL as needed.
 Thus, stack overflow can only be caused by an insufficient virtual
memory quota.
!
{Listelem /OUTPUT}/OUTPUT[=Filename]{brk}
{index /OUTPUT}{index /NOOUTPUT}
 The /OUTPUT=filename switch requests an alternate file for the
standard output channel at execution time.  If this switch is not specified,
then execution output is directed at the same file as the source listing
(/LIST=filename).
 This file is not opened until execution begins.
 If at that time the channel cannot be opened, SPITBOL exits with a
fatal status.
{Ls 1}/NOOUTPUT directs any execution-time references to the standard
output channel to the null device (NL:)
{Ls 1}/OUTPUT with no filename restores the default condition.
 That is, execution output is appended to the listing output.
{Ls 1}Note that /OUTPUT and /LIST are not synonymous.
!
{Listelem /PAGE /NOPAGE}/PAGE /NOPAGE{brk}
{index /PAGE}{index /NOPAGE}
If this switch is specified, page separators in
the source listing and statistics will be a few blank lines, instead of
form feeds.
 "/PAGE" is the default, unless the standard output channel (see /OUTPUT
switch) is a terminal, in which case "/NOPAGE" is the default.
{Index LIB$LP_LINES}{Index SYS$LP_LINES}
{Ls 1}At startup, LIB$LP_LINES is called to get the page length.
 From the value returned (66 unless the logical
name SYS$LP_LINES is assigned), six
 is subtracted to leave room for page shoulders.
!
{Listelem /WARN /NOWARN}/WARN /NOWARN{Brk}
{index /WARN}{index /NOWARN}
When /NOWARN is indicated on the command line, only errors and severe
errors in the VMS interface logic will be reported on SYS$ERROR.
 This can be useful to suppress messages regarding source line truncation,
exit module saves and similar messages.
/WARN, the default, causes reporting of such conditions.
{Ls 1}This switch does not affect in any way SPITBOL's handling of errors with
respect to the program.
!
{Listelem /WIDTH}/WIDTH=nnn{brk}
SPITBOL attempts to compute a proper width for the standard output file.
{index /WIDTH}
 The switch "/WIDTH=n" can be used to override any default.
 Otherwise, if the output device is record-oriented (including
spooled files), the default is the buffer for the device as
indicated by VMS.
 If the buffer size cannot be obtained, or is outside the range
[0..255], then a final default of 132 (decimal) is applied.
{Endlist}
{P}{Hl 3,VMS Errors}
{index errors}
In addition to the errors issued by the interpreter,
the VMS interface may detect a number of conditions which it will
report using the default VMS condition handler.
{Ls 1}There follows the list of SPITBOL's VMS-specific errors, and
the severity of the error.
 Errors which have a severity of warning or less can be suppressed
{Index /NOWARN}
with the /NOWARN startup command line switch.
 Errors with a listed severity of "Severe" will generally cause
execution to be aborted with the DCL
{index $STATUS}{index $SEVERITY}{index DCL}
$STATUS and $SEVERITY symbols set appropriately.
{Ls 2}{Tset input,,Endtext=!**,Informat=False,Fill=False,Just=False}
 Error Name    Severity          Description

 EXIT           Info     EXIT Module Saved - <Filename>
 EXSUP          Info     Execution Suppressed
 INSVIRMEM      Severe   Insufficient Virtual Memory
 LINETRUNC      Warning  Input Source Line Truncated
 LOADCRC        Severe   Load Incompatible,
                           Please Retranslate Source
 LOADMEM        Severe   Insufficient Virtual Memory For LOAD
 LOADOPEN       Severe   Can't Open LOAD File - <Filename>
 LOADMAP        Severe   Error Mapping LOAD File - <Filename>
 LOADUNEXCOND   Error    Loaded Function Failed To Handle
                           Condition At PC=<Hex PC>
 LOADUNEXTRY    Info     Will Attempt to Recover By
                           Forcing Failure
 LOADVERS       Severe   Load Versions Incompatible,
                         Please Retranslate Source
 NOSYSOUT       Severe   Output File Not Accessable
 NOTEXITMOD     Severe   File is Not a Saved EXIT
                           File - <Filename>
 OPENOUT        Severe   Error Opening <Filename> as Output
 OPENIN         Severe   Error Opening <Filename> as Input
 PAUSE          Info     Paused at Statement <Stmt #>
 STACKOVFL      Severe   Virtual Stack Space Exhausted
 SYNTAX         Severe   Syntax Error In Command Line
!**
{p}
{index character set}
{Hl 2,VAX/VMS Character Set}
{Ls 1}Character codes can be a considerable locus of confusion
in SPITBOL.
 The SNOBOL4 language does not define a "standard" graphic set,
so in general an attempt has been made to conform to the
{index IBM}{index EBCDIC}
original IBM/360 EBCDIC symbology where possible
(excluding the 'extended graphics').
 This is the character style most often used in references and manuals.
{index alternation}
{Ls 1}The point where this is most likely to cause problems is
with the binary bar (alternation), which in many other ASCII
implementations has been set as the exclamation point.
 Such programs as make use of this convention must be editted <->
{Index OPSYN}
OPSYN cannot be used to redefine a system operator's semantics
in MACRO SPITBOL.
 Note also that the unary not-sign may be different, although with
the selection feature of MACRO SPITBOL, this is an infrequently used
operator.
{Ls 1}The correspondence between the
{index SNOBOL4}
SNOBOL4 and Macro SPITBOL source program character set is as follows:
{Setq ch,{D 1}{T 20}{D 2}{T 35}{D 3}{brk}}
{Ls 1}
{Ul Character Name}{T 20}{Ul IBM SNOBOL4}{T 35}{Ul VAX/VMS SPITBOL}{LS 1}
{ch Digits,0..9,0..9}
{Ch Letters,A..Z,A..Z a..z}
{Ch Left Parenthesis,(,(}
{Ch Right Parenthesis,),)}
{Ch Left Angle Bracket,{Oab},{Oab} or [}
{Ch Right Angle Bracket,{cab},{cab} or ]}
{ch Colon,:,:}
{Ch Semicolon,;,;}
{Ch Comma,<,>,<,>}
{Ch Equal Sign,=,=}
{Ch Double Quote,","}
{Ch Single Quote,','}
{Tset Hs,< >}{Ch Negation,<<Not-Sign>>,~}{Restore Hs}
{Ch Query,?,?}
{Ch Dollar Sign,$,$}
{Ch Point,.,.}
{Ch Exponentiation,**,** or !}
{Ch Percent,%,%}
{Ch Asterisk,*,*}
{Ch Divide,/,/}
{Ch Plus,+,+}
{Ch Minus,-,-}
{Ch At,<@>,<@>}
{Ch Blank,<<Blank>>,<<Blank> or <Tab>>}
{Ch Alternation,|,|}
{Ch Number Sign,#,#}
{Ch Ampersand,&,&}
{Ch Underscore,not avail.,_}
{p}
{Hl 1,Delivery and Installation}{Ls 1}
{Index Delivery}{Index Installation}
This section of the SPITBOL manual
describes the process for unpackaging and installing
the VAX/VMS MACRO SPITBOL software.
 This section is also provided in hardcopy form with the 1600BPI tape
to facilitate the installation process.
 If this is the first time you have performed the delivery, please
read through these directions before starting;
 the delivery process is not highly automated, and there will be a
number of decisions for you to make.
{Ls 1}There are four steps to be initially performed
to deliver and install the software package.
{List}
{Index SYS$LIBRARY}{Index SYS$HELP}{Index SYS$SYSTEM}
{Listelem}Get the files from the tape into the proper directories,
and link the interpreter.
 The directories involved are SYS$LIBRARY:, SYS$HELP:, and
SYS$SYSTEM:.
 Be certain that these VMS standard logical names are defined to correspond to
valid directories on the system disk before undertaking the
software installation.
{Listelem}Establish the VMS environment and commands necessary to
execute MACRO SPITBOL.
{Listelem}Generate the reference manual and help file.
 The program which does this is a SPITBOL program, so this serves
as an installation checkout.
{Listelem}Delete and/or copy off any optional files which you don't
want to keep.
{endlist}
Each of these steps is now detailed in turn.
{Ls 2}{Ul {Dbl NOTE:}}~This version of MACRO SPITBOL requires version
2.0 of VMS or higher.
{Index VMS}
 If you are running any version 1 of VMS you cannot use the interpreter.
 You must first upgrade your system to version 2 of VMS
before attempting to install MACRO SPITBOL.
{p}
{Hl 2,Transferring Delivery Files}{Ls 2}
Follow these steps:
{List}
{Listelem}Log on to the hardcopy system console using the privileged
SYSTEM account.
 Be certain that your default is set to the system disk.
 "BYPASS" privilege is recommended as it insures that there will be
no snags in renaming or copying files.
{Listelem}If there are any existing files or directories for an
earlier version of SPITBOL, they should be deleted.
 (The new version is strictly upward compatible with previous versions.)
 If it does not already exist, create an empty scratch directory named
SYS$DISK:[SPITBOL] with the command:
{Ls 1}{Center {Ul $} CRE/DIR SYS$DISK:[SPITBOL]}{Ls 1}
{Listelem}Set your default to the SPITBOL directory using the command:
{Ls 1}{Center {Ul $} SET DEFAULT SYS$DISK:[SPITBOL]}{Ls 1}
{Listelem}Mount the delivery tape on a drive with a command such as:
{Ls 1}{Center {Ul $} MOUNT MT:/OVER=ID}{Ls 1}
{Listelem}Copy all files from the tape into the directory using a
command similar to:
{Ls 1}{Center {Ul $} COPY MT:*.* *}{Ls 1}
{Listelem}Dismount the tape with a command such as:
{Ls 1}{Center {Ul $} DISMOUNT MT:}{Ls 1}
{Listelem}Enter the command:
{Ls 1}{Center {Ul $} @SPITBOL}{Ls 1}
This command file will rename files to their proper directories,
and link the interpreter image.
{endlist}
Sites with a previous release of the interpreter may want to print
a copy of [SPITBOL]RELNOTES.LIS which documents changes in this
release.
{p}
{Hl 2,Installing MACRO SPITBOL}
{List}
{listelem}Enter the commands:
{Index SYS$SITENAME}
{Ls 1}
{Center {ul $} SPIT*BOL :== $SYS$SYSTEM:SPITBOL~~~~~}
{Center {Ul $} ASSIGN/SYS "<<site-name>>" SYS$SITENAME}
{Ls 1}
In the above, "<<site-name>>" is any text string of 28 or fewer
characters which SPITBOL will use for the site identification.
{Ls 1}Using an editor,
place the first of the above definitions in the systemwide login command
file to define them for all users.
 (The name of this file varies from system to system, SYLOGIN.COM and
SYSLOGIN.COM in SYS$MANAGER: is typical.
 If your site has not established such a file, then users will have
to define this command in their own LOGIN.COM files.)
 The ASSIGN command should be inserted into SYS$MANAGER:SYSTARTUP.COM~.
{Endlist}
{Hl 2,Interpreter Checkout and Documentation Generation}
{List}
{Listelem}Set your default to SYS$LIBRARY:
{Listelem}Enter the command:
{index GPMDOC}
{Ls 1}{Center {Ul $} SPIT GPMDOC " <{SET INPUT,SPITBOL.GPM}>}
{Ls 1}
(Note the blank following the double quote in the above command.
 This blank is significant and must be included as shown.)
If all is well, this will cause the system to
ask if you want to produce the manual.
 Answer "yes".
 Generating the approximately 90 page manual takes about 4-5 minutes
on an unloaded VAX 11/780.
 If it is working, a message should appear on your console for
every page produced.
{Ls 1}After this, you will be asked if you want to generate the help file.
 Again answer "yes".
 The generated file is a reformatted version of the manual itself, in
VMS help library format.
{Ls 1}When this concludes, the GPMDOC program exits.
{Listelem}Print SYS$LIBRARY:GPMDOC.LIS on a 132 column line printer and examine
the listing to be sure that the interpreter is functioning properly.
 Look at the 2 line header on the first listing page and be certain that
the site name you defined above appears there.
{Listelem}Print SYS$LIBRARY:SPITBOL.MAN on (if possible) an 80 column,
8.5x11 inch, white paper printer.
 An LA120 DECwriter will do if there is plenty of time available.
 If any interactive device is used,
be certain to type "{Ul $}~SET~TERM/NOBROAD" before starting.
 The table of contents is at the back - it
should be moved to the indicated place at the beginning.
{listelem}You should now decide if you want to add the SPITBOL.HLP help
file to the system help file.
 (The only reason for not so doing would be that it consumes about
300 blocks of disk space).
 If you decide to do this, set your default to SYS$HELP: and enter the
following commands:
{Ls 1}
{Center {Ul $} LIB/COMPR=KEYSIZ:31/HELP HELPLIB}
{Center {Ul $} LIB/REPLACE/HELP HELPLIB SPITBOL}
{Center {Ul $} LIB/COMPRESS/HELP HELPLIB~~~~~~~}
{Center {Ul $} PURGE HELPLIB.HLB~~~~~~~~~~~~~~~}
{Ls 1}
{endlist}
{Hl 2,Delivery File Cleanup}{Ls 2}
The delivery and installation process is concluded.
 At this point, some sites may choose to delete some of the delivered files
in order to free up as much system disk space as possible.
 To such an end, a list of all delivered and generated files is
given here, grouped by their function.
 Examine the list and delete the ones you don't want.
{List}
{Listelem Basic Interpreter}BASIC INTERPRETER:{Brk}
Basic interpreter files consist of the executable image, objects,
and sources.
{Ls 1}The executable image is built as SYS$SYSTEM:SPITBOL.EXE~.
 This file must not be deleted.
 Also, SYS$SYSTEM:SPITBOL.STB is the corresponding symbol table
file which can be used when linking images for use by LOAD(...).
 It should also be retained.
{Ls 1}The objects are in SYS$LIBRARY: and named
SPITSYS.OBJ, SPITIOSYS, SPITGO, SPITMSGS and SPITV35.
 It is recommended that these files be kept.
 In addition, SYS$LIBRARY:SPITBOL.OPT is the standard SPITBOL link options
file and should be retained if the objects are.
{Ls 1}The sources are in SYS$LIBRARY and have the same names as the objects
except that the file extensions are different.
 SPITGO.MAR is the entry point, and provides command line processing,
initialization and basic file assignment.
 SPITSYS.MAR contains the VMS interface routines.
 SPITIOSYS.MAR contains the VMS interface routines for input and output
operations.
 SPITV35.MAR is the source for the interpreter itself.
 SPITMSGS.MSG is the source text for the error messages of the system.
It is input to the VMS "MESSAGE" processor.
{Ls 1}SPITMACS.MAR and SPITMACS.MLB comprise the macro library which
is required for assembling any of these sources.
{Ls 1}These source files will be of academic interest to most sites, and
can be profitably deleted since they consume a substantial quantity of
disk space.
{Listelem Interpreter Support Files}INTERPRETER SUPPORT FILES:{Brk}
On SYS$LIBRARY: will be found SPITHLS in .OBJ and .MAR form.
 These files are used in conjunction with the LOAD(...) feature and
should not be deleted.
 In any event they are quite small.
{Listelem Documentation Files}DOCUMENTATION FILES:{brk}
The delivery process outlined above uses and produces several files
that relate to MACRO SPITBOL documentation.
{Ls 1}In SYS$LIBRARY: will be found SPITBOL.GPM and SPITTEXT.GPM~.
These two files, together, comprise the needed information to
generate both the manual and help file text.
 They can be deleted once the manual and/or help file has been produced.
{Ls 1}The delivery process generates the manual in SYS$LIBRARY:SPITBOL.MAN.
Once a good copy of this has been printed, this file can be deleted.
{Ls 1}The help file text is produced in SYS$HELP:SPITBOL.HLP.
 This should be deleted only if no use is made of it.
 If you have added it to the system help library, keep the .HLP file
in case a future VMS delivery reinitializes the system help file.
{Ls 1}The delivery process generates a SPITBOL listing in
SYS$LIBRARY:GPMDOC.LIS.
 This file is of no value once it has been checked out,
and can be deleted.
{Listelem GPMDOC}GPMDOC:{Brk}
GPMDOC is the text processing program (written in SPITBOL) that
produces the manual and help text files.
 It is an interesting program in its own right, and for that reason you
may wish to keep it.
 Otherwise, all of the GPMDOC files can be deleted, they are in
SYS$LIBRARY:
{Ls 1}GPMDOC.SPT is the basic GPMDOC program source.
{Ls 1}GPMBIF.GPM is a file of auxiliary definitions needed by GPMDOC
when it starts up.
{Ls 1}GPMDOC.GPM is part of the reference documentation for GPMDOC.
 To generate this documentation, set the default to SYS$LIBRARY: and
enter the commands:
{Ls 1}
{Center {Ul $} <SPIT GPMDOC> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~}
{Center {UL $}_~<"~{SET OUTPUT,GPMDOC.MAN}{SET INPUT,GPMDOC.GPM}>}
{Center {Ul $} PRINT/DELETE <GPMDOC.MAN~~~~~~~~~~~~~~~~~~~~~~~~~>}
{Center {Ul $} <DELETE GPMDOC.LIS;*>~~~~~~~~~~~~~~~~~~~~~~~~~~~~~}
{Ls 1}
{Ls 1}JUSTIFY (.FOR, .OBJ, .EXE and .OPT) is a LOAD image used by GPMDOC that
{Index LOAD}
performs right-justification of text strings.
 It is not essential to the operation of GPMDOC (though it runs slightly
faster with it.)
 However, JUSTIFY is a good example of use of the LOAD(...) function
feature, and should be retained for that reason.
{Listelem Miscellaneous Files}MISCELLANEOUS FILES:{Brk}
The file [SPITBOL]SPITBOL.COM and it's scratch directory [SPITBOL]
are of no use once the delivery has been successfully completed,
and should be deleted.
 This directory also contains RELNOTES.LIS.
 These release notes are primarily directed at sites with an earlier
release of the system, and may be kept or deleted as desired.
{Ls 1}SYS$LIBRARY:DIF.SPT is a file comparator program similar to the
{Index DIF}{Index CMP}
PDP-11 "CMP" program.
 It runs significantly faster and, in most cases, more accurately than
the V2.2 VMS "DIFFERENCES" command and for that reason may be of
value to some sites.
 The command format for DIF is described in its source.
{endlist}