Enabling keyboard support

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

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

To use keyboard support in ZIETrans Web projects, you must have a supported Web browser.

Defining keyboard support

If not enabled by default, you can enable keyboard support and select available options on the Other tab of your Project Settings. For more information, see Keyboard support.

You can also define a host keypad and an application keypad. See Host keypad and Application keypad for more information.

Changing the appearance of the keypads

For ZIETrans Web projects, use the Host Keypad and Application Keypad settings on the Rendering tab of your Project Settings to define which keys to display and whether to display them as buttons or links. See Host keypad and Application keypad for more information.

To change the style of a keypad for a specific ZIETrans Web project, change the cascading style sheet (.css file) that corresponds to the keypad. This will be the style sheet you are using when you build your project. In the Rational® SDP workbench, go to the ZIETrans Projects view of the ZIETrans Toolkit and expand the project name. Expand Web Content/Common/Stylesheets. For more information, see Using style sheets.

To modify the style sheet, double-click on the .css file to open the editor. Keep in mind that templates can override your style sheet changes. For more information about cascading style sheets, go to http://www.w3.org/Style/CSS/.

If not already defined, the style sheet can define any of the following ZIETrans 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 users

To facilitate use of your ZIETrans application, you may want to document the keyboard settings for your 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 5. Key mapping in ZIETrans
Button on button bar Default physical key mapping
F1 - F12 F1 - F12
F13 - F24 Shift + F1 - F12
ENTER Enter
CLEAR Esc
RESET Ctrl + R
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  Web-only 
HELP Ctrl + H
Enable/disable keyboard Ctrl + K
Default Alt + Insert
Refresh Alt + Page Up
Reset HTML Form Ctrl + S
Disconnect Ctrl + D
View print jobs Ctrl + J
Reverse Alt + Enter
Field Exit
Shift + Enter  Web-only 
Note:
For more information, see Special 5250 field key support.
Field+
Ctrl + Numpad Plus  Web-only 
Field-
Ctrl + Numpad Minus  Web-only 
Note:
For more information, see Special 5250 field key support.

Special 5250 field key support

Note:
For information about this support for mobile devices, see Considerations and limitations for mobile devices.

Default field keypress combinations

The default field keypress combinations for ZIETrans Web applications are listed below. For information about how to remap the keyboard, see Remapping the keyboard in a ZIETrans application.

Quick Field Exit

The Quick Field Exit keypress can be used with ZIETrans Web applications to speed the entry of numeric data for 5250 screens. This keypress clears the current field from the current caret position to end of the field, and advances the cursor position to the next field. Although this keypress can be used on any field, it is especially useful where users might otherwise use a Field Exit. A true Field Exit keypress sends the screen of data to the host and causes the ZIETrans transformation to be redrawn. Therefore, screens requiring many Field Exit aids before being submitted may cause usability issues. The Quick Field Exit keypress, combined with the Field Exit Emulation feature, increases the speed of such applications considerably.

Quick Field Minus

The Quick Field Minus keypress can be used with ZIETrans Web applications to speed the entry of negative numeric data for 5250 screens. This keypress clears the current field from the current caret position to end of the field, prepends the field value with a minus sign character (-), and advances the cursor position to the next field. Although this keypress can be used on any field, it is only useful on 5250 signed numeric fields where users might otherwise use a Field Minus. A true Field Minus keypress sends the screen of data to the host and causes the transformation to be redrawn. Therefore, screens requiring many Field Minus aids before being submitted may cause usability issues. The Quick Field Minus keypress, combined with the Alternate way to input negative numbers feature, increases the speed of such applications considerably. Using the Quick Field Minus keypress on fields other than 5250 signed numeric fields may cause improper data entry.

Alternate way to input negative numbers

To enter a negative number in a 5250 signed numeric field, users can enter a minus sign character (-) in the first position of the field, instead of using a Field Minus and incurring a round trip to the server. This allows for faster entry of large quantities of negative numbers into 5250 signed numeric fields. The ZIETrans server emulates a Field Minus keypress for each 5250 signed numeric field entered with a leading minus sign character. Any unwanted prefilled data must be cleared from the field before tabbing to another field. Users should not enter a minus sign in the first position and also press Field Minus, Field Plus, or Field Exit.

Field Exit Emulation

This feature automatically supplies a Field Exit aid key for the user, when required. A Field Exit aid key is required when certain types of 5250 fields are modified.

For example, if a user is using the Quick Field Exit keypress to advance from field to field, and submits the screen with an Enter key or some other non-field aid key, a Field Exit might be required for the field containing the cursor when the screen is submitted.

In this case, if a required Field Exit is not supplied, the host might respond with the error message, Enter key not allowed in field. With this ZIETrans feature, the ZIETrans server sends a Field Exit to the host before sending the Enter, avoiding the error message.

If you want to disable this feature, add the following statements to the application.hap file:

<class name="com.ibm.hats.common.RuntimeSettings">
        <setting name="emulateFieldExit" value="false"/>
</class>

If there is already a <class> section by this name, just add the <setting> line inside the section.

Remapping the keyboard in a ZIETrans application

Concepts to understand before remapping ZIETrans keys

Every ZIETrans application embeds code from the Host On-Demand product to handle the connection to the Telnet server on behalf of the client. Therefore, this guide uses Host On-Demand terminology for mnemonic keywords which may be sent to the host computer to represent the user pressing keys in the host session.

Mnemonic keywords

ZIETrans-supported 3270 mnemonic keyword table
Table 6. 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]
ZIETrans-supported 5250 mnemonic keyword table
Table 7. 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 [pa1]
PA2 [pa2]
PA3 [pa3]
System Request [sysreq]
Page Up [pageup]
Page Down [pagedn]
Quick Field Exit [qfldext]
Quick Field Minus [qfld-]
Reset [reset]
System Request [sysreq]
Test Request [test]

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>

Remapping keys for ZIETrans Web applications

In every ZIETrans Web application is a file named KBS.js which determines how the keycode values generated by the users keyboard are mapped to key signals sent to the host session. To remap the ZIETrans keyboard, you must edit the KBS.js file. 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, Ctrl, and Shift states of the keyboard, and
  3. The Host On-Demand mnemonic keyword sent for the keycode combination value and Alt, Ctrl, 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 ZIETrans Web application, you can change or add combinations allowing new or existing keys to send the mnemonic keyword.

Be aware that you cannot remap the Ctrl, Alt, and Shift modifier keys. ZIETrans uses JavaScript, and JavaScript does not consider these keys to be keypresses, but rather modifiers.

To remap keys in ZIETrans Web applications, 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, 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 can be set using project-level settings to specify whether it should support all mapped keys, regardless of what buttons or links are displayed. To modify these settings, go to the ZIETrans Projects view and double click the Project Settings of your ZIETrans project, select the Other tab and click Keyboard Support. For more information, see Keyboard support.
  2. By default, ZIETrans shows the application keypad but does not display the host keypad. In order for ZIETrans to display the host keypad, you need to go to the ZIETrans Projects view and double click the Project Settings of your ZIETrans 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.

Example

The following example shows 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 described in Adding additional keypad buttons to a transformation.

To specify 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.

Adding additional keypad buttons to a transformation

You can add a new button or link into the default Host Keypad. The control for this is in Project Settings 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 using the Insert Host Keypad > Individual Key function when editing the transformation. See Individual Key for more information. 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]. If you want keyboard support for this new button, you must add it to the KBS.js defaultKeyMappings table (for Web applications).