========================================================================= M I C R O F O C U S L I C E N S E M A N A G E M E N T F A C I L I T Y Va.b.cc ========================================================================= TERMINFO DATABASE AND TERMINAL DEVICES ====================================== This document should be used in conjunction with your Administrator's Guide. TABLE OF CONTENTS ================= OVERVIEW System Terminfo Portable Terminfo for COBOL CONFIGURING YOUR TERMINAL AND TERMINFO DATABASE Searching for the Portable or system terminfo Adding Terminal Details to Terminfo Additional Key Configuration Wyse Terminal Support PORTABLE TERMINFO UTILITIES mftic AND mfinfocmp Terminfo Compiler (mftic) Terminfo Lister (mfinfocmp) Converting terminfo Using termconv This appendix describes the detailed use and configuration of terminal devices for UNIX. It describes the terminfo database and the details you need include in it to enable the terminal features that License Management requires. The appendix also describes the Micro Focus terminfo utilities mftic, mfinfocmp and termconv. OVERVIEW ======== The License Management Facility makes sophisticated use of the UNIX terminal device for menus and non-scrolling forms. UNIX allows virtually any type of terminal device to be connected and provides a standard method for handling this diversity of terminals: 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. The terminal is an important and complex device that handles input/output (I/O): o Simple unformatted line I/O o Formatted full-screen field I/O, such as that used in the License Administration Services menu interface. For unformatted line I/O, the License Management Facility takes no special action. The logical UNIX devices stdin, stdout and stderr are used assuming that these are redirected by the operating system from or to the terminal. For formatted screen I/O, the License Management Facility takes action at the logical level and the physical level. The high-level requirements are translated into logical, low-level, terminal-independent operations. These logical operations are then translated into the terminal-dependent physical character strings and escape sequences required by the attached terminal. Also any response from the terminal is translated into logical form and is returned. To map the screen I/O between the logical and physical level, License Management 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. You provide this information by setting the TERM environment variable and by providing the details of your terminal in the terminfo database. The License Management Facility recognizes two types of terminfo database: o System terminfo database This is the standard UNIX System V terminfo format and structure, although the License Management Facility ignores any non-standard UNIX vendor-specific extensions. o Portable terminfo database for COBOL Some UNIX systems do not use the standard terminfo format and structure, and in this case the License Management Facility uses the alternative portable UNIX terminfo database. System Terminfo --------------- The system terminfo database is located in /usr/lib/terminfo or /usr/share/lib/terminfo, depending on the operating system. Terminfo 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, such as the License Management Facility, but frequently there is a conflict. The License Management Facility's terminal I/O is 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 License Management Facility. In addition, the terminfo database is sometimes modified to configure a non-COBOL application and so becomes unsuitable for use with a COBOL application. Portable Terminfo for COBOL --------------------------- The License Management Facility 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 portable terminfo database is held in the subdirectory terminfo of the directory where you installed the License Management Facility, $COBDIR. If your terminal is defined in another portable COBOL terminfo database, set the environment variable COBTERMINFO to point to it. Go to the directory where the terminfo is located and enter: COBTERMINFO=`pwd` export COBTERMINFO The portable terminfo database can be maintained using the utilities mftic and mfinfocmp that are described later in this appendix. It can be generated from IBM AIX format using the utility termconv. CONFIGURING YOUR TERMINAL AND TERMINFO DATABASE =============================================== So that the License Management Facility can correctly use your terminal's capabilities, you need to ensure that: o Your TERM environment variable is set to the terminal type you are using. See your UNIX documentation for how to set environment variables. o There is an entry for your terminal type in either the portable COBOL terminfo database or the system terminfo database. See your UNIX documentation for how to find out and add it if it is missing. o The terminfo entry for your terminal contains all the escape sequences match those generated by the appropriate terminal keys when in raw mode. The essential details for your terminfo entry are described later in this appendix. See your UNIX documentation for how to set terminfo entries. o The terminfo database that you are using can be found. By default the environment variables TERMINFO is set up to point to the system terminfo database, and COBTERMINFO to the portable COBOL terminfo database. See the section on searching for the terminfo database. Searching for the Portable or system terminfo --------------------------------------------- The License Management Facility 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 terminfo database that is specified by the environment until it finds details for that terminal. The License Management Facility searches first for a COBOL-specific terminfo file and if that is not found it searches for a system terminfo file. 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. You do not need to set any of the environment variables, as they are set automatically when you invoke the License Management Facility, the License Administration Services, or the command line interface. The License Management Facility searches for terminal details in terminfo files in the following order: 1. If the COBTERMINFO environment variable is not set, it is considered set to the subdirectory terminfo of the directory where you installed the License Management Facility, $COBDIR. In other words, it is 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. If neither environment variable is set, the system terminfo database is used, if it is found. 5. If the file is not found, an error is returned. Adding Terminal Details to Terminfo ----------------------------------- The License Management Facility run-time system depends on a terminfo database being available and providing various terminal details to support the License Management Facility. The run-time system regards some details as essential, and returns a run time error if they are not available. The License Management Facility tries to optimize the use of the terminal and uses some optional terminal capabilities if they are described in terminfo. The following tables list entries in a terminfo terminal description that are recognized by the License Management Facility. See your UNIX system documentation for details on the system terminfo database and how to specify terminal capabilities. Essential Details in Terminfo The following details must be present in the terminfo entry for your terminal for the License Management Facility 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 f10. * kf1 to kf10 Entries for backtab, insert and delete keys. * kcbt, kich1, kdch1 Exit attribute mode. sgr0 Number of columns. ** cols Number of lines. lines Xon/xoff. xon ------------------------------------------------------------------------- Optional Entries in Terminfo The following entries should be used if they are required for the particular type of terminal. However, the License Management Facility does not insist that they are present. ------------------------------------------------------------------------- Entry Mnemonic ------------------------------------------------------------------------- Bell. bel Carriage return. cr Entries for home, next page, previous page, end, and clear-to-end-of-field keys. * khome, knp, kpp, kend, kel Enter ca mode. smcup Exit ca mode. rmcup Keypad local. rmkx Keypad transmit. smkx ------------------------------------------------------------------------- Some terminals must have smcup and rmcup in order to work correctly. Highlighting Details in Terminfo 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: Set attributes. sgr ------------------------------------------------------------------------- Performance Considerations in Terminfo 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 that greatly speeds up such operations: ------------------------------------------------------------------------- Entry Mnemonic ------------------------------------------------------------------------- Change scroll region. csr Insert line. il1 Delete line. dl1 ------------------------------------------------------------------------- Line Drawing Details in Terminfo 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: 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 in Terminfo Only the Tektronics method can be used, for example, ANSI color terminals. 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 appendix 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 appendix 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. Additional Key Configuration ---------------------------- You might find that some keys do not function as expected or do not function at all. This could be due to inconsistencies between the system terminfo database, the absolute control sequences generated by some keys and the default full screen keys in the License Management Facility (for example, change case of character). The following work arounds might be useful: o If the Backspace key operates like the left arrow key, you can delete characters by overtyping them with spaces. o You can add extra terminal initialization sequences, by extending init_1string to include the appropriate sequences. See your terminal manual for further details on escape sequences. Control and Alt Key Support Some terminal facilities, such as Ctrl and Alt key support, are not automatically specified using the terminfo database. 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. As an alternative, you can: o Enter /a to simulate pressing or releasing the Alt key. o Enter /c to simulate pressing or releasing 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. Function Keys and COBKEYTIMEOUT On network-based UNIX systems, information is split into packets, and thus under certain conditions it is possible for part of a function key sequence to be split across two packets. This can lead to incorrect key recognition. This typically occurs while using the telnet or the rlogin commands. This product provides you with the COBKEYTIMEOUT environment variable, which you can use to determine the timeout between the arrival of the first key of a function or special key sequence and the arrival of the next. Setting this environment variable allows function key sequences to be recognized correctly. See your UNIX documentation for how to set environment variables. The timeout period, a value in the range 1 to 126, is dependent on the type of connection and the effective average baud rate. For example, ethernet connections should not require a value greater than 10. Using too small a value results in incorrect function and special key recognition; too large a value results in a delay when certain keys are pressed (such as Escape) unless they are followed by other keys (such as Escape). If the value of the COBKEYTIMEOUT environment variable is outside the range 1 to 126, null, non-integer or the variable does not exist, then a direct connection between the terminal and the machine is assumed. You could also use the COBKEYTIMEOUT environment variable to recognize function key sequences on terminals which do not send such sequences at the correct baud rate, but insert pauses between the characters instead. This environment variable is read once only, when the screen handling subsystem is initialized. Changing its value after this has no effect. Wyse Terminal Support --------------------- The License Management Facility 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. 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 file-name. 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. The License Management Facility 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 Micro Focus utilities mftic and mfinfocmp in place of the system utilities tic and infocmp. Both Micro Focus utilities can operate in the following two modes: o Micro Focus format mode o UNIX vendor-specific format mode 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 License Management Facility 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 details required by the License Management Facility, see the section Essential Details in Terminfo earlier in this appendix. 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= entry in a source file, mftic tries to augment the current terminal description with the description of the terminal . mftic first searches for in the current source file and if not found it searches the compiled terminfo database. If is still not found then mftic reports an error and stops. mftic recursively follows use= links if necessary. Invoking mftic 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 Portable Terminfo Utilities mftic and mfinfocmp earlier in this appendix. 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. Terminfo Lister (mfinfocmp) --------------------------- The mfinfocmp utility performs either of the following functions: o Lists a terminfo source description from the specified binary file o Compares two or more terminfo binary files. 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. Invoking mfinfocmp 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 file-names 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 search sequence defined in the section Searching for the Portable or System Terminfo earlier in this appendix. Converting terminfo Using termconv ---------------------------------- The operating system AIX does not support the UNIX System V definition of terminfo. The License Management Facility supports the UNIX System V terminfo definition only and so does not directly support the AIX system terminfo. On AIX, the License Management Facility can use the portable terminfo only, that by default is located in the subdirectory terminfo of the directory where you installed the License Management Facility, $COBDIR. In other words, it is located in $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. Invoking termconv The command line for invoking termconv is: termconv -i format -o format filename Description ----------- -i format This option specifies the input terminfo file format where format can be one of the following: aix Input file is an IBM AIX terminfo file unix Input file is a UNIX SVR3/SVR4 terminfo file -o format This option specifies the output terminfo file format where format can be one of the following: aix Output file is an IBM AIX terminfo file unix Output file is a UNIX SVR3/SVR4 terminfo file filename This is the name of the file to be converted. This original input terminfo file is saved as filename.bak during the conversion. Example of Using termconv 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. 1. Using the first letter of the terminfo entry name for the terminal (wy60 in this case), create a terminfo directory under $COBDIR/terminfo if one does not exist already: mkdir $COBDIR/terminfo/w 2. Create a temporary directory and make it the current directory: mkdir /tmp/terminfo cd /tmp/terminfo 3. Copy the existing wy60 AIX terminfo file to your temporary directory: cp /usr/lib/terminfo/w/wy60 /tmp/terminfo/wy60 4. Run the Micro Focus conversion utility to convert the AIX specific terminfo file format, to generic UNIX System V format: termconv -i aix -o unix wy60 5. Copy the new file into the COBOL terminfo directory: cp /tmp/terminfo/wy60 $COBDIR/terminfo/w/wy60 Note: This new terminfo file is only used by the Micro Focus COBOL system. ========================================================================= Micro Focus is a registered trademark of Micro Focus Limited. OS/2 is a registered trademark of International Business Machines Corporation. Windows is a registered trademark of Microsoft Corporation. ========================================================================= @(#)Vrn/terminfo.txt/02Sep96/nrV Copyright (C) 1996 Micro Focus Limited