The Terminfo Database

The Terminfo Database

Top  Previous  Next

 

Control sequences and other characteristics of terminal devices are defined in the terminfo database. This is normally a subdirectory structure under the QMSYS account but can be moved elsewhere if required by use of the TERMINFO configuration parameter. The structure of the terminfo database closely mimics that found as a standard component on Linux and other operating systems though QM has some private extensions to the internal library format.

 

 

Location and Structure

 

The terminfo directory contains a set of subdirectories named using the first character of the terminal types stored within them. Each of these directories then contains a file for each terminal type. Thus, for example, the definition for a vt100 terminal on a Windows system with the default QMSYS location would be found in c:\qmsys\terminfo\v\vt100.

 

The definition files are stored in an encoded form that closely reflects the way in which QM uses the data internally. QM provides a utility, qmtic, to compile or decompile terminfo entries.

 

A master source for a variety of terminals is in the QMSYS account directory as terminfo.src and the entire set of definitions is compiled when QM is installed. To simplify maintenance of a private set of new or modified terminal definitions, the QM installation process will look for a file named terminfo.mods in the QMSYS account directory and, if it exists, will compile it after the standard source, allowing new entries to be added or standard entries to be modified.

 

Linux users wishing to transfer entries from the standard Linux terminfo database to the QM terminfo database should use the Linux infocmp tool to decompile the Linux definition and then recompile it using qmtic, removing any entries that are not supported on QM.

 

 

Source Format

 

Terminfo entries contain three types of item; Booleans, numbers and strings.

 

A Boolean item is present in the terminfo entry if the feature or capability that it represents is supported by the terminal. QM currently does not make use of any of the Boolean items.

 

A number entry holds the value of an integer numeric parameter. For example, the cols item defines the normal number of columns per line.

 

A string item holds a control string. These may be codes to be sent to the terminal to perform a specific task such as clearing the screen or moving the cursor, or may be a code sent by the terminal when a specific key is pressed by the user. Strings representing commands sent to the terminal device often include parameterised information such as screen positions or counts.

 

 

A terminfo source file consists of one or more terminal definitions separated by at least one blank line. Lines commencing with a hash character (#) are comments and are totally ignored during compilation. Each definition consists of a number of comma separated items. A definition can be split over multiple lines by inserting a newline after a comma.

 

The first line of each entry contains a list of terminal types defined by that entry and a text description. For example:

vt100|vt100-am|dec vt100 (w/advanced video),

This line must not start with a space or a tab and is separated into a number of fields using the vertical bar (|) character. The last field is the text description. All preceding fields are terminal device names. Thus, the entry introduced by the line shown above defines the vt100 and vt100-am terminal types. There will be separate compiled files for each of these terminals in the final terminfo database.

 

The remaining lines of the entry must be indented by at least one space or a tab and define the characteristics of the device. Although the order is not fixed, terminfo entries normally have the Booleans first, followed by the numbers, followed by the strings.

 

A Boolean entry consists only of its name. A number consists of the name, a hash character, and the value of the parameter. A string consists of the name, an equals character (=), and the value of the parameter.

 

QM extends the terminfo source format to allow multiple strings in a single capability setting. In this case, the entire set of alternative strings for the capability are enclosed in curly brackets and the individual strings inside the brackets are separated by commas. Each comma may be followed by spaces to improve readability.

 

For example, part of the vt100 definition is:

vt100|vt100-am|dec vt100 (w/advanced video),

   am, xenl, msgr, xon,

   cols#80, it#8, lines#24, vt#3,

   bel=^G, cr=\r, csr=\E[%i%p1%d;%p2%dr, tbc=\E[3g,

   clear=\E[H\E[J$<50>, el=\E[K$<3>, ed=\E[J$<50>,

   cup=\E[%i%p1%d;%p2%dH$<5>, cud1=\n, home=\E[H,

   kmous={\E[101~, \E[111~}

 

String tokens may contain the following special character sequences:

\bBackspace (char 8)
\eEscape (char 27)
\fFormfeed (char 12)
\lLinefeed (char 10)
\nLinefeed (char 10)
\rCarriage return (char 13)
\sSpace (char 32)
\tTab (char 9)
\^Caret (^)
\\Backslash (\)
^xCtrl-x (chars 0 - 31)
%xParameter action as described below
%%Percent sign (%)
$<n>Insert an n millisecond delay. This code is ignored by QM, removing it from the final string.

 

 

The %x parameter notation performs run time manipulation of the character string, often inserting parameter values. These operations use a stack for intermediate results and are described in terms of their C programming language equivalents:

 

%cpop top stack item and print it as a character (like %c in printf())
%dpop top stack item and print it as an integer (like %d in printf())
%spop top stack item and print it as a string (like %s in printf())
%[[:]flags][width[.precision]][doxXs]
as in printf, flags are [-+#] and space. The ':' is used to avoid making %+ or %- patterns (see below).
%p[1-9]push ith parm
%P[a-z]set dynamic variable [a-z] from top stack item
%g[a-z]get dynamic variable [a-z] and push it onto stack
%P[A-Z]set static variable [A-Z] from top stack item
%g[A-Z]get static variable [A-Z] and push it onto stack
%lreplace topmost stack item with its string length
%'c'push char constant c
%{nn}push integer constant nn
%+replace top two stack items with their sum
%-replace top two stack items with their difference
%*replace top two stack items with their product
%/replace top two stack items with their quotient
%mreplace top two stack items with the remainder from division
%&replace top two stack items with their logical AND
%|replace top two stack items with their logical OR
%^replace top two stack items with their logical exclusive OR
%=replace top two stack items with the result of an equality test
%>replace top two stack items with the result of a greater than test
%<replace top two stack items with the result of a less than test
%A %Ological and & or operations for conditionals
%!replace top stack item with its logical inverse
%~replace top stack item with its bitwise inverse
%iadd 1 to first two parms (for ANSI terminals)

%? expr %t thenpart %e elsepart %;

if-then-else, %e elsepart is optional.

 

For those of the above operators which are binary and not commutative, the stack works in the usual way, with

%gx %gy %m

resulting in x mod y, not the reverse.

 

 

For example, the QMBasic @(col,row) function translates to the cup (cursor position) terminfo entry. For the vt100 definition shown above this is

cup=\E[%i%p1%d;%p2%dH$<5>

Taking this apart, element by element for a usage as @(10,5):

\EEscape character
[[ character
%iIncrement both arguments to allow for positions numbered from 1 rather than 0. The argument values 10 and 5 thus become 11 and 6.
%p1Push parameter 1 (11) onto the stack
%dPrint top item from stack as an integer
;; character
%p2Push parameter 2 (6) onto the stack
%dPrint top item from stack as an integer
HH character
$<5>Delay - Ignored by QM.

 

The end result is thus "Esc[11;6H".

 

 

 

Mouse Protocols

 
The "mouse" numeric token defines the protocol used by the terminal when sending a mouse click. Values are:

1QMTerm
2PDA
3AccuTerm ASCII format
4XTERM old format (Anzio)
5AccuTerm ANSI format

 

The associated "kmous" token defines the prefix that identifies a mouse click. The "mouse-on" and "mouse-off" tokens define the codes to enable and disable the mouse.

 

 

 

Colour Mapping

 

Different terminal emulators use variations on the numeric values used to represent colours (see the QMBasic @(-37) and @(-38) functions). To enable users to employ a consistent set of colour values in application programs whilst working with different terminal emulators, the terminfo definition may include an optional element named colourmap (British spelling) that provides a translation between internal colour values and the actual colour number transmitted to the terminal. The format of this entry is

colourmap=0|1|2|3|7|5|6|4|8|9|10|11|12|13|14|15

where the elements correspond to internal colour values zero upwards and the number in each element is the colour value to be sent to the terminal. In this example, colours 4 and 7 have been swapped.

 

Colours for which the value is not to be changed may be left blank and trailing unchanged values may be omitted. Thus, the above example could be shortened to

colourmap=||||7|||4

 

 

User Definable Entries

 

The terminfo database includes 10 entries (u0 to u9) for user use. QM pre-defines the function of two of these, the remaining eight are available for any purpose that the user wishes.

u0 - u7

@(-100) to @(-107)

 

Undefined. Users may adopt these for any purpose.

u8

@(-108)

IT$ACMD

Asynchronous command execution prefix. This code prefixes a command to be executed on the client system followed by a newline. The QM session is not suspended while the command is executed.

u9

@(-109)

IT$SCMD

Synchronous command execution prefix. This code prefixes a command to be executed on the client system followed by a newline. The QM session is suspended while the command is executed.

 

The u8 code is used internally by some parts of QM. The remaining codes will only be used as defined in user written application software.

 

 

 

AccuTerm Extensions

 

The AccuTerm terminal emulator includes support for additional special functions that are not part of the terminal definitions for industry standard terminal types. These extra functions include

Client side command execution (synchronous and asynchronous)

Screen region save and restore (used by the QMBasic debugger)

Mouse click detection

 

QM ships with extended definitions for some devices using terminal type names with a -at suffix (e.g. vt100-at). Users can easily add similar extensions to other terminal definitions. If the host type in AccuTerm is set to QM, the correct extended terminal type should be selected automatically for direct network connections to QM.