C02/doc/header.txt

System Specific Header File Specification

The very first directive of the program must be

  #include <header.h02>

where header.h02 is the system specific header file, (e.g. apple1.h02,
vic20.h02, etc.).

Note: This will probably be replaced with a command line parameter
(e.g. '-s apple1', '-s vic20', etc...) to allow program portability.

If compatibility with the C02 Standard Libraries is needed, the following
functions must be defined:

  c = plkey();        Polls keyboard and returns raw ASCII character
                      corresponding to last/current pressed key.

                      Returns constant NULKEY (usually 0) if no key was
                      pressed.

  c = rdkey();        Waits for a keypress and returns the raw ASCII
                      character corresponding to the pressed key.

                      Note: Usually a loop that calls plkey(), but may
                      also directly call a system subroutine.

  c = getkey();       Waits for a keypress and returns the cleaned
                      ASCII value corresponding to the pressed key.

                      Note: Calls rdkey() followed by any necessary
                      character code conversions. This can be due to
                      high-bit being set by keyboard decoder,
                      non-standard key mappings, keys that generate
                      escape sequences, etc...

  newlin();           Advances the cursor to the beginning of then
                      next line.

                      Note: Depending on the system, this will usually
                      output a Carriage Return, Line Feed, both.

  echo(c);            Writes character c to the screen without any
                      translation.

                      Note: May directly access memory-mapped I/O
                      or may call a system subroutine.

  prchr(c);           Writes character c to the screen.

                      Note: Does any needed ACSII conversions, then calls 
                      echo().

along with the Zero Page locations (each pair of which must be sequential)

  srclo, srchi       Spurce String Pointer
  dstlo, dsthi       Destination String Pointer

the following locations that may be Zero Page, but don't have to before

  temp0, temp1       Temporary variables used by stdlib.asm
  temp2, temp3

and the following locations that must be preserved between function calls

  random             Storage for the Random Number Generator

                     Contains the last number generated and is used to
                     generate the next number in the sequence

  rdseed             Seed for Pseudo-Random Number Generator

                     Usually a counter or timer. If one is not provided
                     by the system, should be generated by incrementing
                     in the plkey(), rdkey() functions.

and the constants

  DELKEY            ASCII code for Delete/Backspace key (usually DEL or BS)
  ESCKEY            ASCII code for Escape/Abort key (usually ESC)
  NULKEY            Returned if no Key was Pressed
  RTNKEY            ASCII code for Return/Enter key (usually CR)