Descriptions of Run-time Switches | Micro Focus Environment Variables |
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.
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.
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.
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.
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.
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.
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:
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.
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.
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.
Entry |
Mnemonic |
---|---|
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.
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.
Entry |
Mnemonic |
---|---|
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.
For terminals that have additive attributes the following are used. Entries marked with an asterisk (*) should be set appropriately for the type of terminal:
Entry |
Mnemonic |
---|---|
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:
Entry |
Mnemonic |
---|---|
Set attributes | sgr |
Highlighting is also affected by the COBATTR environment variable. See the appendix Micro Focus Environment Variables for details.
The following optional entries can be included and can improve the performance of screen displays in some situations:
Entry |
Mnemonic |
---|---|
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:
Entry |
Mnemonic |
---|---|
Change scroll region | csr |
Insert line | il1 |
Delete line | dl1 |
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:
Entry |
Mnemonic |
---|---|
Initialize string 1 | is1 |
Initialize string 2 | is2 |
Initialize string 3 | is3 |
Reset string 1 | rs1 |
Reset string 2 | rs2 |
Reset string 3 | rs3 |
For terminals that have additive attributes the following are used:
Entry |
Mnemonic |
---|---|
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:
Entry |
Mnemonic |
---|---|
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.
Only the Tektronics color manipulation method can be used; for example, ANSI color terminals use the Tektronics method. The following entries are required:
Entry |
Mnemonic |
---|---|
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.
The following sections cover special terminal considerations.
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.
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
.
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:
Value |
Meaning |
---|---|
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:
Value |
Meaning |
---|---|
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.
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.
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. |
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. |
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:
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.
Descriptions of Run-time Switches | Micro Focus Environment Variables |