This document covers the following topics:
To let a program use different terminals without modification, information about the terminal description and access routines are provided under Unix / Linux.
The terminal descriptions are usually stored in the directory "/usr/lib/terminfo", in the following referred to as "terminfo". The access routines are stored in the library "/usr/lib/libcurses.a". The Adabas D tools use the "curses" library for addressing the screen or terminal.
The applicable description in "terminfo" is identified by the environment variable "TERM". The value of this environment variable enables the "curses" routines to find for the currently used terminal the corresponding description of its properties under "terminfo". The descriptions of different terminal types are grouped in directories according to the first character of the type name, so with the usual type names, the directory "/usr/lib/terminfo/v" would contain the descriptions of "vt100", "vt200" terminals, etc.
Usually, the system will know from the environment variable "TERMINFO" where these terminal description files can be found. If this environment variable is not set, the terminal description files located under "terminfo" will be used.
As the environment variable "TERMINFO" is reset, it is possible to have and use various directory trees containing terminal description files on the same computer. The "curses" routines read this environment variable and access the corresponding terminal description.
If a user creates a private description of a terminal type "vt100", setting "TERMINFO" to "/private/termtest/new", then the "curses" routines access the file "/private/termtest/new/v/vt100".
Detailed information about "curses" and "terminfo" can be found in the respective system manuals.
To use the tools of Adabas D, the user needs some special keys in addition to the standard alphanumeric keys. These keys are the function keys F1, F2, ... up to F12 and ENTER; if the terminal description does not contain these keys, the tools will not start but terminate voluntarily with an error message.
For comfortable operation, the tools support additional function keys; the most important are: INSERT CHAR, DELETE CHAR, CMD, INSERT LINE, DELETE LINE, DELETE TO EOL.
As the addition of these keys to terminal descriptions might collide with the requirements of other programs, Adabas D supports a concept of terminal descriptions adequate for the Adabas D tools:
If the environment of a running Adabas D tool contains a variable "DBTERM" its value replaces that of "TERM" for the terminal type identification. The environment variable "DBTERM" overrides the environment variable "TERM".
If a user sets "DBTERM" in his ".profile" file, he can use the original terminal description for the normal editor and an enhanced description for the Adabas D tools without any further intervention. This enhanced description can use the same type name because the existence of "DBTERM" implicitly sets the environment variable "TERMINFO" to "$DBROOT/terminfo" for the Adabas D tools .
Whenever "terminal type" is used in the following description or in the manuals of the Adabas D tools, it means the value of the "DBTERM" environment variable or, if that is not set, the value of the "TERM" environment variable.
The distribution medium contains descriptions for frequently used terminal types: for the Digital Equipment terminals VT 100 ("vt100") and VT 200 ("vt220"). The keyboard layouts for "vt100", "vt200", and other terminals are provided in the User Manual Unix and Linux.
Terminal description files are created as plaintext files in a special format which is then compiled into binary by the program "tic", the terminfo compiler. (Details can be found in the respective operating system manuals on "terminfo" and "tic".) The "curses" routines only access compiled files.
To ease the creation (or modification) of a terminal description for use by Adabas D, a special tool "x_maketi" is provided.
This tool takes an existing (binary) description as source file and modifies the keyboard description part by interactively adding or changing definitions of function keys: the other data describing the terminal (number of rows and columns, cursor control commands, timing delays etc.) required by Adabas D are not modified.
After calling "x_maketi", a list of functions is displayed. Adding a function key or changing the function of a function key is done by selecting the function and pressing the key this function is to be assigned to. The user can also erase definitions. The result is a plaintext description to be translated by means of the program "tic".
The (original or resulting) (binary) description can be checked by the tool "xvttest" which displays the functions defined in the terminal description for the pressed keys.
It is recommended to use "x_maketi" in the directory "$DBROOT/terminfo".
See the description of "HIF" files later on before using "x_maketi".
The tool has the following call syntax:
x_maketi [-d] [-e] [-h] [-T <TERM>] [-I <ITERM>] [-o <filename>]
-d : deleting all function key definitions -e : explicitly terminating all keys by 3 * <ESC> (e.g., with remote login) -h : creating a keyboard file (.hif) only, not a terminfo file (explained later) -T : terminal type described is <TERM> (not $DBTERM or $TERM) -I : using terminfo data for <ITERM> as source -o : using <filename> for the output file -u : generating a terminfo source from a binary source
"x_maketi" uses an existing binary terminfo file as start data, this is taken from the tree rooted at the "$TERMINFO" value or, if that environment variable is not set, at "/usr/lib/terminfo". The terminal type is taken from the environment variable ("DBTERM" or "TERM"). This type is used for the output file name "<$TERM>.ti" if the user does not get another type name by the option "-T" or force another file name by the option "-o".
If the description does not yet exist the user must give the option "-I" to use some similar terminal description as input. In this case, the "-d" option should also be given to force a complete redefinition of all function keys.
If after calling "x_maketi" the cursor keys have not yet been defined, the user is asked to press the keys which serve to move the cursor. These keys are needed to navigate in the following menu. The tool displays a menu containing the names of all function keys which are known by the Adabas D tools; those keys for which the current terminal description contains a definition are underlined (if supported by the terminal).
The cursor is on a function displayed in the menu and can be moved up and down, left and right by the four cursor keys to point to any other function. For the key so addressed, its definition (corresponding character sequence) is shown in the field "current value". When the user presses a function key or a combination of function keys on the keyboard, the character sequence sent by the terminal is displayed and the pressed key or combination of keys is assigned to the current function. After the assignment, the tool waits two seconds, which is indicated by "WAITING" displayed in the right upper corner of the screen.
But the user can also delete the assignment of a key by entering "d".
"x_maketi" is terminated by entering "e". This causes the list of presently current values to be written to the output file.
If there are problems with the analysis of the character sequences (possible especially with remote login) "x_maketi" should be called with the "-e" option. In this case, every input must be terminated by pressing the escape key three times. That key is labeled ESC; if it is missing on the keyboard the code can also be generated by the combination of CTRL ("control") and "[" (opening square bracket).
DBTERM=dap4x x_maketi -T ba80-ct03 or DBTERM=ba80-ct03 x_maketi -I dap4x generates '$DBROOT/terminfo/ba80-ct03.ti' with the same properties as the dap4x.
The resulting description file must then be compiled into a binary format. To protect the existing descriptions, the new binary file should not be written to the default tree (rooted at "/usr/lib/terminfo") but to the directory provided by Adabas D, "$DBROOT/terminfo".
Using the Bourne shell, this is done by entering
TERMINFO=$DBROOT/terminfo tic -v <TERM>.ti
Using the C shell, the command sequence is:
setenv TERMINFO $DBROOT/terminfo tic -v <TERM>.ti unsetenv TERMINFO
This new description file will be used by the Adabas D tools if the user provides the environment variable "DBTERM": not only does its value override that of "TERM", its existence also implicitly sets the environment variable "TERMINFO" to "$DBROOT/terminfo", but only while working with Adabas D. After leaving an Adabas D tool, "TERMINFO" again has the previously set value.
Terminal descriptions can be tested by means of the tool "xvttest". Its most common use is for checking the function key definitions.
The user simply calls "xvttest" in the same environment as would be used for the Adabas D tools (especially, the variables TERM, TERMINFO, and DBTERM). The tool displays several fields, possibly with different display attributes (bright, blinking, underlined, inverted), and a list of function keys at the bottom of the screen.
The user presses the function key F9 (described as "9=Keys"), and a new screen is displayed which only serves for output. In the output part of this screen appears the text "pf09".
The user now presses any key on the keyboard. If this is a single character (alphanumeric, punctuation, etc.) this character is echoed (enclosed in single quotes) on the screen. If this is a defined function key its function is echoed on the screen. For all other keys, the terminal beeps. This is repeated for any key the user wants to check.
The (only) exception is the F3 function key which returns the user to the entrance menu. Pressing F3 again terminates "xvttest". If this key is not defined the only exit is the interrupt signal (usually CTRL-C ).
For most Unix / Linux variants, the keys supported by "terminfo" and "curses" are not sufficient for a (convenient) use of the Adabas D tools.
One way of detecting which keys are not supported is to define these keys using "x_maketi", to compile the result by means of "tic", and then to call "x_maketi" again. If a key is not supported, "tic" does not transform its definition to a binary format, so it will be lost on the second call of "x_maketi" (the name is not underlined any more, the value is empty).
To exceed this limitation, the tools of Adabas D support the concept of a key definition file separate from "terminfo". These files are located in the directory "$DBROOT/terminfo/term" (without the separation for the first character of the type name!), the file name is the terminal type with the addition of ".hif".
"x_maketi" will create such a "HIF" file if it is given the "-h" option. The use of "x_maketi" remains as described above with the following change: as these "HIF" files are used in the form they are created by "x_maketi", there is no call of "tic".
Whether the environment variable DBHIF must be set to the filename (without the extension ".hif"), depends on the name of the description file and on the environment variable DBTERM or TERM: if the environment variables DBHIF and DBTERM or DBHIF and TERM have the same contents DBHIF need not be set. The keyboard description file will then automatically be found. If their contents are different the environment variable DBHIF has to be set (see Section Setting Optional Environment Variables).
If there is a keyboard description file it only overrides the keyboard layouts of the files "$DBTERM" or "$TERM". All the other features of the terminal are still read from the description file "$DBTERM" or "$TERM".
Combining the environment variables DBHIF, DBTERM, and TERM gives the user a wide range of possibilities to adapt the terminal definition to his need and taste. The easiest way is to use the terminal descriptions from the distribution medium. If these files do not suit the user's need or taste, or if some other terminal type is to be used the key definitions can be adapted by means of "x_maketi". The result can be tested using "xvttest" and the step can be repeated until the user is satisfied. The user can choose the keyboard (DBHIF) and the terminal description file (DBTERM or TERM) he wants to work with.
Whenever there are strange effects in this area (like the tool not accepting a function key which should be known), the first thing to check is the usage date of the "TERMINFO" file ("$DBROOT/terminfo" or "/usr/lib/terminfo") and of the "HIF" file, if needed. The most likely error is the addition, removal, or change of an environment variable that influences the use of these description files.
For the call of an Adabas D tool, the following procedure is used:
-The environment is searched for the variables "DBHIF", "DBTERM", and "TERM". With the first value found (in that order), the name of a "HIF" file is constructed ("$DBROOT/terminfo/term/<TYPE>.hif"). If such a file is found its contents is taken as the function key definitions.
-If "DBTERM" is set "$DBROOT/terminfo/?/$DBTERM" is taken as terminal description file; otherwise, according to the standard, the terminal description file "/usr/lib/terminfo/?/$TERM" is used.
-In case a "HIF" file has been found, it only overrides the keyboard part of the terminal description file.
If a description change has no effect, it should be checked whether the new description file has been compiled by means of the program "tic" and whether the new "HIF" file has been copied to "$DBROOT/terminfo/term".