Version 1.0 

Please, if you use CaTer, send a short message to LSto at gmx dot de. It's not for registration or something like that, it's just to make me happy ;-)

Installation

Setting up the C64

The C64 needs to be connected to the host system via a null modem cable. The instruction manuals for an user port RS-232 adapter you can find in the hardware section of the CaTer homepage. You can start CaTer either by loading it from floppy disk with the BASIC loader or directly from an EPROM cartridge.

To configure CaTer without recompiling it, there is the file configure.txt in the src directory. It contains addresses of ld* commands, that are useful to change with a hex editor in the binary or EPROM file or with poke commands in the BASIC loader.

_cBEL The next byte may contain $0f, which gives a buzzer when receiving the BEL char, or $81, which gives a bell sound.

_cERR The next byte has the same meaning like at _cBEL but concerns the error sound of the C=A command.

_cFontTable points to a colour table, not to a ld* command. The table contains the eight colors for vanilla, bold, underline, underline bold, blink, blink bold, underline blink and underline blink bold text.

_cBorderCol The next byte contains the border colour.

_cBgCol The next byte contains the background colour.

_cBaud The next byte contains the initial baud rate. $06 = 300, $08 = 1200, $0a = 2400, $0c = 9600

_cBgNum The next byte contains the background colour for the C=A command display.

_cColNum The next byte contains the foreground colour for the C=A command display.

Setting up the Linux host

terminfo The terminfo database may be updated system wide or for particular users only. If you perform the following steps as root, the new terminal type will be available for all users, else, it is available for yourself only. To install the cater terminal type get the file terminfo provided with CaTer and type the command tic terminfo. That's it.

termcap Some programs prefer the termcap database instead of terminfo. For those programs you can copy the termcap file to ~/.termcap, which makes the entry available for yourself only, or you append it to /etc/termcap, which makes it available system wide.

Login on serial line To get a login prompt on the serial line you have to start a getty process. This is done in /etc/inittab with the entry:

c64:23:respawn:/sbin/getty -f /etc/issue.40 -hL ttyS0 9600 cater

Afterwards you have to activate the new setting with init q.

The parameters to getty mean:

• The serial port is /dev/ttyS0 at 9600 baud.
• -h: use RTS/CTS handshake.
• -L: this is a local line, i. e. ignore the state of carrier detect.
• -f /etc/issue.40: This argument is optional and tells getty to display the file /etc/issue.40 as greeting. Usually, the default issue doesn't look well at 40 columns, so you might write a new one.

As the serial line normally has a size of 0 columns and 0 rows, we have to change these values. Otherwise some programs like ls or lynx with SLang become confused. Hence, the shell script profile.cater.sh should be called/inserted either in ~/.profile or /etc/profile

Setting up foreign hosts

If you connect to a foreign host via ssh, it knows the dimension of your screen, i.e. the width and the height, and the terminal type. To make the terminal type cater valid, you have to install the terminfo and, for old fashioned programs, the termcap database. As you normally are not root on those systems, install it for yourself only as described above.

Keyboard

Some keys got a new meaning, sometimes different from the signs printed on the key. The figure below shows the keyboard with the new meaning of the keys.

  ,---,---,---,---,---,---,---,---,---,---,---,---,---,---,---,---,
  |   | ! | " | # | $ | % | & | ' | ( | ) |   | { | } | | | o |DEL|
  |ESC| 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 0 | + | - | \ |TAB|BS |
  |---'-,-'-,-'-,-'-,-'-,-'-,-'-,-'-,-'-,-'-,-'-,-'-,-'-,-'-,-'---|
  |CTRL | Q | W | E | R | T | Y | U | I | O | P | ` | _ | ~ | RE- |
  |     |   |   |   |   |   |   |   |   |   |   | @ | * | ^ |STORE|
 ,'--,--',--',--',--',--',--',--',--',--',--',--',--',--',--'----,'
 | o |SH | A | S | D | F | G | H | J | K | L | [ | ] |   |RETURN |
 |^C |LCK|   |   |   |   |   |   |   |   |   | : | ; | = |       |
 |---+---'-,-'-,-'-,-'-,-'-,-'-,-'-,-'-,-'-,-'-,-'-,-'---+---,---|
 |   |     | Z | X | C | V | B | N | M | < | > | ? |     | ^ |<- |
 |C= |SHIFT|   |   |   |   |   |   |   | , | . | / |SHIFT| v | ->|
 '---'-----+---'---'---'---'---'---'---'---'---+---'-----'---'---'
           |                                   |
           |                                   |
           '-----------------------------------'

The o sign means, that the key has no special meaning but sends a PETSCII code. So in future it may get some meaning. These keys got a new meaning in CaTer. The function keys have no function.

Cursor Keys

The cursor movement keys send to the host the strings shown below. ESC means the ESC character.

C= Commands

With C= commands it is possible to influence the behaviour of CaTer. They are given by pressing the C= key and a special character.

C= A, ASCII Code A character can be entered by its ASCII code. The code has to be given in decimal notation with three digits and leading zeros. The number is displayed in the upper right corner of the screen. It does not affect the content of the screen and so is usable with screen orientated programs. If you enter a non digit character or a number larger than 255 the bell rings and the input is aborted. After any input of a ASCII code, no matter if successfully or not, the number stays on the screen for one second.

C= B, Baud rate This command changes the baud rate of the RS-232 line. Every occurrence of the command steps up the baud rate in the list 300 1200 2400 9600. The actual bud rate is printed to the screen.

C= C, Floppy Command With a yellow cursor the user is prompted for a floppy command. The command string entered is sent to drive 8. Afterwards, the error channel is read.

C= D, Dump Mode Enters or exits the dump mode. In the dump mode every char is printed to screen — if it is printable — followed by the ASCII code in hex notation.

C= L, List Directory The directory of the floppy disk in drive 8 is printed to screen.

C= R, Receive file via XMODEM To use this function, you should fist start the XMODEM sender on the remote host. Then you press C= R to start caters XMODEM receiver. With a yellow cursor you are asked for a file name. The file becomes opened and the error channel is read. After the transmission the file on the floppy disc becomes closed and the error channel is read. See also the XMODEM description

C= S, Send file via XMODEM With a yellow prompt the user is asked for the file to send. The named file becomes opened, the error channel is read and cater turns to normal terminal mode again waiting for the receiver to request the file. If you type C= S again, the send mode becomes aborted and the file on floppy is closed. But normally, you would instead start the XMODEM receiver on the remote machine, and the transfer begins. After the transmission the file on the floppy disc becomes closed and the error channel is read. See also the XMODEM description

XMODEM Description

During the XMODEM transfer, every correctly transmitted block is quitted with a dot (.). You can abort the transfer at any time with RUN/STOP or ^C. The successful end of the transmission is indicated by *. All indicator characters that may occur during the transfer are listed below.

Incoming Chars

The processing of incoming chars is similar to the way a vt102 terminal works. The printable ASCII codes from 32 ($20) to 126 ($7e) are printed to the screen. The table below shows all control characters interpreted by CaTer. All control characters not mentioned are ignored.

Control Characters

ISO-Latin-9 Characters

The characters from 160 ($a0) to 255 ($ff) are intended to be interpreted as ISO-latin-9 codes. ISO-latin-9 is the newer derivate from ISO-latin-1 and differs in only a few characters. The main advantage is that it contains the Euro sign "€". As there were only 33 characters left, only a few of the ISO-latin-9 characters are displayed correctly. Well, as I am from Germany, the German umlauts are displayed correctly. Furthermore the French characters should be complete. All other latin letters with "decoration" are displayed bare. Some characters are not implemented at all, they are displayed as square.

Below there is a list of all ISO-latin-9 characters. Black characters are displayed more ore less exactly, but it's not always distinguished between small and capital letters. Magenta letters are displayed without decoration and red letters are displayed as a square.

The next picture shows the new character ROM.

ESC Sequences

CaTer is able to recognise ANSI ESC commands. ESC commands are strings like

  ESC x          ESC # x
  ESC ( x        ESC [ ... a  
  ESC ) x

where ESC means the ESC character, x means any character, a means any character in {a-z,A-Z} and ... means any character string of the maximum length of 254 bytes.

All these ESC commands are ignored, i.e. they are not displayed. If the command is displayed below, it has a special meaning. The commands should have the same meaning as they have for a vt102. See http://vt100.net/docs/vt102-ug/ for further information. Some ESC sequences get numerical arguments. These have to be given as a decimal number in ASCII characters. If a given number is larger than 255 an overflow occurs which is not caught!

Scrolling Region

  ESC  [  start ; end r
  

The region between line "start" an line "end" scrolls up if the cursor hits its bottom. Initially the scrolling region starts at the first screen line, line 1, and ends at the last. The cursor can be positioned outside the scrolling region with the commands CUP and HVP. Lines outside the scrolling region never scroll. After selecting the scrolling region, the cursor moves to the home position, which is always the upper left corner of the screen.

Cursor movement Each of these commands moves the cursor n steps in the mentioned direction. If the cursor hits the right or left screen margins or the scrolling region margins, it stops. If n is zero or left away, a movement of one step is performed.

  ESC  [ line ; col H
  

  ESC  [ H
  

  ESC  [ line ; col f
  

  ESC  [ f
  

  ESC  D
  

  ESC  M
  

  ESC  E
  

  ESC  7
  

  ESC  8
  

  ESC [ a1; a2; ... ;an m
  

  vanilla (gray3)                  bold (white)
  underline (light blue)           underline bold (cyan)
  blink (green)                    blink bold (light green)
  blink underline (light red)      blink underline bold (yellow)

  ESC [ x K
  

  ESC [ x J