-------------------------------------------------------------------------------

 CPI V3.03 Copyright (C) 1995-1996 by Axel C. Frinke & Matthias Paul
 Analyzer utility for .CPI DOS codepage files.

 This version of CPI.EXE is FreeWare. All rights reserved. No warranties.

 Written by Matthias Paul       <MPaul@ibh.rwth-aachen.de>
            Ubierstrae 28     
            D-50321 BRHL
            GERMANY

 Instead, you can also contact codeveloper and friend of mine, Axel C. Frinke:
 <ACFrinke@uni-bonn.de> or <Frinke@cs.bonn.edu>.

 Updates:

 - Axel C. Frinke's web home-page:
   URL: http://www.rhrz.uni-bonn.de/~uzs180/mpdokger.html
                                   [^ ASCII-126, tilde]
 - Universitt Stuttgart:
   URL: ftp://ftp.uni-stuttgart.de/pub/systems/pc/util/system/cpi???.zip
                                           where ???=version number, e.g. 303.
 - Free-DOS FTP/WWW sites:
   URL: ftp://sunsite.unc.edu/pub/micro/pc-stuff/freedos/incoming/cpi???.zip
   
 Last edit: 18.07.1996 -mp

 DISCLAIMER:
 THIS MATERIAL IS PROVIDED "AS IS". USE AT YOUR OWN RISK. NO WARRANTIES,
 NEITHER EXPRESSED NOR IMPLIED. I cannot be held responsible for any 
 problems caused by use or misuse of the software and/or information.


-------------------------------------------------------------------------------

 I. INTRODUCTION:
 ================

 The CPI.EXE utility can be used to analyze .CPI files in many different ways.

 It adapts to the internal .CPI structure's format (standard display, standard
 printer, and DRFONT compressed format, each in different flavours) and
 displays any valuable information from the file. Additionally, CPI.EXE is
 able to recompile and extract the font data contained in the .CPI file in
 different ways. These font data files can be edited by common font editors.
 Also, using these font and lookup table files, you are now able to create 
 your own .CPI files. (Note, that CPI.EXE itself currently is not to compile
 new .CPI files. This might be added at a later stage.)

 A description of the .CPI file format (derived from debugging and examination
 sessions of multiple original .CPI files from different DOSes) can be found
 in the attached file CPI.LST.

 A description of CUI_LIB features (the Console-User-Interface library,
 CPI.EXE was compiled with) can be found in CUI_LIB.PAS. This is subject
 to be improved.

 Some important notes on CUI_LIB:

   On slow machines, if you notice a very long delay at startup (especially
    when using DESCRIPT.ION files), try setting a special environment variable
    to avoid this:

     SET CUI=On        Default, multilingual string processing.
                       Recommended for faster 486+.
     SET CUI=Fast      Much faster, but only English strings.
                       Recommended for 286, 386 and slower 486.
     SET CUI=Off       Even more faster, but reduced functionality
                       (of CUI_LIB, not CPI.EXE).
                       Recommended for slow XTs and 286 only.

    If CUI is not set to any of these values, CUI_LIB will show an informal
    message at startup. (Currently, I recommend compiling CUI_LIB with symbol
    FAST setting default to CUI=FAST. The .EXE files shipped in the archive
    are compiled this way.)

   If you experience unusual problems with ANSI escape sequences,
    you can solve them by special environment variables settings:

     SET ANSI=On/Off   Default is a very good autodetection.
     SET _ANSI=On/Off  See CUI_LIB.PAS for details.

   By default, CUI_LIB takes advantage of long commandlines via %CMDLINE%,
    automatically recognizing it's method of usage (4DOS/NDOS or MS-DOS 7
    COMMAND.COM). Also, filenames can be given in LFN-notation and will
    be converted to their equivalents in 8.3 format, utilizing LFN-support
    and TRUENAME. You can override this with

     LFN=On/Off        Default is <On>.
     LCMD=On/Off       Default is automatic detection.
     TRUENAME=On/Off   Default is <On>.

   There are more than 30 directives like this for various system settings.
    Have a look at the CUI_LIB documentation for details.


 Please report any comments, news, changes, problems or bugs to me.

  Have fun,

   Matthias


-------------------------------------------------------------------------------

 II. USING CPI (and CUI_LIB):
 ============================

 Syntax: CPI [@] [/?] [/Help] [/!] [/About]
             [/Cpifile[=filespec]] [/Report[=filespec]] [/Verbose[=0..5]]
             [/Fonts[=filespec]] [/Drfonts[=filespec]]
             [/Map[=filespec]] [/Lut[=filespec]] [/Overwrite] [?|&]

 Details on these parameters are described later on. First, some words on
 calling conventions: As those calling parameters are processed by CUI_LIB
 routines, you are relatively free in calling syntax and system configuration.


 II.1. CUI_LIB conventions:
 ==========================
 
 A short summary of basic conventions:
 (for more detailed info have a look at CUI_LIB.PAS)

 - Parameters generally should be introduced with the current SwitChar.
   (SwitChar is optional in most situations.)
   The SwitChar setting defaults to '/', if no other SwitChar was specified.
   Normally, beside the current SwitChar, '/' and '-' will also be accepted.
   The systems SwitChar setting can be overridden by environment variables,
   and/or by description file settings (Details can be found in the CUI_LIB
   documentation).

   E.g. /Help Help -Help  (and e.g. $Help, if '$' was the SwitChar) are
        handled the same.

   Examples to change the SwitChar (using CUI_LIB):

    If a DOS version supports the SwitChar API (MS-DOS/PC-DOS 2.xx-4.xx,
     Novell DOS 7, OS/2), change the current SwitChar by one of the common
     utilities, e.g. SWITCHAR.COM/EXE. Applications using CUI_LIB (such as
     CPI.EXE) and many others adapt to the new setting. With MS-DOS 2.xx
     (only) you can use CONFIG.SYS SWITCHAR= directive to change SwitChar.

    The current SwitChar can be overridden by an environment variable
     (no matter, if DOS actually supports SwitChar API or not), e.g.

      SET SwitChar=-

     Note, that this is a feature of CUI_LIB, not the command processors
     or the OS kernels and thus will work with or without SwitChar API
     support.

    This can be overridden by an entry in the % section of a description
     file, e.g. DESCRIPT.ION (4DOS/NDOS is not neccessary for this).

     Contents of a DESCRIPT.ION file (one line for each file):

      ... 
      CPI.EXE Analyzer utility for .CPI files% SwitChar=-
      ...

     Normally, these lines only contain the file name plus description text.
     If an ASCII-4 followed by an ID char is appended to the line, any data 
     following (up to CR/LF) is ignored by 4DOS/NDOS and can be used for
     configuration data. Multiple configuration records can be stored in
     a line. The maximum length of a line is 4096 chars (for 4DOS/NDOS), but 
     CUI_LIB currently can only handle lines shorter than 255 chars. 
     Three configuration IDs have been reserved by us for CUI_LIB purposes
     ('%' for pseudo-environmental strings, '>' for default command line
     arguments, and '#' for multiple kinds of extended file 'attributes'),
     see CUI_LIB.PAS for details.

 - Parameters will also be accepted when giving only the first character(s)
   of the full parameter string, downto the minimal length, that is indicated
   by capitalized letters (and, with ANSI enabled, highlighted) in the help
   screen. These are the characters, that are necessary, to decide the string
   from other parameters. Parameter scanning itself is not case sensitive.

    E.g.  /H /HE /HEL /HELP /h /he /hel /help /Help, /Hilfe etc.
   
   are all handled the same.

 - Normally, parameters not having special values assigned to them, will
   accept an optional list of 'Yes'/'No' strings, characters or values to
   actually acknowledge the parameter or igore it, as if it was not given.

   The current settings of theses strings are itself configurable by 
   environment variables, description file entries and system defaults. 
   Details can be found in the CUI_LIB documentation. When not giving such 
   a boolean value, 'Yes' is assumed automatically (e.g. /Help => /Help=Yes,
   but /Help=No will disable the /Help parameter, as if it was not given).

 - Parameters, that do accept values (other than those default 'Yes'/'No'-
   values), do accept these values in almost any notation (pre- and postfixes)
   and base (decimal, hex, octal, binary, character, string). If strings are 
   accepted, the syntax depends on their purpose, but generally all useful 
   abbreviations should not be a problem. Example:

    /Verbose=1

   Some examples for numeric values (100 decimal, here):

    Decimal strings:  100 #100 100d &D100
    Hex strings:      $64 x64 0x64 &H64 64h 064h 064$
    Binary strings:   %1100100 0%1100100 1100100b &B1100100
                      Instead of the usual ['0','1'] digits,
                      ['L','H'] or ['F','T'] are also accepted,
                      but shouldn't be mixed.
    Octal strings:    @144 144o &O144
    Characters:       'd' "d" "ab"
    Environment vars (SET test=100): %test%
    Ext. command line params: e.g. CPI.EXE /HELP=%2% 100

 - Using CUI_LIB generally nested environment variables and startup parameter
   evaluation is provided. A complete default parameter line can also be given
   both ways, as environment variable and/or description file entry.

    SET Yellow=Green
     CPI.EXE

    DESCRIPT.ION file (description for the executable file itself):

     CPI.EXE Analyzer utility % Yellow=Green White=%Yellow% > /help=%help%

    DESCRIPT.ION file (default description for the whole directory):

     . % Yellow=Green SwitChar=/

    SET CPICMD=/?
     CPI.EXE

 - In the command line, environment variables can be given within '%'-chars
   (e.g. %var%). Note, that these chars must be doubled when using this at
   the prompt (e.g. %%var%%). Environment variables can be part of other
   parameters. Some variables have special functions: %0%..%9% etc. can be
   used same as in batchjobs (but more than 9 parameters are supported).
   %?% will prompt for input. Optionally you can display a user-definable
   text with %?"text"% and additionally give a default-value to be used when
   answering with <Return>: %?"text"default%. To give a default value without
   optionally text, use: %?""default% instead.
   In output-redirection, %?% is ignored and, if no default value is given,
   replaced by a zero-string.

 - Override for long commandlines:

   When giving long command lines and %LCMD% is enabled, CUI_LIB will take
   advantage of %CMDLINE%, using an automatic recognition method to work fine
   with 4DOS, NDOS and MS-DOS 7 COMMAND.COM. In rare situations (shelling out),
   you may need to temporarily disable any usage of %CMDLINE%. All you need
   to do for overriding is to place a single '@' character as first parameter
   of the command line (this '@' is neathly skipped over in further command
   line processing).
 
 - Online edit mode for batchjobs:
   
   When one of the three command line sources (actual command line,
   %CPICMD% environment variable, DESCRIPT.ION file entries) contains a
   single '?' (or '&') char as very last parameter, you will be prompted
   for additionally parameter input. Environment and parameter variable
   evaluation is allowed, redirection is possible.
   This feature is handled by CUI_LIB and should not conflict with a very
   similiar, but more general command line '?' feature known from MS-DOS 7
   COMMAND.COM (from Windows95/Chicago) and another related '&' feature by
   some applications, such as my PROSHELL and KEIL's assembler shell. The
   ending '?' is partially conflictive with the '/?' parameter, when
   stripping off the SwitChar. There are some special tokens, redirection
   features and macro support. Note that online-edit is not ignored in
   output-redirection!
 

 II.2. CPI parameters:
 =====================

 Now, as we have basically discussed the calling and system conventions, we
 can go on with the CPI.EXE parameters in details:

 /?, /Help   : The help screen.

 /!, /About  : The 'About' info screen.

 /Cpifile    : DOS .CPI file name <EGA.CPI>; extension: <.CPI>.

               When specifying 'CPI.EXE' or '', StdIn will be used.
               When only one parameter is given, the /Cpifile parameter is
               obsolete, and CPI will get this parameter as the .CPI file's
               name. But this easy calling syntax is not recommended, as it
               can be misinterpreted in some cases (see below).

               Examples:

                CPI EGA.CPI
                CPI /C:EGA.CPI
                CPI /cpifile=ega

               Note, that /Cpifile: also can be abbreviated just as C:
               (even without the SwitChar), but - as this most often will
               also be the location of DOSes .CPI files (e.g. C:\DOS\), CPI
               would interpret something like C:\DOS\EGA.CPI (given in
               easy calling syntax) as /CPIFILE=\DOS\EGA.CPI (in standard
               calling syntax), which is obviously not the same, if C: is
               not the current drive.
               Thus, if CPI cannot find the specified file (as given, and
               lacking a drives specification), it checks, if only one
               parameter is given and if it starts with C:. If so, under
               these conditions, CPI automatically adds C: to the drives
               specification. If this is not what you intended, you have
               to change your call to something like e.g. C:C:\DOS\EGA.CPI
               or better /C=C:\DOS\EGA.CPI.
               If you always abbreviate /CPIFILE as /CP (instead of the
               shorter /C), you will not encounter this.

 /Report     : Report file name <''=StdOut>; extension: <.RPT>.

               If you don't want CPI.EXE displaying it's infos on the screen,
               you can use output redirection *or* this report file option.
               All the info (depending on /Verbose mode), that would be
               displayed on the screen, is redirected to the file. Using the
               report option slightly changes the messages format.

               Due to internal handling of the report file output, on file
               IO errors (e.g. media full) a generic runtime error message
               will be shown instead of an individual message (other possible
               error conditions (with other files) are handled internally).

                Examples:

                 CPI /C:EGA.CPI /R:EGA.RPT
                 CPI /cpi=ega /report=prn

 /Verbose    : Dump mode <0>; 0=no; <1>,3,5=DRFONT LUT; 2,3=font; 4,5=bitmaps.

               This option allows you to change the detail level of messages:

               0= Standard messages (as if /V was not specified).
               1= Standard messages plus DRFONT LUT info, if the .CPI file is
                  stored in DRFONT format.
                  (As if /V was specified without an optionally number.)
               2= Standard messages plus hex dump of the font info.
               3= Standard messages plus DRFONT LUT info (if any) and hex dump
                  of the font info. With DRFONT, the combined fonts are
                  displayed, not the separated codepage fonts (this is just,
                  because they don't exist with DRFONTs... ;-) ).
               4= Standard messages plus graphically bitmaps of each fonts
                  characters.
               5= Maximum verbose level: Standard messages, plus bitmaps, plus
                  DRFONT LUT info (if any). As said with point 3, with DRFONTs
                  the combined fonts are displayed, not the separated fonts.

                Examples:

                 CPI /C:EGA.CPI /V:5
                 CPI /C=EGA.CPI /V

               Note, that verbose mode 5 will create very large outputs. 
               Normally, you should use this option only in conjunction with
               output redirection or the /Report option. I recomment to 
               create a file and than loading it into your favorite editor/
               viewer. Files will be large and could easily exceed your
               harddisk's free space...

 /Fonts      : Extract font data to files *<font>; extensions: <codepage>.

               If you need the internal font data, you can use this option
               to extract all the fonts from the .CPI file to separated files.
               Additionally you can give a directory and filename for the files
               to be created. The files extensions are always the number of the
               codepage the file will contain. The last character of the
               name will be the number of the font, to decide between multiple
               fonts. If the name already contains 8 characters, the first
               letter is skipped.
               This option allows you to extract the standard display fonts,
               but also DRFONTs. When processing DRFONT files, the fonts will
               be compiled from the internal compressed fonts and than be
               written in separated files, same as it would be with MS-DOS/
               PC-DOS standard display fonts. This is to create font data files
               containing exactly 256 chars per file (most font editors can
               only handle this style). If you don't need it, use /Drfonts
               instead, as this lets the fonts in their compressed format,
               generally containing more than 256 chars (much less disk space,
               much less files). Note, that the counting of fonts is vice-
               versa with DRFONTs, as the fonts are generally stored in
               different order in DR-DOS / Novell DOS .CPI files:

               MS-DOS / PC-DOS           font 1 generally is font 16x8
                                          ""  2         ""        14x8
                                          ""  3         ""         8x8

               DR DOS 6.0 / Novell DOS 7 font 1 generally is font  6x8
                                          ""  2         ""         8x8
                                          ""  3         ""        14x8
                                          ""  4         ""        16x8

               Printer .CPI files will not contain more than one font, so
               the last character of the font file names stays intact
               (this is not conflictive with /Lut files (see below), as they
               are only generated with DRFONT files and have different names).

                Examples:

                 CPI /C:EGA.CPI /F
                 CPI /C:EGA.CPI /Font=egafnt

 /Drfonts    : Extract DRFONT data to files *<font>; extensions: <font-spec>.

               As described above, DR DOS 6.0 / Novell DOS 7 display fonts
               generally use a new, compressed .CPI font format (DRFONT).
               This will save much memory. If you don't need to compile
               standard font files from a DRFONT file, generally it is
               preferable to extract DRFONT .CPI fonts to fonts using
               the /Drfont option instead of using /Font. The font files
               format is the same as with /Fonts (and the standard bitmapped
               font format, used by almost any font editor), but a font
               generally contains more than 256 characters. The actually font
               assignments for each codepage are stored in a separate table
               (LUT), that indexes into the DRFONT data.
               DR DOS 6.0/Novell DOS 7 can handle both font .CPI formats,
               standard font and it's own DRFONT format (which is preferable,
               because it superseeds the standard format).

               With /Drfont, you can give a directory and the files name.
               The last letter of the name and the extension is handled just
               as with /Fonts. The extension contains a verbatim specification
               of the font format (.6x8, .8x8, .148 or .168), that should
               never be conflictive with any existing codepage.

               If the .CPI file is not a DRFONT style file, this option is
               just ignored.

                Example:

                 CPI /c=c:\nwdos\ega.cpi /d=c:\drfega

 /Map        : Extract DRFONT character lookup table (LUT) to list file;
               extension: <.MAP>.

               This option is for DRFONTs only and is ignored with other
               styles. You can give a directory, name, and extension of a
               verbatim map file to be created from the LUT information.

               This file describes the assignments between the actual fonts
               and the DRFONT data for each codepage.

                Example:

                 CPI c=c:\nwdos\ega.cpi /m:c:\lut.lst

 /Lut        : Extract DRFONT LUTs to binary files; extentions: <codepage>.

               This option is for DRFONTs only and is ignored with other
               styles. You can give a directory and name for binary LUT
               files. The files extension will always be the codepage number.
               To decide the files from other files created by /Fonts, the
               last letter of the name is *not* altered (this can be partially
               conflictive with /Fonts filenames with 8 letters, but without
               /Overwrite existing files are not overwritten).
               The option is related to /Map, but contains the same information
               in a very different format. A /Map file contains information
               for *all* codepages in a verbatim format, whereas each of the
               /Lut files contains only *one* codepages info in a binary format
               (for all fonts, as they are the same) and is always 512 bytes
               long (256 character indexes to the DRFONT data files).

                Example:

                 CPI -c=c:\nwdos\ega.cpi -l

 /Overwrite  : Force to overwrite existing files.

               If existing files should be overwritten, this option can be
               used. Normally, when attempting to overwrite existing files, 
               CPI will show an error message and disable the file's
               creating (normally, the analyzer will continue).

                Examples:

                 CPI /c=ega.cpi /f /o
                 CPI /c=ega.cpi /font /overwrite
                 CPI c=ega.cpi font overwrite=yes


 All kinds of options can be mixed in the same command line. To show & extract
 *all* information in *any* format, call CPI as follows, e.g.:

  CPI /c:ega.cpi /v5 /d /f /m /l /o


 II.3. Codepage registery:
 =========================

  You can help me collecting codepage information from any localized DOSes
  and/or Free/PD .CPI files over our small planet: CPI can help you finding
  out, if I already have codepage information for a specific country/codepage/
  file in my archives. Just

   SET DBGEcho=On

  at the DOS-Prompt and run CPI.EXE on all your .CPI files as usual. When
  finishing CPI.EXE, the program will tell you, if a .CPI file contains
  data, that has not been in my database at compilation time... Currently
  the registery only holds a generic list of codepages for display and printer
  types. So, codepages commonly used in US and Western Europe DOS versions
  are masked out, because they are of less interest to me (already analyzed).

  Despite this automatically recognition method, the following .CPI files are
  *always* in my focus:

   - .CPI files from other DOS versions than listed in the CPI.PAS header
   - all Asian/Arabic/Eastern Europe .CPI files
   - all files containing unusual/unknown data (as reported by CPI.EXE)
   - all FreeWare/PD/ShareWare .CPI files and binary font files


-------------------------------------------------------------------------------

 III. LAST COMMENTS (FYI):
 =========================

 - Other CPIxxx.ZIP distribution points planned (eventually coming soon):

   SimTel sites and mirrors...

 - Some font editors, capable to edit binary font files:
   (Just those, that I am aware off. Please tell me, if you know more.
   This is FYI only. I have absolutely no financally interests with these.)

    FED.EXE by Matthias Uphoff, DMV, Germany.
     A font editor running in text-mode and displaying bitmaps in pseudo-
     graphics, but also can give an overview of all characters in graphics
     mode. Can be found on the accompanion disk from his book:
     "Die Programmierung der EGA/VGA Grafikkarte, Addison & Wesley, 1993"

    FD.EXE, a flexible Font-Designer, running in graphics mode and
     displaying 128 characters simultanously (the 1991 release (DM 28,-)
     was capable to handle 8x8, 10x8, 12x8, 14x8 and 16x8 fonts). From
     the ShareWare VGA-tools package (also including FONTLOAD, a resident
     EVGAFONT utility etc.) by Peter Plucinski, Recklinghausen, Germany.

    ZEISATZ/SCHRIFT by Friedhelm Killet, Kempen, Germany, a text-mode
     based ShareWare tool (ASP & DS, unregistrated version with reminding
     messages), displaying the character in pseudo-graphics. The release of
     1991 (DM 26,-) could handle fonts with 6..32x8.

 - Being interested in codepage information and CPI.EXE, you may also be
   interested in my COUNTRY.EXE utility. This utility allows to change
   system country settings at runtime and provides versatile analyzing
   options. Currently COUNTRY.EXE is part of my FreeWare TIPS_MP.ZIP package,
   which can be obtained from my web-page and other sites.

 - Years ago, I have seen another utility out there, named almost equal to
   "CPI.EXE", but it was created for a very different purpose:

    CPI.COM V1.0 beta (C) 1987 by Rainer Kolbeck (Germany).

   To my testage it was functional, but I never heard of it again.
   That TSR has been a support utility to provide an easy serial
   "Communication Program Interface" to application programs by using
   escape sequences.

   My "CPI.EXE" and "CPIxxx.ZIP" package have absolutely nothing to do with
   that driver.


-------------------------------------------------------------------------------
