Terminal Definition Files

Overview

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.

Introduction

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

xterm

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])
xterm
> ? getenv([DB_TERM])
putty

SET TERMINAL

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.

> SET TERMINAL TO ansi

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

or

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

See also: CHR(), SET SCREENMAP

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]
171=	[RIGHT]	---	[RIGHT 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:

<entry>=<value>

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