Appendix A. Remapping the keyboard in a HATS LE application

Concepts to understand before remapping HATS LE keys

Every HATS LE application embeds code from the Host On-Demand product to handle the connection to the Telnet server on behalf of the web browser client. Therefore, this guide references Host On-Demand documentation for key mnemonics which may be sent to the host computer to represent the user pressing keys in the host session.

Note:
Make sure to check the HATS LE Supported browsers and limitations for more information. For Host On-Demand documentation, go to: http://www.ibm.com/software/network/hostondemand/library.

In every HATS LE application is a file called KBS.js which determines how the keycode values generated by the user's keyboard are mapped to key signals sent to the host session. If it becomes necessary, you may edit the KBS.js file to remap the HATS LE keyboard. To locate KBS.js, look in the HATS5LE.ear.ear/HATSLE.war/Web Content/Common directory. There are three values in KBS.js which determine the relationship between any key on the keyboard being pressed and what signal is then sent to the host. These three values are:

  1. The keycode value for the pressed key, represented as an integer variable in the KBS.js file. For example,
    var CODE_F2 = 113; 
    for the 'F2' key,
  2. The combination of the keycode value and the Alt, Crtl, and Shift states of the keyboard, and
  3. The HOD mnemonic keyword sent for the keycode combination value and Alt, Crtl, and Shift states. For example,
    [CODE_F2, 0, 0, 0, '[pf2]']
    sends the pf2 key signal to the host when the F2 key is pressed on the user's keyboard. To change key mappings in your HATS LE application, you can change or add combinations so new or existing keys send the mnemonic keyword. Note that to remap keys in HATS LE, you only need to modify the keycode and defaultKeyMappings variables at the top of the KBS.js file.
Note:
There are dependencies between the keys listed in the KBS.js file, and the presence or absence of any key buttons listed on the screen. The rules governing these dependencies are listed below.

  1. Keyboard Support must be enabled for keyboard keystrokes to have any effect in the HATS LE application. By default, HATS LE shows the application keypad but does not display the host keypad. In order for HATS LE to display the host keypad, you need to go to configure your application.hap file. For more information, see Modifying your application file.
  2. The host keypad buttons and links displayed in a transformation determine which keyboard keys are enabled. If any host keypad buttons and links for host keys (those displayed by the Host Keypad, and those Host Keypad buttons you may add manually, if any) are displayed on a screen transformation, then only those functions represented by the displayed keypad buttons and links have keyboard support. The Host Keypad buttons defined to display on a given transformation, including the default transformation, act as a filter to provide keyboard support to host keys mapped in KBS.js. Therefore, if you add a new mnemonic keyword to KBS.js while displaying any host keypad keys, you should also add a button or link for the new mnemonic keyword if you want to have keyboard support for that host key.
  3. Keyboard support of host keys is not affected by transformations on host screen data and is only affected by which keypad buttons are displayed. This means that even if your transformation, including the default transformation, of the host screen data causes host key buttons and links to appear in the user's browser, only the host keys displayed in the Host Keypad or keypad buttons manually added to the transformation affect which host keys are supported from the keyboard.

Best practices:

With respect to the above rules when remapping the HATS LE keyboard, it is generally best to either:

Determining keycode values

To determine the keycode value for a given key on the keyboard, you should refer to the your specific browser documentation

Determining mnemonic keywords

HATS LE-supported 5250 mnemonic keyword table
Table 4. Mnemonic Keywords for SendKeys
Function Mnemonic Keyword
Attention [attn]
Alternate View [altview]
Clear [clear]
Enter [enter]
F1 [pf1]
F2 [pf2]
F3 [pf3]
F4 [pf4]
F5 [pf5]
F6 [pf6]
F7 [pf7]
F8 [pf8]
F9 [pf9]
F10 [pf10]
F11 [pf11]
F12 [pf12]
F13 [pf13]
F14 [pf14]
F15 [pf15]
F16 [pf16]
F17 [pf17]
F18 [pf18]
F19 [pf19]
F20 [pf20]
F21 [pf21]
F22 [pf22]
F23 [pf23]
F24 [pf24]
Field exit [fldext]
Field+ [field+]
Field- [field-]
Help [help]
PA1 [home]
PA2 [pa1]
PA3 [pa2]
System Request [pa3]
Page Up [pageup]
Page Down [pagedn]
Reset [reset]
System Request [sysreq]
Test Request [test]

Example

The following is an example on how to map the Ctrl+Home key combination on the keyboard. To send the Home key to the host session and also place a button for this function in your transformation, two steps are required: Edit KBS.js and then modify your transformation as shown below.

Specifying the key combination that sends the host key

Modify the KBS.js file by adding the lines specified in bold italic below:

var CODE_BACKSPACE = 8;
 var CODE_TAB       = 9;
 var CODE_ENTER     = 13;
 var CODE_PAUSE     = 19;
 var CODE_ESC       = 27;
 var CODE_PAGEUP    = 33;
 var CODE_PAGEDOWN  = 34;
 var CODE_END       = 35;
 var CODE_HOME      = 36;
 var CODE_INSERT    = 45;
 var CODE_DELETE    = 46;
 var CODE_A         = 65;
 var CODE_B         = 66;
 var CODE_C         = 67;
 var CODE_D         = 68;
 var CODE_E         = 69;
 var CODE_F         = 70;
 var CODE_G         = 71;
 var CODE_H         = 72;
 var CODE_I         = 73;
 var CODE_J         = 74;
 var CODE_K         = 75;
 var CODE_L         = 76;
 var CODE_M         = 77;
 var CODE_N         = 78;
 var CODE_O         = 79;
 var CODE_P         = 80;
 var CODE_Q         = 81;
 var CODE_R         = 82;
 var CODE_S         = 83;
 var CODE_T         = 84;
 var CODE_U         = 85;
 var CODE_V         = 86;
 var CODE_W         = 87;
 var CODE_X         = 88;
 var CODE_Y         = 89;
 var CODE_Z         = 90;
 var CODE_HOSTHOME = 36;
 var CODE_F1        = 112;
 var CODE_F2        = 113;
 var CODE_F3        = 114;
 var CODE_F4        = 115;
 var CODE_F5        = 116;
 var CODE_F6        = 117;
 var CODE_F7        = 118;
 var CODE_F8        = 119;
 var CODE_F9        = 120;
 var CODE_F10       = 121;
 var CODE_F11       = 122;
 var CODE_F12       = 123;
 var HostKey        =1;
 var ApplicationKey =2;
/***********************************************************
 * NOTICE: DO NOT MODIFY THE ABOVE VARIABLES!!
 ***********************************************************/

 var defaultKeyMappings = [
 // KEYCODE,       ALT, CTRL, SHIFT, MNEMONIC
 //============ command key mappings ================
   [CODE_ENTER,      0,    0,     0, '[enter]'     ],
   [CODE_PAUSE,      0,    0,     0, '[attn]'      ],
   [CODE_ESC,        0,    0,     0, '[clear]'     ],
   [CODE_ESC,        0,    0,     1, '[sysreq]'    ],
   [CODE_PAGEUP,     0,    0,     0, '[pageup]'    ],
   [CODE_PAGEUP,     1,    0,     0, 'refresh'     ],
   [CODE_PAGEDOWN,   0,    0,     0, '[pagedn]'    ],
   [CODE_HOSTHOME, 0,    1,     0, '[home]'    ],
   [CODE_PAGEDOWN,   1,    0,     0, '[pa3]'       ],
   [CODE_END,        1,    0,     0, '[pa2]'       ],
   [CODE_INSERT,     1,    0,     0, 'default'     ],
   [CODE_DELETE,     1,    0,     0, '[pa1]'       ],
   [CODE_D,          0,    1,     0, 'disconnect'  ],
   [CODE_H,          0,    1,     0, '[help]'      ],
   [CODE_P,          0,    1,     0, '[printhost]' ],   
   [CODE_J,          0,    1,     0, 'printjobs'   ],
   [CODE_ENTER,      1,    0,     0, 'reverse'     ],   
   [CODE_K,          0,    1,     0, 'toggle'      ],
   [CODE_S,          0,    1,     0, 'ResetButton' ],   
 //============ function key mappings ===============
   [CODE_F1,         0,    0,     0, '[pf1]'       ],
   [CODE_F1,         0,    0,     1, '[pf13]'      ],
   [CODE_F2,         0,    0,     0, '[pf2]'       ],
   [CODE_F2,         0,    0,     1, '[pf14]'      ],
   [CODE_F3,         0,    0,     0, '[pf3]'       ],
   [CODE_F3,         0,    0,     1, '[pf15]'      ],
   [CODE_F4,         0,    0,     0, '[pf4]'       ],
   [CODE_F4,         0,    0,     1, '[pf16]'      ],
   [CODE_F5,         0,    0,     0, '[pf5]'       ],
   [CODE_F5,         0,    0,     1, '[pf17]'      ],
   [CODE_F6,         0,    0,     0, '[pf6]'       ],
   [CODE_F6,         0,    0,     1, '[pf18]'      ],
   [CODE_F7,         0,    0,     0, '[pf7]'       ],
   [CODE_F7,         0,    0,     1, '[pf19]'      ],
   [CODE_F8,         0,    0,     0, '[pf8]'       ],
   [CODE_F8,         0,    0,     1, '[pf20]'      ],
   [CODE_F9,         0,    0,     0, '[pf9]'       ],
   [CODE_F9,         0,    0,     1, '[pf21]'      ],
   [CODE_F10,        0,    0,     0, '[pf10]'      ],
   [CODE_F10,        0,    0,     1, '[pf22]'      ],
   [CODE_F11,        0,    0,     0, '[pf11]'      ],
   [CODE_F11,        0,    0,     1, '[pf23]'      ],
   [CODE_F12,        0,    0,     0, '[pf12]'      ],
   [CODE_F12,        0,    0,     1, '[pf24]'      ]
 ];
Note:
The name given to any new keycode variable (CODE_HOSTHOME in this example) is not important except that it be unique and match the corresponding entry in the defaultKeyMappings variable list. Also note in this example that adding a new keycode variable for the Home key is not actually necessary since the
var CODE_HOME = 36;
entry already exists for the Home key's keycode. However, if you are mapping a keyboard key that is not associated with a keycode variable already defined in KBS.js, such an entry would be necessary.

Due to limitations in how the Macintosh Safari browser maps keys to ordinal values, we have the need to remove the Function key definitions from the default key mappings. If the Macintosh Safari browser is detected in keyboard init, the table defined below will be replaced by the default table defined above.

 //*************************************************
  var macSafariKeyMappings = [
// KEYCODE,       ALT, CTRL, SHIFT, MNEMONIC
//============ command key mappings ================
  [CODE_ENTER,      0,    0,     0, '[enter]'     ],
  [CODE_PAUSE,      0,    0,     0, '[attn]'      ],
  [CODE_ESC,        0,    0,     0, '[clear]'     ],
  [CODE_ESC,        0,    0,     1, '[sysreq]'    ],
  [CODE_R  ,        0,    1,     0, '[reset]'     ],
  [CODE_PAGEUP,     1,    0,     0, 'refresh'     ],
  [CODE_PAGEDOWN,   0,    0,     0, '[pagedn]'    ],
  [CODE_PAGEDOWN,   1,    0,     0, '[pa3]'       ],
  [CODE_END,        1,    0,     0, '[pa2]'       ],
  [CODE_INSERT,     1,    0,     0, 'default'     ],
  [CODE_DELETE,     1,    0,     0, '[pa1]'       ],
  [CODE_D,          0,    1,     0, 'disconnect'  ],
  [CODE_H,          0,    1,     0, '[help]'      ],
  [CODE_P,          0,    1,     0, '[printhost]' ],   
  [CODE_J,          0,    1,     0, 'printjobs'   ],
  [CODE_ENTER,      1,    0,     0, 'reverse'     ],   
  [CODE_K,          0,    1,     0, 'toggle'      ],
  [CODE_S,          0,    1,     0, 'ResetButton' ],   
  [CODE_ENTER,      0,    1,     0, '[fldext]'    ],
];
Note:
The Function keys are not mappable in Safari.