# CHAPTER 5: Running Empress 4GL in X Windows (UNIX only)

## 5.1 Background

When you run Empress 4GL under X Windows, Empress 4GL is usually brought up in its own window (graphics mode). However, in some cases, we might want to run Empress 4GL inside a terminal emulator window such as `xterm` or `shelltool` in `tty` mode.

Here are some reasons why a user might want to do this:

1. You are running X Windows and dial in to another system through the modem to run Empress 4GL. (Usually you can't run an X client through a modem line.)
2. You are running X Windows and `rlogin/telnet` to another system which does not have X Windows support.
3. You are running X Windows and Empress did not port the X11 interface on your X client machine.
4. You are running X Windows and `rlogin/telnet` to another system which is painfully slow running X Windows applications.

## 5.2 Running Empress 4GL under xterm

The `xterm` program is a terminal emulator for the X Window System. It provides DEC VT102 compatible terminals for programs that can't use the window system directly, for Empress 4GL running in `tty` mode. In general, a good `xterm` program should behave like a VT102. The exception is the key mapping since most X terminal keyboards are different from VT102s.

In order to run Empress 4GL under `xterm`, there are some things to be considered:

1. We assume that `xterm` can display a VT100 screen properly. Some "bad" `xterm` programs may not be able to do this.
2. You need to fool the Empress 4GL program that your `xterm` is a real VT100. Usually, the `xterm` program can display a VT100 screen properly. However, your X Terminal usually does not have a keyboard which is exactly the same as the VT100 terminals. For example, an IBM 101 keyboard does not have PF1, PF2, PF3, PF4, and KP_comma keys. Therefore, you need to assign keys to act like these special keys. In order to change the keymap for an `xterm` program (rather than for the whole X server), you need to create an X resource file (this will be discussed later).

The real VT100 key sequences for some of the special keys are:
Table 5-1

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

The following steps are required to run Empress 4GL (`tty` mode) under `xterm`:

1. Run `xrdb -merge <xresource_file>` (optional).
2. Run `xterm -name <client_name>`. The size of the `xterm` window should be 24 rows x 80 columns, which usually is the default size of an `xterm` window. You can run `stty -a` to verify this. You should not resize the `xterm` window.
3. Login to the target system (`rlogin`, `telnet`, `tip`, `cu`, ...). (optional)
4. Run `setenv MSTERM vt100`.
5. Run Empress 4GL. You may need to run `emp4gl -t db` if your `DISPLAY` variable is set.

### 5.2.1 Create an X resource file for VT100 key emulation

Examples

X Terminal with 101 Keyboard

If your X Terminal has a 101 Keyboard, the keys, which the VT100 terminal has and your X terminal does not, are KP_comma, PF1, PF2, PF3, PF4. (assuming the other keypad keys have been mapped correctly by your X Server).

You can map:
Table 5-2

X Terminal key | VT100 key
`F1` | `PF1`
`F2` | `PF2`
`F3` | `PF3`
`F4` | `PF4`
`KP_Add` | `KP_comma`

The X resource file should look like this:

      101kb*VT100*translations: #override\

        <Key>F1: string(0x1b) string("OP") \n\

        <Key>F2: string(0x1b) string("OQ") \n\

        <Key>F3: string(0x1b) string("OR") \n\

        <Key>F4: string(0x1b) string("OS") \n\

        <Key>KP_Add: string(0x1b) string("Ol")

where `101kb` is the client name, `0x1b` is escape key.

You can create an X resource file and run `xrdb -merge <file>` or add these lines to a primary resource file (often called `.Xdefaults` or `.Xresources`) in your home directory. You can bring up an `xterm` program by running `xterm -name 101kb &`.

## 5.3 Running Empress 4GL Under a Shelltool

If you are running X Windows on a Sun Workstation and want to run Empress 4GL in `tty` mode, you should do the following:

1. Run `shelltool` (the X version and not the sunview version) instead of `cmdtool`. The size of the shelltool window should be 34 rows x 80 columns which usually is the default size of the shelltool window. You can run `stty -a` to verify this. You should not resize the shelltool window.
2. Login to the target system (`rlogin`, `telnet`, `tip`, `cu`, ...). (optional)
3. Run `setenv MSTERM sun`.
4. Run Empress 4GL. You may need to run `emp4gl -t db` if your `DISPLAY` variable is set.

See Also

`xterm(1)`, `shelltool(1)` (X version), `xrdb(1)`, X Window System User's Guide, `/usr/include/X11/keysymdef.h`

## 5.4 Modifying the 4GL Cursors in X Windows (UNIX only)

This section contains guidelines to enable you to modify the 4GL text cursor and pointer cursor in the X Windows version. The 4GL colormap is defined in `colormap.c` in the `custom` directory.

### 5.4.1 Text Cursor

The text cursor is displayed as a box and is a combination of a foreground (character) color and background (space) color. By default, these colors are the inverse of the colors of the character position on top of which the cursor is displayed. The colors of the text cursor can be modified by setting the variable `MS4GLXCURSORCOLOR` to a four-digit number. The first two digits identify a color in the 4GL colormap to be taken as the foreground color and the last two digits as the background color. For example, using the 4GL default colormap, a white cursor with red characters would be defined by the number 0100.

### 5.4.2 Pointer Cursor

The pointer cursor is displayed as a cross hair. By default, the foreground color is black and the background color is white. Also, most of the background has been eliminated by masking it out. The colors of the pointer cursor can be modified by setting the variable `MS4GLXPOINTERCOLOR` to a four-digit number similar to the way the text cursor is defined above.

The shaped of the pointer cursor can be modified by editing the files `pointer.ci` and `mask.ci` in the `custom` directory and executing `mkbins` followed by `mkexec` on the executables `emp4fulg` and `emp4rtg`. The `pointer.ci` file contains a bitmap defining the foreground and background pixels of a box shaped area that is the pointer cursor. The `mask.ci` file contains a bitmap indicating which pixels of the box shaped area are to be displayed. The `mask.ci` file is used to shape the pointer cursor by eliminating unwanted areas of the box. Both files should be edited using the X Windows command `bitmap`.