![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to spitbol.1 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 spitbol.1 CVS log | Up to [Research Unix] / researchv10no / cmd / spitbol |
1.1 root 1: .TH SPITBOL 1
2: .SH NAME
3: spitbol \- SPITBOL Compiler
4: .SH SYNOPSIS
5: .B spitbol
6: [ options ]
7: .I "ifile ..."
8: .SH DESCRIPTION
9: .I Spitbol
10: is an implementation of Macro SPITBOL, which is an upward compatible
11: version of the SNOBOL4 programming language.
12: (Version 3 of SNOBOL4 is the reference version for comparison.)
13: Most SNOBOL4 programs
14: which operate correctly using SNOBOL4 should operate correctly
15: when compiled and executed using
16: .I spitbol.
17: .P
18: All names used in a program are normally mapped to UPPER CASE during
19: compilation and execution.
20: For strict compatibility with SNOBOL4, use the \-f
21: option or \-CASE control statement.
22: .P
23: All
24: .IR ifile s
25: are read in order before the standard input.
26: Standard output comes only from assignments to OUTPUT and from
27: error messages.
28: Program listings and statistics are generated
29: only when requested by options.
30: .P
31: Compiler Options:
32: .P
33: .TP
34: .B \-f
35: don't fold lower case names to UPPER CASE
36: .TP
37: .B \-e
38: don't send error messages to the terminal
39: .TP
40: .B \-l
41: generate source listing
42: .TP
43: .B \-c
44: generate compilation statistics
45: .TP
46: .B \-x
47: generate execution statistics
48: .TP
49: .B \-a
50: like
51: .B "\-lcx"
52: .TP
53: .B \-p
54: long listing format; generates form feeds
55: .TP
56: .B \-z
57: use standard listing format
58: .TP
59: .B \-h
60: write
61: .I spitbol
62: header to standard output
63: .TP
64: .B \-n
65: suppress execution (like \-NOEXEC control card)
66: .TP
67: .BI \-m dd
68: max size (words) of created object
69: [default
70: .BI \-m 8192
71: ]
72: .TP
73: .BI \-s dd
74: maximum size (words) of stack space
75: [default
76: .BI \-s 2048
77: ]
78: .TP
79: .BI \-i dd
80: size (words) of increment by which dynamic area is increased
81: [default
82: .BI \-i 4096
83: ]
84: .TP
85: .BI \-d dd
86: size (words) of maximum allocated dynamic area
87: [default
88: .BI \-d 256K
89: ]
90: .TP
91: .BI \-u " string"
92: executing program may retrieve string with HOST(0)
93: .TP
94: .BI \-o " ofile"
95: write listing, statistics and dump to
96: .I ofile
97: and OUTPUT to standard output
98: .P
99: Note:
100: .I dd
101: can be followed by a
102: .B k
103: to indicate units of 1024.
104: .P
105: .B "Input/Output"
106: .P
107: .IR Spitbol 's
108: interface to the UNIX system handles two modes of i/o transfers:
109: .P
110: .RS 5
111: .I "line mode"
112: where records are delimited by new-line characters.
113: The interface strips them on input and
114: appends them on output.
115: .P
116: .I "raw mode"
117: where a predetermined number of bytes
118: are transferred.
119: .P
120: .RE
121: The particular mode to be used is specified by the programmer
122: in the INPUT or OUTPUT function call and is processed by the
123: interface.
124: The maximum length of an input record is set by the
125: .B \-l
126: or
127: .B \-r
128: argument.
129: The size of an output record is the length of the string written,
130: plus one for a new line character if in line mode.
131: .P
132: The form of the INPUT/OUTPUT function call is
133: .P
134: .RS 10
135: INPUT/OUTPUT(.name,channel,file_name args)
136: .RE
137: .P
138: .I name
139: is the variable name to be input/output associated.
140: .P
141: .I "channel"
142: is an integer or string that identifies the i/o association.
143: The channel id can be used in subsequent calls to EJECT, ENDFILE,
144: INPUT, OUTPUT, REWIND, and SET.
145: If the
146: .I channel
147: is omitted or the null string, the association is deemed
148: to be made to the system's standard input or output stream.
149: .P
150: .I "file_name args"
151: specifies the source/destination of the
152: input/output and any i/o processing arguments. The
153: .I file_name
154: can be either a path name to a file or a
155: command string. Command strings are distinguished from
156: file names by a leading "!". The character following the
157: "!" is the delimiter used to separate the command string
158: from any i/o processing arguments. The ending delimiter
159: may be omitted if there are no i/o processing arguments.
160: There must always be at least one space between the
161: .I file_name
162: and
163: .I args,
164: even if the
165: .I file_name
166: is null.
167: .P
168: In the following examples the string used in the INPUT/OUTPUT
169: call is on the left side of the equal sign and the command
170: string executed on the right side.
171: .P
172: "!*who" = who "!*who* \-c" = who "!$ls \-l$ \-c" = ls \-l
173: .P
174: input/output arguments:
175: .TP
176: .B \-a
177: Append output to existing file. If file doesn't exist
178: then it is created.
179: If
180: .B \-a
181: is not specified then file
182: is created.
183: .TP
184: .BI \-b dd
185: Set internal buffer size to
186: .I dd
187: characters. This value
188: is the byte count used on all input/output transfers
189: except for the last write to an output file. [default
190: .BI \-b 1024
191: ]
192: .TP
193: .B \-c
194: Like
195: .BI \-r 1
196: .TP
197: .BI \-f dd
198: Use
199: .I dd
200: as file desciptor for i/o.
201: .I spitbol
202: assumes that
203: .I dd
204: has been opened by the shell. File names and
205: .BI \-f dd
206: arguments are mutually exclusive.
207: File descriptors
208: 0, 1, and 2
209: may
210: be accessed in this manner.
211: .TP
212: .BI \-l dd
213: Line mode: maximum input record length is
214: .I dd
215: characters;
216: output record length is length of string
217: plus one (for new line). [default
218: .BI \-l 1024
219: ]
220: .TP
221: .BI \-r dd
222: Raw mode: input record length is
223: .I dd
224: characters; output
225: record length is length of string assigned to name.
226: .TP
227: .B \-w
228: On output, each record is directly written to the
229: file without any intermediate buffering.
230: The interface automatically sets this option
231: for terminal output.
232: Any buffer length specifications are ignored.
233: On input, each request results in the interface issuing
234: a single
235: .IR read (2)
236: system call.
237: The result is exactly the data returned by
238: .IR read ,
239: except that if
240: .IR read
241: returns 0, the input request fails.
242: The maximum length requested can be set by the
243: .B \-r
244: option;
245: .B \-l
246: is incompatible with
247: .B \-w
248: on input.
249: .P
250: More than one type of transfer may be associated with a channel.
251: This is accomplished by calling INPUT/OUTPUT after the initial
252: call with the name, channel, and file arguments. The
253: file name or
254: .B \-f
255: argument must not be specified on calls subsequent
256: to the first!
257: .P
258: A new standard function, SET, is available and allows executing programs to
259: set the file pointer for input and output files. SET used in conjunction
260: with assignments to output associated variables will correctly overwrite
261: parts of files.
262: SET is called with three arguments as follows
263: .P
264: .RS 10
265: SET(channel,integer,integer)
266: .RE
267: .P
268: The arguments are the same as those to the
269: .IR lseek (2)
270: system call, except that
271: the first argument identifies a spitbol channel instead of
272: a file descriptor.
273: .P
274: .B "EXIT support"
275: .P
276: The EXIT function terminates execution with certain side effects:
277: .P
278: .TP 10
279: EXIT(\fIcommand-string\fP)
280: causes the value of
281: .I command-string
282: to be handed to the Shell to be executed after
283: .I spitbol
284: terminates.
285: .TP 10
286: EXIT(\fIn\fP)
287: If
288: .I n
289: is greater than 0, a load module will be written in
290: .I a.out
291: before termination.
292: Executing this load module will restore the state of the
293: .I spitbol
294: system to what it was when EXIT was called, except that
295: any files other than the standard input, output, and error
296: will have been closed.
297: To the SNOBOL4 program, it will appear as if
298: EXIT had returned a null string.
299: If
300: .I n
301: is exactly 1,
302: the generated load module will identify
303: the version of
304: .I spitbol
305: that created it in a message when it
306: begins execution.
307: If
308: .I n
309: is greater than 1,
310: it will resume quietly.
311: See the reference manual for further details.
312: .P
313: .B "The HOST function"
314: .TP
315: HOST()
316: returns the host string read from /usr/lib/spithost.
317: .P
318: .TP
319: HOST(0)
320: returns the string specified with the
321: .B \-u
322: option
323: on the command line.
324: If
325: .B \-u
326: was not specified the
327: null string is returned.
328: .TP
329: HOST(1,"command string")
330: executes the command string
331: and continues.
332: .TP
333: HOST(2,\fIn\fP)
334: returns argument number
335: .I n
336: from the command line.
337: It fails if
338: .I n
339: is out of range or not an integer.
340: This is useful for writing
341: .I spitbol
342: programs that behave like system commands.
343: .TP
344: HOST(3)
345: returns the index of the first command line argument
346: that was not examined by
347: .IR spitbol .
348: This allows the user program to interpret additional
349: command line arguments.
350: .TP
351: HOST(4,"var")
352: returns the value of the environment variable
353: .IR var .
354: If the value is too long for an internal buffer
355: (presently 512 bytes) it is quietly truncated.
356: .SH "MISCELLANY"
357: .P
358: A file is not actually opened until the first attempt
359: to read or write it.
360: Thus if a variable is associated to an output file,
361: and no value is ever assigned to that variable, the file
362: will not be created, and, if it already existed, its old
363: contents will remain unchanged.
364: If you want an output file to be created even though it
365: might be empty, REWIND it immediately after forming the
366: output association.
367: .P
368: Folding of names to UPPER CASE can be controlled during compilation
369: by the \-CASE control statement and during execution by the &CASE keyword.
370: A value of 0 prevents folding to UPPER CASE and a value of 1
371: forces folding to UPPER CASE.
372: .P
373: Integers are represented by 32-bit quantities and thus restricted in range
374: from \-2147483648 to 2147483647.
375: Real numbers are implemented in single precision.
376: .P
377: Setting &STLIMIT = \-1 inhibits statement limit checking and provides
378: a way to execute arbitrarily many statements.
379: .P
380: The name TERMINAL is available with default associations for input and
381: output to the terminal.
382: .P
383: If the first line of the first input file begins with
384: .B #!
385: then that line is ignored.
386: This meshes well with the way that
387: .IR exec (2)
388: treats files beginning with
389: .BR #! .
390: .P
391: Setting &PROFILE = 1 causes
392: .I spitbol
393: to accumulate profile information during program execution
394: and print this information after the program terminates.
395: .SH "FILES"
396: /usr/lib/vaxspitv35.err \- Error text.
397: .br
398: /usr/lib/spithost \- Host computer and operating system identifier.
399: .SH "SEE ALSO"
400: .I "Macro SPITBOL Program Reference Manual"
401: by R. B. K. Dewar, A. P. McCann, R. E. Goldberg, and Steven G. Duff
402: .P
403: .I "The SNOBOL4 Programming Language, Second Edition"
404: by R. E. Griswold, J. F. Poage and I. P. Polonsky
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.