OS/2 keyboard translate table design

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

From: Solution Developer Support

This readme describes the OS/2 keyboard translate table design change which provided a new 'Extended Accent Entries' area. The implementation of this change resulted in support for variable length keyboard translation tables.

The layout of the KEYBOARD.DCP is pictorially defined as follows:

KEYBOARD.DCP File Format

+------------------------------+   1 2 N = Offsets
| ***                    | | | |
|  |   +---------------+ | | | |    **** = 1st DWORD is a Ptr
|  |   |               |<+ | | |           to the File Header
|  |   | Xlate Table   |   | | |
|  |   |      1        |   | | |
|  |   +---------------+   | | |
|  |   +---------------+   | | |
|  |   |               |<--+ | |
|  |   | Xlate Table   |     | |
|  |   |      2        |     | |
|  |   +---------------+     | |
|  |          .              | |
|  |          .              | |
|  |   +---------------+     | |
|  |   |               |<--- + |
|  |   | Xlate Table   |       |
|  |   |      N        |       |
|  V   +---------------+       |
+------------------------------+
|      Table 1 Offset          |   File Header consists of
|      Table 2 Offset          |   table offsets into file
|            .                 |
|            .                 |
|                              |
|      Table N Offset          |
+------------------------------+

The KEYBOARD.DCP file consists a File Header section (located at the bottom of the file) which basically contains the file offsets and various lookup information to each of the individual Keyboard Xlate Tables. The "Standard" Keyboard Xlate table is based on a fixed length structure, 1251 bytes, which has the basic form of:

Standard Xlate Table Format

+------------------------+
|           .            |   Xlate Table Header with
|           .            |   Length field = 1251 bytes
+------------------------+
| KeyDef1    |   Key Definitions with
|           .            |   (5) char entries each
|           .            |
| KeyDef127  |
+------------------------+
| Accent1   |   Accent Entries with
|           .            |   (20) elements each
|           .            |   (element = char/scan pair)
| Accent6  |
+------------------------+

This change introduces variable length Keyboard Xlate Tables where the variable length is based on two dynamically expansive variables. First, the number of Accent Entries is variable such that the old (6) accent limitation is replaced with a (256) accent limitation. Second, the number of elements per accent entry is variable such that the old (20) element limitation is replaced with a (256) element limitation. The "Extended" Keyboard Xlate Table is therefore based on a variable structure which has the following form:

Extended Xlate Table Format

+-------------------------------+
|               .               |  Xlate Table Header with
|               .               |  Length field >= 1251 bytes
+------------------------------ +
|  KeyDef1          |  Key Definitions with
|               .               |  (5) char entries each
|               .               |
|  KeyDef127        |
+-------------------------------+
|  Accent1        |  Standard Accent Entries:
|               .               |  with (20) elements each
|               .               |  (element = char/scan pair)
|  Accent6        |
+-------------------------------+
|  Accent7 >        |  Extended Accent Entries:
|               .               |  - up to an additional 250
|               .               |    accent entries (M=256)
|               .               |  - each accent entry has a BYTE
|  AccentM >        |    containing the # elements (L)
+-------------------------------+  - element = char/scan pair

The file header and existing (and unbroken) Xlate tables remain intact and unchanged by the redesign efforts of this change. Hence, the keyboard interfaces (i.e., Category 4, IOCtl 50h) which externalize the Xlate table format are unaffected, they will not be upgraded to include these changes since there is no proof that 16-bit applications need the function.

Changes to AccentEntry record

The first 6 AccentEntry records remain unchanged.

 The record is defined as follows:
 AccEnt
 Where....
 a & b are the scan code & char to use when the key following the accent
 isn't affected by the accent, so the accent itself must be used.
 c & d are the scan code & char to use when Ctl-[accent] is pressed.
 e & f do the same for Alt-[accent].
 c1,s1 - c20,s20 are the char/scan code mapping for accented translation.

For each AccentEntry of 7 and greater, the first byte in the record will contain the LENGTH of the AccentEntry record. The LENGTH value is defined as the total length in bytes of the AccentEntry record including the LENGTH byte.

The record is defined as follows:

 AccEnt
 where....
 l is the total length in bytes of the AccEnt including itself.
 a & b are the scan code & char to use when the key following this accent
 isn't affected by the accent so the accent itself must be used.
 c & d are the scan code & char to use when Ctl-[accent] is pressed.
 e & f do the same for Alt-[accent].
 c1,s1 - c120,s120 are the char/scan code mapping for accented translation.

Up to 255 AccentEntry records can now exist. In 1.x formats this was set at 7, with the 7th entry always unused and left filled with zero's.

For each AccentEntry of 7 and greater, up to 120 element pairs may exist, and the length is dynamic.

In 1.x formats the length was set at 20, with unused elements set to zero.

Notes on the XHeader (Translation Table Header)

There are no changes to the structure of this, but the value of the XtableLen will now be variable. In the past it was always 1251 bytes.

Key Type field 15H will have a new condition defined: (the elseif condition)

For the Alt+Gr case:

If Char3 of the KeyDef record is in range 1-6
  Then Char3 is the number of the AccentEntry to jump to
Elseif Char3 of the KeyDef record is equal to 7
  Then Char5 is the number of the AccentEntry to jump to. All AccentEntry
  records jumped to in this case will be of the new AccentEntry record format.
Else
  Char3 is treated as a valid ASCII character.
Endif

Note that existing translation tables will be compatible with the new tables.