C3270/curses

From The x3270 Wiki

c3270 is based on the curses library.

curses is a library that allows an application to do input and output on a variety of character-mode terminals and terminal emulators. Different terminals and terminal emulators use various conventions for drawing text on the screen and for representing what keys have been pressed. The curses library insulates the application from the specifics of these conventions, and instead presents an abstracted interface. For example, the application tells curses to draw some text with a green foreground and a blue background at some particular screen coordinates, and curses translates that into the right sequence of characters to actually do that. Similarly, the user presses the F1 key, which generates a device-specific sequence of input characters, often beginning with the Esc (U+001B) key; curses delivers an input event to the application indicating that F1 was pressed.

In theory, this all works perfectly. In practice, it often does not.

Components

There are many moving parts in this process, and any of them can go wrong.

The terminal or terminal emulator

The terminal or terminal emulator may claim to be compatible with some industry-standard device, such as a DEC VT100 or an xterm. This might be true to some extent, but it might not be. Or the terminal might only implement a subset of the standard device's functionality. Or it might implement a different sub-model of the standard device than the one the author of the terminfo entry was using. Or it might emulate that device incorrectly.

The terminal name

curses decides what kind of device it is using based on a simple string: the terminal name. This name is usually stored in the TERM environment variable. The problem is that most terminal emulators allow the terminal name to be configured, and users can modify the value of TERM. This is great for ironing out issues with incorrect terminfo entries, but it is also another knob to set incorrectly. For example, by default the PuTTY terminal emulator uses a terminal name of xterm, while the most accurate terminal name for it is putty.

The terminfo database

Curses uses a database to map a terminal name to the set of characteristics of that terminal device. On most systems, that database is terminfo.

For a given terminal or terminal emulator, there may multiple terminfo entries that seem to work. Often finding the right entry involves some guesswork. For example, a real VT100, an xterm and the PuTTY emulator all use pretty much the same sequences to draw basic text on the screen, and to set basic text attributes such as bold. But more subtle actions, like line-drawing and color, and the sequences generated by function keys, differ quite a bit among them.

Also, the terminfo entry for your exact device might not actually be for that device; it could be for an older or newer version. It could also simply be wrong.

The curses library

A further complication is the curses library. The most common version of curses is ncurses, but there are others, and there are subtle incompatibilities between them.

There are also multiple versions of each library (older and newer), and variants of each. For example, ncurses comes in "narrow" and "wide" character variants. The "narrow" version may not be able to represent characters outside of the basic 8-bit ISO 8859 character sets. If c3270 is built with the "narrow" version, it will not be able to display Chinese or Thai.

The application

The final cause of issues is c3270 itself. Though relatively stable at this point, c3270 is by no means bug-free, and it may fail to operate correctly when faced with a terminal that operates differently than what it was designed for.

What goes wrong

Incorrect display

Here is an example of an incorrect display due to curses issues:

C3270-bad-line-drawing.png

This is a screen with the c3270 pop-up keypad displayed. The "lqqwqqwqqw" characters were supposed to be line-drawing characters, but instead they came out as text. Everything else seemed to work until the pop-up keypad was displayed.

Incorrect keyboard input

Here is an example of an input issue related to curses issues:

C3270-bad-input.png

The user pressed F1, but instead of getting the expected PF(1) action, junk appeared on the screen. This is because the sequence generated by the F1 key did not match the terminfo entry, and the sequence was interpreted by c3270 as a series of input characters.

Invisible text

C3270-invisible-colors.png

The c3270> prompt is displayed in blue, which is usually visible against either a black or a white background. Unfortunately, c3270 does not know if this is actually true. In this case, the terminal defines blue as an unusually dark color, and the default background color is a sort of dark gray. This renders the prompt unreadable.

The workaround for this, if possible, is to change either the background color or the RGB configuration for blue on the terminal.