SPITBOL(1)

NAME
spitbol - SPITBOL Compiler

SYNOPSIS
spitbol [ options ] ifile ...

DESCRIPTION
Spitbol is an implementation of Macro SPITBOL, which is an upward compatible version of the SNOBOL4 programming language. (Version 3 of SNOBOL4 is the reference version for comparison.) Most SNOBOL4 programs which operate correctly using SNOBOL4 should operate correctly when compiled and executed using spitbol.

All names used in a program are normally mapped to UPPER CASE during compilation and execution. For strict compatibility with SNOBOL4, use the -f option or -CASE control statement.

All ifiles are read in order before the standard input. Standard output comes only from assignments to OUTPUT and from error messages. Program listings and statistics are generated only when requested by options.

Compiler Options:

-f  don't fold lower case names to UPPER CASE

-e  don't send error messages to the terminal

-l  generate source listing

-c  generate compilation statistics

-x  generate execution statistics

-a  like -lcx

-p  long listing format; generates form feeds

-z  use standard listing format

-h  write spitbol header to standard output

-n  suppress execution (like -NOEXEC control card)

-mdd
    max size (words) of created object [default -m8192 ]

-sdd
    maximum size (words) of stack space [default -s2048 ]

-idd
    size (words) of increment by which dynamic area is increased [default -i4096 ]

-ddd
    size (words) of maximum allocated dynamic area [default -d256K ]

-u string
    executing program may retrieve string with HOST(0)

-o ofile
    write listing, statistics and dump to ofile and OUTPUT to standard output

Note: dd can be followed by a k to indicate units of 1024.

Input/Output

Spitbol's interface to the UNIX system handles two modes of i/o transfers:

    line mode where records are delimited by new-line characters. The interface strips them on input and appends them on output.

    raw mode where a predetermined number of bytes are transferred.

The particular mode to be used is specified by the programmer in the INPUT or OUTPUT function call and is processed by the interface. The maximum length of an input record is set by the -l or -r argument. The size of an output record is the length of the string written, plus one for a new line character if in line mode.

The form of the INPUT/OUTPUT function call is

    INPUT/OUTPUT(.name,channel,file_name args)

name is the variable name to be input/output associated.

channel is an integer or string that identifies the i/o association. The channel id can be used in subsequent calls to EJECT, ENDFILE, INPUT, OUTPUT, REWIND, and SET. If the channel is omitted or the null string, the association is deemed to be made to the system's standard input or output stream.

file_name args specifies the source/destination of the input/output and any i/o processing arguments. The file_name can be either a path name to a file or a command string. Command strings are distinguished from file names by a leading "!". The character following the "!" is the delimiter used to separate the command string from any i/o processing arguments. The ending delimiter may be omitted if there are no i/o processing arguments. There must always be at least one space between the file_name and args, even if the file_name is null.

In the following examples the string used in the INPUT/OUTPUT call is on the left side of the equal sign and the command string executed on the right side.

"!*who" = who "!*who* -c" = who "!$ls -l$ -c" = ls -l

input/output arguments:

-a  Append output to existing file. If file doesn't exist then it is created. If -a is not specified then file is created.

-bdd
    Set internal buffer size to dd characters. This value is the byte count used on all input/output transfers except for the last write to an output file. [default -b1024 ]

-c  Like -r1

-fdd
    Use dd as file desciptor for i/o. spitbol assumes that dd has been opened by the shell. File names and -fdd arguments are mutually exclusive. File descriptors 0, 1, and 2 may be accessed in this manner.

-ldd
    Line mode: maximum input record length is dd characters; output record length is length of string plus one (for new line). [default -l1024 ]

-rdd
    Raw mode: input record length is dd characters; output record length is length of string assigned to name.

-w  On output, each record is directly written to the file without any intermediate buffering. The interface automatically sets this option for terminal output. Any buffer length specifications are ignored. On input, each request results in the interface issuing a single read(2) system call. The result is exactly the data returned by read, except that if read returns 0, the input request fails. The maximum length requested can be set by the -r option; -l is incompatible with -w on input.

More than one type of transfer may be associated with a channel. This is accomplished by calling INPUT/OUTPUT after the initial call with the name, channel, and file arguments. The file name or -f argument must not be specified on calls subsequent to the first!

A new standard function, SET, is available and allows executing programs to set the file pointer for input and output files. SET used in conjunction with assignments to output associated variables will correctly overwrite parts of files. SET is called with three arguments as follows

    SET(channel,integer,integer)

The arguments are the same as those to the lseek(2) system call, except that the first argument identifies a spitbol channel instead of a file descriptor.

EXIT support

The EXIT function terminates execution with certain side effects:

EXIT(command-string)
    causes the value of command-string to be handed to the Shell to be executed after spitbol terminates.

EXIT(n)
    If n is greater than 0, a load module will be written in a.out before termination. Executing this load module will restore the state of the spitbol system to what it was when EXIT was called, except that any files other than the standard input, output, and error will have been closed. To the SNOBOL4 program, it will appear as if EXIT had returned a null string. If n is exactly 1, the generated load module will identify the version of spitbol that created it in a message when it begins execution. If n is greater than 1, it will resume quietly. See the reference manual for further details.

The HOST function

HOST()
    returns the host string read from /usr/lib/spithost.

HOST(0)
    returns the string specified with the -u option on the command line. If -u was not specified the null string is returned.

HOST(1,"command string")
    executes the command string and continues.

HOST(2,n)
    returns argument number n from the command line. It fails if n is out of range or not an integer. This is useful for writing spitbol programs that behave like system commands.

HOST(3)
    returns the index of the first command line argument that was not examined by spitbol. This allows the user program to interpret additional command line arguments.

HOST(4,"var")
    returns the value of the environment variable var. If the value is too long for an internal buffer (presently 512 bytes) it is quietly truncated.

MISCELLANY

A file is not actually opened until the first attempt to read or write it. Thus if a variable is associated to an output file, and no value is ever assigned to that variable, the file will not be created, and, if it already existed, its old contents will remain unchanged. If you want an output file to be created even though it might be empty, REWIND it immediately after forming the output association.

Folding of names to UPPER CASE can be controlled during compilation by the -CASE control statement and during execution by the &CASE keyword. A value of 0 prevents folding to UPPER CASE and a value of 1 forces folding to UPPER CASE.

Integers are represented by 32-bit quantities and thus restricted in range from -2147483648 to 2147483647. Real numbers are implemented in single precision.

Setting &STLIMIT = -1 inhibits statement limit checking and provides a way to execute arbitrarily many statements.

The name TERMINAL is available with default associations for input and output to the terminal.

If the first line of the first input file begins with #! then that line is ignored. This meshes well with the way that exec(2) treats files beginning with #!.

Setting &PROFILE = 1 causes spitbol to accumulate profile information during program execution and print this information after the program terminates.

FILES
/usr/lib/vaxspitv35.err - Error text.
/usr/lib/spithost - Host computer and operating system identifier.

SEE ALSO
Macro SPITBOL Program Reference Manual by R. B. K. Dewar, A. P. McCann, R. E. Goldberg, and Steven G. Duff

The SNOBOL4 Programming Language, Second Edition by R. E. Griswold, J. F. Poage and I. P. Polonsky