=========================================
   KCC2 - Kamasoft C Compiler 2
   editor, compiler and libraries
   manual - esxDOS version
=========================================

CONTENTS
--------

 1. ABOUT KCC2
 2. OVERVIEW
 3. NEW IN VERSION 2
 4. FIRST PROGRAM (TUTORIAL)
 5. EDITOR
 6. FILES AND I/O
 7. COMPILE / GENERATE
 8. WORKING WITH FUNCTIONS
 9. C' LANGUAGE REFERENCE
     - PROGRAM SHAPE
     - DATA TYPES
     - ARRAYS (ONE-DIMENSIONAL ONLY)
     - VARIABLES AND SCOPE
     - CONSTANTS, STRINGS, COMMENTS
     - OPERATORS BY PRECEDENCE
     - UNARY (PREFIX) OPERATORS
     - ADDRESSES AND MEMORY (& AND *)
     - STATEMENTS
     - SWITCH, CASE, DEFAULT
     - INLINE - DIRECT MACHINE CODE
     - FUNCTIONS
     - USING LIBRARIES
10. C' VS STANDARD C
     - SYNTAX COMPARISON (EXAMPLES)
11. COMPILER LIMITS
12. .KCLIB - BUILDING LIBRARIES
13. KCL FILE FORMAT
     - PARAMETER PASSING
     - VALUE SIZES
     - RETURN VALUE
     - VARIABLE ARGUMENT COUNT
     - READING PARAMETERS - EXAMPLES
     - EXAMPLE FNS: PEEK, DPEEK, POKE
14. RELOCATABILITY OF COMPILED CODE
15. MEMORY MAP
16. ERROR MESSAGES

ABOUT KCC2
----------

KCC2 (Kamasoft C Compiler 2) is version 2
of the KAMASOFT C' compiler, originally
from 1990. This new version is based on a
reconstruction of the original assembler
sources (written for Laser Genius),
carried out in the Lnx assembler by a
person named l00k. On top of that
reconstruction sits the esxDOS port and
the extensions listed below. Everything
runs on an ordinary ZX Spectrum with a
divSD (or another older div-device) and
esxDOS.

OVERVIEW
--------

The program consists of an integrated
editor and a compiler for a C-like
language called "C'". You write the
program in the editor, check it with
ANALYSE (SYNTAX CHECK), compile it with
GENERATE (CODE) and run it with RUN.
Source files use the .KCC extension;
during compilation you can attach
ready-made functions from binary
libraries in the .KCL format.

Program code starts at address 57630
(cold start); you can leave it to BASIC.
If you keep RAMTOP below 25000, you can
safely return to the program with
RANDOMIZE USR 57639 (warm start). To
change the colours, especially of the
editor, set the single attribute byte at
address 57678.

NEW IN VERSION 2
----------------

How KCC2 differs from the original KCC
(KAMASOFT C' from 1990):

- Full port to esxDOS: loading, saving,
  merging sources and saving a block all
  go to the SD card.
- Support for file paths and work with
  extensions.
- Files are pure ASCII (CR-terminated).
- New keyword extern (replaces the older
  limited merge). Load a library -
  extern "lib.kcl";
- Libraries can be managed with the dot
  command .KCLIB (add, delete, list,
  join, split). The extended keyword
  inline now also allows attaching any
  data file; it has two forms: inline
  bytes and inline "file"; which inserts
  the contents of a binary file.
- Both inline and extern can take a path
  to the files.
- A single unified menu; all its
  functions are available in EXTend mode.
- A main control byte for the editor
  colour scheme.
- The compile result shows
  <start>,<length>.
- After GENERATE you can press R to run
  the compiled program right away (RUN).
- Reworked error messages: a missing
  element is reported with the prefix
  "NO".
- File errors from the menu (Load, Save,
  Merge, Blk) and reading a library or
  binary file during compilation print no
  message; they light the red border,
  wait for a key and return to the
  editor.
- The editor starts with a built-in short
  help loaded as the source.
- Editor: auto-indent, reworked insert,
  new lines and much more...
- SYMBOL SHIFT + X types ~ (tilde), not
  the pound sign.
- The active block is shown by a flashing
  attribute in the top-right corner.
- Entering an empty name and ENTER
  cancels loading, saving, merging and
  saving a block.
- Library fixes, new functions.
- Hardened return to BASIC, various
  optimisations, faster character
  printing and editor movement, and many
  space savings (filled with
  improvements).

FIRST PROGRAM (TUTORIAL)
------------------------

The whole cycle on one example. In the
EDITOR type:

  extern "libs/basic.kcl";
  declare int i;
  {
  cls();
  for i=1; i<=3; i=i+1 {
    print("ROW %N\N",i);
    }
  }

Then with the command key EXT (CAPS Shift
+ SYMBOL Shift) and a letter: A (ANALYSE)
runs the check. basic.kcl is loaded, the
text is checked and OK is printed (or it
stops at the first error). G (GENERATE)
compiles and prints OK <start>,<length>.
Then press R (RUN). The screen clears and
you get:

  ROW 1
  ROW 2
  ROW 3

That is the whole cycle: source, A
(ANALYSE), G (GENERATE), R (RUN).

You can press R right after G (without
returning to the editor).

If you are too lazy to type the intro by
hand, you have surely already found the
combinations EXT, O and EXT, L for
entering a name and loading a source from
the current directory.

EDITOR
------

After start you are straight in the
editor; this version of KCC no longer has
a separate intro menu. The top line
serves as both menu and command bar; the
rest is a full-screen editor.

Typing and cursor:

- the cursor may sit past the end of a
  line (spaces are filled in when you
  start typing there)
- ENTER opens a new line and auto-indents
  it: the cursor stands under the first
  character of the line you left, so
  formatted code keeps its indentation
- DELETE erases the character to the left
- SYMBOL SHIFT + X types ~ (tilde)
- some operations depend on
  insert/overwrite mode (toggled with
  CAPS Shift + 1)

You enter commands with the command key
(EXT) and then the initial letter from
the list in the top line:

Editing commands (blocks and search):

  S Start  - mark block start (this line)
  E End    - mark block end (a later line
             than Start; a one-line or
             reversed range is rejected)
  C Copy   - copy block to cursor line
  D Delete - delete the marked block
  F Find   - find text

Blocks work on whole lines (Start and End
remember line numbers, not columns).
While a block exists, a small square
flashes in the top-right corner of the
screen; it disappears once the block is
cleared (Del, Cpy, a new Start...).

File operations. Choice Oth (O) redraws
the top menu line and reminds you of the
file operations. It also shows the first
and last addresses free for compilation:

  New   (N)  clear source, start fresh
  Load  (L)  load a .KCC source file
  Write (S)  save the .KCC source file
  Merge (M)  insert a file at the cursor
  Block (B)  save marked block to a file

When entering a file name, the last name
you used is offered; an empty name
cancels the operation. The name is at
most eight characters long. You do not
type the .KCC extension or any other; the
program adds it itself.

FILES AND I/O
-------------

Loading, saving, merging and saving a
block all ask for a file name. Rules for
the name:

- 1 to 8 characters
- letters A-Z or a-z, digits 0-9, '-' and
  '_'
- do not type an extension - .KCC is
  added automatically for source files
- the field is pre-filled with the
  current name; edit as needed
- an EMPTY name (clear it and press
  ENTER) cancels the operation and
  returns to the editor

These operations are in the I/O submenu
under Oth (see EDITOR): L replaces the
whole buffer with the loaded file, M
inserts a file into the buffer at the
cursor (handy for assembling sources), B
writes the marked block to its own .KCC
file, S saves and N starts a new source.
Files are accessed on the current esxDOS
drive. A file error lights the RED BORDER
and waits for a key - with no text
message - then returns to the editor.

COMPILE / GENERATE
------------------

Compilation and running are controlled
from the editor command bar (command key
EXT, then a letter).

  Ana (A)  syntax check of the source
           (ANALYSE) and loads extern
           libraries; stops on the first
           bad line, otherwise reports OK
  Gen (G)  compile source to machine code
           (COMPILE); on success prints
           OK <start>,<length>
  Run (R)  run the compiled program; if
           nothing is compiled, Run is
           ignored

Right after Gen you can press R to run
the program immediately; any other key
returns to the editor.

Compilation

Gen runs the whole analysis again and
only then generates code. Everything Ana
reports is therefore reported by Gen too.
In addition, only Gen resolves names,
labels, variables and constants and
assembles bytes, so these things appear
only here (even if Ana passed OK):

  NO NAME   - undeclared name (or extern
              function not in a library)
  REDEFINED - same name declared twice
  VARS>127  - too many variables
              (offset > 127)
  NO LABEL  - goto to a missing label
  TOO BIG   - numeric constant > 65535
  BAD TOKEN - invalid token while
              generating
  NO MEM    - generated code no longer
              fits (a library that does
              not fit reports NO MEM
              already at Syn)
  inline file - read only now: if not
              found, reports NO FILE; a
              read error lights the red
              border

After a successful Gen, OK
<start>,<length> is printed (the start
address and the code length).

WORKING WITH FUNCTIONS
----------------------

What you can do with functions:

- call as a statement: hrcon();, hcls();
- a function on the right side of an
  assignment: r = rnd() % 3;, c = rnd() %
  6 + 1;
- a function in a condition: while
  (inkey() == 32), if (peek(x) == 0)
- a variable/constant as an argument:
  ink(c);, hrcat(row, col);

What you cannot do - you must not pass
the result of a function call as an
argument to another call, i.e.
func(otherfunc(...)) is not allowed.
Examples that do not work:

- ink(rnd() % 6 + 1) - rnd() inside
  ink(...)
- hprint(itoa(x)), hplot(rnd(), rnd())
  and the like

C' LANGUAGE REFERENCE
---------------------

C' is a small, fixed language similar to
C. A program is global declarations, then
a body in { }, then optional function
definitions. Statements end with ';';
blocks are introduced with '{' and '}'.
The body runs at RUN.

PROGRAM SHAPE

  @49152  \ compile address \
  extern "basic.kcl"; \ libraries \
  declare int n; \ global vars \
  { ... } \ body (runs first) \
  func sub(a); {...} \ after body \

The optional first line @N sets the
address the program is compiled to
(START:); N is decimal and @N stands
alone on the line, BEFORE extern. Without
@N the address is automatic, just above
the source (see MEMORY MAP). The address
must lie in free RAM, outside KCC2 code,
the source, the buffer and the stack.

DATA TYPES

int - 16-bit integer (2 bytes). char -
8-bit value (1 byte), 0..255. There are
no other types.

ARRAYS (ONE-DIMENSIONAL ONLY)

  declare int t[10]; \ 10 int, 20 B \
          char s[32]; \ 32 char, 32 B \

Indexed from 0; t[i] reads or writes
element i (char = 1 byte, int = 2 bytes).
The size in [ ] must be a non-zero
decimal constant (zero reports BAD
CONTEXT).

VARIABLES AND SCOPE

One declare introduces one or more groups
separated by ';':

  declare int i,j; char c[30];

A group is a type (int or char) and a
list of names or arrays; the word declare
is not repeated. Declarations before the
body are GLOBAL; declarations inside a
function are LOCAL to it. Within one
scope (the body or a function) only a
limited number of variables fit: their
total size may be up to 127 bytes; beyond
that COMPILE reports VARS>127.

CONSTANTS, STRINGS, COMMENTS

Numbers are DECIMAL only (read by the
ROM), e.g. 0, 65535; there is no hex or
binary notation. A character constant is
written in apostrophes, 'A', and means
the code of that character (exactly one
character). Strings are in quotes:
"TEXT". A comment is delimited by a
backslash on both sides and may span
several lines:

  \ this is a comment \

OPERATORS BY PRECEDENCE (HIGHEST FIRST)

  ++  --          increment / decrement
  *  /  %         multiply, divide, mod
  +  -            add, subtract
  <<  >>          bit shift left / right
  <  <=  >  >=    comparison
  ==  !=          equal / not equal
  &               bitwise AND
  |   ^           bitwise OR, bitwise XOR
  &&              logical AND
  ||              logical OR
  =               assignment (lowest)

Note: '^' is the bitwise EXCLUSIVE OR; on
the ZX Spectrum it is the up-arrow glyph
(SYMBOL SHIFT+H).

The order above differs in places from
standard C, so rather use parentheses.
For example '|' and '^' have the SAME
precedence here, whereas in C '^' is
above '|'.

UNARY (PREFIX) OPERATORS

  ++x  x++   increment a variable
  --x  x--   decrement a variable
  &name      address of a variable
             (or &arr[i])
  *addr      value stored at addr

C' has no sign before a value: write a
negative number as 0-x. If you write just
a single '+' or '-', C' expects a second
one ('++' or '--'), otherwise it reports
NO OPERAND.

++/-- work only on a plain variable, not
on an array element or a function (e.g.
++arr[i] reports BAD SYNTAX, arr[i]++
reports NO OPERAND). x++ and x-- give the
original value and then change the
variable; ++x and --x change first and
give the new value.

ADDRESSES AND MEMORY (& AND *)

C' has no pointer type - an address is
simply an int - but two operators allow
direct memory access: &name gives the
address of a variable or array element;
*addr is the BYTE at address addr
(peek/poke), so to walk through memory
increase the address by 1. *addr works on
both sides of '=':

  *adr = v;   \ store v at addr (POKE) \
  x = *adr;   \ read from addr (PEEK) \
  *p++ = c;   \ store then advance p \

You can thus read and write memory
directly in the language; the library
functions POKE and PEEK are just a
wrapped form of the same thing.

STATEMENTS

  if cond { ... } else { ... }
  while cond { ... }
  do { ... } while cond;
  for init; cond; step { ... }
  switch e { case 1; ... default; ... }
  break;     leave loop or switch
  continue;  jump to next iteration
  goto lbl;     lbl:   jump within func
  return;   or   return expr;
  inline n1 n2 ... ;  Z80 code bytes
  inline "file";  insert a file (INCBIN)

A condition is simply an expression
before a { } block; parentheses are
optional grouping, not a requirement. for
has three expressions separated by ';'
without enclosing parentheses. case and
default end with ';' and a label is
written as name: with a colon (you jump
to it via goto name;).

SWITCH, CASE, DEFAULT

switch evaluates the expression once and
compares it in turn with the value of
each case. A matching case runs; a case
does NOT terminate itself, so after each
one write break; - that jumps out of the
switch. default runs when no case
matches.

Example:

  switch x {
  case 1; foo(); break;
  case 2; bar(); break;
  default; baz();
  }

If you omit break in a case, after it
finishes execution does not stop and
continues into the following code with an
uncertain result (the internal compared
value may already be overwritten, e.g. by
a function call). So write break after
every case.

A nested switch is forbidden (BAD
CONTEXT). case/default outside a switch
reports CASE/DEFAULT w/o SWITCH.

INLINE - DIRECT MACHINE CODE

inline has two forms. With numbers it
inserts raw Z80 bytes (each 0..255 as one
byte of code):

  inline 62 65 215; \ LD A,65:RST 16 \

With a string in quotes it inserts the
entire contents of a file from the
current directory at that spot (like
INCBIN):

  inline "data.bin";

The file is read into the free code space
only at Gen. If the file does not exist
(not found during compilation), it
reports NO FILE (like extern); on a read
error (SD) it only lights the red border.

Both inline forms can be mixed, separated
by a comma. Use them for what the
language cannot do; inline is a statement
- it may stand anywhere a statement is
allowed: in the body and in a function,
even inside if/while/for/switch.

FUNCTIONS

An internal function is defined after the
main body. (Note: libraries with binary
external functions are declared at the
start of the program.)

  func name(a,b); { ... return e; }

Parameters a,b are named and inside are
used as local variables; a function may
also have its own declarations. It is
called as name(x,y). A function call must
not be nested into an argument - f(g(x))
reports BAD SYNTAX; use an intermediate
result (t=g(x); f(t);). This applies to
both your own and library functions.
Parameters and locals live within a
single call, which the compiler accesses
through register IX, so each call has its
own copies. A function may therefore call
itself (recursion); the depth is limited
only by the free space for frames.
Library (machine-code) functions are
different: they are wired in with the
word extern and read arguments as
described in PARAMETER PASSING in the
library reference.

USING LIBRARIES

A library is a file of ready-made
functions. For compilation the program
loads what it needs with the word extern
- right at the start, before declarations
and the body. 

Load a library file (name in quotes).
One library per statement; they stack
on top of each other:

     extern "basic.kcl";
     extern "zxgfx.kcl";

A wired-up function is then called like
an ordinary one. A full example with two
libraries at once:

     extern "basic.kcl";
     extern "zxgfx.kcl";
     {
     ink(2); circle(128,88,40);
     }

Libraries must be stated with extern in
the source: every ANALYSE/GENERATE starts
with an empty library area, so a library
loaded earlier does not survive into the
next compilation.

C' VS STANDARD C
----------------

C' is modest and small. Compared to K & R
/ ANSI C it omits:

- no preprocessor: no #define, #include,
  #ifdef; #include is replaced by
  libraries via extern.
- no float or long; only int (16-bit) and
  char (8-bit).
- no keywords unsigned / signed / short /
  void.
- no struct, union, enum or typedef.
- no pointer type (an address is simply
  an int) - but the unary & (address) and
  * (dereference) allow direct memory
  access.
- arrays are one-dimensional only.
- no separate compilation or linker; you
  assemble code via extern libraries
- comments are \ ... \, not /* ... */.
- conditions need no parentheses; for is
  'for init; cond; step { }' without
  enclosing parentheses; case/default end
  with ';' and a label is 'name:'.
- '^' is bitwise XOR (the up-arrow key,
  SYMBOL SHIFT+H); '%N' in a PRINT string
  is output formatting, whereas '%' on
  its own is the remainder operator.

Everything else - if/else, while, do,
for, switch, break, continue, goto,
return - has the usual C form.

SYNTAX COMPARISON (EXAMPLES)

The same constructs, different notation.
C' omits the round parentheses around
conditions, uses ';' as a separator
inside 'for' and after 'case'/'default',
makes comments with '\ ... \' and places
functions after the program body. C'
(KCC2) on the left, standard / Small C on
the right.

if / else
  C':      if x>0 { ... } else { ... }
  Small C: if (x>0) { ... } else { ... }

while
  C':      while x<10 { ... }
  Small C: while (x<10) { ... }

do-while
  C':      do { ... } while x<10;
  Small C: do { ... } while (x<10);

for (three exprs by ';', no parens)
  C':      for i=1; i<=3; i=i+1 { ... }
  Small C: for (i=1; i<=3; i=i+1) { ... }

switch / case / default (labels end ';')
  C':  switch e { case 1; ...
                  default; ... }
  SmC: switch(e){ case 1: ...
                  break; default: ... }

break / continue (same)
  C':      break;   continue;
  Small C: break;   continue;

goto and label (same, label with colon)
  C':      goto nav;  ...  nav:
  Small C: goto nav;  ...  nav:

return (same)
  C':      return;   return e;
  Small C: return;   return e;

comments
  C':      \ this is a comment \
  Small C: /* this is a comment */

function definition
  (in C' after the body, header ends ';')
  C':  func name(a,b); { ... return e; }
  SmC: name(a,b) int a,b; {...return e;}

variable declarations (C' uses 'declare')
  C':      declare int i,j; char c[30];
  Small C: int i,j; char c[30];

Note: in switch/case end every case with
break;. C' does not terminate a case by
itself, and without break execution
continues into the following code with an
uncertain result. Details in STATEMENTS
(SWITCH, CASE, DEFAULT).

COMPILER LIMITS
---------------

- variables: within one scope (the body
  or a function) their total size may be
  up to 127 bytes, otherwise COMPILE
  reports VARS>127.
- int is 16-bit; char and an array
  element are 8-bit.
- arrays have one dimension; the size is
  a non-zero decimal constant.
- libraries stack below the program; when
  the next one does not fit, you get NO
  MEM.
- the program (body), its functions and
  all libraries must fit together below
  the ceiling (below address 57700 minus
  the libraries wired in during
  compilation).

.KCLIB - BUILDING LIBRARIES
---------------------------

.KCLIB (KC library maker) is an esxDOS
dot command for building and editing .KCL
files. It runs from BASIC; with no
arguments it prints help. The forms are:

  .KCLIB -a (new)lib[.KCL] file[.BIN]...
           add: appends the bytes of each
           file as a function (name =
           file name); the library is
           created if new
  .KCLIB -d lib[.KCL] func func2...
           delete one or more functions
           by name
  .KCLIB -l lib[.KCL]
           list functions and size
  .KCLIB -j newlib[.KCL] lib1[.KCL]...
           join several libraries into
           newlib
  .KCLIB -s lib[.KCL] newlib[.KCL] func
           split a function out into
           newlib

It reports a bad file name, an unknown
option, a full library buffer or a
function not found, and asks before
overwriting an existing function.

KCL FILE FORMAT
---------------

A .KCL library is a binary file. It
starts with a single descriptive byte
holding the number of functions; then the
individual functions follow:

  [name] 0FFh [len-lo] [len-hi] [body]

  name  uppercase ASCII, ended by 0FFh
  len   16-bit body length, little-endian
        (lo, hi)
  body  function machine-code bytes

Functions are self-contained, so a
library can be freely split and joined
(with the dot command .KCLIB) or several
libraries loaded together.

PARAMETER PASSING

Arguments are shared via a parameter
block. The system variable at 5CB0h holds
the address of this block; a function
loads the block with the instruction

     LD IX,(5CB0h)

Each argument takes one 16-bit slot (2
bytes, low byte first):

     arg1 = (IX+0) low, (IX+1) high
     arg2 = (IX+2) low, (IX+3) high
     etc.

The last (or only) argument is also in
register HL on entry, so a
single-argument function can use HL
directly, without reaching into the
block.

VALUE SIZES

- 16-bit value: the whole slot (or HL) is
  used. The function reads L=(IX+n),
  H=(IX+n+1). This is how coordinates,
  addresses and INT variables are passed.
- 8-bit value: only the low byte matters,
  the high byte is 0. The function reads
  the byte with LD A,(IX+n). This is how
  colours, rows, columns, characters and
  CHAR variables are passed.
- string: passed by ADDRESS, not by
  value. The slot holds a 16-bit pointer
  to the first character; the text itself
  is elsewhere and ends with a zero byte.
  PRINT takes the string address in arg1
  and reads the characters from there.

RETURN VALUE

A function that returns something leaves
the result in HL. For a byte result the
high byte H is zero, so it can be taken
either as a byte or as a 16-bit value.

VARIABLE ARGUMENT COUNT

Most functions have a fixed number of
arguments. The exception is PRINT (1+):
it always takes a string and then as many
numbers as there are %N markers, reading
further slots arg2, arg3 ... as needed.

READING PARAMETERS - EXAMPLES

IX is pointed at the block, then the
individual slots are read. With arg1
16-bit and arg2 8-bit:

  DD2AB05C LD IX,(5CB0h) ; IX -> block
  DD6E00 LD L,(IX+0) ; arg1 low
  DD6601 LD H,(IX+1) ; arg1 high -> HL
  DD7E02 LD A,(IX+2) ; arg2 byte -> A
  ... ; use HL and A
  C9 RET

Two 8-bit arguments (like AT) - each read
from the low byte of its slot:

  DD2AB05C LD IX,(5CB0h) ; IX -> block
  DD7E00 LD A,(IX+0) ; arg1 byte
  ... ; use A
  DD7E02 LD A,(IX+2) ; arg2 byte
  ... ; use A
  C9 RET

On entry the last argument is also in HL,
so a single-argument function can read HL
directly and skip IX.

EXAMPLE FUNCTIONS: PEEK, DPEEK, POKE

Three complete functions. peek and poke
are in BASIC.KCL; dpeek is their
counterpart for a 16-bit value. They show
returning the result in HL and reading
the address from the parameter block.

peek(addr) - a byte from one cell
(0-255). The address is the only
argument, so it is right in HL:

  7E LD A,(HL) ; read byte from addr
  6F LD L,A ; result to L
  2600 LD H,0 ; high byte 0 -> 0-255
  C9 RET

dpeek(addr) - a word from two adjacent
cells (0-65535), low byte first. The
address is in HL:

  7E LD A,(HL) ; low byte from addr
  23 INC HL ; to addr+1
  66 LD H,(HL) ; high byte from addr+1
  6F LD L,A ; HL = value 0-65535
  C9 RET

poke(addr,val) - write a byte into a
cell. Two arguments: the last (val) is
also in HL, the address is read from the
parameter block:

  7D LD A,L ; val (last arg) -> A
  DDE5 PUSH IX ; save IX
  DD2AB05C LD IX,(5CB0h) ; IX -> block
  DD6E00 LD L,(IX+0) ; addr low
  DD6601 LD H,(IX+1) ; addr high -> HL
  77 LD (HL),A ; store val at addr
  DDE1 POP IX ; restore IX
  C9 RET

RELOCATABILITY OF COMPILED CODE
-------------------------------

The compiled program is built at a fixed
start address - the START: address
printed after compilation - and is not
freely relocatable. The body of each
library function is itself
position-independent: it reaches at most
into ROM and to the parameter block at
5CB0h, never to its own fixed address in
RAM. The program that uses and calls it,
however, is not independent.

The compiler places each body at the
chosen address and generates an absolute
CALL to it; the program's own GOTO jumps,
calls and variable accesses are likewise
absolute and tied to the start. If you
want to run the program at a different
address, you must compile it again; you
cannot easily relocate the old binary.

MEMORY MAP
----------

Memory usage from top to bottom (a
48K-style layout):

  FFFxh  top of KCC2 code
  E164h  start of KCC2 (editor +
         compiler). RAMTOP is set below
         the source (CLEAR 24999), so
         BASIC and its stack stay below
         25000 and never touch the
         source, compiled program,
         libraries or KCC2 itself
  below  binary libraries, loaded
         temporarily for compilation,
         stacked downward as the extern
         statements load them
   ...   free space
   ...   compiled program (prolog +
         variables + code), just above
         the source
  START  compiled binary = end of
         source + 1
  61A8h  source text buffer (25000),
         upward
  lower  ZX system vars, screen, BASIC

RUN enters the program at its START:
address. The START: address is overridden
by @N on the first line of the source
(see PROGRAM SHAPE).

PEEK, POKE, CALL and INLINE see the whole
map, so please be careful with them:
avoid KCC2 code, the text buffer and the
stack.

ERROR MESSAGES
--------------

On an error the offending line is shown
(Checking N during ANALYSE, Compiling N
during GENERATE) and the message below
it; failure ends with the word FAILED. A
clean check (ANALYSE) ends with OK. A
successful compile (GENERATE) ends with
the line OK <start>,<length> (the start
address and the length of the compiled
code).

Messages come in two forms: a missing
element is reported with the prefix "NO"
+ what is missing (NO ; NO OPERAND NO
NAME); other errors have their own name
(e.g. BAD SYNTAX).

ANALYSE check messages (syntax):

NO OPERAND
  An operator has no operand; the
  expression is incomplete. E.g.: i=3+;
  x=*2; y=; (nothing follows the operator
  or '='); an empty expression where one
  is expected. Also a lone '-' or '+' at
  the start of an operand (negation is
  written 0-x), and ++/-- on an array
  element or function in postfix
  (arr[i]++).
NO OPERATOR
  Two operands with no operator between
  them. E.g.: i=3 4; x=a b; (a value or
  name right after another value with no
  operator).
NO ;
  A statement is not ended with a
  semicolon. E.g.: a missing ';' after an
  assignment, after 'return', after
  'inline ...', or between parts of a
  'for' header.
NO {
  A '{' (body) was expected and not
  found. E.g.: after if(...), else, for
  ..., while(...), do, switch(...), after
  a function header func name(...) or for
  the main program body.
NO }
  A '}' was expected; a block stayed
  open. E.g.: end of source with an
  unclosed block; a missing closing brace
  of a nested block.
NO SEPARATOR
  A comma ',' is missing in a list. E.g.:
  declare int i j; (should be i,j); f(a
  b) (arguments); the list in 'inline'.
NO FILE
  A file on the SD card could not be
  opened. For extern "lib.kcl"; (a
  missing library) already at ANALYSE;
  for inline "file"; (a missing file) at
  COMPILE. Either it does not exist or it
  has the wrong name/extension.
BAD SYNTAX
  A token is not allowed in this place,
  or the construct is written
  incorrectly. E.g. a prefix ++/-- on an
  array element or function (++arr[i],
  ++f()), or a nested function call in an
  argument (e.g. f(g(x))).
BAD NESTING
  Parentheses or blocks are not nested
  correctly (e.g. '}' without a matching
  '{', crossing of parentheses and
  blocks).
BAD CONTEXT
  A construct is in the wrong context.
  E.g.: switch inside switch (a nested
  switch); an array of zero size (declare
  int t[0]).
DO w/o WHILE
  A do { ... } block has no following
  while(...).
CASE/DEFAULT w/o SWITCH
  case or default is outside a switch
  body.

COMPILE messages (code generation):

NO NAME
  A name (variable, label, function) was
  not declared; or a function is not in
  any loaded library.
NO LABEL
  goto points at a label that does not
  exist.
VARS>127
  A variable index/offset exceeded 127 -
  there are too many variables (the ix+d
  frame reaches above +127, roughly more
  than ~64 int variables or too large a
  cumulative offset).
REDEFINED
  A name is declared more than once (a
  duplicate variable, label or function).
TOO BIG
  A numeric constant in the source is
  greater than 65535 (does not fit in 16
  bits).
BAD TOKEN
  An invalid token while generating code
  (a token the generator cannot process).
NO MEM
  Out of memory: the compiled code or a
  library does not fit below the source
  ceiling. Either the program is too big,
  or a library loaded via extern has not
  enough room in free RAM.

File / SD operation errors:

RED BORDER (no text message)
  An esxDOS error during loading (Load),
  saving (Save), merging (Merge) or
  saving a block (Blk): the editor lights
  the red border, waits for a key and
  returns. Typically a write or SD-card
  error.
  The red border also appears when
  reading a library body, or on a read
  error for inline "..."; (already
  opened). A missing file during
  compilation reports NO FILE.