Recital Terminal Definition Files

In this article, Yvonne Milne explains the contents and configuration of Recital Terminal Definition files.

Yvonne Milne
October, 2005

Overview

Terminal Definition Files are used by Recital to configure screen and keyboard behavior within Recital Terminal Developer 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

Recital Terminal Developer provides 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 profile.db file. By default this is set to the 'terminals' sub-directory of the UD directory. Some one hundred Terminal Definition Files are shipped with Recital Terminal Developer. 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 Terminal Developer 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 Terminal Developer 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 Terminal Developer will be fired up in an xterm window (or equivalent):

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 the Recital 4GL, use the GETENV() function:

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

SET TERMINAL TO

The SET TERMINAL TO <terminal type> can also be used to set the terminal type from within Recital Terminal Developer, 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:

Terminal Definition Files are arranged into the following sections:

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:

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:

Keyboard Input Driver Map:

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:

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:

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.

Click image to display full size

Fig 1: 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

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.

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:

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:

Section 6. Miscellaneous items

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

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.

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 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

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.