# CHAPTER 4: Terminal Definition

## 4.1 Introduction

Empress 4GL is designed to run on different terminals, so it always needs to be told what type of terminal it is addressing. Every time you invoke Empress 4GL, it reads the value of the Empress variable `MSTERM` or if this variable is not defined, the system environment variable `TERM` for the name of the terminal you are using. This terminal name is then used to retrieve information on the terminal from a database called `termdb`.

The information retrieved is comprised of: the number of rows and columns on the terminal; the names of the function keys and the characters that they send; the characters sent by the computer to move the cursor around and to give the screen various video attributes; which function keys are used for the different functions in an Empress 4GL application; and, which video attributes correspond to the video attributes of fields in a form.

Empress 4GL supports two different types of screens through this mechanism. One type is the traditional character-based screen. The other is the bit map graphics screen controlled by a windowing system such as X Windows. The way some of the information in `termdb` is interpreted will depend on the type of screen the terminal uses.

Information on many standard terminals, referred to as terminal definitions, are already continued in the database `termdb`. As well, one example terminal definition for each type of screen has been included at the end of this chapter. To add information on a new type of terminal, or to change the information on an existing terminal, you will have to access `termdb` and update the definition there. This chapter describes the terminal information required by Empress 4GL and how it is stored in `termdb`.

## 4.2 The termdb Database

The `termdb` database is comprised of seven terminal tables, two information tables, a `compile` table, and a set of Empress 4GL application tables. The seven terminal tables contain all the necessary information on all the terminals for which Empress 4GL is currently configured to run. The two information tables contain information on what goes into some of the terminal tables. The `compile` table contains the terminal information in compiled form for all terminals. The set of Empress 4GL application tables contain an Empress 4GL application for maintaining `termdb` itself.

The seven terminal tables:

        terminal         term_ap_key

        term_key         term_ap_video

        term_output      term_form_edit

        term_video

The two information tables:

        term_ap_key_labels

        term_output_names

The `compile` table:

        term_compile

The Empress 4GL application tables contain an application `sys_terminal` which you can run to maintain the terminal tables, as long as you already have a terminal for which a terminal definition already exists in `termdb`. You need only invoke Empress 4GL using `termdb` as your database. If you do not have a terminal on which to run Empress 4GL, you will have to define a terminal entry in the `termdb` database.

### 4.2.1 The "sys_terminal" menu

To make a new terminal entry you will have to select each of the seven terminal tables and enter the appropriate values into each field. There are two tables where an `Autogen` function is available:

1. For the `term_output` table, the `Autogen` function generates a record for each output function. You will have to update the `output_seq` attribute for each record. The output functions are generated from the list of output functions kept in the `term_output_names` table.

Figure 4-1

2. For the `term_ap_key` table the `Autogen` function generates a record for each key label. You will have to update the `key_name` attribute for each record. The key labels are generated from the list of key labels kept in the `term_ap_key_labels` table.

### 4.2.2 Terminal Configuration Tables

The `term_ap_key_labels` lists key labels used in Empress 4GL.The `term_output_names` lists available output functions.
Figure 4-2 Terminal Configuration Tables

## 4.3 Compiling a Terminal Definition

The information in the terminal tables for each terminal must be compiled into the `term_compile` table. Empress 4GL retrieves this information on a terminal and refers to it as the terminal definition. The information for all terminals contained in the database `termdb` is already compiled. If information for a new terminal is added or information for an existing terminal is updated then the appropriate terminal definition will have to be compiled.

Compiling a terminal definition can be done through the `sys_terminal` application or by using the utility `emp4ctdb`. Refer to the "Manual Pages" for details on the `emp4ctdb` utility.)

## 4.4 The "terminal" Table

The `terminal` table contains information on the major characteristics of each terminal and linking information to the remaining six tables.

It has the following attributes:

        name        wraparound     output_set_2

        rows        key_set_1      video_set_1

        columns     key_set_2      video_set_2

        videotype   output_set_1   comment

### 4.4.1 The "name" Attribute

The `name` attribute is the full name of a terminal, for example, `vt100`.

### 4.4.2 The "rows" and "columns" Attributes

The `rows` and `columns` attributes are the maximum number of rows (lines) and columns available on the terminal screen, for example, 24 (rows) and 80 (columns) for the `vt100`.

### 4.4.3 The "videotype" Attribute

The `videotype` attribute specifies the method of showing video attributes peculiar to the terminal. The following values are allowed:

`n` - no videos are allowed
`v` - `vt100` type

The `vt100` type terminals use two concepts:

1. Each character on the screen has its individual video.
2. There is a "current" video. When a character is written to the screen, it inherits the "current" video. No extra space is required to display the video. Commands are available to change the "current" video.

If you configure a terminal that is not a `vt100` type you must set `videotype` to `n` and not use any of the terminal video attributes.

### 4.4.4 The "wraparound" Attribute

The `wraparound` attribute shows whether the terminal has character wraparound. It may have the value `y` (yes) or `n` (no). Character wraparound (yes) means that when a character is written on the rightmost column of the screen, the cursor automatically moves to the leftmost column on the next line. When a character is written on the bottom right corner of the screen, the screen scrolls so that a blank line appears at the bottom of the screen and the cursor moves to the leftmost column of the blank line. This effect of wraparound is generally desirable when running the UNIX shell, but undesirable for full screen applications such as Empress 4GL. If the terminal allows, wraparound should be disabled by entering an `n` (no) value.

### 4.4.5 The "key_set_1" and "key_set_2" Attributes

The `key_set_1` and `key_set_2` attributes contain linking information to the `term_key`, `term_ap_key` and `term_form_edit` tables. They are the names of the primary and secondary sets of (function) keys for the terminal. For example, the `vt100` terminal has `key_set_1` set to `vt100` (to indicate a `vt100` set of keys) and `key_set_2` set to null; the `avt` terminal has `key_set_1` set to `avt` (to indicate an `avt` set of keys) and `key_set_2` set to `vt100` (to indicate that the `avt` also has the `vt100` set of keys). The primary set always overrides the secondary set if there are conflicts.

### 4.4.6 The "output_set_1" and "output_set_2" Attributes

The `output_set_1` and `output_set_2` attributes contain linking information to the `term_output` table. They are the names of the primary and secondary sets of output characters for the terminal.

### 4.4.7 The "video_set_1" and "video_set_2" Attributes

The `video_set_1` and `video_set_2` attributes contain linking information to the `term_video`, `term_ap_video` and `term_form_edit` tables. They are the names of the primary and secondary sets of video characters for the terminal.

### 4.4.8 The "comment" Attribute

The `comment` attribute contains comments on the terminal. This is not used by Empress 4GL and is strictly for user information.

## 4.5 The "term_key" Table

The `term_key` table contains information on what characters the function keys on the terminal send when they are pressed. There should be one record in this table for each function key on each terminal. This table is accessed through `key_set_1` and `key_set_2` of the `terminal` table. It has the following attributes:
key_set key_name key_seq

### 4.5.1 The "key_set" Attribute

The `key_set` attribute is the name of a set of function keys. It corresponds to `key_set_1` and `key_set_2` of the `terminal` table.

### 4.5.2 The "key_name" Attribute

The is the name of a function key. It also contains linking information to the `term_ap_key` table. It is arbitrary, but typically corresponds to the physical label engraved on the key itself.

Any key that sends other than a single printable character (ASCII code hex <20> to <7E>, octal <040> to <176>) should be considered a function key. Examples are <PF1> and <F1>.

On some terminals, some function keys send different characters when pressed together with the <Shift> key. You must choose how to represent the <Shift>. Examples are `SHIFT_PF1` and `SHIFT-PF1`. Some keys have graphic symbols engraved on them. You must choose your own names. Examples are `left_arrow` and `up_arrow`. Other keys, typically on a cursor pad, have printable characters such as "0" or "1" engraved on them, but send sequences of characters when used in Empress 4GL applications. You must choose your own names for these. Some suggestions are `KP 0`, `KP 1`, etc., where `KP` stands for `key pad`.

If the terminal does not have enough function keys for Empress 4GL, you can simulate function keys. For example, you can specify `key_name` to be `ESC 0` so that by pressing the key <ESC> and then the key <0>, you simulate pressing a single function key (say <F0>) which sends the same two characters as `ESC` and `0`.

For convenience, certain values for `key_name` are pre-defined in Empress 4GL, they do not have to be in the `term_key` table. They can be overridden by specifying the characters they send. The pre-defined values and the characters they send are presented in the table below:
Table 4-1

Pre-defined key_name Values
key_name | Value
`ALT` | hex <1B>, octal <033>
`BACKSPACE` | hex <08>, octal <010>
`BS` | hex <08>, octal<010>
`CR` | hex <0D>, octal <015>
`DEL` | hex <7F>, octal <177>
`DELETE` | hex <7F>, octal <177>
`ESC` | hex <1B>, octal <033>
`ESCAPE` | hex <1B>, octal <033
`LF` | hex <0A>, octal <012>
`LINEFEED` | hex <0A>, octal <012>
`RET` | hex <0D>, octal <015>
`RETURN` | hex <0D>, octal <015>
`RUB` | hex <7F>, octal <177>
`RUBOUT` | hex <7F>, octal <177>
`TAB` | hex <09>, octal <011>
`CNTL-x` | hex <01> to <1A>, octal <001> to <032>
`CNTL/x` | hex <01> to <1A>, octal <001> to <032>
`CTRL-x` | hex <01> to <1A>, octal <001> to <032>
`CTRL/x` | hex <01> to <1A>, octal <001> to <032>

where `x`, stands for "A" to "Z", or "a" to "z"

### 4.5.3 The "key_seq" Attribute

The `key_seq` specifies the sequence of characters sent by the terminal when the key corresponding to `key_name` is pressed. It is specified in the same way as `output_seq` in the `term_output table` (see the following section on the `output_seq` attribute). The only restriction for `key_seq` is that operators and parameters are not permitted.

Refer to your terminal manual for the appropriate key sequences.

## 4.6 The "term_output" Table

The `term_output` table contains information on what characters Empress 4GL should send to the terminal to effect various output functions. There should be one record in this table for each output function for each terminal. This table is accessed through `output_set_1` and `output_set_2` of the `terminal` table. It has the following attributes:

        output_set

        output_name

        output_seq

Empress 4GL does not use information from this table when running through a windowing system. Instead a set of subroutine calls for the appropriate windowing package is used to handle output to the screen.

### 4.6.1 The "output_set" Attribute

The `output_set` attribute is the name of a set of output functions. It corresponds to `output_set_1` and `output_set_2` of the `terminal` table.

### 4.6.2 The "output_name" Attribute

This is the name of an output function. If a particular output function is not supported on a terminal, the record of the function on that terminal should be omitted. This name must be one of the following names known to Empress 4GL: (the list can be found in the `term_output_names` table)

        init         clr eow       ins on        left

        done         clr eol       ins off       right

        window       del line      graph on      up

        region       del char      graph off     down

        index        ins line      graph set     bell

        rev index    ins char      cursor

#### 4.6.2.1 The "init" Function

The `init` function is used to start up Empress 4GL and redraw the screen. It typically turns character wraparound off and turns on function keys and cursor pads, if the terminal allows.

After invoking the `init` function, Empress 4GL :

1. turns the character graphics off
2. turns the video to `normal`
3. sets the editing window or scrolling region to the entire screen
4. clears the screen and positions the cursor at the top-left corner of the screen (Empress 4GL considers this position to be (1,1)).

#### 4.6.2.2 The "done" Function

The `done` function is used to stop or escape from Empress 4GL. It typically turns character wraparound on, and if the terminal allows, it turns off the function keys and cursor pads. It also positions the cursor to the bottom-left corner of the screen and scrolls to the new blank line.

Empress 4GL performs the following tasks before invoking the `done` function:

1. turns the character graphics off
2. turns the video to `normal`
3. sets the editing window or scrolling region to the entire screen.

#### 4.6.2.3 The "window" Function

The `window` function sets an editing window to new coordinates. The editing window defines the extent of the screen affected by such output functions as `delete line`, `delete character`, `insert line` and `insert character`. Empress 4GL supplies four parameters to the `window` function and they are: the coordinates of the top-left row and column and the bottom-right row and column of the window.

#### 4.6.2.4 The "region" Function

The `region` function sets a scrolling region to new coordinates. The scrolling region defines the rows of the screen within which scrolling can take place. This is intended for "split-screen" usage. It is a less powerful concept than the "editing window" where only the rows can be defined. Empress 4GL supplies two parameters to the `region` function and these are the top and bottom rows of the scrolling region. Note that a scrolling region must contain at least two rows.

#### 4.6.2.5 The "index" Function

The `index` function scrolls the lines of a scrolling region upwards when the cursor is on the bottom row of the scrolling region. After invoking the `index` function, the cursor is on a new blank line at the bottom row. This function only works with `region`.

#### 4.6.2.6 The "rev index" Function

The `rev index` function scrolls the lines of a scrolling region downwards when the cursor is on the top row of the scrolling region. After invoking the `rev index` function, the cursor is on a new blank line at the top row. This only works with `region`.

#### 4.6.2.7 The "clr eow" Function

The `clr eow` function clears the rest of the screen from the current cursor position onwards.

#### 4.6.2.8 The "clr eol" Function

The `clr eol` function clears the rest of the line from the current cursor position onwards.

#### 4.6.2.9 The "del line" Function

The `del line` function deletes the line on which the cursor appears.

#### 4.6.2.10 The "del char" Function

The `del char` function deletes the character on which the cursor appears.

#### 4.6.2.11 The "ins line" Function

The `ins line` function inserts a blank line before the line on which the cursor appears.

#### 4.6.2.12 The "ins char" Function

The `ins char` function inserts a blank character before the character on which the cursor appears.

#### 4.6.2.13 The "ins on" Function

The `ins on` function turns the `insert` mode on. The concept of `insert` mode is supported on some terminals. When it is on, a character sent to the terminal is placed before the character on which the cursor appears. When it is off, a character sent replaces the character on which the cursor appears and the cursor moves to the right by one character.

#### 4.6.2.14 The "ins off" Function

The `ins off` function turns the `insert` mode off. This is often the same function as `ins on` since the `insert` mode is often treated as a toggle.

#### 4.6.2.15 The "graph on" Function

The `graph on` function turns character graphics on. The concept of character graphics is supported on some terminals. When it is on, a character sent to the terminal is interpreted as a character in a graphics character set. Line drawings are typically produced in this way. When it is off, a character sent is interpreted as a normal character.

#### 4.6.2.16 The "graph off" Function

The `graph off` function turns character graphics off.

#### 4.6.2.17 The "graph set" Function

The `graph set` function specifies the correspondence between the characters sent and the graphics characters produced on the screen. This is discussed below.

#### 4.6.2.18 The "cursor" Function

The `cursor` function moves the cursor to new coordinates. Empress 4GL supplies the following four parameters to the `cursor` function: the new row and column subtracted by 1 (this caters to terminals where the top left corner has coordinates (0,0)) and the new row and column. This output function must be supported and available to Empress 4GL.

#### 4.6.2.19 The "left" Function

The `left` function moves the cursor to the left by one character.

#### 4.6.2.20 The "right" Function

The `right` function moves the cursor to the right by one character.

#### 4.6.2.21 The "up" Function

The `up` function moves the cursor up by one line.

#### 4.6.2.22 The "down" Function

The `down` function moves the cursor down by one line.

#### 4.6.2.23 The "bell" Function

The `bell` function produces an audible or visual warning on the terminal. This function often produces the `bell` character (hex, octal). It must not change the screen or cursor position in any way.

### 4.6.3 The "output_seq" Attribute

The `output_seq` attribute specifies the sequence of characters sent to the terminal to affect the output function. Refer to the functions listed above and your terminal manual to determine the required sequence for each function. The form of the output sequence is a string of words (printable characters) separated by white space. The interpretation of these words produces the desired sequence of characters. This specification method is intended to be understandable and it allows: input sequences, simple output sequences, output sequences involving parameters, and expressions to be handled in a unified manner.

The central concept is that of a stack to hold characters (or equivalently, ASCII codes). Initially, this stack is empty. When it interprets a string of words, characters are pushed onto the stack and manipulated. The final outcome is a stack of zero or more characters comprising the desired sequence which starts from the bottom of the stack.

Each word in the string of words can be divided into the following classes:

- character strings
- numbers
- synonyms
- parameters
- operators
- special operators

#### 4.6.3.1 The Character String Class

A character string is composed of characters to be pushed individually onto the stack. Any word that is not in any of the other classes is a character string. Additionally, any characters within quotes is also a character string. Examples are: "abc", "OQ" and "`abc efg'".

#### 4.6.3.2 The Number Class

A number is a character code to be pushed onto the stack. It has the prefix "#", "#o" or "#x". The remaining characters represent a decimal, octal or hexadecimal number respectively. Examples are: #32, #o40 and #x20.

#### 4.6.3.3 The Synonym Class

A synonym represents one or more characters to be pushed onto the stack. The synonyms "^a" to "^z" represent the characters with codes hex <01> to <1A> or octal <001> to <032>. Other synonyms are:
Table 4-2

Stack Synonym Values
Synonym | Value
`bel` | hex <07>, octal <007>
`bell` | hex <07>, octal <007>
`bs` | hex <08>, octal <010>
`cmd` | hex <1B> <5B>, octal<033> <133>, (ESC [)
`cr` | hex <0D>, octal <015>
`crlf` | hex <0D> <0A>, octal <015> <012>, (CR LF)
`del` | hex <7F>, octal <177>
`esc` | hex <1B>, octal <033>
`ff` | hex <0C>, octal <014>
`ht` | hex <09>, octal <011>, (TAB)
`lf` | hex <0A>, octal <012>
`nl` | hex <0A>, octal <012>
`np` | hex <0C>, octal <014>
`nul` | hex <00>, octal <000>
`null` | hex <00>, octal <000>
`sp` | hex <20>, octal <040>, (SPACE)
`tab` | hex <09>, octal <011>

#### 4.6.3.4 The Parameter Class

A parameter is a value supplied by Empress 4GL to be pushed onto the stack as a character code. It has the prefix "$". The remaining characters represent a decimal number indicating the number of the parameter (from 1 to the number of parameters supplied). Examples are: $1 and $3. It is an error to specify a parameter when none are supplied or when the number of the parameter exceeds the number of parameters supplied.

#### 4.6.3.5 The Operator Class

An operator performs certain operations on the stack. A 1-element operator removes the top element. A 2-element operator removes the top two elements. When the operation is completed the result is pushed onto the stack. It is an error to specify an operator when there are insufficient elements in the stack.

The 1-element operators and their operations are:
Table 4-3

One-element Operators
Operator | Operation
`!` | If X is 0 then 1, else 0
`+` | X + 1
`--` | X - 1
`_ (underscore)` | Negative of X
`bcd` | Convert X to 2 ASCII digits X1 X2 (with leading zero); (X1 << 4) | X2
`cvt` | Convert X to ASCII digits (no leading zeros); push all digits onto stack
`cvt2` | Convert X to 2 ASCII digits (with leading zero); push all digits onto stack
`cvt3` | Convert X to 3 ASCII digits (with leading zeros); push all digits onto stack
`dup` | Push 2 X's onto stack (in effect, duplicate X)
`pop` | Do nothing (in effect, remove X)
`rbcd` | Convert X to 2 ASCII digits X1 X2 (with leading zero); (X2 << 4) | X1
`~ (tilde)` | Bitwise-complement of X

Let "X" be the top element of the stack.

The 2-element operators and their operations are:
Table 4-4

Two-element Operators
Operator | Operation
`!=` | if X != Y then 1 else 0
`%` | X % Y
`&` | X bitwise-and Y
`*` | X * Y
`+` | X + Y
`-` (minus) | X - Y
`/` | X / Y
`<` | if X< Y then 1 else 0
`<<` | X<< Y
`<=` | if X<= Y then 1 else 0
`=` | if X equals Y then 1 else 0
`==` | if X equals Y then 1 else 0
`>` | if X > Y then 1 else 0
`>=` | if X = Y then 1 else 0
`>>` | X >>Y
`^` (caret) | X bitwise-exclusive-or Y
`|` (bar) | X bitwise-or Y

Let "X",, "Y" be the top two elements of the stack.

#### 4.6.3.6 The Special Operator Class

There are five special operators:

        then

        else

        end

        delay

        sep

The special operators `then`, `else` and `end` work together to allow conditional expressions. The operator `then` removes the top element of the stack, call it X. If X is not 0, any words between `else` (if specified) and `end` are discarded. If X is 0, any words between `then` and `else` (or `end` if `else` is not specified) are discarded. The `then`, `else` and `end` construct may be nested.

The special operator `delay` requires a number (as specified above) following it. This gives the number of milliseconds of delay (translated into the appropriate number of null characters, depending on baud rate) to be sent to the terminal.

The special operator `sep` is used only for the `graph set` output function. Fourteen `sep` operators will separate the string of words into fifteen parts, each part specifying the characters that represent the corresponding graphics character. A graphics character can be thought of as a combination of four segments, each segment having the value 1, 2, 4 or 8.

         |     2

         |

        - -   8 4

         |

         |     1

For example, the graphics character "top-left corner" comprises the segments 1 and 4; and the graphics character "tee pointing down" comprises the segments 1, 4 and 8.

The words of part N, then, represent the graphics character for which the values of its segments sum to N. The number of the parts and the graphics character represented can be summarized in the following table.
Table 4-5

Graphic Parts
No. Parts | Graphic Character
`1 = 1` | Vertical (bottom half)
`2 = 2` | Vertical (top half)
`3 = 1+2` | Vertical
`4 = 4` | Horizontal (right half)
`5 = 1+4` | Top-left corner
`6 = 2+4` | Bottom-left corner
`7 = 1+2+4` | Tee pointing right
`8 = 8` | Horizontal (left half)
`9 = 1+8` | Top-right corner
`10 = 2+8` | Bottom-right corner
`11 = 1+2+8` | Tee pointing left
`12 = 4+8` | Horizontal
`13 = 1+4+8` | Tee pointing down
`14 = 2+4+8` | Tee pointing up
`15 = 1+2+4+8` | Cross

#### 4.6.3.7 Termcap Cursor cm/sr Notation

It is possible to derive the required output key sequences from the `termcap` entry for a terminal. The following table summarizes the correspondences.
Table 4-6

Output Key Sequence
Termcap | Empress 4GL
`row/col are origin 0` | $1/$2 are row/column origin 0; $3/$4 are row/column origin 1; so by default,, use $1,$2

Table 4-7

Printing Commands
`%%` | '%'
`%d` | $1/$2 cvt
`%2` | $1/$2 cvt2
`%3` | $1/$2 cvt3
`%.` | $1/$2
`%+x` where `x` is a char | $1/$2 x +

Table 4-8

Non-Printing Commands
`%r` | Use $2/$1 instead of $1/$2
`%i` | Use $3/$4 instead of $1/$2
`%xy` where `x,y` are chars | Use $1/$2 dup x > then y + end
`%n` | Use $1/$2 #0140
`^ %B` | Use $1/$2 bcd

Example

Termcap | Empress 4GL
`E[%i%d;%dH` | `cmd $3 cvt ; $4 cvt H`
`Ep%.%.` | `esc p $1 $2`
`Ex%+_%+_` | `esc x $1 '_' + $2 '_' +`
`Ez%r%.%.` | `esc z $2 $1`

## 4.7 The "term_video" Table

The `term_video table` contains information concerning what video attributes are available on the terminal and what characters must be sent to display them. There should be one record in this table for each video attribute on each terminal. This table is accessed through `video_set_1` and `video_set_2` of the `terminal` table. It has the following attributes:

        video_set

        video_name

        video_seq

### 4.7.1 The "video_set" Attribute

This is the name given to a set of video attributes. It corresponds to `video_set_1` and `video_set_2` of the `terminal` table.

### 4.7.2 The "video_name" Attribute

This is the name of a particular video attribute. It also contains linking information to the `term_ap_video` table. It is arbitrary, but usually corresponds to how the video attribute appears on the screen. Typical names are: "`normal`" and "`reverse`". Color terminals will have colors defined. If any video attributes are specified for a `video_set`, the `video_name` must be "`normal`". This refers to what characters on the screen should normally look like and also what the blank characters should look like if the screen was cleared.

### 4.7.3 The "video_seq" Attribute

This attribute specifies the sequence of characters to be sent to the terminal to display the video attribute. It is specified in the same way as `output_seq` in the `term_output` table (see the above section on the `output_seq` attribute). The only restriction for `video_seq` is that parameters are not permitted.

If Empress 4GL is running through a windowing system then the sequence of characters does not define output to the terminal. Instead, it is used to identify video colors in a table called a `colormap`. Each video attribute has two parts, a foreground (character) color and a background (space) color. The video sequence consists of a four digit code where the first two digits represent the foreground color and the last two digits represent the background color. The two digits together are taken as an offset into the `colormap`.

### 4.7.4 The "colormap"

The `colormap` is a table that a windowing system uses to decide what colors are possible for the screen. When Empress 4GL is invoked it tells the windowing system what `colormap` to use. The Empress 4GL `colormap` is defined in the file `./custom/ colormap.c` where "`.`" is the directory in which Empress is installed.

While colormaps do differ from windowing system to windowing system the structure is essentially that of a `3xn` array of values where "`3`" is the red, green and blue components of a color and "`n`" is the number of colors. The Empress 4GL colormap for color screens currently contains the following eight entries:
Table 4-9

Colormap
Offset | Color | Offset | Color
`0` | white | `4` | blue
`1` | red | `5` | magenta
`2` | green | `6` | cyan
`3` | brown | `7` | black

## 4.8 The "term_ap_key" Table

The `term_ap_key` table contains a mapping of Empress 4GL functions to terminal function keys. There should be at least one record in this table for each Empress 4GL function (mapped to one or more function keys) on each terminal. This table is accessed through `key_set_1` of the `terminal` table. It has the following attributes:

        term_key_set

        key_label

        key_name

### 4.8.1 The "term_key_set" Attribute

This is the name given to a set of function keys. It corresponds to `key_set_1` of the `terminal` table.

### 4.8.2 The "key_label" Attribute

At any time in Empress 4GL, either an application is running or a form is being edited. In the first case, Empress 4GL requires function keys for the Field Editor as well as the application. In the second case, Empress 4GL requires function keys for the Form Editor. Since the two cases are independent, the same function keys may be assigned different functions in each case.

The list of all the Empress 4GL functions can be found in the `term_ap_key_labels` table.

1. Empress 4GL functions common to both cases are:

`DEL_CHAR` | `HELP` | `PRINTSCREEN`
`GO_DOWN` | `INS_MODE` | `QUIT`
`GO_LEFT` | `INTERRUPT` | `REDRAW`
`GO_RIGHT` | `NEXT_FLD` | `RETURN`
`GO_UP` | `PREV_FLD` | `SCROLL`

2. Empress 4GL functions specific to the Field Editor (first case) are:

    FD_BEGIN_END

    FD_CLR_EOS

    FD_EDIT

These must be distinct from the keys in #1 above.
3. Empress 4GL functions specific to applications (first case) are, by convention, named `AP_1` to `AP_10`. By having these standard function names, an application can be assured of having ten functions to use. If a terminal has a mouse and it is made available to Empress 4GL, then additional functions specific to applications are:

    MOUSE_IDN     MOUSE_2UP

    MOUSE_IUP     MOUSE_3DN

    MOUSE_2DN     MOUSE_3UP

An application may use other names for its functions, however, these names must be defined here for each terminal. The names must be distinct from the keys in #1 and #2 above.
4. Empress 4GL functions specific to the Form Editor (second case) are:

    FM_BG_MODE      FM_INS_LINE         FM_PUT

    FM_CHG_HOME     FM_JOIN_FLD         FM_UNDO

    FM_DEL_LINE     FM_MARK             STATUS

    FM_FLD_EDIT     FM_MULTI

These may overlap the keys in #2 and #3 above.

### 4.8.3 The "key_name" Attribute

This is the name of the function key assigned to the Empress 4GL function. This name must either appear in `key_name` in the `term_key` table or be pre-defined in Empress 4GL.

## 4.9 The "term_ap_video" Table

The `term_ap_video` table contains a mapping of field video attributes to field characteristics. There should be one record in this table for each field video attribute on each terminal. This table is accessed through `video_set_1` of the `terminal` table. It has the following attributes:

        term_video_set

        video_label

        lo_video_name

        hi_video_name

        lo_fill

        hi_fill

### 4.9.1 The "term_video_set" Attribute

This is the name given to a set of terminal video attributes. It corresponds to `video_set_1` of the `terminal` table.

### 4.9.2 The "video_label" Attribute

This is the name of a field or region video attribute. It also contains linking information to the `term_form_edit` table. It is arbitrary, but should have some mnemonic value.

### 4.9.3 The "low_video_name" and "hi_video_name" Attributes

These are terminal video attributes associated with the field or region video attribute. For a field, the former applies when the cursor is not on a field, and the latter applies when the cursor is on the field. For a region, the `lo_video_name` is the video attribute for the region. In any case, these names must either appear in `video_name` in the `term_video` table or have the value "`normal`" (see the above section on the `term_video` table).

### 4.9.4 The "low_fill" and "hi_fill" Attributes

These are single characters for padding out a field. The former applies when the cursor is not on the field, and the latter applies when the cursor is on the field. The fill characters defined here are associated with field video attributes. They should be chosen to complement the terminal video attribute associated with the field attribute. For example, the character "_" (underscore) works well with "`normal`" and the character " " (space) works well with "`reverse`".

## 4.10 The "term_form_edit" Table

The `term_form_edit` table contains a definition of the objects (box, field and video region) that the `create` command in the Form Editor can create, and the keys that are used to create these objects. There should be one record in this table for each object on each terminal. This table is accessed through `key_set_1` and `video_set_1` of the `terminal` table. It has the following attributes:

        term_video_set

        term_key_set

        object

        video_label

        key_name

### 4.10.1 The "term_video_set" and "term_key_set" Attributes

These are the names of a set of terminal video attributes and a set of terminal function keys. It corresponds to `video_set_1` and `key_set_1` of the `terminal` table.

### 4.10.2 The "object" Attribute

This is the attribute which indicates the type of object, whether it is a `b` (box), `f` (field) or `v` (video region).

### 4.10.3 The "video_label" Attribute

This is the name of a field or region video attribute. If `object` is `b` (box), then this is not used by Empress 4GL. If `object` is `f` (field), then this gives the field video attribute and must appear in `video_label` in the `term_ap_video` table (see the above section on the `term_ap_video` table). If `object` is `v` (video region), then this gives the video attribute of the video region and must appear in `video_name` in the `term_video` table (see the above section on the `term_video` table).

### 4.10.4 The "key_name" Attribute

This is the key to press for creating the object. It is a single character, typically `b` for box, `n` for field video "normal", `r` for field video "reverse", `N` for video region "normal", etc.

## 4.11 Complete Example for DEC VT100

    *** terminal ***

    name   rows   columns   videotype   wraparound

    vt100  24     80        v           n

    key_set_1     key_set_2    output_set_1   output_set_2,

    vt100                      vt100

    video_set_1     video_set_2       comment

    vt100                             DEC VT100 vanilla flavor

    *** term_key ***

    key_set   key_name     key_seq

    vt100     KP ,         esc O1

    vt100     U_ARROW      esc OA

    vt100     R_ARROW      esc OC

    vt100     PF4          esc OS

    vt100     PF3          esc OR

    vt100     PF2          esc OQ

    vt100     PF1          esc OP

    vt100     L_Arrow      esc OD

    vt100     KP ENTER     esc OM

    vt100     KP 9         esc Oy

    vt100     D_Arrow      esc OB

    vt100     KP 8         esc Ox

    vt100     KP -         esc Om

    vt100     KP 7         esc Ow

    vt100     KP 6         esc Ov

    vt100     KP 5         esc Os

    vt100     KP 4         esc Ot

    vt100     KP 3         esc Os

    vt100     KP 2         esc Or

    vt100     KP 1         esc Oq

    vt100     KP 0         esc Op

    vt100     KP .         esc On

    *** term_output ***

    output_set    output_name     output_seq

    vt100         right           cmd C

    vt100         left            bs

    vt100         cursor          cmd $3 cvt ; $4 cvt H

    vt100         clr eol         cmd K

    vt100         clr eow         cmd J

    vt100         rev index       esc M

    vt100         index           nl

    vt100         Region          cmd $1 cvt; $2 cvt r

    vt100         done            cmd ?11 cmd ?7h esc '>'

                                  cmd 24; 1H crlf

    vt100         graph off       ^o

    vt100         graph on        ^N

    vt100         graph set       x sep x sep x sep q

                                  sep 1 sep m sep t sep q

                                  sep k sep j sep u sep q

                                  sep w sep v sep n

    vt100         bell            ^G

    vt100         init            cmd ?1h cmd ?51 cmd ?61

                                  cmd ?71 esc '=' esc ) 0

    vt100         down            nl

    vt100         up              cmd A

    *** term_video ***

    video_set     video_name     video_seq

    vt100         reverse        cmd 0;7m

    vt100         normal         cmd m

    *** term_ap_key ***

    term_key_set      key_label       key_name

    vt100             NEXT_PAGE       CTRL/D

    vt100             INTERRUPT       CTRL/C

    vt100             PRINTSCREEN     CTRL/P

    vt100             FM_MULTI        KP 2

    vt100             FM_STATUS       KP 0

    vt100             RETURN          LINEFEED

    vt100             REDRAW          CTRL/R

    vt100             QUIT            DELETE

    vt100             PREV_FLD        KP ENTER

    vt100             NEXT_FLD        TAB

    vt100             INS_MODE        KP -

    vt100             HELP            PF4

    vt100             GO_UP           U_Arrow

    vt100             GO_RIGHT        R_Arrow

    vt100             GO_LEFT         L_Arrow

    vt100             GO_LEFT         BACKSPACE

    vt100             GO_DOWN         D_Arrow

    vt100             FM_UNDO         PF1

    vt100             FM_PUT          KP 3

    vt100             FM_MARK         KP 1

    vt100             FM_JOIN_FLD     KP 6

    vt100             FM_INS_LINE     KP 5

    vt100             FM_FLD_EDIT     KP 4

    vt100             FM_DEL_LINE     KP 9

    vt100             FM_CHG_HOME     KP 8

    vt100             FM_BG_MODE      KP 7

    vt100             FD_EDIT         PF3

    vt100             FD_CLR_EOS      PF2

    vt100             FD_BEGIN_END    PF1

    vt100             DEL_CHAR        KP

    vt100             AP_9            KP 3

    vt100             AP_8            KP 2

    vt100             AP_7            KP 1

    vt100             AP_6            KP 6

    vt100             AP_5            KP 5

    vt100             AP_4            KP 4

    vt100             AP_3            KP 9

    vt100             AP_2            KP 8

    vt100             AP_10           KP 0

    vt100             SCROLL          KP .

    vt100             AP_1            KP 7

    vt100             RETURN          RETURN

    vt100             PREV_PAGE       CTRL/U

    *** term_ap_video ***

    term_video_set  video_label  lo_video_name  lo_fill hi_video_name  hi_fill

    vt100           nohilite     normal                 normal

    vt100           reverse      reverse                reverse

    vt100           normal       normal                 reverse

    vt100           background   normal                 normal

    vt100           warning      reverse                reverse

    *** term_form_edit ***

    term_video_set   term_key_set   object   video_label   key_name

    vt100            vt100          v        reverse       R

    vt100            vt100          v        normal        N

    vt100            vt100          f        nohilite      z

    vt100            vt100          f        reverse       r

    vt100            vt100          f        normal        n

    vt100            vt100          b        normal        ++

## 4.12 Complete Example for 386/ix running X Windows

    *** terminal ***

    name       rows     columns     videotype     wraparound

    ix.xterm   24       80          v             n

    key_set_1    key_set_2    output_set_1    output_set_2

    ix.X                      xterm

    video_set_1     video_set_2     comment

    xterm                           AT/386 Color Console

                                    for 386/ix R2 running X Windows

    *** term_key ***

    key_set      key_name       key_seq

    ix.X         F4             cmd-04

    ix.X         F5             cmd-05

    ix.X         F6             cmd-06

    ix.X         F7             cmd-07

    ix.X         F8             cmd-08

    ix.X         F09            cmd-09

    ix.X         F10            cmd-10

    ix.X         F11            cmd-11

    ix.X         F12            cmd-12

    ix.X         Insert         cmd-22

    ix.X         R_Arrow        cmd-52

    ix.X         L_Arrow        cmd-51

    ix.X         D_Arrow        cmd-50

    ix.X         U_Arrow        cmd-49

    ix.X         Tab            cmd-55

    ix.X         S/Tab          cmdS55

    ix.X         KP -           cmd-42

    ix.X         Page Down      cmd-26

    ix.X         Page Up        cmd-25

    ix.X         LEFT DOWN      cmd301z

    ix.X         LEFT UP        cmd302z

    ix.X         MIDDLE DOWN    cmd303Z

    ix.X         MIDDLE UP      cmd304z

    ix.X         RIGHT DOWN     cmd305z

    ix.X         RIGHT UP       cmd306z

    ix.X         Home           cmd-53

    ix.X         End            cmd-54

    ix.X         Delete         del

    ix.X         S/F12          cmdS12

    ix.X         F3             cmd-03

    ix.X         F2             cmd-02

    ix.X         F1             cmd-01

    *** term_output ***

    output_set     output_name     output_seq

    *** term_video ***

    video_set     video_name        video_seq

    xterm         green             0702

    xterm         red               0001

    xterm         black             0007

    xterm         fldrevhi          0007

    xterm         fldrevlo          0706

    xterm         ldnormhi          0003

    xterm         fldnormlo         0400

    xterm         graph             0004

    xterm         reverse           0700

    xterm         normal            0004

    xterm         rown              0003

    xterm         blue              0004

    xterm         magenta           0005

    xterm         cyan              0706

    xterm         white             0700

    *** term_ap_key ***

    term_key_set     key_label     key_name

    ix.X             MOUSE_3UP     RIGHT UP

    ix.X             MOUSE_3DN     RIGHT DOWN

    ix.X             MOUSE_2UP     MIDDLE UP

    ix.X             MOUSE_2DN     MIDDLE DOWN

    ix.X             MOUSE_1UP     LEFT UP

    ix.X             MOUSE_1DN     LEFT DOWN

    ix.X             PREV_PAGE     Page Up

    ix.X             RETURN        RETURN

    ix.X             AP_1          F1

    ix.X             SCROLL        Home

    ix.X             AP_10         F10

    ix.X             AP_2          F2

    ix.X             AP_3          F3

    ix.X             AP_4          F4

    ix.X             AP_5          F5

    ix.X             AP_6          F6

    ix.X             AP_7          F7

    ix.X             AP_8          F8

    ix.X             AP_9          F9

    ix.X             DEL_CHAR      Delete

    ix.X             FD_BEGIN_END  F11

    ix.X             FD_CLR_EOS    F12

    ix.X             FD_EDIT       S/F12

    ix.X             FM_BG_MODE    F1

    ix.X             FM_CHG_HOME   F2

    ix.X             FM_DEL_LINE   F3

    ix.X             FM_FLD_EDIT   F4

    ix.X             M_INS_LINE    F5

    ix.X             FM_JOIN_FLD   F6

    ix.X             FM_MARK       F7

    ix.X             FM_PUT        F9

    ix.X             FM_UNDO       F11

    ix.X             GO_DOWN       D_Arrow

    ix.X             GO_LEFT       BACKSPACE

    ix.X             GO_LEFT       L_Arrow

    ix.X             GO_RIGHT      R_Arrow

    ix.X             GO_UP         U_Arrow

    ix.X             HELP          KP -

    ix.X             NS_MODE       Insert

    ix.X             NEXT_FLD      Tab

    ix.X             PREV_FLD      S/TAb

    ix.X             QUIT          End

    ix.X             REDRAW        CTRL/R

    ix.X             RETURN        LINEFEED

    ix.X             FM_STATUS     F10

    ix.X             FM_MULTI      F8

    ix.X             RIMTSCREEN    CTRL/P

    ix.X             INTERRUPT     CTRL/C

    ix.X             NEXT_PAGE     Page Down

    *** term_ap_video ***

    term_video_set  video_label lo_video_name lo_fill  hi_video_name  hi_fill

    xterm           warning     red                    red

    xterm           background  normal                 normal

    xterm           nohilite    fldnormlo              fldnormlo

    xterm           reverse     fldrevlo               fldrevhi

    xterm           normal      fldnormlo              fldnormhi

    *** term_form_edit ***

    term_video_set  term_key_set   object   video_label   key_name

    xterm           ix.X           v        white         7

    xterm           ix.X           v        cyan          6

    xterm           ix.X           v        magenta       5

    xterm           ix.X           v        blue          4

    xterm           ix.X           v        brown         3

    xterm           ix.X           v        green         2

    xterm           ix.X           v        red           1

    xterm           ix.X           v        black         0

    xterm           ix.X           v        reverse       R

    xterm           ix.X           v        normal        N

    xterm           ix.X           f        nohilite      z

    xterm           ix.X           f        reverse       r

    xterm           ix.X           f        normal        n

    xterm           ix.X           b        normal        +

## 4.13 Print Terminal Definition

There is a utility, `emp4ptrm`, which will print out a complete terminal listing given a valid terminal name. Only one terminal name can be printed at a time. The syntax is:

    emp4ptrm terminal_name

where:

`terminal_name` | is a valid terminal name.

The utility will look for the terminal database within the path set by `MSTERMDB`, or if this is unset, within the 4GL directory where Empress is installed.

For the `vt100` terminal type, output from `emp4ptrm` is as follows:

Terminal Definition for vt100

`Rows: 24 Cols: 80 Wrap: n`
`Key_set_1: vt100 Key_set_2:`
`Output_set_1: vt100 Output_set_2:`
`Video_set_1: vt100 Video_set_2:`
`Comment: DEC VT-100 vanilla flavour`

Key Definition for Terminal: vt100
Keyset: vt100

`Key Name Key Sequence`
`D-Arrow esc OB`
`KP , esc Ol`
`KP - esc Om`
`KP . esc On`
`KP 0 esc Op`
`KP 1 esc Oq`
`KP 2 esc Or`
`KP 3 esc Os`
`KP 4 esc Ot`
`KP 5 esc Ou`
`KP 6 esc Ov`
`KP 7 esc Ow`
`KP 8 esc Ox`
`KP 9 esc Oy`
`KP ENTER esc OM`
`L-Arrow esc OD`
`PF1 esc OP`
`PF2 esc OQ`
`PF3 esc OR`
`PF4 esc OS`
`R-Arrow esc OC`
`U-Arrow esc OA`

Application Key Definition for Terminal: vt100
Keyset: vt100

`Key Label Key Name`
`AP_1 KP 7`
`AP_10 KP 0`
`AP_2 KP 8`
`AP_3 KP 9`
`AP_4 KP 4`
`AP_5 KP 5`
`AP_6 KP 6`
`AP_7 KP 1`
`AP_8 KP 2`
`AP_9 KP 3`
`DEL_CHAR KP ,`

Terminal Definition for: vt100

`FD_BEGIN_END PF1`
`FD_CLR_EOS PF2`
`FD_EDIT PF3`
`FM_BG_MODE KP 7`
`FM_CHG_HOME KP 8`
`FM_DEL_LINE KP 9`
`FM_FLD_EDIT KP 4`
`FM_INS_LINE KP 5`
`FM_JOIN_FLD KP 6`
`FM_MARK KP 1`
`FM_MULTI KP 2`
`FM_PUT KP 3`
`FM_STATUS KP 0`
`FM_UNDO PF1`
`GO_DOWN D-Arrow`
`GO_LEFT BACKSPACE`
`GO_LEFT L-Arrow`
`GO_RIGHT R-Arrow`
`GO_UP U-Arrow`
`HELP PF4`
`INS_MODE KP -`
`INTERRUPT CTRL/C`
`NEXT_FLD TAB`
`NEXT_PAGE CTRL/D`
`PREV_FLD KP ENTER`
`PREV_PAGE CTRL/U`
`PRINTSCREEN CTRL/P`
`QUIT DELETE`
`REDRAW CTRL/R`
`RETURN LINEFEED`
`RETURN RETURN`
`SCROLL KP .`

Output Definition for Terminal: vt100
Outputset: vt100

`Output Name Output Sequence`
`bell ^G`
`clr eol cmd K`
`clr eow cmd J`
`cursor cmd $3 cvt ; $4 cvt H`
`done cmd ?1l cmd ?7h esc '>' cmd 24;1H crlf`
`down nl`
`graph off ^O`
`graph on ^N`
`graph set x sep x sep x sep q sep l sep m sep t sep`
`q sep k sep j sep u sep q sep w sep v sep n`
`index nl`
`init cmd ?1h cmd ?5l cmd ?6l cmd ?7l`
`esc '=' esc )0`
`left bs`
`region cmd $1 cvt ; $2 cvt r`
`rev index esc M`

Terminal Definition for: vt100

`right cmd C`
`up cmd A`

Video Definition for Terminal: vt100
Videoset: vt100

`Video Name Video Sequence`
`normal cmd m`
`reverse cmd 0;7m`

Application Video Definition for Terminal: vt100
Videoset: vt100

`Video Label Low Video Low Fill High Video High Fill`
`background normal normal`
`nohilite normal - normal -`
`normal normal - reverse`
`reverse reverse reverse -`
`warning reverse reverse`

Form-Edit Definition for Terminal: vt100
Videoset: vt100
Keyset: vt100

`Object Video Label Key`
`b normal +`
`f nohilite z`
`f normal n`
`f reverse r`
`v normal N`
`v reverse R`