Return to spitv35.man CVS log

Up to [Research Unix] / researchv10no / cmd / spitbol

Annotation of researchv10no/cmd/spitbol/spitv35.man, revision 1.1

1.1     ! root        1: 
        !             2: 
        !             3: 
        !             4: 
        !             5: 
        !             6: 
        !             7: 
        !             8:                              *      *      *
        !             9: 
        !            10: 
        !            11: 
        !            12: 
        !            13: 
        !            14:                         M A C R O   S P I T B O L
        !            15:                         M A C R O   S P I T B O L
        !            16: 
        !            17:                         -------------------------
        !            18: 
        !            19: 
        !            20: 
        !            21:                     PROGRAM REFERENCE MANUAL (Rev. G)
        !            22: 
        !            23:                     ---------------------------------
        !            24: 
        !            25: 
        !            26: 
        !            27:                      VAX/VMS Version 3.5 (BCAB-2132)
        !            28: 
        !            29:                      -------------------------------
        !            30: 
        !            31: 
        !            32: 
        !            33: 
        !            34: 
        !            35:                   Copyright   (c)   1980    by    DEWAR
        !            36:                   INFORMATION    SYSTEMS   CORPORATION.
        !            37:                   This   manual   may   be   reporduced
        !            38:                   provided  that this Dewar Information
        !            39:                   Systems    Copyright    Notice     is
        !            40:                   incorporated.
        !            41: 
        !            42: 
        !            43: 
        !            44:                   VAX,   VMS,  DECwriter  and  PDP  are
        !            45:                   registered trademarks of the  Digital
        !            46:                   Equipment Corporation.
        !            47: 
        !            48: 
        !            49: 
        !            50: 
        !            51:                   DEWAR INFORMATION SYSTEMS CORPORATION
        !            52:                            221 West Lake Street
        !            53:                       Oak Park, Illinois USA  60302
        !            54: 
        !            55:                               (312) 524-1644
        !            56: 
        !            57: 
        !            58: 
        !            59: 
        !            60: 
        !            61: 
        !            62: 
        !            63: 
        !            64: 
        !            65: 
        !            66: 
        !            67: 
        !            68: 
        !            69: 
        !            70: 
        !            71: 
        !            72: 
        !            73: 
        !            74: 
        !            75: 
        !            76: 
        !            77: 
        !            78: 
        !            79: 
        !            80: 
        !            81: 
        !            82: 
        !            83: 
        !            84: 
        !            85: 
        !            86: 
        !            87: 
        !            88: 
        !            89: 
        !            90: 
        !            91: 
        !            92: 
        !            93: 
        !            94: 
        !            95: 
        !            96:            Please replace this page with the Table of Contents
        !            97:            Please replace this page with the Table of Contents
        !            98:                                (At the end)
        !            99:                                (At the end)
        !           100: 
        !           101: 
        !           102: 
        !           103: 
        !           104: 
        !           105: 
        !           106: 
        !           107: 
        !           108: 
        !           109: 
        !           110: 
        !           111: 
        !           112: 
        !           113: 
        !           114: 
        !           115: 
        !           116: 
        !           117: 
        !           118: 
        !           119: 
        !           120: 
        !           121: 
        !           122: 
        !           123: 
        !           124: 
        !           125: 
        !           126: 
        !           127: 
        !           128: 
        !           129: 
        !           130: 
        !           131:     This  report  is  parallel  to  the  University of Leeds Technical
        !           132:     Report Number 94, "Macro Spitbol - Decsystem 10 Version,"  McCann,
        !           133:     Holden  and Dewar, Dec. 1976.  Differences will be found primarily
        !           134:     in Section 12.
        !           135: 
        !           136: 
        !           137:                              Revision History
        !           138:                              ________ _______
        !           139: 
        !           140:     This document has been revised as follows :
        !           141: 
        !           142:     Dec 1976        to correspond with        SPITBOL Version 3.0
        !           143:     Mar 1978        to correspond with        SPITBOL Version 3.3
        !           144:     Sep 1978        to correspond with        SPITBOL Version 3.4
        !           145:     Feb 1979        to correspond with        SPITBOL Version 3.5
        !           146: 
        !           147: 
        !           148: 
        !           149:     VAX/VMS MACRO SPITBOL Version BCAB-2132 is designed to operate  on
        !           150:     the  VAX 11/780 and VAX 11/750 computers running the VMS operating
        !           151:     system version 2.0, 2.1, 2.2, 2.3 or 2.4.
        !           152: 
        !           153: 
        !           154: 
        !           155: 
        !           156: 
        !           157: 
        !           158: 
        !           159: 
        !           160: 
        !           161: 
        !           162: 
        !           163: 
        !           164: 
        !           165: 
        !           166: 
        !           167: 
        !           168: 
        !           169: 
        !           170: 
        !           171: 
        !           172: 
        !           173: 
        !           174: 
        !           175: 
        !           176: 
        !           177: 
        !           178: 
        !           179: 
        !           180: 
        !           181: 
        !           182: 
        !           183: 
        !           184: 
        !           185: 
        !           186: 
        !           187: 
        !           188: 
        !           189: 
        !           190: 
        !           191:          MACRO SPITBOL V3.5
        !           192:                                                    PAGE 1 - [1]
        !           193:          Introduction
        !           194: 
        !           195: 
        !           196: 
        !           197:                           *-------------------*
        !           198:                             [1]  Introduction
        !           199:                           | [1]  Introduction |
        !           200:                           *-------------------*
        !           201: 
        !           202:     MACRO SPITBOL  is  an  implementation  of  the  SNOBOL4   computer
        !           203:     language  which  was  coded  during 1974/75. In speed and external
        !           204:     style  it resembles the earlier SPITBOL  implementations  for  the
        !           205:     IBM 360   and  UNIVAC 1100  series  computers  but  internally  it
        !           206:     differs  considerably  from  these  since  the  source   code   is
        !           207:     converted  to  a reverse polish string which is then used to drive
        !           208:     interpretive routines.  MACRO SPITBOL is  available  with  a  high
        !           209:     degree  of  compatibility  on  a  range of computers running under
        !           210:     widely differing operating  systems.   This  report  reflects  the
        !           211:     above   fact   by  providing  in  its  first  nine  sections  such
        !           212:     documentation  and  information  for  users  as  is  substantially
        !           213:     machine   independent,  with  a  final  section  giving  essential
        !           214:     information peculiar to each  particular  implementation.   It  is
        !           215:     assumed  that  the  reader  is familiar with the standard version,
        !           216:     referred to simply as SNOBOL4 in the remainder of the  report  and
        !           217:     described   in   the   essential   reference   book  "The  SNOBOL4
        !           218:     Programming Language" by Griswold,  Poage  and  Polonsky,  Addison
        !           219:     Wesley,  1971.   Version  3.4  of SNOBOL4 is the reference version
        !           220:     for comparison.  There are  several  minor  incompatibilities  and
        !           221:     some  features  are  not implemented.  There are several additions
        !           222:     to the language in this implementation.
        !           223: 
        !           224: 
        !           225: 
        !           226: 
        !           227: 
        !           228: 
        !           229: 
        !           230: 
        !           231: 
        !           232: 
        !           233: 
        !           234: 
        !           235: 
        !           236: 
        !           237: 
        !           238: 
        !           239: 
        !           240: 
        !           241: 
        !           242: 
        !           243: 
        !           244: 
        !           245: 
        !           246: 
        !           247: 
        !           248: 
        !           249: 
        !           250: 
        !           251: 
        !           252: 
        !           253: 
        !           254:          MACRO SPITBOL V3.5
        !           255:                                                    PAGE 2 - [1]
        !           256:          Introduction
        !           257: 
        !           258: 
        !           259:     In  general  an  attempt  has   been   made   to   retain   upward
        !           260:     compatibility  wherever  possible.   Most  SNOBOL4  programs which
        !           261:     operate correctly using  SNOBOL4  should  operate  correctly  when
        !           262:     compiled  and  executed  using MACRO SPITBOL.  For brevity, in the
        !           263:     remainder of the report MACRO SPITBOL will be referred  to  simply
        !           264:     as SPITBOL.
        !           265: 
        !           266: 
        !           267:     SPITBOL was initially designed and implemented by:
        !           268: 
        !           269:     Professor Robert B. K. Dewar,
        !           270:     Courant Institute of Mathematical Sciences,
        !           271:     251 Mercer Street,
        !           272:     NEW YORK, N.Y. 10012.
        !           273:     U.S.A.
        !           274: 
        !           275:     It has been further developed and is now maintained by:
        !           276: 
        !           277:     Dr.  Anthony P. McCann,
        !           278:     Department of Computer Studies,
        !           279:     University of Leeds,
        !           280:     LEEDS, LS2 9JT,
        !           281:     England.
        !           282: 
        !           283: 
        !           284:     The VAX/VMS Version is the work of and is maintained by:
        !           285: 
        !           286:     Steven G. Duff
        !           287:     c/o Dewar Information Systems Corporation
        !           288:     221 West Lake Street
        !           289:     Oak Park, Illinois  60302
        !           290: 
        !           291:     which  should  be  contacted to report problems or for information
        !           292:     on distribution.
        !           293: 
        !           294:     The implementor gratefully acknowledges the assistance of  Thagard
        !           295:     Research  in  providing  development  facilities  for  the VAX/VMS
        !           296:     Version of SPITBOL.
        !           297: 
        !           298: 
        !           299: 
        !           300: 
        !           301: 
        !           302: 
        !           303: 
        !           304: 
        !           305: 
        !           306: 
        !           307: 
        !           308: 
        !           309: 
        !           310: 
        !           311: 
        !           312: 
        !           313: 
        !           314: 
        !           315: 
        !           316:          MACRO SPITBOL V3.5
        !           317:                                                    PAGE 3 - [2]
        !           318:          Summary of Differences
        !           319: 
        !           320: 
        !           321: 
        !           322:                      *-----------------------------*
        !           323:                        [2]  Summary of Differences
        !           324:                      | [2]  Summary of Differences |
        !           325:                      *-----------------------------*
        !           326: 
        !           327:     The  principal  differences  between  SPITBOL  and   SNOBOL4   are
        !           328:     summarised here.
        !           329: 
        !           330: 
        !           331:  2.1  Features not Implemented
        !           332:  2.1  Features not Implemented
        !           333:  _____________ ___ ___________
        !           334: 
        !           335: 
        !           336:      1.  The  capability  to  redefine  standard  system functions and
        !           337:          predefined operators.  This restriction permits compile  time
        !           338:          pre-evaluation  of  a wider range of expressions and patterns
        !           339:          than would otherwise  be  possible.   It  affects  the  OPSYN
        !           340:          function (see Section 5 for details).
        !           341: 
        !           342:      2.  The VALUE  and BACKSPACE functions.
        !           343: 
        !           344:      3.  The  keywords  &STFCOUNT  and  &FULLSCAN  .   The  heuristics
        !           345:          associated with the QUICKSCAN mode of  pattern  matching  are
        !           346:          complex  and for many programs do not result in a significant
        !           347:          increase  in speed.  Accordingly only  FULLSCAN  matching  is
        !           348:          provided  and  no  heuristics  are  applied.   In  particular
        !           349:          deferred expressions are not assumed to match  at  least  one
        !           350:          character.
        !           351: 
        !           352:      4.  The BLOCK datatype as in SNOBOL4B .
        !           353: 
        !           354:      5.  The  variable  PUNCH has no predefined association to a punch
        !           355:          stream.   If  required,  the  programmer  should  include   a
        !           356:          statement such as OUTPUT(.PUNCH,3) in his program.
        !           357: 
        !           358:      6.  SPITBOL does not permit exponentiation of two real numbers.
        !           359: 
        !           360:      7.  For  small  machines,  versions  of SPITBOL in which all real
        !           361:          arithmetic capability is omitted are available - see  Section
        !           362:          12.
        !           363: 
        !           364:      8.  Some  implementations  may  omit  a  few features.  A list is
        !           365:          given in Section 12.
        !           366: 
        !           367: 
        !           368: 
        !           369: 
        !           370: 
        !           371: 
        !           372: 
        !           373: 
        !           374: 
        !           375: 
        !           376: 
        !           377: 
        !           378: 
        !           379: 
        !           380: 
        !           381:          MACRO SPITBOL V3.5
        !           382:                                                    PAGE 4 - [2.2]
        !           383:          Summary of Differences
        !           384: 
        !           385: 
        !           386: 
        !           387:  2.2  Features Implemented Differently
        !           388:  2.2  Features Implemented Differently
        !           389:  _____________ ___________ ___________
        !           390: 
        !           391:     Some of the differences here may necessitate program changes.
        !           392: 
        !           393: 
        !           394:      1.  In SPITBOL the value of  &ANCHOR  is  obtained  only  at  the
        !           395:          start  of the match.  In SNOBOL4, changing the value during a
        !           396:          match can lead to unexpected results.
        !           397: 
        !           398:      2.  The pattern valued variables ABORT, ARB, BAL,  FAIL,   FENCE,
        !           399:          REM,  SUCCEED  are write protected so that attempts to assign
        !           400:          to them will fail.
        !           401: 
        !           402:      3.  The same stack is used for pattern matching and for  function
        !           403:          calls.   Thus  the  diagnostic issued for an infinite pattern
        !           404:          recursion is simply the standard stack overflow message.
        !           405: 
        !           406:      4.  Recovery from execution errors (see function SETEXIT ).
        !           407: 
        !           408:      5.  Input/Output.  In particular, FORTRAN I/O  is  not  provided.
        !           409:          Dynamic  association  to  files is possible through the third
        !           410:          argument and statement failure is possible if a  file  cannot
        !           411:          be found as in
        !           412:               INPUT(.IN,3,'INFIL')                :F(NOFILE)
        !           413: 
        !           414:      6.  The  TABLE function is implemented so that table elements can
        !           415:          be rapidly accessed by the efficient  technique  of  hashing.
        !           416:          In  order  to  set  a  suitable size for the hash table it is
        !           417:          important to choose a reasonable value for  the  argument  of
        !           418:          TABLE.   Use of an inappropriate value will not cause program
        !           419:          failure but may delay access to elements or waste memory.
        !           420: 
        !           421:      7.  SPITBOL allows  some  datatype  conversions  not  allowed  in
        !           422:          SNOBOL4.   For  example  a real value may be used in patterns
        !           423:          and is converted to a string.  In  general  objects  will  be
        !           424:          converted to an appropriate datatype if at all possible.
        !           425: 
        !           426:      8.  The  unary  .  (name)  operator applied to a natural variable
        !           427:          yields  a NAME rather than a  STRING.   Since  this  NAME  is
        !           428:          converted  to  a STRING when necessary, the difference is not
        !           429:          normally noticed.  The only points at which   the  difference
        !           430:          will  be  apparent  is  in  use  of  the  IDENT,  DIFFER  and
        !           431:          DATATYPE functions  and when used as a TABLE subscript.
        !           432: 
        !           433:      9.  SPITBOL  permits  leading  and  trailing  blanks  on  numeric
        !           434:          strings which are to be converted to  NUMERIC .
        !           435: 
        !           436:     10.  Several  of  the  built-in  functions are slightly different.
        !           437:          They are identified by a * on their names in Section 5.
        !           438: 
        !           439:     11.  The count  of  statements  executed  includes  labelled  null
        !           440:          statements and  the END statement.
        !           441: 
        !           442: 
        !           443: 
        !           444: 
        !           445:          MACRO SPITBOL V3.5
        !           446:                                                    PAGE 5 - [2.2]
        !           447:          Summary of Differences
        !           448: 
        !           449:     12.  Constant  sub-expressions  and  patterns are pre-evaluated at
        !           450:          compile time.  This  may  occasionally  result  in  execution
        !           451:          errors   (e.g.   integer   overflow)  being  reported  during
        !           452:          compilation.  Significant speed increases may be obtained  by
        !           453:          ensuring  that in-line patterns are constant so that they may
        !           454:          be  pre-evaluated.   Patterns  built  from   pattern   valued
        !           455:          variables  (e.g.  ARB)  and  pattern  functions with constant
        !           456:          arguments (e.g. ANY(*ARG), RTAB(0)) are themselves constant.
        !           457: 
        !           458:     13.  A compact and fast garbage collector is used which  needs  to
        !           459:          distinguish   between  small  integers  and memory addresses.
        !           460:          This effectively restricts the maximum size  of  any  SPITBOL
        !           461:          object  (string,  array, table, code or expression block)  to
        !           462:          be less than a value subsequently  referred  to  as  MXLEN  .
        !           463:          This   is   in  practice  little  restriction  on  most  host
        !           464:          computers.  Where, because of implementation needs, it  might
        !           465:          prove  restrictive,  a  run time option is generally provided
        !           466:          for setting this value to suit  a  user's  requirements  (see
        !           467:          Section  12.  where  an  indication  of  the  default initial
        !           468:          setting of MXLEN is also given).  Since the  value  of  MXLEN
        !           469:          is  used  to initialise &MAXLNGTH , printing &MAXLNGTH during
        !           470:          execution gives its exact value.   A  user  may  subsequently
        !           471:          assign  a  smaller value to this keyword but values exceeding
        !           472:          that of MXLEN may not be assigned to it.
        !           473: 
        !           474:     14.  A value of zero for &TRIM does  not  necessarily  imply  that
        !           475:          trailing  blanks  will  be added to records in which they are
        !           476:          not originally present - see Section 12.
        !           477: 
        !           478: 
        !           479: 
        !           480:  2.3  Additional Features
        !           481:  2.3  Additional Features
        !           482:  _______________ ________
        !           483: 
        !           484:     The following SPITBOL features are not found in SNOBOL4.
        !           485: 
        !           486: 
        !           487:      1.  The  functions APPEND, BREAKX, CHAR, BUFFER,    EJECT,  EXIT,
        !           488:          HOST,    INSERT,    LEQ,  LGE,        LLE,  LLT,  LNE,  LPAD,
        !           489:          REVERSE, RPAD,      RSORT,  SETEXIT,  SORT,  SUBSTR   .   The
        !           490:          sorting  functions,  the  extended  break pattern BREAKX, and
        !           491:          the output formatting functions LPAD and RPAD are  especially
        !           492:          useful.  See Section 5 for details of all these functions.
        !           493: 
        !           494:      2.  The keywords &ERRTEXT and &PROFILE.
        !           495: 
        !           496:      3.  The  symbolic  dump  optionally  includes elements of arrays,
        !           497:          tables  and programmer defined datatypes. (See DUMP ).
        !           498: 
        !           499:      4.  An access trace mode is provided in  addition  to  the  other
        !           500:          standard modes.  (See TRACE ).
        !           501: 
        !           502:      5.  A selection or alternative feature is provided.
        !           503: 
        !           504: 
        !           505: 
        !           506: 
        !           507: 
        !           508: 
        !           509:          MACRO SPITBOL V3.5
        !           510:                                                    PAGE 6 - [2.3]
        !           511:          Summary of Differences
        !           512: 
        !           513:      6.  The second argument of CONVERT may be 'NUMERIC'.
        !           514: 
        !           515:      7.  The  assignment symbol , = , is treated as an ordinary binary
        !           516:          operator  and the binary operator , ? , is  given  a  defined
        !           517:          meaning as a pattern matching operator.
        !           518: 
        !           519:      8.  If  running  SPITBOL from an on-line terminal, options may be
        !           520:          selected  to reduce the amount of  listing  information  sent
        !           521:          to  the  terminal  or  to restrict this to compilation errors
        !           522:          only. (See Section 12 for details).
        !           523: 
        !           524:      9.  Reflecting the fact that many current computer systems   have
        !           525:          good  online  terminal  capabilities,  the  name  TERMINAL is
        !           526:          available with pre-association for  input  and  output  to  a
        !           527:          terminal on such systems - see Section 12.
        !           528:          T     TERMINAL = EVAL(TERMINAL)     :S(T)
        !           529:          acts  as a desk calculator.  TERMINAL may be detached but may
        !           530:          not   then   be   re-associated.    If   this   feature    is
        !           531:          unimplemented, TERMINAL acts as an ordinary variable.
        !           532: 
        !           533:     10.  Several  additional  control  cards  may  be  used  to select
        !           534:          various compile time and run time options.
        !           535: 
        !           536:     11.  An   extended   character   set   is   available   in    some
        !           537:          implementations.   Where  lower  case  letters  are  provided
        !           538:          names such as "INPUT" and "input"  are  distinct.   In  gotos
        !           539:          :f  and :s mean the same as :F and :S.  The Tab character, if
        !           540:          available,  is  syntactically  identical  with  blank.    See
        !           541:          Section 12.
        !           542: 
        !           543:     12.  The  assignment  &STLIMIT = -1 inhibits all checks on numbers
        !           544:          of statements executed.
        !           545: 
        !           546:     13.  Built-in functions are available for sorting the elements  of
        !           547:          tables and arrays.
        !           548: 
        !           549:     14.  A  additional datatype called a BUFFER is available.  Buffers
        !           550:          are  character  arrays  with  a  fixed  allocation   and   an
        !           551:          adjustable   size   which  may  vary  between  zero  and  the
        !           552:          allocated size at any time.   Three  new  functions,  INSERT,
        !           553:          APPEND  and BUFFER have been added to support the buffer type
        !           554:          specifically,  and the CONVERT,  PROTOTYPE,  SIZE,  DATATYPE,
        !           555:          SUBSTR,  COPY and pattern matching and replacement operations
        !           556:          have been enhanced to provide support for buffers.
        !           557: 
        !           558: 
        !           559: 
        !           560: 
        !           561: 
        !           562: 
        !           563: 
        !           564: 
        !           565: 
        !           566: 
        !           567: 
        !           568: 
        !           569: 
        !           570: 
        !           571:          MACRO SPITBOL V3.5
        !           572:                                                    PAGE 7 - [2.4]
        !           573:          Summary of Differences
        !           574: 
        !           575: 
        !           576: 
        !           577:  2.4  Syntax Differences
        !           578:  2.4  Syntax Differences
        !           579:  ___________ ___________
        !           580: 
        !           581:     This section describes differences in syntax between  SPITBOL  and
        !           582:     SNOBOL4.  such  differences  should  not generally affect existing
        !           583:     SNOBOL4 programs.
        !           584: 
        !           585: 
        !           586:      1.  Reference  to  elements  of  arrays  which   are   themselves
        !           587:          elements  of   arrays  is  possible  without  using  the ITEM
        !           588:          function.  Thus the following are equivalent -
        !           589:            A<J><K> = B<J><K>;       ITEM(A<J>,K) = ITEM(B<J>,K)
        !           590: 
        !           591:      2.  The compiler permits real  constants  to  be  followed  by  a
        !           592:          FORTRAN style exponent E+xxx.
        !           593: 
        !           594:      3.  A  selection  or  alternative  construction  may  be  written
        !           595:          anywhere that a value is permitted.  It consists of a  series
        !           596:          of   expressions   separated   by   commas  and  enclosed  in
        !           597:          parentheses:
        !           598:            (e1,e2,e3,....,en)
        !           599:          The semantics is to evaluate the  expressions  from  left  to
        !           600:          right  until one succeeds and then use its value.  Failure is
        !           601:          signalled if all evaluations fail.   This  feature  trivially
        !           602:          provides  an  "or"  function for predicates and also has many
        !           603:          other uses as shown by the following examples:
        !           604:            A     = (EQ(B,3),GT(B,20)) B + 1
        !           605:            NEXT  = (INPUT,'%EOF')
        !           606:            MAXAB = (GT(A,B) A,B)
        !           607:          The   alternative   structure   provides   an    IF-THEN-ELSE
        !           608:          capability,  and  as  such  is  a useful programming feature.
        !           609:          Note incidentally that the semantics of ordinary  parentheses
        !           610:          is  a  correct  degenerate  case  of an alternative structure
        !           611:          with one alternative.
        !           612: 
        !           613:      4.  The array brackets [] may be used instead of <>  if  desired.
        !           614:          Thus X[I,J] and X<I,J> are equivalent.
        !           615: 
        !           616:      5.  By  treating  =  as  a  right  associative operator of lowest
        !           617:          priority, multiple assignments within a single statement  may
        !           618:          be  coded.   The  value  returned by an assignment is that of
        !           619:          its right hand side.  After obeying
        !           620:            A[I = INPUT] = INPUT
        !           621:          I is the index of the element of the array  into  which  data
        !           622:          has been read.
        !           623: 
        !           624:      6.  ?  is  defined  to  be an explicit pattern matching operator.
        !           625:          It is left associative and has priority lower  than  that  of
        !           626:          all  operators  except  =  .   It  returns  as  its value the
        !           627:          substring matched from its left argument (a  string)  by  its
        !           628:          right argument (a pattern).  Thus
        !           629:            'ABCD' ? LEN(3) $ OUTPUT ? LEN(1) REM $ OUTPUT
        !           630:          causes printing of
        !           631:            ABC
        !           632:            BC
        !           633: 
        !           634: 
        !           635:          MACRO SPITBOL V3.5
        !           636:                                                    PAGE 8 - [2.4]
        !           637:          Summary of Differences
        !           638: 
        !           639: 
        !           640: 
        !           641: 
        !           642: 
        !           643: 
        !           644: 
        !           645: 
        !           646: 
        !           647: 
        !           648: 
        !           649: 
        !           650: 
        !           651: 
        !           652: 
        !           653: 
        !           654: 
        !           655: 
        !           656: 
        !           657: 
        !           658: 
        !           659: 
        !           660: 
        !           661: 
        !           662: 
        !           663: 
        !           664: 
        !           665: 
        !           666: 
        !           667: 
        !           668: 
        !           669: 
        !           670: 
        !           671: 
        !           672: 
        !           673: 
        !           674: 
        !           675: 
        !           676: 
        !           677: 
        !           678: 
        !           679: 
        !           680: 
        !           681: 
        !           682: 
        !           683: 
        !           684: 
        !           685: 
        !           686: 
        !           687: 
        !           688: 
        !           689: 
        !           690: 
        !           691: 
        !           692: 
        !           693: 
        !           694: 
        !           695: 
        !           696: 
        !           697:          MACRO SPITBOL V3.5
        !           698:                                                    PAGE 9 - [3]
        !           699:          Datatypes and Conversion
        !           700: 
        !           701: 
        !           702: 
        !           703:                     *-------------------------------*
        !           704:                       [3]  Datatypes and Conversion
        !           705:                     | [3]  Datatypes and Conversion |
        !           706:                     *-------------------------------*
        !           707: 
        !           708:     This  section  details  the datatypes available in SPITBOL and the
        !           709:     conversions which may be performed amongst them.
        !           710: 
        !           711: 
        !           712:  3.1  Available Datatypes
        !           713:  3.1  Available Datatypes
        !           714:  ______________ _________
        !           715: 
        !           716: 
        !           717:      1.  STRING
        !           718:          Strings range  in  length  from  0  (null  string)  to  MXLEN
        !           719:          characters   (subject  to  the  setting  of  &MAXLNGTH).  Any
        !           720:          characters from the hardware set of the computer used to  run
        !           721:          SPITBOL can appear in a string.
        !           722: 
        !           723:      2.  INTEGER
        !           724:          Integers  are  generally  stored  in  the hardware complement
        !           725:          form for the computer used to run SPITBOL and usually  occupy
        !           726:          a single word.  See Section 12 for range.
        !           727: 
        !           728:      3.  REAL
        !           729:          Available  if  floating  point  hardware  is  available  (sec
        !           730:          10.2.4).  Stored according to the usual hardware  conventions
        !           731:          of the computer on which SPITBOL is run.
        !           732: 
        !           733:      4.  ARRAY
        !           734:          Arrays  may  not  exceed  MXLEN words in total size. 10 to 15
        !           735:          words must be allowed for housekeeping information.
        !           736: 
        !           737:      5.  TABLE
        !           738:          A table may have up to MXLEN elements.   Any  SPITBOL  object
        !           739:          may  be  used  as  the name of a table element, including the
        !           740:          null string.  See Section 5 for details.
        !           741: 
        !           742:      6.  PATTERN
        !           743:          Pattern  structures  may  be  arbitrarily  large  within  the
        !           744:          limits imposed by total available memory.
        !           745: 
        !           746:      7.  NAME
        !           747:          A  name  can  be  obtained  from  any variable.  Note that in
        !           748:          SPITBOL , the name operator (unary dot) applied to a  natural
        !           749:          variable  yields  a  name,  not  a string as is the case with
        !           750:          SNOBOL4.  Use  of  names  as  arguments  to  the  indirection
        !           751:          operator  (unary  $)  is  much  faster than the use of string
        !           752:          arguments.   Names  can  also  be  used   advantageously   in
        !           753:          statements such as  INPUT(.IN)
        !           754: 
        !           755: 
        !           756: 
        !           757: 
        !           758: 
        !           759: 
        !           760: 
        !           761: 
        !           762:          MACRO SPITBOL V3.5
        !           763:                                                    PAGE 10 - [3.1]
        !           764:          Datatypes and Conversion
        !           765: 
        !           766: 
        !           767:      8.  EXPRESSION
        !           768:          Any   expression  may  be  deferred  by  using  the  unary  *
        !           769:          operator.
        !           770: 
        !           771:      9.  CODE
        !           772:          A string representing a valid  program  can  be  compiled  at
        !           773:          execution  time.   The  resulting CODE object may be executed
        !           774:          in the same manner as the original program.
        !           775: 
        !           776:     10.  BUFFER
        !           777:          The buffer type does not  exist  in  SNOBOL4;   it  has  been
        !           778:          introduced  into  MACRO  SPITBOL  primarily to provide a more
        !           779:          efficient mechanism for working with large strings.
        !           780: 
        !           781:          Buffers are packed character  arrays  created  with  a  fixed
        !           782:          allocation  defining  the  maximum  number of characters they
        !           783:          can ever contain.  Buffers are helpful in manipulating  large
        !           784:          strings  efficiently.  The reason is that in-situ replacement
        !           785:          of buffer  contents  is  possible  using  APPEND,  INSERT  or
        !           786:          pattern  replacement, while any modification to a string must
        !           787:          be achieved internally by first making a copy of the string.
        !           788: 
        !           789:          A buffer is like an array  in  that  it  cannot  be  extended
        !           790:          beyond  its  allocation size.  The origin of the first buffer
        !           791:          character is always one.   Buffer  creation  is  accomplished
        !           792:          directly   with  the  BUFFER  function,  or  indirectly  with
        !           793:          CONVERT.  In addition, every buffer  has  a  dynamic  defined
        !           794:          size that can vary between zero and the maximum allocation.
        !           795: 
        !           796:          Once  a  buffer  has been created,  characters can be written
        !           797:          into  specific  segments  using   the   INSERT   and   APPEND
        !           798:          functions, or using pattern replacement.
        !           799: 
        !           800:          As  with  other aggregate types, two buffers are IDENTical if
        !           801:          and only if they are the same object.
        !           802: 
        !           803:          Most standard functions will convert buffers to strings  when
        !           804:          required.   Exceptions  to this are SUBSTR, which can be used
        !           805:          to directly produce a string  from  a  section  of  a  buffer
        !           806:          without  the  need  for  an intermediate conversion and SIZE,
        !           807:          which  will  give  the  current  defined  size  of  a  buffer
        !           808:          directly.   The  pattern  matching  and  pattern  replacement
        !           809:          operations of the language will also accept a buffer name  as
        !           810:          a  subject.   Pattern  matching  is  done  directly  from the
        !           811:          buffer, and pattern replacement is  done  directly  into  the
        !           812:          buffer as an INSERT function on the substring matched.
        !           813: 
        !           814:          In  addition,  PROTOTYPE  gives  the  prototype  string for a
        !           815:          buffer, which is the integer allocation size  of  the  buffer
        !           816:          object.   COPY  can be used to create a duplicate of a buffer
        !           817:          to work with.  DATATYPE will, of course,  return  the  string
        !           818:          "BUFFER" for any buffer object.
        !           819: 
        !           820: 
        !           821: 
        !           822: 
        !           823: 
        !           824:          MACRO SPITBOL V3.5
        !           825:                                                    PAGE 11 - [3.2]
        !           826:          Datatypes and Conversion
        !           827: 
        !           828: 
        !           829: 
        !           830:  3.2  Possible Datatype Conversions
        !           831:  3.2  Possible Datatype Conversions
        !           832:  _____________ ________ ___________
        !           833: 
        !           834:     As  far  as possible SPITBOL converts from one datatype to another
        !           835:     as required.  The following  table  shows  which  conversions  are
        !           836:     possible.    Blank  entries  indicate  that  the  conversions  are
        !           837:     impossible, A indicates that conversion is always possible, and  U
        !           838:     indicates  conversion  is usually possible, depending on the value
        !           839:     involved.
        !           840: 
        !           841:                           CONVERT TO:
        !           842: 
        !           843:                        S I R A T P N E C B
        !           844:                      +--------------------
        !           845:                     S! A U U     A A U U U
        !           846:                     I! A A A     A A A   A
        !           847:                     R! A U A     A A A   A
        !           848:             CONVERT A!       A U
        !           849:              FROM:  T!       A A
        !           850:                     P!           A
        !           851:                     N! U U U     U A U U U
        !           852:                     E!               A
        !           853:                     C!                 A
        !           854:                     B!                   A
        !           855: 
        !           856:             S       STRING
        !           857:             I       INTEGER
        !           858:             R       REAL
        !           859:             A       ARRAY
        !           860:             T       TABLE
        !           861:             P       PATTERN
        !           862:             N       NAME
        !           863:             E       EXPRESSION
        !           864:             C       CODE
        !           865:             B       BUFFER
        !           866: 
        !           867: 
        !           868: 
        !           869: 
        !           870: 
        !           871: 
        !           872: 
        !           873: 
        !           874: 
        !           875: 
        !           876: 
        !           877: 
        !           878: 
        !           879: 
        !           880: 
        !           881: 
        !           882: 
        !           883: 
        !           884: 
        !           885: 
        !           886: 
        !           887: 
        !           888:          MACRO SPITBOL V3.5
        !           889:                                                    PAGE 12 - [3.3]
        !           890:          Datatypes and Conversion
        !           891: 
        !           892: 
        !           893: 
        !           894:  3.3  Conversion Details
        !           895:  3.3  Conversion Details
        !           896:  _______________ _______
        !           897: 
        !           898:     This section gives detailed descriptions for each of the  possible
        !           899:     conversions.
        !           900: 
        !           901: 
        !           902:      1.  STRING --> INTEGER
        !           903: 
        !           904:          Leading  and  trailing blanks are ignored.  A leading sign is
        !           905:          optional.  The sign, if  present,  must  immediately  precede
        !           906:          the  digits.   A  null  or  all  blank string is converted to
        !           907:          zero.
        !           908: 
        !           909:      2.  STRING --> REAL
        !           910: 
        !           911:          Leading and trailing blanks are ignored.  A leading  sign  if
        !           912:          present,  must  immediately  precede  the number.  The number
        !           913:          itself may be written in standard FORTRAN  type  format  with
        !           914:          an  optional  exponent.   The  conversion is always accurate,
        !           915:          the last bit  being  correctly  rounded.   A  null  or  blank
        !           916:          string is converted to 0.0 .
        !           917: 
        !           918:      3.  STRING --> PATTERN
        !           919: 
        !           920:          A pattern is created which will match the string value.
        !           921: 
        !           922:      4.  STRING --> NAME
        !           923: 
        !           924:          The  result is the name of the natural variable which has the
        !           925:          given string as its name.  This is identical  to  the  result
        !           926:          of  applying  the  unary  dot  operator  to  the  variable in
        !           927:          question.  The null string cannot be converted to a name.
        !           928: 
        !           929:      5.  STRING --> EXPRESSION
        !           930: 
        !           931:          The string must represent a legal  SPITBOL  expression.   The
        !           932:          compiler  is  used  to convert the string into its equivalent
        !           933:          expression and the result can be used anywhere an  expression
        !           934:          is permitted.
        !           935: 
        !           936:      6.  STRING --> CODE
        !           937: 
        !           938:          The  string  must represent a legal SPITBOL program, complete
        !           939:          with labels, and using  semicolons  to  separate  statements.
        !           940:          The  compiler  is  used to convert the string into executable
        !           941:          code.  The resulting code can be executed by transferring  to
        !           942:          it  with  a  direct  GOTO  or by a normal transfer to a label
        !           943:          within the code.
        !           944: 
        !           945:      7.  STRING --> BUFFER
        !           946: 
        !           947: 
        !           948: 
        !           949: 
        !           950: 
        !           951: 
        !           952:          MACRO SPITBOL V3.5
        !           953:                                                    PAGE 13 - [3.3]
        !           954:          Datatypes and Conversion
        !           955: 
        !           956:          A buffer is created with an  allocation  size  equal  to  the
        !           957:          size  of  the string, and the string value is copied into the
        !           958:          buffer.  The null string cannot be converted to a buffer.
        !           959: 
        !           960: 
        !           961: 
        !           962: 
        !           963: 
        !           964: 
        !           965: 
        !           966: 
        !           967: 
        !           968: 
        !           969: 
        !           970: 
        !           971: 
        !           972: 
        !           973: 
        !           974: 
        !           975: 
        !           976: 
        !           977: 
        !           978: 
        !           979: 
        !           980: 
        !           981: 
        !           982: 
        !           983: 
        !           984: 
        !           985: 
        !           986: 
        !           987: 
        !           988: 
        !           989: 
        !           990: 
        !           991: 
        !           992: 
        !           993: 
        !           994: 
        !           995: 
        !           996: 
        !           997: 
        !           998: 
        !           999: 
        !          1000: 
        !          1001: 
        !          1002: 
        !          1003: 
        !          1004: 
        !          1005: 
        !          1006: 
        !          1007: 
        !          1008: 
        !          1009: 
        !          1010: 
        !          1011: 
        !          1012: 
        !          1013: 
        !          1014:          MACRO SPITBOL V3.5
        !          1015:                                                    PAGE 14 - [3.3]
        !          1016:          Datatypes and Conversion
        !          1017: 
        !          1018: 
        !          1019:      8.  INTEGER --> STRING
        !          1020: 
        !          1021:          The result has no leading  or  trailing  blanks  and  leading
        !          1022:          zeros  are  suppressed.  A minus sign is prefixed to negative
        !          1023:          values.  Zero is converted to "0".
        !          1024: 
        !          1025:      9.  INTEGER --> REAL
        !          1026: 
        !          1027:          A real number is obtained by adding a zero  fractional  part.
        !          1028:          Note  that  it  is  possible  to  lose  significance  in this
        !          1029:          conversion if the mantissa of  the  real  representation  has
        !          1030:          fewer digits than are available for an integer.
        !          1031: 
        !          1032:     10.  INTEGER --> PATTERN
        !          1033: 
        !          1034:          First  convert   to  a  STRING  and  then  treat as STRING to
        !          1035:          PATTERN.
        !          1036: 
        !          1037:     11.  INTEGER --> NAME
        !          1038: 
        !          1039:          First convert to STRING and then treat as STRING to NAME.
        !          1040: 
        !          1041:     12.  INTEGER --> EXPRESSION
        !          1042: 
        !          1043:          The result is an EXPRESSION which when evaluated  yields  the
        !          1044:          INTEGER as its value.
        !          1045: 
        !          1046:     13.  INTEGER --> BUFFER
        !          1047: 
        !          1048:          The  integer  is  first  converted  to a STRING which is then
        !          1049:          converted to a buffer.
        !          1050: 
        !          1051:     14.  REAL --> STRING
        !          1052: 
        !          1053:          The real  number  is  converted  to  its  standard  character
        !          1054:          representation.   Fixed  type  format  is  used  if possible,
        !          1055:          otherwise  an  exponent  (using  E)   is   supplied.    Seven
        !          1056:          significant  digits  are  generated, the last being correctly
        !          1057:          rounded for all  cases.   Trailing  insignificant  zeros  are
        !          1058:          suppressed after rounding has taken place.
        !          1059: 
        !          1060:     15.  REAL --> INTEGER
        !          1061: 
        !          1062:          This  conversion is only possible if the REAL is in the range
        !          1063:          permitted  for  integers.   in  this  case,  the  result   is
        !          1064:          obtained by truncating the fractional part.
        !          1065: 
        !          1066:     16.  REAL --> PATTERN
        !          1067: 
        !          1068:          First convert to STRING and then treat as STRING to PATTERN.
        !          1069: 
        !          1070:     17.  REAL --> NAME
        !          1071: 
        !          1072: 
        !          1073: 
        !          1074: 
        !          1075: 
        !          1076:          MACRO SPITBOL V3.5
        !          1077:                                                    PAGE 15 - [3.3]
        !          1078:          Datatypes and Conversion
        !          1079: 
        !          1080:          First convert to STRING and then treat as STRING to NAME.
        !          1081: 
        !          1082:     18.  REAL --> EXPRESSION
        !          1083: 
        !          1084:          The  result  is an expression which when evaluated yields the
        !          1085:          REAL as its value.
        !          1086: 
        !          1087:     19.  REAL --> BUFFER
        !          1088: 
        !          1089:          First convert to STRING, then treat as STRING to BUFFER.
        !          1090: 
        !          1091:     20.  ARRAY --> TABLE
        !          1092: 
        !          1093:          The array must be two dimensional with a second dimension  of
        !          1094:          2   or  an  error  occurs.   For  each  value  of  the  first
        !          1095:          subscript, J , a table entry using the (J,1)  entry  as  name
        !          1096:          and  the  (J,2)  entry  as value is created.  The table built
        !          1097:          has a number of hash headers (see TABLE in Section  5)  equal
        !          1098:          to the first dimension.
        !          1099: 
        !          1100:     21.  TABLE --> ARRAY
        !          1101: 
        !          1102:          The  table  must  have at least one element which is non-null
        !          1103:          otherwise statement failure occurs.  The array  generated  is
        !          1104:          two  dimensional with the first dimension equal to the number
        !          1105:          of non-null entries in the table and the second dimension  is
        !          1106:          two.   For  each entry, the (J,1) element in the array is the
        !          1107:          the name and the (J,2) element is the value.
        !          1108: 
        !          1109:     22.  NAME --> STRING
        !          1110: 
        !          1111:          A NAME can be converted to a STRING only if it  is  the  name
        !          1112:          of   a   natural  variable.   The  resulting  string  is  the
        !          1113:          character name of the variable.
        !          1114: 
        !          1115:     23.  NAME --> INTEGER, REAL, PATTERN, EXPRESSION, CODE, BUFFER
        !          1116: 
        !          1117:          The NAME is first converted to a  STRING  (if  possible)  and
        !          1118:          then the conversion proceeds as described for STRING.
        !          1119: 
        !          1120: 
        !          1121: 
        !          1122: 
        !          1123: 
        !          1124: 
        !          1125: 
        !          1126: 
        !          1127: 
        !          1128: 
        !          1129: 
        !          1130: 
        !          1131: 
        !          1132: 
        !          1133: 
        !          1134: 
        !          1135: 
        !          1136: 
        !          1137: 
        !          1138:          MACRO SPITBOL V3.5
        !          1139:                                                    PAGE 16 - [4]
        !          1140:          Operators
        !          1141: 
        !          1142: 
        !          1143: 
        !          1144:                             *----------------*
        !          1145:                               [4]  Operators
        !          1146:                             | [4]  Operators |
        !          1147:                             *----------------*
        !          1148: 
        !          1149:     SPITBOL  operators  are  listed  without any detailed descriptions
        !          1150:     since  they  correspond,  with  a  few  exceptions  noted  in  the
        !          1151:     description of differences, to those of SNOBOL4.
        !          1152: 
        !          1153: 
        !          1154:  4.1  Unary Operators
        !          1155:  4.1  Unary Operators
        !          1156:  __________ _________
        !          1157: 
        !          1158:     Unary  operators  all  have  equal  priority which is greater than
        !          1159:     that of any binary operator.
        !          1160: 
        !          1161:     OPERATOR                DESCRIPTION
        !          1162: 
        !          1163:     ?                Interrogation - null if operand succeeds
        !          1164:     &                Keyword
        !          1165:     +                Indicates postive numeric operand
        !          1166:     -                Negates numeric operand
        !          1167:     *                Defers evaluation of expression
        !          1168:     $                Indirection
        !          1169:     .                Returns a name
        !          1170:     ~                Negates failure or success of its operand
        !          1171:     @                Assigns cursor position to its operand
        !          1172: 
        !          1173:          Unused unary operator symbols are   ! % / # =
        !          1174: 
        !          1175: 
        !          1176: 
        !          1177: 
        !          1178: 
        !          1179: 
        !          1180: 
        !          1181: 
        !          1182: 
        !          1183: 
        !          1184: 
        !          1185: 
        !          1186: 
        !          1187: 
        !          1188: 
        !          1189: 
        !          1190: 
        !          1191: 
        !          1192: 
        !          1193: 
        !          1194: 
        !          1195: 
        !          1196: 
        !          1197: 
        !          1198: 
        !          1199: 
        !          1200: 
        !          1201: 
        !          1202: 
        !          1203:          MACRO SPITBOL V3.5
        !          1204:                                                    PAGE 17 - [4.2]
        !          1205:          Operators
        !          1206: 
        !          1207: 
        !          1208: 
        !          1209:  4.2  Binary Operators
        !          1210:  4.2  Binary Operators
        !          1211:  ___________ _________
        !          1212: 
        !          1213:     Several of the associativites and priorities differ from those  of
        !          1214:     SNOBOL4.
        !          1215: 
        !          1216:     OP.     ASSOCY. PRIO.           DEFINITION
        !          1217: 
        !          1218:     =       right   0       Assignment
        !          1219:     ?       left    1       Pattern match
        !          1220:     |       right   3       Pattern alternation
        !          1221:     blank   right   4       Concatenation or pattern match
        !          1222:     +       left    6       Arithmetic addition
        !          1223:     -       left    6       Arithmetic subtraction
        !          1224:     /       left    8       Arithmetic division
        !          1225:     *       left    9       Arithmetic multiplication
        !          1226:     $       left    12      Immediate pattern assignment
        !          1227:     .       left    12      Conditional pattern assignment
        !          1228: 
        !          1229:     &       left    2       Undefined
        !          1230:     @       right   5       Undefined
        !          1231:     ~       left    7       Undefined
        !          1232:     %       left    10      Undefined
        !          1233:     _       right   13      Undefined
        !          1234: 
        !          1235: 
        !          1236: 
        !          1237: 
        !          1238: 
        !          1239: 
        !          1240: 
        !          1241: 
        !          1242: 
        !          1243: 
        !          1244: 
        !          1245: 
        !          1246: 
        !          1247: 
        !          1248: 
        !          1249: 
        !          1250: 
        !          1251: 
        !          1252: 
        !          1253: 
        !          1254: 
        !          1255: 
        !          1256: 
        !          1257: 
        !          1258: 
        !          1259: 
        !          1260: 
        !          1261: 
        !          1262: 
        !          1263: 
        !          1264: 
        !          1265: 
        !          1266: 
        !          1267:          MACRO SPITBOL V3.5
        !          1268:                                                    PAGE 18 - [5]
        !          1269:          Functions
        !          1270: 
        !          1271: 
        !          1272: 
        !          1273:                             *----------------*
        !          1274:                               [5]  Functions
        !          1275:                             | [5]  Functions |
        !          1276:                             *----------------*
        !          1277: 
        !          1278:     This  section  defines  the  built-in  functions  of  SPITBOL, the
        !          1279:     descriptions being given in alphabetical order.   In  most  cases,
        !          1280:     the  arguments  are  pre-converted  to  some  particular datatype.
        !          1281:     This is indicated in the function header by the notation:
        !          1282:       FUNCTION(STRING,INTEGER,....)
        !          1283:     If  the  corresponding  argument  cannot  be  converted   to   the
        !          1284:     indicated  datatype,  an  error  occurs.   Sometimes  the range of
        !          1285:     arguments  permitted  is  restricted,  in  which  case   arguments
        !          1286:     outside  the  range  cause an error.  The usage "ARGUMENT" implies
        !          1287:     that the argument can be of any datatype. "NUMERIC"  implies  that
        !          1288:     either REAL or INTEGER arguments are acceptable.
        !          1289: 
        !          1290:     In  functions  such as ARRAY, DATA, DEFINE with a string prototype
        !          1291:     argument, the string should not contain non-significant blanks.
        !          1292: 
        !          1293: 
        !          1294:  5.1  ANY -- Pattern to Match Selected Character
        !          1295:  5.1  ANY -- Pattern to Match Selected Character
        !          1296:  ________ __ _______ __ _____ ________ _________
        !          1297: 
        !          1298:     ANY(STRING) or ANY(EXPRESSION)
        !          1299: 
        !          1300:     This function  returns   a  pattern  which  will  match  a  single
        !          1301:     character  selected from the characters in the argument string.  A
        !          1302:     null argument is not permitted.   If  an  expression  argument  is
        !          1303:     used,  then  the  expression  is evaluated during pattern matching
        !          1304:     and must yield a non-null string result.
        !          1305: 
        !          1306: 
        !          1307:  5.2  APPEND * -- Append string to buffer
        !          1308:  5.2  APPEND * -- Append string to buffer
        !          1309:  ___________ _ __ ______ ______ __ ______
        !          1310: 
        !          1311:     APPEND(BUFFER,STRING)
        !          1312: 
        !          1313:     APPEND is used to append a string to the contents of  an  existing
        !          1314:     buffer.     APPEND    is    defined    to    be    identical    to
        !          1315:     INSERT(BUFFER,SIZE(BUFFER)+1,0,STRING).  The first  argument  must
        !          1316:     be a buffer type or an error occurs.
        !          1317: 
        !          1318: 
        !          1319:  5.3  APPLY * -- Apply function
        !          1320:  5.3  APPLY * -- Apply function
        !          1321:  __________ _ __ _____ ________
        !          1322: 
        !          1323:     APPLY(NAME,ARG,ARG,...)
        !          1324: 
        !          1325:     The  first argument is the name of a function to be applied to the
        !          1326:     (possibly null) list  of  arguments  following.   Unlike  SNOBOL4,
        !          1327:     SPITBOL  does  not  require  the  number of arguments to match the
        !          1328:     function definition, extra arguments  being  ignored  and  missing
        !          1329:     arguments being supplied as null strings.
        !          1330: 
        !          1331: 
        !          1332: 
        !          1333: 
        !          1334: 
        !          1335: 
        !          1336:          MACRO SPITBOL V3.5
        !          1337:                                                    PAGE 19 - [5.4]
        !          1338:          Functions
        !          1339: 
        !          1340: 
        !          1341: 
        !          1342:  5.4  ARBNO -- Pattern for Iterated Match
        !          1343:  5.4  ARBNO -- Pattern for Iterated Match
        !          1344:  __________ __ _______ ___ ________ _____
        !          1345: 
        !          1346:     ARBNO(PATTERN)
        !          1347: 
        !          1348:     This  function  returns  a  pattern  which will match an arbitrary
        !          1349:     number of occurrences of  the  pattern  argument,  including  zero
        !          1350:     occurrences (this resulting in matching of the null string).
        !          1351: 
        !          1352: 
        !          1353:  5.5  ARG * -- Obtain Argument Name
        !          1354:  5.5  ARG * -- Obtain Argument Name
        !          1355:  ________ _ __ ______ ________ ____
        !          1356: 
        !          1357:     ARG(NAME,INTEGER)
        !          1358: 
        !          1359:     The  first  argument  represents  the  name  of  a  function.  The
        !          1360:     integer is the index of a formal argument to this  function.   The
        !          1361:     NAME  of the selected argument is returned (this is converted to a
        !          1362:     string on output).  ARG fails if the integer is out  of  range  of
        !          1363:     the number of formal arguments.
        !          1364: 
        !          1365: 
        !          1366:  5.6  ARRAY -- Generate Array Structure
        !          1367:  5.6  ARRAY -- Generate Array Structure
        !          1368:  __________ __ ________ _____ _________
        !          1369: 
        !          1370:     ARRAY(STRING,ARG) or ARRAY(INTEGER,ARG)
        !          1371: 
        !          1372:     The  string  represents  the protoype of an array to be allocated.
        !          1373:     This is in the form
        !          1374:        "LBD1:HBD1,LBD2:HBD2,...."
        !          1375:     where  LBD1,HBD1  etc.   are  integers  specifying  low  and  high
        !          1376:     bounds.   The  low  bound  (LBD) may be omitted for some or all of
        !          1377:     the dimensions, in which case the colon may also be omitted and  a
        !          1378:     low  bound of 1 is assumed.  The second argument (of any datatype)
        !          1379:     is the initial value of all the elements in the array.  If  it  is
        !          1380:     omitted,  the  initial  value of all the elements will be the null
        !          1381:     string.  The second form of the call may be  used  to  create  one
        !          1382:     dimensional  arrays  (vectors)  with  a  low  bound  of 1. SPITBOL
        !          1383:     optimises accesses to elements of vectors.
        !          1384: 
        !          1385: 
        !          1386:  5.7  BREAK -- Construct Scanning Pattern
        !          1387:  5.7  BREAK -- Construct Scanning Pattern
        !          1388:  __________ __ _________ ________ _______
        !          1389: 
        !          1390:     BREAK(STRING) or BREAK(EXPRESSION)
        !          1391: 
        !          1392:     This function returns a pattern which will match any string up  to
        !          1393:     the  point  preceding  any  character which occurs in the argument
        !          1394:     string.  A null argument  is  not  permitted.   If  an  expression
        !          1395:     argument  is given, the resulting pattern causes the expression to
        !          1396:     be  evaluated  during  pattern  matching.   In  this   case,   the
        !          1397:     evaluated result must be a non-null string.
        !          1398: 
        !          1399: 
        !          1400: 
        !          1401: 
        !          1402: 
        !          1403: 
        !          1404: 
        !          1405: 
        !          1406:          MACRO SPITBOL V3.5
        !          1407:                                                    PAGE 20 - [5.8]
        !          1408:          Functions
        !          1409: 
        !          1410: 
        !          1411: 
        !          1412:  5.8  BUFFER * -- Create buffer object
        !          1413:  5.8  BUFFER * -- Create buffer object
        !          1414:  ___________ _ __ ______ ______ ______
        !          1415: 
        !          1416:     BUFFER(INTEGER,STRING)
        !          1417: 
        !          1418:     This  function  creates  a buffer-type object (see the description
        !          1419:     in the datatype section).   The  first  argument  is  the  integer
        !          1420:     allocation  for  the  buffer  and  the second argument defines the
        !          1421:     initial contents of the buffer.  The defined size  of  the  buffer
        !          1422:     is  initialized  to  SIZE(STRING).  The allocation must be between
        !          1423:     between 1 and &MAXLNGTH, and the size of the string must  be  less
        !          1424:     than or equal to the allocated size, or an error will occur.
        !          1425: 
        !          1426: 
        !          1427:  5.9  BREAKX * -- Construct Scanning Pattern
        !          1428:  5.9  BREAKX * -- Construct Scanning Pattern
        !          1429:  ___________ _ __ _________ ________ _______
        !          1430: 
        !          1431:     BREAKX(STRING) or BREAKX(EXPRESSION)
        !          1432: 
        !          1433:     BREAKX  returns  a  pattern  whose  initial match is the same as a
        !          1434:     corresponding  BREAK  pattern.   However,  BREAKX   has   implicit
        !          1435:     alternatives  which  on  subsequent  match failure permit scanning
        !          1436:     past the first break character found and  up  to  the  next  break
        !          1437:     character.   Note  that BREAKX may be used to  replace ARB in many
        !          1438:     situations where BREAK cannot be used  easily.   For  example  the
        !          1439:     following replacement can be made -
        !          1440:        ARB ('CAT' ! 'DOG')  -->  BREAKX('CD') ('CAT' ! 'DOG')
        !          1441:     In   the  case  of  an  expression  argument,  the  expression  is
        !          1442:     evaluated during  pattern  matching  and  must  yield  a  non-null
        !          1443:     string.   Note  that  evaluation of the expression is not repeated
        !          1444:     on rematch attempts by extension.
        !          1445: 
        !          1446: 
        !          1447: 
        !          1448: 
        !          1449: 
        !          1450: 
        !          1451: 
        !          1452: 
        !          1453: 
        !          1454: 
        !          1455: 
        !          1456: 
        !          1457: 
        !          1458: 
        !          1459: 
        !          1460: 
        !          1461: 
        !          1462: 
        !          1463: 
        !          1464: 
        !          1465: 
        !          1466: 
        !          1467: 
        !          1468: 
        !          1469: 
        !          1470: 
        !          1471: 
        !          1472:          MACRO SPITBOL V3.5
        !          1473:                                                    PAGE 21 - [5.10]
        !          1474:          Functions
        !          1475: 
        !          1476: 
        !          1477: 
        !          1478:  5.10  CHAR * -- Convert Character Code to String
        !          1479:  5.10  CHAR * -- Convert Character Code to String
        !          1480:  __________ _ __ _______ _________ ____ __ ______
        !          1481: 
        !          1482:     CHAR(INTEGER)
        !          1483: 
        !          1484:     The CHAR function returns a one-character  string  containing  the
        !          1485:     character  with  the  internal character code corresponding to the
        !          1486:     given   argument.    The   string    returned    is    necessarily
        !          1487:     machine-dependent.  In  general however, A = CHAR(N) is equivalent
        !          1488:     to:
        !          1489:        &ALPHABET (LEN(N) LEN(1) . A)
        !          1490: 
        !          1491:     If the given argument is not a non-negative integer in  the  range
        !          1492:     of the host machine character set, an error is issued.
        !          1493: 
        !          1494: 
        !          1495:  5.11  CLEAR * -- Clear Variable Storage
        !          1496:  5.11  CLEAR * -- Clear Variable Storage
        !          1497:  ___________ _ __ _____ ________ _______
        !          1498: 
        !          1499:     CLEAR(STRING)
        !          1500: 
        !          1501:     This  function  causes  the values of variables to be set to null.
        !          1502:     In the simple case, where the argument is  omitted  or  null,  the
        !          1503:     action  is  the  same as in SNOBOL4 (i.e. all variables cleared to
        !          1504:     null).  An extension is available in SPITBOL.  The first  argument
        !          1505:     may  be  a  string  which is a list of variable names separated by
        !          1506:     commas.  These represent the names of variables whose  values  are
        !          1507:     to be left unchanged.  For example -
        !          1508:        CLEAR('ABC,CDE,EFG')
        !          1509:     would  cause the value of all variables except ABC, CDE, EFG to be
        !          1510:     set to the null string.
        !          1511: 
        !          1512: 
        !          1513:  5.12  CODE * -- Compile Code
        !          1514:  5.12  CODE * -- Compile Code
        !          1515:  __________ _ __ _______ ____
        !          1516: 
        !          1517:     CODE(STRING)
        !          1518: 
        !          1519:     The effect of this function is to convert  the  argument  to  type
        !          1520:     CODE  as  described in the section on type conversion.  The STRING
        !          1521:     must represent a valid SPITBOL program complete  with  labels  and
        !          1522:     using  semicolons  (;)  to  separate statements.  The call to CODE
        !          1523:     fails if syntactic errors are found.  In this case it is  possible
        !          1524:     to inspect &ERRTEXT to find the error message.  e.g.
        !          1525:            C = CODE(CD)     :F<CODE(' OUTPUT = &ERRTEXT')>
        !          1526:     SETEXIT  may  also  be  used  to  intercept these errors.  Another
        !          1527:     extension over  SNOBOL4  is  that  the  code  string  may  contain
        !          1528:     embedded  control  cards  (notably  -LIST  to cause listing of the
        !          1529:     code) and comments delimited by semicolons.
        !          1530: 
        !          1531: 
        !          1532: 
        !          1533: 
        !          1534: 
        !          1535: 
        !          1536: 
        !          1537: 
        !          1538: 
        !          1539: 
        !          1540:          MACRO SPITBOL V3.5
        !          1541:                                                    PAGE 22 - [5.13]
        !          1542:          Functions
        !          1543: 
        !          1544: 
        !          1545: 
        !          1546:  5.13  COLLECT -- Initiate Storage Regeneration
        !          1547:  5.13  COLLECT -- Initiate Storage Regeneration
        !          1548:  _____________ __ ________ _______ ____________
        !          1549: 
        !          1550:     COLLECT(INTEGER)
        !          1551: 
        !          1552:     The COLLECT function forces a garbage collection  which  retrieves
        !          1553:     unused  storage  and returns it to the block of available storage.
        !          1554:     The integer argument represents a minimum number of  words  to  be
        !          1555:     made  available.   If  this  amount of storage cannot be obtained,
        !          1556:     the COLLECT function fails.  On successful return, the  result  is
        !          1557:     the   number   of   words   actually   obtained.    Although   the
        !          1558:     implementation of COLLECT is the same as in  SNOBOL4,  the  values
        !          1559:     obtained  will  be  quite different due to different internal data
        !          1560:     representations.  Furthermore,  the  organization  of  SPITBOL  is
        !          1561:     such  that  forcing  garbage  collections to occur before they are
        !          1562:     required increases execution time.
        !          1563: 
        !          1564: 
        !          1565:  5.14  CONVERT * -- Convert Datatypes
        !          1566:  5.14  CONVERT * -- Convert Datatypes
        !          1567:  _____________ _ __ _______ _________
        !          1568: 
        !          1569:     CONVERT(ARGUMENT,STRING)
        !          1570: 
        !          1571:     The returned result is obtained by converting the  first  argument
        !          1572:     to  the type indicated by the string name of the datatype given as
        !          1573:     the second argument.  The permitted conversions are  described  in
        !          1574:     the  section  on  type  conversion.  Any conversions which are not
        !          1575:     permitted cause failure of the CONVERT call.  The second  argument
        !          1576:     may  be  'NUMERIC'  ,  in  which case the argument is converted to
        !          1577:     INTEGER or REAL according to its form.
        !          1578: 
        !          1579: 
        !          1580:  5.15  COPY * -- Copy Structure
        !          1581:  5.15  COPY * -- Copy Structure
        !          1582:  __________ _ __ ____ _________
        !          1583: 
        !          1584:     COPY(ARGUMENT)
        !          1585: 
        !          1586:     The COPY function returns a distinct copy of the object  presented
        !          1587:     as  its argument.  This is only useful for arrays, tables, buffers
        !          1588:     and program defined datatypes.  Note that SPITBOL permits  copying
        !          1589:     of TABLES unlike SNOBOL4.
        !          1590: 
        !          1591: 
        !          1592: 
        !          1593: 
        !          1594: 
        !          1595: 
        !          1596: 
        !          1597: 
        !          1598: 
        !          1599: 
        !          1600: 
        !          1601: 
        !          1602: 
        !          1603: 
        !          1604: 
        !          1605: 
        !          1606: 
        !          1607: 
        !          1608:          MACRO SPITBOL V3.5
        !          1609:                                                    PAGE 23 - [5.16]
        !          1610:          Functions
        !          1611: 
        !          1612: 
        !          1613: 
        !          1614:  5.16  DATA -- Create Datatype
        !          1615:  5.16  DATA -- Create Datatype
        !          1616:  __________ __ ______ ________
        !          1617: 
        !          1618:     DATA(STRING)
        !          1619: 
        !          1620:     The  argument  to  DATA  is  a  prototype  for  a  program defined
        !          1621:     datatype in the form  of  a  function  call  with  arguments  e.g.
        !          1622:     DATA('CMPLX(RE,IM)').   The  function  name  in  the string is the
        !          1623:     name of the new datatype.  The argument names in  the  string  are
        !          1624:     the  names  of  field selector functions used to access the fields
        !          1625:     of  the  new  datatype.   Increased  efficiency  is  obtained   by
        !          1626:     avoiding   the   use   of  duplicate  field  names  for  different
        !          1627:     datatypes, although such multiple use is not forbidden.
        !          1628: 
        !          1629: 
        !          1630:  5.17  DATATYPE * -- Obtain Datatype
        !          1631:  5.17  DATATYPE * -- Obtain Datatype
        !          1632:  ______________ _ __ ______ ________
        !          1633: 
        !          1634:     DATATYPE(ARGUMENT)
        !          1635: 
        !          1636:     DATATYPE returns the formal identification of the datatype of  its
        !          1637:     argument.
        !          1638: 
        !          1639: 
        !          1640:  5.18  DATE * -- Obtain Date
        !          1641:  5.18  DATE * -- Obtain Date
        !          1642:  __________ _ __ ______ ____
        !          1643: 
        !          1644:     DATE()
        !          1645: 
        !          1646:     DATE  returns  a  string giving the current date and possibly also
        !          1647:     clock-on-the-wall-time (see Section 12.)
        !          1648: 
        !          1649: 
        !          1650:  5.19  DEFINE -- Define a Function
        !          1651:  5.19  DEFINE -- Define a Function
        !          1652:  ____________ __ ______ _ ________
        !          1653: 
        !          1654:     DEFINE(STRING) or DEFINE(STRING,NAME)
        !          1655: 
        !          1656:     The DEFINE function is used to create  program  defined  functions
        !          1657:     according  to  the prototype supplied as the argument.  The second
        !          1658:     argument if  supplied,  names  the  label  at  the  entry  to  the
        !          1659:     function.
        !          1660: 
        !          1661: 
        !          1662:  5.20  DETACH -- Detach I/O Association
        !          1663:  5.20  DETACH -- Detach I/O Association
        !          1664:  ____________ __ ______ ___ ___________
        !          1665: 
        !          1666:     DETACH(NAME)
        !          1667: 
        !          1668:     NAME  is the name of a variable which has previously been input or
        !          1669:     output associated   by appearing as the first  argument  of  INPUT
        !          1670:     or  OUTPUT.   DETACH  cancels  the association of the variable but
        !          1671:     does not affect the file to which it was associated.
        !          1672: 
        !          1673: 
        !          1674: 
        !          1675: 
        !          1676: 
        !          1677: 
        !          1678: 
        !          1679: 
        !          1680:          MACRO SPITBOL V3.5
        !          1681:                                                    PAGE 24 - [5.21]
        !          1682:          Functions
        !          1683: 
        !          1684: 
        !          1685: 
        !          1686:  5.21  DIFFER * -- Test for Arguments Differing
        !          1687:  5.21  DIFFER * -- Test for Arguments Differing
        !          1688:  ____________ _ __ ____ ___ _________ _________
        !          1689: 
        !          1690:     DIFFER(ARGUMENT,ARGUMENT)
        !          1691: 
        !          1692:     DIFFER is a predicate function which fails if  its  two  arguments
        !          1693:     are identical objects.  In SPITBOL
        !          1694:        DIFFER(.ABC,'ABC')
        !          1695:     succeeds  since  .ABC  is  a  NAME.  DIFFER and IDENT are the only
        !          1696:     functions in  which  the  different  implementation  of  the  name
        !          1697:     operator (unary dot) may give rise to problems.
        !          1698: 
        !          1699:     DIFFER also works on object of type BUFFER (see IDENT).
        !          1700: 
        !          1701: 
        !          1702:  5.22  DUMP * -- Dump Storage
        !          1703:  5.22  DUMP * -- Dump Storage
        !          1704:  __________ _ __ ____ _______
        !          1705: 
        !          1706:     DUMP(INTEGER)
        !          1707: 
        !          1708:     The  DUMP  function  causes  a  dump  of  current values to occur.
        !          1709:     After the dump is complete, execution  continues  unaffected  (the
        !          1710:     DUMP  function  returns  the  null  string). If the argument is 1,
        !          1711:     then the dump includes values of  all  non-constant  keywords  and
        !          1712:     all  non-null  natural  variables.  If the argument is 2, then the
        !          1713:     dump also  includes  values  of  all   non-null  array  and  table
        !          1714:     elements  and  non-null field values of program defined datatypes.
        !          1715:     The format of the latter  dump  is  self  explanatory  and  avoids
        !          1716:     printing  any  structure  more  than  once.  A call to DUMP with a
        !          1717:     zero argument is ignored.  This  allows  use  of  a  switch  value
        !          1718:     which  can  be turned on and off globally.  A call to DUMP with an
        !          1719:     argument greater than 2 produces a core dump in  the  same  format
        !          1720:     as  that produced by a system abnormal end and should therefore be
        !          1721:     used with discretion.
        !          1722: 
        !          1723: 
        !          1724:  5.23  DUPL * -- Duplicate String or Pattern
        !          1725:  5.23  DUPL * -- Duplicate String or Pattern
        !          1726:  __________ _ __ _________ ______ __ _______
        !          1727: 
        !          1728:     DUPL(STRING,INTEGER) or DUPL(PATTERN,INTEGER)
        !          1729: 
        !          1730:     DUPL returns a result obtained by duplicating the  first  argument
        !          1731:     the  number  of  times  indicated by the second.  A null string is
        !          1732:     returned if INTEGER is zero and statement failure occurs if it  is
        !          1733:     negative.
        !          1734: 
        !          1735: 
        !          1736:  5.24  EJECT * -- Eject to new page
        !          1737:  5.24  EJECT * -- Eject to new page
        !          1738:  ___________ _ __ _____ __ ___ ____
        !          1739: 
        !          1740:     EJECT(INTEGER) or EJECT(STRING)
        !          1741: 
        !          1742:     The  argument must have previously appeared as the second argument
        !          1743:     of a call of  OUTPUT to identify an output channel.  An  eject  to
        !          1744:     the  top  of  the  next page of the output file occurs.  A null or
        !          1745:     absent argument causes an eject on the standard output file.
        !          1746: 
        !          1747: 
        !          1748: 
        !          1749: 
        !          1750:          MACRO SPITBOL V3.5
        !          1751:                                                    PAGE 25 - [5.25]
        !          1752:          Functions
        !          1753: 
        !          1754: 
        !          1755: 
        !          1756:  5.25  ENDFILE * -- Close a File
        !          1757:  5.25  ENDFILE * -- Close a File
        !          1758:  _____________ _ __ _____ _ ____
        !          1759: 
        !          1760:     ENDFILE(INTEGER) or ENDFILE(STRING)
        !          1761: 
        !          1762:     The argument must have previously appeared as the second  argument
        !          1763:     of  a  call  of    INPUT  or  OUTPUT  to  identify an input/output
        !          1764:     channel.  The file attached to the channel is  closed,  associated
        !          1765:     storage  is  released  and  all variables associated with the file
        !          1766:     are detached.  Thus ENDFILE should be used only  when  no  further
        !          1767:     use  is  to  be  made of the file.  If the file is to be reread or
        !          1768:     rewritten,  use  REWIND  (if  the  implementation  supports   this
        !          1769:     function - see Section 12).
        !          1770: 
        !          1771: 
        !          1772:  5.26  EQ -- Test for Equal
        !          1773:  5.26  EQ -- Test for Equal
        !          1774:  ________ __ ____ ___ _____
        !          1775: 
        !          1776:     EQ(NUMERIC,NUMERIC)
        !          1777: 
        !          1778:     EQ  is  a  predicate  function which succeeds if its two arguments
        !          1779:     are equal.
        !          1780: 
        !          1781: 
        !          1782:  5.27  EVAL * -- Evaluate Expression
        !          1783:  5.27  EVAL * -- Evaluate Expression
        !          1784:  __________ _ __ ________ __________
        !          1785: 
        !          1786:     EVAL(EXPRESSION)
        !          1787: 
        !          1788:     EVAL returns the result of  evaluating  its  expression  argument.
        !          1789:     Note  that  a  string  can  be  converted  into  an  expression by
        !          1790:     compiling it into CODE.  Thus EVAL in SPITBOL is  compatible  with
        !          1791:     SNOBOL4  and  handles strings in the same way.  If an error occurs
        !          1792:     in evaluating the argument,  &ERRTEXT is set and EVAL  fails.   To
        !          1793:     avoid  such  errors  passing   unnoticed,  it  may  be well to use
        !          1794:     SETEXIT to intercept them,  or use a FAIL  goto,  or  evaluate  in
        !          1795:     -NOFAIL  mode.
        !          1796: 
        !          1797: 
        !          1798:  5.28  EXIT * -- Exit to Save Load Module or to JCL
        !          1799:  5.28  EXIT * -- Exit to Save Load Module or to JCL
        !          1800:  __________ _ __ ____ __ ____ ____ ______ __ __ ___
        !          1801: 
        !          1802:     EXIT(INTEGER) or EXIT(STRING)
        !          1803: 
        !          1804:     This  function  resembles that introduced by Gimpel in SITBOL.  It
        !          1805:     permits the saving of a core image at any point in  the  execution
        !          1806:     of  a  SPITBOL  program  to  produce  a   load module  and in some
        !          1807:     implementations it may be permissible to exit  from  SPITBOL  into
        !          1808:     another  program.   For  an  often  executed program use of a load
        !          1809:     module saves translation  and  initialisation  time.    A  garbage
        !          1810:     collection  is  performed  in  order to compact store before it is
        !          1811:     saved.  If initialising code is  label  free,  it  is  collectable
        !          1812:     after  it  has  been  executed,  giving  a further opportunity for
        !          1813:     economy.  The argument, N, may have the following values -
        !          1814: 
        !          1815: 
        !          1816: 
        !          1817: 
        !          1818: 
        !          1819: 
        !          1820:          MACRO SPITBOL V3.5
        !          1821:                                                    PAGE 26 - [5.28]
        !          1822:          Functions
        !          1823: 
        !          1824: 
        !          1825: 
        !          1826:      1.  N > 0   Save the whole core  image  (includes  all  the  pure
        !          1827:          SPITBOL  code  and  unused  stack space, so is wasteful). The
        !          1828:          resulting load  module  is  free-standing  and  is  not  made
        !          1829:          obsolete by changes to SPITBOL.
        !          1830: 
        !          1831:      2.  N  =  0   Interrupt program execution and return to JCL level
        !          1832:          so  that  user  can  issue  JCL  commands  and  then   resume
        !          1833:          execution if wished.  Does not save a core image.
        !          1834: 
        !          1835:      3.  N  <  0  Save the impure areas of memory only so that program
        !          1836:          can be restarted by loading pure SPITBOL  code  +  the  saved
        !          1837:          areas.   The  resulting load modules are considerably smaller
        !          1838:          than for the case N = 1, but are made obsolete  and  must  be
        !          1839:          regenerated as new versions of SPITBOL are released.
        !          1840: 
        !          1841:      4.  N  =  "string".   If  this feature is available, (see Section
        !          1842:          12), then SPITBOL execution is  terminated  and  the  program
        !          1843:          named by "string" is entered.
        !          1844: 
        !          1845: 
        !          1846:     EXIT  returns  the null string and may occur in the program at any
        !          1847:     position syntactically valid for a function  call.   No  mechanism
        !          1848:     is  provided  for automatic re-attaching of files which are in use
        !          1849:     at the time an EXIT call terminates a run.  Hence EXIT  calls  are
        !          1850:     most  commonly  placed  after  initialising  code  and  before the
        !          1851:     opening of input/output files for the program proper.  In  general
        !          1852:     no  standard input file is available when a load module is run, so
        !          1853:     references  to  variable  INPUT  will  fail  unless  it  has  been
        !          1854:     detached  or  a  file is explicitly associated to it.  The absence
        !          1855:     of a standard output file may create problems  (in  reporting  run
        !          1856:     time  errors  in  particular).  SPITBOL  implementors will usually
        !          1857:     provide  a  means  of  attaching  such  a  file  at   load   time.
        !          1858:     Alternatively a user may prefer to include a statement
        !          1859: 
        !          1860:          OUTPUT(.OUTPUT,,'FILENAME')
        !          1861: 
        !          1862:     Failing  these  possibilities,  either  a default output file name
        !          1863:     should be allocated or execution should end with a  special  error
        !          1864:     code  if  printing  to  a non-existent standard file is attempted.
        !          1865:     Section  12  gives  details  for  this  implementation.    Certain
        !          1866:     listing options may be selected by choice of the argument value.
        !          1867:       N  =  +1  or  -1. The output file will be given a heading and in
        !          1868:     some implementations it  may  be  possible  to  re-specify  record
        !          1869:     length  (only  to  a  smaller  value  than during compilation) and
        !          1870:     other options.
        !          1871:       N = +2 or -2. Heading omitted but  re-specification  of  options
        !          1872:     may be possible.
        !          1873:       N = +3 or -3. Heading omitted and no option re-specification.
        !          1874: 
        !          1875: 
        !          1876: 
        !          1877: 
        !          1878: 
        !          1879: 
        !          1880: 
        !          1881: 
        !          1882:          MACRO SPITBOL V3.5
        !          1883:                                                    PAGE 27 - [5.29]
        !          1884:          Functions
        !          1885: 
        !          1886: 
        !          1887: 
        !          1888:  5.29  FENCE * -- Generate Fenced Pattern
        !          1889:  5.29  FENCE * -- Generate Fenced Pattern
        !          1890:  ___________ _ __ ________ ______ _______
        !          1891: 
        !          1892:     FENCE(PATTERN)
        !          1893: 
        !          1894:     FENCE(pattern)  returns  a  pattern value which is the same as the
        !          1895:     given pattern, except that alternatives  within  the  pattern  are
        !          1896:     only  seen  by  the  scanner  when  it  is  moving  in the forward
        !          1897:     direction.    Pattern   backup   will    always    pass    through
        !          1898:                                                                    not
        !          1899:     FENCE(pattern).  Note that backup through FENCE(pattern) does  ___
        !          1900:     cause  the  match to abort, as does the &FENCE pattern, it is that
        !          1901:     alternatives within the Fenced pattern are not examined  when  the
        !          1902:     scanner  is  backing  up.  For  example, this pattern will match a
        !          1903:     string of text up to the next comma, or if there is no  comma,  to
        !          1904:     the  end  of  the  string.   The text is put in STR, and the match
        !          1905:     will only succeed if STR is non-null.
        !          1906:             P = FENCE( BREAK(',') | REM ) $ STR  *DIFFER(STR)
        !          1907:     Without the FENCE, failure of  the  DIFFER(STR)  would  cause  the
        !          1908:     scanner  to try the REM alternative regardless of whether or not a
        !          1909:     comma is found.
        !          1910: 
        !          1911:     FENCE is not available in all implementations.  See Section 12.
        !          1912: 
        !          1913: 
        !          1914:  5.30  FIELD * -- Get Field Name
        !          1915:  5.30  FIELD * -- Get Field Name
        !          1916:  ___________ _ __ ___ _____ ____
        !          1917: 
        !          1918:     FIELD(NAME,INTEGER)
        !          1919: 
        !          1920:     FIELD returns the NAME  of  the  selected  field  of  the  program
        !          1921:     defined  datatype whose name is the first argument.  If the second
        !          1922:     argument is out of range (less than 1, or greater than the  number
        !          1923:     of fields), the FIELD function fails.
        !          1924: 
        !          1925: 
        !          1926:  5.31  GE -- Test for Greater or Equal
        !          1927:  5.31  GE -- Test for Greater or Equal
        !          1928:  ________ __ ____ ___ _______ __ _____
        !          1929: 
        !          1930:     GE(NUMERIC,NUMERIC)
        !          1931: 
        !          1932:     GE  is  a  predicate function which succeeds if the first argument
        !          1933:     is greater than or equal to the second.
        !          1934: 
        !          1935: 
        !          1936:  5.32  GT -- Test for Greater
        !          1937:  5.32  GT -- Test for Greater
        !          1938:  ________ __ ____ ___ _______
        !          1939: 
        !          1940:     GT(NUMERIC,NUMERIC)
        !          1941: 
        !          1942:     GT is a predicate function which succeeds if  the  first  argument
        !          1943:     is greater than the second.
        !          1944: 
        !          1945: 
        !          1946: 
        !          1947: 
        !          1948: 
        !          1949: 
        !          1950: 
        !          1951: 
        !          1952: 
        !          1953:          MACRO SPITBOL V3.5
        !          1954:                                                    PAGE 28 - [5.33]
        !          1955:          Functions
        !          1956: 
        !          1957:  5.33  HOST * -- Obtain Information about Host Computer
        !          1958:  5.33  HOST * -- Obtain Information about Host Computer
        !          1959:  __________ _ __ ______ ___________ _____ ____ ________
        !          1960: 
        !          1961:     HOST(ARGUMENT,ARGUMENT,ARGUMENT)
        !          1962: 
        !          1963:     SPITBOL  runs on different mainframes with differing file formats,
        !          1964:     file naming conventions etc.  which makes  it  desirable  in  some
        !          1965:     programs  to  know  on  what machine the program is running.  HOST
        !          1966:     called with null arguments returns a string of the form
        !          1967:        "<COMPUTER NAME>:<OPERATING SYSTEM NAME>:<SITE NAME>"
        !          1968:     which  satisfies  most  requirements  of  this   kind.    At   the
        !          1969:     discretion  of  the SPITBOL implementor, non-null arguments may be
        !          1970:     used to specify other features specific to the host.  See  Section
        !          1971:     12 for details.
        !          1972: 
        !          1973: 
        !          1974:  5.34  IDENT * -- Test for Identical
        !          1975:  5.34  IDENT * -- Test for Identical
        !          1976:  ___________ _ __ ____ ___ _________
        !          1977: 
        !          1978:     IDENT(ARGUMENT,ARGUMENT)
        !          1979: 
        !          1980:     IDENT  is a predicate function which succeeds if its two arguments
        !          1981:     are identical.  In SPITBOL,
        !          1982:        IDENT(.ABC,'ABC')
        !          1983:     fails since .ABC is a NAME in SPITBOL.  Also, two values  of  type
        !          1984:     BUFFER  will  be IDENTical if and only if they are the same buffer
        !          1985:     object.  Apart from this, IDENT is compatible with SNOBOL4.
        !          1986: 
        !          1987: 
        !          1988: 
        !          1989: 
        !          1990: 
        !          1991: 
        !          1992: 
        !          1993: 
        !          1994: 
        !          1995: 
        !          1996: 
        !          1997: 
        !          1998: 
        !          1999: 
        !          2000: 
        !          2001: 
        !          2002: 
        !          2003: 
        !          2004: 
        !          2005: 
        !          2006: 
        !          2007: 
        !          2008: 
        !          2009: 
        !          2010: 
        !          2011: 
        !          2012: 
        !          2013: 
        !          2014: 
        !          2015: 
        !          2016: 
        !          2017: 
        !          2018: 
        !          2019:          MACRO SPITBOL V3.5
        !          2020:                                                    PAGE 29 - [5.35]
        !          2021:          Functions
        !          2022: 
        !          2023: 
        !          2024: 
        !          2025:  5.35  INPUT * -- Set Input Association
        !          2026:  5.35  INPUT * -- Set Input Association
        !          2027:  ___________ _ __ ___ _____ ___________
        !          2028: 
        !          2029:     INPUT(NAME,INTEGER,STRING) or INPUT(NAME,STRING,STRING)
        !          2030: 
        !          2031:     Rather than give a separate description of OUTPUT which  would  be
        !          2032:     almost  exactly  parallel with that for INPUT, a joint description
        !          2033:     is given  here.   Some  machine  dependency  is  likely  in  these
        !          2034:     functions   -   see  Section  12  for  details  relating  to  this
        !          2035:     implementation.
        !          2036: 
        !          2037:     The first argument is the name  of  a  variable  which  is  to  be
        !          2038:     input/output  associated  and  is required, whereas the others are
        !          2039:     optional.  The second argument  identifies  a  channel  which  may
        !          2040:     subsequently   be  used  to  refer  to  the  association.   It  is
        !          2041:     recommended that,  as  in  SNOBOL4,  the  second  argument  be  an
        !          2042:     integer  but  the  use  of  a more general string is not excluded.
        !          2043:     Different  channel  identifiers   are   required   for   accessing
        !          2044:     different  files.   The  second  argument  may be omitted in which
        !          2045:     case association is to the standard input  or  output  file.   The
        !          2046:     chief  divergence between SNOBOL4 and SPITBOL is in the use of the
        !          2047:     third argument, where SPITBOL permits the very useful  feature  of
        !          2048:     dynamic  file  assignment.  The general form of the third argument
        !          2049:     is a string
        !          2050: 
        !          2051:         <f>,R<r>,C<c>,I<i>,X<x>...      where
        !          2052: 
        !          2053:     <f> is an optional file name which is placed first;
        !          2054: 
        !          2055:     ,   is a delimiter used to mark  off  remaining  items  which  are
        !          2056:         optional and may occur in any order;
        !          2057: 
        !          2058:     <r> is  the  maximum  record  length  in  characters  for the file
        !          2059:         (default values are documented in Section 12);
        !          2060: 
        !          2061:     <c> is a carriage control  character  or  string  needed  in  some
        !          2062:         implementations;
        !          2063: 
        !          2064:     <i> is   additional   channel   identification   needed   in  some
        !          2065:         implementations  in  the  absence  of  <f>  to  associate  the
        !          2066:         variable  with  a file attached by job control commands at the
        !          2067:         start of a SPITBOL run;
        !          2068: 
        !          2069:     <x> symbolises   additional   fields    needed    in    particular
        !          2070:         implementations.
        !          2071: 
        !          2072:     If  <f>  is  non-null,  when  the  statement is obeyed file <f> is
        !          2073:     opened and assigned to the channel  corresponding  to  the  second
        !          2074:     argument  and  normally  this  assignment should be performed once
        !          2075:     only.  If several variables are  to  be  associated  to  the  same
        !          2076:     channel,  <f>  should  be  omitted  from  all but the first of the
        !          2077:     INPUT/OUTPUT calls.
        !          2078: 
        !          2079: 
        !          2080: 
        !          2081: 
        !          2082: 
        !          2083:          MACRO SPITBOL V3.5
        !          2084:                                                    PAGE 30 - [5.35]
        !          2085:          Functions
        !          2086: 
        !          2087:     Alternatively <f> can be omitted from all INPUT/OUTPUT  statements
        !          2088:     relating  to  a  channel  provided  the  necessary assignments are
        !          2089:     performed  by  suitable  job  control  commands  before  execution
        !          2090:     starts.  Thus -
        !          2091:        INPUT(.IN,2,'INFILE');    OUTPUT(.OU,7,'OUF')
        !          2092:        INPUT(.IN,2);             OUTPUT(.OU,7)
        !          2093:     will  have the same effect if in the latter case INFILE , OUF have
        !          2094:     been suitably attached by JCL commands.  A call in  which  <f>  is
        !          2095:     omitted  but  some  other  item  is present in the third argument,
        !          2096:     alters the association of the channel  in  respect  of  that  item
        !          2097:     only.   E.g.  INPUT(.X,,',R72')  sets the maximum record length to
        !          2098:     72 characters.
        !          2099: 
        !          2100:     Error  messages  are  given  for   syntactically   invalid   third
        !          2101:     arguments  but  in  the  case  where  the  file corresponding to a
        !          2102:     syntactically valid file name  cannot  be  found,  then  statement
        !          2103:     failure  occurs  and  may  be  tested  for  in  the usual way by a
        !          2104:     conditional goto.  For the sake of portability and  compatibility,
        !          2105:     programmers  are  strongly  urged  to use integer second arguments
        !          2106:     (as in SNOBOL4) and short alphanumeric file  names  in  the  third
        !          2107:     argument.   Further  details, particular to an implementation, are
        !          2108:     given in Section 12.
        !          2109: 
        !          2110: 
        !          2111:  5.36  INSERT * -- Insert string in buffer
        !          2112:  5.36  INSERT * -- Insert string in buffer
        !          2113:  ____________ _ __ ______ ______ __ ______
        !          2114: 
        !          2115:     INSERT(BUFFER,INTEGER,INTEGER,STRING)
        !          2116: 
        !          2117:     The function INSERT is defined to return null, but  has  the  side
        !          2118:     effect  of  replacing  characters (pos, pos+1, ..., pos+length) in
        !          2119:     the designated BUFFER with the characters  of  STRING.   "Pos"  is
        !          2120:     given  by  the first INTEGER argument, and "length" by the second.
        !          2121:     Note that if "length"  is  not  equal  to  SIZE(string)  then  the
        !          2122:     trailing  contents  of  the  buffer  following  the  section to be
        !          2123:     replaced will have  to  be  moved  by  INSERT  to  accomodate  the
        !          2124:     STRING.
        !          2125: 
        !          2126:     If  the  inserted  string  cannot  fit,  or if the insertion would
        !          2127:     leave a 'gap' of undefined characters  in  the  buffer,  then  the
        !          2128:     INSERT call fails.
        !          2129: 
        !          2130:     If  the first argument is not a buffer type, then an error occurs.
        !          2131:     (No conversion is attempted since it would be pointless).
        !          2132: 
        !          2133: 
        !          2134: 
        !          2135: 
        !          2136: 
        !          2137: 
        !          2138: 
        !          2139: 
        !          2140: 
        !          2141: 
        !          2142: 
        !          2143: 
        !          2144: 
        !          2145: 
        !          2146: 
        !          2147:          MACRO SPITBOL V3.5
        !          2148:                                                    PAGE 31 - [5.37]
        !          2149:          Functions
        !          2150: 
        !          2151: 
        !          2152: 
        !          2153:  5.37  INTEGER * -- Test for Integer
        !          2154:  5.37  INTEGER * -- Test for Integer
        !          2155:  _____________ _ __ ____ ___ _______
        !          2156: 
        !          2157:     INTEGER(NUMERIC)
        !          2158: 
        !          2159:     INTEGER is a predicate function which succeeds if its argument  is
        !          2160:     integral.   It  fails  if  the  argument  cannot  be  converted to
        !          2161:     numeric or has a non-integral value.
        !          2162: 
        !          2163: 
        !          2164:  5.38  ITEM -- Select Array or Table Element
        !          2165:  5.38  ITEM -- Select Array or Table Element
        !          2166:  __________ __ ______ _____ __ _____ _______
        !          2167: 
        !          2168:     ITEM(ARRAY,INTEGER,INTEGER,....) or  ITEM(TABLE,ARGUMENT)
        !          2169: 
        !          2170:     ITEM returns the selected array or table element  by  name.   Note
        !          2171:     that  the use of ITEM is never necessary in SPITBOL because of the
        !          2172:     extended syntax for array references.
        !          2173: 
        !          2174: 
        !          2175:  5.39  LE -- Test for Less or Equal
        !          2176:  5.39  LE -- Test for Less or Equal
        !          2177:  ________ __ ____ ___ ____ __ _____
        !          2178: 
        !          2179:     LE(NUMERIC,NUMERIC)
        !          2180: 
        !          2181:     LE is a predicate function which succeeds if  its  first  argument
        !          2182:     is less than or equal to the second argument.
        !          2183: 
        !          2184: 
        !          2185: 
        !          2186: 
        !          2187: 
        !          2188: 
        !          2189: 
        !          2190: 
        !          2191: 
        !          2192: 
        !          2193: 
        !          2194: 
        !          2195: 
        !          2196: 
        !          2197: 
        !          2198: 
        !          2199: 
        !          2200: 
        !          2201: 
        !          2202: 
        !          2203: 
        !          2204: 
        !          2205: 
        !          2206: 
        !          2207: 
        !          2208: 
        !          2209: 
        !          2210: 
        !          2211: 
        !          2212: 
        !          2213: 
        !          2214: 
        !          2215:          MACRO SPITBOL V3.5
        !          2216:                                                    PAGE 32 - [5.40]
        !          2217:          Functions
        !          2218: 
        !          2219: 
        !          2220: 
        !          2221:  5.40  LEN -- Generate Specified Length Pattern
        !          2222:  5.40  LEN -- Generate Specified Length Pattern
        !          2223:  _________ __ ________ _________ ______ _______
        !          2224: 
        !          2225:     LEN(INTEGER) or LEN(EXPRESSION)
        !          2226: 
        !          2227:     LEN   generates  a  pattern  which  will  match  any  sequence  of
        !          2228:     characters of length  given  by  the  argument  which  must  be  a
        !          2229:     non-negative  integer.   If  the  argument is an expression, it is
        !          2230:     evaluated during pattern matching and must  yield  a  non-negative
        !          2231:     integer.
        !          2232: 
        !          2233: 
        !          2234:  5.41  LEQ * -- Test for Lexically Equal
        !          2235:  5.41  LEQ * -- Test for Lexically Equal
        !          2236:  _________ _ __ ____ ___ _________ _____
        !          2237: 
        !          2238:     LEQ(STRING,STRING)
        !          2239: 
        !          2240:     LEQ  is  a predicate which succeeds if its arguments are lexically
        !          2241:     equal.   LEQ  differs  from  IDENT  in  that  its  arguments   are
        !          2242:     converted to strings so that both the following succeed
        !          2243:        LEQ(10,'10')             LEQ(.ABC,'ABC')
        !          2244: 
        !          2245: 
        !          2246:  5.42  LGE * -- Test for Lexically Greater or Equal
        !          2247:  5.42  LGE * -- Test for Lexically Greater or Equal
        !          2248:  _________ _ __ ____ ___ _________ _______ __ _____
        !          2249: 
        !          2250:     LGE(STRING,STRING)
        !          2251: 
        !          2252:     LGE  is  a  predicate  which  succeeds  if  the  first argument is
        !          2253:     lexically greater than or equal to the second argument.
        !          2254: 
        !          2255: 
        !          2256:  5.43  LGT * -- Test for Lexically Greater
        !          2257:  5.43  LGT * -- Test for Lexically Greater
        !          2258:  _________ _ __ ____ ___ _________ _______
        !          2259: 
        !          2260:     LGT(STRING,STRING)
        !          2261: 
        !          2262:     LGT is a  predicate  which  succeeds  if  the  first  argument  is
        !          2263:     lexically greater than the second argument.
        !          2264: 
        !          2265: 
        !          2266:  5.44  LLE * -- Test for Lexically Less or Equal
        !          2267:  5.44  LLE * -- Test for Lexically Less or Equal
        !          2268:  _________ _ __ ____ ___ _________ ____ __ _____
        !          2269: 
        !          2270:     LLE(STRING,STRING)
        !          2271: 
        !          2272:     LLE  is  a  predicate  which  succeeds  if  the  first argument is
        !          2273:     lexically less than or equal to the second argument.
        !          2274: 
        !          2275: 
        !          2276: 
        !          2277: 
        !          2278: 
        !          2279: 
        !          2280: 
        !          2281: 
        !          2282: 
        !          2283: 
        !          2284: 
        !          2285: 
        !          2286: 
        !          2287:          MACRO SPITBOL V3.5
        !          2288:                                                    PAGE 33 - [5.45]
        !          2289:          Functions
        !          2290: 
        !          2291: 
        !          2292: 
        !          2293:  5.45  LLT * -- Test for Lexically Less
        !          2294:  5.45  LLT * -- Test for Lexically Less
        !          2295:  _________ _ __ ____ ___ _________ ____
        !          2296: 
        !          2297:     LLT(STRING,STRING)
        !          2298: 
        !          2299:     LLT is a  predicate  which  succeeds  if  the  first  argument  is
        !          2300:     lexically less than the second argument.
        !          2301: 
        !          2302: 
        !          2303:  5.46  LNE * -- Test for Lexically Not Equal
        !          2304:  5.46  LNE * -- Test for Lexically Not Equal
        !          2305:  _________ _ __ ____ ___ _________ ___ _____
        !          2306: 
        !          2307:     LNE(STRING,STRING)
        !          2308: 
        !          2309:     LNE  is  a predicate which succeeds if its arguments are lexically
        !          2310:     unequal.  LNE differs  from  DIFFER  in  that  its  arguments  are
        !          2311:     converted to strings so that both the following fail
        !          2312:        LNE(10,'10')                 LNE(.ABC,'ABC')
        !          2313: 
        !          2314: 
        !          2315:  5.47  LOAD -- Load External Function
        !          2316:  5.47  LOAD -- Load External Function
        !          2317:  __________ __ ____ ________ ________
        !          2318: 
        !          2319:     LOAD(STRING,STRING)
        !          2320: 
        !          2321:     LOAD  is  used  to  make  external  functions available to SPITBOL
        !          2322:     programs.  The first STRING is a prototype of the form:
        !          2323: 
        !          2324:        "function-name(type,type,...)result-type"
        !          2325: 
        !          2326:     The  indicated  types  can  be  any  of  "INTEGER",   "REAL"   (if
        !          2327:     implemented)  or  "STRING" in which case the value is converted to
        !          2328:     the designated type before being passed  to  (returned  from)  the
        !          2329:     external  function.  Any other name for a type leaves the value in
        !          2330:     an unconverted form.
        !          2331: 
        !          2332:     The second argument to LOAD is a library name where  the  function
        !          2333:     is to be found.
        !          2334: 
        !          2335:     LOAD  is  highly  implementation  specific and is not available in
        !          2336:     all implementations.  See Section 12 for details.
        !          2337: 
        !          2338: 
        !          2339:  5.48  LOCAL * -- Get Name of Local
        !          2340:  5.48  LOCAL * -- Get Name of Local
        !          2341:  ___________ _ __ ___ ____ __ _____
        !          2342: 
        !          2343:     LOCAL(NAME,INTEGER)
        !          2344: 
        !          2345:     The value returned is the NAME  of  the  indicated  local  of  the
        !          2346:     function  whose  name is given by the first argument.  LOCAL fails
        !          2347:     if the second argument is out of range (less than  1,  or  greater
        !          2348:     than the number of locals).
        !          2349: 
        !          2350: 
        !          2351: 
        !          2352: 
        !          2353: 
        !          2354: 
        !          2355: 
        !          2356: 
        !          2357:          MACRO SPITBOL V3.5
        !          2358:                                                    PAGE 34 - [5.49]
        !          2359:          Functions
        !          2360: 
        !          2361: 
        !          2362: 
        !          2363:  5.49  LPAD * -- Left Pad
        !          2364:  5.49  LPAD * -- Left Pad
        !          2365:  __________ _ __ ____ ___
        !          2366: 
        !          2367:     LPAD(STRING,INTEGER,STRING)
        !          2368: 
        !          2369:     LPAD  returns  the  result  obtained  by  padding  out  the  first
        !          2370:     argument on the  left  to  the  length  specified  by  the  second
        !          2371:     argument,  using  the  pad character supplied by the one character
        !          2372:     string third argument.  If the third argument is null or  omitted,
        !          2373:     a  blank  is  used as the pad character.  If the first argument is
        !          2374:     already long enough or too long, it is  returned  unchanged,  this
        !          2375:     always  being the case if the second argument is negative or zero.
        !          2376:     LPAD is useful for constructing columnar output.
        !          2377: 
        !          2378: 
        !          2379:  5.50  LT -- Test for Less
        !          2380:  5.50  LT -- Test for Less
        !          2381:  ________ __ ____ ___ ____
        !          2382: 
        !          2383:     LT(NUMERIC,NUMERIC)
        !          2384: 
        !          2385:     LT is a predicate function which succeeds if  its  first  argument
        !          2386:     is less than the second.
        !          2387: 
        !          2388: 
        !          2389:  5.51  NE -- Test for Not Equal
        !          2390:  5.51  NE -- Test for Not Equal
        !          2391:  ________ __ ____ ___ ___ _____
        !          2392: 
        !          2393:     NE(NUMERIC,NUMERIC)
        !          2394: 
        !          2395:     NE  is  a  predicate  function which succeeds if its two arguments
        !          2396:     are unequal.
        !          2397: 
        !          2398: 
        !          2399:  5.52  NOTANY -- Build Character Select Pattern
        !          2400:  5.52  NOTANY -- Build Character Select Pattern
        !          2401:  ____________ __ _____ _________ ______ _______
        !          2402: 
        !          2403:     NOTANY(STRING) or NOTANY(EXPRESSION)
        !          2404: 
        !          2405:     NOTANY returns a pattern which will match any single character  in
        !          2406:     the  subject  string,  provided  it  does  not occur in the string
        !          2407:     argument.  A null argument is not permitted.  If the  argument  is
        !          2408:     an  expression,  it  is evaluated during pattern matching and must
        !          2409:     yield a non-null string.
        !          2410: 
        !          2411: 
        !          2412: 
        !          2413: 
        !          2414: 
        !          2415: 
        !          2416: 
        !          2417: 
        !          2418: 
        !          2419: 
        !          2420: 
        !          2421: 
        !          2422: 
        !          2423: 
        !          2424: 
        !          2425: 
        !          2426: 
        !          2427:          MACRO SPITBOL V3.5
        !          2428:                                                    PAGE 35 - [5.53]
        !          2429:          Functions
        !          2430: 
        !          2431: 
        !          2432: 
        !          2433:  5.53  OPSYN * -- Equate Functions and Operators
        !          2434:  5.53  OPSYN * -- Equate Functions and Operators
        !          2435:  ___________ _ __ ______ _________ ___ _________
        !          2436: 
        !          2437:     OPSYN(NAME,NAME,INTEGER)
        !          2438: 
        !          2439:     In contrast with SNOBOL4, the second argument must  always  be  an
        !          2440:     already  defined  function name.  If the third argument is omitted
        !          2441:     or zero, the first argument must  be  a  function  name.   If  the
        !          2442:     third  argument  is 1 or 2 , the first argument must be resp.  one
        !          2443:     of the undefined unary or binary  operators  (sec  4.1).   In  all
        !          2444:     three  cases,  subsequent  use  of  the  first argument results in
        !          2445:     calling of the function corresponding to the second argument  with
        !          2446:     the  appropriate  arguments.   Note that names of system functions
        !          2447:     or operators cannot appear as the first argument.
        !          2448: 
        !          2449: 
        !          2450:  5.54  OUTPUT * -- Set Output Association
        !          2451:  5.54  OUTPUT * -- Set Output Association
        !          2452:  ____________ _ __ ___ ______ ___________
        !          2453: 
        !          2454:     OUTPUT(NAME,INTEGER,STRING) or OUTPUT(NAME,STRING,STRING)
        !          2455: 
        !          2456:     This function has  similar  arguments  and  behaves  similarly  to
        !          2457:     INPUT, which should be consulted for a detailed description (2).
        !          2458: 
        !          2459: 
        !          2460:  5.55  POS -- Define Positioning Pattern
        !          2461:  5.55  POS -- Define Positioning Pattern
        !          2462:  _________ __ ______ ___________ _______
        !          2463: 
        !          2464:     POS(INTEGER) or POS(EXPRESSION)
        !          2465: 
        !          2466:     POS  returns  a pattern which matches the null string provided the
        !          2467:     value  of  the  cursor  is  equal  to  the  non-negative   integer
        !          2468:     argument.   If  the  argument  is  an  expression, it is evaluated
        !          2469:     during pattern matching and must yield a non-negative integer.
        !          2470: 
        !          2471: 
        !          2472: 
        !          2473: 
        !          2474: 
        !          2475: 
        !          2476: 
        !          2477: 
        !          2478: 
        !          2479: 
        !          2480: 
        !          2481: 
        !          2482: 
        !          2483: 
        !          2484: 
        !          2485: 
        !          2486: 
        !          2487: 
        !          2488: 
        !          2489: 
        !          2490: 
        !          2491: 
        !          2492: 
        !          2493: 
        !          2494: 
        !          2495:          MACRO SPITBOL V3.5
        !          2496:                                                    PAGE 36 - [5.56]
        !          2497:          Functions
        !          2498: 
        !          2499: 
        !          2500: 
        !          2501:  5.56  PROTOTYPE -- Retrieve Prototype
        !          2502:  5.56  PROTOTYPE -- Retrieve Prototype
        !          2503:  _______________ __ ________ _________
        !          2504: 
        !          2505:     PROTOTYPE(ARRAY) or PROTOTYPE(TABLE)
        !          2506: 
        !          2507:     PROTOTYPE returns the first argument used in the ARRAY,  TABLE  or
        !          2508:     BUFFER function call which created the argument.
        !          2509: 
        !          2510: 
        !          2511:  5.57  REMDR -- Remainder
        !          2512:  5.57  REMDR -- Remainder
        !          2513:  ___________ __ _________
        !          2514: 
        !          2515:     REMDR(INTEGER,INTEGER)
        !          2516: 
        !          2517:     REMDR  returns the remainder of dividing the first argument by the
        !          2518:     second.  This has the same sign as the first argument.
        !          2519: 
        !          2520: 
        !          2521:  5.58  REPLACE -- Translate Characters
        !          2522:  5.58  REPLACE -- Translate Characters
        !          2523:  _____________ __ _________ __________
        !          2524: 
        !          2525:     REPLACE(STRING,STRING,STRING)
        !          2526: 
        !          2527:     REPLACE  returns  the  result  of  applying  the   transformations
        !          2528:     represented  by  the  second  and  third  arguments  to  the first
        !          2529:     argument.  REPLACE fails if the second  and  third  arguments  are
        !          2530:     unequal in length or null.
        !          2531: 
        !          2532: 
        !          2533:  5.59  REVERSE * -- Reverse String
        !          2534:  5.59  REVERSE * -- Reverse String
        !          2535:  _____________ _ __ _______ ______
        !          2536: 
        !          2537:     REVERSE(STRING)
        !          2538: 
        !          2539:     REVERSE returns the result of reversing its argument.  Thus
        !          2540:        REVERSE('ABC')            produces          'CBA'
        !          2541: 
        !          2542: 
        !          2543:  5.60  REWIND -- Reposition File
        !          2544:  5.60  REWIND -- Reposition File
        !          2545:  ____________ __ __________ ____
        !          2546: 
        !          2547:     REWIND(INTEGER) or REWIND(STRING)
        !          2548: 
        !          2549:     The  argument must have previously appeared as the second argument
        !          2550:     of a call of   INPUT or OUTPUT.  The file attached to the  channel
        !          2551:     is  repositioned  so  that the next read or write operation starts
        !          2552:     at the first record of the file.   Existing  associations  to  the
        !          2553:     file   are   unaffected.   REWIND  may  not  be  provided  in  all
        !          2554:     implementations - see Section 12.
        !          2555: 
        !          2556: 
        !          2557: 
        !          2558: 
        !          2559: 
        !          2560: 
        !          2561: 
        !          2562: 
        !          2563: 
        !          2564: 
        !          2565: 
        !          2566: 
        !          2567:          MACRO SPITBOL V3.5
        !          2568:                                                    PAGE 37 - [5.61]
        !          2569:          Functions
        !          2570: 
        !          2571: 
        !          2572: 
        !          2573:  5.61  RPAD * -- Right Pad
        !          2574:  5.61  RPAD * -- Right Pad
        !          2575:  __________ _ __ _____ ___
        !          2576: 
        !          2577:     RPAD(STRING,INTEGER,STRING)
        !          2578: 
        !          2579:     RPAD  returns  the  result  obtained  by  padding  out  the  first
        !          2580:     argument  on  the  right  to  the  length  specified by the second
        !          2581:     argument, using the pad character supplied by  the  one  character
        !          2582:     string  third argument.  If the third argument is null or omitted,
        !          2583:     a blank is used as the pad character.  If the  first  argument  is
        !          2584:     already  long  enough  or too long, it is returned unchanged, this
        !          2585:     always being the case if the second argument is negative or  zero.
        !          2586:     RPAD is useful for constructing columnar output.
        !          2587: 
        !          2588: 
        !          2589:  5.62  RPOS -- Define Positioning Pattern
        !          2590:  5.62  RPOS -- Define Positioning Pattern
        !          2591:  __________ __ ______ ___________ _______
        !          2592: 
        !          2593:     RPOS(INTEGER) or RPOS(EXPRESSION)
        !          2594: 
        !          2595:     RPOS  returns a pattern which matches the null string provided the
        !          2596:     indicated number  of  characters  remain  to  be  matched  in  the
        !          2597:     subject   string.   If  the  argument  is  an  expression,  it  is
        !          2598:     evaluated during pattern matching and must  yield  a  non-negative
        !          2599:     integer.
        !          2600: 
        !          2601: 
        !          2602:  5.63  RSORT -- Reverse Sort
        !          2603:  5.63  RSORT -- Reverse Sort
        !          2604:  ___________ __ _______ ____
        !          2605: 
        !          2606:     RSORT(ARRAY or TABLE,INTEGER or NAME)
        !          2607: 
        !          2608:     Performs  a sort in descending (reverse) order of key on the first
        !          2609:     argument.  Consult SORT for details.
        !          2610: 
        !          2611: 
        !          2612:  5.64  RTAB -- Create Tabbing Pattern
        !          2613:  5.64  RTAB -- Create Tabbing Pattern
        !          2614:  __________ __ ______ _______ _______
        !          2615: 
        !          2616:     RTAB(INTEGER) or RTAB(EXPRESSION)
        !          2617: 
        !          2618:     RTAB returns a pattern which matches from the current location  up
        !          2619:     to  the  point  where the indicated number of characters remain to
        !          2620:     be matched.  The argument must be a non-negative integer.  If  the
        !          2621:     argument   is  an  expression,  it  is  evaluated  during  pattern
        !          2622:     matching and must yield a non-negative integer.
        !          2623: 
        !          2624: 
        !          2625: 
        !          2626: 
        !          2627: 
        !          2628: 
        !          2629: 
        !          2630: 
        !          2631: 
        !          2632: 
        !          2633: 
        !          2634: 
        !          2635: 
        !          2636: 
        !          2637:          MACRO SPITBOL V3.5
        !          2638:                                                    PAGE 38 - [5.65]
        !          2639:          Functions
        !          2640: 
        !          2641: 
        !          2642: 
        !          2643:  5.65  SETEXIT * -- Set Error Exit
        !          2644:  5.65  SETEXIT * -- Set Error Exit
        !          2645:  _____________ _ __ ___ _____ ____
        !          2646: 
        !          2647:     SETEXIT(NAME) or SETEXIT()
        !          2648: 
        !          2649:     SETEXIT allows interception of  execution  errors,  including  any
        !          2650:     detected  during calls of CODE and EVAL .  The argument is a label
        !          2651:     to  which  control  is  passed  if  a  subsequent  error   occurs,
        !          2652:     providing  that  the  value  of the keyword &ERRLIMIT is non-zero.
        !          2653:     The value of &ERRLIMIT is decremented when the error trap  occurs.
        !          2654:     A  SETEXIT  call with a null argument causes cancellation of error
        !          2655:     intercepts.  A subsequent error will terminate execution as  usual
        !          2656:     with  an  error  message.   The  result returned by SETEXIT is the
        !          2657:     previous intercept setting (i.e.  a  label  name  or  null  if  no
        !          2658:     intercept  was  set).  This  can  be  used to save and restore the
        !          2659:     SETEXIT conditions recursively.  The  error  routine  may  inspect
        !          2660:     the  error code and text   in &ERRTYPE and &ERRTEXT , and take one
        !          2661:     of the actions -
        !          2662: 
        !          2663: 
        !          2664:      1.  Terminate execution by transferring  to  the  special  system
        !          2665:          label,   ABORT  .   This causes error processing to resume as
        !          2666:          though no error intercept had been set.
        !          2667: 
        !          2668:      2.  Branch to the special system label CONTINUE  .   This  causes
        !          2669:          execution  to  resume by branching to the failure exit of the
        !          2670:          statement in error.
        !          2671: 
        !          2672:      3.  Continue execution elsewhere by branching to another  section
        !          2673:          of  the  program.   If  the error occurred inside a function,
        !          2674:          execution is still 'down a level'.
        !          2675: 
        !          2676:      4.  Branch  to  label  RETURN  ,  FRETURN  ,   NRETURN   provided
        !          2677:          &FNCLEVEL  is  non-zero.   This  avoids possible difficulties
        !          2678:          with 3.
        !          2679: 
        !          2680:     The occurrence of  an  error  cancels  the  intercept.   An  error
        !          2681:     routine  must  reissue  a SETEXIT call if error interception is to
        !          2682:     continue.
        !          2683: 
        !          2684: 
        !          2685: 
        !          2686: 
        !          2687: 
        !          2688: 
        !          2689: 
        !          2690: 
        !          2691: 
        !          2692: 
        !          2693: 
        !          2694: 
        !          2695: 
        !          2696: 
        !          2697: 
        !          2698: 
        !          2699: 
        !          2700: 
        !          2701:          MACRO SPITBOL V3.5
        !          2702:                                                    PAGE 39 - [5.66]
        !          2703:          Functions
        !          2704: 
        !          2705: 
        !          2706: 
        !          2707:  5.66  SIZE -- Get String or Buffer Size
        !          2708:  5.66  SIZE -- Get String or Buffer Size
        !          2709:  __________ __ ___ ______ __ ______ ____
        !          2710: 
        !          2711:     SIZE(STRING or BUFFER)
        !          2712: 
        !          2713:     SIZE returns an  integer  count  of  the  defined  length  of  its
        !          2714:     argument.
        !          2715: 
        !          2716: 
        !          2717:  5.67  SORT * -- Sort
        !          2718:  5.67  SORT * -- Sort
        !          2719:  __________ _ __ ____
        !          2720: 
        !          2721:     SORT(ARRAY or TABLE,INTEGER or NAME)
        !          2722: 
        !          2723:     This  routine  sorts  the  contents  of  the ARRAY or  TABLE first
        !          2724:     argument in ascending order of key.  It differs from   RSORT  only
        !          2725:     in  that  the  latter  sorts  in  descending order of key.  If the
        !          2726:     first  argument  is  an  ARRAY  it  must  be  of   one   dimension
        !          2727:     (subsequently  referred  to  as  a  VECTOR ), or two dimensions (a
        !          2728:     MATRIX ).  Where the argument is a TABLE  ,  it  is  converted  by
        !          2729:     SORT  to an array of 2 dimensions, the first column containing the
        !          2730:     reference or key item and the second the  value,  in  exactly  the
        !          2731:     same  way as  results from a call to CONVERT . This is then sorted
        !          2732:     just as any other two dimensional array.  In all cases, the  items
        !          2733:     to  be  sorted  may  be  of mixed dataypes and the sorting is done
        !          2734:     primarily on datatype of key, using lexical ordering  of  datatype
        !          2735:     names,  and secondarily on value.  Thus items of similar datatypes
        !          2736:     become contiguously grouped in sorted order.  The  only  deviation
        !          2737:     from  this  rule  is that mixed  INTEGER and REAL (NUMERIC ) items
        !          2738:     are sorted as a single group and strings which  can  be  converted
        !          2739:     to  NUMERIC  are  compared  numerically  against NUMERIC keys.  In
        !          2740:     particular the NULL string is regarded as 0 or 0.0  in  comparison
        !          2741:     with  them.   Note  that  compared  numerically,  100  >  "20" but
        !          2742:     compared lexically "100" < "20".  A second argument, if  specified
        !          2743:     for  an  ARRAY  or  TABLE,  must  be an integer corresponding to a
        !          2744:     column index (1 or 2 for a TABLE). The keys are  then  taken  from
        !          2745:     this  column,  and  during the sort, complete rows are permuted to
        !          2746:     the order determined by key values.  If  the  second  argument  is
        !          2747:     omitted,  the  default  column  used  is that corresponding to the
        !          2748:     smallest  value  of  the   second   index   (e.g   -2   in   M   =
        !          2749:     ARRAY('10,-2:+2')).   The  sorting  method  used  is  stable  with
        !          2750:     respect to non-interchange of items having  equal  keys,  so  that
        !          2751:     repeated  sorting  on  successive  columns may be used to effect a
        !          2752:     total ordering.
        !          2753: 
        !          2754:     In the case of a VECTOR, the optional second argument may  be  the
        !          2755:     NAME   of a field of a programmer defined datatype created by DATA
        !          2756:     . In this case, if any of the values in the  VECTOR  are  of  this
        !          2757:     type,  the  contents  of the field corresponding to NAME  are used
        !          2758:     as the key.  If the second argument is  omitted,  the  sorting  is
        !          2759:     carried out by using the values the VECTOR contains as keys.
        !          2760: 
        !          2761: 
        !          2762: 
        !          2763: 
        !          2764: 
        !          2765: 
        !          2766: 
        !          2767:          MACRO SPITBOL V3.5
        !          2768:                                                    PAGE 40 - [5.67]
        !          2769:          Functions
        !          2770: 
        !          2771:     The  sort  method  used is Heapsort (see for instance Horowitz and
        !          2772:     Sahni, "Fundamentals of Data Structures",  Pitman  1977)  modified
        !          2773:     so  that  no  interchanging of equal keys occurs.  It is efficient
        !          2774:     in usage of both space and time, the time taken to  sort  N  items
        !          2775:     being  proportional  to  N * log(N).   The  aggregate  obtained is
        !          2776:     always a sorted copy of the original.  No extra store is used  for
        !          2777:     the  sort  except  in  the case of a TABLE, where space sufficient
        !          2778:     for conversion to an ARRAY is taken.  Examples of calls are
        !          2779:     *  Assume USERS is an ARRAY of programmer defined datatypes
        !          2780:     *  of the type created by       DATA('COMPUSER(NAME,TYME)')
        !          2781:           SUS = RSORT(SORT(USERS,.NAME),.TYME)
        !          2782:     which creates an array sorted  primarily  by  tyme  in  descending
        !          2783:     order  and secondarily by name in alphabetic order.
        !          2784:           MATX = SORT(SORT(SORT(MATX,3),2))
        !          2785:     which sorts MATX respectively by columns 3, 2, 1.
        !          2786:           V = SORT(V)
        !          2787:     which sorts V  by its elements.
        !          2788: 
        !          2789: 
        !          2790:  5.68  SPAN -- Create Spanning Pattern
        !          2791:  5.68  SPAN -- Create Spanning Pattern
        !          2792:  __________ __ ______ ________ _______
        !          2793: 
        !          2794:     SPAN(STRING) or SPAN(EXPRESSION)
        !          2795: 
        !          2796:     SPAN  creates  a  pattern  which, starting from the current cursor
        !          2797:     position, will match the longest non-null sequence  of  characters
        !          2798:     drawn  from  the  character  set  contained  in the argument.  The
        !          2799:     argument is not permitted to be  null.   If  the  argument  is  an
        !          2800:     expression,  it  is  evaluated  during  pattern  matching and must
        !          2801:     yield a non-null string.
        !          2802: 
        !          2803: 
        !          2804:  5.69  STOPTR * -- Stop Trace
        !          2805:  5.69  STOPTR * -- Stop Trace
        !          2806:  ____________ _ __ ____ _____
        !          2807: 
        !          2808:     STOPTR(NAME,STRING)
        !          2809: 
        !          2810:     STOPTR  terminates  tracing  for  the  name  given  by  the  first
        !          2811:     argument.   The  second  argument  designates the respect in which
        !          2812:     the trace is to be stopped and consists  of  one  of  the  strings
        !          2813:     listed under the description of TRACE.
        !          2814: 
        !          2815: 
        !          2816: 
        !          2817: 
        !          2818: 
        !          2819: 
        !          2820: 
        !          2821: 
        !          2822: 
        !          2823: 
        !          2824: 
        !          2825: 
        !          2826: 
        !          2827: 
        !          2828: 
        !          2829: 
        !          2830: 
        !          2831: 
        !          2832: 
        !          2833:          MACRO SPITBOL V3.5
        !          2834:                                                    PAGE 41 - [5.70]
        !          2835:          Functions
        !          2836: 
        !          2837: 
        !          2838: 
        !          2839:  5.70  SUBSTR * -- Extract Substring
        !          2840:  5.70  SUBSTR * -- Extract Substring
        !          2841:  ____________ _ __ _______ _________
        !          2842: 
        !          2843:     SUBSTR(STRING or BUFFER,INTEGER,INTEGER)
        !          2844: 
        !          2845:     Extracts   a  substring  from  the  first  argument.   The  second
        !          2846:     argument specifies the first character (1 = start of  string)  and
        !          2847:     the  third  argument  gives  the number of characters.  An omitted
        !          2848:     third argument specifies all remaining characters of  the  string.
        !          2849:     Improper substrings cause statement failure.
        !          2850: 
        !          2851:     Note  that  no  conversion  to  string  is needed in the case of a
        !          2852:     BUFFER argument, the substring  is  extracted  directly  from  the
        !          2853:     buffer making SUBSTR quite efficient when working with buffers.
        !          2854: 
        !          2855: 
        !          2856:  5.71  TAB -- Create Tabbing Pattern
        !          2857:  5.71  TAB -- Create Tabbing Pattern
        !          2858:  _________ __ ______ _______ _______
        !          2859: 
        !          2860:     TAB(INTEGER) or TAB(EXPRESSION)
        !          2861: 
        !          2862:     TAB  returns  a pattern which matches from the current location up
        !          2863:     to the point where the indicated number of  characters  have  been
        !          2864:     matched.   The  argument  must  be a non-negative integer.  If the
        !          2865:     argument  is  an  expression,  it  is  evaluated  during   pattern
        !          2866:     matching and must yield a non-negative integer.
        !          2867: 
        !          2868: 
        !          2869:  5.72  TABLE * -- Create Table
        !          2870:  5.72  TABLE * -- Create Table
        !          2871:  ___________ _ __ ______ _____
        !          2872: 
        !          2873:     TABLE(INTEGER,,ARG)
        !          2874: 
        !          2875:     The  TABLE  function  creates  an associative table as in SNOBOL4.
        !          2876:     However in SPITBOL, the table is implemented internally  using  an
        !          2877:     efficient   hashing algorithm.  The integer argument is the number
        !          2878:     of hash headers used.  If it is omitted, 11 is  used  by  default.
        !          2879:     If  N  is  the number of entries in the table, and H is the number
        !          2880:     of hash headers, the average number of probes  to  find  an  entry
        !          2881:     rises  from  about 1.0 for small N, to N/2H if N is large compared
        !          2882:     with H.  Since the overhead for hash headers is small compared  to
        !          2883:     the  size of a table element, a useful guide is to use as argument
        !          2884:     an estimate of the number of entries to be stored  in  the  table.
        !          2885:     Any  second  argument  (permitted  for  SNOBOL4  compatibility) is
        !          2886:     always ignored.  The optional third argument is a value  which  it
        !          2887:     is  desired  to  have  returned  instead of the default NULL, when
        !          2888:     table look-up is performed using a key which has not been  entered
        !          2889:     into  the  TABLE.   This  is similar in effect to the usage of the
        !          2890:     second argument of ARRAY.  In contrast  with  SNOBOL4,  where  the
        !          2891:     first  reference  to an entry automatically creates a table entry,
        !          2892:     in  SPITBOL  an  entry  is  inserted  in  a  table  only  when  an
        !          2893:     assignment   is   explicitly  made.   Thus  table  look-up  for  a
        !          2894:     currently missing key does not create an entry for  that  key  and
        !          2895:     may be freely used.
        !          2896: 
        !          2897: 
        !          2898: 
        !          2899: 
        !          2900: 
        !          2901:          MACRO SPITBOL V3.5
        !          2902:                                                    PAGE 42 - [5.73]
        !          2903:          Functions
        !          2904: 
        !          2905: 
        !          2906: 
        !          2907:  5.73  TIME -- Get Timer Value
        !          2908:  5.73  TIME -- Get Timer Value
        !          2909:  __________ __ ___ _____ _____
        !          2910: 
        !          2911:     TIME()
        !          2912: 
        !          2913:     TIME  returns the integer number of milliseconds of processor time
        !          2914:     since the start of execution.
        !          2915: 
        !          2916: 
        !          2917:  5.74  TRACE * -- Initiate Trace
        !          2918:  5.74  TRACE * -- Initiate Trace
        !          2919:  ___________ _ __ ________ _____
        !          2920: 
        !          2921: 
        !          2922:     The TRACE function, which is quite invaluable as a debugging  aid,
        !          2923:     initiates  a  trace  of  the item whose name is given by the first
        !          2924:     argument.  The second argument specifies the sense  of  the  trace
        !          2925:     as follows -
        !          2926: 
        !          2927: 
        !          2928:             'A' or 'ACCESS'               access
        !          2929:             'V' or 'VALUE' or null        value
        !          2930:             'K' or 'KEYWORD'              keyword
        !          2931:             'L' or 'LABEL'                label
        !          2932:             'F' or 'FUNCTION'             function call and return
        !          2933:             'C' or 'CALL'                 function call
        !          2934:             'R' or 'RETURN'               function return
        !          2935: 
        !          2936:     The  access trace mode introduced in SPITBOL consists of producing
        !          2937:     trace output each  time  an  access  traced  item  is  referenced.
        !          2938:     Attempts  to trace a function before a DEFINE statement for it has
        !          2939:     been executed will fail.  If &STLIMIT  is  negative,  STCOUNT  may
        !          2940:     not  be  traced.  To give a visual impression of depth of nesting,
        !          2941:     a letter "I" is included in the trace output for  each  additional
        !          2942:     level of function call.
        !          2943: 
        !          2944: 
        !          2945:  5.75  TRIM -- Trim Trailing Blanks
        !          2946:  5.75  TRIM -- Trim Trailing Blanks
        !          2947:  __________ __ ____ ________ ______
        !          2948: 
        !          2949:     TRIM(STRING)
        !          2950: 
        !          2951:     TRIM  returns  the  result  of  trimming  trailing blanks from the
        !          2952:     argument string.
        !          2953: 
        !          2954: 
        !          2955:  5.76  UNLOAD * -- Unload Function
        !          2956:  5.76  UNLOAD * -- Unload Function
        !          2957:  ____________ _ __ ______ ________
        !          2958: 
        !          2959:     UNLOAD(NAME)
        !          2960: 
        !          2961:     NAME is the name of an external function which is to be  unloaded.
        !          2962:     The  names  of  user defined functions may also appear in calls to
        !          2963:     UNLOAD in which case the function becomes undefined.
        !          2964: 
        !          2965: 
        !          2966: 
        !          2967: 
        !          2968: 
        !          2969: 
        !          2970: 
        !          2971:          MACRO SPITBOL V3.5
        !          2972:                                                    PAGE 43 - [6]
        !          2973:          Keywords
        !          2974: 
        !          2975: 
        !          2976: 
        !          2977:                             *---------------*
        !          2978:                               [6]  Keywords
        !          2979:                             | [6]  Keywords |
        !          2980:                             *---------------*
        !          2981: 
        !          2982:     The following is a list of the keywords  implemented  in  SPITBOL.
        !          2983:     The  notation  (R)  after  the name indicates that the keyword may
        !          2984:     only be read so that attempts to assign to it will  result  in  an
        !          2985:     error.   With  the  exception  of  &STLIMIT,  values  assigned  to
        !          2986:     numeric keywords  must be in the range 0 to MXLEN .
        !          2987: 
        !          2988: 
        !          2989:      1.  &ABEND : Normally set to zero.  If it is set  to  a  non-zero
        !          2990:          value  at  the  end of execution,  an ABEND dump may be given
        !          2991:          if supported by the implementation.
        !          2992: 
        !          2993:      2.  &ABORT (R) :  Contains the pattern ABORT .
        !          2994: 
        !          2995:      3.  &ALPHABET (R) : Contains the full character set of  the  host
        !          2996:          computer in natural collating sequence.
        !          2997: 
        !          2998:      4.  &ANCHOR  :  Set to one for anchored pattern matching mode and
        !          2999:          to zero for  unanchored  mode.   Initial  value  is  zero  to
        !          3000:          correspond  with  SNOBOL4.   However  unanchored  matching is
        !          3001:          needed only rarely and is liable  to  be  very  expensive  in
        !          3002:          runtime  unless  carefully  used,  so  in  general it is good
        !          3003:          practice to start programs with the statement
        !          3004:              &ANCHOR = 1
        !          3005: 
        !          3006:      5.  &ARB (R) :  Contains the pattern ARB .
        !          3007: 
        !          3008:      6.  &BAL (R) :  Contains the pattern BAL .
        !          3009: 
        !          3010:      7.  &CODE  :  Initially  zero.   In  implementations  where   the
        !          3011:          concept   makes  sense,  values  found  to  be  in  &CODE  at
        !          3012:          termination are used as ending codes (Section 12).
        !          3013: 
        !          3014:      8.  &DUMP : The standard value is zero.  If the value is zero  at
        !          3015:          the  end  of  execution,  then  no symbolic dump is given.  A
        !          3016:          value of one gives a dump including values  of  keywords  and
        !          3017:          natural  variables.   If  the value is two, the dump includes
        !          3018:          non-null array, table and program defined  datatype  elements
        !          3019:          as  well.  The dump format is self explanatory and deals with
        !          3020:          the case of branched  structures  including  circular  lists.
        !          3021:          If  the  value exceeds two, an  ABEND dump may be produced as
        !          3022:          well if the implementation supports this.
        !          3023: 
        !          3024: 
        !          3025: 
        !          3026: 
        !          3027: 
        !          3028: 
        !          3029: 
        !          3030: 
        !          3031: 
        !          3032: 
        !          3033: 
        !          3034:          MACRO SPITBOL V3.5
        !          3035:                                                    PAGE 44 - [6]
        !          3036:          Keywords
        !          3037: 
        !          3038: 
        !          3039:      9.  &ERRLIMIT :  The  maximum  number  of  errors  which  can  be
        !          3040:          trapped  using  the  SETEXIT function. &ERRLIMIT is initially
        !          3041:          zero and when set non-zero by assignment, it  is  decremented
        !          3042:          each  time  a  SETEXIT trap occurs.  SETEXIT has no effect on
        !          3043:          normal error processing if &ERRLIMIT is zero.
        !          3044: 
        !          3045:     10.  &ERRTEXT : If an  execution  error  occurs,  then  the  error
        !          3046:          message  text  corresponding to the error code is stored as a
        !          3047:          string in &ERRTEXT.  It is possible to  assign  a  string  to
        !          3048:          &ERRTEXT  which  is then used in a subsequent error report if
        !          3049:          &ERRTYPE is assigned  a  value  out  of  the  range  used  by
        !          3050:          SPITBOL  itself.  Such an assignment does not signal an error
        !          3051:          as is the case with &ERRTYPE.
        !          3052: 
        !          3053:     11.  &ERRTYPE : If an execution error occurs, then the error  code
        !          3054:          is  stored  as  an  integer  in  &ERRTYPE.  &ERRTYPE  may  be
        !          3055:          assigned  a  value  in  which  case  an  immediate  error  is
        !          3056:          signalled.   This may be useful in reporting program detected
        !          3057:          errors.  Error codes used by  SPITBOL  all  fall  below  300.
        !          3058:          Values  in  &ERRTEXT and &ERRTYPE are useful in SETEXIT error
        !          3059:          intercept routines.
        !          3060: 
        !          3061:     12.  &FAIL (R) :  Contains the pattern FAIL .
        !          3062: 
        !          3063:     13.  &FENCE (R) :  Contains the pattern FENCE .
        !          3064: 
        !          3065:     14.  &FNCLEVEL (R) : Contains the current function nesting  level.
        !          3066: 
        !          3067:     15.  &FTRACE  :  The  standard  value  is  zero.   If  it  is  set
        !          3068:          positive, each function  call  and  return  is  traced.   The
        !          3069:          value  of &FTRACE is decremented  for each trace line printed
        !          3070:          until the value reaches zero again.
        !          3071: 
        !          3072:     16.  &INPUT : Set to one for normal  input  (standard  value).  If
        !          3073:          set to zero, all input associations are ignored.
        !          3074: 
        !          3075:     17.  &LASTNO  (R)  :  Contains  the  number  of the last statement
        !          3076:          executed.
        !          3077: 
        !          3078:     18.  &MAXLNGTH : Contains the  maximum  permitted  string  length.
        !          3079:          At  the  start  of execution its value is that given by MXLEN
        !          3080:          (Section 12). It may be set to  smaller values but not  to  a
        !          3081:          value exceeding MXLEN .
        !          3082: 
        !          3083:     19.  &OUTPUT  :  Set to one for normal output (standard value). If
        !          3084:          set to zero, all output associations are ignored.
        !          3085: 
        !          3086:     20.  &PROFILE :  When  set  to  zero  (the   default),   statement
        !          3087:          profiling  is disabled.  When set to one, statement profiling
        !          3088:          is enabled.  When statement  profiling  is  enabled,  SPITBOL
        !          3089:          keeps  track  of   the  count of each statement executed, and
        !          3090:          the  amount  of  central  processor  time   accumulated   for
        !          3091:          executing  each  statement.   If  profiling is enabled at any
        !          3092:          time during an execution, the accumulated profile is  printed
        !          3093:          on  the  standard output channel when the program terminates.
        !          3094: 
        !          3095: 
        !          3096:          MACRO SPITBOL V3.5
        !          3097:                                                    PAGE 45 - [6]
        !          3098:          Keywords
        !          3099: 
        !          3100:          The profile also indicates the  average  time  for  executing
        !          3101:          each statement.
        !          3102: 
        !          3103:          If  &PROFILE  is  set  to  two,  it  acts  as in the case for
        !          3104:          &PROFILE=1, except that function calls  are  charged  to  the
        !          3105:          statements which contain them.
        !          3106: 
        !          3107:          &PROFILE  is  not  available  in all implementations, and for
        !          3108:          some machines where processor  time  is  not  available,  the
        !          3109:          time  indicated may be wall time.  In all cases, the enabling
        !          3110:          of the profile adds additional time to the execution, so  the
        !          3111:          times indicated should be viewed as relative.
        !          3112: 
        !          3113:     21.  &REM (R) :  Contains the pattern REM .
        !          3114: 
        !          3115:     22.  &RTNTYPE  (R)  :  Contains  'RETURN',  'FRETURN' or 'NRETURN'
        !          3116:          depending on  the  type  of  function  return  most  recently
        !          3117:          executed.
        !          3118: 
        !          3119:     23.  &STCOUNT  :  Contains  a  count  of  the number of statements
        !          3120:          executed unless &STLIMIT is negative.
        !          3121: 
        !          3122:     24.  &STLIMIT : The maximum number of statements permitted  to  be
        !          3123:          executed.    Initially   50000  and  with  an  implementation
        !          3124:          dependent maximum (Section 12)  beyond  which  it  cannot  be
        !          3125:          set.    To  inhibit  this  check  on  numbers  of  statements
        !          3126:          executed, assign a negative value to the keyword.  Thus
        !          3127:                  &STLIMIT = -1
        !          3128:          is equivalent to &STLIMIT = "infinity". This will  result  in
        !          3129:          a  marginal  execution  speed  up  since  count  updating and
        !          3130:          checking is omitted.  The value of  &STCOUNT  remains  frozen
        !          3131:          at  the  value reached when &STLIMIT was set negative and the
        !          3132:          number of statements executed is omitted from  the  execution
        !          3133:          statistics.   Tracing  of  STCOUNT becomes no longer possible
        !          3134:          since its value is not incremented.
        !          3135: 
        !          3136:     25.  &STNO (R) : The number of the current statement.
        !          3137: 
        !          3138:     26.  &SUCCEED (R) :  Contains the pattern SUCCEED .
        !          3139: 
        !          3140:     27.  &TRACE : Initial value of zero suppresses trace  output.   If
        !          3141:          assigned  a positive value, trace output is generated and for
        !          3142:          each line printed &TRACE is  decremented  by  one  until  the
        !          3143:          value reaches zero again.
        !          3144: 
        !          3145:     28.  &TRIM  :  Set  to zero for normal input mode (default value).
        !          3146:          If  the  value  is  set  non-zero,  all  input  records   are
        !          3147:          automatically  trimmed  (trailing  blanks  are removed).  For
        !          3148:          operating systems  having  file  formats  in  which  variable
        !          3149:          length   records  may  have  trailing  blanks  suppressed,  a
        !          3150:          setting of zero does not imply that  padding  to  a  standard
        !          3151:          size  occurs,  merely  that  any  trailing  blanks  which are
        !          3152:          actually present will be preserved.  For  most  applications,
        !          3153:          initialising the value to 1 is to be recommended.
        !          3154: 
        !          3155: 
        !          3156: 
        !          3157: 
        !          3158:          MACRO SPITBOL V3.5
        !          3159:                                                    PAGE 46 - [7]
        !          3160:          Program Listing and Control Cards
        !          3161: 
        !          3162: 
        !          3163: 
        !          3164:                 *----------------------------------------*
        !          3165:                   [7]  Program Listing and Control Cards
        !          3166:                 | [7]  Program Listing and Control Cards |
        !          3167:                 *----------------------------------------*
        !          3168: 
        !          3169:     Normally  a  listing  of  the  source program is produced in which
        !          3170:     statements are prefixed with a  statement  number.   This  listing
        !          3171:     usually  starts  with  a  heading identifying the SPITBOL version,
        !          3172:     and giving date  and  time  of  run.   Where  this  is  considered
        !          3173:     inappropriate  it  may  be  suppressed  (Section  12). Many of the
        !          3174:     control cards to be  described  permit  choice  of  other  listing
        !          3175:     options.   Control  cards are identified by a minus sign in column
        !          3176:     one.  They may occur anywhere in a source program and take  effect
        !          3177:     when  they  are encountered.  Most of them are special features of
        !          3178:     SPITBOL and are not available in  SNOBOL4.   The  full  names  are
        !          3179:     given  for  each  of  them, but they may be abbreviated since only
        !          3180:     the first four characters are significant to the compiler.
        !          3181: 
        !          3182: 
        !          3183:  7.1  Listing Control Cards
        !          3184:  7.1  Listing Control Cards
        !          3185:  ____________ _______ _____
        !          3186: 
        !          3187:     Listing control cards are used to  alter  the  appearance  of  the
        !          3188:     listing.   They  have no other effect on compilation or execution.
        !          3189:     Listing control cards always occur individually.
        !          3190: 
        !          3191: 
        !          3192: 
        !          3193: 
        !          3194:  7.1.1  -EJECT
        !          3195:  7.1.1  -EJECT
        !          3196: 
        !          3197:     The -EJECT control card  causes  the  compilation  listing  to  be
        !          3198:     skipped  to  the  top  of  the  next  page.  The current title and
        !          3199:     subtitle (if any) are printed at the top of the page.
        !          3200: 
        !          3201: 
        !          3202: 
        !          3203: 
        !          3204:  7.1.2  -SPACE
        !          3205:  7.1.2  -SPACE
        !          3206: 
        !          3207:     The -SPACE control  card  causes  spaces  to  be  skipped  on  the
        !          3208:     current  page.  If -SPACE occurs with no operand, then one line is
        !          3209:     skipped.  Alternatively, an  unsigned  integer  can  be  given  in
        !          3210:     columns  8-72  which represents the number of lines to be skipped.
        !          3211:     If there is insufficient space on the current  page,  -SPACE  acts
        !          3212:     like  -EJECT  and  the  listing  is  spaced to the top of the next
        !          3213:     page.
        !          3214: 
        !          3215: 
        !          3216: 
        !          3217: 
        !          3218: 
        !          3219: 
        !          3220: 
        !          3221: 
        !          3222: 
        !          3223: 
        !          3224: 
        !          3225:          MACRO SPITBOL V3.5
        !          3226:                                                    PAGE 47 - [7.1.3]
        !          3227:          Program Listing and Control Cards
        !          3228: 
        !          3229:  7.1.3  -TITLE
        !          3230:  7.1.3  -TITLE
        !          3231: 
        !          3232:     This card supplies a title for the source  program  listing.   The
        !          3233:     text  of  the title is taken from columns 8-72 of the -TITLE card.
        !          3234:     The subtitle is cleared to blanks, and an eject to the  next  page
        !          3235:     occurs next time a line is listed.
        !          3236: 
        !          3237: 
        !          3238:  7.1.4  -STITL
        !          3239:  7.1.4  -STITL
        !          3240: 
        !          3241:     The  -STITL  card  is  used  to  supply  a subtitle for the source
        !          3242:     program listing.  The text of the subtitle is taken  from  columns
        !          3243:     8-72  of  the -STITL card.  An eject occurs to the top of the next
        !          3244:     page next time a line is listed and the  current  title  (if  any)
        !          3245:     and  the  newly  supplied subtitle are printed.  If both title and
        !          3246:     subtitle are to be changed, then the -TITLE  card  should  precede
        !          3247:     the -STITL card.
        !          3248: 
        !          3249: 
        !          3250: 
        !          3251: 
        !          3252: 
        !          3253: 
        !          3254: 
        !          3255: 
        !          3256: 
        !          3257: 
        !          3258: 
        !          3259: 
        !          3260: 
        !          3261: 
        !          3262: 
        !          3263: 
        !          3264: 
        !          3265: 
        !          3266: 
        !          3267: 
        !          3268: 
        !          3269: 
        !          3270: 
        !          3271: 
        !          3272: 
        !          3273: 
        !          3274: 
        !          3275: 
        !          3276: 
        !          3277: 
        !          3278: 
        !          3279: 
        !          3280: 
        !          3281: 
        !          3282: 
        !          3283: 
        !          3284: 
        !          3285: 
        !          3286: 
        !          3287: 
        !          3288: 
        !          3289:          MACRO SPITBOL V3.5
        !          3290:                                                    PAGE 48 - [7.2]
        !          3291:          Program Listing and Control Cards
        !          3292: 
        !          3293: 
        !          3294: 
        !          3295:  7.2  Option Control Cards
        !          3296:  7.2  Option Control Cards
        !          3297:  ___________ _______ _____
        !          3298: 
        !          3299:     The  option  control  cards  allow  selection  of various compiler
        !          3300:     options.  In each case, there are two modes and a pair of  control
        !          3301:     cards  which  permit  repeated flipping back and forth of the mode
        !          3302:     within a program.  Several control options  may  be  specified  on
        !          3303:     the  same  control  card  by  separating  the  names  with commas,
        !          3304:     leaving no intervening blanks.  For example
        !          3305:     -FAIL,LIST,PRINT
        !          3306:     In the list below, the default option is named first.
        !          3307: 
        !          3308: 
        !          3309: 
        !          3310: 
        !          3311:  7.2.1  -LIST -NOLIST
        !          3312:  7.2.1  -LIST -NOLIST
        !          3313: 
        !          3314:     The -NOLIST option causes  suppression  of  the  normal  statement
        !          3315:     listing.   This  may  be  useful  for  established program, or for
        !          3316:     terminal  output.   If  compilation  errors  are   detected,   the
        !          3317:     offending  statements are printed regardless of the setting of the
        !          3318:     list mode.  Some implementations provide  a  run  time  option  to
        !          3319:     select  NOLIST  mode  initially without the need to insert -NOLIST
        !          3320:     into the program being run (Section 12).
        !          3321: 
        !          3322: 
        !          3323: 
        !          3324: 
        !          3325:  7.2.2  -NOPRINT -PRINT
        !          3326:  7.2.2  -NOPRINT -PRINT
        !          3327: 
        !          3328:     Normally control cards are not printed.  The -PRINT option  causes
        !          3329:     them  to  be listed, provided the -LIST option is in effect.  This
        !          3330:     option may be useful if serialization is used for updating.
        !          3331: 
        !          3332: 
        !          3333: 
        !          3334: 
        !          3335:  7.2.3  -SINGLE -DOUBLE
        !          3336:  7.2.3  -SINGLE -DOUBLE
        !          3337: 
        !          3338:     The compilation listing is normally singly  spaced.   The  -DOUBLE
        !          3339:     option  causes  double  spacing  to  be  used,  with  a blank line
        !          3340:     folowing each listed line.
        !          3341: 
        !          3342: 
        !          3343: 
        !          3344: 
        !          3345: 
        !          3346: 
        !          3347: 
        !          3348: 
        !          3349: 
        !          3350: 
        !          3351: 
        !          3352: 
        !          3353: 
        !          3354: 
        !          3355: 
        !          3356:          MACRO SPITBOL V3.5
        !          3357:                                                    PAGE 49 - [7.2.4]
        !          3358:          Program Listing and Control Cards
        !          3359: 
        !          3360: 
        !          3361: 
        !          3362:  7.2.4  -INXXX
        !          3363:  7.2.4  -INXXX
        !          3364: 
        !          3365:     XXX in the above stands for an integer indicating  the  number  of
        !          3366:     characters  to  be  read  from  each  record of the SPITBOL source
        !          3367:     file.  The normal default is for  the  compiler  to  read  SPITBOL
        !          3368:     statements  from  columns  1-72  of  the  input  image.  Longer or
        !          3369:     shorter input  records  may  be  read  by  specifying  alternative
        !          3370:     values  for  XXX.  If any value other than 72 is in use at the end
        !          3371:     of translation, it is used as the maximum record length  for  data
        !          3372:     read  from  the  standard  input  file.  For historical reasons, a
        !          3373:     -IN72 card in effect at the end of compilation is taken  to  imply
        !          3374:     a  maximum  record length of 80 for execution time data.  There is
        !          3375:     however no need to restrict records to lengths of 72 or 80.
        !          3376: 
        !          3377: 
        !          3378: 
        !          3379: 
        !          3380:  7.2.5  -ERRORS -NOERRORS
        !          3381:  7.2.5  -ERRORS -NOERRORS
        !          3382: 
        !          3383:     Normally execution is allowed even when compilation errors  occur.
        !          3384:     If  it  is  wished  to inhibit execution if compilation errors are
        !          3385:     detected then the -NOERRORS option should be selected.
        !          3386: 
        !          3387: 
        !          3388: 
        !          3389: 
        !          3390:  7.2.6  -FAIL -NOFAIL
        !          3391:  7.2.6  -FAIL -NOFAIL
        !          3392: 
        !          3393:     In SNOBOL4 and in SPITBOL with the -FAIL mode set, a failure in  a
        !          3394:     statement  with  no  conditional  goto  is ignored and the program
        !          3395:     execution resumes with  the  next  statement  in  sequence.   This
        !          3396:     convention  often leads to errors going undetected, particuarly in
        !          3397:     the case of array references with  out  of  bound  subscripts  and
        !          3398:     pattern  matches  which  the user anticipates will always succeed.
        !          3399:     The -NOFAIL  option  changes  this  convention.   If  a  statement
        !          3400:     lacking  a  conditional goto is compiled under the -NOFAIL option,
        !          3401:     then if a failure occurs when  the  statement  is  executed,  this
        !          3402:     produces  an execution error with a suitable message.  This option
        !          3403:     is especially useful for student jobs and other  situations  where
        !          3404:     many small programs are being debugged.
        !          3405: 
        !          3406: 
        !          3407: 
        !          3408: 
        !          3409:  7.2.7  -EXECUTE -NOEXECUTE
        !          3410:  7.2.7  -EXECUTE -NOEXECUTE
        !          3411: 
        !          3412:     Normally   execution  is  initiated  following  compilation.   The
        !          3413:     -NOEXECUTE  option,  if  in  force  at  the  end  of  compilation,
        !          3414:     inhibits  execution.   A  run  time option may be provided for the
        !          3415:     same purpose (Section 12).
        !          3416: 
        !          3417: 
        !          3418: 
        !          3419: 
        !          3420: 
        !          3421: 
        !          3422:          MACRO SPITBOL V3.5
        !          3423:                                                    PAGE 50 - [8]
        !          3424:          Errors
        !          3425: 
        !          3426: 
        !          3427: 
        !          3428:                              *-------------*
        !          3429:                                [8]  Errors
        !          3430:                              | [8]  Errors |
        !          3431:                              *-------------*
        !          3432: 
        !          3433: 
        !          3434:  8.1  Compilation Error Messages
        !          3435:  8.1  Compilation Error Messages
        !          3436:  ________________ _____ ________
        !          3437: 
        !          3438:     When the compiler detects an error, the offending line is  printed
        !          3439:     with  a  marker  under  the  point at which the error was actually
        !          3440:     detected  and  an  error  code  and  self-explanatory  message  is
        !          3441:     printed.    Processing   of  the  statement  is  discontinued  and
        !          3442:     compilation continues with the next  statement.   Execution  of  a
        !          3443:     program  containing  errors is not suppressed unless the -NOERRORS
        !          3444:     option has  been  set.   If  an  attempt  is  made  to  execute  a
        !          3445:     statement  found  erroneous  by  the  compiler, an execution error
        !          3446:     occurs.
        !          3447: 
        !          3448: 
        !          3449:  8.2  Execution Error Messages
        !          3450:  8.2  Execution Error Messages
        !          3451:  ______________ _____ ________
        !          3452: 
        !          3453:     Extensive error checking is performed at run time.  When an  error
        !          3454:     is  detected,  execution is terminated with an error message which
        !          3455:     refers to the number of  the  erroneous  statement.   However,  as
        !          3456:     described  in  Section  5,  it  is  possible  to  avoid  automatic
        !          3457:     execution  termination  and  to   obtain   user   error   handling
        !          3458:     facilities by means of the SETEXIT function.
        !          3459: 
        !          3460:     In  addition  to  the  errors  listed here, the implementation may
        !          3461:     have additional system errors.  See Section 12.
        !          3462: 
        !          3463: 
        !          3464:  8.3  Error Codes and Messages
        !          3465:  8.3  Error Codes and Messages
        !          3466:  __________ _____ ___ ________
        !          3467: 
        !          3468:     The following list details all error messages with  the  exception
        !          3469:     of any which may be particular to certain implementations.
        !          3470: 
        !          3471:     Code                       Message
        !          3472:     ____                       _______
        !          3473: 
        !          3474:       1   Addition left operand is not numeric
        !          3475:       2   Addition right operand is not numeric
        !          3476:       3   Addition caused integer overflow
        !          3477:       4   Affirmation operand is not numeric
        !          3478:       5   Alternation right operand is not pattern
        !          3479:       6   Alternation left operand is not pattern
        !          3480:       7   Compilation error encountered during execution
        !          3481:       8   Concatenation left opnd is not string or pattern
        !          3482:       9   Concatenation right opd is not string or pattern
        !          3483:      10   Complementation operand is not numeric
        !          3484:      11   Complementation caused integer overflow
        !          3485:      12   Division left operand is not numeric
        !          3486:      13   Division right operand is not numeric
        !          3487:      14   Division caused integer overflow
        !          3488:      15   Exponentiation right operand is not numeric
        !          3489:      16   Exponentiation left operand is not numeric
        !          3490: 
        !          3491: 
        !          3492:          MACRO SPITBOL V3.5
        !          3493:                                                    PAGE 51 - [8.3]
        !          3494:          Errors
        !          3495: 
        !          3496:      17   Exponentiation caused integer overflow
        !          3497:      18   Exponentiation result is undefined
        !          3498:      19   Exponentiation right operand is negative
        !          3499:      20   Goto evaluation failure
        !          3500:      21   Function called by name returned a value
        !          3501:      22   Undefined function called
        !          3502:      23   Goto operand is not a natural variable
        !          3503:      24   Goto operand in direct goto is not code
        !          3504:      25   Immediate assignment left operand is not pattern
        !          3505:      26   Multiplication left operand is not numeric
        !          3506:      27   Multiplication right operand is not numeric
        !          3507:      28   Multiplication caused integer overflow
        !          3508:      29   Undefined operator referenced
        !          3509:      30   Pattern assignment left operand is not pattern
        !          3510:      31   Pattern replacement right operand is not string
        !          3511:      32   Subtraction left operand is not numeric
        !          3512:      33   Subtraction right operand is not numeric
        !          3513:      34   Subtraction caused integer overflow
        !          3514:      35   Unexpected failure in -NOFAIL mode
        !          3515:      36   Goto ABORT with no preceding error
        !          3516:      37   Goto CONTINUE with no preceding error
        !          3517:      38   Goto undefined label
        !          3518:      39   External function argument is not string
        !          3519:      40   External function argument is not integer
        !          3520:      41   FIELD function argument is wrong datatype
        !          3521:      42   Attempt to change value of protected variable
        !          3522:      43   ANY evaluated argument is not string
        !          3523:      44   BREAK evaluated argument is not string
        !          3524:      45   BREAKX evaluated argument is not string
        !          3525:      46   Expression does not evaluate to pattern
        !          3526:      47   LEN evaluated argument is not integer
        !          3527:      48   LEN evaluated argument is negative or too large
        !          3528:      49   NOTANY evaluated argument is not string
        !          3529:      50   POS evaluated argument is not integer
        !          3530:      51   POS evaluated argument is negative or too large
        !          3531:      52   RPOS evaluated argument is not integer
        !          3532:      53   RPOS evaluated argument is negative or too large
        !          3533:      54   RTAB evaluated argument is not integer
        !          3534:      55   RTAB evaluated argument is negative or too large
        !          3535:      56   SPAN evaluated argument is not string
        !          3536:      57   TAB evaluated argument is not integer
        !          3537:      58   TAB evaluated argument is negative or too large
        !          3538:      59   ANY argument is not string or expression
        !          3539:      60   APPLY first arg is not natural variable name
        !          3540:      61   ARBNO argument is not pattern
        !          3541:      62   ARG second argument is not integer
        !          3542:      63   ARG first argument is not program function name
        !          3543:      64   ARRAY first argument is not integer or string
        !          3544:      65   ARRAY first argument lower bound is not integer
        !          3545:      66   ARRAY first argument upper bound is not integer
        !          3546:      67   ARRAY dimension is zero,negative or out of range
        !          3547:      68   ARRAY size exceeds maximum permitted
        !          3548:      69   BREAK argument is not string or expression
        !          3549:      70   BREAKX argument is not string or expression
        !          3550:      71   CLEAR argument is not string
        !          3551:      72   CLEAR argument has null variable name
        !          3552: 
        !          3553: 
        !          3554:          MACRO SPITBOL V3.5
        !          3555:                                                    PAGE 52 - [8.3]
        !          3556:          Errors
        !          3557: 
        !          3558:      73   COLLECT argument is not integer
        !          3559:      74   CONVERT second argument is not string
        !          3560:      75   DATA argument is not string
        !          3561:      76   DATA argument is null
        !          3562:      77   DATA argument is missing a left paren
        !          3563:      78   DATA argument has null datatype name
        !          3564:      79   DATA argument is missing a right paren
        !          3565:      80   DATA argument has null field name
        !          3566:      81   DEFINE first argument is not string
        !          3567:      82   DEFINE first argument is null
        !          3568:      83   DEFINE first argument is missing a left paren
        !          3569:      84   DEFINE first argument has null function name
        !          3570:      85   Null arg name or missing ) in DEFINE first arg.
        !          3571:      86   DEFINE function entry point is not defined label
        !          3572:      87   DETACH argument is not appropriate name
        !          3573:      88   DUMP argument is not integer
        !          3574:      89   DUMP argument is negative or too large
        !          3575:      90   DUPL second argument is not integer
        !          3576:      91   DUPL first argument is not string or pattern
        !          3577:      92   EJECT argument is not a suitable name
        !          3578:      93   EJECT file does not exist
        !          3579:      94   EJECT file does not permit page eject
        !          3580:      95   EJECT caused non-recoverable output error
        !          3581:      96   ENDFILE argument is not a suitable name
        !          3582:      97   ENDFILE argument is null
        !          3583:      98   ENDFILE file does not exist
        !          3584:      99   ENDFILE file does not permit endfile
        !          3585:     100   ENDFILE caused non-recoverable output error
        !          3586:     101   EQ first argument is not numeric
        !          3587:     102   EQ second argument is not numeric
        !          3588:     103   EVAL argument is not expression
        !          3589:     104   EXIT argument is not suitable integer or string
        !          3590:     105   EXIT action not available in this implementation
        !          3591:     106   EXIT action caused irrecoverable error
        !          3592:     107   FIELD second argument is not integer
        !          3593:     108   FIELD first argument is not datatype name
        !          3594:     109   GE first argument is not numeric
        !          3595:     110   GE second argument is not numeric
        !          3596:     111   GT first argument is not numeric
        !          3597:     112   GT second argument is not numeric
        !          3598:     113   INPUT third argument is not a string
        !          3599:     114   Inappropriate second argument for INPUT
        !          3600:     115   Inappropriate first argument for INPUT
        !          3601:     116   Inappropriate file specification for INPUT
        !          3602:     117   INPUT file cannot be read
        !          3603:     118   LE first argument is not numeric
        !          3604:     119   LE second argument is not numeric
        !          3605:     120   LEN argument is not integer or expression
        !          3606:     121   LEN argument is negative or too large
        !          3607:     122   LEQ first argument is not string
        !          3608:     123   LEQ second argument is not string
        !          3609:     124   LGE first argument is not string
        !          3610:     125   LGE second argument is not string
        !          3611:     126   LGT first argument is not string
        !          3612:     127   LGT second argument is not string
        !          3613:     128   LLE first argument is not string
        !          3614: 
        !          3615: 
        !          3616:          MACRO SPITBOL V3.5
        !          3617:                                                    PAGE 53 - [8.3]
        !          3618:          Errors
        !          3619: 
        !          3620:     129   LLE second argument is not string
        !          3621:     130   LLT first argument is not string
        !          3622:     131   LLT second argument is not string
        !          3623:     132   LNE first argument is not string
        !          3624:     133   LNE second argument is not string
        !          3625:     134   LOCAL second argument is not integer
        !          3626:     135   LOCAL first arg is not a program function name
        !          3627:     136   LOAD second argument is not string
        !          3628:     137   LOAD first argument is not string
        !          3629:     138   LOAD first argument is null
        !          3630:     139   LOAD first argument is missing a left paren
        !          3631:     140   LOAD first argument has null function name
        !          3632:     141   LOAD first argument is missing a right paren
        !          3633:     142   LOAD function does not exist
        !          3634:     143   LOAD function caused input error during load
        !          3635:     144   LPAD third argument not a string
        !          3636:     145   LPAD second argument is not integer
        !          3637:     146   LPAD first argument is not string
        !          3638:     147   LT first argument is not numeric
        !          3639:     148   LT second argument is not numeric
        !          3640:     149   NE first argument is not numeric
        !          3641:     150   NE second argument is not numeric
        !          3642:     151   NOTANY argument is not string or expression
        !          3643:     152   OPSYN third argument is not integer
        !          3644:     153   OPSYN third argument is negative or too large
        !          3645:     154   OPSYN second arg is not natural variable name
        !          3646:     155   OPSYN first arg is not natural variable name
        !          3647:     156   OPSYN first arg is not correct operator name
        !          3648:     157   OUTPUT third argument is not a string
        !          3649:     158   Inappropriate second argument for OUTPUT
        !          3650:     159   Inappropriate first argument for OUTPUT
        !          3651:     160   Inappropriate file specification for OUTPUT
        !          3652:     161   OUTPUT file cannot be written to
        !          3653:     162   POS argument is not integer or expression
        !          3654:     163   POS argument is negative or too large
        !          3655:     164   PROTOTYPE argument is not table or array
        !          3656:     165   REMDR second argument is not integer
        !          3657:     166   REMDR first argument is not integer
        !          3658:     167   REMDR caused integer overflow
        !          3659:     168   REPLACE third argument is not string
        !          3660:     169   REPLACE second argument is not string
        !          3661:     170   REPLACE first argument is not string
        !          3662:     171   Null or unequally long 2nd, 3rd args to REPLACE
        !          3663:     172   REWIND argument is not a suitable name
        !          3664:     173   REWIND argument is null
        !          3665:     174   REWIND file does not exist
        !          3666:     175   REWIND file does not permit rewind
        !          3667:     176   REWIND caused non-recoverable error
        !          3668:     177   REVERSE argument is not string
        !          3669:     178   RPAD third argument is not string
        !          3670:     179   RPAD second argument is not integer
        !          3671:     180   RPAD first argument is not string
        !          3672:     181   RTAB argument is not integer or expression
        !          3673:     182   RTAB argument is negative or too large
        !          3674:     183   TAB argument is not integer or expression
        !          3675:     184   TAB argument is negative or too large
        !          3676: 
        !          3677: 
        !          3678:          MACRO SPITBOL V3.5
        !          3679:                                                    PAGE 54 - [8.3]
        !          3680:          Errors
        !          3681: 
        !          3682:     185   RPOS argument is not integer or expression
        !          3683:     186   RPOS argument is negative or too large
        !          3684:     187   SETEXIT argument is not label name or null
        !          3685:     188   SPAN argument is not string or expression
        !          3686:     189   SIZE argument is not string
        !          3687:     190   STOPTR first argument is not appropriate name
        !          3688:     191   STOPTR second argument is not trace type
        !          3689:     192   SUBSTR third argument is not integer
        !          3690:     193   SUBSTR second argument is not integer
        !          3691:     194   SUBSTR first argument is not string
        !          3692:     195   TABLE argument is not integer
        !          3693:     196   TABLE argument is out of range
        !          3694:     197   TRACE fourth arg is not function name or null
        !          3695:     198   TRACE first argument is not appropriate name
        !          3696:     199   TRACE second argument is not trace type
        !          3697:     200   TRIM argument is not string
        !          3698:     201   UNLOAD argument is not natural variable name
        !          3699:     202   Input from file caused non-recoverable error
        !          3700:     203   Input file record has incorrect format
        !          3701:     204   Memory overflow
        !          3702:     205   String length exceeds value of MAXLNGTH keyword
        !          3703:     206   Output caused file overflow
        !          3704:     207   Output caused non-recoverable error
        !          3705:     208   Keyword value assigned is not integer
        !          3706:     209   Keyword in assignment is protected
        !          3707:     210   Keyword value assigned is negative or too large
        !          3708:     211   Value assigned to keyword ERRTEXT not a string
        !          3709:     212   Syntax error.  Value used where name is required
        !          3710:     213   Syntax error.  Statement is too complicated.
        !          3711:     214   Syntax error.  Bad label or misplaced continuation line
        !          3712:     215   Syntax error.  Undefined or erroneous entry label
        !          3713:     216   Syntax error.  Missing END line
        !          3714:     217   Syntax error.  Duplicate label
        !          3715:     218   Syntax error.  Duplicated goto field
        !          3716:     219   Syntax error.  Empty goto field
        !          3717:     220   Syntax error.  Missing operator
        !          3718:     221   Syntax error.  Missing operand
        !          3719:     222   Syntax error.  Invalid use of left bracket
        !          3720:     223   Syntax error.  Invalid use of comma
        !          3721:     224   Syntax error.  Unbalanced right parenthesis
        !          3722:     225   Syntax error.  Unbalanced right bracket
        !          3723:     226   Syntax error.  Missing right paren
        !          3724:     227   Syntax error.  Right paren missing from goto
        !          3725:     228   Syntax error.  Right bracket missing from goto
        !          3726:     229   Syntax error.  Missing right array bracket
        !          3727:     230   Syntax error.  Illegal character
        !          3728:     231   Syntax error.  Invalid numeric item
        !          3729:     232   Syntax error.  Unmatched string quote
        !          3730:     233   Syntax error.  Invalid use of operator
        !          3731:     234   Syntax error.  Goto field incorrect
        !          3732:     235   Subscripted operand is not table or array
        !          3733:     236   Array referenced with wrong number of subscripts
        !          3734:     237   Table referenced with more than one subscript
        !          3735:     238   Array subscript is not integer
        !          3736:     239   Indirection operand is not name
        !          3737:     240   Pattern match right operand is not pattern
        !          3738: 
        !          3739: 
        !          3740:          MACRO SPITBOL V3.5
        !          3741:                                                    PAGE 55 - [8.3]
        !          3742:          Errors
        !          3743: 
        !          3744:     241   Pattern match left operand is not string
        !          3745:     242   Function return from level zero
        !          3746:     243   Function result in NRETURN is not name
        !          3747:     244   Statement count exceeds value of STLIMIT keyword
        !          3748:     245   Translation/execution time expired
        !          3749:     246   Stack overflow
        !          3750:     247   Invalid control card
        !          3751:     248   Attempted redefinition of system function
        !          3752:     249   Expression evaluated by name returned value
        !          3753:     250   Insufficient memory to complete dump
        !          3754:     251   Keyword operand is not name of defined keyword
        !          3755:     252   Error on printing to interactive channel
        !          3756:     253   Print limit exceeded on standard output channel
        !          3757:     254   Erroneous argument to HOST
        !          3758:     255   Error during execution of HOST
        !          3759:     256   SORT/RSORT 1st arg not suitable ARRAY or TABLE
        !          3760:     257   Erroneous 2nd arg in SORT/RSORT of vector
        !          3761:     258   SORT/RSORT 2nd arg out of range or non-integer
        !          3762:     259   FENCE function argument is not pattern
        !          3763:     261   Addition caused real overflow
        !          3764:     262   Division caused real overflow
        !          3765:     263   Multiplication caused real overflow
        !          3766:     264   Subtraction caused real overflow
        !          3767:     265   External function argument is not real
        !          3768:     266   Exponentiation caused real overflow
        !          3769:     267   Exponentiation right operand is real not integer
        !          3770:     268   Inconsistent value assigned to profile keyword
        !          3771:     269   BUFFER first argument is not integer
        !          3772:     270   BUFFER second argument is not string or buffer
        !          3773:     271   BUFFER initial value too big for allocation
        !          3774:     272   BUFFER first argument is not positive
        !          3775:     273   Buffer size is too big
        !          3776:     274   Requested buffer allocation exceeds MXLEN
        !          3777:     275   APPEND first argument is not buffer
        !          3778:     276   APPEND second argument is not string
        !          3779:     277   INSERT third argument not integer
        !          3780:     278   INSERT second argument not integer
        !          3781:     279   INSERT first argument not buffer
        !          3782:     280   INSERT fourth argument not a string
        !          3783:     281   CHAR argument not integer
        !          3784:     282   CHAR argument not in range
        !          3785: 
        !          3786: 
        !          3787: 
        !          3788: 
        !          3789: 
        !          3790: 
        !          3791: 
        !          3792: 
        !          3793: 
        !          3794: 
        !          3795: 
        !          3796: 
        !          3797: 
        !          3798: 
        !          3799: 
        !          3800: 
        !          3801: 
        !          3802:          MACRO SPITBOL V3.5
        !          3803:                                                    PAGE 56 - [9]
        !          3804:          Programming Notes
        !          3805: 
        !          3806: 
        !          3807: 
        !          3808:                         *------------------------*
        !          3809:                           [9]  Programming Notes
        !          3810:                         | [9]  Programming Notes |
        !          3811:                         *------------------------*
        !          3812: 
        !          3813:     The  internal organization of SPITBOL is quite different from that
        !          3814:     of  SNOBOL4.   Consequently  the   relative   speed   of   various
        !          3815:     operations  differs.   This  section attempts to give some idea of
        !          3816:     how to obtain high efficiency in SPITBOL programs.
        !          3817: 
        !          3818: 
        !          3819:  9.1  Space Considerations
        !          3820:  9.1  Space Considerations
        !          3821:  __________ ______________
        !          3822: 
        !          3823:     The ANY, NOTANY, BREAK, BREAKX, SPAN functions use  translate  and
        !          3824:     test  tables  for  arguments  longer  than one character.  A table
        !          3825:     allocated for this purpose will be M words long by  N  bits  wide,
        !          3826:     where  M  is  64, 128 or 256 (machine dependent) and N is the word
        !          3827:     length in bits of the host computer.  For  each  function  call  a
        !          3828:     bit  column  is  used so that a single table suffices for N calls.
        !          3829:     With a constant  argument,  the  table  entry  is  precomputed  at
        !          3830:     compile  time  thus avoiding erosion of space by repeated calls in
        !          3831:     a run time loop.   Single  character  arguments  incur  no   space
        !          3832:     overhead .
        !          3833: 
        !          3834:     Integers  and reals have an overhead of one word above that needed
        !          3835:     by the usual hardware representation.
        !          3836: 
        !          3837:     Multidimensional arrays have a  space  overhead  of  8 + 2D  words
        !          3838:     where  D is the number of dimensions.  One dimensional arrays with
        !          3839:     a low bound of 1 (vectors ) are  treated  specially  and  have  an
        !          3840:     overhead of only three words.
        !          3841: 
        !          3842:     The  space  needed  for  non-null elements of tables is 4 words in
        !          3843:     addition to space  for  the  element  itself.   Each  table   hash
        !          3844:     header  is  one  word.   Thus  the  number  of headers can be made
        !          3845:     reasonably large without using  much  additional  space.   Program
        !          3846:     defined  datatypes  require  3 + F words, where F is the number of
        !          3847:     fields.  They are thus quite  compact  and  can  be  used  freely.
        !          3848:     Each  variable  block requires 8 words plus space for the variable
        !          3849:     name, the characters of  which  are  packed  several  to  a  word,
        !          3850:     usually  using  6,  7 or 8 bits for each character.  This space is
        !          3851:     constant irrespective of whether the name has a single  use     or
        !          3852:     is  used  multiply as a label, function, variable etc.  This space
        !          3853:     is never reclaimed once  it  has  been   allocated.   It  is  thus
        !          3854:     inefficient  to   use  variables  to build tables with the unary $
        !          3855:     operator.  Instead use the TABLE datatype.  The interpretive  code
        !          3856:     produced  by  the  compiler is held in code blocks  and is subject
        !          3857:     to garbage collection when no longer  accessible.   Advantage  can
        !          3858:     be  taken  of  this by writing label-free initialising code at the
        !          3859:     head of a program.  Even if labels are present it is  possible  to
        !          3860:     make  initialising  code   collectable  by the artifice of calling
        !          3861:     CODE with a string argument in which the labels are redeclared.
        !          3862: 
        !          3863: 
        !          3864: 
        !          3865: 
        !          3866: 
        !          3867:          MACRO SPITBOL V3.5
        !          3868:                                                    PAGE 57 - [9.1]
        !          3869:          Programming Notes
        !          3870: 
        !          3871: 
        !          3872:     Considerable amounts of store  are  used  in  repeatedly  building
        !          3873:     patterns.    They  should  either  be  pre-assigned  to  variables
        !          3874:     outside program loops  or  alternatively  if  written  in-line  in
        !          3875:     loops,  should  be  constant  so  that  they may be precomputed at
        !          3876:     compile time in order to avoid this overhead.
        !          3877: 
        !          3878:     Setting &TRIM non-zero  ensures  that  memory  is  not  wasted  in
        !          3879:     storing trailing blanks in strings.
        !          3880: 
        !          3881:     The   COLLECT  function  can  be  used  to  obtain  very  detailed
        !          3882:     information of memory utilization for various structures.
        !          3883: 
        !          3884:     Modifications to a string type require that the string  be  copied
        !          3885:     internally  first.   This  means  that space must be available for
        !          3886:     two copies of the string to  co-exist  in  memory  simultaneously.
        !          3887:     If  the  string  is  large  this  can lead to unanticipated memory
        !          3888:     usage.  For example, consider the input loop:
        !          3889:         LOOP CORPUS = CORPUS INPUT  :S(LOOP)
        !          3890:     As this reads more and more lines, CORPUS grows larger, and  large
        !          3891:     amounts  of  memory  (and  processor  time)  are spent copying the
        !          3892:     'old' value of CORPUS before INPUT is appended to it.  The  buffer
        !          3893:     type  is  helpful in avoiding this situation,  since modifications
        !          3894:     to buffers  (via  APPEND,  INSERT  and  pattern  replacement)  are
        !          3895:     performed directly on the existing buffer contents.
        !          3896: 
        !          3897: 
        !          3898:  9.2  Speed Considerations
        !          3899:  9.2  Speed Considerations
        !          3900:  __________ ______________
        !          3901: 
        !          3902:     To  a  greater  extent  than  is the case with SNOBOL4, there is a
        !          3903:     loss of efficiency in  encoding  complex  structures  as  strings.
        !          3904:     Use  arrays,  tables,  buffers and program defined datatypes where
        !          3905:     possible since all of these are highly efficient in SPITBOL.   The
        !          3906:     fast  associative  lookup  (hashing) feature of the TABLE makes it
        !          3907:     a particularly recommended feature  to  be  exploited  in  a  wide
        !          3908:     range of applications.
        !          3909: 
        !          3910:     Programmers  frequently  do  not  appreciate that execution speeds
        !          3911:     may be reduced  by  an  order  of  magnitude  if  poorly  designed
        !          3912:     patterns  fruitlessly  scan  data  in   unanchored mode.  With the
        !          3913:     pattern  matching  primitives  of  SPITBOL,  it   is   rare   that
        !          3914:     unanchored  matching  is  necessary and since anchored matching is
        !          3915:     much less expensive it is worth  acquiring the habit of  initially
        !          3916:     setting  &ANCHOR  non-zero.   If unanchored matching is needed for
        !          3917:     some purpose, take care that it is not unduly wasteful  with  data
        !          3918:     for which match failure is common.
        !          3919: 
        !          3920:     The  binary  $ pattern assignment is rather faster than the binary
        !          3921:     . pattern assignment and may be used freely.  SPITBOL  precomputes
        !          3922:     constant  expressions  before execution.  No efficiency is lost by
        !          3923:     writing pre-evaluable patterns  in-line  rather  than  predefining
        !          3924:     them.    Use of the unary * to defer computation is useful in some
        !          3925:     cases.  For example, consider the in-line matches -
        !          3926:         X ANY('PQR') BAL PAT 'X' RPOS(0)
        !          3927:         X ANY('PQR') BAL *PAT 'X' RPOS(0)
        !          3928:     The  second  form  is  more  efficient,  since  the  compiler  can
        !          3929: 
        !          3930: 
        !          3931:          MACRO SPITBOL V3.5
        !          3932:                                                    PAGE 58 - [9.2]
        !          3933:          Programming Notes
        !          3934: 
        !          3935:     precompute  the  entire  pattern  where  PAT  occurs as a deferred
        !          3936:     expression.
        !          3937: 
        !          3938:     The ANY, NOTANY, BREAK, BREAKX, SPAN,  RSORT, SORT  functions  are
        !          3939:     fast and highly recommended.
        !          3940: 
        !          3941:     ARB  and  ARBNO  are  slow  and can very often be avoided by using
        !          3942:     other  constructions.   Time  for  datatype  conversions  may   be
        !          3943:     significant.    Where  efficiency  is  important,  avoid  repeated
        !          3944:     unnecessary conversions.
        !          3945: 
        !          3946:     The SETEXIT error intercepts are fast and may be used for  program
        !          3947:     control as well as for debugging.
        !          3948: 
        !          3949:     Tracing  or  I/O  associating  a variable substantially slows down
        !          3950:     references to it but there is no residual access  penalty  if  the
        !          3951:     trace or I/O associations  are removed by STOPTR or DETACH.
        !          3952: 
        !          3953:     The  unary  $  (indirect) operator applied to a string argument in
        !          3954:     SPITBOL corresponds to a hash search of existing  variables.   The
        !          3955:     process  of  applying $ to a NAME (including the name of a natural
        !          3956:     variable),  is  much  faster,  which  is  why   unary  dot   (name
        !          3957:     operator)  returns  a NAME instead of a string.  It is thus better
        !          3958:     to use names rather than strings in applications such  as  passing
        !          3959:     variable names or labels indirectly as in
        !          3960:         F(.X)            rather than
        !          3961:         F("X") .
        !          3962: 
        !          3963:     Use  of the REPLACE function is optimised when, on repeated calls,
        !          3964:     the second and third arguments are found to  be  unchanged,  since
        !          3965:     in this case the previously constructed replace table is re-used.
        !          3966: 
        !          3967:     The  buffer  type  is  recommended for containing and manipulating
        !          3968:     large strings.   Pattern  replacement  can  be  specified  with  a
        !          3969:     buffer  name as the subject; the replacement is done on the buffer
        !          3970:     contents corresponding  to  the  substring  matched  as  with  the
        !          3971:     INSERT function.
        !          3972: 
        !          3973: 
        !          3974:  9.3  Other Notes
        !          3975:  9.3  Other Notes
        !          3976:  __________ _____
        !          3977: 
        !          3978:     The pattern match
        !          3979:        &ALPHABET LEN(N) LEN(1) $ CHAR
        !          3980:     is  useful  to  put  into  "CHAR"  the  Nth  character of the host
        !          3981:     machine character set.
        !          3982: 
        !          3983: 
        !          3984:     The interrogation operator, unary ? , is useful to  annihilate  an
        !          3985:     expression  which  is  evaluated  for its side effects rather than
        !          3986:     for its value.  For example
        !          3987:        S BREAK(*DELIM) $ K *?(TABLE<K> = TABLE<K> + 1)
        !          3988: 
        !          3989: 
        !          3990: 
        !          3991: 
        !          3992: 
        !          3993: 
        !          3994: 
        !          3995:          MACRO SPITBOL V3.5
        !          3996:                                                    PAGE 59 - [10]
        !          3997:          Specimen Programs
        !          3998: 
        !          3999: 
        !          4000: 
        !          4001:                         *------------------------*
        !          4002:                           [10] Specimen Programs
        !          4003:                         | [10] Specimen Programs |
        !          4004:                         *------------------------*
        !          4005: 
        !          4006:     Specimen programs of several  different  types  are  listed.   The
        !          4007:     first  one  is  especially  simple and uses no special facilities.
        !          4008:     The second and third are a little more ambitious and make  use  of
        !          4009:     program  defined  datatypes  and  tables  respectively.  Program 4
        !          4010:     serves no function apart from showing some of the  techniques  for
        !          4011:     producing  trace  output  and  providing  user handling of errors.
        !          4012:     The  job  control  commands  needed  to  run  these  programs  are
        !          4013:     implementation dependent and hence are listed in Section 12.
        !          4014: 
        !          4015: 
        !          4016: 
        !          4017: 
        !          4018: 
        !          4019: 
        !          4020: 
        !          4021:  10.1  Program 1
        !          4022:  10.1  Program 1
        !          4023:  _____________ _
        !          4024: 
        !          4025:     This  program reads data appended to its end and scans each record
        !          4026:     to count the number of vowels  it  contains.   A  listing  of  all
        !          4027:     records  constituting  the  program  and data is shown and this is
        !          4028:     followed by a copy of  the  output  produced  on  compilation  and
        !          4029:     execution.   The  -NOLIST  card  indicates  that no listing of the
        !          4030:     program is required.   Note  the  use  of  the  SPITBOL  selection
        !          4031:     feature  in  the  statement labelled NOMORE and the plus used as a
        !          4032:     statement continuation symbol in column 1 of the next  card.   The
        !          4033:     data  for  the  run   follows  the  END label of the program.  The
        !          4034:     output includes  the version number of the SPITBOL compiler  which
        !          4035:     will  be  updated  as  new  versions are introduced.  Compile time
        !          4036:     statistics, output  from  the  program  execution  and  statistics
        !          4037:     relating to the run are listed.
        !          4038: 
        !          4039: 
        !          4040: 
        !          4041: 
        !          4042: 
        !          4043: 
        !          4044: 
        !          4045: 
        !          4046: 
        !          4047: 
        !          4048: 
        !          4049: 
        !          4050: 
        !          4051: 
        !          4052: 
        !          4053: 
        !          4054: 
        !          4055: 
        !          4056: 
        !          4057: 
        !          4058: 
        !          4059: 
        !          4060:          MACRO SPITBOL V3.5
        !          4061:                                                    PAGE 60 - [10.1]
        !          4062:          Specimen Programs
        !          4063: 
        !          4064:   -NOLIST
        !          4065:   -TITLE  P R O G R A M   1
        !          4066:   *
        !          4067:   *    PROGRAM TO COUNT THE VOWELS IN LINES OF TEXT
        !          4068:   *
        !          4069:             &ANCHOR  = &TRIM = 1
        !          4070:             VOWELS   = BREAK('AEIOU') LEN(1)
        !          4071:   *
        !          4072:   *    LOOP TO READ NEXT LINE OF INPUT
        !          4073:   *
        !          4074:   INP       INP      = COPY = INPUT                     :F(END)
        !          4075:             N        = 0
        !          4076:   *
        !          4077:   *    LOOP TO SEARCH FOR VOWELS
        !          4078:   *
        !          4079:   FINDVWLS  INP VOWELS =                                :F(NOMORE)
        !          4080:             N        = N + 1                            :(FINDVWLS)
        !          4081:   *
        !          4082:   *    ALL VOWELS HAVE BEEN FOUND
        !          4083:   *
        !          4084:   NOMORE    OUTPUT   = RPAD(N,2) (EQ(N,1) ' VOWEL ' , ' VOWELS')
        !          4085:   +           ' FOUND IN "' COPY '"'                    :(INP)
        !          4086:   END
        !          4087:   QWERTY
        !          4088:   1900 AND DECSYSTEM-10 SPITBOL
        !          4089:   THE SLITHY TOVES DID GYRE AND GIMBLE IN THE WABE
        !          4090:   12 * 2 = 24
        !          4091: 
        !          4092: 
        !          4093: 
        !          4094: 
        !          4095:   STORE USED     1360
        !          4096:   STORE LEFT     4477
        !          4097:   COMP ERRORS    0
        !          4098:   REGENERATIONS  0
        !          4099:   COMP TIME-MSEC 160
        !          4100: 
        !          4101: 
        !          4102:   1  VOWEL  FOUND IN "QWERTY"
        !          4103:   5  VOWELS FOUND IN "1900 AND DECSYSTEM-10 SPITBOL"
        !          4104:   13 VOWELS FOUND IN "THE SLITHY TOVES DID GYRE AND GIMBLE IN THE WABE"
        !          4105:   0  VOWELS FOUND IN "12 * 2 = 24"
        !          4106: 
        !          4107: 
        !          4108:   NORMAL END
        !          4109:   IN STATEMENT   8
        !          4110:   STMTS EXECUTED 58
        !          4111:   RUN TIME-MSEC  100
        !          4112:   MCSEC / STMT   1724
        !          4113:   REGENERATIONS  0
        !          4114: 
        !          4115: 
        !          4116: 
        !          4117: 
        !          4118: 
        !          4119: 
        !          4120: 
        !          4121: 
        !          4122:          MACRO SPITBOL V3.5
        !          4123:                                                    PAGE 61 - [10.2]
        !          4124:          Specimen Programs
        !          4125: 
        !          4126: 
        !          4127: 
        !          4128:  10.2  Program 2
        !          4129:  10.2  Program 2
        !          4130:  _____________ _
        !          4131: 
        !          4132:     This  is  a  somewhat  more  complex  program for sorting a set of
        !          4133:     records.  There is no -NOLIST card present and  so  a  listing  of
        !          4134:     the  program  is  produced  by the compiler with statement numbers
        !          4135:     placed on the left.  The output includes the sorted list and  then
        !          4136:     following  the  execution  statistics is a dump resulting from the
        !          4137:     assignment to keyword &DUMP in statement 2.  This illustrates  the
        !          4138:     excellent  diagnostic  assistance  available  should a program not
        !          4139:     behave as  expected.   The  structure  of  the  trees  is  readily
        !          4140:     discernible   in   the  dump  of  the  NODEs  of  which  they  are
        !          4141:     constituted.   (Note  that  this  program  could  also  have  been
        !          4142:     written using the SORT feature.)
        !          4143: 
        !          4144: 
        !          4145:   P R O G R A M   2                                               PAGE 1
        !          4146: 
        !          4147:           *    PROGRAM TO SORT A SET OF RECORDS ON A KEY USING A TREE SORTING
        !          4148:           *    TECHNIQUE.
        !          4149:           *
        !          4150:           *    DATATYPE WITH THE NECESSARY 4 FIELDS
        !          4151:           *
        !          4152:   1                 DATA('NODE(KEY,DAT,PRED,SUCC)')
        !          4153:   2                 &DUMP    = 2; &ANCHOR = &TRIM = 1
        !          4154:           *
        !          4155:           *    ROUTINE TO ADD "DATA" TO A TREE SORTED BY "KEY".
        !          4156:           *    "ROOT" IS PASSED BY REFERENCE (IT IS A SPITBOL NAME)
        !          4157:           *    AND POINTS TO THE TREE TO BE USED.
        !          4158:           *
        !          4159:   4                 DEFINE('ADNODE(KEY,DATA,ROOT)PTR')          :(ADNEND)
        !          4160:           *
        !          4161:           *    CREATE TREE INITIALLY IF NOT YET IN EXISTENCE
        !          4162:           *
        !          4163:   5       ADNODE    $ROOT    = IDENT($ROOT) NODE(KEY,DATA)      :S(RETURN)
        !          4164:   6                 PTR      = $ROOT
        !          4165:           *
        !          4166:           *    SEARCH TO FIND INSERTION POINT IN TREE
        !          4167:           *
        !          4168:   7       SEARCH    LLE(KEY,KEY(PTR))                           :S(BEFORE)
        !          4169:           *
        !          4170:           *    HERE IF NODE FOLLOWS THAT IN TREE
        !          4171:           *
        !          4172:   8       AFTER     PTR      = DIFFER(SUCC(PTR)) SUCC(PTR)      :S(SEARCH)
        !          4173:   9                 SUCC(PTR) = NODE(KEY,DATA)                  :S(RETURN)
        !          4174:           *
        !          4175:           *    HERE IF KEY PRECEDES THAT IN TREE
        !          4176:           *
        !          4177:   10      BEFORE    PTR      = DIFFER(PRED(PTR)) PRED(PTR)      :S(SEARCH)
        !          4178:   11                PRED(PTR) = NODE(KEY,DATA)                  :(RETURN)
        !          4179:   12      ADNEND
        !          4180: 
        !          4181: 
        !          4182: 
        !          4183: 
        !          4184: 
        !          4185: 
        !          4186:          MACRO SPITBOL V3.5
        !          4187:                                                    PAGE 62 - [10.2]
        !          4188:          Specimen Programs
        !          4189: 
        !          4190:           *
        !          4191:           *    ROUTINE TO PRINT A SORTED BINARY TREE
        !          4192:           *
        !          4193:   13                DEFINE('PRINTREE(TREE)')                    :(ENDPRT)
        !          4194:   14      PRINTREE  DIFFER(PRED(TREE)) PRINTREE(PRED(TREE))
        !          4195:   15                OUTPUT   = KEY(TREE) '  ' DAT(TREE)
        !          4196:   16                DIFFER(SUCC(TREE)) PRINTREE(SUCC(TREE))     :(RETURN)
        !          4197:   17      ENDPRT
        !          4198:           *
        !          4199:           *    RECORDS OF WHICH
        !          4200:           *    '1609   GALILEO :   TELESCOPE'
        !          4201:           *    IS TYPICAL ARE TO BE SORTED BY DATE AND BY INVENTOR.
        !          4202:           *    SPLIT OUT THE RECORDS AND ADD TO TWO SORTED TREES.
        !          4203:           *
        !          4204:   18      SORT      INP      = INPUT                            :F(PRINT)
        !          4205:   19                INP LEN(4) $ DATE SPAN(' ') (BREAK(':') ':') $ INVR
        !          4206:           .               SPAN(' ') REM $ INVN
        !          4207:   20                ADNODE(DATE,RPAD(INVR,16) INVN,.DATREE)
        !          4208:   21                ADNODE(RPAD(INVR,16),DATE '  ' INVN,.INVRTREE) :(SORT)
        !          4209:           *
        !          4210:           *    JOB DONE APART FROM PRINTING THE SORTED TREES
        !          4211:           *
        !          4212:   22      PRINT     OUTPUT   = 'INVENTIONS SORTED BY DATE'; OUTPUT =
        !          4213:   24                PRINTREE(DATREE) ; OUTPUT =
        !          4214:   26                OUTPUT   = 'INVENTIONS SORTED BY INVENTOR'; OUTPUT =
        !          4215:   28                PRINTREE(INVRTREE)
        !          4216:   29      END
        !          4217: 
        !          4218: 
        !          4219:   INVENTIONS SORTED BY DATE
        !          4220: 
        !          4221:   1609  GALILEO :         TELESCOPE
        !          4222:   1835  TALBOT W F :      PHOTOGRAPHY
        !          4223:   1876  BELL A G :        TELEPHONE
        !          4224:   1896  DIESEL R :        DIESEL ENGINE
        !          4225:   1896  MARCONI G :       RADIO
        !          4226:   1903  WRIGHT O & W :    POWERED FLIGHT
        !          4227: 
        !          4228:   INVENTIONS SORTED BY INVENTOR
        !          4229: 
        !          4230:   BELL A G :        1876  TELEPHONE
        !          4231:   DIESEL R :        1896  DIESEL ENGINE
        !          4232:   GALILEO :         1609  TELESCOPE
        !          4233:   MARCONI G :       1896  RADIO
        !          4234:   TALBOT W F :      1835  PHOTOGRAPHY
        !          4235:   WRIGHT O & W :    1903  POWERED FLIGHT
        !          4236: 
        !          4237: 
        !          4238:   NORMAL END
        !          4239:   IN STATEMENT   29
        !          4240:   STMTS EXECUTED 146
        !          4241:   RUN TIME-MSEC  160
        !          4242:   MCSEC / STMT   1095
        !          4243:   REGENERATIONS  0
        !          4244: 
        !          4245: 
        !          4246: 
        !          4247: 
        !          4248:          MACRO SPITBOL V3.5
        !          4249:                                                    PAGE 63 - [10.2]
        !          4250:          Specimen Programs
        !          4251: 
        !          4252:     DUMP OF NATURAL VARIABLES
        !          4253: 
        !          4254:   DATE = '1896'
        !          4255:   DATREE = NODE `1
        !          4256:   INP = '1896    DIESEL R :          DIESEL ENGINE'
        !          4257:   INPUT = '1896    DIESEL R :          DIESEL ENGINE'
        !          4258:   INVN = 'DIESEL ENGINE'
        !          4259:   INVR = 'DIESEL R :'
        !          4260:   INVRTREE = NODE `2
        !          4261:   OUTPUT = 'WRIGHT O & W :    1903  POWERED FLIGHT'
        !          4262:   REM = PATTERN
        !          4263: 
        !          4264: 
        !          4265:   DUMP OF KEYWORD VALUES
        !          4266: 
        !          4267:   &ANCHOR = 1
        !          4268:   &CODE = 0
        !          4269:   &DUMP = 2
        !          4270:   &ERRLIMIT = 0
        !          4271:   &ERRTEXT = ''
        !          4272:   &ERRTYPE = 0
        !          4273:   &FNCLEVEL = 0
        !          4274:   &FTRACE = 0
        !          4275:   &INPUT = 1
        !          4276:   &LASTNO = 28
        !          4277:   &MAXLNGTH = 3104
        !          4278:   &OUTPUT = 1
        !          4279:   &RTNTYPE = 'RETURN'
        !          4280:   &STCOUNT = 146
        !          4281:   &STLIMIT = 50000
        !          4282:   &STNO = 29
        !          4283:   &TRACE = 0
        !          4284:   &TRIM = 1
        !          4285: 
        !          4286: 
        !          4287:   NODE `1
        !          4288:   KEY(DATREE) = '1876'
        !          4289:   DAT(DATREE) = 'BELL A G :      TELEPHONE'
        !          4290:   PRED(DATREE) = NODE `5
        !          4291:   SUCC(DATREE) = NODE `3
        !          4292: 
        !          4293:   NODE `2
        !          4294:   KEY(INVRTREE) = 'BELL A G :      '
        !          4295:   DAT(INVRTREE) = '1876  TELEPHONE'
        !          4296:   SUCC(INVRTREE) = NODE `4
        !          4297: 
        !          4298:   NODE `3
        !          4299:   KEY(NODE `3) = '1896'
        !          4300:   DAT(NODE `3) = 'MARCONI G :     RADIO'
        !          4301:   PRED(NODE `3) = NODE `11
        !          4302:   SUCC(NODE `3) = NODE `7
        !          4303: 
        !          4304: 
        !          4305: 
        !          4306: 
        !          4307: 
        !          4308: 
        !          4309: 
        !          4310:          MACRO SPITBOL V3.5
        !          4311:                                                    PAGE 64 - [10.2]
        !          4312:          Specimen Programs
        !          4313: 
        !          4314:   NODE `4
        !          4315:   KEY(NODE `4) = 'MARCONI G :     '
        !          4316:   DAT(NODE `4) = '1896  RADIO'
        !          4317:   PRED(NODE `4) = NODE `6
        !          4318:   SUCC(NODE `4) = NODE `8
        !          4319: 
        !          4320:   NODE `5
        !          4321:   KEY(NODE `5) = '1609'
        !          4322:   DAT(NODE `5) = 'GALILEO :       TELESCOPE'
        !          4323:   SUCC(NODE `5) = NODE `9
        !          4324: 
        !          4325:   NODE `6
        !          4326:   KEY(NODE `6) = 'GALILEO :       '
        !          4327:   DAT(NODE `6) = '1609  TELESCOPE'
        !          4328:   PRED(NODE `6) = NODE `12
        !          4329: 
        !          4330:   NODE `7
        !          4331:   KEY(NODE `7) = '1903'
        !          4332:   DAT(NODE `7) = 'WRIGHT O & W :  POWERED FLIGHT'
        !          4333: 
        !          4334:   NODE `8
        !          4335:   KEY(NODE `8) = 'WRIGHT O & W :  '
        !          4336:   DAT(NODE `8) = '1903  POWERED FLIGHT'
        !          4337:   PRED(NODE `8) = NODE `10
        !          4338: 
        !          4339:   NODE `9
        !          4340:   KEY(NODE `9) = '1835'
        !          4341:   DAT(NODE `9) = 'TALBOT W F :    PHOTOGRAPHY'
        !          4342: 
        !          4343:   NODE `10
        !          4344:   KEY(NODE `10) = 'TALBOT W F :    '
        !          4345:   DAT(NODE `10) = '1835  PHOTOGRAPHY'
        !          4346: 
        !          4347:   NODE `11
        !          4348:   KEY(NODE `11) = '1896'
        !          4349:   DAT(NODE `11) = 'DIESEL R :      DIESEL ENGINE'
        !          4350: 
        !          4351:   NODE `12
        !          4352:   KEY(NODE `12) = 'DIESEL R :      '
        !          4353:   DAT(NODE `12) = '1896  DIESEL ENGINE'
        !          4354: 
        !          4355: 
        !          4356: 
        !          4357: 
        !          4358: 
        !          4359: 
        !          4360: 
        !          4361: 
        !          4362: 
        !          4363: 
        !          4364: 
        !          4365: 
        !          4366: 
        !          4367: 
        !          4368: 
        !          4369: 
        !          4370: 
        !          4371: 
        !          4372:          MACRO SPITBOL V3.5
        !          4373:                                                    PAGE 65 - [10.3]
        !          4374:          Specimen Programs
        !          4375: 
        !          4376: 
        !          4377: 
        !          4378:  10.3  Program 3
        !          4379:  10.3  Program 3
        !          4380:  _____________ _
        !          4381: 
        !          4382:     This  program reads a set of keywords and then processes a file in
        !          4383:     order to count the number of occurrences of the  keywords  in  the
        !          4384:     text  held  in the file.  Notice the simple method of making input
        !          4385:     and output associations to the various input and output  files  in
        !          4386:     statements  2,  3  and  4.   A  table  created  in  statement 7 is
        !          4387:     initialised with the keywords at statement 8.   The  pattern  used
        !          4388:     to  break out words is written out of line since this ensures that
        !          4389:     matching in the inner loop at label WORDLOOP executes  at  maximum
        !          4390:     speed.   In a similar application where an in-line pattern must be
        !          4391:     used (e.g. if the string value  of  PUNCTUATION  were  subject  to
        !          4392:     change  during  execution),  then  the  statement  would  best  be
        !          4393:     written using deferred expressions as
        !          4394: 
        !          4395:       WORDLOOP INP BREAK(*PUNCTUATION) . WORD SPAN(*PUNCTUATION) =
        !          4396: 
        !          4397:     since,  being  constant,  the  pattern  can  be  pre-evaluated  at
        !          4398:     compile  time.   This saves repeatedly building the pattern in the
        !          4399:     loop, leaving only the necessary processing of the current  string
        !          4400:     in  PUNCTUATION  as  additional  work to be done compared with the
        !          4401:     version in  the  program.   The  searching  for  and  counting  of
        !          4402:     keywords  in statement 11  is done using the inherently efficient,
        !          4403:     system-provided hashing capability  of  the  TABLE  datatype.   To
        !          4404:     economise  in  table  lookups,  the  table  entry is assigned to a
        !          4405:     temporary variable in statement 10  whilst  a  check  is  made  to
        !          4406:     ensure  that  it  is non-null.  The call of CONVERT used to access
        !          4407:     non-null entries in the table does not sort the keys,  so  that  a
        !          4408:     separate  sorting process would be necessary if sorted output were
        !          4409:     required.  A listing of the filed output is given.
        !          4410: 
        !          4411: 
        !          4412: 
        !          4413: 
        !          4414: 
        !          4415: 
        !          4416: 
        !          4417: 
        !          4418: 
        !          4419: 
        !          4420: 
        !          4421: 
        !          4422: 
        !          4423: 
        !          4424: 
        !          4425: 
        !          4426: 
        !          4427: 
        !          4428: 
        !          4429: 
        !          4430: 
        !          4431: 
        !          4432: 
        !          4433: 
        !          4434: 
        !          4435: 
        !          4436:          MACRO SPITBOL V3.5
        !          4437:                                                    PAGE 66 - [10.3]
        !          4438:          Specimen Programs
        !          4439: 
        !          4440:     Contents of file KEYWDS
        !          4441:     ________ __ ____ ______
        !          4442: 
        !          4443:     BREEZE
        !          4444:     DAY
        !          4445:     MOON
        !          4446:     OCEAN
        !          4447:     SEA
        !          4448:     SHIP
        !          4449:     SUN
        !          4450:     THE
        !          4451:     TWAS
        !          4452:     WATER
        !          4453: 
        !          4454:     Contents of file KEYTXT
        !          4455:     ________ __ ____ ______
        !          4456: 
        !          4457:     THE FAIR BREEZE BLEW, THE WHITE FOAM FLEW,
        !          4458:     THE FURROW FOLLOWED FREE:
        !          4459:     WE WERE THE FIRST THAT EVER BURST
        !          4460:     INTO THAT SILENT SEA.
        !          4461: 
        !          4462:     DOWN DROPT THE BREEZE, THE SAILS DROPT DOWN,
        !          4463:     'TWAS SAD AS SAD COULD BE;
        !          4464:     AND WE DID SPEAK ONLY TO BREAK
        !          4465:     THE SILENCE OF THE SEA!
        !          4466: 
        !          4467:     DAY AFTER DAY, DAY AFTER DAY,
        !          4468:     WE STUCK, NOR BREATH NOR MOTION;
        !          4469:     AS IDLE AS A PAINTED SHIP
        !          4470:     UPON A PAINTED OCEAN.
        !          4471: 
        !          4472:     WATER, WATER, EVERY WHERE,
        !          4473:     AND ALL THE BOARDS DID SHRINK;
        !          4474:     WATER, WATER, EVERY WHERE,
        !          4475:     NOR ANY DROP TO DRINK.
        !          4476: 
        !          4477:             SAMUEL TAYLOR COLERIDGE
        !          4478: 
        !          4479: 
        !          4480:     Contents of file KEYOUT at end of run
        !          4481:     ________ __ ____ ______ __ ___ __ ___
        !          4482: 
        !          4483:          KEYWORD    NUMBER OF OCCURRENCES
        !          4484:          -------    --------------------
        !          4485: 
        !          4486:              SUN .  .  .  .  . 0
        !          4487:             MOON .  .  .  .  . 0
        !          4488:             SHIP .  .  .  .  . 1
        !          4489:             TWAS .  .  .  .  . 1
        !          4490:              DAY .  .  .  .  . 4
        !          4491:              SEA .  .  .  .  . 2
        !          4492:              THE .  .  .  .  . 9
        !          4493:           BREEZE .  .  .  .  . 2
        !          4494:            OCEAN .  .  .  .  . 1
        !          4495:            WATER .  .  .  .  . 4
        !          4496: 
        !          4497: 
        !          4498: 
        !          4499: 
        !          4500: 
        !          4501:          MACRO SPITBOL V3.5
        !          4502:                                                    PAGE 67 - [10.3]
        !          4503:          Specimen Programs
        !          4504: 
        !          4505: 
        !          4506:   P R O G R A M   3                                               PAGE 1
        !          4507: 
        !          4508:           -PRINT
        !          4509:           -IN80
        !          4510:           *    PROGRAM TO COUNT THE OCCURRENCES OF KEYWORDS IN A PIECE
        !          4511:           *    OF TEXT.  THE SEARCH FOR KEYWORDS IS EFFICIENTLY PERFORMED
        !          4512:           *    BY HASHING INTO A TABLE.
        !          4513:           *
        !          4514:   1                 &ANCHOR = &TRIM = 1
        !          4515:   2                 INPUT(.KEYS,1,'KEYWDS')                     :F(NOFILE)
        !          4516:   3                 INPUT(.INPUT,2,'KEYTXT')                    :F(NOFILE)
        !          4517:   4                 OUTPUT(.OUT,3,)
        !          4518:   5                 PUNCTUATION = " .,;:'!"
        !          4519:   6                 WORDPAT  = BREAK(PUNCTUATION) $ WORD SPAN(PUNCTUATION)
        !          4520:   7                 KEYTABLE = TABLE(31)
        !          4521:           *
        !          4522:           *    LOOP IN WHICH KEYWORDS ARE READ IN AND HASHED INTO KEYTABLE
        !          4523:           *
        !          4524:   8       KEYLOOP   KEYTABLE<KEYS> = 0                          :S(KEYLOOP)
        !          4525:           *
        !          4526:           *    A SPACE IS ADDED TO LINES OF TEXT TO ENSURE MATCH SUCCESS
        !          4527:           *
        !          4528:   9       READLOOP  INP      = INPUT ' '                        :F(CONVERT)
        !          4529:           *
        !          4530:           *    INDIVIDUAL WORDS ARE EXTRACTED BY PATTERN MATCHING
        !          4531:           *
        !          4532:   10      WORDLOOP  INP WORDPAT =
        !          4533:   11                KEYTABLE<WORD> = DIFFER(ENTRY = KEYTABLE<WORD>) ENTRY + 1
        !          4534:   12                DIFFER(INP)                       :S(WORDLOOP)F(READLOOP)
        !          4535:           *
        !          4536:           *    FAILURE POINT
        !          4537:           *
        !          4538:   13      NOFILE    OUTPUT  = 'MISSING INPUT FILE'              :(END)
        !          4539:   14      CONVFL    OUTPUT  = 'NO KEYWORDS FOUND'               :(END)
        !          4540:           *
        !          4541:           *    EXTRACT THE ENTRIES FROM THE TABLE INTO AN ARRAY
        !          4542:           *
        !          4543:   15      CONVERT   A        = CONVERT(KEYTABLE,'ARRAY')        :F(CONVFL)
        !          4544:   16                OUT      = '     KEYWORD    NUMBER OF OCCURRENCES'
        !          4545:   17                OUT      = '     -------    ---------------------'
        !          4546:   18                OUT      =
        !          4547:           *
        !          4548:           *    PRINT THE ENTRIES
        !          4549:           *
        !          4550:   19                 I        = 1
        !          4551:   20      PRINT    OUT   = LPAD(A[I,1],13) DUPL(' . ',5) A[I,2] :F(END)
        !          4552:   21                I        = I + 1                            :(PRINT)
        !          4553:   22      END
        !          4554: 
        !          4555: 
        !          4556: 
        !          4557: 
        !          4558: 
        !          4559: 
        !          4560: 
        !          4561: 
        !          4562: 
        !          4563:          MACRO SPITBOL V3.5
        !          4564:                                                    PAGE 68 - [10.4]
        !          4565:          Specimen Programs
        !          4566: 
        !          4567: 
        !          4568: 
        !          4569:  10.4  Program 4
        !          4570:  10.4  Program 4
        !          4571:  _____________ _
        !          4572: 
        !          4573:     This program  is  included  merely  to  show  how  errors  may  be
        !          4574:     handled,  use  of  the  -NOFAIL  option  and  the  nature of trace
        !          4575:     output.
        !          4576: 
        !          4577: 
        !          4578:     Statement 1 sets the keyword &TRACE to permit printing  of  up  to
        !          4579:     40  lines of trace output and the next two statements indicate the
        !          4580:     items to be traced.  In statement 4 a limit of 10 is  set  on  the
        !          4581:     number  of  errors  to be intercepted and processed by the program
        !          4582:     itself, whilst the destination label in  the  event  of  an  error
        !          4583:     occurring  is  identified  in  the  next statement.  The next line
        !          4584:     contains a syntax error which results in the printing of an  error
        !          4585:     message.   Following  statement  14 is a -NOFAIL control card, the
        !          4586:     effect of which  is  to  cause  generation  of  special  code  for
        !          4587:     subsequent  statements  containing  no conditional goto so that if
        !          4588:     such a  statement  does,  contrary  to  the  implied  expectation,
        !          4589:     actually  fail,  an  error  message  is  produced.  This can be of
        !          4590:     great diagnostic value.   The  output  from  the  run  illustrates
        !          4591:     various  points.   Execution  of  the program was not inhibited by
        !          4592:     the compilation error.  The number of any statement where a  trace
        !          4593:     association  is active is embedded in asterisks and printed on the
        !          4594:     left so that starting with statement 4, we can trace the  flow  of
        !          4595:     control  through the program on account of the trace intercept set
        !          4596:     on the keyword &STCOUNT.  It will be  seen  that  the  compilation
        !          4597:     error  in  statement 6 results in an execution error and that this
        !          4598:     in turn causes a transfer of control to statement  18  where  user
        !          4599:     processing  of  the error message is provided.  At statement 7 the
        !          4600:     ACCESS trace of the INPUT variable produces lines of trace  output
        !          4601:     indicating  the  value  which  it  currently  holds.   The jump to
        !          4602:     statement 10 followed by the STOPTR statement results  in  turning
        !          4603:     off  the  &STCOUNT trace.   An attempt to jump to the non-existent
        !          4604:     label L100 produces a failure,  followed  immediately  by  another
        !          4605:     when  an  attempt is made to form the sum 3 + 'L200'.  The loop at
        !          4606:     statements 16 and 17 reads 10 elements into the array A  and  then
        !          4607:     as  the  array  is  accessed outside its bounds, a statement error
        !          4608:     occurs which is converted  to  a  run  time  failure  because  the
        !          4609:     statement  was  compiled  in  -NOFAIL mode.  Had this not been the
        !          4610:     case the loop could have run for many seconds before  the  integer
        !          4611:     value  in I finally overflowed.  A correct program of course would
        !          4612:     have had a conditional goto such as
        !          4613: 
        !          4614:                               :F(ARRAY.FULL.OR.DATA.USED.UP)
        !          4615: 
        !          4616:     in statement 16.  The  failure  terminates  execution  because  at
        !          4617:     statement  13  the  limit  on the number of errors to be tolerated
        !          4618:     was reset to zero.
        !          4619: 
        !          4620: 
        !          4621: 
        !          4622: 
        !          4623: 
        !          4624: 
        !          4625: 
        !          4626: 
        !          4627:          MACRO SPITBOL V3.5
        !          4628:                                                    PAGE 69 - [10.4]
        !          4629:          Specimen Programs
        !          4630: 
        !          4631:     P R O G R A M   4                                              PAGE 1
        !          4632: 
        !          4633:           -PRINT
        !          4634:           *
        !          4635:           *    PROGRAM TO DEMONSTRATE TRACING AND ERROR HANDLING
        !          4636:           *
        !          4637:   1                 &TRACE   = &ANCHOR = &TRIM = 40
        !          4638:   2                 TRACE(.INPUT,'ACCESS')
        !          4639:   3                 TRACE(.STCOUNT,'K')
        !          4640:   4                 &ERRLIMIT = 10
        !          4641:   5                 SETEXIT(.ERROR)
        !          4642:   6                 STATEMENT , WHICH SHOULD FAIL TO COMPILE
        !          4643:                               ^
        !          4644:   ERROR 223 -- SYNTAX ERROR.  INVALID USE OF COMMA
        !          4645: 
        !          4646:   7       LOOP                                             :S($INPUT)F(FAIL)
        !          4647:   8       L1        OUTPUT   = '"L1"'                           :(LOOP)
        !          4648:   9       L2        OUTPUT   = '"L2"'                           :(LOOP)
        !          4649:   10      STOPTR    OUTPUT   = 'STOPTR'
        !          4650:   11                STOPTR(.STCOUNT,'K')                        :(LOOP)
        !          4651:   12      FAIL      X        = 3 + INPUT
        !          4652:   13                &ERRLIMIT =
        !          4653:   14                A        = ARRAY(10);     I = 1
        !          4654:           -NOFAIL
        !          4655:   16      READ      A<I>     = INPUT
        !          4656:   17                I        = I + 1                            :(READ)
        !          4657:           *
        !          4658:           *    ERROR INTERCEPT ROUTINE
        !          4659:           *
        !          4660:   18      ERROR     OUTPUT   = 'ERROR NO.  '  &ERRTYPE '  IN STATEMENT'
        !          4661:           .            &LASTNO
        !          4662:   19                OUTPUT   = 'REASON FOR FAILURE :- '  &ERRTEXT
        !          4663:   20                OUTPUT   =
        !          4664:   21                SETEXIT(.ERROR)                             :(CONTINUE)
        !          4665:   22      END
        !          4666: 
        !          4667: 
        !          4668:   STORE USED     1279
        !          4669:   STORE LEFT     4558
        !          4670:   COMP ERRORS    1
        !          4671:   REGENERATIONS  0
        !          4672:   COMP TIME-MSEC 400
        !          4673: 
        !          4674: 
        !          4675: 
        !          4676: 
        !          4677: 
        !          4678: 
        !          4679: 
        !          4680: 
        !          4681: 
        !          4682: 
        !          4683: 
        !          4684: 
        !          4685: 
        !          4686: 
        !          4687: 
        !          4688: 
        !          4689:          MACRO SPITBOL V3.5
        !          4690:                                                    PAGE 70 - [10.4]
        !          4691:          Specimen Programs
        !          4692: 
        !          4693:   ****4*******  &STCOUNT = 4
        !          4694:   ****5*******  &STCOUNT = 5
        !          4695:   ****6*******  &STCOUNT = 6
        !          4696:   ****18******  &STCOUNT = 7
        !          4697:   ERROR NO.  7  IN STATEMENT  6
        !          4698:   ****19******  &STCOUNT = 8
        !          4699:   REASON FOR FAILURE :- COMPILATION ERROR ENCOUNTERED DURING EXECUTION
        !          4700:   ****20******  &STCOUNT = 9
        !          4701: 
        !          4702:   ****21******  &STCOUNT = 10
        !          4703: 
        !          4704:   ****7*******  &STCOUNT = 11
        !          4705:   ****7*******  INPUT = 'L2'
        !          4706:   ****9*******  &STCOUNT = 12
        !          4707:   "L2"
        !          4708:   ****7*******  &STCOUNT = 13
        !          4709:   ****7*******  INPUT = 'STOPTR'
        !          4710:   ****10******  &STCOUNT = 14
        !          4711:   STOPTR
        !          4712:   ****11******  &STCOUNT = 15
        !          4713:   ****7*******  INPUT = 'L1'
        !          4714:   "L1"
        !          4715:   ****7*******  INPUT = 'L100'
        !          4716: 
        !          4717: 
        !          4718:   ERROR NO.  38  IN STATEMENT  7
        !          4719:   REASON FOR FAILURE :- GOTO UNDEFINED LABEL
        !          4720: 
        !          4721:   ****12******  INPUT = 'L200'
        !          4722:   ERROR NO.  2  IN STATEMENT  12
        !          4723:   REASON FOR FAILURE :- ADDITION RIGHT OPERAND IS NOT NUMERIC
        !          4724: 
        !          4725:   ****16******  INPUT = '1.111111'
        !          4726:   ****16******  INPUT = '2.2'
        !          4727:   ****16******  INPUT = '3.3'
        !          4728:   ****16******  INPUT = '4.4'
        !          4729:   ****16******  INPUT = '5.5'
        !          4730:   ****16******  INPUT = '6.6'
        !          4731:   ****16******  INPUT = '7.7'
        !          4732:   ****16******  INPUT = '8.8'
        !          4733:   ****16******  INPUT = '9.9'
        !          4734:   ****16******  INPUT = '10.10'
        !          4735: 
        !          4736: 
        !          4737:   ERROR 035 -- UNEXPECTED FAILURE IN -NOFAIL MODE
        !          4738: 
        !          4739:   IN STATEMENT   16
        !          4740:   STMTS EXECUTED 51
        !          4741:   RUN TIME-MSEC  280
        !          4742:   MCSEC / STMT   5490
        !          4743:   REGENERATIONS  0
        !          4744: 
        !          4745: 
        !          4746: 
        !          4747: 
        !          4748: 
        !          4749: 
        !          4750: 
        !          4751:          MACRO SPITBOL V3.5
        !          4752:                                                    PAGE 71 - [11]
        !          4753:          Implementation Information
        !          4754: 
        !          4755: 
        !          4756: 
        !          4757:                    *---------------------------------*
        !          4758:                      [11] Implementation Information
        !          4759:                    | [11] Implementation Information |
        !          4760:                    *---------------------------------*
        !          4761: 
        !          4762:     SPITBOL  is  implemented  on  a   wide   variety   of   computers.
        !          4763:     Condsiderable  efforts have been made to achieve compatibility and
        !          4764:     portability between versions but inevitably  there  are  features,
        !          4765:     values  or  limitations  particular  to each implementation.  This
        !          4766:     section gives details for the VAX/VMS implementation.
        !          4767: 
        !          4768:     Note that version BCAB-2132  of  SPITBOL  or  higher  requires  at
        !          4769:     least VMS version 2.
        !          4770: 
        !          4771: 
        !          4772:  11.1  &CODE
        !          4773:  11.1  &CODE
        !          4774:  ___________
        !          4775:     The  default  value  for  &CODE  in  VAX/VMS SPITBOL is one.  This
        !          4776:     avoids a "successful completion" message  from  VMS  which  occurs
        !          4777:     when &CODE is zero on exit.
        !          4778: 
        !          4779:     The  value  of  &CODE  is  used on exit as the return code to VMS.
        !          4780:       There are two exceptions:
        !          4781: 
        !          4782:     - &CODE = 998 will print a message on termination  to  the  effect
        !          4783:       that the standard output channel is not available.
        !          4784: 
        !          4785:     - &CODE  =  999  will print a message on termination to the effect
        !          4786:       that execution was suppressed  (either  via  startup  switch  or
        !          4787:       control card).
        !          4788: 
        !          4789:     The  VMS message number 196648 corresponds to "CLI-F-ABORT" and is
        !          4790:     useful to signal general program failure  to  the  command  stream
        !          4791:     via $STATUS/$SEVERITY.
        !          4792: 
        !          4793: 
        !          4794:  11.2  &ERRTEXT
        !          4795:  11.2  &ERRTEXT
        !          4796:  ______________
        !          4797:     The  initial  value  of &ERRTEXT contains the startup command line
        !          4798:     text, excluding the command name and any trailing  comment.   When
        !          4799:     reloading  from  a saved EXIT(n) file, if the value of n was -2 or
        !          4800:     -1, the new command line will replace the value of &ERRTEXT.
        !          4801: 
        !          4802: 
        !          4803:  11.3  &STLIMIT
        !          4804:  11.3  &STLIMIT
        !          4805:  ______________
        !          4806:     The default value for &STLIMIT is one billion.  Maximum  value  is
        !          4807:     2,147,403,647.   Note  that statement counting and checking can be
        !          4808:     disabled by setting the value of &STLIMIT to -1.
        !          4809: 
        !          4810: 
        !          4811: 
        !          4812: 
        !          4813: 
        !          4814: 
        !          4815: 
        !          4816: 
        !          4817: 
        !          4818: 
        !          4819: 
        !          4820:          MACRO SPITBOL V3.5
        !          4821:                                                    PAGE 72 - [11.4]
        !          4822:          Implementation Information
        !          4823: 
        !          4824:  11.4  &TRIM
        !          4825:  11.4  &TRIM
        !          4826:  ___________
        !          4827:     Records are never implicitly padded with blanks  on  output.   For
        !          4828:     input,  any  trailing  blanks  received depend on the file and the
        !          4829:     value of &TRIM.
        !          4830: 
        !          4831: 
        !          4832:  11.5  Buffers
        !          4833:  11.5  Buffers
        !          4834:  _____________
        !          4835:     VAX/VMS  SPITBOL  contains  an  additional  datatype  called   the
        !          4836:     BUFFER.   This  is  described  in  the  section  on datatypes.  In
        !          4837:     addition, new functions BUFFER, INSERT and APPEND have been  added
        !          4838:     to  support  buffers.   These functions are described in detail in
        !          4839:     Section 5.
        !          4840: 
        !          4841: 
        !          4842: 
        !          4843: 
        !          4844: 
        !          4845: 
        !          4846: 
        !          4847: 
        !          4848: 
        !          4849: 
        !          4850: 
        !          4851: 
        !          4852: 
        !          4853: 
        !          4854: 
        !          4855: 
        !          4856: 
        !          4857: 
        !          4858: 
        !          4859: 
        !          4860: 
        !          4861: 
        !          4862: 
        !          4863: 
        !          4864: 
        !          4865: 
        !          4866: 
        !          4867: 
        !          4868: 
        !          4869: 
        !          4870: 
        !          4871: 
        !          4872: 
        !          4873: 
        !          4874: 
        !          4875: 
        !          4876: 
        !          4877: 
        !          4878: 
        !          4879: 
        !          4880: 
        !          4881: 
        !          4882: 
        !          4883: 
        !          4884: 
        !          4885: 
        !          4886:          MACRO SPITBOL V3.5
        !          4887:                                                    PAGE 73 - [11.6]
        !          4888:          Implementation Information
        !          4889: 
        !          4890: 
        !          4891: 
        !          4892:  11.6  Character Set for VAX/VMS SPITBOL
        !          4893:  11.6  Character Set for VAX/VMS SPITBOL
        !          4894:  _______________ ___ ___ _______ _______
        !          4895: 
        !          4896:     Character codes can  be  a  considerable  locus  of  confusion  in
        !          4897:     SPITBOL.   The  SNOBOL4  language  does  not  define  a "standard"
        !          4898:     graphic set, so in general an attempt has been made to conform  to
        !          4899:     the   original  IBM/360 EBCDIC symbology where possible (excluding
        !          4900:     the 'extended graphics').  This is the character style most  often
        !          4901:     used in references and manuals.
        !          4902: 
        !          4903:     The  point where this is most likely to cause problems is with the
        !          4904:     binary   bar   (alternation),   which   in   many   other    ASCII
        !          4905:     implementations  is  the exclamation point.  Such programs as make
        !          4906:     use of this convention must be editted -  OPSYN cannot be used  to
        !          4907:     redefine  a  system  operator's  semantics in MACRO SPITBOL.  Note
        !          4908:     also that the unary not-sign may be different.
        !          4909: 
        !          4910:     The correspondence between the  SNOBOL4 and VAX/VMS Macro  SPITBOL
        !          4911:     source program character set is as follows:
        !          4912: 
        !          4913:     Character Name
        !          4914:     _________ ____
        !          4915:                         IBM SNOBOL4
        !          4916:                         ___ _______
        !          4917:                                        VAX/VMS SPITBOL
        !          4918:                                        _______ _______
        !          4919: 
        !          4920:     Digits
        !          4921:                         0..9
        !          4922:                                        0..9
        !          4923:     Letters
        !          4924:                         A..Z
        !          4925:                                        A..Z a..z
        !          4926:     Left Parenthesis
        !          4927:                         (
        !          4928:                                        (
        !          4929:     Right Parenthesis
        !          4930:                         )
        !          4931:                                        )
        !          4932:     Left Angle Bracket
        !          4933:                         <
        !          4934:                                        < or [
        !          4935:     Right Angle Bracket
        !          4936:                         >
        !          4937:                                        > or ]
        !          4938:     Colon
        !          4939:                         :
        !          4940:                                        :
        !          4941:     Semicolon
        !          4942:                         ;
        !          4943:                                        ;
        !          4944:     Comma
        !          4945:                         ,
        !          4946:                                        ,
        !          4947:     Equal Sign
        !          4948:                         =
        !          4949:                                        =
        !          4950:     Double Quote
        !          4951: 
        !          4952: 
        !          4953:          MACRO SPITBOL V3.5
        !          4954:                                                    PAGE 74 - [11.6]
        !          4955:          Implementation Information
        !          4956: 
        !          4957:                         "
        !          4958:                                        "
        !          4959:     Single Quote
        !          4960:                         '
        !          4961:                                        '
        !          4962:     Negation
        !          4963:                         <Not-Sign>
        !          4964:                                        ~
        !          4965:     Query
        !          4966:                         ?
        !          4967:                                        ?
        !          4968:     Dollar Sign
        !          4969:                         $
        !          4970:                                        $
        !          4971:     Point
        !          4972:                         .
        !          4973:                                        .
        !          4974:     Exponentiation
        !          4975:                         **
        !          4976:                                        ** or !
        !          4977:     Percent
        !          4978:                         %
        !          4979:                                        %
        !          4980:     Asterisk
        !          4981:                         *
        !          4982:                                        *
        !          4983:     Divide
        !          4984:                         /
        !          4985:                                        /
        !          4986:     Plus
        !          4987:                         +
        !          4988:                                        +
        !          4989:     Minus
        !          4990:                         -
        !          4991:                                        -
        !          4992:     At
        !          4993:                         @
        !          4994:                                        @
        !          4995:     Blank
        !          4996:                         <Blank>
        !          4997:                                        <Blank> or <Tab>
        !          4998:     Alternation
        !          4999:                         |
        !          5000:                                        |
        !          5001:     Number Sign
        !          5002:                         #
        !          5003:                                        #
        !          5004:     Ampersand
        !          5005:                         &
        !          5006:                                        &
        !          5007:     Underscore
        !          5008:                         not avail.
        !          5009:                                        _
        !          5010: 
        !          5011: 
        !          5012: 
        !          5013: 
        !          5014: 
        !          5015:          MACRO SPITBOL V3.5
        !          5016:                                                    PAGE 75 - [11.7]
        !          5017:          Implementation Information
        !          5018: 
        !          5019: 
        !          5020: 
        !          5021:  11.7  Form of DATE String
        !          5022:  11.7  Form of DATE String
        !          5023:  __________ __ ____ ______
        !          5024:     DATE() returns an 22 character string of the form:
        !          5025: 
        !          5026:                           MM-DD-YYYY HH:MM:SS.CC
        !          5027: 
        !          5028:                                                            M      D
        !          5029:     These  wall-time  components  designate  respectively: _onth, _ay,
        !          5030:     Y     H     M       S                      C
        !          5031:     _ear, _our, _inute, _econd and Hundredths (_enti-) seconds.
        !          5032: 
        !          5033: 
        !          5034:  11.8  Errors
        !          5035:  11.8  Errors
        !          5036:  ____________
        !          5037:     In addition to the errors  issued  by  the  interpreter,  the  VMS
        !          5038:     interface  may  detect a number of conditions which it will report
        !          5039:     using the default VMS condition handler.
        !          5040: 
        !          5041:     There follows the list of SPITBOL's VMS-specific errors,  and  the
        !          5042:     severity  of  the  error.  Errors which have a severity of warning
        !          5043:     or less can be suppressed  with the /NOWARN startup  command  line
        !          5044:     switch.   (An  exception are the messages generated as a result of
        !          5045:     an exception caused by a LOADed function image.)   Errors  with  a
        !          5046:     listed  severity  of "Severe" will generally cause execution to be
        !          5047:     aborted  with  the  DCL   $STATUS  and   $SEVERITY   symbols   set
        !          5048:     appropriately.   Although  more  messages  may  be  added  in  the
        !          5049:     future, existing message symbols and values will not.
        !          5050: 
        !          5051: 
        !          5052:      Error Name    Severity          Description
        !          5053: 
        !          5054:      EXIT           Info     EXIT Module Saved - <Filename>
        !          5055: 
        !          5056:      EXSUP          Info     Execution Suppressed
        !          5057: 
        !          5058:      INSVIRMEM      Severe   Insufficient Virtual Memory
        !          5059:        This can occur if the value specified on the /MINT switch, or
        !          5060:     if
        !          5061:        the value of the system VIRTUALPAGECNT parameter is too low (it
        !          5062:        should generally be at least 4000.)
        !          5063: 
        !          5064:      LINETRUNC      Warning  Input Source Line Truncated
        !          5065: 
        !          5066:      LOADCRC        Severe   Load Incompatible, Please Retranslate
        !          5067:     Source
        !          5068:        SPITBOL has been modified since the EXIT(-n) module was saved.
        !          5069: 
        !          5070:      LOADMEM        Severe   <No longer used>
        !          5071: 
        !          5072:      LOADOPEN       Severe   Can't Open LOAD File - <Filename>
        !          5073: 
        !          5074:      LOADMAP        Severe   Error Mapping LOAD File - <Filename>
        !          5075: 
        !          5076:      LOADUNEXCOND   Warning  Loaded Function Failed To Handle
        !          5077:                                Condition At PC=<Hex PC>
        !          5078:        An external LOADed function was invoked and generated an
        !          5079:     exception
        !          5080:        condition which it did not handle.  Check to see that the image
        !          5081: 
        !          5082: 
        !          5083:          MACRO SPITBOL V3.5
        !          5084:                                                    PAGE 76 - [11.8]
        !          5085:          Implementation Information
        !          5086: 
        !          5087:        base address was properly specified.
        !          5088: 
        !          5089:      LOADUNEXTRY    Warning  Will Attempt to Recover By Forcing
        !          5090:     Failure
        !          5091:        A loaded function was unable to return an acceptable result, so
        !          5092:        SPITBOL attempts to continue execution by simulating failure.
        !          5093: 
        !          5094:      LOADVERS       Severe   Load Versions Incompatible,
        !          5095:                                Please Retranslate Source
        !          5096:        The version of SPITBOL used to save an EXIT(-n) module was not
        !          5097:        the same as the one being used to load it.
        !          5098: 
        !          5099:      NOSYSOUT       Severe   Output File Not Accessable
        !          5100:        The /LIST= or /OUT= device/file could not be opened for
        !          5101:     writing.
        !          5102: 
        !          5103:      NOTEXITMOD     Severe   File is Not a Saved EXIT File -
        !          5104:     <Filename>
        !          5105:        The file implied or specified by /LOAD was not a saved SPITBOL
        !          5106:        EXIT(-n) file.
        !          5107: 
        !          5108:      OPENOUT        Severe   Error Opening <Filename> as Output
        !          5109: 
        !          5110:      OPENIN         Severe   Error Opening <Filename> as Input
        !          5111: 
        !          5112:      PAUSE          Info     Paused at Statement <Stmt #>
        !          5113:        This is issued as a consequence of executing an EXIT(0).  Enter
        !          5114:        CONTINUE to resume execution.
        !          5115: 
        !          5116:      STACKOVFL      Severe   Virtual Stack Space Exhausted
        !          5117:        This is a severe stack overflow which will not be seen (SPITBOL
        !          5118:        will issue its own stack overflow through the standard error
        !          5119:        handling mechanism) unless SPITBOL is improperly linked.
        !          5120: 
        !          5121:      SYNTAX         Severe   Syntax Error In Command Line
        !          5122: 
        !          5123:      BADLINK        Severe   Incorrectly specified BASE(s) in SPITBOL
        !          5124:     link
        !          5125:        The symbol LOAD_BASE is higher than the start of the
        !          5126:     interpreter
        !          5127:        (BASE=) or STACK_LIMIT is too close to LOAD_BASE.
        !          5128: 
        !          5129:      LOADBADINT     Warning  Loaded function returned invalid
        !          5130:                                integer result pointer
        !          5131: 
        !          5132:      LOADBADREAL    Warning  Loaded function returned invalid real
        !          5133:                                number result ptr
        !          5134: 
        !          5135:      LOADBADSTRING  Warning  Loaded function returned invalid string
        !          5136:                                descriptor
        !          5137: 
        !          5138:      LOADBADUNCONV  Warning  Loaded function returned bad block for
        !          5139:                                unconverted result
        !          5140: 
        !          5141: 
        !          5142: 
        !          5143: 
        !          5144: 
        !          5145:          MACRO SPITBOL V3.5
        !          5146:                                                    PAGE 77 - [11.9]
        !          5147:          Implementation Information
        !          5148: 
        !          5149: 
        !          5150: 
        !          5151:  11.9  EXIT Function Usage
        !          5152:  11.9  EXIT Function Usage
        !          5153:  __________ ________ _____
        !          5154:     The EXIT  function  has  been  implemented  in  all  forms  except
        !          5155:     positive  integer  arguments  (that  is  to say, there is no total
        !          5156:     image save).  Each of the forms is described below.
        !          5157: 
        !          5158: 
        !          5159:  11.9.1  EXIT(0) Usage
        !          5160:  11.9.1  EXIT(0) Usage
        !          5161:     EXIT(0) will pause the program with a message;  a  DCL  "CONTINUE"
        !          5162:     command  will  continue  execution.  The message can be suppressed
        !          5163:     with the /NOWARN command line option.
        !          5164: 
        !          5165: 
        !          5166:  11.9.2  EXIT(String) Usage
        !          5167:  11.9.2  EXIT(String) Usage
        !          5168:     EXIT(string) will cause SPITBOL  to  exit  and  "string"  will  be
        !          5169:     given  to  the command interpreter as the next command.  Note that
        !          5170:     this subsumes the normal SPITBOL  semantics  of  EXIT(string)  for
        !          5171:     chain  execution  if the string is of the form "RUN image".  It is
        !          5172:     also possible to initiate a command file  (including  one  written
        !          5173:     by   the   program   itself)   if  the  string  is  of  the  form:
        !          5174:     "@command-file".
        !          5175: 
        !          5176: 
        !          5177:  11.9.3  EXIT(-n) Usage
        !          5178:  11.9.3  EXIT(-n) Usage
        !          5179:     EXIT(-n) is implemented, and will save the impure segments of  the
        !          5180:     interpreter  in  a  specially formatted block mode file.  The name
        !          5181:     for this file is the same as the  standard  input  file,  with  an
        !          5182:                       S       EX
        !          5183:     extension ".SEX" (SPITBOL EXit!) under the default directory.   If
        !          5184:     such  a  file already exists, it will be reused (with an extension
        !          5185:     of space if required), otherwise a new file  is  allocated.    The
        !          5186:     startup   switch   "/LOAD[=filename]"   can  be  used  to  load  a
        !          5187:     previously saved .SEX file.  If the "=filename" is  not  specified
        !          5188:     on  the  load, the default LOAD name is the same as that described
        !          5189:     above.  Specification of  /LOAD  does  not  obviate  the  need  to
        !          5190:     specify  a standard input file, although it need not have the same
        !          5191:     name as the save file,  and trivially could be "NL:" if no use  is
        !          5192:     to be made of the standard input channel.
        !          5193: 
        !          5194:     Certain  remarks are in order regarding this form of EXIT.  When a
        !          5195:     previously saved .SEX file is loaded, SPITBOL  performs  a  number
        !          5196:     of  fairly  extensive  checks to verify that the segment was saved
        !          5197:     under the same version of SPITBOL that is being used to  load  it.
        !          5198:     If  it is not, the load will not work and one of a number of fatal
        !          5199:     errors will be issued.  The conclusion should  be  that  the  file
        !          5200:     created  by  EXIT  is not really analogous to a "permanent" object
        !          5201:     or executable binary.   The  original  source  and  data  must  be
        !          5202:     retained in the event that a retranslation is indicated.
        !          5203: 
        !          5204:     One  other point should be noted as regards EXIT(-n).  Neither the
        !          5205:     status of open files, nor the contents of LOAD(...)  functions  is
        !          5206:     preserved  across  an  EXIT(-n);  this includes the standard input
        !          5207:     and output files, which are instead associated anew when the  exit
        !          5208:     module  is reloaded using the filenames given on the /LOAD startup
        !          5209:     line.   In general, INPUT(...), OUTPUT(...)  and  LOAD(...)  calls
        !          5210:     must  be  made  after  the  call  to  EXIT(-n).   In addition, the
        !          5211: 
        !          5212: 
        !          5213:          MACRO SPITBOL V3.5
        !          5214:                                                    PAGE 78 - [11.9.3]
        !          5215:          Implementation Information
        !          5216: 
        !          5217:     load-time  values  (default  or  explicit)  of  /MINC  and   /MINT
        !          5218:     override  whatever  values were in effect when the exit module was
        !          5219:     saved (SPITBOL will, however,  always  attempt  to  obtain  enough
        !          5220:     virtual  space  to  hold  the  impure  data  of  the  exit module,
        !          5221:     regardless of the setting of /MINT.)  If the EXIT(-1) or  EXIT(-2)
        !          5222:     forms  are  used,  then  the load-time values of the other startup
        !          5223:     command line switches override the  values  at  the  time  of  the
        !          5224:     EXIT.
        !          5225: 
        !          5226: 
        !          5227:  11.10  FENCE(PATTERN)
        !          5228:  11.10  FENCE(PATTERN)
        !          5229:  _____________________
        !          5230:     VAX/VMS  SPITBOL contains an additional intrinsic pattern matching
        !          5231:     function called FENCE.  This function is described  in  Section  5
        !          5232:     in detail.
        !          5233: 
        !          5234: 
        !          5235:  11.11  HOST
        !          5236:  11.11  HOST
        !          5237:  ___________
        !          5238:     The  only defined entry to HOST is when all arguments are null, in
        !          5239:     which case, HOST() returns the identifying string of the form:
        !          5240: 
        !          5241:                   VAX:VMS:sitename:username:accountname
        !          5242: 
        !          5243:     "Sitename" is derived from  a  translation  of  the  logical  name
        !          5244:     "SYS$SITENAME"  to  obtain  a  site name both for HOST and for the
        !          5245:     banner.  The translated string must be 28 or fewer characters.
        !          5246: 
        !          5247: 
        !          5248:  11.12  Range of Integers
        !          5249:  11.12  Range of Integers
        !          5250:  ____________ __ ________
        !          5251:     Integers are represented in a single  VAX  32-bit  longword.   The
        !          5252:     range for integers is: [ -2,147,483,648 , +2,147,483,647 ].
        !          5253: 
        !          5254: 
        !          5255: 
        !          5256: 
        !          5257: 
        !          5258: 
        !          5259: 
        !          5260: 
        !          5261: 
        !          5262: 
        !          5263: 
        !          5264: 
        !          5265: 
        !          5266: 
        !          5267: 
        !          5268: 
        !          5269: 
        !          5270: 
        !          5271: 
        !          5272: 
        !          5273: 
        !          5274: 
        !          5275: 
        !          5276: 
        !          5277: 
        !          5278: 
        !          5279: 
        !          5280: 
        !          5281:          MACRO SPITBOL V3.5
        !          5282:                                                    PAGE 79 - [11.13]
        !          5283:          Implementation Information
        !          5284: 
        !          5285: 
        !          5286: 
        !          5287:  11.13  INPUT/OUTPUT
        !          5288:  11.13  INPUT/OUTPUT
        !          5289:  ___________________
        !          5290:     All  VAX/VMS  Macro  SPITBOL  I/O is processed through RMS (Record
        !          5291:     Management Services).  The general form of the  INPUT/OUTPUT  call
        !          5292:     in Macro SPITBOL is:
        !          5293: 
        !          5294:                       XXXPUT(Var,Filearg1,Filearg2)
        !          5295: 
        !          5296:     "Filearg1"  may  be any Macro SPITBOL object that can be converted
        !          5297:     to a name (e.g. number or string).  It has no significance to  the
        !          5298:     I/O  system  as  such,  however  it represents a unique binding to
        !          5299:     this I/O channel,  and it can thus be used in subsequent calls  to
        !          5300:     INPUT,  OUTPUT,  REWIND,  ENDFILE and EJECT.  If Filearg1 is null,
        !          5301:     an INPUT call refers to the standard  input  channel  association,
        !          5302:     and  an  OUTPUT  call  similarly  refers  to  the  standard output
        !          5303:     channel.   It  is  permitted  to  reassign  these   channels   via
        !          5304:     INPUT/OUTPUT,  but note that SPITBOL does not allow null arguments
        !          5305:     to REWIND or ENDFILE.
        !          5306: 
        !          5307:     "Filearg2" differs slightly from the form shown in Section  5  for
        !          5308:     the INPUT and OUTPUT functions, and has the form:
        !          5309: 
        !          5310:                        "Filespec/Switch/Switch/..."
        !          5311: 
        !          5312:     where  all  components,  including  "Filespec"  are  optional.  If
        !          5313:     Filespec is given, the current channel (if any) is closed out  and
        !          5314:     a  new  association  to the given Filespec is created.  "Filespec"
        !          5315:     is  given   in   standard   VMS/RMS   form   for   a   device/file
        !          5316:     specification.   If  the  Filespec  is  omitted  then any switches
        !          5317:     specified are processed  for  the  association,  but  the  present
        !          5318:     association  to  the  channel  remains  unchanged.   If the entire
        !          5319:     Filearg2 is null, then this  reduces  to  simply  I/O  associating
        !          5320:     "Var" to the channel designated by Filearg1.
        !          5321: 
        !          5322:     Any  given "Filearg1" channel can be associated for both INPUT and
        !          5323:     OUTPUT, however any such dual associations must  be  formed  prior
        !          5324:     to  opening  the  channel  in order to avoid an RMS error when the
        !          5325:     channel is used in a  manner  for  which  is  was  not  originally
        !          5326:     opened.   A  channel  is opened for I/O activity indirectly due to
        !          5327:     the first I/O reference to it.  The call to  INPUT  or  OUTPUT  by
        !          5328:     itself  causes no I/O activity, but only establishes the nature of
        !          5329:     the variable-to-channel and channel-to-file associations that  can
        !          5330:     be   used  later.   The  first  I/O  reference  to  a  channel  or
        !          5331:     channel-associated variable causes either an OPEN or CREATE to  be
        !          5332:     issued.   The  OPEN  (an existing file) is issued unless an OUTPUT
        !          5333:     association to the channel has been made, in which case  a  CREATE
        !          5334:     (new  file)  will  be issued.  The occurrence of some switches can
        !          5335:     modify this default action.
        !          5336: 
        !          5337:     Note that all I/O sequential in nature; the default mode  of  file
        !          5338:     creation  is  variable-length,  carriage  return  delimited record
        !          5339:     attributes.   It is possible to  process  existing  indexed  files
        !          5340:     transparently  through RMS, however, sequential access is the only
        !          5341:     processing   mode   available,   regardless    of    the    file's
        !          5342:     characteristics.
        !          5343: 
        !          5344: 
        !          5345:          MACRO SPITBOL V3.5
        !          5346:                                                    PAGE 80 - [11.13.1]
        !          5347:          Implementation Information
        !          5348: 
        !          5349: 
        !          5350: 
        !          5351:  11.13.1  FILEARG2 SWITCHES
        !          5352:  11.13.1  FILEARG2 SWITCHES
        !          5353:     The   following   switches  are  available  for  specification  on
        !          5354:     Filearg2.  They must be specified in upper-case.  In  many  cases,
        !          5355:     it  is  possible  to  precede  the  switch name by the prefix "NO"
        !          5356:     which indicates that the condition indicated by the switch  is  to
        !          5357:     be  inverted  for  this channel.  For switches which apply only to
        !          5358:     terminal I/O, their presence is ignored when  dealing  with  other
        !          5359:     devices or files.
        !          5360: 
        !          5361:         SWITCH           _ _ _ _ _ _ _ _ _ _ _
        !          5362:         ______           D_E_S_C_R_I_P_T_I_O_N
        !          5363: 
        !          5364:          /CCO   Cancel   terminal   control  O  on  subsequent  output
        !          5365:                 operations.
        !          5366:          /CIF   If  the  named  file  already  exists,  it  is   used.
        !          5367:                 Otherwise,  a  new  file  is created.  Note that if an
        !          5368:                 existing  sequential  variable-length  file  is  being
        !          5369:                 processed,  /EOF  must  also  be  specified  since RMS
        !          5370:                 cannot  rewrite   records   in   such   files.    This
        !          5371:                 restriction does not apply to indexed files.
        !          5372:          /CR    Set  CR/LF  file  attributes  for  CREATE  operations.
        !          5373:                 Note that an  output  association  to  "TT:/-CR"  will
        !          5374:                 thus  suppress the usual carriage return and line feed
        !          5375:                 after each output assignment to the terminal.
        !          5376:          /DLT   Delete the file when it is closed.
        !          5377:          /EOF   Position  to  end-of-file  on  open.   If  an   OUTPUT
        !          5378:                 association  has  been made, the presence of /EOF will
        !          5379:                 cause an OPEN to be issued rather than a CREATE.
        !          5380:          /FTN   Set  FORTRAN-type  carriage  control  attributes   for
        !          5381:                 CREATE.   This  switch  is mutually exclusive with the
        !          5382:                 "CR" switch.
        !          5383:          /MXV   Maximize the version number of the file  on  a  CREATE
        !          5384:                 between  any specified version and one higher than the
        !          5385:                 highest existing verion.
        !          5386:          /PTA   Purge the terminal type-ahead  buffer  for  subsequent
        !          5387:                 terminal input on this channel.
        !          5388:          /RNE   For  a  terminal  input-associated channel, subsequent
        !          5389:                 input is not to be echoed.
        !          5390:          /RNF   For terminal-associated  input,  control-U,  control-R
        !          5391:                 and  DELETE  characters are passed in the input string
        !          5392:                 and are not taken as control characters.
        !          5393:          /SCF   Submit this file to the system standard  batch  stream
        !          5394:                 when it is closed.
        !          5395:          /SPL   Submit  this  file  to the system standard spool queue
        !          5396:                 when it is closed.
        !          5397:          /SUP   Supercede any existing file on CREATE.
        !          5398:          /TEF   Truncate the file to actual EOF when it is closed.
        !          5399: 
        !          5400: 
        !          5401: 
        !          5402: 
        !          5403: 
        !          5404: 
        !          5405: 
        !          5406: 
        !          5407: 
        !          5408: 
        !          5409:          MACRO SPITBOL V3.5
        !          5410:                                                    PAGE 81 - [11.13.2]
        !          5411:          Implementation Information
        !          5412: 
        !          5413: 
        !          5414: 
        !          5415:  11.13.2  I/O EXAMPLES
        !          5416:  11.13.2  I/O EXAMPLES
        !          5417:     Here are a few examples of INPUT/OUTPUT calls.  The  colons  (":")
        !          5418:     represent code sequences which are not shown.
        !          5419: 
        !          5420:     1. Attach  the user's terminal for input without echoing the first
        !          5421:        line read in.
        !          5422: 
        !          5423:             INPUT(.TTNE,1,'TT:/RNE')
        !          5424:                      :
        !          5425:             FIRST_LINE = TTNE
        !          5426:             INPUT(.TTNE,1,'/NORNE')
        !          5427:                      :
        !          5428: 
        !          5429: 
        !          5430:     2. Write  to  a  new  file  OUT.DAT  and  spool  it  when  SPITBOL
        !          5431:        terminates.
        !          5432: 
        !          5433:             OUTPUT(.OUTFILE,1,'OUT.DAT/SPL')
        !          5434: 
        !          5435: 
        !          5436:     3. Write  to  an  intermediate  file, then rewind it, read through
        !          5437:        it, and delete it.
        !          5438: 
        !          5439:             INPUT(.INTER,1,'SCRATCH.DAT/DLT')
        !          5440:             OUTPUT(.INTER,1)
        !          5441:                     :
        !          5442:        WRITELOOP
        !          5443:             INTER = X
        !          5444:                     :
        !          5445:             REWIND(1)
        !          5446:        READLOOP
        !          5447:             X = INTER   :F(EXIT)
        !          5448:                     :
        !          5449:        EXIT
        !          5450:             ENDFILE(1)
        !          5451:        END
        !          5452: 
        !          5453: 
        !          5454:     4. Append the record "***END***" to an existing file:
        !          5455: 
        !          5456:             OUTPUT(.OLDFILE,1,'OLDFILE.DAT/EOF/CIF')
        !          5457:             OLDFILE = '***END***'
        !          5458:        END
        !          5459: 
        !          5460: 
        !          5461: 
        !          5462: 
        !          5463: 
        !          5464: 
        !          5465: 
        !          5466: 
        !          5467: 
        !          5468: 
        !          5469: 
        !          5470: 
        !          5471: 
        !          5472:          MACRO SPITBOL V3.5
        !          5473:                                                    PAGE 82 - [11.14]
        !          5474:          Implementation Information
        !          5475: 
        !          5476: 
        !          5477: 
        !          5478:  11.14  Linking SPITBOL
        !          5479:  11.14  Linking SPITBOL
        !          5480:  ______________ _______
        !          5481: 
        !          5482: 
        !          5483:     SPITBOL is delivered pre-linked and ready for use.  Some sites  or
        !          5484:     users  may  wish  to  link their own copies.  Modifications to the
        !          5485:     source are not encouraged, as it renders much more  difficult  the
        !          5486:     process  of  diagnosing  trouble  reports.  If trouble reports are
        !          5487:     submitted, the implementor requests that the original,  unmodified
        !          5488:     interpreter be used to provide the necessary information.
        !          5489: 
        !          5490:     The normal link command is:
        !          5491: 
        !          5492:          $
        !          5493:          _ LINK/SYMB=SYS$SYSTEM:SPITBOL/EXE=SYS$SYSTEM:SPITBOL -
        !          5494:          $
        !          5495:          __     SYS$LIBRARY:SPITBOL/OPT
        !          5496: 
        !          5497:     The recommended SPITBOL.OPT linker options file is:
        !          5498: 
        !          5499:          SPITV35,SPITGO,SPITMSGS,SPITSYS,SPITIOSYS,-
        !          5500:          SYS$SYSTEM:SYS.STB/SELECT
        !          5501:          BASE=%X100000
        !          5502:          IOSEGMENT=128
        !          5503:          STACK=10
        !          5504:          SYMBOL=LOAD_BASE,%X7FE00
        !          5505:          SYMBOL=STACK_LIMIT,%X10000
        !          5506: 
        !          5507:     Note  that  VAX/VMS  SPITBOL  is  a  licensed product and sources,
        !          5508:     objects and executable images are for use only  on  the  system(s)
        !          5509:     where  the  license  applies.   This applies both to the delivered
        !          5510:     files as well as any modified versions of them.
        !          5511: 
        !          5512: 
        !          5513:  11.15  Terminal Listing Options
        !          5514:  11.15  Terminal Listing Options
        !          5515:  _______________ _______ _______
        !          5516:     If  the  standard  output  channel  is  a  terminal   device,   an
        !          5517:     abbreviated  listing  format  is  used  by default.  See below for
        !          5518:     details.
        !          5519: 
        !          5520: 
        !          5521: 
        !          5522: 
        !          5523: 
        !          5524: 
        !          5525: 
        !          5526: 
        !          5527: 
        !          5528: 
        !          5529: 
        !          5530: 
        !          5531: 
        !          5532: 
        !          5533: 
        !          5534: 
        !          5535: 
        !          5536: 
        !          5537: 
        !          5538: 
        !          5539: 
        !          5540:          MACRO SPITBOL V3.5
        !          5541:                                                    PAGE 83 - [11.16]
        !          5542:          Implementation Information
        !          5543: 
        !          5544: 
        !          5545: 
        !          5546:  11.16  LOAD Function Usage
        !          5547:  11.16  LOAD Function Usage
        !          5548:  ___________ ________ _____
        !          5549:     The LOAD function is implemented with the  general  philosophy  of
        !          5550:     permitting  a  true  dynamic  load  of  externally  linked  images
        !          5551:     without  any  necessity  for  resorting  to  MACRO-32  or  similar
        !          5552:     machine-level  coding.  The first argument to LOAD is as described
        !          5553:     in Section 5.  The second argument  string  is  the  name  of  the
        !          5554:     image  to  be  loaded.   The usual defaults (those of the process)
        !          5555:     apply to this  name;   the  default  extension  is  ".EXE".   This
        !          5556:     string  should  never  be null, that form is reserved for a future
        !          5557:     implementation of a static LOAD.
        !          5558: 
        !          5559:     The  general  process  for  creating  a  LOADable  image  can   be
        !          5560:     summarized as follows:
        !          5561: 
        !          5562:       1. Prepare  and  debug  the  external  subroutine(s) you want to
        !          5563:          link into  a  loadable  function.   The  code  should  be  as
        !          5564:          thoroughly   checked   out  as  possible.    Debugging  under
        !          5565:          control of SPITBOL is difficult, and in extreme  cases,  bugs
        !          5566:          can  corrupt  the  interpreter's  store,  making them all but
        !          5567:          impossible to locate.
        !          5568: 
        !          5569:          Any language(s) can  be  used  to  program  the  subprograms,
        !          5570:          however  users of high-level languages usually need to follow
        !          5571:          some special guidelines (see below).
        !          5572: 
        !          5573:       2. Link an image consisting of the modules required.  The  image
        !          5574:          must  be  linked  at  a  suitable base address if it contains
        !          5575:          positionally dependent content (see below).  The link  should
        !          5576:          incorporate  a  search  of  SPITBOL's  symbol  table to avoid
        !          5577:          duplication of  the  run-time  library  in  the  image's  own
        !          5578:          virtual  space.   The  image  must  have  a  defined transfer
        !          5579:          address in user space.
        !          5580: 
        !          5581:       3. Run the  SPITBOL  program  and  issue  the  LOAD  call.   The
        !          5582:          function can now be used as an ordinary SPITBOL function.
        !          5583: 
        !          5584:     Details on each of these steps follow.
        !          5585: 
        !          5586: 
        !          5587: 
        !          5588: 
        !          5589: 
        !          5590: 
        !          5591: 
        !          5592: 
        !          5593: 
        !          5594: 
        !          5595: 
        !          5596: 
        !          5597: 
        !          5598: 
        !          5599: 
        !          5600: 
        !          5601: 
        !          5602: 
        !          5603: 
        !          5604:          MACRO SPITBOL V3.5
        !          5605:                                                    PAGE 84 - [11.16.1]
        !          5606:          Implementation Information
        !          5607: 
        !          5608: 
        !          5609: 
        !          5610:  11.16.1  High-Level Languages and LOAD
        !          5611:  11.16.1  High-Level Languages and LOAD
        !          5612:     Images  invoked  by  LOAD are not entered via the image activator.
        !          5613:     Instead,  SPITBOL  gets  to  them  via   an   ordinary   CALL-type
        !          5614:     instruction  to  the  entry  point  of  the image.  Note that most
        !          5615:     "high-level  languages"  do  not  support  the  declaration  of  a
        !          5616:     parameterized subprogram as an image entry point.
        !          5617: 
        !          5618:     To  permit  the use of such languages for LOAD functions, a module
        !          5619:     to solve the problem just described is provided with  the  SPITBOL
        !          5620:     delivery  in  SYS$LIBRARY:SPITHLS.OBJ.   This  module  defines  an
        !          5621:     entry point, and  then  jumps  one  word  past  the  global  label
        !          5622:     SPIT$LOAD_ENTRY.   (The  one  word  is  to  bypass the procedure's
        !          5623:     register save mask.)  This means that the entry subprogram of  any
        !          5624:     LOADable   function    which   uses   SPITHLS.OBJ  must  be  named
        !          5625:     SPIT$LOAD_ENTRY.
        !          5626: 
        !          5627: 
        !          5628:  11.16.2  Calling Conventions for LOAD
        !          5629:  11.16.2  Calling Conventions for LOAD
        !          5630:     All  arguments  to  LOAD  are  transmitted  to  the  function   by
        !          5631:     reference  pointers  to  values  on the stack (in P1 space).  (The
        !          5632:     only exception  is  unconverted  arguments  which  are  passed  by
        !          5633:     reference  to  a  block  in SPITBOL's dynamic area.)  The function
        !          5634:     may  overwrite  these  stacked  values  freely,  since  they   are
        !          5635:     discarded  when  the  function  returns.   It goes without further
        !          5636:     comment that in no case should an attempt ever be  made  to  store
        !          5637:     outside the defined length of the value.
        !          5638: 
        !          5639:     If  a  LOADed function requires a dynamically sized memory area to
        !          5640:     work in, the LOAD prototype can specify a 'junk'  parameter  which
        !          5641:     can  be  a  string  of the appropriate length when the function is
        !          5642:     called.  LOADed functions should under  no  circumstances  attempt
        !          5643:     to  dynamically  map  their  own  virtual  memory since this would
        !          5644:     likely interfere with SPITBOL's own allocation process.
        !          5645: 
        !          5646:     It may, for  some  applications,  be  helpful  to  be  aware  that
        !          5647:     arbitrary binary data can be stored in strings and buffers.
        !          5648: 
        !          5649: 
        !          5650:  11.16.3  Return Conventions for LOAD
        !          5651:  11.16.3  Return Conventions for LOAD
        !          5652:     When  an  external  function  is  ready  to  return, it may signal
        !          5653:     success or  failure,  and  if  it  succeeds,  it  must  return  an
        !          5654:     appropriate  result  of  the  type described by the LOAD prototype
        !          5655:     for the function.
        !          5656: 
        !          5657:     Success or failure is indicated on return by the low order bit  of
        !          5658:     R0,  according  to the normal VAX/VMS convention (the remainder of
        !          5659:     the register is ignored).
        !          5660: 
        !          5661:     If the low bit of R0 is set on  return,  this  indicates  success,
        !          5662:     and  R1  points  to  an  integer  value,  real  value,  or  string
        !          5663:     descriptor as appropriate for the function.   This  is  the  value
        !          5664:     that will be returned to SPITBOL as the result of the call.
        !          5665: 
        !          5666: 
        !          5667: 
        !          5668: 
        !          5669:          MACRO SPITBOL V3.5
        !          5670:                                                    PAGE 85 - [11.16.3]
        !          5671:          Implementation Information
        !          5672: 
        !          5673:     Many   high-level   languages   do  not  have  the  capability  of
        !          5674:     returning  values  in  this  manner,  so   SYS$LIBRARY:SPITHLS.OBJ
        !          5675:     contains  two  additional  entry  points, SPIT$SUCCESS_RETURN(obj)
        !          5676:     and SPIT$FAIL_RETURN().  These are co-routine  entry  points  that
        !          5677:     can  be called using the VAX/VMS standard calling conventions, and
        !          5678:     will make adjustments to the  stack,  R0  and  R1  and  return  to
        !          5679:     SPITBOL.   "Obj" is the address of the returned value when success
        !          5680:                                                         must
        !          5681:     is  to  be  indicated.   Both of these entry points must be called
        !          5682:     from the same level as when the function was  originally  entered,
        !          5683:     that  is,  at the same point in execution where the function would
        !          5684:     normally return.
        !          5685: 
        !          5686:     Before the LOADed function is invoked, and also  when  the  result
        !          5687:     is  being  checked,  SPITBOL  establishes a condition handler that
        !          5688:     will receive control if any exceptions  occur.   These  exceptions
        !          5689:     typically  are  the result of an error in the function itself,  an
        !          5690:     improper specification of argument or result  types  in  the  LOAD
        !          5691:     call,    or  an  improper  link  of a non-PIC function (see below)
        !          5692:     causing invalid addresses to  be  returned  to  SPITBOL.   In  any
        !          5693:     event,  this handler will, after printing a message indicating the
        !          5694:     cause of the error, attempt recovery by  forcing  failure  of  the
        !          5695:     function  call.   This  will  generally allow SPITBOL execution to
        !          5696:     continue.  Note that this handler will  only  receive  control  in
        !          5697:     the  event  that  the  user's function does not properly field the
        !          5698:     condition itself.
        !          5699: 
        !          5700: 
        !          5701:  11.16.4  Linking External Functions
        !          5702:  11.16.4  Linking External Functions
        !          5703:     Like the old saw  about   how  to  shave  a  gorilla,  linking  an
        !          5704:                                          very
        !          5705:     function image for LOAD must be done ____ carefully.  As  a  rule,
        !          5706:     you  will  have  an  easier  time  of it if the image to be linked
        !          5707:     contains solely position independent content  (PIC),  though  this
        !          5708:     is not absolutely necessary.
        !          5709: 
        !          5710:     SPITBOL  reserves a set of pages between an address defined by the
        !          5711:     link-time symbol LOAD_BASE, and the bottom of the interpreter  for
        !          5712:     loading  images.    LOAD_BASE  is  defined in the SPITBOL.OPT link
        !          5713:     options file and is normally hex 7FE00
        !          5714: 
        !          5715:     When requested by a LOAD(...) call  to  load  an  external  image,
        !          5716:     SPITBOL  first  allocates the next available page in this area for
        !          5717:     image information, and maps the image itself directly  above  this
        !          5718:     page,  taking  as  many  pages  as required.  The base address (if
        !          5719:     any) specified to the linker when the image was generated  has  no
        !          5720:     effect  on the base address of the load.   So even if the image is
        !          5721:     not PIC, it is possible to predict  in  advance  where  the  image
        !          5722:     will  be  loaded.  Knowing this, the image can be linked with this
        !          5723:     location as the  base  address.   Note  that  if  several  non-PIC
        !          5724:     images  are to be loaded with different LOAD(...) calls, the order
        !          5725:     of the loading is significant.
        !          5726: 
        !          5727:     As an example, suppose you have an object module called  PROCSTATS
        !          5728:     produced  by VAX/VMS Fortran V2 (non-PIC) which you wish to use as
        !          5729:     a LOAD function.  You would link the image with a  linker  command
        !          5730:     such as:
        !          5731: 
        !          5732: 
        !          5733: 
        !          5734:          MACRO SPITBOL V3.5
        !          5735:                                                    PAGE 86 - [11.16.4]
        !          5736:          Implementation Information
        !          5737: 
        !          5738:            $ LINK/MAP PROCSTATS,SYS$LIBRARY:SPITHLS,-
        !          5739:              SYS$SYSTEM:SPITBOL/SELECTIVE_SEARCH,PROCSTATS/OPT
        !          5740: 
        !          5741:     The  reason for linking against SPITBOL's symbol table is to avoid
        !          5742:     including the VMS shareable run-time library  in  the  image.   In
        !          5743:     some  cases,  there will also be global symbols of interest in the
        !          5744:     interpreter  to  which  the  program  will   need   access.    The
        !          5745:     PROCSTATS.OPT  options  file  would contain at least one statement
        !          5746:     to  define  the  base  address  of  the   image   of   the   form:
        !          5747:     "BASE=%X80000".    This  is  one  page  above  the usual LOAD_BASE
        !          5748:     (%X7FE00) to leave room for the image data page  which  is  always
        !          5749:     allocated first by SPITBOL.
        !          5750: 
        !          5751:     If  additional  non-PIC images were to be linked, the total amount
        !          5752:     of virtual space used by images to be loaded first would  have  to
        !          5753:     be  calculated,  in  order  to  determine  the  actual load (base)
        !          5754:     address. For images which are entirely PIC, the  base  address  is
        !          5755:     irrelevant.   Note that for languages such as Fortran, the code is
        !          5756:     PIC but the pure data is not.
        !          5757: 
        !          5758: 
        !          5759:  11.16.5  Unconverted Values and Results for LOAD
        !          5760:  11.16.5  Unconverted Values and Results for LOAD
        !          5761:     If a type other than "INTEGER", "STRING", or "REAL"  is  indicated
        !          5762:     in  the  first  argument of the call to LOAD, the value is said to
        !          5763:     be "unconverted."
        !          5764: 
        !          5765:     In the case of passed arguments, a pointer to the  internal  block
        !          5766:     for  the  argument is given to the program.  The first longword of
        !          5767:     any such block is a SPITBOL block-type  word.   The  remainder  of
        !          5768:     the  block  is vertically encoded depending on the block-type.  No
        !          5769:     discussion of the internals of the interpreter are provided  here.
        !          5770:     The  source  listing  gives  a complete description of the storage
        !          5771:     blocks  for  SPITBOL   and   should   be   consulted   by   anyone
        !          5772:     contemplating using unconverted values.
        !          5773: 
        !          5774:     In  the  case  of  returned  values,  a pointer to the unconverted
        !          5775:     result must  be  in  R1  (returned  value  register).   The  block
        !          5776:     pointed  to must be in SPITBOL-correct format, including the value
        !          5777:     of the block-type  word.   It  will  be  copied  by  SPITBOL  into
        !          5778:     dynamic memory upon return.
        !          5779: 
        !          5780: 
        !          5781: 
        !          5782: 
        !          5783: 
        !          5784: 
        !          5785: 
        !          5786: 
        !          5787: 
        !          5788: 
        !          5789: 
        !          5790: 
        !          5791: 
        !          5792: 
        !          5793: 
        !          5794: 
        !          5795: 
        !          5796: 
        !          5797:          MACRO SPITBOL V3.5
        !          5798:                                                    PAGE 87 - [11.17]
        !          5799:          Implementation Information
        !          5800: 
        !          5801: 
        !          5802: 
        !          5803:  11.17  MXLEN
        !          5804:  11.17  MXLEN
        !          5805:  ____________
        !          5806:     The   value   of   MXLEN  is  approximately  1,000,000.   This  is
        !          5807:     controlled by the "BASE=..." option  in  the  SPITBOL.OPT   linker
        !          5808:     options  file.   It is not recommended that this value be reduced,
        !          5809:     as it will limit the size  of  objects,  and  reduce  the  virtual
        !          5810:     space available for mapping in external (LOAD) images.
        !          5811: 
        !          5812: 
        !          5813:  11.18  Real Arithmetic
        !          5814:  11.18  Real Arithmetic
        !          5815:  ___________ __________
        !          5816:     Available  in  single  precision  with  a  printing  accuracy of 6
        !          5817:     digits.
        !          5818: 
        !          5819: 
        !          5820:  11.19  Extended Character Set
        !          5821:  11.19  Extended Character Set
        !          5822:  _______________ _________ ___
        !          5823:     All 256 8-bit ASCII codes are in  &ALPHABET.   The  tab  character
        !          5824:     may be used lexically in place of the space.
        !          5825: 
        !          5826: 
        !          5827:  11.20  REWIND
        !          5828:  11.20  REWIND
        !          5829:  _____________
        !          5830:     Available.
        !          5831: 
        !          5832: 
        !          5833:  11.21  Running SPITBOL
        !          5834:  11.21  Running SPITBOL
        !          5835:  ______________ _______
        !          5836: 
        !          5837: 
        !          5838:     SPITBOL  must  be  started with a command line in order to specify
        !          5839:     filenames for the standard channels, and  to  explicitly  override
        !          5840:     any  default  processing options.  This means that SPITBOL must be
        !          5841:     installed as a foreign command so that it can  recieve  a  command
        !          5842:     line.   If  SPITBOL  has  not been installed as a foreign command,
        !          5843:     this can be done individually by the  user  by  entering  the  VMS
        !          5844:     command:
        !          5845: 
        !          5846:                          $
        !          5847:                          _ SPIT*BOL :== $SPITBOL
        !          5848: 
        !          5849:     The  system  manager  normally  adds  this to the systemwide login
        !          5850:     command file as a part of the SPITBOL  delivery  process,  so  the
        !          5851:     above should not be necessary.
        !          5852: 
        !          5853:     The general form of the SPITBOL startup command line is:
        !          5854: 
        !          5855:             $ SPITBOL/switch... input-file/switch... "Any Text
        !          5856: 
        !          5857:     The  input-file  sets  the  identity of the standard input channel
        !          5858:     for SPITBOL.   The default extension  for  this  file  is  ".SPT".
        !          5859:     The  standard input channel represents the program source, and any
        !          5860:     data for  the  preassociated  INPUT  variable.   Such  data  input
        !          5861:     should  thus  immediately  follow the END statement of the source.
        !          5862:     All switches are optional.
        !          5863: 
        !          5864:     If no input-file is given, or  if  SPITBOL  is  unable  to  get  a
        !          5865:     command line, the default input-file will be SYS$INPUT.
        !          5866: 
        !          5867: 
        !          5868: 
        !          5869: 
        !          5870:          MACRO SPITBOL V3.5
        !          5871:                                                    PAGE 88 - [11.21]
        !          5872:          Implementation Information
        !          5873: 
        !          5874:     The  initial  value of the startup command line as provided by the
        !          5875:     VMS Command Line Interpreter (CLI) is  assigned  to  the  &ERRTEXT
        !          5876:     keyword.  This makes it possible to examine the command line as it
        !          5877:     is given to SPITBOL, in order  to  determine  filenames,  switches
        !          5878:     and  the like.   (The assignment to &ERRTEXT is made just prior to
        !          5879:     execution, and is  not  affected  by  any  preceeding  compilation
        !          5880:     errors.)   Note that the CLI will compress runs of tabs and blanks
        !          5881:     into single blanks, and place all unquoted  text  in  upper  case.
        !          5882:     Also  note that the command string begins with the first non-blank
        !          5883:                following
        !          5884:     character  _________  the VMS command name.   CLI "comments" (text
        !          5885:     following an unquoted "!" on the  command  line)  are  not  passed
        !          5886:     either.
        !          5887: 
        !          5888:     SPITBOL  recognizes  a  double-quote (") as an end-of-command line
        !          5889:     delimiter.  Any text following the double-quote  will  be  ignored
        !          5890:     by  SPITBOL,  but  will  appear  intact  in  the  initial value of
        !          5891:     &ERRTEXT.  This provides a mechanism for  passing  arbitrary  text
        !          5892:     into  the  program  from the command line.  The CLI will not alter
        !          5893:     the text following this double quote.
        !          5894: 
        !          5895:     It should be pointed out that the availability of startup  command
        !          5896:     line  text  in  &ERRTEXT is an addition in VAX/VMS SPITBOL, and is
        !          5897:     not  necessarily  portable  to  other   implementations   of   the
        !          5898:     language.
        !          5899: 
        !          5900:     In  some  cases,  there  may  be  a SPITBOL application or utility
        !          5901:     program for which a "custom" command  may  be  desired.   This  is
        !          5902:     easily achieved with a definition something like:
        !          5903: 
        !          5904:         $
        !          5905:         _ SPUTIL :== $SPITBOL/OUT=TT:/LOAD=SYS$LIBRARY:SPUTIL NL:
        !          5906: 
        !          5907:              $
        !          5908:     Typing  "_SPUTIL"  as  a VMS command will then load the saved EXIT
        !          5909:     file named SPUTIL in SYS$LIBRARY and execute it with the  standard
        !          5910:     output  file assigned to the terminal.  Other permutations will be
        !          5911:     useful depending on the particular application.
        !          5912: 
        !          5913: 
        !          5914: 
        !          5915: 
        !          5916: 
        !          5917: 
        !          5918: 
        !          5919: 
        !          5920: 
        !          5921: 
        !          5922: 
        !          5923: 
        !          5924: 
        !          5925: 
        !          5926: 
        !          5927: 
        !          5928: 
        !          5929: 
        !          5930: 
        !          5931: 
        !          5932: 
        !          5933: 
        !          5934: 
        !          5935:          MACRO SPITBOL V3.5
        !          5936:                                                    PAGE 89 - [11.21.1]
        !          5937:          Implementation Information
        !          5938: 
        !          5939: 
        !          5940: 
        !          5941:  11.21.1  Startup Switches
        !          5942:  11.21.1  Startup Switches
        !          5943:     Startup switches are optional in the sense that there are  defined
        !          5944:     defaults  for  all  of  them  that  should be adequate most of the
        !          5945:     time.  Switch names can be abbreviated to the minimum  unambiguous
        !          5946:     length.  A syntax error in the startup command line will cause the
        !          5947:     interpreter to exit with a message.
        !          5948: 
        !          5949:     Switches may appear at any point in the command  line;   they  are
        !          5950:     processed  left-to-right.   There  are no 'file-specific' switches
        !          5951:     as with some VMS languages, all switches are global.  The  use  of
        !          5952:     multiple  input  files separated either by commas or plus signs is
        !          5953:     not
        !          5954:     ___ supported.
        !          5955: 
        !          5956:     These are the switches provided on  the  SPITBOL  startup  command
        !          5957:     line:
        !          5958: 
        !          5959: 
        !          5960:      1.  /CRC /NOCRC
        !          5961:          This  switch  is  only  meaningful  on a /LOAD=... operation,
        !          5962:          where the specification of  /NOCRC  will  bypass  the  cyclic
        !          5963:          reducdancy  check of the SPITBOL code region.  The purpose of
        !          5964:          this check is to insure that the  version  of  SPITBOL  being
        !          5965:          used  is  the same as the version under which the exit module
        !          5966:          was saved.  As SPITBOL  also  checks  version  identification
        !          5967:          data  and  other  parameters, the overhead for this check may
        !          5968:          be considered unnecessary for frequently used  load  modules.
        !          5969:          In  such  cases,  /NOCRC  can  be  profitably specified.  The
        !          5970:          default is /CRC.
        !          5971: 
        !          5972:      2.  /CSTATS /NOCSTATS
        !          5973:          This  switch  will  suppress  the  printing  of   compilation
        !          5974:          statistics  on  the  output  file.  "/CSTATS" is the default.
        !          5975:          If /NOLIST has been specified, the default is /NOCSTATS.
        !          5976: 
        !          5977:      3.  /ESTATS /NOESTATS
        !          5978:          This  switch  will  suppress  the   printing   of   execution
        !          5979:          statistics  on  the  output  file.  "/ESTATS" is the default.
        !          5980:          If  /NOLIST  has  been  specified,  then   the   default   is
        !          5981:          /NOESTATS.
        !          5982: 
        !          5983:      4.  /EXECUTE /NOEXECUTE
        !          5984:          This  switch  has  the  same  logical effect as a  -NOEXECUTE
        !          5985:          control card in the source  program.   SPITBOL  will  process
        !          5986:          the  source  program,  and  then  exit  with  a  message that
        !          5987:          Execution Was Suppressed.  The default is "/EXECUTE".
        !          5988: 
        !          5989:      5.  /LIST[=filename] /NOLIST
        !          5990:          The /LIST switch allows specification  of  the  filename  for
        !          5991:          the  standard  output  channel.   If  a  terminal  device  is
        !          5992:          specified for the  /LIST  switch,  then  form  feeds  in  the
        !          5993:          program  listing  will be suppressed.  The default device and
        !          5994:          account for this  file  is  the  same  as  that  under  which
        !          5995:          SPITBOL  is  being run.  The default name for the output file
        !          5996:          is the input  file's  name,  and  the  default  extension  is
        !          5997: 
        !          5998: 
        !          5999:          MACRO SPITBOL V3.5
        !          6000:                                                    PAGE 90 - [11.21.1]
        !          6001:          Implementation Information
        !          6002: 
        !          6003:          ".LIS".   The  program listing and compilation statistics are
        !          6004:          sent to this file.  If neither of  /OUTPUT=...  or  /NOOUTPUT
        !          6005:          are  also  specified  on  the  command  line,  then execution
        !          6006:          output is also directed to this file.  This  includes  OUTPUT
        !          6007:          assigned text and TRACE and DUMP output.
        !          6008: 
        !          6009:          The  /NOLIST  switch  indicates that source listing is not to
        !          6010:          be generated. /NOLIST also causes an implicit  /NOESTATS  and
        !          6011:          /NOCSTATS.   Note  that  the  appearance  of /NOLIST does not
        !          6012:          mean that no output will  be  sent  to  the  standard  output
        !          6013:          channel.   However,  if the program makes no reference to the
        !          6014:          standard output channel, then if /NOLIST is  specified,  this
        !          6015:          channel will never be opened.
        !          6016: 
        !          6017:          /LIST  with  no  filename  inverts  the  effect of a previous
        !          6018:          /NOLIST  spec.   That  is,   enables   source   listing   and
        !          6019:          compilation statistics.
        !          6020: 
        !          6021:      6.  /MINC=nnn
        !          6022:          This  switch  controls the number of pages by which SPITBOL's
        !          6023:          working store is expanded when it becomes  exhausted.   Under
        !          6024:          normal  circumstances,  it should not be necessary to specify
        !          6025:          this switch, however, "/MINC=0" will prevent  any  additional
        !          6026:          allocation  to SPITBOL past the MINT allocation, and may thus
        !          6027:          be useful  in  preventing  the  unrestrained  growth  of  the
        !          6028:          interpreter.
        !          6029: 
        !          6030:          Even  if  MINC is non-zero, there are three cases which could
        !          6031:          concievably cause dynamic allocation of a SPITBOL  object  to
        !          6032:          fail.  These are:
        !          6033: 
        !          6034:             - The  size  of  the object exceeds &MAXLNGTH (MXLEN).  As
        !          6035:               this is initially greater than one million,  this  fault
        !          6036:               is  very  unlikely  to  occur  except as the result of a
        !          6037:               programming error.
        !          6038: 
        !          6039:             - If allocation would cause the virtual  memory  quota  to
        !          6040:               be  exceeded,  SPITBOL  will  print  a  MEMORY  OVERFLOW
        !          6041:               error, and terminate execution.  This is  also  unlikely
        !          6042:               on most systems.
        !          6043: 
        !          6044:             - If  SPITBOL  has  been  linked  allowing  RMS buffers to
        !          6045:               extend  in   P0  space  (linker  option  P0BUFS  -   the
        !          6046:               default),  then  with  a  large number of simultaneously
        !          6047:               open files  an  RMS  space  extension  would  block  the
        !          6048:               contiguous  growth  of  the  dynamic  area  and  cause a
        !          6049:               memory overflow.
        !          6050: 
        !          6051:          The default for this switch is "/MINC=20" which is 10K  bytes
        !          6052:          or about 2,000 SPITBOL 'words.'
        !          6053: 
        !          6054:      7.  /MINT=nnn
        !          6055:          This  switch  controls  the amount of  virtual memory (in 512
        !          6056:          Byte pages) that will be  initally  allocated  for  SPITBOL's
        !          6057:          working   storage   areas.   The  SPITBOL  VMS  interface  is
        !          6058:          designed to  permit  these  working  storage  areas  to  grow
        !          6059: 
        !          6060: 
        !          6061:          MACRO SPITBOL V3.5
        !          6062:                                                    PAGE 91 - [11.21.1]
        !          6063:          Implementation Information
        !          6064: 
        !          6065:          indefinitely,  as  long as the region remains contiguous, and
        !          6066:          there are pages available  in  the  process'  virtual  quota.
        !          6067:          However,  SPITBOL will not request additional memory from VMS
        !          6068:          unless it cannot get  enough  by  regenerating  its  existing
        !          6069:          store.   So,  this switch may be useful in some situations to
        !          6070:          avoid garbage collector  thrashing.   The  default  for  this
        !          6071:          switch  is  "/MINT=200"  which  is  equivalent to  about 100K
        !          6072:          bytes, or 25,000 SPITBOL 'words' (VAX Longwords).
        !          6073: 
        !          6074:          For most applications, the performance  will  increase  quite
        !          6075:          dramatically  as  real  memory  is made available.  Past that
        !          6076:          point, additional working set will improve  performance  only
        !          6077:          marginally.   As  the  dynamic  space  is  allowed  to become
        !          6078:          increasingly  virtual,  performance   will   very   gradually
        !          6079:          deteriorate  because  of  the  thrashing caused (principally)
        !          6080:          during garbage collection.  Thus as a general  guide,  it  is
        !          6081:          usually  best  to  minimize garbage collection at the expense
        !          6082:          of additional memory.
        !          6083: 
        !          6084:          Stack space is not included in the  MINT  allocation.   Stack
        !          6085:          is allocated automatically as needed.
        !          6086: 
        !          6087:      8.  /OUTPUT[=Filename]
        !          6088:          The  /OUTPUT=filename  switch  requests an alternate file for
        !          6089:          the standard output  channel  at  execution  time.   If  this
        !          6090:          switch  is  not  specified, then execution output is directed
        !          6091:          at the same file  as  the  source  listing  (/LIST=filename).
        !          6092:          This  file  is not opened until execution begins.  If at that
        !          6093:          time the channel cannot  be  opened,  SPITBOL  exits  with  a
        !          6094:          fatal status.
        !          6095: 
        !          6096:          /NOOUTPUT   directs  any  execution-time  references  to  the
        !          6097:          standard output channel to the null device (NL:)
        !          6098: 
        !          6099:          /OUTPUT with no  filename  restores  the  default  condition.
        !          6100:          That is, execution output is appended to the listing output.
        !          6101: 
        !          6102:          Note that /OUTPUT and /LIST are not synonymous.
        !          6103: 
        !          6104:      9.  /PAGE /NOPAGE
        !          6105:          If  this  switch  is specified, page separators in the source
        !          6106:          listing and statistics will be a few blank lines, instead  of
        !          6107:          form  feeds.   "/PAGE"  is  the  default, unless the standard
        !          6108:          output channel (see /OUTPUT switch) is a terminal,  in  which
        !          6109:          case "/NOPAGE" is the default.
        !          6110: 
        !          6111:          At  startup,  LIB$LP_LINES  is called to get the page length.
        !          6112:          From  the  value  returned  (66  unless  the   logical   name
        !          6113:          SYS$LP_LINES  is  assigned), six  is subtracted to leave room
        !          6114:          for page shoulders.
        !          6115: 
        !          6116:     10.  /WARN /NOWARN
        !          6117:          When /NOWARN is indicated on the command  line,  only  errors
        !          6118:          and  severe  errors  in  the  VMS  interface  logic  will  be
        !          6119:          reported on  SYS$ERROR.   This  can  be  useful  to  suppress
        !          6120:          messages  regarding source line truncation, exit module saves
        !          6121: 
        !          6122: 
        !          6123:          MACRO SPITBOL V3.5
        !          6124:                                                    PAGE 92 - [11.21.1]
        !          6125:          Implementation Information
        !          6126: 
        !          6127:          and similar messages. /WARN, the  default,  causes  reporting
        !          6128:          of such conditions.
        !          6129: 
        !          6130:          This  switch does not affect in any way SPITBOL's handling of
        !          6131:          errors with respect to the program.
        !          6132: 
        !          6133:     11.  /WIDTH=nnn
        !          6134:          SPITBOL attempts to compute a proper width for  the  standard
        !          6135:          output  file.   The switch "/WIDTH=n" can be used to override
        !          6136:          any  default.    Otherwise,   if   the   output   device   is
        !          6137:          record-oriented  (including  spooled  files),  the default is
        !          6138:          the buffer for the  device  as  indicated  by  VMS.   If  the
        !          6139:          buffer  size  cannot  be  obtained,  or  is outside the range
        !          6140:          [0..255], then a final default of 132 (decimal) is applied.
        !          6141: 
        !          6142: 
        !          6143: 
        !          6144: 
        !          6145: 
        !          6146: 
        !          6147: 
        !          6148: 
        !          6149: 
        !          6150: 
        !          6151: 
        !          6152: 
        !          6153: 
        !          6154: 
        !          6155: 
        !          6156: 
        !          6157: 
        !          6158: 
        !          6159: 
        !          6160: 
        !          6161: 
        !          6162: 
        !          6163: 
        !          6164: 
        !          6165: 
        !          6166: 
        !          6167: 
        !          6168: 
        !          6169: 
        !          6170: 
        !          6171: 
        !          6172: 
        !          6173: 
        !          6174: 
        !          6175: 
        !          6176: 
        !          6177: 
        !          6178: 
        !          6179: 
        !          6180: 
        !          6181: 
        !          6182: 
        !          6183: 
        !          6184: 
        !          6185:          MACRO SPITBOL V3.5
        !          6186:                                                    PAGE 93 - [11.22]
        !          6187:          Implementation Information
        !          6188: 
        !          6189: 
        !          6190: 
        !          6191:  11.22  Stack Overflow
        !          6192:  11.22  Stack Overflow
        !          6193:  ____________ ________
        !          6194:     SPITBOL  stack  is  located  in  P0  (program)  space.   It  grows
        !          6195:     downwards  as  needed  from  LOAD_BASE  to STACK_LIMIT.  These two
        !          6196:     values are defined in the SPITBOL Link options file.  In  general,
        !          6197:     these  values  are  set  such  that stack overflow is not possible
        !          6198:     unless a program is truly out of control.
        !          6199: 
        !          6200: 
        !          6201:  11.23  TERMINAL
        !          6202:  11.23  TERMINAL
        !          6203:  _______________
        !          6204:     TERMINAL  is  available  and  is  associated  with  SYS$INPUT  and
        !          6205:     SYS$OUTPUT.   The  first  assignment  or  access to TERMINAL opens
        !          6206:     this channel.
        !          6207: 
        !          6208: 
        !          6209:  11.24  Time
        !          6210:  11.24  Time
        !          6211:  ___________
        !          6212:     All execution times in the VAX/VMS Macro  SPITBOL  system  are  in
        !          6213:     CPU  time  increments  of 10 (milliseconds).  This covers both the
        !          6214:     times shown in the statistics, and  the  time  retrieved  via  the
        !          6215:     system TIME function.  Wall time is available through DATE.
        !          6216: 
        !          6217: 
        !          6218: 
        !          6219: 
        !          6220: 
        !          6221: 
        !          6222: 
        !          6223: 
        !          6224: 
        !          6225: 
        !          6226: 
        !          6227: 
        !          6228: 
        !          6229: 
        !          6230: 
        !          6231: 
        !          6232: 
        !          6233: 
        !          6234: 
        !          6235: 
        !          6236: 
        !          6237: 
        !          6238: 
        !          6239: 
        !          6240: 
        !          6241: 
        !          6242: 
        !          6243: 
        !          6244: 
        !          6245: 
        !          6246: 
        !          6247: 
        !          6248: 
        !          6249: 
        !          6250: 
        !          6251: 
        !          6252: 
        !          6253:          MACRO SPITBOL V3.5
        !          6254:                                                    PAGE 94 - [12]
        !          6255:          Implementation Information
        !          6256: 
        !          6257: 
        !          6258: 
        !          6259:                     *--------------------------------*
        !          6260:                       [12] Installation and Delivery
        !          6261:                     | [12] Installation and Delivery |
        !          6262:                     *--------------------------------*
        !          6263: 
        !          6264:     This  section  of  the  SPITBOL  manual  describes the process for
        !          6265:     unpackaging and installing the  VAX/VMS  MACRO  SPITBOL  software.
        !          6266:     This  section  is  also provided in hardcopy form with the 1600BPI
        !          6267:     tape to facilitate the  installation  process.   If  this  is  the
        !          6268:     first  time  you  have performed the delivery, please read through
        !          6269:     these directions before starting;  the  delivery  process  is  not
        !          6270:     highly  automated, and there will be a number of decisions for you
        !          6271:     to make.
        !          6272: 
        !          6273:     There are four steps to be  initially  performed  to  deliver  and
        !          6274:     install the software package.
        !          6275: 
        !          6276: 
        !          6277:      1.  Get  the files from the tape into the proper directories, and
        !          6278:          link  the  interpreter.    The   directories   involved   are
        !          6279:          SYS$LIBRARY:,  SYS$HELP:,  and  SYS$SYSTEM:.  Be certain that
        !          6280:          these VMS standard logical names are  defined  to  correspond
        !          6281:          to  valid  directories  on the system disk before undertaking
        !          6282:          the software installation.
        !          6283: 
        !          6284:      2.  Establish the  VMS  environment  and  commands  necessary  to
        !          6285:          execute MACRO SPITBOL.
        !          6286: 
        !          6287:      3.  Generate  the  reference  manual  and help file.  The program
        !          6288:          which does this is a SPITBOL program, so this  serves  as  an
        !          6289:          installation checkout.
        !          6290: 
        !          6291:      4.  Delete  and/or  copy  off  any optional files which you don't
        !          6292:          want to keep.
        !          6293: 
        !          6294:     Each of these steps is now detailed in turn.
        !          6295: 
        !          6296: 
        !          6297:     NOTE:
        !          6298:     NOTE:
        !          6299:     _____ This  version  of  MACRO  SPITBOL requires version 2 of VMS.
        !          6300:     If you are running any  version  1  of  VMS  you  cannot  use  the
        !          6301:     interpreter.   You  must first upgrade your system to version 2 of
        !          6302:     VMS before attempting to install MACRO SPITBOL.
        !          6303: 
        !          6304: 
        !          6305: 
        !          6306: 
        !          6307: 
        !          6308: 
        !          6309: 
        !          6310: 
        !          6311: 
        !          6312: 
        !          6313: 
        !          6314: 
        !          6315: 
        !          6316: 
        !          6317: 
        !          6318:          MACRO SPITBOL V3.5
        !          6319:                                                    PAGE 95 - [12.1]
        !          6320:          Implementation Information
        !          6321: 
        !          6322: 
        !          6323: 
        !          6324:  12.1  Transferring Delivery Files
        !          6325:  12.1  Transferring Delivery Files
        !          6326:  __________________ ________ _____
        !          6327: 
        !          6328: 
        !          6329:     Follow these steps:
        !          6330: 
        !          6331: 
        !          6332:      1.  Log on to the hardcopy system console  using  the  privileged
        !          6333:          SYSTEM  account.   Be certain that your default is set to the
        !          6334:          system  disk.   "BYPASS"  privilege  is  recommended  as   it
        !          6335:          insures  that  there  will be no snags in renaming or copying
        !          6336:          files.
        !          6337: 
        !          6338:      2.  If there  are  any  existing  files  or  directories  for  an
        !          6339:          earlier  version  of  SPITBOL,  they should be deleted.  (The
        !          6340:          new version  is  strictly  upward  compatible  with  previous
        !          6341:          versions.)   If  it  does  not already exist, create an empty
        !          6342:          scratch directory named SYS$DISK:[SPITBOL] with the command:
        !          6343: 
        !          6344:                          $
        !          6345:                          _ CRE/DIR SYS$DISK:[SPITBOL]
        !          6346: 
        !          6347: 
        !          6348:      3.  Set your default to the SPITBOL directory using the command:
        !          6349: 
        !          6350:                        $
        !          6351:                        _ SET DEFAULT SYS$DISK:[SPITBOL]
        !          6352: 
        !          6353: 
        !          6354:      4.  Mount the delivery tape on a drive with a command such as:
        !          6355: 
        !          6356:                               $
        !          6357:                               _ MOUNT MT:/OVER=ID
        !          6358: 
        !          6359: 
        !          6360:      5.  Copy all files from the  tape  into  the  directory  using  a
        !          6361:          command similar to:
        !          6362: 
        !          6363:                                 $
        !          6364:                                 _ COPY MT:*.* *
        !          6365: 
        !          6366: 
        !          6367:      6.  Dismount the tape with a command such as:
        !          6368: 
        !          6369:                                 $
        !          6370:                                 _ DISMOUNT MT:
        !          6371: 
        !          6372: 
        !          6373:      7.  Enter the command:
        !          6374: 
        !          6375:                                   $
        !          6376:                                   _ @SPITBOL
        !          6377: 
        !          6378:          This   command   file  will  rename  files  to  their  proper
        !          6379:          directories, and link the interpreter image.
        !          6380: 
        !          6381:     Sites with a previous release  of  the  interpreter  may  want  to
        !          6382:     print  a  copy of [SPITBOL]RELNOTES.LIS which documents changes in
        !          6383:     this release.
        !          6384: 
        !          6385: 
        !          6386: 
        !          6387: 
        !          6388:          MACRO SPITBOL V3.5
        !          6389:                                                    PAGE 96 - [12.2]
        !          6390:          Implementation Information
        !          6391: 
        !          6392: 
        !          6393: 
        !          6394:  12.2  Installing MACRO SPITBOL
        !          6395:  12.2  Installing MACRO SPITBOL
        !          6396:  ________________ _____ _______
        !          6397: 
        !          6398: 
        !          6399:      1.  Enter the commands:
        !          6400: 
        !          6401:                     $
        !          6402:                     _ SPIT*BOL :== $SYS$SYSTEM:SPITBOL
        !          6403:                     $
        !          6404:                     _ ASSIGN/SYS "<site-name>" SYS$SITENAME
        !          6405: 
        !          6406:          In the above, "<site-name>" is  any  text  string  of  28  or
        !          6407:          fewer   characters  which  SPITBOL  will  use  for  the  site
        !          6408:          identification.
        !          6409: 
        !          6410:          Using an editor, place the first of the above definitions  in
        !          6411:          the  systemwide  login  command  file  to define them for all
        !          6412:          users.   (The  name  of  this  file  varies  from  system  to
        !          6413:          system,  SYLOGIN.COM  and  SYSLOGIN.COM  in  SYS$MANAGER:  is
        !          6414:          typical.  If your site has not established such a file,  then
        !          6415:          users   will  have  to  define  this  command  in  their  own
        !          6416:          LOGIN.COM files.)   The ASSIGN  command  should  be  inserted
        !          6417:          into SYS$MANAGER:SYSTARTUP.COM .
        !          6418: 
        !          6419:      2.  In  general,  if  SPITBOL  is  to  be  used frequently, it is
        !          6420:          recommended that it be installed as a shareable image.   This
        !          6421:          can  be  done  (from  the  SYSTEM  account) using the command
        !          6422:          lines:
        !          6423: 
        !          6424:                    $ MCR INSTALL
        !          6425:                    SYS$SYSTEM:SPITBOL.EXE/SHARE/OPEN/HEADER
        !          6426: 
        !          6427:          SPITBOL  should  not   normally   be   installed   with   any
        !          6428:          privileges.
        !          6429: 
        !          6430: 
        !          6431: 
        !          6432:  12.3  Interpreter Checkout and Documentation Generation
        !          6433:  12.3  Interpreter Checkout and Documentation Generation
        !          6434:  _________________ ________ ___ _____________ __________
        !          6435: 
        !          6436: 
        !          6437:      1.  Set your default to SYS$LIBRARY:
        !          6438: 
        !          6439:      2.  Enter the command:
        !          6440: 
        !          6441:                     $
        !          6442:                     _ SPIT GPMDOC " {SET INPUT,SPITBOL.GPM}
        !          6443: 
        !          6444:          Note the blank  following  the  double  quote  in  the  above
        !          6445:          ____ ___ _____  _________  ___  ______  _____  __  ___  _____
        !          6446:          command.  This blank is significant and must be  included  as
        !          6447:          ________  ____ _____ __ ___________ ___ ____ __  ________  __
        !          6448:          shown.
        !          6449:          ______  If all is well, this will cause the system to ask  if
        !          6450:          you  want  to  produce the manual.  Answer "yes".  Generating
        !          6451:          the approximately 100 page manual takes about  5  minutes  on
        !          6452:          an  unloaded  VAX 11/780.  If it is working, a message should
        !          6453:          appear on your console for every page produced.
        !          6454: 
        !          6455: 
        !          6456: 
        !          6457: 
        !          6458: 
        !          6459: 
        !          6460:          MACRO SPITBOL V3.5
        !          6461:                                                    PAGE 97 - [12.3]
        !          6462:          Implementation Information
        !          6463: 
        !          6464:          After this, you will be asked if you  want  to  generate  the
        !          6465:          help  file.   Again  answer  "yes".   The generated file is a
        !          6466:          reformatted  version  of  the  manual  itself,  in  VMS  help
        !          6467:          library format.
        !          6468: 
        !          6469:          When this concludes, the GPMDOC program exits.
        !          6470: 
        !          6471:      3.  Print  SYS$LIBRARY:GPMDOC.LIS  on  a  132 column line printer
        !          6472:          and examine the listing to be sure that  the  interpreter  is
        !          6473:          functioning  properly.   Look  at  the  2  line header on the
        !          6474:          first listing page and be certain  that  the  site  name  you
        !          6475:          defined above appears there.
        !          6476: 
        !          6477:      4.  Print  SYS$LIBRARY:SPITBOL.MAN on (if possible) an 80 column,
        !          6478:          8.5x11 inch, white paper printer.  An  LA120  DECwriter  will
        !          6479:          do  if there is plenty of time available.  If any interactive
        !          6480:                                                    $
        !          6481:          device is  used,  be  certain  to  type  "_ SET TERM/NOBROAD"
        !          6482:          before  starting.   The table of contents is at the back - it
        !          6483:          should be moved to the indicated place at the beginning.
        !          6484: 
        !          6485:      5.  You should now decide if you  want  to  add  the  SPITBOL.HLP
        !          6486:          help  file to the system help file.  (The only reason for not
        !          6487:          so doing would be that it consumes about 300 blocks  of  disk
        !          6488:          space).   If  you  decide  to  do  this,  set your default to
        !          6489:          SYS$HELP: and enter the following commands:
        !          6490: 
        !          6491:                       $
        !          6492:                       _ LIB/COMPR=KEYSIZ:31/HELP HELPLIB
        !          6493:                       $
        !          6494:                       _ LIB/REPLACE/HELP HELPLIB SPITBOL
        !          6495:                       $
        !          6496:                       _ LIB/COMPRESS/HELP HELPLIB
        !          6497:                       $
        !          6498:                       _ PURGE HELPLIB.HLB
        !          6499: 
        !          6500: 
        !          6501: 
        !          6502: 
        !          6503:  12.4  Delivery File Cleanup
        !          6504:  12.4  Delivery File Cleanup
        !          6505:  ______________ ____ _______
        !          6506: 
        !          6507: 
        !          6508:     The delivery and  installation  process  is  concluded.   At  this
        !          6509:     point,  some  sites  may  choose  to  delete some of the delivered
        !          6510:     files in order to free up as much system disk space  as  possible.
        !          6511:     To  such  an  end,  a list of all delivered and generated files is
        !          6512:     given here, grouped by  their  function.   Examine  the  list  and
        !          6513:     delete the ones you don't want.
        !          6514: 
        !          6515: 
        !          6516:      1.  BASIC INTERPRETER:
        !          6517:          Basic  interpreter  files  consist  of  the executable image,
        !          6518:          objects, and sources.
        !          6519: 
        !          6520:          The executable image  is  built  as  SYS$SYSTEM:SPITBOL.EXE .
        !          6521:          This  file must not be deleted.  Also, SYS$SYSTEM:SPITBOL.STB
        !          6522:          is the corresponding symbol table  file  which  can  be  used
        !          6523:          when  linking images for use by LOAD(...).  It should also be
        !          6524:          retained.
        !          6525: 
        !          6526: 
        !          6527: 
        !          6528: 
        !          6529:          MACRO SPITBOL V3.5
        !          6530:                                                    PAGE 98 - [12.4]
        !          6531:          Implementation Information
        !          6532: 
        !          6533:          The  objects  are  in  SYS$LIBRARY:  and  named  SPITSYS.OBJ,
        !          6534:          SPITIOSYS,  SPITGO,  SPITMSGS and SPITV35.  It is recommended
        !          6535:          that    these    files     be     kept.      In     addition,
        !          6536:          SYS$LIBRARY:SPITBOL.OPT  is the standard SPITBOL link options
        !          6537:          file and should be retained if the objects are.
        !          6538: 
        !          6539:          The sources are in SYS$LIBRARY and have  the  same  names  as
        !          6540:          the  objects  except  that the file extensions are different.
        !          6541:          SPITGO.MAR is the entry  point,  and  provides  command  line
        !          6542:          processing,   initialization   and   basic  file  assignment.
        !          6543:          SPITSYS.MAR   contains   the    VMS    interface    routines.
        !          6544:          SPITIOSYS.MAR  contains  the VMS interface routines for input
        !          6545:          and output operations.  SPITV35.MAR is  the  source  for  the
        !          6546:          interpreter  itself.  SPITMSGS.MSG is the source text for the
        !          6547:          error messages  of  the  system.  It  is  input  to  the  VMS
        !          6548:          "MESSAGE" processor.
        !          6549: 
        !          6550:          SPITMACS.MAR  and  SPITMACS.MLB  comprise  the  macro library
        !          6551:          which is required for assembling any of these sources.
        !          6552: 
        !          6553:          These source files will  be  of  academic  interest  to  most
        !          6554:          sites,  and  can  be  profitably deleted since they consume a
        !          6555:          substantial quantity of disk space.
        !          6556: 
        !          6557:      2.  INTERPRETER SUPPORT FILES:
        !          6558:          On SYS$LIBRARY: will be found SPITHLS in .OBJ and .MAR  form.
        !          6559:          These  files  are  used  in  conjunction  with  the LOAD(...)
        !          6560:          feature and should not be deleted.  In  any  event  they  are
        !          6561:          quite small.
        !          6562: 
        !          6563:      3.  DOCUMENTATION FILES:
        !          6564:          The   delivery  process  outlined  above  uses  and  produces
        !          6565:          several files that relate to MACRO SPITBOL documentation.
        !          6566: 
        !          6567:          In SYS$LIBRARY: will be found SPITBOL.GPM and  SPITTEXT.GPM .
        !          6568:          These  two  files,  together, comprise the needed information
        !          6569:          to generate both the manual and help file text.  They can  be
        !          6570:          deleted once the manual and/or help file has been produced.
        !          6571: 
        !          6572:          The    delivery    process    generates    the    manual   in
        !          6573:          SYS$LIBRARY:SPITBOL.MAN. Once a good copy of  this  has  been
        !          6574:          printed, this file can be deleted.
        !          6575: 
        !          6576:          The  help  file  text  is  produced  in SYS$HELP:SPITBOL.HLP.
        !          6577:          This should be deleted only if no use is made of it.  If  you
        !          6578:          have  added it to the system help library, keep the .HLP file
        !          6579:          in case a future VMS delivery reinitializes the  system  help
        !          6580:          file.
        !          6581: 
        !          6582:          The   delivery   process   generates  a  SPITBOL  listing  in
        !          6583:          SYS$LIBRARY:GPMDOC.LIS.  This file is of  no  value  once  it
        !          6584:          has been checked out, and can be deleted.
        !          6585: 
        !          6586: 
        !          6587: 
        !          6588: 
        !          6589: 
        !          6590: 
        !          6591:          MACRO SPITBOL V3.5
        !          6592:                                                    PAGE 99 - [12.4]
        !          6593:          Implementation Information
        !          6594: 
        !          6595:      4.  GPMDOC:
        !          6596:          GPMDOC  is  the  text processing program (written in SPITBOL)
        !          6597:          that produces the manual and  help  text  files.   It  is  an
        !          6598:          interesting  program  in  its  own right, and for that reason
        !          6599:          you may wish to keep it.  Otherwise, all of the GPMDOC  files
        !          6600:          can be deleted, they are in SYS$LIBRARY:
        !          6601: 
        !          6602:          GPMDOC.SPT is the basic GPMDOC program source.
        !          6603: 
        !          6604:          GPMBIF.GPM  is  a  file  of  auxiliary  definitions needed by
        !          6605:          GPMDOC when it starts up.
        !          6606: 
        !          6607:          GPMDOC.GPM  is  part  of  the  reference  documentation   for
        !          6608:          GPMDOC.   To  generate this documentation, set the default to
        !          6609:          SYS$LIBRARY: and enter the commands:
        !          6610: 
        !          6611:               $
        !          6612:               _ SPIT GPMDOC -
        !          6613:               $
        !          6614:               __ " {SET OUTPUT,GPMDOC.MAN}{SET INPUT,GPMDOC.GPM}
        !          6615:               $
        !          6616:               _ PRINT/DELETE GPMDOC.MAN
        !          6617:               $
        !          6618:               _ DELETE GPMDOC.LIS;*
        !          6619: 
        !          6620: 
        !          6621:          JUSTIFY (.FOR, .OBJ, .EXE and .OPT) is a LOAD image  used  by
        !          6622:          GPMDOC  that   performs  right-justification of text strings.
        !          6623:          It is not essential to the operation  of  GPMDOC  (though  it
        !          6624:          runs  slightly  faster  with it.)  However, JUSTIFY is a good
        !          6625:          example of use of the LOAD(...) function feature, and  should
        !          6626:          be retained for that reason.
        !          6627: 
        !          6628:      5.  MISCELLANEOUS FILES:
        !          6629:          The  file  [SPITBOL]SPITBOL.COM  and  it's  scratch directory
        !          6630:          [SPITBOL]  are  of  no  use  once  the  delivery   has   been
        !          6631:          successfully   completed,   and  should  be  deleted.    This
        !          6632:          directory also contains RELNOTES.LIS.   These  release  notes
        !          6633:          are  primarily  directed  at sites with an earlier release of
        !          6634:          the system, and may be kept or deleted as desired.
        !          6635: 
        !          6636:          SYS$LIBRARY:DIF.SPT is a file comparator program  similar  to
        !          6637:          the   PDP-11  "CMP"  program.   It  runs significantly faster
        !          6638:          and, in  most  cases,  more  accurately  than  the  V2.4  VMS
        !          6639:          "DIFFERENCES"  command and for that reason may be of value to
        !          6640:          some sites.  The command format for DIF is described  in  its
        !          6641:          source.
        !          6642: 
        !          6643: 
        !          6644: 
        !          6645: 
        !          6646: 
        !          6647: 
        !          6648: 
        !          6649: 
        !          6650: 
        !          6651: 
        !          6652: 
        !          6653: 
        !          6654: 
        !          6655: 
        !          6656: 
        !          6657: 
        !          6658: 
        !          6659: 
        !          6660:     ! ...................................... 16, 17
        !          6661:     $ ...................................... 16, 56, 57, 58
        !          6662:     $SEVERITY .............................. 75
        !          6663:     $STATUS ................................ 75
        !          6664:     % ...................................... 16
        !          6665:     & ...................................... 16
        !          6666: 
        !          6667:     &ABEND ................................. 43
        !          6668:     &ABORT ................................. 43
        !          6669:     &ALPHABET .............................. 43, 58
        !          6670:     &ANCHOR ................................ 4, 43, 57
        !          6671:     &ARB ................................... 43
        !          6672: 
        !          6673:     &BAL ................................... 43
        !          6674:     &CODE .................................. 43, 71
        !          6675:     &DUMP .................................. 43
        !          6676:     &ERRLIMIT .............................. 44
        !          6677:     &ERRTEXT ............................... 5, 21, 25, 38, 44, 71, 88
        !          6678: 
        !          6679:     &ERRTYPE ............................... 38, 44
        !          6680:     &FAIL .................................. 44
        !          6681:     &FENCE ................................. 44
        !          6682:     &FNCLEVEL .............................. 38, 44
        !          6683:     &FTRACE ................................ 44
        !          6684: 
        !          6685:     &FULLSCAN .............................. 3
        !          6686:     &INPUT ................................. 44
        !          6687:     &LASTNO ................................ 44
        !          6688:     &MAXLNGTH .............................. 5, 9, 44, 90
        !          6689:     &OUTPUT ................................ 44
        !          6690: 
        !          6691:     &PROFILE ............................... 5, 44
        !          6692:     &REM ................................... 45
        !          6693:     &RTNTYPE ............................... 45
        !          6694:     &STCOUNT ............................... 45
        !          6695:     &STFCOUNT .............................. 3
        !          6696: 
        !          6697:     &STLIMIT ............................... 6, 42, 45, 71
        !          6698:     &STNO .................................. 45
        !          6699:     &SUCCEED ............................... 45
        !          6700:     &TRACE ................................. 45
        !          6701:     &TRIM .................................. 5, 45, 57, 71
        !          6702: 
        !          6703:     * ...................................... 16, 57
        !          6704:     + ...................................... 16
        !          6705:     - ...................................... 16
        !          6706:     -DOUBLE ................................ 48
        !          6707:     -EJECT ................................. 46
        !          6708: 
        !          6709: 
        !          6710: 
        !          6711: 
        !          6712: 
        !          6713: 
        !          6714:                                      Index - i
        !          6715: 
        !          6716: 
        !          6717: 
        !          6718: 
        !          6719: 
        !          6720:     -EXECUTE ............................... 49
        !          6721:     -FAIL .................................. 49
        !          6722:     -IN .................................... 49
        !          6723:     -LIST .................................. 21, 48
        !          6724:     -NOERRORS .............................. 49, 50
        !          6725:     -NOEXECUTE ............................. 49, 89
        !          6726: 
        !          6727:     -NOFAIL ................................ 25, 49
        !          6728:     -NOLIST ................................ 48
        !          6729:     -NOPRINT ............................... 48
        !          6730:     -PRINT ................................. 48
        !          6731:     -SINGLE ................................ 48
        !          6732: 
        !          6733:     -SPACE ................................. 46
        !          6734:     -TITLE ................................. 46
        !          6735:     . ...................................... 16, 57
        !          6736:     .EXE ................................... 83
        !          6737:     .SEX ................................... 77
        !          6738: 
        !          6739:     .SPT ................................... 87
        !          6740:     / ...................................... 16
        !          6741:     /CCO ................................... 80
        !          6742:     /CIF ................................... 80
        !          6743:     /CR .................................... 80
        !          6744: 
        !          6745:     /CRC ................................... 89
        !          6746:     /CSTATS ................................ 89
        !          6747:     /DLT ................................... 80
        !          6748:     /EOF ................................... 80
        !          6749:     /ESTATS ................................ 89
        !          6750: 
        !          6751:     /EXECUTE ............................... 89
        !          6752:     /FTN ................................... 80
        !          6753:     /LIST .................................. 89
        !          6754:     /LOAD .................................. 71, 77
        !          6755:     /MINC .................................. 77, 90
        !          6756: 
        !          6757:     /MINT .................................. 77, 90
        !          6758:     /MXV ................................... 80
        !          6759:     /NOCRC ................................. 89
        !          6760:     /NOCSTATS .............................. 89
        !          6761:     /NOESTATS .............................. 89
        !          6762: 
        !          6763:     /NOEXECUTE ............................. 89
        !          6764:     /NOLIST ................................ 89
        !          6765:     /NOOUTPUT .............................. 91
        !          6766:     /NOPAGE ................................ 91
        !          6767:     /NOWARN ................................ 75, 91
        !          6768: 
        !          6769: 
        !          6770: 
        !          6771: 
        !          6772: 
        !          6773: 
        !          6774:                                      Index - ii
        !          6775: 
        !          6776: 
        !          6777: 
        !          6778: 
        !          6779: 
        !          6780:     /OUTPUT ................................ 91
        !          6781:     /PAGE .................................. 91
        !          6782:     /PTA ................................... 80
        !          6783:     /RNE ................................... 80
        !          6784:     /RNF ................................... 80
        !          6785:     /SCF ................................... 80
        !          6786: 
        !          6787:     /SPL ................................... 80
        !          6788:     /SUP ................................... 80
        !          6789:     /TEF ................................... 80
        !          6790:     /WARN .................................. 91
        !          6791:     /WIDTH ................................. 92
        !          6792: 
        !          6793:     <> ..................................... 7
        !          6794:     = ...................................... 6, 7, 16
        !          6795:     ? ...................................... 6, 7, 16, 58
        !          6796:     @ ...................................... 16
        !          6797:     ABEND .................................. 43, 43
        !          6798: 
        !          6799:     ABORT .................................. 4, 38, 43
        !          6800:     ALTERNATION ............................ 73
        !          6801:     ALTERNATIVE ............................ 5, 7
        !          6802:     ANCHOR ................................. 43
        !          6803:     ANCHORED MATCHING ...................... 57
        !          6804: 
        !          6805:     ANY .................................... 18, 56, 58
        !          6806:     APPEND ................................. 5, 10, 18, 57
        !          6807:     APPLY .................................. 18
        !          6808:     ARB .................................... 4, 20, 43, 58
        !          6809:     ARBNO .................................. 19, 58
        !          6810: 
        !          6811:     ARG .................................... 19
        !          6812:     ARRAY .................................. 9, 15, 18, 19, 39, 41
        !          6813:     ARRAYS ................................. 19, 56, 57
        !          6814:     ASSOCIATIVE LOOKUP ..................... 57
        !          6815:     BACKSPACE .............................. 3
        !          6816: 
        !          6817:     BAL .................................... 4, 43
        !          6818:     BLOCK .................................. 3
        !          6819:     BREAK .................................. 19, 56, 58
        !          6820:     BREAKX ................................. 5, 20, 56, 58
        !          6821:     BUFFER ................................. 5, 20
        !          6822: 
        !          6823:     BUFFERS ................................ 6, 10, 30, 57, 57, 58, 72
        !          6824:     CHAR ................................... 5, 21
        !          6825:     CHARACTER SET .......................... 6, 73, 87
        !          6826:     CLEAR .................................. 21
        !          6827:     CLI .................................... 88
        !          6828: 
        !          6829: 
        !          6830: 
        !          6831: 
        !          6832: 
        !          6833: 
        !          6834:                                     Index - iii
        !          6835: 
        !          6836: 
        !          6837: 
        !          6838: 
        !          6839: 
        !          6840:     CMP .................................... 99
        !          6841:     CODE ................................... 10, 21, 38, 56
        !          6842:     CODE BLOCKS ............................ 56
        !          6843:     COLLECT ................................ 22, 57
        !          6844:     COMMAND LINE ........................... 87
        !          6845:     CONDITION HANDLERS ..................... 85
        !          6846: 
        !          6847:     CONTINUE ............................... 38
        !          6848:     CONTROL CARDS .......................... 6, 46
        !          6849:     CONVERT ................................ 5, 22, 39
        !          6850:     COPY ................................... 22
        !          6851:     CPU TIME ............................... 93
        !          6852: 
        !          6853:     DATA ................................... 18, 23, 39
        !          6854:     DATATYPE ............................... 4, 23
        !          6855:     DATATYPE CONVERSIONS ................... 4, 11, 12, 58
        !          6856:     DATE ................................... 23, 75
        !          6857:     DCL .................................... 75
        !          6858: 
        !          6859:     DEBUGGING .............................. 42, 58, 83
        !          6860:     DEFERRED EXPRESSION .................... 58, 65
        !          6861:     DEFINE ................................. 18, 23
        !          6862:     DELIVERY ............................... 94
        !          6863:     DETACH ................................. 23, 58
        !          6864: 
        !          6865:     DIF.SPT ................................ 99
        !          6866:     DIFFER ................................. 4, 24
        !          6867:     DUMP ................................... 5, 24
        !          6868:     DUPL ................................... 24
        !          6869:     EBCDIC ................................. 73
        !          6870: 
        !          6871:     EJECT .................................. 5, 24, 79
        !          6872:     END .................................... 4
        !          6873:     ENDFILE ................................ 25, 79
        !          6874:     ERRORS ................................. 50, 75
        !          6875:     EVAL ................................... 25, 38
        !          6876: 
        !          6877:     EXIT ................................... 5, 25, 71, 77
        !          6878:     EXPRESSION ............................. 10
        !          6879:     FAIL ................................... 4, 44
        !          6880:     FENCE .................................. 4, 27, 44, 78
        !          6881:     FIELD .................................. 27
        !          6882: 
        !          6883:     FRETURN ................................ 38
        !          6884:     FULLSCAN ............................... 3
        !          6885:     FUNCTION ............................... 56
        !          6886:     FUNCTIONS .............................. 18
        !          6887:     GARBAGE COLLECTION ..................... 5, 22, 25, 56, 91
        !          6888: 
        !          6889: 
        !          6890: 
        !          6891: 
        !          6892: 
        !          6893: 
        !          6894:                                      Index - iv
        !          6895: 
        !          6896: 
        !          6897: 
        !          6898: 
        !          6899: 
        !          6900:     GE ..................................... 27
        !          6901:     GORILLA ................................ 85
        !          6902:     GOTOS .................................. 6
        !          6903:     GPMDOC ................................. 96, 99
        !          6904:     GT ..................................... 27
        !          6905:     HASH ................................... 56
        !          6906: 
        !          6907:     HASHING ................................ 4, 41, 57
        !          6908:     HELP LIBRARY ........................... 97
        !          6909:     HOST ................................... 5, 27, 78
        !          6910:     I/O .................................... 79
        !          6911:     I/O ASSOCIATION ........................ 58
        !          6912: 
        !          6913:     I/O SWITCHES ........................... 79
        !          6914:     IBM .................................... 1, 73
        !          6915:     IDENT .................................. 4, 28
        !          6916:     IF-THEN-ELSE ........................... 7
        !          6917:     INPUT .................................. 23, 25, 29, 36, 77, 79
        !          6918: 
        !          6919:     INSERT ................................. 5, 10, 30, 57
        !          6920:     INSTALL ................................ 96
        !          6921:     INSTALLATION ........................... 94, 96
        !          6922:     INTEGER ................................ 9, 14, 31, 39
        !          6923:     INTEGERS ............................... 56, 78
        !          6924: 
        !          6925:     INTERROGATION .......................... 58
        !          6926:     ITEM ................................... 7, 31
        !          6927:     JUSTIFY ................................ 99
        !          6928:     KEYWORDS ............................... 43
        !          6929:     LABEL .................................. 56
        !          6930: 
        !          6931:     LE ..................................... 31
        !          6932:     LEN .................................... 32
        !          6933:     LEQ .................................... 5, 32
        !          6934:     LGE .................................... 5, 32
        !          6935:     LGT .................................... 32
        !          6936: 
        !          6937:     LIB$LP_LINES ........................... 91
        !          6938:     LINKER ................................. 82, 82, 87
        !          6939:     LISTING ................................ 46
        !          6940:     LISTING OPTIONS ........................ 82
        !          6941:     LLE .................................... 5, 32
        !          6942: 
        !          6943:     LLT .................................... 5, 33
        !          6944:     LNE .................................... 5, 33
        !          6945:     LOAD ................................... 33, 77, 77, 83, 99
        !          6946:     LOAD MODULE ............................ 25
        !          6947:     LOAD_BASE .............................. 82, 85, 86, 93
        !          6948: 
        !          6949: 
        !          6950: 
        !          6951: 
        !          6952: 
        !          6953: 
        !          6954:                                      Index - v
        !          6955: 
        !          6956: 
        !          6957: 
        !          6958: 
        !          6959: 
        !          6960:     LOCAL .................................. 33
        !          6961:     LONGWORD ............................... 91
        !          6962:     LPAD ................................... 5, 34
        !          6963:     LT ..................................... 34
        !          6964:     MACRO-32 ............................... 83
        !          6965:     MATRIX ................................. 39
        !          6966: 
        !          6967:     MAXIMUM SIZE ........................... 5
        !          6968:     MXLEN .................................. 5, 9, 9, 9, 43, 44, 87, 90
        !          6969:     NAME ................................... 4, 9, 15, 39, 58
        !          6970:     NE ..................................... 34
        !          6971:     NL: .................................... 77
        !          6972: 
        !          6973:     NOTANY ................................. 34, 56, 58
        !          6974:     NRETURN ................................ 38
        !          6975:     NULL STRING ............................ 39
        !          6976:     NUMERIC ................................ 4, 39
        !          6977:     ON-LINE TERMINAL ....................... 6
        !          6978: 
        !          6979:     OPERATORS .............................. 16
        !          6980:     OPSYN .................................. 35, 73
        !          6981:     OPTIONS FILE ........................... 82
        !          6982:     OUTPUT ................................. 23, 24, 25, 29, 35, 36,
        !          6983:                                             77, 79
        !          6984: 
        !          6985:     P0BUFS ................................. 90
        !          6986:     PATTERN ................................ 9
        !          6987:     PATTERN MATCHING OPERATOR .............. 6
        !          6988:     PATTERN REPLACEMENT .................... 57
        !          6989:     PIC .................................... 85, 85, 86
        !          6990: 
        !          6991:     POS .................................... 35
        !          6992:     POSITION INDEPENDENCE .................. 85, 85
        !          6993:     PRE-EVALUATION ......................... 3, 5, 57, 65
        !          6994:     PROGRAM DEFINED DATATYPES .............. 23, 56, 57
        !          6995:     PROTOTYPE .............................. 36
        !          6996: 
        !          6997:     PUNCH .................................. 3
        !          6998:     QUICKSCAN .............................. 3
        !          6999:     REAL ................................... 9, 14, 39
        !          7000:     REAL ARITHMETIC ........................ 3, 87
        !          7001:     REALS .................................. 56
        !          7002: 
        !          7003:     RELEASE NOTES .......................... 99
        !          7004:     RELNOTES.LIS ........................... 99
        !          7005:     REM .................................... 4, 45
        !          7006:     REMDR .................................. 36
        !          7007:     REPLACE ................................ 36, 58
        !          7008: 
        !          7009: 
        !          7010: 
        !          7011: 
        !          7012: 
        !          7013: 
        !          7014:                                      Index - vi
        !          7015: 
        !          7016: 
        !          7017: 
        !          7018: 
        !          7019: 
        !          7020:     RETURN ................................. 38
        !          7021:     REVERSE ................................ 5, 36
        !          7022:     REWIND ................................. 36, 79, 87
        !          7023:     RMS .................................... 79, 90
        !          7024:     RPAD ................................... 5, 37
        !          7025:     RPOS ................................... 37
        !          7026: 
        !          7027:     RSORT .................................. 5, 6, 37, 39, 58
        !          7028:     RTAB ................................... 37
        !          7029:     SELECTION .............................. 5, 7
        !          7030:     SETEXIT ................................ 4, 5, 21, 25, 38, 44, 44
        !          7031:     SHAREABLE IMAGE ........................ 96
        !          7032: 
        !          7033:     SIZE ................................... 39
        !          7034:     SNOBOL4 ................................ 73
        !          7035:     SNOBOL4B ............................... 3
        !          7036:     SORT ................................... 5, 6, 39, 58
        !          7037:     SPACE OVERHEAD ......................... 56
        !          7038: 
        !          7039:     SPAN ................................... 40, 56, 58
        !          7040:     SPEED CONSIDERATIONS ................... 57
        !          7041:     SPIT$FAIL_RETURN ....................... 85
        !          7042:     SPIT$LOAD_ENTRY ........................ 84
        !          7043:     SPIT$SUCCESS_RETURN .................... 85
        !          7044: 
        !          7045:     SPITHLS ................................ 84, 85, 85
        !          7046:     STACK .................................. 91
        !          7047:     STACK OVERFLOW ......................... 93
        !          7048:     STACK_LIMIT ............................ 93
        !          7049:     STITL .................................. 47
        !          7050: 
        !          7051:     STOPTR ................................. 40, 58
        !          7052:     STRING ................................. 9, 12
        !          7053:     SUBSTR ................................. 5, 41
        !          7054:     SUCCEED ................................ 4, 45
        !          7055:     SWITCHES ............................... 87
        !          7056: 
        !          7057:     SYS$HELP ............................... 94
        !          7058:     SYS$INPUT .............................. 87
        !          7059:     SYS$LIBRARY ............................ 82, 84, 85, 85, 94
        !          7060:     SYS$LIBRARY: ........................... 98
        !          7061:     SYS$LP_LINES ........................... 91
        !          7062: 
        !          7063:     SYS$SITENAME ........................... 96
        !          7064:     SYS$SYSTEM ............................. 85, 94
        !          7065:     SYSLOGIN.COM ........................... 96
        !          7066:     SYSTARTUP.COM .......................... 96
        !          7067:     TAB .................................... 41
        !          7068: 
        !          7069: 
        !          7070: 
        !          7071: 
        !          7072: 
        !          7073: 
        !          7074:                                     Index - vii
        !          7075: 
        !          7076: 
        !          7077: 
        !          7078: 
        !          7079: 
        !          7080:     TAB CHARACTER .......................... 6
        !          7081:     TABLE .................................. 4, 4, 9, 15, 39, 39, 41,
        !          7082:                                             56, 57
        !          7083:     TABLES ................................. 56, 57
        !          7084:     TERMINAL ............................... 6, 93
        !          7085:     TERMINAL I/O ........................... 80
        !          7086: 
        !          7087:     TIME ................................... 42, 93
        !          7088:     TRACE .................................. 5, 42
        !          7089:     TRACING ................................ 58
        !          7090:     TRIM ................................... 42
        !          7091:     UNANCHORED MODE ........................ 57
        !          7092: 
        !          7093:     UNIVAC ................................. 1
        !          7094:     UNLOAD ................................. 42
        !          7095:     VALUE .................................. 3
        !          7096:     VARIABLE ............................... 56
        !          7097:     VECTOR ................................. 39
        !          7098: 
        !          7099:     VECTORS ................................ 19, 56
        !          7100:     VMS .................................... 94
        !          7101:     WORD ................................... 91
        !          7102:     [] ..................................... 7
        !          7103:     | ...................................... 17
        !          7104: 
        !          7105:     ~ ...................................... 16, 16
        !          7106: 
        !          7107: 
        !          7108: 
        !          7109: 
        !          7110: 
        !          7111: 
        !          7112: 
        !          7113: 
        !          7114: 
        !          7115: 
        !          7116: 
        !          7117: 
        !          7118: 
        !          7119: 
        !          7120: 
        !          7121: 
        !          7122: 
        !          7123: 
        !          7124: 
        !          7125: 
        !          7126: 
        !          7127: 
        !          7128: 
        !          7129: 
        !          7130: 
        !          7131: 
        !          7132: 
        !          7133: 
        !          7134:                                     Index - viii
        !          7135: 
        !          7136: 
        !          7137:                                  TABLE OF CONTENTS
        !          7138:                                  _____ __ ________
        !          7139: 
        !          7140: 
        !          7141:          Section                        Title
        !          7142:          Page
        !          7143: 
        !          7144: 
        !          7145: 
        !          7146:               Introduction
        !          7147:     1         Introduction                                          1
        !          7148: 
        !          7149:               Summary of Differences
        !          7150:     2         Summary of Differences                                3
        !          7151:     2.1         Features not Implemented                            3
        !          7152:     2.2         Features Implemented Differently                    4
        !          7153:     2.3         Additional Features                                 5
        !          7154:     2.4         Syntax Differences                                  7
        !          7155: 
        !          7156:               Datatypes and Conversion
        !          7157:     3         Datatypes and Conversion                              9
        !          7158:     3.1         Available Datatypes                                 9
        !          7159:     3.2         Possible Datatype Conversions                       11
        !          7160:     3.3         Conversion Details                                  12
        !          7161: 
        !          7162:               Operators
        !          7163:     4         Operators                                             16
        !          7164:     4.1         Unary Operators                                     16
        !          7165:     4.2         Binary Operators                                    17
        !          7166: 
        !          7167:               Functions
        !          7168:     5         Functions                                             18
        !          7169:     5.1         ANY -- Pattern to Match Selected Character          18
        !          7170:     5.2         APPEND * -- Append string to buffer                 18
        !          7171:     5.3         APPLY * -- Apply function                           18
        !          7172:     5.4         ARBNO -- Pattern for Iterated Match                 19
        !          7173:     5.5         ARG * -- Obtain Argument Name                       19
        !          7174:     5.6         ARRAY -- Generate Array Structure                   19
        !          7175:     5.7         BREAK -- Construct Scanning Pattern                 19
        !          7176:     5.8         BUFFER * -- Create buffer object                    20
        !          7177:     5.9         BREAKX * -- Construct Scanning Pattern              20
        !          7178:     5.10        CHAR * -- Convert Character Code to String          21
        !          7179:     5.11        CLEAR * -- Clear Variable Storage                   21
        !          7180:     5.12        CODE * -- Compile Code                              21
        !          7181:     5.13        COLLECT -- Initiate Storage Regeneration            22
        !          7182:     5.14        CONVERT * -- Convert Datatypes                      22
        !          7183:     5.15        COPY * -- Copy Structure                            22
        !          7184:     5.16        DATA -- Create Datatype                             23
        !          7185:     5.17        DATATYPE * -- Obtain Datatype                       23
        !          7186:     5.18        DATE * -- Obtain Date                               23
        !          7187:     5.19        DEFINE -- Define a Function                         23
        !          7188:     5.20        DETACH -- Detach I/O Association                    23
        !          7189:     5.21        DIFFER * -- Test for Arguments Differing            24
        !          7190:     5.22        DUMP * -- Dump Storage                              24
        !          7191:     5.23        DUPL * -- Duplicate String or Pattern               24
        !          7192:     5.24        EJECT * -- Eject to new page                        24
        !          7193:     5.25        ENDFILE * -- Close a File                           25
        !          7194:     5.26        EQ -- Test for Equal                                25
        !          7195:     5.27        EVAL * -- Evaluate Expression                       25
        !          7196:     5.28        EXIT * -- Exit to Save Load Module or to JCL        25
        !          7197:     5.29        FENCE * -- Generate Fenced Pattern                  27
        !          7198: 
        !          7199: 
        !          7200:                                          i
        !          7201: 
        !          7202: 
        !          7203:                              TABLE OF CONTENTS (CON'T)
        !          7204:                              _____ __ ________ _______
        !          7205: 
        !          7206: 
        !          7207:          Section                        Title
        !          7208:          Page
        !          7209: 
        !          7210:     5.30        FIELD * -- Get Field Name                           27
        !          7211:     5.31        GE -- Test for Greater or Equal                     27
        !          7212:     5.32        GT -- Test for Greater                              27
        !          7213:     5.33        HOST * -- Obtain Information about Host Computer    28
        !          7214:     5.34        IDENT * -- Test for Identical                       28
        !          7215:     5.35        INPUT * -- Set Input Association                    29
        !          7216:     5.36        INSERT * -- Insert string in buffer                 30
        !          7217:     5.37        INTEGER * -- Test for Integer                       31
        !          7218:     5.38        ITEM -- Select Array or Table Element               31
        !          7219:     5.39        LE -- Test for Less or Equal                        31
        !          7220:     5.40        LEN -- Generate Specified Length Pattern            32
        !          7221:     5.41        LEQ * -- Test for Lexically Equal                   32
        !          7222:     5.42        LGE * -- Test for Lexically Greater or Equal        32
        !          7223:     5.43        LGT * -- Test for Lexically Greater                 32
        !          7224:     5.44        LLE * -- Test for Lexically Less or Equal           32
        !          7225:     5.45        LLT * -- Test for Lexically Less                    33
        !          7226:     5.46        LNE * -- Test for Lexically Not Equal               33
        !          7227:     5.47        LOAD -- Load External Function                      33
        !          7228:     5.48        LOCAL * -- Get Name of Local                        33
        !          7229:     5.49        LPAD * -- Left Pad                                  34
        !          7230:     5.50        LT -- Test for Less                                 34
        !          7231:     5.51        NE -- Test for Not Equal                            34
        !          7232:     5.52        NOTANY -- Build Character Select Pattern            34
        !          7233:     5.53        OPSYN * -- Equate Functions and Operators           35
        !          7234:     5.54        OUTPUT * -- Set Output Association                  35
        !          7235:     5.55        POS -- Define Positioning Pattern                   35
        !          7236:     5.56        PROTOTYPE -- Retrieve Prototype                     36
        !          7237:     5.57        REMDR -- Remainder                                  36
        !          7238:     5.58        REPLACE -- Translate Characters                     36
        !          7239:     5.59        REVERSE * -- Reverse String                         36
        !          7240:     5.60        REWIND -- Reposition File                           36
        !          7241:     5.61        RPAD * -- Right Pad                                 37
        !          7242:     5.62        RPOS -- Define Positioning Pattern                  37
        !          7243:     5.63        RSORT -- Reverse Sort                               37
        !          7244:     5.64        RTAB -- Create Tabbing Pattern                      37
        !          7245:     5.65        SETEXIT * -- Set Error Exit                         38
        !          7246:     5.66        SIZE -- Get String or Buffer Size                   39
        !          7247:     5.67        SORT * -- Sort                                      39
        !          7248:     5.68        SPAN -- Create Spanning Pattern                     40
        !          7249:     5.69        STOPTR * -- Stop Trace                              40
        !          7250:     5.70        SUBSTR * -- Extract Substring                       41
        !          7251:     5.71        TAB -- Create Tabbing Pattern                       41
        !          7252:     5.72        TABLE * -- Create Table                             41
        !          7253:     5.73        TIME -- Get Timer Value                             42
        !          7254:     5.74        TRACE * -- Initiate Trace                           42
        !          7255:     5.75        TRIM -- Trim Trailing Blanks                        42
        !          7256:     5.76        UNLOAD * -- Unload Function                         42
        !          7257: 
        !          7258:               Keywords
        !          7259:     6         Keywords                                              43
        !          7260: 
        !          7261: 
        !          7262:                                          ii
        !          7263: 
        !          7264: 
        !          7265:                              TABLE OF CONTENTS (CON'T)
        !          7266:                              _____ __ ________ _______
        !          7267: 
        !          7268: 
        !          7269:          Section                        Title
        !          7270:          Page
        !          7271: 
        !          7272: 
        !          7273:               Program Listing and Control Cards
        !          7274:     7         Program Listing and Control Cards                     46
        !          7275:     7.1         Listing Control Cards                               46
        !          7276:     7.1.1         -EJECT                                            46
        !          7277:     7.1.2         -SPACE                                            46
        !          7278:     7.1.3         -TITLE                                            47
        !          7279:     7.1.4         -STITL                                            47
        !          7280:     7.2         Option Control Cards                                48
        !          7281:     7.2.1         -LIST -NOLIST                                     48
        !          7282:     7.2.2         -NOPRINT -PRINT                                   48
        !          7283:     7.2.3         -SINGLE -DOUBLE                                   48
        !          7284:     7.2.4         -INXXX                                            49
        !          7285:     7.2.5         -ERRORS -NOERRORS                                 49
        !          7286:     7.2.6         -FAIL -NOFAIL                                     49
        !          7287:     7.2.7         -EXECUTE -NOEXECUTE                               49
        !          7288: 
        !          7289:               Errors
        !          7290:     8         Errors                                                50
        !          7291:     8.1         Compilation Error Messages                          50
        !          7292:     8.2         Execution Error Messages                            50
        !          7293:     8.3         Error Codes and Messages                            50
        !          7294: 
        !          7295:               Programming Notes
        !          7296:     9         Programming Notes                                     56
        !          7297:     9.1         Space Considerations                                56
        !          7298:     9.2         Speed Considerations                                57
        !          7299:     9.3         Other Notes                                         58
        !          7300: 
        !          7301:               Specimen Programs
        !          7302:     10        Specimen Programs                                     59
        !          7303:     10.1        Program 1                                           59
        !          7304:     10.2        Program 2                                           61
        !          7305:     10.3        Program 3                                           65
        !          7306:     10.4        Program 4                                           68
        !          7307: 
        !          7308:               Implementation Information
        !          7309:     11        Implementation Information                            71
        !          7310:     11.1        &CODE                                               71
        !          7311:     11.2        &ERRTEXT                                            71
        !          7312:     11.3        &STLIMIT                                            71
        !          7313:     11.4        &TRIM                                               72
        !          7314:     11.5        Buffers                                             72
        !          7315:     11.6        Character Set for VAX/VMS SPITBOL                   73
        !          7316:     11.7        Form of DATE String                                 75
        !          7317:     11.8        Errors                                              75
        !          7318:     11.9        EXIT Function Usage                                 77
        !          7319:     11.9.1        EXIT(0) Usage                                     77
        !          7320:     11.9.2        EXIT(String) Usage                                77
        !          7321:     11.9.3        EXIT(-n) Usage                                    77
        !          7322:     11.10       FENCE(PATTERN)                                      78
        !          7323:     11.11       HOST                                                78
        !          7324:     11.12       Range of Integers                                   78
        !          7325:     11.13       INPUT/OUTPUT                                        79
        !          7326: 
        !          7327: 
        !          7328:                                         iii
        !          7329: 
        !          7330: 
        !          7331:                              TABLE OF CONTENTS (CON'T)
        !          7332:                              _____ __ ________ _______
        !          7333: 
        !          7334: 
        !          7335:          Section                        Title
        !          7336:          Page
        !          7337: 
        !          7338:     11.13.1       FILEARG2 SWITCHES                                 80
        !          7339:     11.13.2       I/O EXAMPLES                                      81
        !          7340:     11.14       Linking SPITBOL                                     82
        !          7341:     11.15       Terminal Listing Options                            82
        !          7342:     11.16       LOAD Function Usage                                 83
        !          7343:     11.16.1       High-Level Languages and LOAD                     84
        !          7344:     11.16.2       Calling Conventions for LOAD                      84
        !          7345:     11.16.3       Return Conventions for LOAD                       84
        !          7346:     11.16.4       Linking External Functions                        85
        !          7347:     11.16.5       Unconverted Values and Results for LOAD           86
        !          7348:     11.17       MXLEN                                               87
        !          7349:     11.18       Real Arithmetic                                     87
        !          7350:     11.19       Extended Character Set                              87
        !          7351:     11.20       REWIND                                              87
        !          7352:     11.21       Running SPITBOL                                     87
        !          7353:     11.21.1       Startup Switches                                  89
        !          7354:     11.22       Stack Overflow                                      93
        !          7355:     11.23       TERMINAL                                            93
        !          7356:     11.24       Time                                                93
        !          7357: 
        !          7358:               Installation and Delivery
        !          7359:     12        Installation and Delivery                             94
        !          7360:     12.1        Transferring Delivery Files                         95
        !          7361:     12.2        Installing MACRO SPITBOL                            96
        !          7362:     12.3        Interpreter Checkout and Documentation Generation   96
        !          7363:     12.4        Delivery File Cleanup                               97
        !          7364: 
        !          7365: 
        !          7366: 
        !          7367: 
        !          7368: 
        !          7369: 
        !          7370: 
        !          7371: 
        !          7372: 
        !          7373: 
        !          7374: 
        !          7375: 
        !          7376: 
        !          7377: 
        !          7378: 
        !          7379: 
        !          7380: 
        !          7381: 
        !          7382: 
        !          7383: 
        !          7384: 
        !          7385: 
        !          7386: 
        !          7387: 
        !          7388: 
        !          7389: 
        !          7390:                                          iv
        !          7391: 
        !          7392: 
        !          7393: 
        !          7394: 
        !          7395: 
        !          7396: 
        !          7397: 
        !          7398: 
        !          7399: 
        !          7400: 

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.