Symptom:1. Parameter values that have been set to x_param cannot be stored because the function key is not set.
The function keys in the SAP DB do not work.
Cause and prerequisitesIncorrect values of DBTERM, DBHIF and TERM
SolutionWhen starting the database tools (for example, XCONTROL, x_param or XQUERY), the function keys are not allocated or the screen layout is not correct.
1. When changing parameters with XPARAM very often terminal emulators in vtXXX (for example, vt100 mode) are used. But, you have to keep in mind, that the computer function keys correspond directely to the SAP DB function keys ONLY as an EXCEPTION. Because the vt100 did NOT have function keys, they were set to the number keys of the numerical number pad (NUMKEY pad) for SAP DB by default. As a rule the first four keys of the vtxxx keyboard (GOLD, PF2 and so on) are set to the computer function keys F1 to F4 for some emulators (for example, Lan-Workplace Hostpresenter). That means that the SAP DB function key F12 is set to the computer key F3.
However, if you use the F12 key in XPARAM the effect will be as follows:
Terminate the program without a query and without saving, do not choose "back to menu".
That means for the user: He presses the computer key F3 and XPARAM terminates itself without any further notice. When you restart all the changes are gone. Two possible solution: If the terminal emulation can reset function keys with its own strings, the NUMPAD-Keystrings should be set to them. This is not possible for every emulation. Therefore, it is easier to use the Unix environment variables DBTERM, DBHIF and/or TERM and the program 'x_maketi'(or x_maketi-).
2. Every DB Release is delivered with certain terminal descriptions. If other terminals are used an individual keyboard setting can be created with SAP DB Tools 'x_maketi'.
SNI : RM400 und RM600
Terminal type : 97801
setenv TERM 97801
setenv DBTERM vt100
setenv DBHIF vt100
The function keys are on the number pad, the keys F10-F12 above the numbers.
Terminal type : BA80-08
setenv TERM ba80-08
setenv DBTERM ba80-08 DBHIF does not have to be set.
Terminal type : Ba48
setenv TERM ba48
setenv DBTERM ba48 DBHIF can be ba48
HP :
X terminals : setenv TERM hpterm
setenv DBTERM vt100_hp
setenv DBHIF vt100_hp
PC :
LAN workplace : setenv TERM vt220
setenv DBTERM vt100
setenv DBHIF vt100
The database function keys 1-9 are on the number pad, the database function keys F10 to F12 correspond to the keys F1-F3.
DEC-OSF1 : Terminal type: DEC console
setenv TERM vt300
setenv DBTERM vt320
Sun Sparc Station :
OPEN Windows : setenv TERM sun-cmd
setenv DBTERM sqldbsun
DBHIF does not have to be set.
3. Terminal adjustment and key setting
a) Description and identification of a terminal type
In order for a program to work with different terminal types, without any changes, information for terminal description and access routines are provided under UNIX.
As a rule, terminal descriptions are to be found in the directory "/usr/lib/ terminfo" (called "terminfo" in the following). The access routines are included in the library "/usr/lib/libcurses.a". The SAP DB tools use the "curses" library to access a screen or terminal control.
The environment variable "TERM" determines which description is to be used from "terminfo". On the basis of the environment variable, the description of a terminal's features can be found by the "curses" routines under "terminfo". The descriptions of various terminal types are grouped in directories under the first letter of the type name. If the usual type names are used, the directory "/usr/lib/terminfo/v" contains descriptions of the terminals types "vt100", "vt220" and so on.
The environment variable "TERMINFO" indicates where these terminal description files are to be found. If the environment variable is not set, the terminal description files stored under "terminfo" are used.
If the environment variable "TERMINFO" is set, several directory trees that contain terminal description files can exist and be shared simultaneously on a computer. The "curses" routines read this environment variable and access the appropriate terminal description.
When a user creates a private description of a terminal with type "vt100" and sets "TERMINFO" to "private/termtest/new", "curses" routines access the file "private/termtest/new/v/vt100".
b) Key settings for the SAP DB tools
To work with SAP DB tools, users need some specific keys in addition to the alphanumeric standard keys.
These are the function keys F1 - F12 and the ENTER key.
If the terminal description does not contain these keys, the tool does not start but terminates with an error message.
The tools support additional function keys to facilitate work. The most important keys are INSERT, DELETECHAR, CMD, INSERT LINE, and so on.
However, when these keys are added to the terminal descriptions, this may cause problems because the requirements of other programs are no longer met. For this reason the SAP DB tools use specific terminal descriptions:
If the environment where the SAP DB tool is running contains a "DBTERM" variable, its value is used to identify the terminal type (instead of the value of the "TERM" variable. The environment variable "DBTERM" then overrides the variable "TERM".
When users set "DBTERM" in their ".profile" file, they can use the original terminal description for the standard editor and the extended description for the SAP DB tools without any problems.
c) Changing terminal descriptions
Terminal description files are created as text files in a specific format. They are converted into a binary format using the program "tic", the terminfo compiler. (For details please refer to the operating system documentation for "terminfo" and "tic".) The "curses" routines access only compiled files.
To make it easier to create or change a terminal description for SAP DB, the tool "x_maketi" is provided.
"x_maketi" uses an existing (binary) description as a source file and changes the keyboard description part by adding or changing function key definitions. Other data describing the terminal (number of lines and columns, cursor control commands, output delay etc.) required by SAP DB remains unchanged.
After calling up "x_maketi", the user gets a list of functions. To add or change a function key, he or she has to select the function and then press the key to which this function should be assigned. The user can also delete definitions. The result is the text to be translated by the "tic" program.
You can test the original or resulting binary description using the tool "xvttest". "xvttest" shows the functions defined in the terminal description on the screen when you press the appropriate function keys.
d) Using "x_maketi"
We recommend that you use "x_maketi" in the directory "$DBROOT/terminfo". Please first read the description of the "HIF" files below, before you start working with "x_maketi"!
The syntax for calling "x_maketi" is:
x_maketi [-d] [-e] [-h] [-T ] [-I ]
[-o ]
-d : Deleting all function key definitions
-e : Explicitly ending all keys with 3 *
(for example, with remote login)
-h : Creating a keyboard file (.hif), not a terminfo
file (explanation see below)
-T : Terminal type is (neither $DBTERM nor $TERM)
-I : Using the terminfo data from as a source
-o : Using for the output file
-u : Creating a terminfo source from a binary source
"x_maketi" uses an existing binary terminfo file as a source. This file is read from the directory "$TERMINFO" or (if this environment variable is not set) from "/usr/lib/terminfo". The terminal type is taken from the environment variable ("DBTERM" or "TERM". This type is used for the name of the output file "<$TERM>.ti" unless the user specifies another type name using the option '-T' or forcibly sets another file name for the output file using the option '-o'.
If this description does not exist yet, the user has to specify a similar terminal description (except for the keyboard) as a source using the option "-I". In this case the option "-d" should also be specified to have all the function keys redefined.
If the cursor keys are not yet defined after "x_maketi" has been called, the user is prompted to first press the keys used to move the cursor. These keys are required for the following menu. This menu shows all the functions known to the SAP DB tool. The functions to which keys have already been assigned in the current keyboard description are underlined (provided this is supported by the terminal).
The cursor is on one of the functions that appear in the menu. Using the four cursor keys it can be moved up and down, to the left and to the right to point to another function. The field "Current value" shows the definition (the appropriate character sequence) for the key assigned to this function. 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 key or key combination pressed is assigned to the current function. After the assignment the system waits for 2 seconds (indicated by "WAITING" in the upper right corner of the screen).
The user can also delete a key setting by entering 'd'.
You can leave "x_maketi" by entering 'e'. A list of the current values is written to the output file.
If problems occur during the analyses of the character sequences (for example, with remote login), call up "x_maketi" with option "-e". In this case every entry must be closed by pressing the Escape key three times. If the Escape key is not available on the keyboard, its code can be generated by combining ("control") and '[' (opening bracket).
Examples:
DBTERM=dap4x x_maketi -T ba80-ct03
or
DBTERM=ba80-ct03 x_maketi -I dap4x
generates '$DBROOT/terminfo/ba80-ct03.ti' with the same characteristics
as dap4x
The new description file needs to be translated into a binary format. In order that existing descriptions are not overwritten, this new binary file should not be written to the standard directory ("/usr/lib/terminfo") but to the directory "$DBROOT/terminfo" provided by SAP DB.
When the Bourne shell is used, this can be achieved using the following command:
TERMINFO=$DBROOT/terminfo tic -v .ti
When the C shell is used, the command is as follows:
setenv TERMINFO $DBROOT/terminfo
tic -v .ti
unsetenv TERMINFO
If the user has set the environment variable "DBTERM", this new description file is used by the SAP DB tools. The value of "DBTERM" not only overrides the "TERM" value but causes the environment variable "TERMINFO" to be converted implicitly to "$DBROOT/terminfo", but only as long as the SAP DB tools are used. After the user leaves the SAP DB tool, "TERMINFO" has the previously set value.
e) Using "xvttest" terminal descriptions can be tested using the tool "xvttest". "xvttest" can be used to test the function key definitions.
The user calls "xvttest" in the environment to be used for the SAP DB tools (in particular, the variables TERM, TERMINFO and DBTERM). Different fields may be displayed with different display attributes (highlighted, blinking, reverse video, underlined). A list of function keys appears in the lower part of the screen.
The user presses the function key (described as "9=Keys"). A new screen is then generated which is used for output only. The text "pf09" appears on the screen.
The user then presses any key on the keyboard.
If this is a character (alphanumeric, punctuation etc.), this character appears on the screen (enclosed in inverted commans). If the key is a defined function key, the function appears on the screen. All other cases are indicated by an audible signal. This procedure can be used for every key that the user wants to check.
The only exception is the F3 function key, which brings the user back to the initial screen. To leave "xvttest", press F3 once more. If this key is not defined, the interrupt signal (usually CTRL-C) is the only way to leave "xvttest".
f) Incomplete terminfo and HIF files
In most of the UNIX variants the keys supported by "terminfo" and "curses" are not sufficient for comfortable handling of the SAP DB tools.
To find out which keys are not supported, define the keys using "x_maketi", compile the result file using "tic" and then call up "x_maketi" once more. "tic" does not translate the definition of a key that is not supported into binary format, i.e., the description of this key is lost after the second call of "x_maketi" (the name is no longer underlined, the value is empty).
To eliminate this restriction, the SAP DB tools support the concept of a key definition file which is independent of "terminfo".
Such a file is to be found in the directory "$DBROOT/terminfo/term" (without separator for the first character of the type name!). The file name consists of the terminal type and the addition ".hif".
"x_maketi" generates such an "HIF" file if the option '-h' was specified. Except for the following change, "x_maketi" is used as described above: Since the "HIF" files are used in the form generated by "x_maketi", "tic" is not to be used.
Whether the environment variable DBHIF must be set for the file name (without the .hif addition) depends on the name of the description file and on the environment variables DBTERM or TERM. If the environment variables DBHIF and DBTERM or DBHIF and TERM have the same content, DBHIF does not need to be set. The keyboard description file is then found automatically. Otherwise the environment variable DBHIF needs to be set.
If a keyboard description file exists, it overrides only the keyboard setting part of the files "$DBTERM" or "$TERM". All other terminal features are still read from the description files "$DBTERM" or "$TERM".
g) General recommendations
The combination of the environment variables DBHIF, DBTERM and TERM provides the user with a number of options for adjusting the terminal definition to his or her requirements.
The easiest way is to use the terminal descriptions from the distribution medium. If these files do not meet the user's requirements or another terminal type should be used, the key definitions can be adjusted using "x_maketi". The result can be tested using "xvttest" and the step can be repeated until the user is satisfied. Users can choose with which keyboard (DBHIF) and terminal description file (DBTERM or TERM) they want to work.
If unusual effects occur in this area (for example, the tool does not accept a function key that should be known to it), the read data of the TERMINFO file ("$DBROOT/terminfo" or "/usr/lib/terminfo") the "HIF" file needs to be checked first. The reason for this error probably is that an environment variable affecting the use of the description files has been added, removed or changed.
When an SAP DB tool is called up, the procedure is as follows:
The system checks whether the environment variables "DBHIF", "DBTERM" or "TERM" are set. The first value found (in this sequence) is used to create the name of an "HIF" file ("$DBROOT/terminfo/term/ .hif"). If this "HIF" is found, its content is used as the function key definition.
If "DBTERM" is set, "$DBROOT/terminfo/?/$DBTERM" is used as the terminal description file; otherwise the terminal description file "$TERMINFO/?/$TERM" or "/usr/lib/terminfo/?/$TERM" is used.
The "HIF" file (if found) now overrides the keyboard setting part of the terminal description file.
If a change in the description has no effect, you should check whether the new description file has been compiled using the "tic" program or the new "HIF" file has been copied to "$DBROOT/terminfo/term".
Additional key words
DBTERM and DBHIF