=========================================
   KCC2 - Kamasoft C Compiler 2
   editor, kompilator a knihovny
   manual - verze pro esxDOS
=========================================

OBSAH
-----

 1. O PROGRAMU KCC2
 2. PREHLED
 3. NOVINKY VE VERZI 2
 4. PRVNI PROGRAM (NAVOD)
 5. EDITOR
 6. SOUBORY A I/O
 7. KOMPILACE / GENERATE
 8. JAK NA FUNKCE
 9. REFERENCE JAZYKA C'
     - TVAR PROGRAMU
     - DATOVE TYPY
     - POLE (jen jednorozmerna)
     - PROMENNE A ROZSAH PLATNOSTI
     - KONSTANTY, RETEZCE, KOMENTARE
     - OPERATORY PODLE PRIORITY
     - UNARNI (PREFIXOVE) OPERATORY
     - ADRESY A PAMET (& a *)
     - PRIKAZY
     - SWITCH, CASE, DEFAULT
     - INLINE - PRIMY STROJOVY KOD
     - FUNKCE
     - POUZITI KNIHOVEN
10. C' OPROTI STANDARDNIMU C
     - SROVNANI SYNTAXE (PRIKLADY)
11. LIMITY KOMPILATORU
12. .KCLIB - STAVBA KNIHOVEN
13. FORMAT SOUBORU KCL
     - ZPUSOB PREDAVANI PARAMETRU
     - VELIKOSTI HODNOT
     - NAVRATOVA HODNOTA
     - PROMENNY POCET ARGUMENTU
     - CTENI PARAMETRU - PRIKLADY
     - PRIKLADY FUNKCI: PEEK, DPEEK, POKE
14. RELOKOVATELNOST PRELOZENEHO PROGRAMU
15. MAPA PAMETI
16. CHYBOVA HLASENI

O PROGRAMU KCC2
---------------

KCC2 (Kamasoft C Compiler 2) je verze 2
kompilatoru KAMASOFT C', puvodne z roku
1990. Tato nova verze vychazi z
rekonstrukce puvodnich zdrojovych kodu
psanych v assembleru Laser Genius, kterou
v Lnx assembleru provedl clovek jmenem
l00k. Na tuto rekonstrukci pak navazuje
uprava esxDOS a rozsireni o novinky
uvedene nize. Vse bezi na obycejnem ZX
Spectru s divSD (nebo jinym starsim
div-zarizenim) a esxDOSem.

PREHLED
-------

Program se sklada z integrovaneho editoru
a kompilatoru jazyka podobnemu C, zvany
"C'". Program napises v editoru,
zkontrolujes volbou ANALYZE (SYNTAX
CHECK), prelozis volbou GENERATE (CODE) a
spustis volbou RUN. Zdrojove soubory maji
priponu .KCC, pri kompilaci lze
pripojovat hotove funkce z binarnich
knihoven ve formatu .KCL.

Programovy kod zacina na adrese 57630
(studeny start), lze z nej odejit do
BASICu. Pokud drzis RAMTOP pod 25000,
muzes se do programu bezpecne vratit
pomoci RANDOMIZE USR 57639 (teply start).
Pokud chces zmenit barvy, zejmena
editoru, nastav jednotny atributovy bajt
na adrese 57678.

NOVINKY VE VERZI 2
------------------

Cim se KCC2 lisi od puvodniho KCC
(KAMASOFT C' z roku 1990):

- Uplny prenos na esxDOS: nahravani,
  ukladani, slucovani zdrojaku a ulozeni
  bloku jdou na SD kartu.
- Podpora souborove cesty a prace s
  priponami.
- Soubory jsou ciste ASCII (s ukoncenim
  CR).
- Nove klicove slovo extern (nahrazuje
  starsi omezene merge). Nahrani
  knihovny: extern "lib.kcl";
- Knihovny lze spravovat pomoci teckoveho
  prikazu .KCLIB (pridat, smazat, vypsat,
  spojit, rozdelit). Rozsirene klicove
  slovo inline, nove umoznujici pripojeni
  libovolneho souboru dat, ma dve formy:
  inline bajty a inline "soubor"; vlozi
  obsah binarniho souboru
- Take v prikazech inline i extern lze
  zadavat cestu k souborum.
- Sjednocene a jedine menu, jeho vsechny
  funkce jsou dostupne v rezimu EXTend.
- Hlavni ridici bajt pro barevne schema
  editoru.
- Vysledek prekladu uvadi
  <start>,<length>.
- Po prekladu (GENERATE) lze stiskem R
  prelozeny program rovnou spustit (RUN).
- Prepracovana chybova hlaseni: chybejici
  prvek se hlasi predponou "NO"
- Chyby pri operacich se soubory z menu
  (Load, Save, Merge, Blk) a cteni
  knihovny ci binarniho souboru pri
  kompilaci netisknou hlasku, ale
  rozsviti cerveny border, pockaji na
  klavesu a vrati se do editoru.
- Editor startuje s vestavenym strucnym
  helpem nactenym jako zdroj.
- Editor: auto-odsazeni prepracovany
  insert, nove radky a mnohe dalsi...
- SYMBOL SHIFT + X pise ~ (tilda), ne
  libru.
- Indikace aktivovaneho bloku blikajicim
  atributem v pravem hornim rohu
- Zadani prazdneho jmena a ENTER zrusi
  nahravani, ukladani, slucovani i
  ulozeni bloku.
- Opravy knihoven, nove funkce.
- Zpevneny navrat do BASICu, ruzne
  optimalizace, rychlejsi tisk znaku i
  pohyb v editoru a mnohocetne uspory
  mista (zaplnene vylepsenimi).

PRVNI PROGRAM (NAVOD)
---------------------

Cely cyklus na jednom prikladu. V EDITORU
napis:

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

Pak prikazovou klavesou EXT (CAPS Shift +
SYMBOL Shift) a pismenem: A (ANALYSE)
proved kontrolu. Nahraje se basic.kcl,
zkontroluje text a vypise OK (nebo se
zastavi na prvni chybe); Stisk G
(GENERATE) provede kompilaci a vypise OK
<start>,<length>. Pak stiskni R (RUN).
Obrazovka se smaze a objevi se:

  RADEK 1 RADEK 2 RADEK 3

To je cely cyklus: zdrojak, A (ANALYSE),
G
(GENERATE), R (RUN).

R muzes zmacknout i na konci G (bez
navratu do editoru).

Pokud jsi liny neco na uvod opisovat,
urcite jsi zjistil uz kombinaci EXT, O,
resp. EXT, L pro zadani jmena a prihrani
zdrojaku z aktualniho adresare.

EDITOR
------

Po startu jsi rovnou v editoru;
samostatne uvodni menu uz tato verze KCC
nema. Horni radek slouzi jako menu i jako
prikazova lista, zbytek je
celoobrazovkovy editor.

Psani a kurzor:

- kurzor smi stat i za koncem radku
  (mezery se doplni, az tam zacnes psat)
- ENTER otevre novy radek a auto-odsadi
  ho: kurzor stoji pod prvnim znakem
  radku, ze ktereho jsi odesel, takze
  formatovany kod si drzi odsazeni
- DELETE smaze znak vlevo
- SYMBOL SHIFT + X pise ~ (tilda)
- nektere operace zalezi na modu
  insert/overwrite (prepinacem je CAPS
  Shift +1)

Prikazy zadavas prikazovou klavesou (EXT)
a pak pocatecnim pismenem z listy v
hornim radku:

Editacni prikazy (bloky a hledani):

  S Start - oznaci zacatek bloku (tento
  radek) E End - oznaci konec bloku
  (pozdejsi radek nez
             Bgn; jednoradkovy ci
             obraceny rozsah se odmitne)
  C Copy - zkopiruje blok na radek s
  kurzorem D Delete- smaze oznaceny blok
  F Find - najde text

Bloky pracuji po celych radcich (Start a
End si pamatuji cisla radku, ne sloupce).
Dokud blok existuje, blika v pravem
hornim rohu obrazovky ctverecek; zmizi,
jakmile se blok zrusi (Del, Cpy, novy
Start...).

Souborove operace Volba Oth (O) prekresli
horni radek menu a pripomene ti souborove
operace. Dale zobrazuje prvni a posledni
adresy, volne pro kompilaci.:

  New (N) vymaze zdroj a zalozi novy
  (cisty editor) Load (L) nahraje
  zdrojovy soubor .KCC Write (S) ulozi
  zdrojovy soubor .KCC Merge (M) vlozi
  soubor na pozici kurzoru Block (B)
  ulozi oznaceny blok do souboru

Pri zadavani jmena souboru se ti nabizi
posledni zadane jmeno; prazdne jmeno
operaci zrusi. Delka souboru je maximalne
osm znaku. Priponu .KCC ani zadnou jinou
nezadavas. Tu si program doplni sam.

SOUBORY A I/O
-------------

Nahrani, ulozeni, slucovani i ulozeni
bloku se ptaji na jmeno souboru. Pravidla
pro jmeno:

- 1 az 8 znaku
- pismena A-Z nebo a-z, cislice 0-9, '-'
  a '_'
- priponu nepis - .KCC se u zdrojovych
  souboru doplni automaticky
- pole je predvyplneno aktualnim jmenem;
  uprav podle potreby
- PRAZDNE jmeno (smaz ho a stiskni ENTER)
  operaci zrusi a vrati do editoru

Tyto operace jsou v I/O podmenu pod
volbou Oth (viz EDITOR): L nahradi cely
buffer nactenym souborem, M vlozi soubor
do bufferu na pozici kurzoru (hodi se pro
skladani zdroju), B zapise oznaceny blok
do vlastniho .KCC souboru, S ulozi a N
zalozi novy zdroj. Pristup k souborum je
na aktualni jednotce esxDOS. Chyba
souboru rozsviti CERVENY BORDER a pocka
na klavesu - bez textove hlasky - pak se
vrati do editoru.

KOMPILACE / GENERATE
--------------------

Preklad a spusteni se ovladaji z
prikazove listy editoru (prikazova
klavesa EXT, pak pismeno).

  Ana (A) syntakticka kontrola zdroje
  (ANALYSE)
           a nahrani knihoven extern;
           zastavi na prvnim chybnem
           radku, jinak hlasi OK
  Gen (G) preklad zdroje do strojoveho
  kodu
           (COMPILE); po uspechu vypise
           OK <start>,<length>
  Run (R) spusti prelozeny program; dokud
  neni
           nic prelozeno, Run se ignoruje

Hned po Gen lze stiskem R spustit program
rovnou; jina klavesa vrati do editoru.


Kompilace

Gen spusti celou analyzu znovu a teprve
pak generuje kod. Vse, co hlasi Ana,
proto hlasi i Gen. Navic az Gen resi
jmena, navesti, promenne a konstanty a
sklada bajty, takze tyto veci se objevi
az tady (i kdyz Ana prosel OK):
  NO NAME - nedeklarovane jmeno (nebo
  extern
               funkce neni v knihovne)
  REDEFINED - stejne jmeno deklarovano
  dvakrat VARS>127 - prilis promennych
  (offset > 127) NO LABEL - goto na
  neexistujici navesti TOO BIG - ciselna
  konstanta > 65535 BAD TOKEN - neplatny
  token pri generovani NO MEM -
  vygenerovany kod se uz nevejde
               (knihovna, ktera se
               nevejde, hlasi NO MEM uz u
               Syn)
  inline soubor - cte se az ted: kdyz
               se nenajde, hlasi NO FILE;
               chyba cteni rozsviti
               cerveny border

Po uspesnem Gen se vypise OK <start>,
<length> (pocatecni adresa a delka kodu).

JAK NA FUNKCE
-------------

Co muzes s funkcemi delat:

- volani jako prikaz: hrcon();, hcls();
- funkce na prave strane prirazeni: r =
  rnd() % 3;, c = rnd() % 6 + 1;
- funkce v podmince: while (inkey() ==
  32), if (peek(x) == 0)
- promenna/konstanta jako argument:
  ink(c);, hrcat(row, col);

Co nelze -nesmis dat vysledek volani
funkce jako argument jineho volani,
 tedy nelze: funkce(jinafunkce(...))
priklady, co nejdou:
- ink(rnd() % 6 + 1) - rnd() uvnitr
  ink(...)
- hprint(itoa(x)), hplot(rnd(), rnd())
  apod.

REFERENCE JAZYKA C'
-------------------

C' je maly, pevne dany jazyk podobny C.
Program jsou globalni deklarace, pak telo
v { }, pak pripadne definice funkci.
Prikazy konci ';'; bloky se zavadeji '{'
a '}'. Telo se spusti pri RUN.

TVAR PROGRAMU

  @49152  \ adresa prekladu \
  extern "basic.kcl"; \ knihovny \
  declare int n; \ globalni promenne \
  { ... } \ telo (bezi prvni) \
  func sub(a); {...} \ za telem \

Volitelny prvni radek @N urci adresu, na
kterou se program prelozi (START:); N je
dekadicke a @N stoji samo na radku, JESTE
PRED extern. Bez @N je adresa
automaticka, tesne nad zdrojem (viz MAPA
PAMETI). Adresa musi lezet ve volne RAM,
mimo kod KCC2, zdroj, buffer a zasobnik.

DATOVE TYPY

int - 16bitove cele cislo (2 bajty). char
- 8bitova hodnota (1 bajt), 0..255. Zadne
jine typy nejsou.

POLE (jen jednorozmerna)

  declare int t[10]; \ 10 int, 20 B \
          char s[32]; \ 32 char, 32 B \
Indexuje se od 0; t[i] cte nebo zapisuje
prvek i (char = 1 bajt, int = 2 bajty).
Velikost v [ ] musi byt nenulova
dekadicka konstanta (nulova hlasi
BAD CONTEXT).

PROMENNE A ROZSAH PLATNOSTI

Jeden declare uvadi jednu nebo vice
skupin oddelenych ';':
  declare int i,j; char c[30];
Skupina je typ (int nebo char) a seznam
jmen nebo poli; slovo declare se
neopakuje. Deklarace pred telem jsou
GLOBALNI; deklarace uvnitr funkce jsou
LOKALNI pro ni. V jednom rozsahu (telo
nebo funkce) se promennych vejde jen
omezeny pocet: jejich souhrnna velikost
smi byt do 127 bajtu, nad to COMPILE
hlasi VARS>127.

KONSTANTY, RETEZCE, KOMENTARE

Cisla jsou jen DEKADICKA (cte je ROM),
napr. 0, 65535; neni hex ani binarni
zapis. Znakova konstanta se pise v
apostrofech, 'A', a znamena kod toho
znaku (prave jeden znak). Retezce jsou v
uvozovkach: "TEXT". Komentar je ohranicen
zpetnym lomitkem z obou stran a smi byt
pres vice radku:
  \ toto je komentar \

OPERATORY PODLE PRIORITY (nejvyssi prvni)

  ++ -- inkrementace / dekrementace * / %
  nasobeni, deleni, zbytek + - scitani,
  odcitani << >> bitove posuny vlevo /
  vpravo < <= > >= porovnani == != rovno
  / nerovno & bitovy AND | ^ bitovy OR,
  bitovy XOR && logicky AND || logicky OR
  = prirazeni (nejnizsi)

Pozor: '^' je bitovy EXKLUZIVNI OR; na ZX
Spectru je to glyf sipky nahoru (SYMBOL
SHIFT+H).

Vyse uvedene poradi se misty se lisi od
standardniho C, tak radeji zavorkuj.
Napr. '|' a '^' maji tady STEJNOU
prioritu, kdezto v C je '^' nad '|'.

UNARNI (PREFIXOVE) OPERATORY

  ++x x++ inkrementace promenne --x x--
  dekrementace promenne &jmeno adresa
  promenne (nebo &pole[i]) *adr hodnota
  ulozena na adrese adr

C' nezna znamenko pred hodnotou: zaporne
cislo zapis jako 0-x. Kdyz napises jen
jedno '+' nebo '-', C' ceka druhe ('++'
nebo '--'), jinak hlasi
NO OPERAND.

++/-- jdou jen na obycejnou promennou, ne
na prvek pole ci na funkci (napr.
++pole[i] hlasi BAD SYNTAX, pole[i]++
hlasi NO OPERAND). x++ a x-- daji puvodni
hodnotu a pak promennou upravi; ++x a --x
nejdriv upravi a daji novou.

ADRESY A PAMET (& a *)

C' nema typ ukazatel - adresa je proste
int - ale dva operatory umoznuji primy
pristup do pameti: &jmeno da adresu
promenne nebo prvku pole; *adr je BAJT na
adrese adr (peek/poke), takze pro pruchod
pameti zvysuj adresu po 1. *adr funguje
na obou stranach '=':
  *adr = v;   \ uloz v na adr (POKE) \
  x = *adr;   \ cti z adr (PEEK) \
  *p++ = c;   \ uloz a pak posun p \
Pamet tak ctes i zapisujes primo v
jazyce; knihovni funkce POKE a PEEK jsou
jen zabaleny tvar teze veci.

PRIKAZY

  if podm { ... } else { ... } while podm
  { ... } do { ... } while podm;
  for init; podm; krok { ... }
  switch e { case 1; ...  default; ... }
  break; opusti smycku nebo switch
  continue; skoci na dalsi pruchod goto
  nav; nav: skok v ramci funkce return;
  nebo return vyraz;
  inline n1 n2 ... ;  bajty Z80 kodu
  inline "soubor";  vlozi soubor (INCBIN)

Podminka je proste vyraz pred blokem { };
zavorky jsou nepovinne seskupeni, ne
nutnost. for ma tri vyrazy oddelene ';'
bez obalujicich zavorek. case a default
konci ';' a navesti se pise jmeno: s
dvojteckou (skace se na ne pres goto
jmeno;).

SWITCH, CASE, DEFAULT

switch spocita vyraz jednou a porovna ho
postupne s hodnotou kazdeho case. Sedici
case se provede; case se NEukonci sam,
proto za kazdy pis break; - tim ze
switche vyskocis. default se provede,
kdyz zadny case nesedi.

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

Kdyz u case break vynechas, beh po jeho
skonceni nezastavi a pokracuje do dalsiho
kodu s nejistym vysledkem (vnitrni
porovnavana hodnota uz muze byt prepsana,
napr. volanim funkce). Proto za kazdym
case pis break.

Vnoreny switch je zakazan (BAD CONTEXT).
case/default mimo switch hlasi
CASE/DEFAULT w/o SWITCH.

INLINE - PRIMY STROJOVY KOD

inline ma dve formy. S cisly vlozi primo
bajty Z80 (kazde 0..255 jako jeden bajt
kodu):
  inline 62 65 215; \ LD A,65:RST 16 \
S retezcem v uvozovkach vlozi na dane
misto cely obsah souboru z aktualniho
adresare (jako INCBIN):
  inline "data.bin";
Soubor se cte do volneho mista kodu az
pri Gen. Kdyz soubor neexistuje (neni pri
kompilaci nalezen), hlasi NO FILE (jako
extern); pri chybe cteni (SD) vsak pouze
rozsviti cerveny border.

Obe formy inline lze stridat, oddelene
carkou. Pouzijte je pro to, co jazyk
neumi; Inline je prikaz - smi stat
kdekoli, kde je dovolen prikaz: v tele i
ve funkci, i uvnitr if/while/for/switch.

FUNKCE

Vnitrni funkce se definuje az za hlavnim
telem. (Pozor: knihovny s binarnimi
externimi funkcemi se definuji na zacatku
programu).

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

Parametry a,b jsou pojmenovane a uvnitr
se pouzivaji jako lokalni promenne;
funkce smi mit i vlastni deklarace. Vola
se jako jmeno(x,y). Volani funkce se ale
nesmi vnorit do argumentu - f(g(x)) hlasi
BAD SYNTAX; pouzij mezivysledek (t=g(x);
f(t);). To plati pro funkce vlastni i
knihovni. Parametry a lokaly ziji v ramci
jednoho volani, ke kteremu kompilator
pristupuje pres registr IX, takze kazde
volani ma vlastni kopie. Funkce proto smi
volat i sama sebe (rekurze); hloubku
omezuje jen volne misto pro ramce.
Knihovni (strojove) funkce jsou jine:
zapojuji se slovem extern a ctou
argumenty podle ZPUSOB PREDAVANI
PARAMETRU v knihovni referenci.

POUZITI KNIHOVEN

Knihovna je soubor hotovych funkci.
Program si pro kompilaci nahraje, co
potrebuje, slovem extern - hned na
zacatku, pred deklaracemi a telem. 

Nahrej soubory knihovny (jmeno
v uvozovkach), skladaji se na
sebe:
     extern "basic.kcl";
     extern "zxgfx.kcl";

Uplny priklad se dvema knihovnami naraz:

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

Knihovny se musi uvest slovem extern ve
zdroji: kazda operace ANALYSE/GENERATE
zacina s prazdnou oblasti knihoven, takze
knihovna nahrana drive do dalsiho
prekladu neprezije.

C' OPROTI STANDARDNIMU C
------------------------

C' je skromne a male. Oproti K & R / ANSI
C vynechava:
- zadny preprocesor: zadne #define,
  #include,
#ifdef; #include nahrazuji knihovny pres
extern.
- zadny float ani long; jen int (16bit) a
  char
(8bit).
- zadna klicova slova unsigned / signed /
  short /
void.
- zadne struct, union, enum ani typedef.
- zadny typ ukazatel (adresa je proste
  int) - ale
unarni & (adresa) a * (dereference) primy
pristup do pameti umoznuji.
- pole jsou jen jednorozmerna.
- zadny samostatny preklad ani linker;
  kod skladas
pres knihovny extern a slucovani v
editoru.
- komentare jsou \ ... \, ne /* ... */.
- podminky nepotrebuji zavorky; for je
  'for init;
cond; krok { }' bez obalujicich zavorek;
case/default konci ';' a navesti je
'jmeno:'.
- '^' je bitovy XOR (klavesa sipka
  nahoru, SYMBOL SHIFT+H); '%N' v retezci
  PRINT je formatovani vystupu, kdezto
  samotne '%' je operator zbytku.

Vse ostatni - if/else, while, do, for,
switch, break, continue, goto, return -
ma obvykly tvar jako v C.

SROVNANI SYNTAXE (PRIKLADY)

Stejne konstrukce, jiny zapis. C'
vynechava kulate zavorky kolem podminek,
pouziva ';' jako oddelovac uvnitr 'for' a
za 'case'/'default', komentare dela '\
... \' a funkce klade az za telo
programu. Vlevo C' (KCC2), vpravo
standardni / Small C.

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 (tri vyrazy oddelene ';', bez
zavorek)
  C':      for i=1; i<=3; i=i+1 { ... }
  Small C: for (i=1; i<=3; i=i+1) { ... }

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

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

goto a navesti (shodne, navesti s
dvojteckou)
  C':      goto nav;  ...  nav:
  Small C: goto nav;  ...  nav:

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

komentare
  C':      \ toto je komentar \
  Small C: /* this is a comment */

definice funkce
  (v C' az za telem, hlavicka konci ';')
  C':  func jmeno(a,b); { ... return e; }
  SmC: jmeno(a,b) int a,b; {...return e;}

deklarace promennych (C' uvozuje
'declare')
  C':      declare int i,j; char c[30];
  Small C: int i,j; char c[30];

Pozn.: u prikazu switch/case ukonci kazdy
case slovem break;. C' sam od sebe case
neukonci, a bez break beh pokracuje do
dalsiho kodu s nejistym vysledkem.
Podrobnosti v PRIKAZY
(SWITCH, CASE, DEFAULT).

LIMITY KOMPILATORU
------------------

- promenne: v jednom rozsahu (telo nebo
  funkce)
smi byt jejich souhrnna velikost do 127
bajtu, jinak COMPILE hlasi VARS>127.
- int je 16bitovy; char a prvek pole jsou
  8bitove.
- pole maji jeden rozmer; velikost je
  nenulova
dekadicka konstanta.
- knihovny se stohuji pod program; kdyz
  se dalsi
nevejde, dostanes NO MEM.
- program (telo), jeho funkce a vsechny
  knihovny se
musi vejit spolecne pod strop (pod adresu
57700 minus knihovny zapojene pri
kompilaci).

.KCLIB - STAVBA KNIHOVEN
------------------------

.KCLIB (KC library maker) je dot command
esxDOSu pro stavbu a upravu souboru .KCL.
Spousti se z BASICu; bez argumentu vypise
napovedu. Tvary jsou:
  .KCLIB -a (new)lib[.KCL] file[.BIN]...
           pridat: prida bajty kazdeho
           souboru jako funkci (jmeno =
           jmeno souboru); knihovna se
           vytvori, je-li nova
  .KCLIB -d lib[.KCL] func func2...
           smazat jednu ci vice funkci
           podle jmena
  .KCLIB -l lib[.KCL]
           vypsat funkce a velikost
  .KCLIB -j newlib[.KCL] lib1[.KCL]...
           spojit vice knihoven do newlib
  .KCLIB -s lib[.KCL] newlib[.KCL] func
           vyclenit funkci do newlib
Hlasi spatne jmeno souboru, neznamou
volbu, plny buffer knihovny nebo
nenalezenou funkci a pred prepsani
existujici funkce se zepta.

FORMAT SOUBORU KCL
------------------

Knihovna .KCL je binarni soubor. Zacina
jedinym svym popisnym bajtem, nesoucim
pocet funkci; pak nasleduji jednotlive
funkce:

  [jmeno] 0FFh [len-lo] [len-hi] [telo]

  jmeno velka ASCII pismena, ukoncena
  znackou 0FFh len 16-bit delka tela,
  little-endian (lo, hi) telo bajty
  strojoveho kodu funkce

Funkce jsou samostatne, takze knihovnu
lze volne delit i slucovat (pomoci
dot-cmd .KCLIB) anebo prihrat vice
knihoven.

ZPUSOB PREDAVANI PARAMETRU

Argumenty se sdileji pres blok parametru.
Systemova promenna na 5CB0h drzi adresu
tohoto bloku; funkce si blok nacte
instrukci

     LD IX,(5CB0h)

Kazdy argument zabira jeden 16bitovy slot
(2 bajty, dolni bajt prvni):

     arg1 = (IX+0) dolni, (IX+1) horni
     arg2 = (IX+2) dolni, (IX+3) horni
     atd.

Posledni (nebo jediny) argument je pri
vstupu i v registru HL, takze
jednoargumentova funkce muze HL pouzit
primo, bez sahani do bloku.

VELIKOSTI HODNOT

- 16bitova hodnota: pouzije se cely slot
  (nebo HL). Funkce cte L=(IX+n),
  H=(IX+n+1). Takto jdou souradnice,
  adresy a promenne typu INT.
- 8bitova hodnota: rozhoduje jen dolni
  bajt, horni je 0. Funkce cte bajt
  instrukci LD A,(IX+n). Takto jdou
  barvy, radky, sloupce, znaky a promenne
  typu CHAR.
- retezec: predava se ADRESOU, ne
  hodnotou. Slot drzi 16bitovy ukazatel
  na prvni znak; samotny text je jinde a
  konci nulovym bajtem. PRINT bere v arg1
  adresu retezce a odtud cte znaky.

NAVRATOVA HODNOTA

Funkce, ktera neco vraci, necha vysledek
v HL. U bajtoveho vysledku je horni bajt
H nulovy, takze ho lze brat jako bajt i
jako 16bitovou hodnotu.

PROMENNY POCET ARGUMENTU

Vetsina funkci ma pevny pocet argumentu.
Vyjimkou je PRINT (1+): vzdy bere retezec
a pak tolik cisel, kolik je znacek %N, a
cte dalsi sloty arg2, arg3 ... podle
potreby.

CTENI PARAMETRU - PRIKLADY

IX se nasmeruje na blok, pak se ctou
jednotlive sloty. S arg1 16bitovym a arg2
8bitovym:

  DD2AB05C LD IX,(5CB0h) ; IX -> blok
  DD6E00 LD L,(IX+0) ; arg1 dolni
  DD6601 LD H,(IX+1) ; arg1 horni -> HL
  DD7E02 LD A,(IX+2) ; arg2 bajt  -> A
  ... ; pouzij HL a A
  C9 RET

Dva 8bitove argumenty (jako AT) - kazdy
se cte z dolniho bajtu sveho slotu:

  DD2AB05C LD IX,(5CB0h) ; IX -> blok
  DD7E00 LD A,(IX+0) ; arg1 bajt
  ... ; pouzij A
  DD7E02 LD A,(IX+2) ; arg2 bajt
  ... ; pouzij A
  C9 RET

Pri vstupu je posledni argument i v HL,
takze jednoargumentova funkce muze cist
primo HL a IX vynechat.

PRIKLADY FUNKCI: PEEK, DPEEK, POKE

Tri kompletni funkce. peek a poke jsou v
BASIC.KCL, dpeek je jejich obdoba pro
16bitovou hodnotu. Ukazuji navrat
vysledku v HL i cteni adresy z bloku
parametru.

peek(addr) - bajt z jedne bunky (0-255).
Adresa je jediny argument, takze je
rovnou v HL:

  7E LD A,(HL) ; precti bajt z adresy
  6F LD L,A ; vysledek do L
  2600 LD H,0 ; horni bajt 0 -> 0-255
  C9 RET

dpeek(addr) - slovo ze dvou sousednich
bunek (0-65535), dolni bajt napred.
Adresa je v HL:

  7E LD A,(HL) ; dolni bajt z adresy
  23 INC HL ; na adresu+1
  66 LD H,(HL) ; horni bajt z adresy+1
  6F LD L,A ; HL = hodnota 0-65535
  C9 RET

poke(addr,val) - zapis bajtu do bunky.
Dva argumenty: posledni (val) je i v HL,
adresa se cte z bloku parametru:

  7D LD A,L ; val (posledni arg) -> A
  DDE5 PUSH IX ; uschovej IX
  DD2AB05C LD IX,(5CB0h) ; IX -> blok
  DD6E00 LD L,(IX+0) ; adresa dolni
  DD6601 LD H,(IX+1) ; adresa horni -> HL
  77 LD (HL),A ; zapis val na adresu
  DDE1 POP IX ; obnov IX
  C9 RET

RELOKOVATELNOST PRELOZENEHO PROGRAMU
------------------------------------

Prelozeny program je sestaven na pevne
pocatecni adrese - adrese START: vypsane
po kompilaci - a neni volne
relokovatelny. Telo kazde knihovni funkce
je samo o sobe nezavisle na poloze: saha
pripadne jen do ROM a na blok parametru
na 5CB0h, nikdy na vlastni pevnou adresu
v RAM. Program, ktery ji vyuziva a vola,
vsak nezavisly neni.

Kompilator umisti kazde telo na zvolenou
adresu a vygeneruje na ni absolutni CALL;
vlastni skoky GOTO, volani a pristupy k
promennym jsou rovnez absolutni a vazane
na pocatek. Chces-li program spustit na
jine adrese, musis jej prelozit znovu,
starou binarku snadno nerelokujes.

MAPA PAMETI
-----------

Vyuziti pameti shora dolu (rozlozeni typu
48K):
  FFFxh vrchol kodu KCC2 E164h zacatek
  KCC2 (editor + kompilator).
         RAMTOP je nastaven pod zdroj
         (CLEAR 24999), takze BASIC i
         jeho zasobnik zustanou pod 25000
         a nesahnou na zdroj, prelozeny
         program, knihovny ani na KCC2
  pod binarni knihovny, docasne
  prihravane pro kompilaci, stohovane
  smerem dolu, jak je nahravaji
  jednotlive prikazy extern
   ... volne misto ... prelozeny program
   (prolog +
         promenne + kod), tesne nad
         zdrojem;
  START prelozena binarka = konec zdroje
  + 1 61A8h textovy buffer zdrojoveho
  kodu (25000) nahoru nize systemove
  promenne ZX, obrazovka, BASIC
RUN vstoupi do programu na jeho adrese
START:. Adresu START: prepise volba @N na
prvnim radku zdroje (viz TVAR PROGRAMU).

PEEK, POKE, CALL a INLINE vidi celou
mapu, tak prosim pri praci s nimi
opatrne, vyhybej se kodu KCC2, textovemu
bufferu a zasobniku.

CHYBOVA HLASENI
---------------

Pri chybe se ukaze chybny radek (Checking
N pri kontrole ANALYSE, Compiling N pri
prekladu GENERATE) a pod nim hlaska;
neuspech konci slovem FAILED. Cista
kontrola (ANALYSE) konci OK. Uspesny
preklad (GENERATE) konci radkem OK
<start>,<length> (pocatecni adresa a
delka prelozeneho kodu).

Hlasky maji dva tvary: chybejici prvek se
hlasi predponou "NO" + co chybi (NO ; NO
OPERAND NO NAME); ostatni chyby maji
vlastni nazev (napr. BAD SYNTAX).


Hlasky kontroly ANALYSE (syntaxe):

NO OPERAND
  Operator nema operand, vyraz je
  neuplny. Napr.: i=3+; x=*2; y=; (za
  operatorem nebo za '=' nic
  nenasleduje); prazdny vyraz tam, kde se
  ceka. Tez samotne '-' nebo '+' na
  zacatku operandu (negace se pise 0-x) a
  ++/-- na prvku pole nebo funkci v
  postfixu (pole[i]++).
NO OPERATOR
  Dva operandy bez operatoru mezi sebou.
  Napr.: i=3 4; x=a b; (hodnota nebo
  jmeno hned za jinou hodnotou bez
  operatoru).
NO ;
  Prikaz neni ukoncen strednikem. Napr.:
  chybi ';' za prirazenim, za 'return',
  za 'inline ...', nebo mezi castmi
  hlavicky 'for'.
NO {
  Ocekavala se '{' (telo) a nenasla se.
  Napr.: za if(...), else, for ...,
  while(...), do, switch(...), za
  hlavickou funkce func jmeno(...) nebo u
  tela hlavniho programu.
NO }
  Ocekavala se '}', blok zustal otevreny.
  Napr.: konec zdroje pri neuzavrenem
  bloku; chybi uzaviraci zavorka
  vnoreneho bloku.
NO SEPARATOR
  Ve vyctu chybi carka ','. Napr.:
  declare int i j; (ma byt i,j); f(a b)
  (argumenty); seznam u 'inline'.
NO FILE
  Soubor na SD karte se nepodarilo
  otevrit. U extern "lib.kcl"; (chybejici
  knihovna) uz pri ANALYSE; u inline
  "soubor"; (chybejici soubor) az pri
  COMPILE. Bud neexistuje,
  nebo ma spatny nazev/priponu.
BAD SYNTAX
  Token neni na danem miste povoleny,
  nebo je konstrukce zapsana chybne.
  Napr. prefix ++/-- na prvku pole nebo
  funkci (++pole[i], ++f()), nebo vnorene
  volani funkce v argumentu (napr.
  f(g(x))).
BAD NESTING
  Zavorky nebo bloky nejsou spravne
  vnoreny (napr. '}' bez odpovidajici
  '{', krizeni zavorek a bloku).
BAD CONTEXT
  Konstrukce je v nespravnem kontextu.
  Napr.: switch uvnitr switch (vnoreny
  switch); pole s nulovou velikosti
  (declare int t[0]).
DO w/o WHILE
  Blok do { ... } nema nasledujici
  while(...).
CASE/DEFAULT w/o SWITCH
  case nebo default je mimo telo switch.


Hlasky prekladu COMPILE (generovani
kodu):

NO NAME
  Jmeno (promenna, navesti, funkce)
  nebylo deklarovano; nebo funkce neni
  v zadne nahrane knihovne.
NO LABEL
  goto miri na navesti, ktere neexistuje.
VARS>127
  Index/odsazeni promenne presahlo 127 -
  promennych je prilis mnoho (ramec ix+d
  dosahne nad +127, radove vice nez ~64
  int promennych nebo prilis velke
  kumulativni odsazeni).
REDEFINED
  Jmeno je deklarovano vicekrat
  (duplicitni promenna, navesti nebo
  funkce).
TOO BIG
  Ciselna konstanta ve zdroji je vetsi
  nez 65535 (nevejde se do 16 bitu).
BAD TOKEN
  Neplatny token pri generovani kodu
  (token, ktery generator neumi
  zpracovat).
NO MEM
  Nedostatek pameti: prelozeny kod nebo
  knihovna se nevejde pod strop zdroje.
  Bud je program prilis velky, nebo
  knihovna nactena pres extern nema dost
  mista ve volne RAM.


Chyby souboru / operace SD:

CERVENY BORDER (bez textove hlasky)
  Chyba esxDOS pri nahrani (Load),
  ulozeni (Save), slouceni (Merge),
  ulozeni bloku (Blk), Editor rozsviti
  cerveny border, pocka na klavesu a
  vrati se zpet. Typicky chyba zapisu
  nebo SD karty.

  Cerveny border se take zobrazi pri
  cteni tela knihovny nebo pri chybe
  cteni souboru u inline "..."; (jiz
  otevrenych). Nenalezeny, chybejici
  soubor pri kompilaci hlasi NO FILE.
