   =========================================================================

                            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

=========================================================================

                     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)


   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 and mfinfocmp.                                           


   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.           


   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=<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.                                                      


   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.                                

=========================================================================   
   Micro Focus is a registered trademark of Micro Focus International       
   Limited. All other trademarks are the property of their respective       
   owners.
=========================================================================   
   @(#)Vrn/terminfo.txt/01Feb02/nrV
   Copyright (C) 1996-2002 Micro Focus Limited
