PreviousDescriptions of Run-time Switches Micro Focus Environment VariablesNext

Chapter 16: Terminfo Database and Terminal Devices

Interactive COBOL applications rely heavily on sophisticated use of the terminal device for full-screen input and output, using the ACCEPT and DISPLAY statements. UNIX allows virtually any type of terminal device to be connected and provides the terminfo database as a means for handling the diversity of terminals. This chapter describes how the terminfo database is used by your COBOL system and what details need to be included in the database to enable COBOL to use particular terminal features. The chapter also describes the Micro Focus terminfo utilities mftic and mfinfocmp.

The chapter Device Handling in your Programmer's Guide to Writing Programs discusses devices in general including terminal devices. This chapter describes the detailed use and configuration of terminal devices for UNIX.

16.1 Overview

The terminal is perhaps the most important and complex device that a typical COBOL program uses. It can be used in two ways:

For unformatted screen I/O, the COBOL system takes no special action. It simply uses the logical UNIX devices stdin, stdout and stderr (see the chapter Device Handling in your Programmer's Guide to Writing Programs) assuming that these are redirected by the operating system from or to the terminal.

For formatted screen I/O, the COBOL system has to take action at two levels: the logical level and the physical level. The Adis module (see the chapter Adis in your Programmer's Guide to Creating User Interfaces) translates the high-level COBOL requirements into logical, low-level, terminal-independent operations. The screen handling module translates these logical operations into the terminal-dependent physical character strings and escape sequences required by the attached terminal. The screen handling module also translates any response from the terminal into logical form and returns it to the Adis module.

To carry out the mapping between logical and physical form, the screen handling module needs to know the type of terminal that is attached, the capabilities of that terminal type and the physical format of any I/O activity. UNIX provides a standard method for providing this information; the environment variable TERM contains the name of the terminal type, and the details for that terminal type are held in a UNIX system database, known as terminfo.

16.1.1 System Terminfo

Your COBOL system can understand and use the standard UNIX System V terminfo format and structure, although it ignores any non-standard UNIX vendor-specific extensions. Some UNIX systems do not use the standard terminfo format and structure and in this case your COBOL system uses the alternative portable UNIX terminfo database described below.

The system terminfo database is located in /usr/lib/terminfo on most platforms and is available for general use by any system application, a typical example being the system editor vi. If a particular process requires use of an alternative general terminfo database, then this can be selected by specifying its location in the environment variable TERMINFO.

The terminal details are held in a terminfo database for general use by non-COBOL applications. They can be made suitable for use by COBOL applications but frequently there is a conflict. COBOL terminal I/O is generally more sophisticated than that of most UNIX applications and has more stringent minimal requirements of the terminfo database. The precise meaning of some the terminal information can be ambiguous and sometimes the terminfo database reflects an interpretation that differs from that made by the COBOL system. In addition, the terminfo database is sometimes modified to configure a non-COBOL application and so becomes unsuitable for use with a COBOL application.

16.1.2 Portable Terminfo for COBOL

This COBOL system supports the use of a portable UNIX terminfo database and provides one that includes details for a selection of terminals. The format follows the UNIX specification but omits the UNIX vendor-specific portions. The database can be used by COBOL applications as an adjunct or alternative to the system databases. The system COBOL terminfo database is held in the directory terminfo in the COBOL system directory $COBDIR. If a particular COBOL process requires use of an alternative COBOL terminfo database, then this can be selected by specifying its location in the environment variable COBTERMINFO

The portable UNIX terminfo database can be maintained using the utilities mftic and mfinfocmp that are described later in this chapter.

16.1.3 COBOL Screen Handling Requirements

When COBOL provides formatted field input and output on the terminal, it carries out some sophisticated screen handling compared to many UNIX applications. Certain terminal capabilities must be available and described in the terminfo entry referenced by TERM otherwise the run-time system gives a run-time error.

Your COBOL system tries to optimize the use of the terminal and uses some optional terminal capabilities if they are described in terminfo. Required and optional terminal terminfo details are described later in this chapter.

16.2 Special Terminal Facilities

Some terminal facilities, such as Ctrl and Alt key support, are not automatically specified via the terminfo database. Other facilities such as wide terminal mode are specified via the terminfo database but are not part of the standard COBOL screen I/O. These special facilities are described later in this chapter.

16.3 Searching Portable and System Terminfo Databases

The COBOL system recognizes two types of terminfo database: the portable terminfo for COBOL and the system terminfo. When it requires details for a terminal it searches each database that is specified by the environment until it finds details for that terminal.

The COBOL system searches first for a COBOL-specific terminfo file and if that is not found it searches for a system terminfo file (see steps below). Non-COBOL utilities such as vi only search for a system terminfo file.

For a particular terminal, COBOL applications and non-COBOL applications such as vi can have different requirements for a terminfo file. Not only can different entries be required but also they can require different binary formats. COBOL might require a portable format and non-COBOL requires a system-specific format.

It is important to distinguish between general terminfo files and COBOL-specific terminfo files (examples provided with this system), to place them in separate locations and at run time to set up the environment variables COBTERMINFO (see the appendix Micro Focus Environment Variables) for the COBOL-specific files and TERMINFO for the system or general terminfo files as appropriate. The COBOL system then searches for a terminfo file using the following steps:

  1. If the COBTERMINFO environment variable is not set, it is considered set to $COBDIR/terminfo.

  2. If COBTERMINFO is set, it is read as a set of colon-separated paths to the terminfo database. If the required file is found on any of the paths (parsed from left to right), then it is used.

  3. If the TERMINFO environment variable is set, it is used as a path to the terminfo database. If the file is found, it is used.

  4. Use the default system terminfo database, usually/usr/lib/terminfo, as the path to the terminfo database. If the file is found here, it is used.

  5. If the file is not found, an error is returned.

16.4 Terminal Devices

UNIX environments support virtually any terminal type, terminal definitions being held in a system database. This database must contain enough details for the terminal being used in order that Adis can function.

Adis uses the standard input and output device interfaces for terminal I/O and so such terminal I/O can be redirected but with the restriction that you must not redirect standard input from a file unless it is a terminal device.

So, for example, the following is legal:

cobrun prog < `tty` >`tty`

(use the appropriate (`) character) whereas redirecting the input from an ordinary file or /dev/null is not legal and could result in a run time error.

16.4.1 Screen Handling Requirements

The COBOL run-time system depends on a terminfo database being available and providing various terminal details to support the Adis module. The run time system regards some details as essential, and returns a run time error if they are not available. It regards all others as optional (making use of many of them and ignoring the rest). The following tables list entries in a terminfo terminal description that are recognized by the COBOL system. See your UNIX system documentation for details on the system terminfo database and how to specify terminal capabilities.

16.4.2 Essential Entries

The following entries must be present for the Micro Focus COBOL system to operate correctly. Entries marked with an asterisk (*) should be set appropriately for the type of terminal.

Auto right margin * am
Clear to end of line el
Clear screen clear
Clear to end of screen ed
Cursor address (row, column) cup
Cursor down cud1
Cursor home home
Cursor left cub1
Cursor right cuf1
Cursor up cuu1
Eat newline glitch * xen1
Entries for cursor keys kcud1, kcub1, kcuf1, kcuu1
Entries for function keys
f1 to f63 *
kf1 to kf63
Entries for home, next page,
previous page, end, backtab,
insert, delete and
clear-to-end-of-field keys *
khome, knp, kpp, kend, kcbt, kich1,
kdch1, kel
Exit attribute mode sgr0
Number of columns ** cols
Number of lines ** lines
Xon/xoff * xon

** The number of lines and columns will be read dynamically if using an X terminal, or can be overridden using the environment variables LINES and COLUMNS. See the appendix Micro Focus Environment Variables for details.

16.4.3 Optional Entries

The following entries should be used if they are required for the particular type of terminal. However, the Micro Focus COBOL system does not insist that they are present.

Bell bel
Carriage return cr
Enter ca mode smcup
Exit ca mode rmcup
Keypad local rmkx
Keypad transmit smkx
Move safely in standout mode (if appropriate) msgr

Some terminals must have smcup and rmcup in order to work correctly. Highlighting

For terminals that have additive attributes the following are used. Entries marked with an asterisk (*) should be set appropriately for the type of terminal:

Enter blink mode * blink
Enter bold mode * bold
Enter dim mode * dim
Enter reverse mode * rev
Enter underline mode * smul

For terminals that do not have additive attributes, the following is needed:

Set attributes sgr

Highlighting is also affected by the COBATTR environment variable. See the appendix Micro Focus Environment Variables for details. Performance Considerations

The following optional entries can be included and can improve the performance of screen displays in some situations:

Parameterized cursor down cud
Parameterized cursor left cub
Parameterized cursor right cuf
Parameterized cursor up cuu

If the following entries are present, scroll regions can be used to scroll areas of the screen, which greatly speeds up such operations:

Change scroll region csr
Insert line il1
Delete line dl1 Wide Terminal Mode

If you want to use wide terminal mode, you must ensure that the sequence to set the number of columns appears in one of the following entries:

Initialize string 1 is1
Initialize string 2 is2
Initialize string 3 is3
Reset string 1 rs1
Reset string 2 rs2
Reset string 3 rs3 Line Drawing

For terminals that have additive attributes the following are used:

Enable alternate character set enacs
Alternate character set characters acsc
Enter alternate character set smacs
End alternate character set rmacs

For terminals that do not have additive attributes, the following is needed:

Set attributes sgr

If you do not specify the appropriate alternate character set characters for your terminal, or your terminal does not provide a complete set, normal ASCII characters are substituted for the missing line drawing characters. Color

Only the Tektronics color manipulation method can be used; for example, ANSI color terminals use the Tektronics method. The following entries are required:

Number of colors colors
Set foreground setf
Set background setb
Original colors oc
Original pairs op

Only one of oc or op needs to be specified, but it must reset to the default colors.

Check that these entries are included in your terminfo database by running the mfinfocmp utility. See the section Terminfo Lister (mfinfocmp) in this chapter for details.

Should you require, you can add entries to your terminfo database by running the operating system utility tic See your operating system manuals for details of how to do this. Alternatively, you can create a new set of COBOL-specific terminal details in a COBOL-specific terminfo database using the mftic utility. See the section Terminfo Compiler (mftic) in this chapter for details.

Notes: If you use an attribute that is defined in your terminfo, but your terminal does not recognize it, the attribute is not displayed and no error message is given.

Any attributes in ACCEPT or DISPLAY statements are automatically disabled by the run-time system if your terminal uses character positions to store attributes. This is the case for terminals that support the magic cookie glitch; that is, terminals that have "xmc" defined in their terminfo file.

16.5 Special Terminal Facilities

The following sections cover special terminal considerations.

16.5.1 Wyse Terminal Support

Your Micro Focus COBOL system supports terminals, such as Wyse terminals, whose escape sequences are prefixed with a character other than escape (0x1b). The cursor and function keys are fully operable.

16.5.2 Control and Alt Key Support

Most UNIX terminals are not capable of detecting the Alt, Ctrl and a number of other keys (such as Shift) when they are pressed alone. Therefore, an alternative is provided. Enter /a to simulate the depression or release of the Alt key. Enter /c to simulate the depression or release of the Ctrl key

To use the forward slash character, enter it twice: //. To get help on these and other keyboard mappings, enter /m. See the appendix UNIX Key Usage Chart for a list of keystroke mappings.

If your UNIX system supports the use of Alt and Ctrl keys (for example, SCO Open Desktop from Version 2.0 onwards) you should use the detect_alt_ctrl run-time configurable option. See the chapter Run-time Configuration for information on detect_alt_ctrl.

16.5.3 Wide Terminal Mode

This facility is for use with COBOL only, and enables you to use a wide mode if it is supported on your terminal; for example vt100 style terminals have a 132 column mode. All normal methods of screen output are allowed including ANSI DISPLAY, Adis DISPLAY and the cobprintf() call. See the chapter Adis in your Programmer's Guide to Creating User Interfaces for details. Cursor addressing must be consistent with the current terminal mode. For example, if you ask Adis to position the cursor at column 100 while in 80 column mode, this is not successful, neither does it cause an automatic switch from normal to wide mode. Wide mode must be set explicitly as shown below.

To use this facility you must include a record in the Working-Storage Section of your program as follows:

01 mode-number pic x comp-x.

then at run time you use the following call:

call "cobtermmode" using mode-number

where mode-number can have one of the following values:

0 Standard terminal mode. The standard terminal terminfo file is used.
1 Wide terminal mode. The standard terminal name suffixed by -w is the name of the terminfo file used.

The value of RETURN-CODE is set to zero if the call completes successfully. It is set to non-zero if the call fails, for example if the required terminfo file cannot be found. The method of searching for terminfo is described in the earlier section Searching Portable and System Terminfo Databases.

If the call is successful, the screen handling system is initialized (if it was not already) and:

As the screen handling system is now initialized, all DISPLAY statements now use it, including ANSI DISPLAY statements.

If the call fails, the RETURN-CODE is nonzero and the screen does not change. The RETURN-CODE is set as follows:

0 Operation successful.
1 The terminfo file has not been found, is not readable, is corrupt or there is not enough memory.
2 The terminfo file does not contain one or more of the required capabilities.
3 The environment does not support the requested code.

When using the cobtermmode call, you must be aware of the following:

To cause the terminal to switch states, six terminfo facilities are used:

Full Name
Abbreviated Name
init_1string is1
init_2string is2
init_3string is3
reset_1string rs1
reset_2string rs2
reset_3string rs3

These are fully documented in the AT&T UNIX System V Interface Definition (SVID) and are used as follows:

Ensure that the terminal mode and terminfo specified by the terminal name in TERM match when you run an application.

16.6 The Portable Terminfo Utilities mftic and mfinfocmp

The UNIX operating system enables applications to handle terminal I/O from any terminal attached to the system, though each terminal can be of a different type with different capabilities. It does this using a database of terminal types, the terminfo database, that includes a file for each type of terminal. Each terminfo file holds details of the capabilities of the terminal-type identified by the filename. The details are stored in a machine-readable, compiled format that is specified in the entry for term(4) in your operating system documentation. The specification includes an initial generic portion and allows for a subsequent vendor-specific portion.

Each vendor's UNIX generally provides a utility, tic, that creates a terminfo file from human-readable parameters given in a terminfo "source" file and a utility, infocmp, that creates a terminfo source file from a compiled terminfo file. Both utilities assume the vendor-specific format for the terminfo file.

This COBOL system uses the terminfo database to handle any terminal I/O that your applications require. It uses the generic portion of the terminfo file and ignores any vendor-specific portion. It uses only some of the terminal capabilities that can be specified; some are mandatory and some are optional.

Two machines running UNIX from two different vendors and having identical terminal types attached can run the same COBOL application. This COBOL system can use an identical terminfo file on each machine. However, it can be difficult to exploit this capability if a UNIX vendor does not conform to the standard for the generic portion of the terminfo file or if a UNIX vendor adds a vendor-specific portion to the terminfo file that is inconsistent with that from other vendors.

You can solve this problem by using the COBOL system utilities mftic and mfinfocmp in place of the system utilities tic and infocmp. Both COBOL utilities can operate in the following two modes:

Micro Focus mode assumes that the terminfo file format comprises only the standard generic portion of the specification and that only the capabilities recognized by this COBOL system are present. This format is fully portable between different versions of UNIX; however, it might not include all the capabilities required by non-COBOL applications.

UNIX vendor-specific mode assumes that the terminfo format is fully compatible with the system tic and infocmp utilities. This format is generally not portable between different versions of UNIX, but it does enable you to define all the capabilities available to non-COBOL applications.

For a detailed description of the terminfo source and binary formats, including the list of capabilities your environment supports, see your operating system documentation. For a list of essential terminal capabilities required by the Micro Focus COBOL system, see the section Screen Handling Requirements earlier in this chapter.

16.6.1 Terminfo Compiler (mftic)

The terminfo compiler, mftic, translates a terminfo source file from the source format to the compiled format, that is placed in a terminfo database. See the section Search Sequence for details of how this database is located.

mftic is compatible with tic. By default, mftic produces terminfo binaries in a Micro Focus generic format. It can also produce terminfo binaries in the same format as the system format.

mftic supports the concept of use= links, as tic does. When it encounters a use=name entry in a source file, mftic tries to augment the current terminal description with the description of the terminal name. mftic first searches for name in the current source file and if not found it searches the compiled terminfo database. If name is still not found then mftic reports an error and stops. mftic recursively follows use= links if necessary.

The command line to invoke mftic is:

 mftic [-vn] [-c] [-m] [-S] filename

where the parameters are:

-vn Specifies whether or not the compiler gives verbose messages. The value of n is one of:
0 - suppress all messages
1 - give verbose messages
-c Prevents the creation of terminfo binaries. When this option is used, mftic only checks the input source file for errors (it does not check use= links for errors).
-m Produces terminfo binaries in Micro Focus format rather than in the UNIX vendor-specific format. These formats are described in the section The Portable Terminfo Utilities mftic and mfinfocmp earlier in this chapter. This is the default.
-S Treats the input binary as UNIX vendor-specific format rather than in the Micro Focus format.
filename The name of the terminfo source file to be compiled.

16.6.2 Terminfo Lister (mfinfocmp)

The mfinfocmp utility performs either of the following functions:

The binary, compiled, files must be held in a terminfo database. See the section Search Sequence for details of how this database is located if the -A or -B options are not set.

The command line for invoking mfinfocmp is:

mfinfocmp [-1] [-m] [-w n] [-A dir] [-B dir] [-S] 
    [filename [...]]

where the parameters are:

-1 (Numeric one, not a lower case "L") Outputs the results in single-column format.
-w n Limits the width of the output to n characters. The default value of n is 60.
-m Treats the input binary file as Micro Focus format, that is, a file produced by mftic with the -m option set. Results are undefined if this option is used to list a terminfo file in system format. This is the default.
-A dir
-B dir
Changes the location of the terminfo database when comparing two or more files. The -A option changes the database location for the first file to the directory specified. The -B option changes the database location for the second and subsequent files to the directory specified. (Note that the binary files do not usually reside in the same directory as the database. For example, the file containing details for the vt100 terminal typically resides in a subdirectory v in the database.)
-S Treats the input binary as UNIX vendor-specific format rather than Micro Focus format.
filename Either the name of the terminfo binary file to be listed or the names of the terminfo binary files to be compared. The function performed depends on the number of filenames specified on the command line as follows:

If no file is specified, mfinfocmp takes the name held in the TERM environment variable and lists that file's terminfo source description

If one file is specified, mfinfocmp lists the given file's terminfo source description

If two or more files are specified, mfinfocmp compares the first file with the second and subsequent given files. Search Sequence

mftic produces, and mfinfocmp lists, compiled format terminfo files for a terminfo database. Unless an option is specified to override it, by default, the directory containing the database is located using the following search sequence:

  1. If the COBTERMINFO environment variable is set, its contents are taken to be the directory name.

  2. If the TERMINFO environment variable is set, its contents are taken to be the directory name.

  3. If neither environment variable is set, the default directory used depends on whether or not the -m option is specified. If -m is specified then the directory $COBDIR/terminfo is used; if it is not specified then /usr/lib/terminfo is used. See the sections Invoking mftic and Invoking mfinfocmp earlier in this chapter for details on the -m option.

Note: If Micro Focus format terminfo files are placed in a database located in a directory other than $COBDIR/terminfo, then at COBOL application run time you must use the COBTERMINFO environment variable (rather than the TERMINFO environment variable) to locate this directory. If you do not do this, either COBOL or non-COBOL applications can fail to run correctly.

Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousDescriptions of Run-time Switches Micro Focus Environment VariablesNext