     THE STRUCTURE OF THE KL FILE
     ============================

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

   Format of the KL file
   (KL file: physical keyboard descriptor for FD-KEYB 2.0)

   Copyright (C) 2004 by Aitor SANTAMARIA_MERINO
   aitorsm@inicia.es

   Version  : 1.10
   Last edit: 2005-08-13 (ASM)

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

   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!


A KL file is the container of the information for a given physical keyboard to
be used by FreeDOS KEYB 2.0.

FD-KEYB 2.0 uses Keyboard Control Blocks (KeybCB) to operate, therefore, the
structure of the KL file is closely related to the KeybCB. You are encouraged
to read the latest version of the KeybCB.

DEFINITIONS:

Physical keyboard:
   Each possible variation of an enhanced AT (MFII) keyboard, where by
   variation it is understood the labels physically printed in the keys.


STRUCTURE OF THE KL FILE

The KL file contains two parts which are clearly differentiated. A first part
is a KL header, which contains non-resident information for identification
purposes, and a second part, which is closely related to a KeybCB, that we
shall call KL data.


============================================================================
TABLE 1: The KL header
============================================================================
The KL header has variable size. Its structure is given by


Ofs  Size      Description
---  --------- ------------------------------------------------------------
000  3 BYTES   Signature:  "KLF"
               Signature for the KLF file

003    WORD    Version of the KL structure (in this case 0100h)

005    BYTE    Length n of the following namestring

006  n BYTES   namestring (see table 2)

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



============================================================================
TABLE 2: The namestring
============================================================================
The namestring is a sequence of 1 or more keyboard identifiers, each of
which is separated by comma.

     keyboardID [ ',' keyboardID ] ...

where keyboardID has the following structure

Ofs  Size      Description
---  --------- ------------------------------------------------------------
000    WORD    Keyboard numeric identifier
               (0 if none is specified)

002   x BYTES  A variable number of characters that conform the string
               identifier


The string descriptor ends when character ',' is found, or when the
namestring finishes.
============================================================================

Each keyboard ID is used by KEYB to identify that the contents of the KL
file are correct. The user usually gives the information in the commandline:

    KEYB   stringID[,CP[,datafile]]  [/ID:numericID]

The datafile maybe a KL file or a file containing KLs. The numericID is
optional, and when it is omitted, then it is assumed to be 0.

A KL header may contain more than one of such keyboard identifiers. The KL is
matched whenever at least ONE of the keyboard IDs (both in the string and
number) are matched.


THE KL DATA

The KL data comes immediately after the KL header. It is basically the same
structure as a KeybCB, with one exception.

One of the many unused fields in the KeybCB when it resides in the file
(but that later becomes valid when it is alive in memory) is reused by KEYB
to learn in advance some features of the KeybCB that helps it optimize the
memory usage, by discarding unused code.

This field is the pointer to the next KeybCB (offset 006 of the KeybCB), from
which only the first word is user, as a flag field.

The description of each flag is listed in table 3.


============================================================================
TABLE 3: Flags that FD-KEYB 2.0 expects on WORD offset 006 of the KeybCB
============================================================================

Flag    Value   Meaning
-----  ------- ------------------------------------------------------------
C  0    0001h   Diacritics. The KeybCB uses diacritics
S  1    0002h   Beep. The KeybCB beeps (beep command)
B  2    0004h   Basic commands. One command other than 0, 160 is used
E  3    0008h   Extended commands. One of these commands is used:
                 80..99, 120..139, 140..159, 162..199
L  4    0010h   Default Shifts. The KeybCB remaps the usual shift/lock keys
                somewhere else (shift, ctrl, alt, ...)
U  5    0020h   User defined keys. The KeybCB uses the userkeys management
                commands (180-195)
9  6    0040h   Basic management of int9h.
                User explicitely requests to hook and chain int9h manager
                of KEYB.
A  7    0080h   Ussage of APM commands (150..154)
   8    0100h   <<<Unused>>>
X  9    0200h   Strings. the KeybCB uses strings
F 10    0400h   Full management (not chain) of int9h, completely replacing
                BIOS
  11    0800h   <<<Unused>>>
  12    1000h   The planes make use of ScrollLock
  13    2000h   The planes make use of NumLock
  14    4000h   The planes make use of CapsLock
  15    8000h   <<<Unused>>>

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


