SOFTEK

Masters of the Game


'IS' INTEGER COMPILER & 'FP' FULL COMPILER
==========================================


(C) 1983
M. Lewis
Softek International Ltd
LONDON, ENGLAND


(Typed in by Nele Abels-Ludwig. Keep Spectrum software
usable, transcribe technical manuals!)


Introduction
------------

WHAT IS A COMPILER?

A compiler translates a program written in BASIC into an equivalent
program in machine code. Machine code is in a sense, your Spectrum's
'Mother Tongue', it in fact always works in this language: the BASIC you
may be used to writing is understood by your Spectrum because its 'ROM'
(Read Only Memory) contains a so-called 'BASIC interpreter' itself
written in machine code. Because the heart of your Spectrum, its 'CPU'
(Central Processing Unit) does not understand the 'BASIC' language. Your
Spectrum spends a fair amount of time whilst running your program
'interpreting' it for the CPU.

The Softek Compiler, by contrast, converts your BASIC so that it is in
Machine Code and because of this your Compiled programs will run
typicall ten times faster than BASIC (less for the 'FP' version), but up
to 200 times faster is possible with the 'IS' Integer Compiler.

Both Softek Compilers allow you to choose where the compiled code will
sit in the memory, and this final Machine Code version of your proram
can easily be saved on tape as CODE. The beauty of Softek Compilers is
that after compilation your BASIC is still present so that should
ammendments be required there is no need to load again from
tape/microdrive. Furthermore, you can compile subroutines.

LOADING THE COMPILER

Simply type LOAD"" and press the <ENTER> key. Set the tape running
(being sure to connect the tape leads correctly in the rear of your
spectrum). The programs all load in two parts, a BASIC loader and the
compiler itself. When loaded you will be asked if the RAMTOP setting is
okay (40000 for 48K versions and 26000 for 16K versions). If it is, just
press 'y' and <ENTER> else press 'n' and <ENTER> and respond with the
RAMTOP you require. Note that RAMTOP is the location where your compiled
program will start.

Each of the compilers has a 16K and 48K version on the tape. Either
version could be used on a 48K Spectrum, but naturally only the 16K
version will run in 16K.

Once loaded and RAMTOP is set, each program will tell you that you may
'NEW' the BASIC loader. This done your compiler is still in memory
(protected above RAMTOP) and you may begin programming or load your
BASIC to be compiled.

USING YOUR COMPILER

Using your compiler could hardly be easier. Key in your BASIC as usual
or load it in from a tape or microdrive. The 'FP' compiler will
understand virtually every BASIC command and function, but if you are
using the 'IS' then do refer to the follow notes to check its
limitations.

When your BASIC is ready to be compiled simply enter: RANDOMIZE USR
59300 (for 48K or 26600 for 16K)

Having done this you enter the compiler and it begins its work. Various
messages will appear as the compiler passes twice through your BASIC
turning it into machine code. Here are the messages and their meanings:

1. "START ADDRESS"
This shows the start address of the machine code being compiled (this is
always one byte above RAMTOP)

2. "END ADDRESS"
This is updated during the compilation and shows the end address of the
code as it is built up.

3. "VARIABLES END"
This message appears when your program contains STRINGS or ARRAYS. These
are stored immediately after your machine code program and when
compilation is complete the last address of the array is shown.

4. "FIRST PASS", "SECOND PASS"
To make a complete compilation your Softek compiler must make two passes
through your BASIC. These messages tell you which pass of your program
is compiling.

5. "ERRORS"/"NO ERRORS"
If at the end of compilation the "NO ERRORS" message appears then you
have a successful Machine Code program. However, if "ERROR" appears then
the compilation will halt and display the line of BASIC and the part of
that line which the compiler cannot understand. You will see the
question mark (?) placed just after the error and the compiler will have
changed the 'current line' cursor to this line number. Hence, pressing
'EDIT' will call down this offending BASIC line (press CAPS SHIFT + 1 to
edit).

RUNNING COMPILED PROGRAMS
Make a note at the end of compilation of the START ADDRESS of the code
and then, from BASIC, simply tpe in: RANDOMIZE USR (START ADDRESS).

WHERE IS THE MACHINE CODE PUT?
As mentioned above, your machine code is put in RAM starting one byte
above the RAMTOP which you are set. You can reset RAMTOP anytime by
entering: CLEAR N, where 'N' is one less than the start address you
choose. It is thus quite possible to compile subroutines or build up a
programm in parts, by carefully setting and resetting RAMTOP (you will
have to take careful note of the values of "END ADDRESS" or "VARIABLES
END" to ensure the parts do not overlap).

WHAT HAPPENS TO THE BASIC?
Your BASIC remains in memory after compilation. However, if the machine
code works as planned then it can be saved as CODE (see below) or the
BASIC 'NEWED' to allow more BASIC to be compiled.

MEMORY USAGE
MEMORY can be exhausted in several ways.
1. During compilation a table of LINE numbers is built up and "OUT OF
MEMORY" will occur if too many lines are used.
2. If either the machine code or the VARIABLES threaten to overwrite the
compiler then "OUT OF MEMORY" will also occur.

VARIABLES, STRINGS, ARRAYS & NUMBERS
Variables are handled as in BASIC, allowing full names to be used in
either upper or lower case. Only the 'FP' compiler will handle arrays,
but you must ensure that these are not multi-dimensional.

The 'FP' compiler will handle all 'real' (floating point) numbers as n
BASIC. The 'IS' compiler treats all numbers as integers (no decimal
points), in the range -32767 to 32767. Certain functions will take a
number stored as 0 to 65536 (e.g. PEEK, POKE, USR).

COMMANDS THE COMPILERS HANDLE:

KEY:
e                       represents an expression
s                       a sequence of statements separated by colons
n                       a positive integer number
c                       a sequence of colour items separated by ','
                        or ';' or '"'
x,y                     a set of expressions
$                       a string expression

BEEP x,y
BORDER e                as normal
BRIGHT e                as normal
CIRCLE c;x,y,z          as normal
CLEAR                   'FP' version only
CLS                     as normal
CLOSE#n,$               'FP' version only
COPY                    as normal
DATA                    on both versions no expressions can be put into
                        DATA statements. Only numbers, or strings in
                        the form "..." can be used, and these forms can
                        be mixed.
DIM A(n) or A$(n)       'FP' version only
DRAW c;x,y              as normal
DRAW c;x,y,z            as normal
FLASH e                 as normal
FOR a=x TO y            as normal
STEP z                  as normal
GOSUB n                 as normal
GOTO n                  as normal
IF e THEN s             Exactly as BASIC (full Boolean)
INK e
INPUT                   Exactly as BASIC except for LINE.
                        BASIC's line editor is used allowing
                        full cursor control and PRINT statements
                        may be included. Variables may be printed
                        if they are enclosed in brackets.
INVERSE e
LET a=e
LOAD $ CODE n           only one parameter
LPRINT                  the '#' may also be used
NEW
OPEN#n,$                only 'FP' version
OUT x,y
OVER e
PAPER e
PAUSE e
plot c;x,y
POKE x,y
PRINT                   the '#' may also be used
RANDOMIZE
RANDOMIZE e
READ
REM                     see later
RESTORE
RESTORE n               as in BASIC
RETURN
SAVE $ CODE e,e
STOP
VERIFY $ CODE e         e is optional

REM STATEMENTS
REM statements are used in Softek compilers to offer commands and
facilities not obtainable in Spectrum BASIC. In each ase REM is followed
by a single capital letter, but if this letter is not one of the 'Key
Letters' below then the line is treated as a normal REM statement.

INTEGER 'IS' VERSION

REM B                   checks to see if the Break key is pressed
REM M,n,n,n,n...        enters code into the program and allows a
                        machine code routine to be called at this point
                        in the program
REM S,a,x,y             PRINTs a character (ASCII code 'a') onto the
                        screen at PLOT position x,y. This is very useful
                        for games requirint high resolution smooth
                        movement.

FULL 'FP' VERSION

REM B                   checks for BREAK key
REM M,n,n,n,n...        as in the 'IS' version
REM E,n                 sets an error trap to line 'n'. Thus whenever an
                        error occurs a jump to line 'n' is made. If a
                        program uses this facility the STACK will be
                        corrupted when an error occurs. Thus if a later
                        return to BASIC is made it should only be done
                        by jumping beyond the program or by using a
                        STOP statement.
REM N                   restores error trapping to the normal mode. This
                        must be done before returning to BASIC.
REM O,a,n,n...          this simulates the BASIC function: ON n GOTO
                        n,n,n,... 'a' must be a single variable only and
                        if it is greater than the number of lines
                        present the program continues past the
                        statement


STRINGS AND STRING HANDLING
Strings are totally flexible and may be any length (not only up to 256
characters as in BASIC). Strings are stored after the normal variables,
which are in turn stored immediately after the compiled code.

String arrays are possible on the 'FP' version only and must be singly
dimension. When a string is dimensioned it is filled with spaces as in
BASIC.

Both types of string slicing are possible, e.g.
LET A$(3 TO 7)="HH" or LET A$="any abcde" (3 TO 5) or a mixture of the
two.

Numbers may be missed out as in BASIC, e.g. A$(3 TO)
And all the following as possible:

LEN STR$ CODE CHR$ CODE INKEY$ SCREEN$ "+" (for concatenation)

NOTE
In both compilers printing in PRINT statements is not evaluated. Thus if
you wish to include something like "abcded" (3 TO 6) or "y"="h", etc.,
then you must enclose the expression in brackets to force the compiler
to call the evaluator before PRINTing.
Note also that neither VAL nor VALS are usable as these can only be
handled by BASIC in real time.

INTEGER COMPILER: FUNCTIONS etc.

FUNCTIONS:
ABS AND ATTR CHR$ CODE IN INKEY$ LEN NOT OR PEEK POINT RND(a number
between 0 and 32767) SCREEN$ SGN STR$ USRn USR$
+/*- and all comparison operators.

BEEP
You may make a Beep of lesss than one second including division e.g.
BEEP 1/expression,n
Where the 'expression' can be any number or any expression. The
expression is calculated in integer form and then floating-point
calculator is called to do the final division.

CLEAR just clears the simple and control variables and deletes string
variables too.

FULL COMPILER: FUNCTIONS etc.
The Full 'FP' compiler will handle all the functions possible with the
'IS' compiler. In addition it will handle all floating point functions
too, such as SIN, COS, ATN etc.

CLEAR can also be used for its other function of adjusting RAMTOP in
this 'FP' version only.

The CLEAR command will clear all arrays and will also change the complex
stack. Thus a STOP statement must be used to RETURN to BASIC after a
CLEAR or the program will crash.

In general, you should not RETURN to BASIC from a compiled 'FP' program
except at the very end of a program or by using the STOP  statement.

GENERAL DIFFERENCES BETWEEN THE COMPILERS
The Full 'FP' compiler and 'IS' integer one both take up a similar
amount of RAM (about 6K). The 'FP' ckearly is more able to compile the
full range of Spectrum BASIC and is thus most suitable for scientific or
technical uses. However the numbers in 'FP' compiled code are treated as
floating point ones (5 bytes each) whereas they are all inteers in the
'IS' version (2 bytes each). For this reason the code produced by the
'FP' compiler will tend to be slower than that of the 'IS' compiler,
whereas code using the 'IS' compiler is typically 10 times faster than
BASIC (with up to perhaps 500 times faster being possible), the 'FP's
code will offer more typically a speed increase in the region of 2 to 10
times faster.

THE COMPILERS IN USE/MEMORY MAP
Compiled code will always be positioned in RAM to run from one byte
above RAMTOP. Hence you may choose where in RAM your code is placed by
using 'CLEAR n' to alter RAMTOP (se compiler's loaders). The compiler
must be in memory when the code is called to run the machine code
programm because the compiled code uses 'run-time routines' in the
compiler.

After the compiled code is a 130 byte block which stores all particulars
about the 26 strings allowed. Then there is normally free space unless
this is filled with strings when the M/C program creates them.

----------------------------------------------------------------...
prog : arrays :: line address's : spare :: MCode : Vars : $data
----------------------------------------------------------------...
     VARS    STKEND                    RAMTOP

...---------------------------------------------+
   130 bytes : $'s : spare : vars ads : Compiler:
...---------------------------------------------+

The 'FP' compiler stores all arrays in the BASIC interpreter's variable
area. This is done so that the values can easily be transferred from
BASI to the machine code and vice versa. A custom search routine is used
so that the time taken to look for this variable is extremely small.

When compiling the compiler builds up a table of addresses of the lines
of the program being produced. This is stored just above STKEND, in the
spare area of memory. Also the compiler builds up a table of addresses
of the various variables used by the program. This table "grows" down in
memory from the start of the compiler. The compiler allows just enough
space for the variable being used, i.e. if only a simple variable 2 (or
5 for the FP version) bytes are reserved for that variable. But if that
variable is ever used in a FOR-NEXT loop then 8 (or 17 for FP) bytes are
reserved for it.
Variables can be any length and any number of variables can be used (if
you have enough memory of course)

SAVING THE COMPILED CODE
For the compiler to produce efficient (fast) machine code there must be
a set of RUN-TIME routines which are called from the code. The machine
code cannot function without these routines and so must be saved along
with the code.

Your programs can be SAVED as follows:

For 48K versions: SAVE "name" CODE start address, 65536 - start address
For 16K versions: SAVE "name" CODE start address, 32767 - start address

EXAMPLES

10 FOR A=0 TO 100: OUT 254,53: FOR B=0 TO A:NEXT B: OUT 254,0:
   FOR B=A TO 0 STEP -1: NEXT B: NEXT A
20 REM B
30 GOTO 10


10 FOR A=1 TO 128
20 LET B=(255-A)
30 REM S,87,A,A
40 REM S,88,B,A
50 REM B
60 BEEP 1/50,1
70 NEXT A



