The COBOL Profiler | 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, mfinfocmp and termconv.
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 libscreen module translates these logical operations into the terminal-dependent physical character strings and escape sequences required by the attached terminal. The libscreen 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 libscreen 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 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. The default value for $COBDIR is /usr/lib/cobol or /opt/lib/cobol depending on the operating system. 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. It can be generated from IBM AIX format using the utility termconv.
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 controlling a terminal printer or 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 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 region s can be used to scroll areas of the screen that 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 |
The following entries are required for printer support:
Entry |
Mnemonic |
---|---|
Turn on printer. | mc5 |
Turn off printer. | mc4 |
Print screen. | mc0 |
Parameterized print string. | mc5p |
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 method can be used, for example, ANSI color terminal s. 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, 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.
Your Micro Focus COBOL system supports a number of calls that enable you to control a printer attached to your terminal. Using these calls, you can switch the printer on-line or off-line, print the current screen, and print a string of characters.
Using these calls can affect the portability of your application.
These calls cause the screen handling system to be initialized, if it is not already.
To switch the attached printer on-line or off-line, you need to add the following record to the Working-Storage Section of your program:
01 state pic x comp-x.
Then at run time you use the following call:
call "cobprt" using state
where the parameter is:
state |
Set to 0 to put the printer off-line or 1 to put the printer on-line. |
When the printer is on-line, all screen output goes to the printer; it can also show on your screen, but this is terminal dependent. You must be aware that the behavior of your terminal and printer, once you have set the printer on-line, is entirely hardware dependent.
The screen handling library sends various control codes to the terminal (for example, to position the cursor) that some terminals might pass to the printer, though this is undefined, as is the action the printer takes if these codes are passed to it.
Once the printer is placed off-line, the run-time system redraws the screen to ensure it is up to date, as the terminal might not have updated it during printer output.
If the printer is placed on-line by this call and the run-time system terminates, the run-time system automatically places the printer off-line.
Results of animating programs that make this call are undefined.
To print the contents of the current screen on the printer, you use the following call at run time:
call "cobprtscrn"
Although this call causes the screen handling system to be initialized, this call is pointless if the screen handling system has not already been initialized as it simply causes a blank screen to be printed.
To print a string of characters on the printer you need to add these records to the Working-Storage Section of your program:
01 strng pic x(100). 01 strng-length pic x comp-x value 100.
Then at run time you use the following call:
call "cobprtstring" using strng strng-length
where the parameters are:
strng |
A string that can contain only printable characters: control characters are not allowed. |
strng-length |
The number of characters to be output. |
This causes the string to be output to the printer, and possibly to the screen as well depending on the terminal.
After the completion of this call, the run-time system redraws the screen.
When using the above three calls, you must be aware of the following:
The calls described in the sections above require additional terminfo capabilities as shown below. The last column shows the behavior if the named capability is not present:
Call |
Capabilities Required |
Action if Not Present |
---|---|---|
cobprt 1 | prtr_on | The printer cannot be placed on-line. |
cobprt 0 | prtr_off | The printer cannot be placed off-line. |
cobprtscrn | print_screen | Trying to print the screen has no effect. |
cobprtstring | prtr_non | Trying to print a string has no effect. |
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 your operating system documentation, such as the AT&T, UNIX System V Release 4, "System Administrator's Reference Manual" in the entry for term(4). 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.
AIX:
The operating system AIX does not support the UNIX System V definition of
terminfo. This COBOL system only supports the UNIX System V terminfo
definition and so does not directly support the AIX system terminfo. On
AIX, the COBOL system can only use the portable terminfo, that by default
is located at $COBDIR/terminfo.
Terminfo entries that are held in the AIX system terminfo database can be converted to the portable terminfo format using the utility termconv that is included with this system for your convenience.
The command line for invoking termconv is:
termconv -i format -o format filename
-i format |
This option specifies the input terminfo file format
where format can be one of the following:
|
||||
-o format |
This option specifies the output terminfo file format
where format can be one of the following:
|
||||
filename |
This is the name of the file to be converted. This
original input terminfo file is saved as filename .bak
during the conversion. |
This section describes how you can use termconv to convert AIX terminfo format to UNIX terminfo format. The example shows how to convert a wy60 entry for a Wyse60 terminal.
You need to be logged in as root to do this.
mkdir $COBDIR/terminfo/w
mkdir /tmp/terminfo cd /tmp/terminfo
cp /usr/lib/terminfo/w/wy60 /tmp/terminfo/wy60
termconv -i aix -o unix wy60
cp /tmp/terminfo/wy60 $COBDIR/terminfo/w/wy60
Note: This new terminfo file is only used by the Micro Focus COBOL system.
Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
The COBOL Profiler | Micro Focus Environment Variables |