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 = rdchr();          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...

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

                        Note: Does any needed ACSII conversions, then calls
                        the native print character routine.

  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.

  delchr();             Delete character to left and move cursor one
                        character to the left.

                        Note: Depending on the system, this will usually
                        print one or two delete or backspace characters, and
                        possibly a space to overwite the deleted character.

  clrscn();             Clears the screen. On systems without this capability,
                        such as the Apple 1, this function should simply
                        return without performing any actions.

                        Note: Depending on the system, this will may either
                        print the clear screen control character or execute
                        the native clear screen routine.

  setpos(col,row);      Moves the cursor to the specified column and row. On
                        systems without this capability, such as the Apple 1,
                        this function should simply returns without performing
                        any actions.

  col, row = getpos();  Returns the cursor's current position. On systems
                        without this capability, such as the Apple 1,
                        this function should return the values 255, 255.

  wid, hgt = getsiz();  Returns the size of the screen in columns, and rows.
  
                        Note: This may call a system subroutine, read system
                        variables, or simply return hard-coded values.

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

  srclo, srchi       Source String Pointer
  dstlo, dsthi       Destination String Pointer
  stklo, stkhi       Stack 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)