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