Go to the previous, next section.

Termcap -- A Terminal Database

Termcap is a Unix idea, that makes it possible to write software that runs on a wide range of different terminals. The implementation that SM uses contains no Unix source code. The idea is similar to graphcap or filecap -- each property of the terminal is given as a field in a file. For example, the string to clear to end of line is called ce, and for ansi terminals is given as ce=^[[K. The format for termcap files is described under `graphcap', which is identical. Our termcap is identical to the Unix one, so for details see section 5 of the Unix manual. The file to use as a termcap file is specified as termcap in your `.sm' file, or as the environment variable TERMCAP (logical variable to VMS). If SM can't open TERMCAP as a file, it is taken to be the value of the entry for your terminal. If it doesn't begin with a colon, it is treated like a termcap file, and searched for the desired terminal. If it does begin with a colon, it is simply taken to be the termcap entry to use. A TERMCAP variable takes precedence over an entry in your `.sm' file. As for graphcap, a list of termcap files can be specified, to be searched in order.

A full termcap entry can be pretty long, but fortunately SM only uses a small subset. (The rest are needed by full scale screen editors, but we haven't written one.) In particular we use:

ce (Clear End)
Delete to end of line
ch (Cursor Horizontal)
Move cursor within line
cm (Cursor Movement)
Move cursor around screen
cn (ColumNs)
Number of columns on screen
dc (Delete Character)
Delete character under cursor
is (InitialiSe)
Initialise terminal
ks (Keypad Start)
Initialise Keypad
ks (Keypad End)
Undo Keypad Initialisation
kd (Kursor Down)
Move cursor down one character
kl (Kursor Left)
Move cursor left one character
kr (Kursor Right)
Move cursor right one character
ku (Kursor Up)
Move cursor up one character
k1 (Key 1)
Key sequence emitted by PF1 key (also k2, k3, and k4)
li (Lines)
Number of lines on screen
pc (Pad Character)
Pad character, if not NIL
All of these are strings except co and li which expect numbers, and pc which expects a single character. The editor uses all of these except co, although the k ones are only provided as a convenience to you, mapping the arrow keys. In fact, these arrow keys may supercede desired bindings such as ^K to delete to end of line (e.g. on a televideo 912). If this happens, use the EDIT or READ EDIT commands to fix things up.

The cursor addressing strings ch and cm use a variant of the C printf %. Consider the string as a function, with a stack on which are pushed first the desired column, and then the desired line (so the line is on top). The possible % formats operate on the stack, and pop it after output.

As in printf, zero origin
Like %2d
Like %3d
Like %c
Add x to value, then `%.'
If value > x add y (no output)
Interchange line and column (no output)
Increment line and column by 1 (no output)
Output a single %
We do not support %n, %B, or %D out of pure laziness. A couple of examples might help. To go to (5,60) a vt100 expects to receive the string ^[[5;60H, so the termcap entry reads :cm=\E[%i%d;%dH:. We need the %i to go to one-indexed coordinates, and the escape is written \E. The :'s delimit the termcap entry. A Televideo 912 expects to be given first ESC=, then the coordinates as characters, where ` ' is 0, `!' is 1, and so forth through the ascii character set. To convert a given number to this form we add ` ', so the termcap entry is :cm=\E=%+ %+ :.

If an entry begins with a number, it gives the number of milliseconds of padding that the terminal requires (it is optionally followed by an *, which we can and do ignore). If the terminal requires a pad character that is not simply ascii NIL it should be given as pc, so to use `a' as a pad character specify :pc#97:. The baudrate is taken to be 9600, unless you specify it as the ttybaud variable in your `.sm' file. We have never yet seen SM have any trouble with padding, so we wouldn't worry about any of this if we were you.

You might wonder why we need both ch and cm. The simple answer is that we don't, but that we do want one of them. Because cm moves the cursor to a specific line, its use requires that SM remember which line you are on which can be tough what with switching to and from graphics mode. We therefore assume that you are on the last line of the terminal, as set by li or explicitly by the TERMTYPE command. If you provided ch this problem wouldn't arise but many terminals don't support such a capability and we have to code around this deficiency. To summarise: use ch if you can, failing that use cm.

There is a problem with using the last line of the screen as the SM command line, and this is that some terminals use the same screen for graphics as for text, and your graph will merrily scroll away as you type. The graphcap GD (Graphics Disable) command can be set to take you to the top of the screen, but cm won't keep you there. Your only chance is to disable cursor motion, either by setting ch to `disabled', or by specifying a negative screen size to TERMTYPE which has the same effect. You can still use the editor, but it'll be slower. If you still have trouble, try TERMTYPE dumb, which really is a bit brain damaged, or TERMTYPE none which disables the editor entirely.

Go to the previous, next section.