; This program makes the Commodore 64 operate like a semi-
; intelligent 40 or 80 column ASCII terminal.  It supports input
; and display of all the ASCII characters, and beeps when the BEL
; character is received.  Beware that the 80 column display mode
; will probably require a monitor unless you are using a B/W
; TV set with outstanding sharpness and video bandwidth.
;
; The communication protocol is full duplex, 8 bits, no
; parity, 1 stop bit, 300 or 1200 baud, with XON/XOFF (DC1/
; DC3) host flow control protocol -- this should satisfy most
; host computers.  The display screen is 40 columns X 25 lines
; or 80 columns X 25 lines.
;
; Because of the unusual layout of the C64 keyboard, the
; desire to support all ASCII characters, and a personal
; need to find the ESC and BS keys in their usual positions,
; the following key substitutions apply (note- ^x is short-
; hand for CONTROL-x):
;
;       TO SEND         TYPE
;       -------         ----
;       BACKSLASH       BRITISH-POUND
;       ^BACKSLASH      ^BRITISH-POUND
;       ^UNDERLINE      ^=
;       CARET           UP-ARROW
;       ^CARET          ^UP-ARROW
;       ^[ (ESC)        ^[ or BACK-ARROW
;       UNDERLINE       F1
;       VERTICAL-BAR    F2
;       GRAVE-ACCENT    F3
;       TILDE           F4
;       LEFT-BRACE      F5
;       RIGHT-BRACE     F6
;       DEL (RUB)       F7
;       ^T              F8
;       ^H (BS)         DEL, ^H, or ^T
;       ^J (NL)         SHIFT/RETURN or ^J
;       ^S (DC3)        ^S or HOME
;       ^Q (DC1)        ^Q or CURSOR DOWN
;       ^I (TAB)        ^I (ie. No separate TAB key)
;
; The CONTROL-8 key is used to switch the program from 40 column
; to 80 column mode.  The CONTROL-4 key is used to switch the
; program back from 80 column to 40 column mode.  Depressing one
; of these keys when already in the corresponding mode will simply
; clear the screen (as it does when switching modes).
;
; Note that pressing the COMMODORE key will place the terminal
; program in a suspended display mode (ie. the cursor will freeze
; at its current position), and ^S will be sent to the host
; computer when the RS-232 input buffer fills up.  Similarly,
; pressing the COMMODORE key will remove the terminal from the
; suspended display mode and send a ^Q to the host computer only
; if a ^S had previously been sent and the buffer has become nearly
; empty.  This enables the COMMODORE key to be used like the SCROLL/
; NO-SCROLL key on DEC terminals.  Suspended display mode is
; indicated to the user by the cursor blinking much faster than
; normal, an indication that the COMMODORE key must be pressed to
; resume displaying the received text.  The program may also send
; ^S and ^Q to the host computer on it's own from time to time if
; it detects an impending RS-232 buffer overflow condition - this
; normally will only occur while printing a number of short or blank
; lines while scrolling the screen up (or down), since 4 to 15 char-
; acters are received into the RS-232 buffer during the time it
; takes to scroll the whole screen.  In any case, this automatic
; flow control is fully synchronized with the flow control
; necessitated by the use of the COMMODORE key to suspend and resume
; the display of received text.  Depressing the ^S and ^Q keys (or
; their substitutes indicated above) unconditionally sends those
; ASCII characters to the remote host computer without any local
; effect.
;
; This terminal program does *not* support flow control in the
; opposite direction - receiving ^S from the host computer will not
; lock the keyboard or have any other effect, nor will ^Q.
;
; Also note that pressing the RUN/STOP key with SHIFT depres-
; sed will cleanly terminate the terminal emulator program,
; and generate the BRK interrupt to send the C64 back
; to whoever is servicing those interrupts (BASIC,
; SUPERMON64,etc).
;
; All 94 printable ASCII characters and the space will
; be displayed on the screen as received over the RS-232
; channel.  Most of the remaining (control) characters are
; not displayed- however the following control characters
; and escape sequences have special effects:
;
;       CHARACTER       EFFECT
;       ---------       ------
;       ^G (BEL)        beeps the TV
;       ^H (BS)         cursor backspaces
;       ^I (TAB)        cursor moves right to next tab stop
;       ^J (NL)         cursor moves down one line with scrolling
;       ^M (CR)         cursor moves to start of line
;       ^[A             cursor moves up one line
;       ^[B             cursor moves down
;       ^[C             cursor moves right one char.
;       ^[D             cursor moves left one char.
;       ^[H             cursor homes
;       ^[I             cursor moves up one line with scrolling
;       ^[J             clears from cursor to end of screen
;       ^[K             clears from cursor to end of line
;       ^[Ylc           cursor moves to line l-$20, col c-$20
;       ^[Z             sends DEC VT-52 terminal id string
;       ^[n             turns off reverse video
;       ^[o             turns on reverse video
;       ^[^BACKSLASH    initiates downline load
;
; Tab stops are pre-defined and fixed at every 8 columns
; beginning with column 0 (ie. 0, 8, 16, 24, ...).
;
; The rest should all be pretty much self explanatory except
; for "downline load".  Once the ^[^BACKSLASH sequence has been re-
; ceived, the program expects lines to come in over the RS-
; 232 channel of the form:
;
;       ;llhhdddddddddd...
;
; where "llhh" is the address for the first byte of data
; on the line (in 6502 low/high format), and "dddddd.."
; are the data bytes themselves - note that the address
; must be 4 hexadecimal digits and each data byte must
; be 2 hexadecimal digits.  The load is terminated normally
; by reception of the control character ^CARET, or abnormally
; if the user hits a key on the C64 keyboard during the
; load.  In the 40 column mode, It is possible to load anywhere
; in the address ranges $0800 through $9FFF and $C000 through
; $CFFF since the terminal program itself hides under the BASIC
; ROM (from $A000 through $BFFF).  80 column mode should not
; be used to download into the address range $5C00 through
; $7FFF because that is where the high resolution video matrix
; and screen image reside in that mode.
;
; VAX UNIX users (Berkeley 4.1bsd) will find that the following
; "termcap" entries effectively describe this terminal program
; for use with the terminal dependent UNIX programs (eg. vi,
; emacs, more, rogue, etc.):
;
;  qcc64C64Commodore 64:co#40:li#25:\
;          :up=\EA:do=\EB:cl=\EH\EJ:am:bs:\
;          :bw:ho=\EH:nd=\EC:so=\Eo:\
;          :se=\En:cm=\EY%+ %+ :\
;          :ce=\EK:sr=\EI:pt:
;
;  qdc64wC64WCommodore 64 80 Col X 25 Lin:co#80:li#25:\
;          :up=\EA:do=\EB:cl=\EH\EJ:bs:\
;          :bw:ho=\EH:nd=\EC:so=\Eo:\
;          :se=\En:cm=\EY%+ %+ :\
;          :ce=\EK:sr=\EI:pt:
;                                      (note: \ is BACKSLASH)
;
; VAX VMS users can probably get away with the following (although
; some VMS programs [e.g. EDT] require an auxilliary keypad, and do
; not work especially well in 40 column mode):
;
;          set term /dev=vt52
;          set term /pag=25
;          set term /wid=80  [or 40, as the case may be]
;
; TOPS-20 users can run "emacs" and the like after the following:
;
;          term vt52
;          term length 25
;          term width 80  [or 40, as the case may be]
;          term pause com
;
; A low pitched beep (much lower than that generated by
; receipt of the BEL character) indicates an error on the
; RS-232 channel (a hit, lost data, etc).
;
; Of course, this program assumes you have been able
; to connect a modem (or null modem) to the C64 user
; port, which may or may not be trivial!
;
; To run the terminal program, just load it like any BASIC
; program and RUN it.  You will be prompted for the baud
; rate.  Enter either 3 or 300 for 300 baud, 12 or 1200
; for 1200 baud, or just a carriage return for the default
; (300 baud).  If you find communications shaky or impos-
; sible at 1200 baud, you may have to change the POKE in
; basic which POKEs 0 to poke 8 instead.  If this fails to
; help, try tuning the optional baud rate constants in 0A4F
; and 0A50 for your system clock as described in ref. guide
; page 350 (use POKE of 0 into 0A4D in this case).
;
; Once it has been run, the terminal program moves itself
; under the BASIC ROM and runs there (although the original
; copy remains where it was loaded and can be re-run as long
; as it remains intact).  The memory map at run time is:
;
;       $A080-$AFFF     The program area
;       $B000-$B1FF     Unused
;       $B200-$B2FF     RS-232 output buffer
;       $B300-$B3FF     RS-232 input buffer
;       $B400-$B7FF     Video matrix (the 40 column screen)
;       $B800-$BFFF     Character set for 40 column mode
;       $02A7-$02B6     Termination/Restart code
;
; In addition, the following memory areas are used only while the
; program is in the 80 column mode:
;
;       $5C00-$5FFF     Video matrix (the 80 column color memory)
;       $6000-$7FFF     Hires screen (the 80 column screen)
;
; Once the terminal program has been terminated (with SHIFT/
; RUN/STOP), it may be re-started by re-running the original
; BASIC program.  However, if the BASIC program area has been
; over-written during downloading, the terminal program can
; still be restarted (at the same baud rate as before) with
; the BASIC direct command "SYS(686)"; this command will
; restart the terminal program at any time, even after running
; other programs, unless some program is run which pokes
; into the areas shown in the first map above.
;
; One last warning: this program is not relocatable - do
; not change the *length* of the BASIC program or nothing
; will work!
;
; Good Luck and Enjoy....
;               Frank Prindle
