CHARWIN: Character-based Windowing API
The Terminal Capabilities Database
The core of the character windows subsystem is completely terminal independent. At the lowest level, however, it needs to know many details about the current terminal. The system must know, for example, how many lines and columns the terminal has, how to position the cursor anywhere on the screen, and whether or not the cursor should automatically wrap to the next line when it reaches the last column.
This collection of information about a terminal is referred to as the "terminal capabilities". It is stored in the ^%SYS("tercap") global and loaded to memory when a /INIT
command is issued. A terminal capabilities database contains the following items:
Terminal names and aliases (e.g., "vt220|VT220|DEC-vt220")
A set of boolean flags (e.g., has color, auto-wrap, etc.)
A set of numeric constants (e.g., lines x columns)
A set of control sequences (e.g., /cup, /el, etc.)
A border map (tells which control sequences draw the borders)
An existing terminal description may be edited and new terminal descriptions may be created using the TERCAP utility.
TERCAP is the utility for creating/editing terminal descriptions. At most of the utilities prompts, you can see a list of options by entering ?. To run this utility from the %SYS namespace, enter:
Enter a ?
(question mark) at the Option prompt to display the three options:
1 - Edit/create terminal description
2 - Edit/create border map
3 - Delete terminal description
Control sequences sent to a terminal trigger some action at the terminal, like clearing the screen or positioning the cursor at a certain coordinate. Some sequences, like /clr, contain only literals (i.e., constant codes), while others, like /cup(l,c), also contain parameters. To ease the creation and maintenance of these tables, a special syntax resembling ObjectScript was devised. Generally, a control sequence may be a literal, an expression or a function. A literal is simply a number of ASCII characters inside double quotes (such as "[H").
If necessary, a quote symbol may be duplicated to be included as a literal. An expression is a parameter (%1, %2, and so on) optionally added to a decimal constant. For different mnemonics, the parameters mean different things. For the /cup(l,c), for example, %1 represents l (the line number) and %2 is c (the column number). In /ind(n), %1 is the repeat count for the "index" operation. Examples of expressions:
%1 %1+32 %2-1
The offset added to the parameter is limited to the range [-128,127].
A function is either $C(<list of codes>) or $A(<expression>). $C is just like the ObjectScript function of the same name. It is used to indicate control characters to be sent to the terminal, such as:
$A, however, is not the same as its ObjectScript counterpart. It indicates that the enclosed <expression> should be evaluated and sent to the terminal as ASCII characters and not in binary form.
sends "A" (i.e., code 65)
sends the string "65" (i.e., codes 54, 53)
sends %1 as a sequence of ASCII characters
evaluates %2+32 and sends it as a sequence of ASCII characters
For a complete example, consider the /cup(l,c)
sequence for ANSI-like terminals:
Both parameters have 1 added to them before being sent, because their internal forms start at 0 and not at 1.