Enabling keyboard support in projects

Users frequently interact with host applications using special keys on the physical keyboard, such as F1, Attn, Reset, and Clear. There are two different ways in which the end users of your HATS projects can send keystrokes to the host:

This chapter explains how to define keyboard support in your HATS project and contains tips for documenting keyboard support for your end users.

To use keyboard support in HATS projects, have a supported Web browser. For a list supported Web browsers and limitations, refer to HATS Getting Started

 

Defining keyboard support

To configure keyboard support in a HATS project, you need to enable keyboard support in your project. You will also need to define the host keypad as well as which application keypad keys to include. See Modify a HATS project for information about the project settings for keyboard support and the keypads.

 

Changing the appearance of the keypads

To change style of a keypad for a specific HATS project, change the cascading stylesheet that corresponds to the keypad. This will be the stye sheet you are using when you build your project. In the WebSphere Studio workbench, go to the HATS Project View tab of the HATS Studio and expand the project name. Expand Web Content/Common/Stylesheets.

To modify the keypad, double-click on the xxxxtheme.css stylesheet to open the editor. Keep in mid that templates could override your stylesheet changes. For more information on cascading stylesheets, go to http://www.w3.org/Style/CSS/.

The cascading stylesheet defines seven styles:

table.HostKeypad

Host keypad background

table.ApplicationKeypad

Application keypad background

input.HostPFKey

Host keypad PF buttons

input.HostButton

Host keypad buttons

input.ApplicationButton

Application keypad buttons

a.HostKeyLink

Host keypad links

a.ApplicationKeyLink

Application keypad links

 

Providing documentation for end users

To facilitate use of your HATS project, we recommend that you document the keyboard settings for your end users--either in the application's graphical user interface or in some other easily displayed form (perhaps a link in your template). Your documentation should describe:

Table 3. Key mapping in HATS
Button on button bar Default physical key mapping
F1 - F12 F1 - F12
F13 - F24 Shift + F1 - F12
ENTER Enter
CLEAR Esc
SYSREQ Shift + Esc
ATTN Pause/Break
PAGEUP Page Up
PAGEDN Page Down
PA1 Alt + Delete
PA2 Alt + End
PA3 Alt + Page Down
PRINT Ctrl + P
HELP Ctrl + H
Enable/disable keyboard Ctrl + K
Default Alt + Insert
Refresh Alt + Page Up
Reset Ctrl + S
Disconnect Ctrl + D
View print jobs Ctrl + J
Reverse Ctrl + R

 

Remapping the keyboard in a HATS application

 

Concepts to understand before remapping HATS keys

Every HATS 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.

In every HATS application is a file called KBS.js which determines how the keycode values generated by the users keyboard are mapped to key signals sent to the host session. You will edit the KBS.js file and then rebuild your HATS application to remap the HATS keyboard. To locate KBS.js, go to the Navigator view then look in the project_name/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 application, you can change or add combinations so new or existing keys send the mnemonic keyword. Note that to remap keys in HATS, you only need to modify the keycode and defaultKeyMappings variables at the top of the KBS.js file.

There are dependencies between the keys listed in the KBS.js file, the Keyboard Support state of the Project Settings, 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 application. By default, HATS shows the application keypad but does not display the host keypad. In order for HATS to display the host keypad, you need to go to the HATS Project View and double click the Project Settings of your HATS project, select the Rendering tab and click Host Keypad. You will then have the option of enabling the check box to display the host keypad as well as selecting which keys to display.

  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/or those Host Keypad buttons you may add manually) 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, 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. For instance, you may choose to remove the PF3 button/link from the host keypad by clearing the F3 check box under the 'Select keys to display' section of the Host Keypad on the General tab of the Project Settings. This causes the Host Keypad to not show the PF3 button/link, and also keeps the F3 keyboard key from sending the [pf3] mnemonic keyword to the host session. However, on this same screen the transformation you chose may have included a PF3 button within the transformed screen data, and this button will still work to send the [pf3] mnemonic keyword when pressed.

Best practices:

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

 

Determining keycode values

To determine the keycode value for a given key on the keyboard, save the following HTML code in a file and open it in an Internet Explorer browser window. The keycode value is displayed for any key pressed in that browser.

<html>
<head>
<script>
document.onkeydown = keydownhandler;
function keydownhandler()
{
 document.testform.displayField.value = "Keycode: " + window.event.keyCode;
}
</script>
</head>
<body>
 <center>
  <form name="testform">
   <input type="text" name="displayField" value="Hit any key">
  </form>
 </center>
</body>
</html>

 

Determining mnemonic keywords

:

HATS-supported 3270 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]
Home [home]
PA1 [pa1]
PA2 [pa2]
PA3 [pa3]
Reset [reset]
System Request [sysreq]

HATS-supported 5250 mnemonic keyword table

Table 5. 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 and 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]'      ]
 ];

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.

 

Adding additional keypad buttons to a transformation

You can add a new button or link into the default Host Keypad with the Project Settings. The control for this is on the Rendering tab, Host Keypad settings. The new button or link will appear whenever the default Host Keypad is used. You can add a new button or link to a single transformation JSP using the Insert Individual Host Key item from the HATS Tools menu when editing the JSP. The GUI for adding your own button or link requires a Caption and a Mnemonic. In this example, the Caption is "Home", and the Mnemonic is "[home]".

 

Home