C02/include/old/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.

For compatability with the C02 Standard Library, 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.
                      
  prchr(c);           Writes character c to the screen.
                      
                      Note: May directly access memory-mapped I/O
                      or may call a system subroutine. 

  r = getstr(&s);     Reads a maximum of 128 characters from keyboard 
                      until a carriage return is received, storing the 
                      entered characters as null-terminated string s.
                      
                      Allows corrections using Backspace/Delete. 
                      
                      Pressing the Escape/Abort key terminates entry,
                      leaving the string in an undefined state.
                      
                      Returns number of characters entered, or 255
                      if entry was aborted.

  r = outstr(n, &s):  Writes up to 128 characters of null-terminated 
                      string s to the screen, starting at position n.
                      
                      Returns position of null terminator in string.

  r = putstr(&s):     Writes up to 128 characters of null-terminated 
                      string s to the screen and advances the cursor to 
                      the beginning of the next line.
                      
                      Returns number of characters printed.
                      
                      Note: Calls putstr(0, &s) followed by newlin().

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

  strlo, strhi       String Pointer for stdio.asm and string.asm
  srclo, rcshi       Secondary String Pointer for string.asm

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

  temp0, temp1       Temporary variables used by stdlib.asm

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)