Google
 

Trailing-Edge - PDP-10 Archives - decus_20tap2_198111 - decus/20-0028/snobol.mem
There is 1 other file named snobol.mem in the archive. Click here to see a list.



                PDP-10 SNOBOL4 USER'S GUIDE



                             Author:  L.  P.  Wade
                               Date:  October 17, 1970
                            Version:  %004





                          PREFACE




     This manual is intended to serve as an introduction  to
SNOBOL4   on   the  PDP-10.   The  material  presented  here
describes all the unique aspects of the PDP-10  version  and
includes  the  introductory chapters of the reference manual
(Griswold, Poage Polonsky, THE SNOBOL4 PROGRAMMING  LANGUAGE
Copyright  1968.   Reprinted by permission of Prentice-Hall,
Inc., Englewood Cliffs, N.  J.) for  those  unfamiliar  with
the language.


This manual describes version 3.4 on the PDP-10.


Copyright  1970,  Digital  Equipment  Corporation   Maynard,
Mass., 01754.
PDP-10 Snobol4 User's Guide                           Page 2
TABLE OF CONTENTS


               ----- TABLE OF CONTENTS -----



1. INTRODUCTION

2. PDP-10 DIFFERENCES AND FEATURES

     A. Character Set

     B. Input/Output

     C. Omissions

     D. Changes

     E. Additions

   Notes for the Novice

3. INTRODUCTION TO THE SNOBOL4 PROGRAMMING LANGUAGE

     A. Assignment Statements

        and Basic Data Types

     B. Pattern Matching Statements

     C. Replacement Statements

     D. Patterns

     E. Conditional Value Assignment

     F. Flow of Control

     G. Indirect Reference

     H. Functions

     I. Keywords

     J. Arrays

     K. Programmer-defined Data Types

     L. Program Example

     M. Tables

4. INPUT AND OUTPUT

     A. Printed Output
PDP-10 Snobol4 User's Guide                           Page 3
TABLE OF CONTENTS


     B. Punched Output

     C. Input

     D. The I/O System

     E. Output Associations

     F. Input Associations

     G. Other I/O Functions

5. STRUCTURE OF A SNOBOL4 RUN

     A. Compilation

     B. Execution

     C. Termination

APPENDIX A - SYSTEM PROGRAMMER'S NOTES

APPENDIX B - DEVICE NUMBER ASSIGNMENTS
PDP-10 Snobol4 User's Guide                           Page 4
CHAPTER 1


INTRODUCTION

     The  PDP-10  version  of  SNOBOL4  is   almost   wholly
compatible  with  the  Bell  Telephone  Laboratories version
running on  other  systems.   Minor  changes  were  required
because  of  slightly different character sets and operating
systems.  In addition several  modifications  were  made  to
take  advantage  of the PDP-10 time sharing features.  These
unique characteristics are itemized later in this chapter.

BACKGROUND

     SNOBOL stands for StriNg-Oriented symBOlic Language (1)
and   was   developed   at   Bell   Telephone  Laboratories,
Incorporated, in 1962 by  D. J. Farber,  R. E. Griswold  and
I. P. Polonsky.   SNOBOL4  is  the  latest in the series and
contains features not commonly found  in  other  programming
languages.   As  such  it  is a useful tool in such areas as
compilation   techniques,   machine   simulation,   symbolic
mathematics, text preparation, natural language translation,
linguistics, and music analysis.

     The basic element of SNOBOL4 is a string of characters.
The  language  has  facilities  for  joining  and separating
strings,  for  testing  their  contents,  and   for   making
replacements  in them.  If the string is a paragraph, it can
be broken  into  sentences,  phrases  or  words.   A  common
operation  on  a string is examination of its contents for a
desired structure of characters.  This structure is known as
a  pattern  and  can  be  as  simple  as  a string or can be
extremely complicated.  The basic facility of SNOBOL is  the
use of the pattern in a pattern matching statement.

     SNOBOL4 provides numerical capabilities with both  real
and  integer  numbers.  However, the arithmetical facilities
are  not  extensive  since  the  language   is   essentially
character  oriented.   Also  a number of built-in functions,
called  primitive  functions,  are  available  which  are  a
standard  part  of  the language.  As examples, the function
LGT (for  lexical  comparison)  will  test  two  strings  to
determine  whether  the first is alphabetically greater than
the second,  and  the  function  REPLACE  will  replace  all
characters  in  one  set which appear in a given string with
corresponding members of another set.


   ------------------------------------------------------
(1) Farber was once overheard to  say  that  this  name  was
largely   contrived  when  the  original  JACM  article  was
published.  The name was apparently picked when one  of  the
original implementors made a statment such as, "This program
doesn't have a snowball's chance in hell of ...".
PDP-10 Snobol4 User's Guide                           Page 5
CHAPTER 1


     Execution of SNOBOL4  programs  in  interpretive.   The
system  compiles  a  program into a notation the interpreter
can easily execute.  This approach makes it fairly simple to
provide  capabilities  such  as  tracing  of  new values for
variables, an operation that is otherwise  quite  difficult.
Another  important product of interpretation is flexibility.
Functions  can  be  defined  and  redefined  during  program
execution.   Function  calls can be made recursively with no
special program notation.  Consult "THE SNOBOL4  PROGRAMMING
LANGUAGE, for a complete description.

USER'S GUIDE

     SNOBOL4 on the PDP-10 corresponds to  the  latest  copy
released  by Bell Telephone Laboratories.  This is currently
version 3.4.

     The program takes  up  a  good  deal  of  core.   Small
programs   will  require  35K  to  run  and  serious  SNOBOL
programming will likely require 45K to  50K  of  user  core.
The high segment requires about 16K and the low segment will
initially take 17K and expand as more core is needed.

     The following  remarks  assume  operation  on  a  10/50
system.   If  using  a  10/40  system,  refer  to the System
Programmer's Notes in Appendix A for additional details.

     In general, source programs will be prepared  with  one
of  the system editors and saved with an extension of "SNO".
Alternatively the source program can be typed  in  directly,
but  this  method  should be discouraged since a copy of the
program is not saved.

After getting SNOBOL into core by typing

                        R SNOBOL<CR>

it will type an asterisk indicating the user is expected  to
give  it  input.   At  this time the user should specify the
standard input and output device files, as described below

GENERAL FORMAT


LISTING-DEVICE:FILENAME.EXT_SOURCE-DEVICE:FILENAME.EXT(S)

LISTING-DEVICE

The device on which the output produced by SNOBOL is  to  be
written.  If a device is not specified DSK is assumed.

MTAn:  Magnetic Tape
DTAn:  DEC Tape
DSK:   Disk
PDP-10 Snobol4 User's Guide                           Page 6
CHAPTER 1


PTP:   Paper Tape Punch
LPT:   Line Printer
TTY:   Teletype

SOURCE-DEVICE

The  device  from  which  the  source   program   input   to
compilation  is  to  be read.  If a device is not specified,
"DSK" is assumed.

MTAn:  Magnetic Tape
DTAn:  DEC Tape
TTY:   Teletype
CDR:   Card Reader
PTR:   Paper Tape Reader


FILENAME.EXT (DSK:  AND DTAn:  only)

        The filename and filename
extension of the listing                                file
and the source file.


                                        If .EXT is  omitted,
.LST                                    is  assumed  for the
listing                                         file     and
.SNO is assumed                                         for
the source file.

                                        The  listing  device
is separated                                    from     the
source device by a                                      left
arrow.

     Note that a shorthand form is possible where  only  the
name  of  the input file needs to be specified.  For example
the user would type

                        SNOPRG<CARRIAGE RETURN> 

     This would result in the source program  SNOPRG.SNO  to
be  compiled  and the output to be written on the file named
SNOPRG.LST.

     The output file can be listed either with  PIP  or  the
LIST  command, or can be examined with an editor to look for
the desired results.

     While specifying the standard IO devices the  user  can
specify several switches as described below.
PDP-10 Snobol4 User's Guide                           Page 7
CHAPTER 1


     /D - Set the SNOBOL keyword DUMP in order  to  cause  a
dump of variable storage at program termination.

     /I - Increase the size of the reserved IO buffer  space
for  each  occurrence of this switch.  For each input/output
association which your program has which is  not  on  device
numbers  5  or  6,  you  must  use this switch to reserve IO
buffer space.  Initially, enough buffer space for a total of
six separate files is reserved (including the standard INPUT
and OUTPUT files).

     /U - Equivalent to -UNLIST to suppress printout of  the
source program listing.

     Later versions of the CCL program released by DEC  will
likely  have  an interface to SNOBOL.  If this version is on
the system the source  program  can  be  executed  with  the
EXECUTE command.  for example, you would type

                        .EXECUTE SNOPRG<CARRIAGE RETURN> 

The "EG" command of TECO could also be used to expedite  the
debugging process.
PDP-10 Snobol4 User's Guide                           Page 8
CHAPTER 2


              PDP-10 DIFFERENCES AND FEATURES


A.  CHARACTER SET


        1.  The alternation symbol is the  exclamation  mark
(!) instead of the vertical bar.

        2.  The negation symbol is the back slash (\).

        3.  The underline symbol is not defined.

        4.  Of the control characters,  TAB,  FORM-FEED  and
VERTICAL TAB are syntactically equivalent to BLANK.

        5.  Since the exclamation mark has been used for the
alternation symbol, it cannot be used for exponentiation.

        6.  Since the vertical bar is undefined,  it  cannot
be  used  to  indicate  a  comment line.  Additional comment
characters include the exclamation mark and semicolon.

        7.  Both upper and lower case letters are allowed.



B.  INPUT/OUTPUT 


        1.   The  devices  and  files  associated  with  the
standard  input and output reference numbers are selected by
the user at run time.  This mechanism is  a  substitute  for
the JCL procedure on the IBM/360.

        2.  The IO device reference numbers available to the
programmer are listed in Appendix B.

     3.   The   standard   FORMAT   statement   for   OUTPUT
associations  should  include  the A5 conversion rather than
the typical A1 conversion with IBM installations.

C.  OMISSIONS 


        1.   Variables  are  not  alphabetized  on  a   DUMP
request.

        2.    The   EXTERNAL   FUNCTION   feature   is   not
implemented.


D.  CHANGES 
PDP-10 Snobol4 User's Guide                           Page 9
CHAPTER 2


        1.  LIST LEFT has been made the default in order  to
make  it  more practical to use a TTY (it reduces the amount
of typeout).

E.  ADDITIONS 


        1.  The IFILE primitive function has been defined to
allow  the  user to select the disk filename for input files
at execution time.

     2.  The OFILE primitive function has  been  defined  to
allow  the user to select the disk filename for output files
at execution time.

        3.  The MSTIME primitive function has  been  defined
to  return  the elapsed time in milliseconds since midnight.
This is in contrast to the TIME function which returns  only
the runtime.

        4.  An INPUT association to device reference  number
99 is an interface to the PDP-10 TTCALL facility.  Each time
such an association is made, one  character  will  be  input
from   the   user's   terminal  (including  perhaps  control
characters).

        5.  An OUTPUT association to device reference number
99  is  interfaced to the PDP-10 TTCALL facility.  Each time
such an association is made, the referenced string  will  be
output.  No free CARRIAGE-RETURN/LINE-FEED will be added.

        6.  The ASCII primitive function has been defined to
allow referencing nonprinting and control characters.

        7.  The "D" switch is equivalent to &DUMP  =  1  and
causes a dump of variable storage at program termination.

        8.  The "U" switch  is  equivalent  to  -UNLIST  and
suppresses  all  compiler output up to the "ERRORS DETECTED"
message.

        9.  Dynamic core expansion has been added to  reduce
the amount of start-up core required.  As more core for free
storage is needed, it is  retrieved.   The  program  shrinks
back  to  its original size upon termination.  A message has
been added to the statistics printout  to  indicate  to  the
user how much core his program used.

        10.  The program has been made  reentrant,  to  make
multiprogramming of SNOBOL practical.


                    NOTES FOR THE NOVICE
PDP-10 Snobol4 User's Guide                          Page 10
CHAPTER 2


These notes may help you avoid some of the  common  pitfalls
usually made by new SNOBOL programmers.

     1.  Always remember that the "BLANK"  is  syntactically
significant  in SNOBOL and it must be present in a number of
key places.  For example,

        A.  Blanks must be on both sides of an "="  sign  in
an      assignment statement.

        B.   Blanks  must  be  on  both  sides   of   binary
operators,               I.E.  I = I + 1.

     In addition, blanks must  not  be  inserted  in  random
places.  For example, if in the label

                END.OF.FILE 

one of the dots was missing and a  BLANK  inserted  instead,
error  termination  will  likely  result  in  a "TRANSFER TO
UNDEFINED LABEL" message or cause incorrect results.  Blanks
must  also  not  be inserted between a function name and the
left parenthesis.

     2.  Remember that strings are always initialized to the
NULL  string.   Consequently,  misspelled  key variables can
cause confusing results.  For example, if  the  word  OUTPUT
was spelled as OUTPVT then the statement

                OUTPVT = 'DATE IS ' DATE() 

will assign the correct result but no output will occur.

     3.  It is good practice to always set the DUMP  keyword
in order to provide the maximum amount of information.

     4.  It is good practice to always set the TRIM  keyword
to  work  with  trimmed  strings, especially until you see a
need to leave trailing blanks on.

     5.  When making OUTPUT associations, you should use the
following FORMAT

                OUTPUT('TYPE',5,'(1X,16A5)')

The A5 format is  the  only  practical  "A"  FORMAT  on  the
PDP-10.   In particular A1 formats will give you every fifth
character.

     6.  Access to disk files is possible through the  IFILE
and OFILE primitive functions (described elsewhere)..break
PDP-10 Snobol4 User's Guide                          Page 11
CHAPTER 3



INTRODUCTION TO THE SNOBOL4 PROGRAMMING LANGUAGE 


        This chapter is  an  introductory  overview  of  the
SNOBOL4  programming  language.   It describes the format of
statements, some of the operations, and some of the types of
data   handled   by  the  language.   The  reference  manual
describes in more detail the material in  this  introductory
chapter.

        A  SNOBOL4  program  consists  of  a   sequence   of
statements.  There are four basic types of statements:

        1)  THE ASSIGNMENT STATEMENT,
        2)  THE PATTERN MATCHING STATEMENT,
        3)  THE REPLACEMENT STATEMENT, AND
        4)  THE END STATEMENT.

THE END statement terminates the program.

A.  ASSIGNMENT STATEMENTS AND BASIC DATA TYPES 

The simplest type of statement is the assignment  statement.
It has the form

        VARIABLE = VALUE 

The assignment statement may be said to have  the  following
meaning:   "LET VARIABLE HAVE THE GIVEN VALUE." For example,
let V have the value 5, or

        V = 5 

The value may be given  by  a  expression,  consisting,  for
example, of arithmetic operations as in the statement

        W = 14 + (16 - 10) 

which assigns the value 20 to the variable  W.   Blanks  are
required  around arithmetic operators such as + and - .  The
value need not be an integer, which is just one type of data
handled  by SNOBOL4.  For example, the value may be a string
of characters, indicated by enclosing quotes.  An example is
the assignment statement

        V = 'DOG' 

which assigns the string DOG to  the  variable  V.   Various
types  of  data and operations that may be performed on them
are described later.

Typically a variable is  a  name  such  as  V,  X,  or  ANS.
Variables  appearing explicitly in a program must begin with
PDP-10 Snobol4 User's Guide                          Page 12
CHAPTER 3


a letter which may be followed by  any  number  of  letters,
digits and periods.

The value of  a  variable  may  be  used  in  an  assignment
statement.  Thus

        RESULT = ANS.1 

assigns  to  the  variable  RESULT  the  value   of   ANS.1.
(Quotation    marks   distinguish   literal   strings   from
variables.)

Blanks are required to separate the parts  of  a  statement.
In an assignment statement, the equal sign must be separated
from the variable on the left and the value on the right  by
at least one blank.

A statement which is longer than one line can  be  continued
onto successive lines by starting the coninuation lines with
a period or plus sign.  An example is

           N   =   (3 + M)  (2 + SUM)  -
.   (F - 2)

When continuing  a  statement  over  a  line  boundary,  the
statement may be broken wherever a blank is required.  

Several statements may  be  placed  on  one  line  by  using
semicolons  which  indicate  the  ends  of  statements.   An
example is

        X = 2;  Y = 3;  Z = 10 

A line beginning with an asterisk is treated  as  a  comment
and does not affect the operation of the program.

        1.  INTEGERS 

The  arithmetic   operations   of   addition,   subtraction,
multiplication, division, and exponentiation of integers may
be used in expressions.  The statements

        N  =  5;  M  =  4
        P  =  N * M / (N - 1)

assign the value 5 to P.  While blanks are required  between
the  binary  operators  and  their operands, unary operators
such as the minus sign must be adjacent to  their  operands.
An example is the statement

      Q2 = -P / -N 

which assigns the value 1 to Q2 .
PDP-10 Snobol4 User's Guide                          Page 13
CHAPTER 3


Arithmetic expressions can  be  arbitrarily  complex.   When
evaluating  arithmetic  expressions,  the  natural  order of
operator  precedence  applies.   The  unary  operations  are
performed    first,    then    exponentiation   (**),   then
multiplication, followed by division, and  finally  addition
and  subtraction.   All  operations  associate  to  the left
except exponentiation.  Hence,

        X = 2 ** 3 ** 2 

is equivalent to

        X = 2 ** (3 ** 2) 

Parentheses may be used to emphasize or alter the  order  of
evaluation of an expression.

In the above examples all the operands are integers and  the
results  are integers.  The quotient of two integers is also
an integer.  The remainder is discarded.  Thus

        Q1  =  5 / 2
        Q2  =  5 / -2

give  Q1  and  Q2  the  values  2  and   -2,   respectively.
Similarly,

        MOD = N - (N / M) * M 

gives MOD the value N modulo M  if  N  and  M  are  positive
integers.

        2.  REAL NUMBERS 

Arithmetic expressions  involving  real  operands  are  also
permitted in assignment statements.  The statements

        PI  =  3.14159
        CIRCUM  =  2. * PI * 5.

assign real values to PI and CIRCUM.

Exponentiation  can  be  performed  on  real  operands.   In
addition  integer  and  real  numbers can be mixed freely to
permit mixed-mode arithmetic.


        3.  STRINGS 

Expressions involving operands that  are  character  strings
are  also  permitted in assignment statements.  For example,
the assignment statement

        SCREAM = 'HELP' 
PDP-10 Snobol4 User's Guide                          Page 14
CHAPTER 3


assigns the string HELP as the value of SCREAM .

The string is specified by enclosing it  within  a  pair  of
quotation  marks.   Any character may appear in a string.  A
pair of double quotation marks can be used instead of single
quotation  marks.   This  permits the use of quotation marks
within a string as in the statements

        PLEA  =  'HE SHOUTED, "HELP."'
        QUOTE  =  '"'
        APOSTROPHE  =  "'"

THE NULL STRING 

The NULL string, which  is  a  string  of  length  zero,  is
frequently   used   in  SNOBOL4.   With  a  few  exceptions,
explained later, all variables have the NULL string as their
initial  value.   A  variable  can also be assigned the NULL
string by a statement like

        NULL = ''

or, more briefly,

        NULL =

The variable NULL is used in many examples  that  follow  to
represent the NULL string.

The NULL string is different  from  the  following  strings,
each of which has length one:

        '0'
        " "

STRINGS IN ARITHMETIC EXPRESSIONS



Numeral strings can be used in arithmetic expressions with
integers.  For example, as a result of the statements

      Z = '10'
        Z  =  "10"
        X  =  5 * -Z + '10'

X has the value -40.  Numeral strings  contain  only  digits
and a decimal point and perhaps a preceding sign.  Thus, the
following strings can be used in arithmetic expressions:

        '-3.50'
        '3.257'

The  following  strings  cannot  be   used   in   arithmetic
PDP-10 Snobol4 User's Guide                          Page 15
CHAPTER 3


expressions:

        '1,253,465'
        '.364 E-03'

They cause execution of the program to  terminate  with  the
comment "ILLEGAL DATA TYPE."

Strings can be used in expressions involving real numbers.

The NULL  string  is  equivalent  to  the  integer  zero  in
arithmetic expressions.

STRING-VALUED EXPRESSIONS 


Concatenation is  the  basic  operation  for  combining  two
strings   to   form   a  third.   The  following  statements
illustrate   the   format   of   an   expression   involving
concatenation.

        TYPE  =  'SEMI'
        OBJECT  =  TYPE 'GROUP'

The resulting value of OBJECT  is  the  string  SEMIGROUP  .
Notice  there  is  no  explicit  operator for concatenation.
Concatenation is indicated by specifying two  string  valued
operands separated by at least one blank.

        FIRST  =  'WINTER'
LT      SECOND  =  'SPRING'
        TWO.SEASONS  =  FIRST ',' SECOND

are equivalent to

        TWO.SEASONS = 'WINTER,SPRING' 

Strings can also be concatenated with integers as in

        ROW  =  'K'
        NO.  =  22
        SEAT  =  ROW NO.

which gives SEAT the value K22 .

In  an  expression  involving  concatenation   and   integer
arithmetic, concatenation has the lowest precedence.  Thus

        SEAT = ROW NO.  + 4 / 2 

is equivalent to

        SEAT = ROW (NO.  + 4 / 2)) 
PDP-10 Snobol4 User's Guide                          Page 16
CHAPTER 3


or 

        SEAT = 'K24' 


INPUT AND OUTPUT OF STRINGS 



Three variables provide means for reading and writing  data.
The   variables  OUTPUT  and  PUNCH  are  for  printing  and
punching.  Whenever either of them is assigned a  string  or
integer value, a copy of the value is put out.

        OUTPUT  =  'THE RESULTS ARE:'

assigns THE RESULTS ARE:  to OUTPUT and also prints it.

        PUNCH = OUTPUT 

causes the same line to be punched on the card  punch.   The
statements

        OUTPUT  =
        PUNCH  =

cause a blank line to be printed and  a  blank  card  to  be
punched.

The variable INPUT is used for  reading  in  strings.   Each
time  the value of INPUT is required in a statement, another
card is read in  and  the  80  character  string  on  it  is
assigned as the value of INPUT.  Thus

        PUNCH = INPUT 

produces a copy of the input card on the card punch.

B.  PATTERN MATCHING STATEMENTS 


The operation of examining substrings for the occurrence  of
specified substrings (i.e.  pattern matching) is fundamental
to the SNOBOL4 language.  Pattern matching can be  specified
in two types of statements:

        1)  THE PATTERN MATCHING STATEMENT, AND
        2)  THE REPLACEMENT STATEMENT.

The pattern matching statement has the form

        SUBJECT PATTERN 

where the two fields are separated by at  least  one  blank.
PDP-10 Snobol4 User's Guide                          Page 17
CHAPTER 3


The  subject  specifies a string that is to be examined, and
the pattern can  be  thought  of  as  specifying  a  set  of
strings.   The  statement  causes  the  subject string to be
scanned from  the  left  for  the  occurrence  of  a  string
specified by the pattern.

If

        TRADE = 'PROGRAMMER' 

the statement

        TRADE 'GRAM' 

examines the value of TRADE for an occurrence of GRAM .  If

        PART = 'GRAM' 

then an equivalent statement is

        TRADE   PART 

The  following  example  illustrates  a   pattern   matching
statement   in   which   the  pattern  is  a  string  valued
expression.

        ROW  =  'K'
        NO.  =  20
        'K24'  ROW  NO. + 4

The subject is a literal and the value of the expression  is
the string K24 .

Notice that there is no explicit pattern  matching  operator
between  the  subject  and  the pattern.  The two fields are
separated by blanks.

If it is necessary to have concatenation in the subject, the
expression  must  be  enclosed  within  parentheses to avoid
ambiguity.  An example is

        TENS  =  2
        UNITS  =  5
        (TENS UNITS)  30

On the other hand, a pattern formed  by  concatenation  does
not   need   parentheses.    The  following  statements  are
equivalent:

        TENS UNITS 30 

        TENS (UNITS 30) 

C.  REPLACEMENT STATEMENTS 
PDP-10 Snobol4 User's Guide                          Page 18
CHAPTER 3


A replacement statement has the form

        SUBJECT PATTERN = OBJECT 

where the fields are separated by at least  one  blank.   If
the  pattern  matching operation succeds, the subject string
is modified  by  replacing  the  matched  substring  by  the
object.  For example, if

        WORD = 'GIRD' 

then the replacement statement

        WORD 'I' = 'OU' 

causes the subject string GIRD to be scanned for the  string
I and then, since the pattern matches, I is replaced by OU .
Hence word has as value the string GOURD .  If the statement
is

        WORD 'AB' = 'OU' 

the value of WORD does not change because the pattern  fails
to match.

Another example of the  use  of  replacement  statements  is
given in the following sequence of statements

        HAND  =  'AC4DAHKDKS'
        RANK  =  4
        SUIT  =  'D'
        HAND  RANK SUIT  =  'A5'

which replaces the substring 4D with the string A5 .

A matched substring is deleted from the  subject  string  if
the  object in the replacement statement is the NULL string.
Thus

        HAND RANK SUIT = 

deletes 4D from hand leaving it with the string ACAHKDKS  as
value.

D.  PATTERNS 

The  patterns  in  the  preceding  examples  specify  single
strings.   It  is  also  possible  to  specify  more complex
patterns.   There   are   two   operations   available   for
constructing such patterns:

       1)  Alternation, and
       2)  Concatenation.
PDP-10 Snobol4 User's Guide                          Page 19
CHAPTER 3


Alternation is indicated by an expression of the form

        P1 !  P2 

where the two patterns P1 and P2 are separated  from  the  !
by  blanks.   The  value  of  the  expression  is  a pattern
structure that matches any string specified by either P1  or
P2.  For example, the statement

        KEYWORD = 'COMPUTER' !  'PROGRAM' 

assigns to KEYWORD a pattern structure that  matches  either
of these two strings.

Subsequently, KEYWORD may  be  used  wherever  patterns  are
permitted.  for example,

        KEYWORD = KEYWORD !  'ALGORITHM' 

gives KEYWORD a new pattern value equivalent  to  the  value
assigned by executing the statement

        KEYWORD = 'COMPUTER' !  'PROGRAM' !  'ALGORITHM' 

Similarly,

        TEXT KEYWORD = 

examines the value of TEXT from the  left  and  deletes  the
first occurrence of one of the alternative strings.  If

        TEXT = 'PROGRAMMING ALGORITHMS FOR COMPUTERS' 

the result  of  the  replacement  statement  is  as  if  the
following statement were executed:

        TEXT = 'MING ALGORITHMS FOR COMPUTERS' 

Concatenation of two patterns, P1 and P2,  is  specified  in
the same way as the concatenation of two strings:

        P1 P2

that is, the two patterns  are  separated  by  blanks.   The
value  of  the expression is a pattern that matches a string
consisting of two substrings, the first matched by  P1,  the
second matched by P2.  For example, if

        BASE  =  'BINARY' ! 'DECIMAL' ! 'HEX'
        SCALE  =  'FIXED' ! 'FLOAT'
        ATTRIBUTE  =  SCALE BASE

and
PDP-10 Snobol4 User's Guide                          Page 20
CHAPTER 3


        DCL = 'AREAFIXEDDECIMAL' 

then the pattern match succeeds in the statement

        DCL ATTRIBUTE 

Concatenation has higher precedence than alternation.  Thus

        ATTRIBUTE = 'FIXED' !  'FLOAT' 'DECIMAL' 

matches FIXED of FLOATDECIMAL.  The order of evaluation  may
be altered by using parentheses.

        ATTRIBUTE = ('FIXED' !  'FLOAT') 'DECIMAL' .break

matches either FIXEDDECIMAL or FLOATDECIMAL.

E.  CONDITIONAL VALUE ASSIGNMENT 


It is possible to associate a variable with a component of a
pattern  such  that  if the pattern matches, the variable is
assigned  the  substring  matched  by  the  component.   The
operator  . is the conditional value assignment operator and
it is used in an expression of the form

        PATTERN . VARIABLE 

where the operator is separated from its operands by blanks.
For example

        BASE = ('HEX' !  'DEC') .  B1 

assigns to BASE a pattern that matches either  HEX  or  DEC.
If  BASE  is used successfully in a pattern match, the value
of B1 is set  to  the  substring  matched  by  BASE  .   The
operator  .  has the highest precedence of all the operators
and associates to the left.  Thus

        A.OR.B = A !  B . OUTPUT 

is equivalent to

        A.OR.B = A !  (B . OUTPUT) 

which assigns to A.OR.B a pattern that matches the value  of
A or B .  If B matches, the substring matched is printed.

There is also an operator $ for immediate  value  assignment
which   assigns  value  to  a  variable  if  the  associated
component of the pattern matches regardless of  whether  the
entire  pattern  matches.   Immediate  value  assignment  is
discussed in more detail in the reference manual.
PDP-10 Snobol4 User's Guide                          Page 21
CHAPTER 3


F.  FLOW OF CONTROL 


A SNOBOL4 program is a sequence of statements terminated  by
an  END  statement.   Statements  are  executed sequentially
unless otherwise specified in the program.  Labels and gotos
are provided to control the flow of the program.

A statement may begin with a label, permitting  transfer  to
the statement.  For example, the assignment statement

START TEXT = INPUT 

has the label START.  A label consists  of  a  letter  or  a
digit  followed  by  any  number of other characters up to a
blank.  Blanks separate  the  label  from  the  subject.   A
statement  with no label must begin with at least one blank.
The  END  statement  is  distinguished  by  the  label  END,
indicating the end of the program.

Transfer to a labelled statement is specified  in  the  goto
field  which  may  appear  at  the end of a statement and is
separated from the rest of the statement by  a  colon.   Two
types  of  transfers  can  be  specified  in the goto field:
conditional and unconditional.

A conditional transfer consists of a label  enclosed  within
parentheses  and  preceded  by  an  F  or S corresponding to
failure or sucess goto.  An example is the statement

        TEXT = INPUT :F(DONE) 

This statement causes a record to be read in and assigned as
the  value  of  TEXT.   If, however, there is no data in the
input file, i.e.  an end of  file  is  encountered,  no  new
value  is assigned to TEXT.  Then, because of the failure to
read, transfer is made to the statement labelled DONE.

A use of the success goto is illustrated  in  the  following
program which punches a copy of the input file.

LOOP   PUNCH  =  INPUT     :S(LOOP)
END

The first statement is repeatedly executed until the end  of
file  is encountered and then the program flows into the END
statement which causes the program to terminate.

The success or failure of a pattern match can also  be  used
to  control the flow of a program by conditional gotos.  For
example

        COLOR  =  'RED' ! 'GREEN' ! 'BLUE'
BRIGHT TEXT  COLOR  =     :S(BRIGHT)F(BLAND)
PDP-10 Snobol4 User's Guide                          Page 22
CHAPTER 3


BLAND

All occurrences of the  strings  RED,  GREEN  amd  BLUE  are
deleted  from  the value of TEXT before the pattern fails to
match.  Control then passes to the statement labelled BLAND.
Both  success and failure gotos can be specified in one goto
field, and may appear in either order.

For an example of an unconditional  transfer,  consider  the
following program that punches and lists a deck of cards.

LOOP   PUNCH   =   INPUT     :F(END)
            OUTPUT   =   PUNCH    :(LOOP)
END

The  goto  field  in  the  second  statement  specifies   an
unconditional transfer.

G.  INDIRECT REFERENCE 


Indirect referencing is indicated by the unary operator $  .
For example, if

        MONTH   =   'APRIL'

then $MONTH is equivalent to APRIL .  That is, the statement

        $MONTH = 'CRUEL' 

is equivalent to

        APRIL = 'CRUEL' 

The indirect reference operator can also  be  applied  to  a
parenthesized expression as in the statements

        WORD   =   "RUN"
        $(WORD ':')   =   $(WORD ':') + 1

which increment the value of RUN:  .

In general, the unary operator $ generates a  variable  that
is the value of its operand.  The expression

        $("A" !  "B") 

causes the program to terminate with  the  message  "ILLEGAL
DATA  TYPE"  because  the  value  of  the  operand of $ is a
pattern, not a string.  Indirect  reference  in  a  goto  is
demonstrated by

        N = N + 1 :($("PHASE" N)) 
PDP-10 Snobol4 User's Guide                          Page 23
CHAPTER 3


If, for example, the assignment statement sets N equal to 5,
then the transfer is to the statement labelled PHASE5.

H.  FUNCTIONS 


Many SNOBOL4 procedures are invoked by functions built  into
the  system  called  primitive  functions.   Operations that
occur frequently are implemented as primitive functions  for
efficiency.   Other  primitive  functions are used to invoke
more  complex  operations  that  are  fundamental   to   the
language,  affect  parameters  and  tables  internal  to the
system, and perform operations that could not be  programmed
in  source language by other means.  In addition, facilities
are available for a programmer  to  define  his  own  source
language functions.

    1.  PRIMITIVE FUNCTIONS 

Consider the  function  SIZE,  which  has  a  single  string
argument and returns as value an integer which is the length
(number of characters) of the string.  The statements

        APE   =   'SIMIAN'
        OUTPUT   =   SIZE(APE)

print the number 6 .

Arguments to all functions  are  passed  by  value,  and  an
arbitrarily  complex  exprssion may be used in the argument.
Thus the statements

        N   =   100
        OUTPUT   =   SIZE('PART' N + 4)

print the number 7 , because the value of  the  argument  is
the string PART104 .

The argument of SIZE is supposed to be a string.  Therefore,
a call of the form

        SIZE("APE" !  "MONKEY") 

causes the program to terminate with the diagnostic  message
"ILLEGAL  DATA  TYPE" because the value of the argument is a
pattern.

TRIM  is  another  function  that  performs   an   operation
frequently required.  TRIM(STRING) returns as value a string
which is equal to the argument with trailing blanks removed.
It is often used in a statement of the form

READ    TEXT = TRIM(INPUT)      :F(END) 
PDP-10 Snobol4 User's Guide                          Page 24
CHAPTER 3


which assigns as value to TEXT the string on the next  input
card,  trimmed  of  trailing blanks.  Notice that the use of
the variable INPUT in the argument causes a card to be read.

        REPLACE is  a  function  called  with  three  string
valued arguments.

        REPLACE(TEXT,CH1,CH2) 

returns as value a string which is equal to TEXT  with  each
occurrence  of  a character appearing in CH1 replaced by the
corresponding character in CH2.  For example the statements

        STATEMENT  =  'A(I,J)  =  A(I,J) + 3'
        OUTPUT   =   REPLACE(STATEMENT,'()','<>')

print the line

A<I,J> = A<I,J> + 3 

If the last two arguments of the function call do  not  have
the same length, the function fails.  Function failure, like
INPUT failure, can be used in a conditional transfer.

Another example of the  use  of  REPLACE  is  the  following
program  that produces a simple cryptographic encoding of an
input deck.

        INALPH   =   'ABCDEFGHIJLMNOPQRSTUVWXYZ'
        OUTALPH   =   'KLMNOPQRSTUVWXYZABCDEFGHIJ'
LOOP    PUNCH   =  
 REPLACE(INPUT,INALPH,OUTALPH)       :S(LOOP)
END

The iteration is terminated by INPUT failure.

There are also several functions  that  return  patterns  as
their values.  LEN is such a function.  LEN(INTEGER) returns
a pattern  that  that  matches  any  string  of  the  length
specified by the integer.

The following example punches the value of STR centered on a
card.
        BLANKS   =   '                                      
'
        BLANKS   LEN((80 - SIZE(STR)) / 2) . PAD
        PUNCH   =   PAD STR

If the size of STR is greater than 80, the argument  of  LEN
is  negative,  causing  error  termination  with the message
"NEGATIVE NUMBER IN ILLEGAL CONTEXT."

DUPL(S,N duplicates a string S.  The number of  duplications
is determined by N.  The value of
PDP-10 Snobol4 User's Guide                          Page 25
CHAPTER 3


      DUPL('.*',5) 

is '.*.*.*.*.*' .  If S is the NULL string  or  N  is  zero,
DUPL  returns  the NULL string as value.  DUPL fails if N is
negative.

DUMP(N) prints a dump of variable storage at the  time  DUMP
is  called if N is nonzero.  The dump is similar to the dump
provided  after  program  termination,   except   that   the
variables  are  not  alphabetized.   DUMP  returns  the NULL
string as value.  No dump is given if N is zero.

        The value of REMDR(N,M)  is  the  remainder  of  the
integer  division  N  / M.  The sign of the remainder is the
same as the sign of the dividend.  Thus the value of

        REMDR(-5,2) 

is -1, and the value of

        REMDR(5,-2) 

is 1.

    2.  PREDICATES 

A predicate is a function or operation that returns the NULL
string   as   value  if  a  given  condition  is  satisfied.
Otherwise it fails.

LE is an example of a predicate used for comparing integers.

        LE(N1,N2) 

returns the NULL string as value if N1 is  an  integer  less
than or equal to N2.  Thus

        PUNCH = LE(SIZE(TEXT),80) TEXT 

punches the string TEXT if its length is  not  greater  than
80.   The NULL string value of the predicate does not affect
the string that is punched.   If  the  predicate  fails,  no
assignment  is  made  to PUNCH, and no card is punched.  The
success of failure  of  a  predicate  can  be  used  with  a
conditional  goto  to  control  the  flow of a program.  For
example,

        N   =   0;   SUM   =   0
ADD     N   =   LT(N,50) N + 1    :F(DONE)
        SUM   =   SUM + N         :(ADD)
DONE    OUTPUT   =   SUM

sums the first 50 integers.  Iteration continues as long  as
N   is   less  than  50.   When  the  predicate  fails,  the
PDP-10 Snobol4 User's Guide                          Page 26
CHAPTER 3


conditional transfer to DONE is  performed  and  the  string
1275 is printed.  There are several predicates for comparing
strings.  For example,

        DIFFER(ST1,ST2) 

returns the NULL string  as  value  if  the  values  of  two
arguments are not identical.  Thus 

        OUPUT = DIFFER(FIRST,SECOND) FIRST SECOND 

concatenates the values of FIRST and SECOND if they are  not
the same, and then prints them.

For all functions, an omitted argument is assumed to be  the
NULL string.  Thus

        PUNCH = DIFFER(TEXT) TEXT 

punches the value of TEXT if it is not the NULL string.

LGT is a predicate that lexically compares two strings.

        LGT(ST1,ST2) 

succeeds if ST1 follows (is lexically greater than)  ST2  in
alphabetical order.  the statements

        OUTPUT   =   LGT(TEXT1,TEXT2) TEXT2     :S(SKIP)
        OUTPUT   =   TEXT1
        OUTPUT   =   TEXT2                      :(JUMP)
SKIP    OUTPUT   =   TEXT1
JUMP

print the values of TEXT1 and TEXT2 in alphabetical order.

    3.  DEFINED FUNCTIONS 

The  SNOBOL4  language  provides  the  programmer  with  the
capability to define functions in the source language.  This
feature facilitates the organization of a  program  and  may
improve its efficiency.

A  programmer  may  define  a  function  by  executing   the
primitive  function  DEFINE  to  specify  the function name,
formal arguments, local variables, and the  entry  point  of
the  function.  The entry point is the label of the first of
a set of SNOBOL4 statements constituting the  procedure  for
the function.

The first argument of DEFINE is a prototype  describing  the
form of the function call.  The second argument is the entry
point.  For example, execution of the statement
PDP-10 Snobol4 User's Guide                          Page 27
CHAPTER 3


        DEFINE('DELETE(STRING,CHAR)','D1') 

defines a  function  DELETE  having  two  formal  arguments,
STRING and CHAR, and entry point D1.  The statements

D1      STRING CHAR   =    :S(D1)
        DELETE   =   STRING     :(RETURN)

form a procedure that deletes all occurrences of  CHAR  from
the  value of STRING.  The statement assigning the resulting
value  to  the  variable  DELETE  illustrates  the   SNOBOL4
convention  for  returning  a  function value:  The function
name may be used as a variable in  the  function  procedure.
Its  value  on return from the procedure is the value of the
function call.  Return from a procedure is  accomplished  by
transfer to the system label RETURN.

If the second argument is omitted from the call  of  DEFINE,
the  entry point to the procedure is taken to be the same as
the function name.  For example

        DEFINE('DELETE(STRING,CHAR)') 

could have the procedure

DELETE   STRING CHAR   =   :S(DELETE)
                DELETE  =   STRING      :(RETURN)

A call of the  function  is  illustrated  in  the  following
statements

        MAGIC   =   'ABRACADABRA'
        OUTPUT   =   DELETE(MAGIC,'A')

which print BRCDBR.  Arguments are passed by value  and  may
be arbitrarily complex expressions.  Thus the statement

        TEXT = DELETE(TRIM(INPUT),' ')

deletes all blanks from the input string.

Functions can also fail under specified conditions.   As  an
example,  consider  the  following  version of DELETE, which
fails if STRING does not contain an occurrence of CHAR.

DELETE          STRING  CHAR   =        :F(FRETURN)
D2              STRING  CHAR   =        :S(D2)
                DELETE  =   STRING        :(RETURN)

The transfer to the system label FRETURN  indicates  failure
of the function call.  Consequently,

        PUNCH = DELETE(TRIM(INPUT),'*') 
PDP-10 Snobol4 User's Guide                          Page 28
CHAPTER 3


punches a card only if the input string contains an * .

Arguments to a function and the value returned  can  be  any
type  of  data  object.  Consider, for example, the function
MAXNO where MAXNO(P,N) returns a pattern that matches up  to
N adjacent strings matched by the pattern P.  That is, if

        PAT = MAXNO('A' !  'B' !  'C' ,2) 

then in the statement 

        'EBCDIC' PAT 'D' 

the pattern match succeeds with PAT matching the string BC.

MAXNO has the defining statement

        DEFINE('MAXNO(P,N)') 

and the procedure

MAXNO   N   =   GT(N,0) N - 1   :F(RETURN)
        MAXNO   =   NUL ! P MAXNO       :(MAXNO)

Consider the function REVERSE that reverses  a  string.   It
has the defining statement

        DEFINE('REVERSE(STRING)','R1') 

and the procedure

R1      ONECH   =   LEN(1) . CH
R2      STRING  ONECH   =               :F(RETURN)
        REVERSE   =   CH  REVERSE       :(R2)

There are two variables, ONECH and CH, used in the  function
definition  in  addition  to  the  function  name and formal
argument.  It is prudent to protect these variables so their
use  outside  the function is not affected when the function
is called.  This is accomplished by  declaring  them  to  be
local variables in the defining statement:

        DEFINE ('REVERSE(STRING)ONECH,CH','R1') 

When the function is called, the current values of the local
variables,  the  formal arguments, and the function name are
saved before the procedure is  entered.   These  values  are
restored  upon  return from the procedure.  This permits the
programmer considerable freedom in defining functions.   For
example,  a  function can be recursive, i.e.  include a call
of the function itself.  Consider the  binomial  coefficient
C(N,M) which can be defined by equations

        C(N,0) = 1
PDP-10 Snobol4 User's Guide                          Page 29
CHAPTER 3


        C(N,M) = N*C(N-1,M-1)/M    FOR M>0

Computational efficiency can be improved  by  employing  the
relation

        C(N,M) = C(N,N-M) 

for M> N/2.

The corresponding programmer-defined  function  consists  of
the defining statement          DEFINE('C(N,M') 

and the procedure

C       M  =  LT(N - M,M) N - M
        C  =  EQ(M,0) 1             :S(RETURN)
        C  =  N * C(N - 1,M - 1) / M   :(RETURN)

        COMB is an example of  another  recursively  defined
function.    COMB(STR,N)   lists   all   combinations  of  N
characters from the string STR.  The defining statement  and
procedure are

        DEFINE('COMB(STR,N,HEAD)CH') 

and

COMB    OUTPUT = EQ(N,0) HEAD   :S(RETURN)
C2      STR LE(N,SIZE(STR)) LEN(1) . CH =       :F(RETURN)
        COMB(STR,N - 1,HEAD CH)    :(C2)

then

        COMB('ABCD',3) 

prints

ABC
ABD
ACD
BCD

        Notice  that  COMB  is  defined  with  three  formal
arguments  but  only  two values are supplied in the initial
call.  The missing value is taken to be NULL.

I.      KEYWORDS 


Several parameters and  switches  internal  to  the  SNOBOL4
system  can  be accessed by means of keywords.  Keywords are
specified by prefixing an ampersand to certain  identifiers.
For  example, if the value of the keyword &DUMP is a nonzero
integer  when  a  program  terminates,  a  dump  of  natural
PDP-10 Snobol4 User's Guide                          Page 30
CHAPTER 3


variables is printed.  Thus the execution of the statement

        &DUMP = 1

indicates that a dump is to be produced.  &TRIM controls the
trimming  of  trailing  blanks.   If  the  value of &TRIM is
greater than zero, input records are trimmed.   The  default
value of &TRIM is zero.

&INPUT and &OUTPUT control input and output.  If  &INPUT  is
greater  than  zero,  automatic  input  is performed through
input  accociations.   If  &INPUT  is  zero,  however,  such
associations   are   ignored  and  automatic  input  ceases.
&OUTPUT controls automatic output in a similiar manner.  The
default value of &INPUT and &OUTPUT is 1.

J.  ARRAYS 


Arrays of variables can be created by  using  the  primitive
function  ARRAY.  The arguments of ARRAY describe the number
of dimensions, the bounds of each dimension, and the initial
value of each variable in the array.  Thus

        V = ARRAY(10,1.0) 

creates and assigns to V a  one  dimensional  array  of  ten
variables,  each  initialized  to  the  real value 1.0.  The
created variables can be referenced by  expressions  of  the
form V<I> where I = 1,...,10.  the statement

        N = ARRAY('3,5') 

creates a 2-dimensional array of variables

        N<1,1>   N<1,2>   N<1,3>   N<1,4>   N<1,5>

        N<2,1>     .        .        .        .

        N<3,1>     .        .        .      N<3,5>

the omission of the  second  argument  causes  each  of  the
variables  to  have  the  NULL string as initial value.  The
arguments in the call of ARRAY can be expressions.  Thus

        A = ARRAY(TRIM(INPUT)) 

creates an array with dimensionality that is data dependent.
An  array reference, A<I>, that is outside the bounds of the
array causes failure that can be  used  to  control  program
flow.  The statements

        I  = 1
        ST  =  ARRAY(TRIM(INPUT))
PDP-10 Snobol4 User's Guide                          Page 31
CHAPTER 3


MORE    ST<I>  =  INPUT                         :F(GO)
        I  =  I  +  1                           :(MORE)
GO

generate an array, ST, and assign  values  to  each  of  the
variables.  When all the variables in the array are assigned
values, or an end of file is encountered, the transfer to GO
is executed.

K.  PROGRAMMER-DEFINED DATA TYPES 

INTEGERS, REALS, STRINGS, PATTERNS, and ARRAYS are types  of
data  objects  that  are  built  into  the SNOBOL4 language.
Facilities  are  provided  in  the  language  to  permit   a
programmer   to   define   additional   data   types.   This
facilitates  representation  of   structural   relationships
inherent  in data.  For example, a simple linear linked list
is made up of nodes, each containing a  VALUE  field  and  a
LINK field.

The primitive function DATA can be used to define  the  data
type NODE and the two field functions, VALUE and LINK.

        DATA('NODE(VALUE,LINK)') 

The statement

        P = NODE('S',) 

creates a node with VALUE field S and the NULL string in the
LINK field.  The value of P is a data object with two fields
that can be  referenced  by  means  of  the  function  calls
VALUE(P)  and LINK(P).  The insertion of a node with value T
at the head of the list is accomplished by the statement

        P = NODE('T',P) 

The following statement deletes a node from the head of  the
list

        P = LINK(P) 

L.  PROGRAM EXAMPLE 

This  is  an  example  of   a   complete   SNOBOL4   program
illustrating  the  use of comment lines, continuation lines,
and the END statement.  The program reads in data cards that
follow the END statement.

************************************************************
*       EXAMPLE OF A FUNCTION THAT PRINTS ALL
*       PERMUTATIONS OF SIZE N FROM A GIVEN STRING.
************************************************************
PDP-10 Snobol4 User's Guide                          Page 32
CHAPTER 3


        DUMP    = 1
        DEFINE('PERM(STRING,N,HEAD)CH,USED')

        STRING  =  TRIM(INPUT)                  :F(ERROR)
        N  =  TRIM(INPUT)                       :F(ERROR)
        PERM(STRING,N)                          :(END)
PERM    OUTPUT  =  EQ(N,0)  HEAD                :S(RETURN)
PERMA   STRING  LEN(1)  .  CH  =                :F(RETURN)
        USED
.       =  PERM(STRING USED,N - 1,HEAD CH)  USED
 CH     :(PERMA)
END
ABCD
3


M.  TABLES 


A TABLE is similar to an ARRAY except that it is limited  to
one  dimension,  and  its  argument  is not restricted to an
INTEGER, but may be any value.  A TABLE may be thought of as
an ARRAY that permits associative references.

A TABLE is created by the TABLE function.  For example,

        T = TABLE() 

creates a TABLE and assigns it as the value of  T.   Entries
in  the  table T may subsequently be referred to in much the
same way as ARRAY references are made.  For example,

        T<'A'> = 3 

assigns the value 3 to the "Ath" element of T.

The referencing argument may be  any  value  with  any  data
type.   Simply  by referring to the element, the appropriate
table element is referenced.  If no such element exists, one
is created and given the NULL string as its initial value.

Tables cannot  be  copied  using  the  COPY  function.   The
function ITEM can be used for tables as well as for arrays.

Programmers are cautioned that  T<1>  and  T<'1'>  reference
different  elements of T.  Particular care must be used when
the argument is the value of an expression.

The TABLE function actually has two arguments, both of which
may  be  omitted  as  illustrated in the example above.  The
general form of the function is

        TABLE(N,M) 
PDP-10 Snobol4 User's Guide                          Page 33
CHAPTER 3


where N and M concern the size of the table.   N  determines
the  initial size of the table, indicating how many elements
it can contain.  M is  the  number  of  additional  elements
provided if more are required.  For example,

        TABLE(20,15) 

specifies a TABLE of 20 elements.  If more are required, the
table  size  is increased to 35.  If this is not sufficient,
the size is increased to 50, and so on.         The  default
values  for  N  and M are 10.  If either argument is omitted
(or zero), the corresponding default is used.  Efficient use
of  tables  is  obtained  by specifying values corresponding
approximately to the expected TABLE sizes.

        Conversion  between  tables  and   arrays   may   be
performed using the CONVERT function.  If T is a TABLE,

        A = CONVERT(T,'ARRAY') 

assigns to A an ARRAY corresponding to  the  TABLE  T.   The
PROTOTYPE  of A is 'N,2' where N is the number of items in T
that have nonnull values.  A<I,1> is a reference element  of
T and A<i,2> is the value of that element.  The order of the
items in A is unpredictable.  Only items with nonnull values
are  included.   Conversion  from  TABLE  to ARRAY data type
fails if there is no item with a nonnull value.

        A rectangular array with a second dimension that has
an  extent of two can be converted to a TABLE.  For example,
if R is an ARRAY with the PROTOTYPE '-3:3,2',

        B = CONVERT(R,'TABLE') 

creates a TABLE B of 7 items  corresponding  to  R<I,1>  and
with the values of these items being R<I,2> respectively.

        The value used for additional  items  (corresponding
to M in TABLE(N,M) is the default, 10.

        In  output,  trace   messages,   dumps   and   other
situations  where  data  type  representations are required,
tables appear as TABLE(N,M).  For example, the statement

        OUTPUT = B 

results in the printout

TABLE(7,10) 
PDP-10 Snobol4 User's Guide                          Page 34
CHAPTER 4


INPUT AND OUTPUT 



        INPUT and OUTPUT  are  accomplished  by  associating
variables  with  devices  or  filenames.   In  the case of a
variable associated in  the  OUTPUT  sense,  each  time  the
variable is assigned a value, a copy of the value is put out
onto the associated device  or  file.   In  the  case  of  a
variable  associated in the INPUT sense, each time the value
of the variable is used,  a  new  value  is  read  from  the
associated  device  or file and becomes the new value of the
variable.  Thus  input  and  output  go  on  during  program
execution  without  any explicit I/O statements, as a result
of I/O associations.  Variables having standard associations
are described in the following sections.

A.  PRINTED OUTPUT



        The variable OUTPUT is associated with a  device  or
file  which  is  selected  at  run  time  by  the  user, for
instance, the line printer.  Consequently,  whenever  OUTPUT
is assigned a value, printout is generated.  For example,

                OUTPUT = 'THE SELECTED VALUES ARE'

produces the output

THE SELECTED VALUES ARE

Output may also result from value  assignment  specified  in
patterns.  For example,

                PEXP = BAL . EXP1 . OUTPUT '+' BAL . EXP2 .
OUTPUT
                     .
                     .
                     .
                EXP PEXP

prints the two terms in EXP, and  assigns  their  values  to
EXP1  and  EXP2.   This  type  of output is often useful for
diagnostic  purposes,  and  does  not  affect  the   pattern
matching or the assignments made to EXP1 and EXP2.

        Ordinary printout  is  printed  132  characters  per
line,  with as many lines as necessary being generated.  The
NULL string is treated as a blank character and a blank line
is  printed  for it.  (On the PDP-10 this is actually output
as  a  CARRIAGE  RETURN/LINE  FEED).   Strings  are  usually
assigned  to  output  variables.   Integers and real numbers
assigned to an output variable are  automatically  converted
PDP-10 Snobol4 User's Guide                          Page 35
CHAPTER 4


to  strings.  If an array is assigned to an output variable,
the printed output is ARRAY with the prototype of the  array
enclosed in parentheses.  For example, the statements

                MATRIX  =  ARRAY('-2:2,-3:3',0)
                OUTPUT  =  MATRIX

print

ARRAY('-2:2,-3:3') 

If the prototype is longer than twenty characters, only  the
string  ARRAY  is printed.  If an object with any other data
type  is  assigned  to  an  output  variable,   the   formal
identification of its data type is printed.  For example,

     OUTPUT = LEN(7)

prints

PATTERN


B.  PUNCHED OUTPUT



        The variable PUNCH is associated with device  number
7.  Consequently, whenever PUNCH is assigned a value, a line
is punched on the card punch.  For example,

                PUNCH = 0 

punches a card with a zero in column one.

        All the remarks about print output  apply  to  punch
output.


C.  INPUT

        The variable INPUT is associated with  the  standard
input  data  stream.  Whenever the value of INPUT is used, a
card image is read from the input stream and becomes the new
value of INPUT.  For example,

                OUTPUT = INPUT

reads a card image and prints it.  Similarly,

                TRIM(INPUT) BAL .  EXP 

reads a card image and matches for a balanced  string.   All
eighty columns of the card images are read, but the value of
PDP-10 Snobol4 User's Guide                          Page 36
CHAPTER 4


INPUT is generally trimmed of trailing blanks.

        Since each use of INPUT reads a card image, previous
values  of  INPUT are lost unless they are assigned to other
variables.

        If an end of file is encountered  when  a  value  of
INPUT  is  requested,  failure results.  This failure can be
used to detect the end of a data file.  For example,

        I   =   1
READ    DATA<I>   =   INPUT             :F(OUT)
        I   =   I + 1                   :(READ)
OUT

reads card images into the array DATA until the  input  data
stream  is  exhausted  (or  I  exceeds  the  range of data).
Control is then transferred to OUT.


D.  THE I/O SYSTEM 



        All  input/output  is  handled  by  FORTRAN  IV  I/O
routines.   That  is, SNOBOL4 I/O is done by the same system
that does I/O for FORTRAN IV object programs.  Consequently,
the  conventions  and I/O concepts specified for the FORTRAN
IV language also apply to SNOBOL4.  In addition, the version
of  the  language  described  here operates under the PDP-10
Time-Sharing  Systems,  either  10/40  or  10/50.    It   is
necessary  to understand both the fundamentals of FORTRAN IV
I/O and the PDP-10 standard CUSP to user interface in  order
to do SNOBOL4 I/O effectively.

        in  FORTRAN,  devices  and  files  have   associated
numbers.   These  numbers are referred to in source language
programs and are associated with specific devices and  files
at  run time.  These numbers correspond to an index into the
FORTRAN operating system's device table,  called  DEVTB.   A
copy  of  this table is listed in Appendix B.  Filenames for
disk and DECtape files  are  established  for  the  standard
INPUT  and  OUTPUT  streams  by  the  user  at startup time.
Filenames can also be established via the  IFILE  and  OFILE
primitive functions as described later.

        The  FORTRAN  I/O  used  in  SNOBOL4  only   handles
sequential  data  sets.   In  particular,  it  cannot handle
random accessing of files.

        SNOBOL on the PDP-10 handles multiple segment source
files for input.  This allows the user to segment his coding
into short routines and to use common routines  residing  on
the system area of the disk.
PDP-10 Snobol4 User's Guide                          Page 37
CHAPTER 4


        Thus, for example, a user may specify the  following
command string 

LPT:_SYS:COMMON,DSK:ONE,TWO,THREE 

which would place  the  output  listing  file  on  the  line
printer  and  compile  the file named COMMON (located on the
system area  of  the  disk)  followed  by  the  files  named
ONE,TWO,THREE located on the user's disk area.

        If after this command string has been exhausted  and
no  END statement has been seen, the system will then accept
further input from the user's terminal.   To  let  the  user
know additional input is expected from him, the message

WAITING FOR TTY INPUT

is printed on this terminal.  This syntax allows the user to
specify  at  runtime  which  associations he desires for the
standard  input  and  output  streams.   This  specification
determines  where  the results of INPUT are to come from and
where the results of OUTPUT are to go.

Additional examples are

     LPT:_CDR:
     TTY:_CDR:
     LPT:_DSK:PROG1
     TTY:_TTY:

In general any device capable of output can be specified  on
the  left  side of the arrow and any device capable of input
can be specified to the  right  of  the  arrow.   These  are
summarized below.

GENERAL FORMAT 

        LISTING-DEVICE:FILENAME.EXT_SOURCE-DEVICE:FILENAME.EX
T, ...  

        (1)     LISTING-DEVICE:  The  device  on  which  the
OUTPUT          produced by SNOBOL is to be written.

                MTAn:  Magnetic Tape
                DTAn:  DEC Tape
                DSK:   Disk
                PTP:   Paper Tape Punch
                LPT:   Line Printer
                TTY:   Teletype
                CDP:   Card Punch

         (1)    SOURCE-DEVICE:  The device  from  which  the
source program          INPUT to compilation is to be read.
PDP-10 Snobol4 User's Guide                          Page 38
CHAPTER 4


                MTAn:  Magnetic Tape
                DTAn:  DEC Tape
                DSK:   Disk
                TTY:   Teletype
                CDR:   Card Reader
                PTR:   Paper Tape Reader

FILENAME.EXT (DSK:  and DTAn:only) The filename and filename
extension               of the listing and the source files.

                if .EXT is omitted, .LST is assumed for  the
listing                 file  and  .SNO  is  assumed for the
source file.

(1) if a device is not specified, "DSK:" is always assumed.


E.  OUTPUT ASSOCIAITONS 



The  variables  OUTPUT  AND  PUNCH  have  predefined  output
associations.   Programmer-defined  associations may be made
using the function OUTPUT.  The form of the function is

        OUTPUT(NAME,NUMBER,FORMAT) 

OUTPUT associates the name with the device reference  number
according  to  the  given  format.   The  format is a string
specifying a FORTRAN IV FORMAT.   The  following  statements
correspond  to the associations for the variables OUTPUT and
PUNCH:

        OUTPUT('OUTPUT',6,'(1X,27A5)')
        OUTPUT('PUNCH',7,'(16A5)')

Using the OUTPUT function, any variable  can  be  associated
with any device reference number.  For example,

        PRFORM  =  '(1X,27A5)'
        TEST  =  ARRAY('8,8')
        OUTPUT(.TEST<1,1>,6,PRFORM)
        OUTPUT(.TEST<8,8>,6,PRFORM)

associate the array elements TEST<1,1>  and  TEST<8,8>  with
the  ordinary print file and with the standard print format.
As a result,  whenever  either  TEST<1,1>  or  TEST<8,8>  is
assigned a value, the new value is printed.

Device reference numbers are not restricted to 5 and 6,  but
can range from 1 through 37 .  Associations can be made with
reference numbers other than the  standard  ones.   In  this
case,  just set up the appropriate OUTPUT statement, perhaps
in conjunction with the  IFILE  primitive  function  if  the
PDP-10 Snobol4 User's Guide                          Page 39
CHAPTER 4


device is file oriented.

Formats  used  in  OUTPUT  association  must   specify   the
conversion   of   at  least  one  element  by  A-conversion.
(Normally nA5-conversion is used.)  Integers  are  converted
into strings and I conversion must not be used.  In addition
to A conversion, quoted literals, X , H , and  T  conversion
may  be  specified.   Carriage  control must be provided for
printing;  otherwise the first character of  the  string  is
consumed for this purpose.  Consider

        OUTPUT('TITLE',6,'(1H1,27A5/(1X,27A5))') 

When a value is assigned to TITLE, a page is ejected and the
value  titles  the next page of output.  The use of literals
is illustrated by

        OUTPUT('SUM',6,"(' SUM='25A5/(1X,27A5))") 

which includes  identifying  information  with  the  format.
Subsequently,

        SUM = 300 

causes the printout

SUM=300 

The predefined associations can be changed.  Thus,

                OUTPUT('OUTPUT',6,'(1X,24A5)') 

shortens the line length for OUTPUT to 120 characters.


F.  INPUT ASSOCIATIONS



        Programmer-defined input associations  can  be  made
using the function INPUT.  The form of this function is

                INPUT(NAME,NUMBER,LENGTH) 

INPUT associates the name with the device reference  number,
and specifies that the resulting string is to have the given
length.  (Notice in particular that no FORMAT is specified.)
INPUT has a predefined association equivalent to

                INPUT('INPUT',5,80)

The specified length has some special  properties.   If  the
length  is less than the record size on the file being read,
the last part of the record is lost.  Hence,
PDP-10 Snobol4 User's Guide                          Page 40
CHAPTER 4


                INPUT('INPUT',5,72)

changes the association for INPUT so that  only  72  columns
are  read.   Columns  73  through  80  are  lost if data set
reference number 5 is associated with ordinary  card  INPUT.
A  length  longer  than the record is usually recommended to
avoid any problems with truncation.  Even  though  a  longer
length is asked for, the actual string length will always be
used.

For  example,  if  the  user  specifies  a  length  of   130
characters  in  the  INPUT  function,  and  a  string  of  5
characters is read, the system will assign the string length
to be 5 and not 130.


G.  OTHER I/O FUNCTIONS 



        Several other functions are provided for I/O-related
operations.   All  of these functions return the NULL string
as value.

        1.  DETACH 

DETACH(NAME) removes any INPUT and OUTPUT association  which
the name may have.  For example,

        DETACH('OUTPUT') 

terminates normal print output.


        2.  ENDFILE 

ENDFILE(NUMBER) writes an end of file on (closes)  the  file
specified by the number.  For example,

                ENDFILE(20)

closes the file associated with device reference number 20.


        3.  REWIND 

REWIND(NUMBER) repositions  the  file  associated  with  the
number to the beginning.  For example,

        REWIND(10)

rewinds the file associated with device reference number 10.
Subsequently, reference to 10 refers to the beginning of the
file  specified.   REWIND  will  cause  any  IFILE  function
PDP-10 Snobol4 User's Guide                          Page 41
CHAPTER 4


associated with this file to be cancelled.

        4.  BACKSPACE 

BACKSPACE(NUMBER)  backspaces  one  record   on   the   file
associated with the number.

        5.  IFILE 

IFILE(NUMBER,FILENAME)  allows  the  SNOBOL  programmer   to
select  the  name of INPUT disk or DECtape files at runtime.
This function is a link to the FORTRAN IFILE subroutine.

This function will signal a failure return if the file  does
not exist on the given device.

For example,

        IFILE(20,'SURVEY.OMA')

        FILENAME = 'SNIP.SNO'
        IFILE(25,FILENAME)

        INPUT('ACCEPT',2,80)
        IFILE(1,TRIM(ACCEPT))

are all valid uses of IFILE

        6.  OFILE 

OFILE(NUMBER,FILENAME)  allows  the  SNOBOL  programmer   to
select  the name of OUTPUT disk or DECtape files at runtime.
This function is a link to the FORTRAN OFILE subroutine.

This function will signal  a  failure  return  if  the  file
cannot be entered on the given device.

        I = I + 1
        OUTPUT.NAME = SEQ '.' I
        OFILE(22,OUTPUT.NAME)

        OFILE(FINDEVICE('DTA0'),'THISIS.IT')

Are all valid examples of the use of OFILE.

        7.  TTCALL INTERFACE 

The PDP-10  time  sharing  system  has  a  special  teletype
interface  designed  to  allow  character  at  a time I/O as
opposed to line at a time I/O.

To take advantage of this feature, any I/O to unit number 99
will be directed to or from the user's teletype.
PDP-10 Snobol4 User's Guide                          Page 42
CHAPTER 4


For example,

        INPUT('CHARIN',99,1)
        OUTPUT('TTYOUT',99)

Note that only one character is input  each  time  an  INPUT
association is referenced.

An  entire  string  will  be  output  each  time  an  OUTPUT
association is referenced.  A free CARRIAGE-RETURN LINE FEED
will not be supplied, however.

Since on input, control characters can now be referenced,  a
means  has been provided via the ASCII primitive function to
handle this case.

        8.  ASCII 

ASCII(NUMBER) treats 'NUMBER' as  octal  and  generates  one
equivalent  ASCII  character.  This mechanism is provided to
allow referencing of control characters.

For example,

        CARRIAGE.RETURN.LINE.FEED = ASCII(15) ASCII(12) 

Octal 15 is the CARRIAGE RETURN character and  octal  12  is
the   LINE   FEED  character.   In  the  above  example  the
concatenation of the two resulting characters is assigned to
the variable name CARRIAGE.RETURN.LINE.FEED for later use.

        9.  TTY 'SWITCHES' 

Several switches have been defined which allow the  user  to
specify  options  at  runtime without modifying his program.
These switches are entered by the "/" character followed  by
a single letter.  They are defined as follows:

/D is equivalent to &DUMP = 1, and causes a dump of variable
storage at program termination.

/U is equivalent to -UNLIST, and suppresses printout of  the
source program listing.

/I for each occurrence of this switch additional I/O  buffer
space  for  one  more  disk  file  is allocated.  The system
currently allows enough buffering for six simultaneous  disk
files.   If  this  number  is exceeded, the I switch must be
used enough times to  increase  the  buffering  area  by  an
appropriate amount.
PDP-10 Snobol4 User's Guide                          Page 43
CHAPTER 5


STRUCTURE OF A SNOBOL4 RUN 



A SNOBOL4 run consists of three distinguishable parts:



1)  COMPILATION,
2)  EXECUTION, AND
3)  TERMINATION.

A.  COMPILATION 


        During   compilation,   the   SNOBOL4   system    is
initialized  and  the  source  program  is  compiled into an
intermediate  object   code   in   a   form   suitable   for
interpretation  during  program execution.  Compilation uses
the same processes as conversion of a string to object  code
using  the CODE function.  Additional processes are involved
in the reading of lines to be compiled from the  input  data
set, printing of a source listing on an output data set, and
noting errors in the source program.

        1.  SOURCE PROGRAM INPUT 

        Input to the compiler comes from a device associated
with  unit  reference number 5.  The actual source device is
specified by the user at run time by  using  the  relatively
standard  PDP-10  command  string  syntax.   If no device is
specified, DSK is assumed.  In  this  case  the  user  would
specify  a  filename.  Only 72 characters per line are read,
so that columns 73-80 of the card image input  may  be  used
for  sequential  numbering.   The compiler continues to read
until it encounters the END statement.  If an end of file is
encountered  before the END statement is found, the compiler
will read from the next file specified by the user.   If  no
additional  files  are specified, control will revert to the
user's terminal so he can type additional statements.  If no
further  input  is  desired,  the user can type END<CARRIAGE
RETURN> to terminate the compilation phase.

        2.  SOURCE LISTING 

        The listing of the program with sequential statement
numbers  goes  on  the  standard print output.  When the END
statement is encountered, the compilation process stops.   A
listing  of  the  compilation  and  placement  of  statement
numbers can be controlled by control lines.  A minus sign at
the  beginning of a line identifies a control line.  Program
listing is suppressed by the control line.

-UNLIST 
PDP-10 Snobol4 User's Guide                          Page 44
CHAPTER 5


Program listing is restored by the control line

-LIST 

     The normal positioning of statement numbers is  at  the
left   side   of  the  source  listing.   Statement  numbers
optionally may be placed at the right side of  the  listing.
The control line

-LIST LEFT 

changes statement numbering to the left.  Right  positioning
of the statement numbers is restored by

-LIST RIGHT 

or simply

-LIST 

        Blanks may appear between the minus sign and LIST or
UNLIST.  One or more blanks must appear between the LIST and
the LEFT or RIGHT.  Any characters other than LEFT following
blanks  on  the  LIST  control line cause the same action as
RIGHT.  An erroneous control line is ignored.

-EJECT 

causes a page eject to occur in the compilation listing when
encountered.

        3.  ERRORS DETECTED DURING COMPILATION 

        Certain kinds of errors in the  source  program  are
detected during compilation.  When an error is detected in a
statement, compilation of that statement is  terminated  and
an  error message is printed below the statement, describing
the nature of  the  error.   A  list  of  compilation  error
messages  is given below.  A marker pointing to the vicinity
of the error is also printed.  This marker may  be  somewhat
before  or  after  the error, depending on the nature of the
error.  Since compilation of a statement stops when an error
is  encountered, only the first error in any on statement is
detected.   Compilation  continues  in  spite  of  erroneous
statements.    However,   if   more   than  fifty  erroneous
statements are  found,  error  termination  occurs  and  the
program is not executed.

B.  EXECUTION 

        Execution of the compiled object  code  begins  when
compilation  is  complete.   Ordinarily,  program  execution
begins with the first statement  of  the  program.   Program
execution  may  be  started  at  any  labelled  statement by
PDP-10 Snobol4 User's Guide                          Page 45
CHAPTER 5


specifying that label in the END statement.   The  label  of
the first statement to be executed is placed in the position
of the subject.  For example,

END     INIT 

causes  program  execution  to  begin  with  the   statement
labelled INIT.

        Data read from the standard input source beings with
the first line after the END statement.  Data printed during
execution follows the source listing.


C.  TERMINATION 

        Upon termination, a statistics summary is printed to
provide  timing  information  and  counts of certain program
operations.   If  the  keyword  &DUMP  is  on   at   program
termination,  a  dump  of  natural variables and unprotected
keywords is also  provided.   Only  natural  variables  with
nonnull  values are included.  If the value of a variable is
not a string, the same representation of the value is  given
as would be given if the value were printed as the result of
an output association.

        There are four kinds of termination:

        1)  normal,
        2)  error,
        3)  intervention, and
        4)  catastrophic.

        1.  Normal Termination

        Normal termination occurs when the program transfers
to  END  or flows into the END statement.  The number of the
last statement executed and the function level are  printed.

        2.  Error Termination

        Error termination occurs in case  of  a  programming
error  or internal condition sufficiently serious to prevent
continued  execution.   The  statement   number   in   which
execution terminated and the function level are printed.  An
error  message  is  printed  indicating  the  cause  of  the
termination.   Dumps  and statistics are then printed as for
normal termination.  The error messages are as follows:

             THE CONDITIONALLY FATAL ERRORS ARE:

        1.   ILLEGAL DATA TYPE
        2.   ERROR IN ARITHMETIC OPERATION
        3.   ERRONEOUS ARRAY OR TABLE REFERENCE
PDP-10 Snobol4 User's Guide                          Page 46
CHAPTER 5


        4.   NULL STRING IN ILLEGAL CONTEXT
        5.   UNDEFINED FUNCTION OR OPERATION
        6.   ERRONEOUS PROTOTYPE
        7.   UNKNOWN KEYWORD
        8.   VARIABLE NOT PRESENT WHERE REQUIRED
        9.   ENTRY POINT OF FUNCTION NOT LABEL
        10.  ILLEGAL ARGUMENT TO PRIMITIVE FUNCTION
        11.  READING ERROR
        12.  ILLEGAL I/O UNIT
        13.  LIMIT ON DEFINED DATA TYPES EXCEEDED
        14.  NEGATIVE NUMBER IN ILLEGAL CONTEXT
        15.  STRING OVERFLOW
        16.  OVERFLOW DURING PATTERN MATCHING

             THE UNCONDITIONALLY FATAL ERRORS ARE:

        17.  ERROR IN SNOBOL4 SYSTEM
        18.  RETURN FROM LEVEL ZERO
        19.  FAILURE DURING GOTO EVALUATION
        20.  INSUFFICIENT STORAGE TO CONTINUE
        21.  STACK OVERFLOW
        22.  LIMIT ON STATEMENT EXECUTION EXCEEDED
        23.  OBJECT EXCEEDS SIZE LIMIT
        24.  UNDEFINED OR ERRONEOUS GOTO
        25.  INCORRECT NUMBER OF ARGUMENTS
        26.  LIMIT ON COMPILATION ERRORS EXCEEDED
        27.  ERRONEOUS END STATEMENT
        28.  EXECUTION OF STATEMENT WITH COMPILATION ERROR
        29.  IO BUFFER SPACE EXHAUSTED, RESTART AND USE
           THE I SWITCH
        30.  INSUFFICIENT STORAGE, NOT ENOUGH CORE FOR
           STARTING

         When program execution is terminated by  an  error,
the     error  number  as  well as the descriptive phrase is
printed on      the program listing.


        3.  INTERVENTION TERMINATION 

        On the PDP-10 intervention termination can be forced
by  the  user  With  the  REENTER  command.   When  the user
suspects that his program is looping he can get  control  by
typing  two  control  C's  to  get  into monitor mode again.
Should be  desire  to  resume  processing  the  CONTINUE  or
CCONTINUE  commands  can  be  used  to  continue  where  the
operation was interrupted.  If, however, the user desired to
terminate the run in a somewhat graceful fashion, he can use
the REENTER command.  This will automatically cause the DUMP
keyword  to  be  set  so  the  user  will get as much useful
information as possible.  The  message  "CUT  BY  SYSTEM  IN
STATEMENT  N  AT  LEVEL  M"  is  printed  and  the dumps and
statistics are then printed as for normal termination.
PDP-10 Snobol4 User's Guide                          Page 47
CHAPTER 5


There are a number of situations on  the  PDP-10  where  the
FORTRAN  operating  system  will  detect  an error, print an
error message and return you to monitor mode.  The user  has
no  recourse  but to correct the error condition and restart
his program.

        4.  CATASTROPHIC TERMINATION 

        Catastrophic  termination  occurs  when  system   or
machine  malfunction  causes  a  situation  so  serious that
intervention termination is impossible.  In the  case  of  a
catastrophic  termination, there may be no indication of the
source or cause of the termination.  Print and punch  output
may  be incomplete or lacking altogether..;appendix a edited
9-5-70 lp wade
PDP-10 Snobol4 User's Guide                          Page 48
APPENDIX A


                 SYSTEM PROGRAMMER'S NOTES

1.  A fixed amount of space is reserved for  the  user's  IO
buffers.   The  buffers  are set up at run time by FORSE and
their size is variable depending upon device.  The user  can
increase  this  amount with the "I" switch.  Each occurrence
of this switch allows space for double  buffering  one  more
device.

The global variable NUMIOB (NUMber of IO  Buffers)  controls
the buffering space.  It is initially set to four to provide
space for four devices in addition to the standard input and
output devices.

If your users tend to use more devices change NUMIOB  either
with DDT or with the I switch before putting SNOBOL on SYS.

2.  The internal design of SNOBOL is such that key constants
are  destroyed  upon  program  execution.   This  creates  a
problem when the user tries  to  execute  many  programs  in
succession or tries to stop and restart a program.  For this
reason a file called SNOBOL.INI  is  read  in  each  time  a
program  is  compiled  in  order  to  reset these constants.
SNOBOL looks for this file on SYS so be sure to put it there
when  putting  on  SNOBOL.SHR  and SNOBOL.LOW.  For non disk
systems the user should assign the DECtape drive  containing
SNOBOL.INI  to  SYS.   This  file  is  created using the "C"
switch as described below.

The C switch is intended for use by the system's  programmer
when  SNOBOL  is  first  put  on the system.  SNOBOL has the
property of destroying key constants during a  run,  and  in
order   to   allow   restarts   these   constants   must  be
reinitialized prior to every run.

The intended procedure is to LOGIN,  run  SNOBOL,  and  type
"/C".   This  will  write  SNOBOL.INI  on  DSK:.   Then  PIP
SNOBOL.* to SYS:.  Hereafter, any user running  SNOBOL  will
always   access  this  file  for  his  initialization.   See
SNOBOL.OPR on the system tape for a better description.


3.  Since IO is done through FORSE you should  be  aware  of
some of the limitations which result.

At execution time all strings are read via the STREAD  macro
which  executes  the  FORSE  IN.  UUO with a FORMAT of 16A5.
This means only 80 characters are read  and  longer  strings
are  truncated.  To read in a long string it is necessary to
concatenate the portions of the input.

FORSE will strip off all CR and LF characters on  input  and
append them on output.
PDP-10 Snobol4 User's Guide                          Page 49
APPENDIX A


When outputting strings at execution  time,  an  attempt  is
made to not merely truncate the string to 132 characters but
to output the string in its entirety.  The string is  placed
in  a  previously zeroed buffer of 27 words and enough DATA.
UUOs are executed to output the characters in the buffer  If
more  words  remain,  the  internal  buffer is again zeroed,
filled and output.  After each output, a CR and LF  will  be
added by FORSE.

At compilation time all input is read with a FORMAT of  16A5
to limit the source to card image input.

All of the magtape operations are also done by FORSE such as
REWIND  and  BACKSPACE.   Any  problems encountered here are
likely in FORSE.

4.  Adding new functions is fairly easy.  I suggest  looking
at  the  common  functions of SIZE or OFILE and pattern your
additions after these.  Keywords will be added in  much  the
same way.

5.  Each installation may  wish  to  change  the  so  called
attribution  printed  each  time  a run is started.  This is
actually a FORMAT statement at the label SOURCF in the  file
named  COMMON,  which  typically  prints  "DIGITAL EQUIPMENT
CORP.  PDP-10".

6.  I suggest you stick with the loading procedure noted  in
SNOBOL.OPR.   This  leaves  DDT  at  the very end of the low
segment thereby taking a simple patch to reclaim  the  space
in the production version but offering the benefit of having
DDT around for quick fixes.

7.  A few edits were made to the FORTRAN operating system in
order to handle the SNOBOL interface.

    a.  The RESET.  UUO executes a CALLI 0 which  cannot  be
tolerated  since  program  execution  has begun when this is
called.

    b.  The RESET.UUO releases all channels 0-17.  A  change
was  made  to  release  only 0-16 because channel 17 is kept
open for the CCL feature.

    c.  The CHINN routine which  does  character  input  was
modified  to  not  change  characters  less  than  24  octal
(control characters) to blanks.   This  was  primarily  done
because of TAB being converted to a single blank character.

    d.  The  ALPHO  routine  was  modified  to  not  convert
control characters to blanks, again primarily for TAB.

8.  The command scanner in EXEC  accepts  project-programmer
numbers  and  passes  them  to  a  modified  IFILE  routine.
PDP-10 Snobol4 User's Guide                          Page 50
APPENDIX A


Consequently, users can specify PPNS, i.e.  FOO_FOO[30,112].

9.  Dynamic core expansion is done  in  two  parts,  and  is
always associated with the garbage collection routine.

The first part is invoked if the garbage collector fails  to
find enough free storage.  In this case we attempt to get 2K
more, or 1K if  that  is  all  that  remains.   If  core  is
exhausted  the  program  is  terminated  with an appropriate
error message.

The second part is invoked  on  every  fifth  entry  to  the
garbage   collector.   On  these  occasions  a  2K  (or  1K)
preexpansion is performed in order  to  prevent  reaching  a
state  where  just enough core is obtained and an inordinate
number of collections is  required.   This  preexpansion  is
only performed as long as the free storage area is less than
15K.

At proper termination the amount of core used is printed  as
a  part  of  the  "STATISTICS"  printout.   Before giving up
control, the program shrinks back to the  original  starting
size.

10.  As a means of getting more information from the  system
i added the "V" switch which will cause the number of string
lookups to be printed as part of  the  statistics  printout.
This  number  is  really  comparable to the number of symbol
table look- ups.  Each time the VARID  macro  is  called  to
hash  code a string, it increments a count.  The printing of
this count is controlled by the global VARPRT which in  turn
is controlled by the "V" switch.

If you desire this printout to always be  included  in  your
user's printout, set VARPRT non zero with DDT before putting
SNOBOL on the system.


                          PDP-10 SYNTAX TABLE LAYOUTS


GENERAL FORM

     XXXTAB:

          1     0

          3     2

          5     4

          7     6

         11    10
PDP-10 Snobol4 User's Guide                          Page 51
APPENDIX A


         13    12

          .     .


        177   176

THERE ARE 64 DECIMAL WORDS  IN EACH SYNTAX TABLE,
WITH ONE HALFWORD ENTRY FOR EACH CHARACTER.

TYPICAL HALFWORD ENTRY

     2 free bits
     1 bit for ERROR
     1 bit for CONTIN
     1 bit for STOPSH
     1 bit for STOP
     6 bits for SYNTAB index
     6 bits for PUTTAB index


SYNTAB is a table of 18 bit addresses  which  point  to  the
next  syntax  table  to search through.  The index into this
table is stored as opposed to the actual address in order to
make the tables compact.

PUTTAB is a table containing either  constants  or  function
addresses  (possibly 18 bits).  The index into this table is
stored as opposed to the actual value in order to  make  the
tables compact.  The six bit size was chosen by counting the
number of possible entries.

There are less that 32 separate syntax tables so  five  bits
is  sufficient  for the index.  However, six bits was chosen
for readability.

The particular entry is retrieved by the STREAM macro (which
calls  the  STREEM  subroutine)  by  picking  up  successive
characters,  dividing  the  ASCII  value  by  two  observing
whether   the  result  is  odd  or  even  and  indexing  the
appropriate table half.

The GEN macro generates the tables.  Care must be  taken  if
these  tables  are changed.  The appearance of the arguments
is opposite of what  the  core  image  will  generate.   For
example,

                GEN     102, 103, A, B 

will be the equivalent of saying

                XWD B, A 

I felt it was easier to read the syntax table source  coding
PDP-10 Snobol4 User's Guide                          Page 52
APPENDIX A


by doing it this way..;appendix b edited 9-5-70 lp wade
PDP-10 Snobol4 User's Guide                          Page 53
APPENDIX B


                 DEVICE NUMBER ASSIGNMENTS

* THE FOLLOWING ARE THE DEVICE DEFINITIONS AS USED BY SNOBOL
*
* THIS PROGRAM CAN BE ASSEMBLED BEFORE YOUR PROGRAM
* TO PROVIDE A FUNCTION CALLED 'FINDEVICE' WHICH WILL
* ALLOW YOU MORE FLEXIBILTY IN HANDLING I/O.
*
* FOR EXAMPLE, IF THIS PROGRAM IS ON SYS:FIND.SNO
* YOU WOULD TYPE
*
* .R SNOBOL
* *FOO_SYS:FIND,YOURS.SNO
*
        DEVTB = TABLE(40)
        DEVTB<'DSK'> = 1
        DEVTB<'TTY'> = 2
        DEVTB<'PTR'> = 3
        DEVTB<'PTP'> = 4
        DEVTB<'DSK10'> = 5
        DEVTB<'DSK11'> = 6
        DEVTB<'CDP'> = 7
        DEVTB<'CDR'> = 8
        DEVTB<'LPT'> = 9
        DEVTB<'DTA0'> = 10
        DEVTB<'DTA1'> = 11
        DEVTB<'DTA2'> = 12
        DEVTB<'DTA3'> = 13
        DEVTB<'DTA4'> = 14
        DEVTB<'DTA5'> = 15
        DEVTB<'DTA6'> = 16
        DEVTB<'DTA7'> = 17
        DEVTB<'PLT'> = 18
        DEVTB<'FORTR'> = 19
        DEVTB<'DSK0'> = 20
        DEVTB<'DSK1'> = 21
        DEVTB<'DSK2'> = 22
        DEVTB<'DSK3'> = 23
        DEVTB<'DSK4'> = 24
        DEVTB<'DSK5'> = 25
        DEVTB<'DSK6'> = 26
        DEVTB<'DSK7'> = 27
        DEVTB<'DSK8'> = 28
        DEVTB<'DSK9'> = 29
        DEVTB<'MTA0'> = 30
        DEVTB<'MTA1'> = 31
        DEVTB<'MTA2'> = 32
        DEVTB<'MTA3'> = 33
        DEVTB<'MTA4'> = 34
        DEVTB<'MTA5'> = 35
        DEVTB<'MTA6'> = 36
        DEVTB<'MTA7'> = 37
*
        DEFINE('FINDEVICE(NAME)')       :(FINDEND)
PDP-10 Snobol4 User's Guide                          Page 54
APPENDIX B


*
FINDEVICE       FINDEVICE = DEVTB<NAME> 
        IDENT(FINDEVICE) :S(FRETURN)F(RETURN)
FINDEND
PDP-10 Snobol4 User's Guide                          Page 55
INDEX


                     ----- INDEX -----

$ operator . . . . . . . . . . 20
&DUMP  . . . . . . . . . . . . 29, 42
&INPUT . . . . . . . . . . . . 30
&OUTPUT  . . . . . . . . . . . 30
&TRIM  . . . . . . . . . . . . 30
.  . . . . . . . . . . . . . . 20
.LST . . . . . . . . . . . . . 6
.SNO . . . . . . . . . . . . . 6

A FORMAT . . . . . . . . . . . 39
A1 FORMAT  . . . . . . . . . . 8
A5 FORMAT  . . . . . . . . . . 8
Addition . . . . . . . . . . . 12
ADDITIONS  . . . . . . . . . . 9
Alternation  . . . . . . . . . 8, 18
Alternation symbol . . . . . . 8
APE  . . . . . . . . . . . . . 23
Arithmetic expressions . . . . 13
Arithmetic operations  . . . . 12
ARRAY  . . . . . . . . . . . . 30-33, 35
ASCII  . . . . . . . . . . . . 9, 42
Assignment statement . . . . . 11
Assignments  . . . . . . . . . 11
Asterisk . . . . . . . . . . . 12

BACKSPACE  . . . . . . . . . . 41, 49
Beginner's notes . . . . . . . 9
BLANK  . . . . . . . . . . . . 8, 10-12, 18-19

C Switch . . . . . . . . . . . 48
Carriage control . . . . . . . 39
CARRIAGE RETURN  . . . . . . . 34
CHANGES  . . . . . . . . . . . 8
CHARACTER SET  . . . . . . . . 8
Colon  . . . . . . . . . . . . 21
COMB . . . . . . . . . . . . . 29
Command  . . . . . . . . . . . 37
Command string . . . . . . . . 37
Command syntax . . . . . . . . 37
Comment line . . . . . . . . . 8, 12
COMPILATION  . . . . . . . . . 43
Compilation errors . . . . . . 44
Concatenation  . . . . . . . . 15, 17-20
Conditional assignment . . . . 20
Conditional transfer . . . . . 21
Conditional value assignment . 20
CONDITIONALLY FATAL ERRORS . . 45
Continuation lines . . . . . . 12
CONVERT  . . . . . . . . . . . 33
COPY . . . . . . . . . . . . . 32
Core . . . . . . . . . . . . . 5
Core expansion . . . . . . . . 9, 50
PDP-10 Snobol4 User's Guide                          Page 56
INDEX


Core size  . . . . . . . . . . 5
Current version  . . . . . . . 5
CUT BY SYSTEM  . . . . . . . . 46

D Switch . . . . . . . . . . . 7, 9, 42
DATA . . . . . . . . . . . . . 31
DEFINE . . . . . . . . . . . . 26, 28
Defined functions  . . . . . . 26
DELETE . . . . . . . . . . . . 27
DETACH . . . . . . . . . . . . 40
Device assignments . . . . . . 53
Device numbers . . . . . . . . 8, 36, 38
Device reference number  . . . 39
Device reference numbers . . . 8, 38
Device table . . . . . . . . . 36
DEVTB  . . . . . . . . . . . . 36, 53
DIFFER . . . . . . . . . . . . 26
DIFFERENCES  . . . . . . . . . 8
Division . . . . . . . . . . . 12
Dollar sign operator . . . . . 20
Dot operator . . . . . . . . . 20
DUMP . . . . . . . . . . . . . 7-10, 25, 29, 42
DUPL . . . . . . . . . . . . . 24

EJECT  . . . . . . . . . . . . 44
END  . . . . . . . . . . . . . 11, 21, 37, 45
End of file  . . . . . . . . . 36
END statement  . . . . . . . . 21
ENDFILE  . . . . . . . . . . . 40
Error termination  . . . . . . 45
ERRORS . . . . . . . . . . . . 44-46
Exclamation mark . . . . . . . 8
EXECUTION  . . . . . . . . . . 44
Exponentiation . . . . . . . . 12
Expressions  . . . . . . . . . 13
EXTERNAL FUNCTIONS . . . . . . 8

F  . . . . . . . . . . . . . . 21
Failure goto . . . . . . . . . 21
FEATURES . . . . . . . . . . . 8
FINDEVICE FUNCTION . . . . . . 53
FORM FEED  . . . . . . . . . . 8
FORMAT . . . . . . . . . . . . 8, 10, 38-39, 49
Format statement . . . . . . . 39
FORSE  . . . . . . . . . . . . 48-49
FORTRAN  . . . . . . . . . . . 36
FRETURN  . . . . . . . . . . . 27
Function . . . . . . . . . . . 4
FUNCTIONS  . . . . . . . . . . 23
Functions  . . . . . . . . . . 26

Garbage collection . . . . . . 50
Goto field . . . . . . . . . . 22
H FORMAT . . . . . . . . . . . 39
High segment . . . . . . . . . 5

I Switch . . . . . . . . . . . 7, 42, 48
I/O  . . . . . . . . . . . . . 34
I/O buffers  . . . . . . . . . 42
I/O SYSTEM . . . . . . . . . . 36
IFILE  . . . . . . . . . . . . 9, 36, 41
ILLEGAL DATA TYPE  . . . . . . 15, 22-23
Immediate value assignment . . 20
Indirect . . . . . . . . . . . 22
Indirect reference . . . . . . 22
INPUT  . . . . . . . . . . . . 8-9, 16, 30, 34-35, 40
INPUT ASSOCIATIONS . . . . . . 39
INPUT failure  . . . . . . . . 36
Input length . . . . . . . . . 40
INTEGER  . . . . . . . . . . . 31
Integer  . . . . . . . . . . . 12
Interpreter  . . . . . . . . . 5
Interpretive . . . . . . . . . 5
INTERVENTION TERMINATION . . . 46
INTRODUCTION . . . . . . . . . 11
IO BUFFERS . . . . . . . . . . 7

Keywords . . . . . . . . . . . 29

LE . . . . . . . . . . . . . . 25
LEN  . . . . . . . . . . . . . 24
LGT  . . . . . . . . . . . . . 4, 26
LINE FEED  . . . . . . . . . . 34
LIST . . . . . . . . . . . . . 44
LIST LEFT  . . . . . . . . . . 9, 44
LIST RIGHT . . . . . . . . . . 44
Listing  . . . . . . . . . . . 37
Listing device . . . . . . . . 37
Listing file . . . . . . . . . 37
LISTING-DEVICE . . . . . . . . 5
Low segment  . . . . . . . . . 5

MAXNO  . . . . . . . . . . . . 28
Minus sign . . . . . . . . . . 43
Mixed mode expressions . . . . 13
MOD  . . . . . . . . . . . . . 13
MSTIME . . . . . . . . . . . . 9
Multiple source files  . . . . 36
Multiplication . . . . . . . . 12

Negation . . . . . . . . . . . 8
Negation symbol  . . . . . . . 8
Normal termination . . . . . . 45
NULL . . . . . . . . . . . . . 10, 14-15, 34
NULL STRING  . . . . . . . . . 10
NULL string  . . . . . . . . . 14
NUMIOB . . . . . . . . . . . . 48

OFILE  . . . . . . . . . . . . 9, 36, 41
OMISSIONS  . . . . . . . . . . 8
OTHER I/O FUNCTIONS  . . . . . 40
PDP-10 Snobol4 User's Guide                          Page 58
INDEX


OUTPUT . . . . . . . . . . . . 8, 16, 30, 34, 36, 38
OUTPUT asociaitons . . . . . . 10
OUTPUT ASSOCIATIONS  . . . . . 38

Parentheses  . . . . . . . . . 13
Patern matching  . . . . . . . 16
Pattern  . . . . . . . . . . . 4, 16
Pattern matching . . . . . . . 4, 16
PATTERNS . . . . . . . . . . . 31
Patterns . . . . . . . . . . . 16, 18
Precedence . . . . . . . . . . 15
Predicates . . . . . . . . . . 25
Primitive functions  . . . . . 4, 23
PRINTED OUTPUT . . . . . . . . 34
PROGRAM EXAMPLE  . . . . . . . 31
Programmer defined . . . . . . 31
PUNCH  . . . . . . . . . . . . 35, 38
PUNCHED OUTPUT . . . . . . . . 35

Quotation marks  . . . . . . . 14
Quotes . . . . . . . . . . . . 14

Random access  . . . . . . . . 36
Reading  . . . . . . . . . . . 16
REAL . . . . . . . . . . . . . 31
Real numbers . . . . . . . . . 13
Recursive  . . . . . . . . . . 28
REENTER COMMAND  . . . . . . . 46
Reentrant  . . . . . . . . . . 9
REMDR  . . . . . . . . . . . . 25
REPLACE  . . . . . . . . . . . 4, 24
Replacement  . . . . . . . . . 17
Replacement statement  . . . . 17
RETURN . . . . . . . . . . . . 27
REVERSE  . . . . . . . . . . . 28
REWIND . . . . . . . . . . . . 40, 49

S  . . . . . . . . . . . . . . 21
Semicolon  . . . . . . . . . . 8, 12
SIZE . . . . . . . . . . . . . 23
SNOBOL.INI . . . . . . . . . . 48
SNOBOL.OPR . . . . . . . . . . 49
SOURCE DEVICE  . . . . . . . . 5
Source device  . . . . . . . . 37
Source file  . . . . . . . . . 37
Source files . . . . . . . . . 36
SOURCE LISTING . . . . . . . . 43
SOURCE PROGRAM INPUT . . . . . 43
SOURCE-DEVICE  . . . . . . . . 6
Standard input . . . . . . . . 5
Standard output  . . . . . . . 5
STRINGS  . . . . . . . . . . . 31
Subtraction  . . . . . . . . . 12
Success goto . . . . . . . . . 21
PDP-10 Snobol4 User's Guide                          Page 59
INDEX


Switches . . . . . . . . . . . 6, 42
SYNTAX TABLES  . . . . . . . . 50
SYSTEM PROGRAMMER'S NOTES  . . 48

T FORMAT . . . . . . . . . . . 39
TAB  . . . . . . . . . . . . . 8
TABLE  . . . . . . . . . . . . 32
TERMINATION  . . . . . . . . . 45
Transfers  . . . . . . . . . . 21
TRIM . . . . . . . . . . . . . 10, 23, 30, 35
TTCALL . . . . . . . . . . . . 9
TTCALL interface . . . . . . . 41
TTY SWITCHES . . . . . . . . . 42

U Switch . . . . . . . . . . . 7, 9, 42
Unary  . . . . . . . . . . . . 22
Unconditional transfer . . . . 21
UNCONDITIONALLY FATAL ERRORS . 46
Underline  . . . . . . . . . . 8
Underline symbol . . . . . . . 8
UNLIST . . . . . . . . . . . . 7, 9, 42-43
User's Guide . . . . . . . . . 5

Version  . . . . . . . . . . . 5
VERTICAL TAB . . . . . . . . . 8
VORMAT . . . . . . . . . . . . 48

WAITING FOR TTY INPUT  . . . . 37
Writing  . . . . . . . . . . . 16

X FORMAT . . . . . . . . . . . 39

Zero . . . . . . . . . . . . . 15