=========================================
   BASIC.KCL
   FUNCTION LIBRARY FOR KAMASOFT C'
=========================================

The library is loaded in the compilation
phase (ExT, G) to the upper part of
memory. A function is used by declaring
the library once with extern "basic.kcl";
and each function with extern NAME();
then it is called like an ordinary
function.

FUNCTION LIST
-------------------------

name     bytes  input  output
-------  -----  -----  ------
AT          20      2       0
ATTR        25      2       1
BEEP        19      2       0
BORDER      18      1       0
BRIGHT      25      1       0
CALL         1      1       1
CLS          3      0       0
DPEEK        5      1       1
DPOKE       24      2       0
FLASH       24      1       0
FRAMES       4      0       1
GETKEY      17      0       1
IN           8      1       1
INK         23      1       0
INKEY       13      0       1
INPUT      108      2       1
INVERSE     19      1       0
OUT         18      2       0
OVER        17      1       0
PAPER       26      1       0
PAUSE       10      1       0
PEEK         5      1       1
POKE        17      2       0
PRINT       88     1+       0
SCROLL      12      1       0

Note: PRINT takes a variable input (a
format plus 0 to N values).

PARAMETER PASSING
--------------------------
- the last (or only) argument is in
register HL
- all arguments are also in the parameter
block
  pointed to by the system variable 5CB0h
 Each argument takes 2 bytes:
     arg1 = ((5CB0))+0 and +1
     arg2 = ((5CB0))+2 and +3   etc.
- the return value (for functions that
return
  one) is in register HL (the high byte H
  is
  zero for byte results)

=========================================
 AT - set print position
=========================================

INPUT : 2 - arg1 row (0-23), arg2 column
(0-31)
OUTPUT: 0

Sends the AT control code (22) followed
by the coordinates. Use it before
printing.

USAGE:
  extern "basic.kcl";
  {
  at(10,5); print("HELLO");
  }

MACHINE CODE (20 B):
  +0   DDE5      PUSH IX
  +2   DD2AB05C  LD IX,(5CB0h)
  +6   3E16      LD A,16h
       ; AT code (22)
  +8   D7        RST 10h
  +9   DD7E00    LD A,(IX+0)   ; row
  +12  D7        RST 10h
  +13  DD7E02    LD A,(IX+2)   ; column
  +16  D7        RST 10h
  +17  DDE1      POP IX
  +19  C9        RET

=========================================
 ATTR - cell attribute
=========================================

INPUT : 2 - arg1 row (0-23), arg2 column
(0-31)
OUTPUT: 1 - attribute byte of the cell
(0-255)

Returns the attribute byte of the
character cell at the given row and
column (address 5800h + row*32 + column).
Bits: 0-2 INK, 3-5 PAPER, 6 BRIGHT, 7
FLASH. Equivalent to BASIC's ATTR.

USAGE:
  extern "basic.kcl";
  c = attr(0,0);

MACHINE CODE (25 B):
  +0   55        LD D,L   ; column -> D
  +1   2AB05C    LD HL,(5CB0h)
       ; param block
  +4   7E        LD A,(HL)   ; row
  +5   6F        LD L,A
  +6   2600      LD H,0
  +8   29        ADD HL,HL   ; row*2
  +9   29        ADD HL,HL
  +10  29        ADD HL,HL
  +11  29        ADD HL,HL
  +12  29        ADD HL,HL   ; row*32
  +13  7C        LD A,H
  +14  C658      ADD A,58h   ; base 5800h
  +16  67        LD H,A
  +17  7D        LD A,L
  +18  82        ADD A,D   ; + column
  +19  6F        LD L,A
  +20  7E        LD A,(HL)
       ; read attribute
  +21  6F        LD L,A   ; return in HL
  +22  2600      LD H,0
  +24  C9        RET

=========================================
 BEEP - tone sound
=========================================

INPUT : 2 - arg1 pitch, arg2 number of
cycles
OUTPUT: 0

Produces a tone via the ROM BEEPER
routine (03B5h). arg1 is the pitch time
constant (larger = lower tone), arg2 is
the number of wave cycles (duration). The
routine disables interrupts itself and
reads BORDCR for the border. Relation to
frequency f (Hz): arg1 = 437500/f - 30,
arg2 = f*time.

USAGE:
  extern "basic.kcl";
  beep(200,400);   /* short tone */

MACHINE CODE (19 B):
  +0   EB        EX DE,HL
       ; cycles -> DE
  +1   DDE5      PUSH IX
  +3   DD2AB05C  LD IX,(5CB0h)
       ; param block
  +7   DD6E00    LD L,(IX+0)
       ; pitch -> HL
  +10  DD6601    LD H,(IX+1)
  +13  CDB503    CALL 03B5h
       ; ROM BEEPER
  +16  DDE1      POP IX
  +18  C9        RET

=========================================
 BORDER - set border colour
=========================================

INPUT : 1  - border colour (0-7)
OUTPUT: 0

Sets the border colour. It does an OUT to
port 254 (FEh) so the colour shows at
once, and also stores the attribute into
the system variable BORDCR (5C48h) so the
lower screen uses it and it stays set.
The lower-line ink is set for contrast
(white for a dark border). Same as the
ROM BORDER command.

USAGE:
  extern "basic.kcl";
  {
  border(1);    /* blue border */
  }

MACHINE CODE (18 B):
  +0   7D        LD A,L
       ; A = colour 0-7
  +1   E607      AND 7   ; 0-7
  +3   D3FE      OUT (0FEh),A
       ; port 254 = border
  +5   07        RLCA
       ; colour*8 -> paper
  +6   07        RLCA
  +7   07        RLCA
  +8   CB6F      BIT 5,A
       ; light border?
  +10  2002      JR NZ,+14
  +12  EE07      XOR 7
       ; dark -> white ink
  +14  32485C    LD (5C48h),A   ; BORDCR
  +17  C9        RET

=========================================
 BRIGHT - set brightness
=========================================

INPUT : 1 - 0 = normal, 1 = bright colour
OUTPUT: 0

Sets the BRIGHT attribute (bit 6). With 1
the bit is set, with 0 it is cleared, in
both variables ATTR_P (5C8Dh) and ATTR_T
(5C8Fh). Other bits are left unchanged.
Takes effect on the next print.

USAGE:
  extern "basic.kcl";
  {
  bright(1); cls(); /* bright colours */
  }

MACHINE CODE (25 B):
  +0   7D        LD A,L   ; A = 0/1
  +1   E601      AND 1   ; bit 0 only
  +3   0F        RRCA   ; bit 0 -> bit 6
  +4   0F        RRCA
  +5   4F        LD C,A
  +6   FD7E53    LD A,(IY+53h)
       ; ATTR_P (5C8Dh)
  +9   E6BF      AND 0BFh
       ; keep other bits
  +11  B1        OR C
  +12  FD7753    LD (IY+53h),A
  +15  FD7E55    LD A,(IY+55h)
       ; ATTR_T (5C8Fh)
  +18  E6BF      AND 0BFh
  +20  B1        OR C
  +21  FD7755    LD (IY+55h),A
  +24  C9        RET

=========================================
 CALL - jump to machine code
=========================================

INPUT : 1  - routine address (HL)
OUTPUT: 1 - whatever the routine returns
in HL

Jumps to the given address (JP (HL)). The
called routine must return with RET and
leave the return value in HL.

USAGE:
  extern "basic.kcl";
  {
  call(32); /* run the routine at address
  32 */
  }

MACHINE CODE (1 B):
  +0   E9        JP (HL)

=========================================
 CLS - clear screen
=========================================

INPUT : 0
OUTPUT: 0

Clears the screen (jumps to the ROM
routine 0D6Bh).

USAGE:
  extern "basic.kcl";
  {
  cls();
  }

MACHINE CODE (3 B):
  +0   C36B0D    JP 0D6Bh   ; ROM CLS

=========================================
 DPEEK - read a 16-bit word from memory
=========================================

INPUT : 1  - address (HL)
OUTPUT: 1  - word at that address (HL)

Reads a 16-bit value from the given
address, low byte first (little-endian):
low byte from the address, high byte from
address+1. Like a double PEEK and the
counterpart to DPOKE - reads back an
address or a number 0-65535 stored as a
word in one call. The same value could be
built from two PEEKs as
peek(a)+256*peek(a+1), but this is
shorter and faster.

USAGE:
  declare int w;
  extern "basic.kcl";
  {
  w=dpeek(40000); /* w = word at
  40000/40001 */
  }

MACHINE CODE (5 B):
  +0   7E        LD A,(HL)
       ; addr in HL -> A = low byte
  +1   23        INC HL
  +2   66        LD H,(HL)
       ; H = high byte
  +3   6F        LD L,A
       ; HL = 16-bit word (little-endian)
  +4   C9        RET

=========================================
 DPOKE - store a 16-bit word to memory
=========================================

INPUT : 2 - arg1 address, arg2 value
(0-65535)
OUTPUT: 0

Stores a 16-bit value at the given
address, low byte first (little-endian):
low byte at the address, high byte at
address+1. Like a double POKE - handy for
storing an address or a number 0-65535 in
one call.

USAGE:
  extern "basic.kcl";
  {
  dpoke(40000,12345); /* 40000=low,
  40001=high */
  }

MACHINE CODE (24 B):
  +0   DDE5      PUSH IX
  +2   DD2AB05C  LD IX,(5CB0h)
       ; param block
  +6   DD6E00    LD L,(IX+0)
       ; address - low
  +9   DD6601    LD H,(IX+1)
       ; address - high
  +12  DD4E02    LD C,(IX+2)
       ; value - low
  +15  DD4603    LD B,(IX+3)
       ; value - high
  +18  DDE1      POP IX
  +20  71        LD (HL),C
       ; store low byte
  +21  23        INC HL
  +22  70        LD (HL),B
       ; store high byte
  +23  C9        RET

=========================================
 FLASH - set flash
=========================================

INPUT : 1  - 0 = off, 1 = flashing
OUTPUT: 0

Sets the FLASH attribute (bit 7). With 1
the bit is set, with 0 cleared, in both
ATTR_P (5C8Dh) and ATTR_T (5C8Fh). Other
bits stay unchanged. Takes effect on the
next print.

USAGE:
  extern "basic.kcl";
  {
  flash(1); print("FLASHES");
  }

MACHINE CODE (24 B):
  +0   7D        LD A,L   ; A = 0/1
  +1   E601      AND 1   ; bit 0 only
  +3   0F        RRCA   ; bit 0 -> bit 7
  +4   4F        LD C,A
  +5   FD7E53    LD A,(IY+53h)
       ; ATTR_P (5C8Dh)
  +8   E67F      AND 7Fh
       ; keep other bits
  +10  B1        OR C
  +11  FD7753    LD (IY+53h),A
  +14  FD7E55    LD A,(IY+55h)
       ; ATTR_T (5C8Fh)
  +17  E67F      AND 7Fh
  +19  B1        OR C
  +20  FD7755    LD (IY+55h),A
  +23  C9        RET

=========================================
 FRAMES - frame counter
=========================================

INPUT : 0
OUTPUT: 1 - low 16 bits of the FRAMES
counter (HL)

Returns the low two bytes of the system
FRAMES counter (5C78h), which the ROM
increments 50 times a second (every
frame). Typical uses: measuring a short
interval - subtract two reads and the
difference is the number of frames
between them, so divide by 50 for
seconds; timing delays or frame-synced
animation; or a quick pseudo-random seed,
as the low byte changes fastest. The full
counter is 3 bytes (5C78h-5C7Ah); this
function reads only the low word
(0-65535), so it wraps after about 21 min
51 s. A difference of two reads is still
correct across one wrap as long as the
real interval is shorter than that.

USAGE:
  declare int t0,dt;
  extern "basic.kcl";
  {
  t0=frames();
  /* ... something happens ... */
  dt=frames()-t0;   /* elapsed frames */
  }

MACHINE CODE (4 B):
  +0   2A785C    LD HL,(5C78h)
       ; FRAMES counter (low word)
  +3   C9        RET

=========================================
 GETKEY - wait for a key
=========================================

INPUT : 0
OUTPUT: 1  - key code (HL)

Waits until a key is pressed and returns
its code (the same codes as INKEY and
INKEY$). Unlike INKEY it first clears the
new-key flag and blocks until a fresh
press, so it is the usual press-any-key
primitive. It uses the ROM keyboard
interrupt (the LAST_K system variable at
5C08h), so interrupts must be enabled, as
they are in normal operation. To wait for
one particular key, loop on it, e.g.
while (getkey()!='Y');

USAGE:
  declare int k;
  extern "basic.kcl";
  {
  k=getkey();          /* any key */
  while(getkey()!='Y');  /* wait Y */
  }

MACHINE CODE (17 B):
  +0   FDCB01AE   RES 5,(IY+1)
       ; clear "new key" flag first
  +4   FDCB016E   BIT 5,(IY+1)
       ; FLAGS bit 5 : key ready ?
  +8   28FA       JR Z,+4
       ; no -> keep waiting
  +10  3A085C     LD A,(5C08h)
       ; LAST_K = decoded key code
  +13  6F         LD L,A
  +14  2600       LD H,0
  +16  C9         RET   ; HL = key code

=========================================
 IN - read a hardware port
=========================================

INPUT : 1  - arg1 port (0-65535)
OUTPUT: 1  - value read (0-255)

Reads a byte from a 16-bit hardware port.
The full 16-bit port goes on the bus
(high byte on A8-A15) via IN A,(C), so
address-decoded ports can be read too
(e.g. keyboard FEFEh-7FFEh).

USAGE:
  extern "basic.kcl";
  i = in(32765);

MACHINE CODE (8 B):

  +0   44        LD B,H   ; port -> BC
  +1   4D        LD C,L
  +2   ED78      IN A,(C)   ; read port
  +4   6F        LD L,A   ; return in HL
  +5   2600      LD H,0
  +7   C9        RET

=========================================
 INK - set foreground colour
=========================================

INPUT : 1  - INK colour (0-7)
OUTPUT: 0

Sets the foreground colour (INK). Writes
bits 0-2 into both attribute variables
ATTR_P (5C8Dh) and ATTR_T (5C8Fh); PAPER,
BRIGHT and FLASH stay unchanged. Takes
effect on the next print.

USAGE:
  extern "basic.kcl";
  {
  ink(2); cls();    /* red foreground */
  }

MACHINE CODE (23 B):
  +0   7D        LD A,L
       ; A = colour 0-7
  +1   E607      AND 7   ; INK bits (0-2)
  +3   4F        LD C,A
  +4   FD7E53    LD A,(IY+53h)
       ; ATTR_P (5C8Dh)
  +7   E6F8      AND 0F8h
       ; keep other bits
  +9   B1        OR C
  +10  FD7753    LD (IY+53h),A
  +13  FD7E55    LD A,(IY+55h)
       ; ATTR_T (5C8Fh)
  +16  E6F8      AND 0F8h
  +18  B1        OR C
  +19  FD7755    LD (IY+55h),A
  +22  C9        RET

=========================================
 INKEY - read the keyboard
=========================================

INPUT : 0
OUTPUT: 1 - key code, or 32 when nothing
(HL)

USAGE:
  declare int k;
  extern "basic.kcl";
  {
  k=inkey();
  }

MACHINE CODE (13 B):

  +0   FDCB016E  BIT 5,(IY+1)
       ; FLAGS - new key
  +4   212000    LD HL,0020h
       ; default 32
  +7   C8        RET Z   ; no key -> 32
  +8   3A085C    LD A,(5C08h)   ; LAST_K
  +11  6F        LD L,A
  +12  C9        RET

=========================================
 INPUT - read a line from the keyboard
=========================================

INPUT : 2 - arg1 buffer address, arg2
size
OUTPUT: 1  - length of the line (HL)

Reads a line of text from the keyboard
into your buffer, echoing each key. ENTER
ends the line; DELETE rubs out the last
character. At most size-1 characters are
stored - you own the buffer, so make it
at least the wanted length plus one for
the trailing zero; once it is full the
extra keys are ignored. The text is
always 0-terminated and the return value
is its length, so an empty line gives 0.
There is no prompt - print one yourself
first. Like GETKEY it uses the ROM
keyboard interrupt, so interrupts must be
enabled. Pair it with ATOI to read a
number.

USAGE:
  extern "basic.kcl";
  declare char nm[15];
  declare int n;
  print("Name? ");
  n=input(nm,15);  /* max 14 */
  /* read a number: */
  declare char b[6];
  print("N? "); input(b,6); n=atoi(b);

MACHINE CODE (108 B):
  +0   DDE5       PUSH IX   ; save IX
  +2   DD2AB05C   LD IX,(5CB0h)
       ; param block
  +6   DD5E00     LD E,(IX)
       ; buf -> DE (write ptr)
  +9   DD5601     LD D,(IX+1)
  +12  DD6E02     LD L,(IX+2)
       ; max -> HL
  +15  DD6603     LD H,(IX+3)
  +18  DDE1       POP IX
  +20  7C         LD A,H
       ; maxchars = min(max-1,255)
  +21  B7         OR A
  +22  2007       JR NZ,+31
  +24  7D         LD A,L
  +25  B7         OR A
  +26  2805       JR Z,+33
  +28  3D         DEC A
  +29  1802       JR +33
  +31  3EFF       LD A,FFh
  +33  4F         LD C,A   ; C = maxchars
  +34  0600       LD B,0   ; B = count
  +36  FDCB01AE   RES 5,(IY+1)
       ; wait for a key (FLAGS bit 5)
  +40  FDCB016E   BIT 5,(IY+1)
  +44  28FA       JR Z,+40
  +46  3A085C     LD A,(5C08h)
       ; A = LAST_K
  +49  FE0D       CP 13   ; ENTER ?
  +51  2831       JR Z,+102
  +53  FE0C       CP 12   ; DELETE ?
  +55  2818       JR Z,+81
  +57  FE20       CP 20h
       ; below space -> ignore
  +59  38E7       JR C,+36
  +61  FE80       CP 80h
       ; graphics/token -> ignore
  +63  30E3       JR NC,+36
  +65  6F         LD L,A
  +66  78         LD A,B
  +67  B9         CP C
       ; count < maxchars ?
  +68  30DE       JR NC,+36
  +70  7D         LD A,L
  +71  12         LD (DE),A
       ; store char
  +72  13         INC DE
  +73  04         INC B
  +74  C5         PUSH BC
  +75  D5         PUSH DE
  +76  D7         RST 10h
       ; echo it (ROM print)
  +77  D1         POP DE
  +78  C1         POP BC
  +79  18D3       JR +36
  +81  78         LD A,B
       ; nothing to delete ?
  +82  B7         OR A
  +83  28CF       JR Z,+36
  +85  05         DEC B
  +86  1B         DEC DE
  +87  C5         PUSH BC
  +88  D5         PUSH DE
  +89  3E08       LD A,8
       ; screen erase: left, space, left
  +91  D7         RST 10h
  +92  3E20       LD A,20h
  +94  D7         RST 10h
  +95  3E08       LD A,8
  +97  D7         RST 10h
  +98  D1         POP DE
  +99  C1         POP BC
  +100 18BE       JR +36
  +102 AF         XOR A
  +103 12         LD (DE),A
       ; 0-terminate
  +104 68         LD L,B   ; HL = length
  +105 2600       LD H,0
  +107 C9         RET

=========================================
 INVERSE - inverse mode
=========================================

INPUT : 1  - arg1 flag (0 or 1)
OUTPUT: 0

Turns INVERSE mode on (1) or off (0) in
P_FLAG (bits 2 and 3). Affects PRINT and
PLOT/DRAW/CIRCLE - with INVERSE 1
drawing/printing is inverted (points are
erased instead of drawn). Sets both the
temporary and permanent bit, like
INK/PAPER.

USAGE:
  extern "basic.kcl";
  inverse(1);

MACHINE CODE (19 B):
  +0   7D        LD A,L   ; flag
  +1   E601      AND 1
  +3   4F        LD C,A
  +4   87        ADD A,A
  +5   B1        OR C   ; flag*3
  +6   87        ADD A,A
  +7   87        ADD A,A   ; flag*12
  +8   4F        LD C,A   ; mask 0/0Ch
  +9   3A915C    LD A,(5C91h)   ; P_FLAG
  +12  E6F3      AND 0F3h
       ; clear bits 2,3
  +14  B1        OR C
  +15  32915C    LD (5C91h),A
  +18  C9        RET

=========================================
 OUT - write a hardware port
=========================================

INPUT : 2 - arg1 port (0-65535), arg2
value
OUTPUT: 0

Writes a byte to a 16-bit hardware port.
The full 16-bit port goes on the bus
(high byte on A8-A15) via OUT (C),A. Like
POKE but for ports.

USAGE:
  extern "basic.kcl";
  out(254,2);   /* border colour */

MACHINE CODE (18 B):
  +0   7D        LD A,L   ; value -> A
  +1   DDE5      PUSH IX
  +3   DD2AB05C  LD IX,(5CB0h)
       ; param block
  +7   DD4E00    LD C,(IX+0)   ; port lo
  +10  DD4601    LD B,(IX+1)   ; port hi
  +13  ED79      OUT (C),A
       ; write to port
  +15  DDE1      POP IX
  +17  C9        RET

=========================================
 OVER - over (pixel merge) mode
=========================================

INPUT : 1  - arg1 flag (0 or 1)
OUTPUT: 0

Turns OVER mode on (1) or off (0) in
P_FLAG (bits 0 and 1). Affects PRINT and
PLOT/DRAW/CIRCLE - PLOT-SUB reads P_FLAG,
so with OVER 1 points are merged (XOR)
with the existing content. Sets both the
temporary and permanent bit, like
INK/PAPER.

USAGE:
  extern "basic.kcl";
  over(1);

MACHINE CODE (17 B):
  +0   7D        LD A,L   ; flag
  +1   E601      AND 1
  +3   4F        LD C,A
  +4   87        ADD A,A
  +5   B1        OR C   ; flag*3
  +6   4F        LD C,A   ; mask 0/3
  +7   3A915C    LD A,(5C91h)   ; P_FLAG
  +10  E6FC      AND 0FCh
       ; clear bits 0,1
  +12  B1        OR C
  +13  32915C    LD (5C91h),A
  +16  C9        RET

=========================================
 PAPER - set background colour
=========================================

INPUT : 1  - PAPER colour (0-7)
OUTPUT: 0

Sets the background colour (PAPER).
Writes bits 3-5 into both attribute
variables ATTR_P (5C8Dh) and ATTR_T
(5C8Fh); INK, BRIGHT and FLASH stay
unchanged. Takes effect on the next
print.

USAGE:
  extern "basic.kcl";
  {
  paper(1); cls(); /* blue background */
  }

MACHINE CODE (26 B):
  +0   7D        LD A,L
       ; A = colour 0-7
  +1   E607      AND 7
  +3   07        RLCA
       ; shift into PAPER field
  +4   07        RLCA
  +5   07        RLCA
  +6   4F        LD C,A
  +7   FD7E53    LD A,(IY+53h)
       ; ATTR_P (5C8Dh)
  +10  E6C7      AND 0C7h
       ; keep other bits
  +12  B1        OR C
  +13  FD7753    LD (IY+53h),A
  +16  FD7E55    LD A,(IY+55h)
       ; ATTR_T (5C8Fh)
  +19  E6C7      AND 0C7h
  +21  B1        OR C
  +22  FD7755    LD (IY+55h),A
  +25  C9        RET

=========================================
 PAUSE - pause
=========================================

INPUT : 1 - number of frames (1/50 s); 0
= until a key
OUTPUT: 0

Waits the given number of 1/50-second
frames, or until a key is pressed; 0
means wait until a key. It uses the ROM
PAUSE routine (entered at 1F3Dh with the
count already in BC). First it clears bit
5 of FLAGS so that a key left over from
earlier does not end the pause straight
away, then enables interrupts. The wait
counts the 50 Hz frame interrupt, so if
the caller had left interrupts off the
HALT inside the ROM loop would wait for
an interrupt that never comes and the
program would hang. With them on the
pause cannot dead-lock and a key press
still ends it early.

USAGE:
  extern "basic.kcl";
  {
  pause(50);    /* about 1 second */
  }

MACHINE CODE (10 B):
  +0    E5        PUSH HL
       ; BC = frames (0 = until key)
  +1    C1        POP BC
  +2    FDCB01AE  RES 5,(IY+1)
       ; clear stale new-key flag
  +6    FB        EI
       ; frames need interrupts on
  +7    C33D1F    JP 1F3Dh ; ROM PAUSE-1


=========================================
 PEEK - read a byte from memory
=========================================

INPUT : 1  - address (HL)
OUTPUT: 1 - byte at that address (HL,
H=0)

USAGE:
  declare int b;
  extern "basic.kcl";
  {
  b=peek(40000); /* b = byte at address
  40000 */
  }

MACHINE CODE (5 B):
  +0   7E        LD A,(HL)
       ; A = byte at address
  +1   6F        LD L,A   ; into result
  +2   2600      LD H,0   ; high byte 0
  +4   C9        RET

=========================================
 POKE - store a byte to memory
=========================================

INPUT : 2 - arg1 address, arg2 value (low
byte)
OUTPUT: 0

The address is taken from the parameter
block, the value from L (the low byte of
the last argument).

USAGE:
  extern "basic.kcl";
  {
  poke(16384,255); /* store 255 at 16384
  */
  }

MACHINE CODE (17 B):
  +0   7D        LD A,L   ; A = value
  +1   DDE5      PUSH IX
  +3   DD2AB05C  LD IX,(5CB0h)
       ; param block
  +7   DD6E00    LD L,(IX+0)
       ; address - low
  +10  DD6601    LD H,(IX+1)
       ; address - high
  +13  77        LD (HL),A   ; store
  +14  DDE1      POP IX
  +16  C9        RET

=========================================
 PRINT - print text and values
=========================================

INPUT : 1+ - arg1 = string (format)
address,
              then 0 to N numbers for the
              %N markers
OUTPUT: 0

The first parameter is always a STRING in
quotes; it is printed character by
character. The compiler adds the trailing
zero itself - so "A%N" is stored as four
bytes A, '%', 'N', 0 (you do not write
that 0 in the source).

Control sequences inside the string:
  %N the next number from the parameters
  is inserted here
  \N   new line
  \T tab to the next column (like a
  comma)
  \B   move the cursor one character back
  %%   prints a single '%' character

After the string, give as many numbers as
there are %N markers in it: the first %N
takes the first number, the second the
second, and so on. With no %N, give no
numbers.

USAGE:
  declare int a,b,score;
  extern "basic.kcl";
  {
  print("HELLO"); /* text only */
  print("COUNT = %N",10); /* COUNT = 10
  */
  a=7; b=12;
  print("%N + %N",a,b); /* 7 + 12 */
  print("LINE 1\NLINE 2"); /* two lines
  */
  print("A\TB\TC"); /* columns A B C */
  score=2500;
  print("SCORE:\N%N",score); /* SCORE:
  then 2500 */
  print("DONE 100%%"); /* DONE 100% */
  }

MACHINE CODE (88 B):
  +0   DDE5      PUSH IX
  +2   DD2AB05C  LD IX,(5CB0h)
  +6   DD6E00    LD L,(IX+0)
       ; string address
  +9   DD6601    LD H,(IX+1)
  +12  7E        LD A,(HL)   ; char loop
  +13  A7        AND A
  +14  280C      JR Z,+28   ; end on 0
  +16  FE25      CP 25h   ; '%'
  +18  2827      JR Z,+59
  +20  FE5C      CP 5Ch   ; '\'
  +22  280A      JR Z,+34
  +24  D7        RST 10h   ; print char
  +25  23        INC HL
  +26  18F0      JR -16   ; next char
  +28  DDE1      POP IX
  +30  C9        RET
  +31  78        LD A,B
       ; (escape) literal
  +32  18F6      JR -8
  +34  23        INC HL
  +35  7E        LD A,(HL)
  +36  CBAF      RES 5,A   ; uppercase
  +38  0608      LD B,8
  +40  FE42      CP 42h   ; 'B'
  +42  28F3      JR Z,+31
  +44  FE4E      CP 4Eh   ; 'N'
  +46  060D      LD B,13
  +48  28ED      JR Z,+31
  +50  0606      LD B,6
  +52  FE54      CP 54h   ; 'T'
  +54  28E7      JR Z,+31
  +56  7E        LD A,(HL)
  +57  18DD      JR -35
  +59  23        INC HL   ; format %?
  +60  7E        LD A,(HL)
  +61  CBAF      RES 5,A
  +63  FE4E      CP 4Eh   ; 'N' = number
  +65  20F5      JR NZ,+56
  +67  E5        PUSH HL
  +68  DD23      INC IX   ; next argument
  +70  DD23      INC IX
  +72  DD4E00    LD C,(IX+0)
  +75  DD4601    LD B,(IX+1)
  +78  CD2B2D    CALL 2D2Bh
       ; ROM STACK-BC
  +81  CDE32D    CALL 2DE3h
       ; ROM PRINT-FP
  +84  E1        POP HL
  +85  23        INC HL
  +86  18B4      JR -76
       ; back to loop (+12)

=========================================
 SCROLL - scroll the screen up
=========================================

INPUT : 1  - arg1 number of lines (0-255)
OUTPUT: 0

Scrolls the whole screen up by arg1
character lines using the ROM routine
CL_SC_ALL (0DFEh), calling it arg1 times.
The freed bottom lines are filled with
paper.

USAGE:
  extern "basic.kcl";
  scroll(1);

MACHINE CODE (12 B):
  +0   7D        LD A,L   ; line count
  +1   A7        AND A
  +2   C8        RET Z   ; n=0 -> end
  +3   47        LD B,A
  +4   C5        PUSH BC
  +5   CDFE0D    CALL 0DFEh
       ; ROM scroll
  +8   C1        POP BC
  +9   10F9      DJNZ -7   ; next line
  +11  C9        RET

=========================================
 End

