Terminal Definition Files

From Recital Documentation Wiki
Jump to: navigation, search


Terminal Definition Files are used by Recital to configure screen and keyboard behavior within Recital for the user's current terminal or terminal emulator. The following sections examine the contents of a Terminal Definition File and explain how to modify them for individual terminal and application requirements.


Recitalprovides its own Terminal Definition Files, so that it can be run on a wide variety of different terminals. The Terminal Definition Files are stored in the directory indicated by the DB_TERMDIR environment variable, set in the system-wide configuration file. By default this is set to the 'terminals' sub-directory of the Recital home directory. Some one hundred Terminal Definition Files are shipped with Recital. These files are text files and have a '.def' file extension on a base name of the terminal type, e.g. ansi.def, vt220.def. When Recital is invoked, it checks to see whether the environment variable, DB_TERM, has been set, e.g.

$ DB_TERM=vt220; export DB_TERM

If the DB_TERM environment variable is not set, Recital takes its setting from your Linux/UNIX TERM.

$ TERM=vt220; export TERM


Note that if the DB_TERM is set to xterm or similar (or if DB_TERM is not set and TERM is xterm or similar), Recital will be fired up in an xterm window (or equivalent):

DB_TERM Window Command
aixterm aixterm
konsole xterm
gnome-console xterm
xterm xterm
dtterm xterm
xterm-color xterm
scoterm scoterm
hpterm xterm
sun-cmd shelltool
sun shelltool

When running with an xterm TERM in a non-windowing environment, DB_TERM must be set to an appropriate value, e.g. vt220, ansi, putty.

GETENV() Function

To determine the value of an Environment Variable using Recital, use the GETENV() function:

> ? getenv([TERM])
> ? getenv([DB_TERM])


The SET TERMINAL TO <terminal type> can also be used to set the terminal type from within Recital, but this is normally only used for testing purposes.


Terminal Definition File contents

Since the Terminal Definition Files are text files, they can be altered manually if required. If your particular terminal is not represented by a pre-built file, choose one that is similar, and then alter it to fit. Each Terminal Definition File consists of a series of numbers with an associated value or control sequence, covering such aspects of terminal behavior as the following:

Entry Terminal Behavior Example File
1 Clear Screen \E[2J ansi.def
4 Select concurrent screen and printer port \E[?5i vt220.def
5 Select printer port only \E[5i vt220.def
6 Turn off printer port \E[4i\E[?4i vt220.def
150 F1 key sequence \E[11~ xterm.def
175 Foreground color - black \E[30m putty.def
208 ESC key delay in tenths of a second \002 ansi.def
220 Enable / disable 25 rows \001 ansi.def

Terminal Definition File sections

Section Contents
1 Identification
2 Terminal Output Definitions
3 Map of Function Keys to Internal Control Keys
4 Function Key Labels
5 Map of Control Keys in Menus to Function Key Labels
6 Miscellaneous Items
7 Keyboard Input Driver Map
8 Foreground Colors
9 Background Colors
10 Secondary Miscellaneous Items
11 Secondary Display Section
12 Terminal Initialization Section
13 Tertiary Miscellaneous Items

Terminal Definition File entries

Each section contains entries in the form:

<entry>=<value> # comments

An entry is a decimal number that performs a specific function for Recital. A value is a string sequence, decimal value, or logical value that is assigned to the specified entry. String values are escape sequences that may contain the following controls:

Control Description
\E Escape
\n Carriage return or line feed
\\ A '\'
\ddd A 3 digit octal number
\xddd A 3 digit hexadecimal number
\Dddd A 3 digit decimal number
\t A tab
\b A backspace
\f A form feed
\s A space
\: A colon
\, A comma
\^ A caret
^c A control character where 'c' is in the range a-z
\001 True flag (exceptions to this are noted as appropriate)

Lines beginning with a ! are comment lines. Any entries that do not exist in a definition file, or that have been commented are set to a Recital default value.

Creating your own Recital Terminal Definition Files

If you have a terminal that is not supported by one of Recital's terminal definition files, you may create your own. This is done by copying an existing Terminal Definition File and changing the <values> for the Recital <entry> functions. You can find some of the escape sequences needed for the RECITAL Terminal Definition File from the termcap or terminfo file on Linux/UNIX systems. The following charts show the relationship between Recital <entry> numbers, and the <values> which may be obtained from termcap or terminfo files.

Terminal Output Definitions

Termdef # Termcap Entry Terminfo Entry Description
1 cl clear Clear screen
2 cs csr Scrolling region
3 cm cup Cursor position
7 sc sc Save terminal state
8 rc rc Restore terminal state
9 ce el Clear to end of line
10 cd ed Clear to end of screen
11 us smul Underline on
12 ue rmul Underline off
14 as smacs Select graphics mode
15 ae rmacs Select ASCII mode
28 so rev Reverse on
29 se rmso Reverse off
30 md bold Bold on
31 me sgr0 Bold off
33 mb blink Blink on
34 is is2 Terminal initialization
35 ve cnorm Cursor normal
36 vi civis Cursor invisible
37 rs rs2 Terminal reset

Keyboard Input Driver Map

Termdef # Termcap Entry Terminfo Entry Description
150 k1 kf1 F1 Function key
151 k2 kf2 F2 Function key
152 k3 kf3 F3 Function key
153 k4 kf4 F4 Function key
154 k5 kf5 F5 Function key
155 k6 kf6 F6 Function key
156 k7 kf7 F7 Function key
157 k8 kf8 F8 Function key
158 k9 kf9 F9 Function key
159 k; kf10 F10 Function key
162 kh khome Home key

Section 1. Identification

This section describes the terminal definition and any special terminal set up characteristics. This section contains comments only.

!** Terminal definition: Putty terminal with SCO keyboard + SHIFT and CRTL    **

Section 2. Terminal Output Definitions

This section defines the output escape sequences needed to drive the terminal display. Manuals that define escape sequences used for character output, printer handling, etc., are usually shipped with terminals. Entries 2 and 3 are the only non-standard ones in this section. The first two bytes denote the order of the row and column parameters: \001 indicates row and \002 indicates column. The %d is the standard C language printf() style formatting. The %d will put the number itself into the escape sequence. Use %c to put the character represented by the number into the escape code. The printf() formatting is as follows:

Code Description
%d A decimal number
%o An octal number
%x A hexadecimal number
%u An unsigned decimal
%c A character
%s A null terminated string

Some terminals require a value to be added to the row and column values for scrolling and cursor positioning. This should be specified in entry 145. The following escape sequences are example terminal output definitions:

<Entry>=<Value> Comment
1=\E[2j # Clear the screen
2=\001\002\E[%d;%dr # Set scrolling region
3=\001\002\E[%d;%dH # Cursor position
4=\E[?5i # Select concurrent screen and printer port
5=\E[5i # Select printer port only
6=\E[4i\E[?4i # Turn off printer port
7=\E7 # Save terminal state
8=\E8 # Restore terminal state
9=\E[K # Clear to end of line
10=\E[J # Clear to end of screen
11=\E[4m # Underline on
12=\E[=0E\E[m # Select normal attribute mode
13=\E(0\170\E(B # Graphics vertical bar
14=\E(0 # Select graphics mode
15=\E(B # Select ASCII mode (turn off graphics mode)
16=\313 # Lines top 'T'
17=\316 # Lines crossing '+'
18=\312 # Lines bottom 'T'
19=\314 # Lines left vertical 'T'
20=\271 # Lines right vertical 'T'
21=\311 # Lines top left corner
22=\273 # Lines top right corner
23=\310 # Lines bottom left corner
24=\274 # Lines bottom right corner
25=\315 # Lines horizontal line character
26=\272 # Lines vertical line character
27=\333 # 'Hatch' character for windows
28=\E[7m # Reverse video on
29=\E[0m # Reverse video off
30=\E[1m # Bold on
31=\E[0m # Bold off
32=\E> # Select keypad mode
33=\E[5m # Blink on
34=\E[=0E\E[?71 # Initialization
35=\E[=11;12C # Cursor normal
36=\E[14;12C # Cursor invisible
37=\E[?7h # Terminal close (reset)

Entries 4/5/6: printing

Entries 4,5 and 6 are used by the local printing commands SET DEVICE TO PRINT, SET CONSOLE OFF and SET DEVICE TO SCREEN respectively.

Entry 27: 'hatch'

This graphics character is most visible as the background character in the Recital Information Center.

Entry 32: keypad mode

Entry number 32 controls whether the keypad is in application or numeric mode. In the example above, the setting is \E= for application mode, and \E> for numeric mode.

This setting can also be changed from within Recital Terminal Developer at the developer prompt or in applications by issuing the following sequence:

// Set keypad to application mode
set screenmap off
?? chr(27) + "="
set screenmap on


// Set keypad to numeric mode
set screenmap off
?? chr(27) + ">"
set screenmap on


Section 3. Map of Function Keys To Internal Control Keys

This section should not need to be modified. This section defines the mapping between the logical keypad keys and the control keys. The ANSI/Enhanced column shows the typical ANSI or DEC Enhanced Keyboard Key that performs the control sequence. Recital will perform the function listed whenever the control key specified is received.

Control key values can be remapped to function keys by specifying escape sequences in the keyboard section. Entries in the keyboard section can be cross-referenced to the control map section via the logical key. Entry numbers 66 to 75 are internal codes for keyboard macros.

The following table illustrates the typical mapping of function keys to internal control keys.

Control Key Logical Key Entry Map(ANSI/Enhanced) Function
38=^c [0] 150 ANSI [HELP]
39=^a [1] 151 ANSI [WORD LEFT]
40=^f [2] 152 ANSI [WORD RIGHT]
41=^t [3] 153 ANSI [UPDATE MODE]
42=^u [4] 154 ANSI [DELETE FIELD]
43=^z [5] 155 ANSI [PAN LEFT]
44=^b [6] 156 ANSI [PAN RIGHT]
45=^y [7] 157 ANSI [REMOVE]
46=^k [8] 158 ANSI [FIND]
47=^l [9] 159 ANSI [FIND NEXT]
48=^g [-] 160 ANSI [ABANDON]
49=^d [,] 161 ANSI [REFRESH]
50=^q [.] 162 ANSI [MENU BAR]
51=^v [Enter] 163 ANSI [EDIT FIELD]
52=^w [PF1] 164 ANSI [EXIT/SAVE]
53=^r [PF2] 165 ANSI [PAGE UP]
54=^n [PF3] 166 ANSI [PAGE DOWN]
55=^s [PF4] 167 ANSI --RESERVED--
56= [F1] --- ENH --RESERVED--
57= [F2] --- ENH --RESERVED--
58= [F3] --- ENH --RESERVED--
59= [F4] --- ENH --RESERVED--
60= [F5] --- ENH --RESERVED--
61= [F6] --- ENH --RESERVED--
62= [F7] --- ENH --RESERVED--
63= [F8] N\A ENH --RESERVED--
64=^b [F9] N\A ENH --RESERVED--
65=^z [F10] N\A ENH --RESERVED--
66=^g [F11] N\A ENH [ABANDON]
67=^h [F12] N\A ENH [BACKSPACE]
68=^a [F13] N\A ENH [UP CURSOR]
69=^f [F14] N\A ENH [DOWN CURSOR]
70=^c [F15] N\A ENH [HELP]
71=^q [F16] N\A ENH [MENU BAR]
72=^t [F17] N\A ENH [UPDATE MODE]
73=^d [F18] N\A ENH [REFRESH]
74=^u [F19] N\A ENH [DELETE FIELD]
75=^w [F20] N\A ENH [EXIT/SAVE]

See also: Function Keys

Section 4. Function Key Labels

This section defines the function key labels associated with ANSI keypad keys and control keys. The Recital command SET FUNCTION uses these assignments for re-mapping of the function keys outside standard Recital worksurfaces. (i.e. F5 will still delete a field in the MODIFY STRUCTURE worksurface). These labels appear in list status. The following is a list of typical function key labels:

<Entry>=<Value> Function Key Label
76=F1 Function key label [0]
77=F2 Function key label [1]
78=F3 Function key label [2]
79=F4 Function key label [3]
80=F5 Function key label [4]
81=F6 Function key label [5]
82=F7 Function key label [6]
83=F8 Function key label [7]
84=F9 Function key label [8]
85=F10 Function key label [9]
86= Function key label [-]
87= Function key label [,]
88= Function key label [.]
89= Function key label [Enter]
90= Function key label [PF1]
91= Function key label [PF2]
92= Function key label [PF3]
93= Function key label [PF4]
94=[Hold] Function key label [Hold]
95=[Print] Function key label [Print]
96=[Set-Up] Function key label [Set-Up]
97=[Data\Talk] Function key label [Data\Talk]
98=[Break] Function key label [Break]
99=[F6] Function key label [F6]
100=[F7] Function key label [F7]
101=[F8] Function key label [F8]
102=[F9] Function key label [F9]
103=[F10] Function key label [F10]
104=[F11] Function key label [F11](ESC)
105=[F12] Function key label [F12](BS)
106=[F13] Function key label [F13]
107=[F14] Function key label [F14]
108=[F15] Function key label [F15]
109=[F16] Function key label [F16]
110=[F17] Function key label [F17]
111=[F18] Function key label [F18]
112=[F19] Function key label [F19]
113=[F20] Function key label [F20]

Section 5. Map Of Control Keys In Menus To Function Key Labels

This section defines mapping between control keys and their labels on the keyboard. The values associated with an entry are displayed in Recital key help menus. Key help menus display in Recital default work surfaces, such as BROWSE and EDIT, to show users which keys perform which functions. In our example below, the ^g character, or ABANDON function, is performed by the [ESC] key, and the [esc] key will display in the key help menu. The following example lists typical control key-to-key label mapping:

Displayed String Key Function
114=\^ ^a [UP CURSOR]
115=\F7 ^b [PAN RIGHT]
116=F1 ^c [HELP]
117=F12 ^d [REFRESH]
118=<- ^e [LEFT CURSOR]
119=\040v ^f [DOWN CURSOR]
120=Esc ^g [ABANDON]
121=F2 ^h [BACKSPACE]
122=Home ^i [TAB]
123=F3 ^j [RIGHT CURSOR]
124=F9 ^k [FIND]
125=F10 ^l [FIND NEXT]
!126= ^m -- NOT USED --
127=PgDn ^n [PAGE DOWN]
!128= ^o -- NOT USED --
!129= ^p -- NOT USED --
130=Home ^q [MENU BAR]
131=PgUp ^r [PAGE UP]
!132= ^s -- NOT USED --
133=F4 ^t [UPDATE MODE]
134=F5 ^u [DELETE FIELD]
135=Ins ^v [EDIT FIELD]
136=End ^w [EXIT/SAVE]
137=-> ^x [RIGHT CURSOR]
138=F8 ^y [REMOVE]
139=F6 ^z [PAN LEFT]

Section 6. Miscellaneous items

This section defines miscellaneous entries. The functions of the entries are listed in the comments.

Entry Comment
140=\001 # \001 if a workstation environment
141=\001 # \001 if a BS-> DEL mapping required
142=\001 # \001 if a bordered window required
143=\001 # \001 if keyboard translation required
144=\001 # \001 to disable SET PCKEYS offsetting of codes
145=\001 # Offset to be added to cursor addresses
146=\001 # \001 if LF->CR mapping required
147=\001 # \001 if terminal cannot combine reverse and bold
148=\001 # \001 if cursor does not display correctly in menus
149=\001 # \001 if underline should be used for shading

Section 7. Keyboard Input Driver Map

This section defines the mapping between the physical keyboard keys and their logical ANSI keypad equivalents. This section is used by Recital to interpret escape codes sent by the keyboard. In this example termdef file Recital equates the escape sequence \E[M to the F1 key. The control map section in Section 3 defines the equivalent control key to be used when F1 is interpreted (^c). This can be cross-referenced with the entry number listed.

These codes are standard for all OpenVMS systems and should not be changed.

Pressing the appropriate function key at the UNIX prompt and then pressing return displays the UNIX operating system function key codes. The escape sequence will be echoed back to the terminal. Under the bash shell on Linux, the read command will display escape codes rather than interpret them or if you enter Ctrl-v the shell will display the escape code for the key stroke following Ctrl-v rather than interpreting it.

Most UNIX/Linux systems will display ^[ for the escape character. Replace that character sequence with \E in the termdef files. For example, if the F1 key is pressed at the UNIX prompt, a ^[M is shown (for an ANSI standard terminal). This value should be placed at entry 150 (F1) in the termdef file.

Entries 168 to 171 map control key sequences sent by a terminal into Recital control keys that are interpreted as cursor key inputs. If a control value is specified here that remapping takes precedence over default functionality. For example, if a terminal sends a ^j when the down cursor is pressed entry #169 can be set to ^j. Whenever Recital receives a ^j it will react as if the down cursor was pressed.

Sequence Received Physical Key Entry Function
150=\E[M [F1] 38 [HELP]
151=\E[N [F2] 39 [WORD LEFT]
152=\E[O [F3] 40 [WORD RIGHT]
153=\E[P [F4] 41 [UPDATE MODE]
154=\E[Q [F5] 42 [DELETE FIELD]
155=\E[R [F6] 43 [PAN LEFT]
156=\E[S [F7] 44 [PAN RIGHT]
157=\E[T [F8] 45 [REMOVE]
158=\E[U [F9] 46 [FIND]
159=\E[V [F10] 47 [FIND NEXT]
160=\E[W [F11] 48 [ABANDON]
161=\E[X [F12] 49 [REFRESH]
162=\E[H [HOME] 50 [MENU BAR]
163=\E[L [INS] 51 [EDIT FIELD]
164=\E[F [END] 52 [EXIT/SAVE]
165=\E[I [PGUP] 53 [PAGE UP]
166=\E[G [PGDN] 54 [PAGE DOWN]
167= --- 55 [LEFT CURSOR]
168= [UP] --- [UP CURSOR]
169= [DOWN] --- [DOWN CURSOR]
170= [LEFT] --- [LEFT CURSOR]
172= --- --- --RESERVED--
173= --- --- --RESERVED--
174= --- --- --RESERVED—

Section 8. Foreground Colors

This section is used to define foreground colors on terminals that support color. Colors are defined with escape sequences. Recital will send the escape sequence shown to produce the color stated in the comment.

Entry Comment
175=\E[=0F\E[0m # Black
176=\E[=8F\E[0m # Gray
177=\E[=4F\E[0m # Red
178=\E[=12F\E[0m # Light red
179=\E[=2F\E[0m # Green
180=\E[=10F\E[0m # Light green
181=\E[=6F\E[0m # Brown
182=\E[=14F\E[0m # Yellow
183=\E[=1F\E[0m # Blue
184=\E[=9F\E[0m # Light blue
185=\E[=5F\E[0m # Magenta
186=\E[=13F\E[0m # Light magenta
187=\E[=3F\E[0m # Cyan
188=\E[=11F\E[0m # Light cyan
189=\E[=7F\E[0m # White
190=\E[=15F\E[0m # Bright white

Entry 175: black

If entry 175, the color sequence definition for black, is commented out, then all color sequences are ignored and the session operates as if on a monochrome terminal.

!** Foreground colors                                                        **
!175=\E[=0F\E[0m                 # black

See also: SET COLOR

Section 9. Background Colors

This section is used to define background colors on terminals that support color. Colors are defined with escape sequences. Recital will send the escape sequence shown to produce the color stated in the comment.

Entry Comment
191=\E[=0G\E[0m # Black
192=\E[=8G\E[0m # Gray
193=\E[=4G\E[0m # Red
194=\E[=12G\E[0m # Light red
195=\E[=2G\E[0m # Green
196=\E[=10G\E[0m # Light green
197=\E[=6G\E[0m # Brown
198=\E[=14G\E[0m # Yellow
199=\E[=1G\E[0m # Blue
200=\E[=9G\E[0m # Light blue
201=\E[=5G\E[0m # Magenta
202=\E[=13G\E[0m # Light magenta
203=\E[=3G\E[0m # Cyan
204=\E[=11G\E[0m # Light cyan
205=\E[=7G\E[0m # White
206=\E[=15G\E[0m # Bright white

Section 10. Secondary Miscellaneous Items

This section defines miscellaneous entries. The functions of the entries are listed in the comment.

Entry Comment
207=\001 # \001 if screen does not retain colors on clear
208=\002 # ESC key delay in tenths of a second
209=\033\x018 # UP arrow character
210=\033\x19 # DOWN arrow character
211=\033\x01a # RIGHT arrow character
212=\033\x01b # LEFT arrow character
220=\001 # \001 to enable 25 rows
221=\001 # \001 to enable 8-bit PC characters
222=\E[11m # Prefix for Ctrl-characters
223=\E[10m # Postfix for Ctrl-characters
224=\001 # \001 to enable font file (same name as .def with .fnt extension)

Entry 208: escape key delay

If the escape key delay is incorrect, users will need to press the escape key twice (escape key delay too long) or other key presses comprising escape plus a sequence will be handled as an escape (escape key delay too short).

Entry 221: 8 bit PC characters

The 221 flag converts ASCII 16 to the character '<' and ASCII 17 to the character '>'. These are commonly used to denote the default menu item in FoxPro style menu dialogs. The 221 flag also causes the @...BOX command to expect a string containing the line drawing characters.

Entry 222/223: prefix and postfix for control characters

Entries 222 and 223 define prefix and postfix sequences for ASCII characters 1-26, so that they can be displayed correctly by the terminal.

Entry 224: font files

The 224 flag enables font files. A font file remaps character output under Recital. Entries in the font file are as follows:


Where <entry> is the original character number and <value> is the character number it has been mapped to.

For example: The line 201=144 in the font file will show character number 144 whenever output calls for character 201 to be displayed. When font files are enabled (entry 224=\001), the control character prefix and postfix entries (222 and 223) should be disabled.

Section 11. Secondary Display Section

This section defines additional display characteristics. Entries include characters to be used for double line drawing.

Entry Comment
230=\X0c2 # Double top 'T'
231=\x0c5 # Double crossing '+'
232=\x0c1 # Double bottom 'T'
233=\x0c3 # Double left vertical 'T'
234=\x0b4 # Double right vertical 'T'
235=\x0da # Double top left corner
236=\x0bf # Double top right corner
237=\x0c0 # Double bottom left corner
238=\x0d9 # Double bottom right corner
239=\x0c4 # Double horizontal line
240=\x0b3 # Double vertical line
241=\x0c7 # Double -> single vertical 'T'
242=\x0b6 # Single -> double right vertical 'T'
243=\x0d1 # Double -> single top 'T'
244=\x0cf # Single ->double bottom 'T'

Section 12. Tertiary Miscellaneous Items

This section defines miscellaneous entries. The functions of entries are listed in the comment:

Entry Comment
250=\001 # \001 to map ^j to [DOWN CURSOR]
251=\001 # \001 to cursor address starts at 00,00

Section 13. Terminal Initialization section

This section is used to send escape sequences to a terminal to set the terminal up with specific features. All entries in this section are 999 and any number of 999 entries can be used.

Entry Comment
999=\E[=0E # Initialize terminal