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