Modifying a HATS project

When you create a project using the HATS Create a Project wizard, the settings you choose in the wizard are saved in a project application (.hap) file. You can invoke the project editor by double-clicking on Project Settings under the name of the project you want to modify in the HATS Projects view.

The settings displayed in the project editor are the settings that are used for the entire project. If you want to modify any of the settings, you can use the tabs of the project editor. Saved changes made in the project editor are automatically recognized when running your project in a test environment by clicking Refresh on the application keypad or by displaying a new host screen in the GUI. The Refresh will not pick up changes made to the connection (.hco) files. Connection setting changes are applied when the application server (or application) is restarted.

Note:
Settings used for the entire HATS project should not be confused with settings applied throughout HATS. HATS-wide settings can be applied from Window > Preferences > HATS.

The following sections describe each tab of the project editor, and explain how they can be used to modify the project settings.

Overview

The Overview tab of the project editor summarizes all of the settings you specified when you created your project.

The General Information section contains the project name and description, the chosen template and theme, and the date last modified.

Note:
A theme is not displayed for projects optimized for mobile devices. For more information, see Developing HATS applications for mobile devices.

Click the link for the current theme to change the project theme. Four options are provided, Standard, Modern Web application  Web-only  or Modern UI application  RCP-only , Classic terminal emulator, and Custom. Each function in the list of settings can be enabled elsewhere in the project settings. This list provides a convenient method of setting the functions in one place that together can be treated as a theme for the appearance and behavior of your application.

The following table shows how each theme setting maps to an individual project setting.

Table 1. Theme setting to project setting map
Theme Setting Project Editor Tab Project Setting
Arrow key navigation  RCP-only  Other Client settings > Enable arrow key navigation
Automatic field advance Other Client settings > Enable automatic field advance
Cursor positioning on protected fields Rendering Widgets > Field > Allow cursor positioning on protected fields
Field extended attributes Rendering Widgets > Field > Enable extended attributes
Host keypad Rendering Host keypad > Show default host keypad
Keyboard support Other Keyboard support > Enable keyboard support
Operator information area Rendering Operator information area > Show OIA
Overwrite mode (initial) Other Client settings > Overwrite mode (initial)
Rendering using monospaced font Rendering Widgets > Field > Render using monospace font

The Standard theme enables the functions that are enabled by default when a HATS project is first created. Selecting the Modern theme deselects all of the individual functions. Selecting the Classic theme selects all of the functions. Selecting the Custom theme allows you to select any other combination of functions.

Note:
For more theme settings when using DBCS support see Project theme settings.

The Testing section contains links that can be used to test your project. For HATS Web projects the links are:

For HATS rich client projects the links are:

Notes:
  1. Clicking either of these links will perform the same operation as if you right-click on your project in the HATS Projects view and select either Run on Server (Run if rich client) or Debug on Server (Debug if rich client).
  2. For more information about testing modes see Testing your project in HATS Getting Started.
  3. For more information about testing HATS rich client applications see Testing HATS rich client applications.

The Deployment  RCP-only  section includes a Target platform drop-down. Use this drop-down to change the target deployment for your rich client project. This allows you to start building an application targeted for one platform and switch to a different platform at a later time. Supported platforms are Eclipse Rich Client Platform, Lotus® Expeditor Client for Desktop, and Lotus Notes.

If you change the target platform here, and it does not match the target platform of the workspace, a message is displayed informing you of this. The action to take in this case depends on which platform you have changed to for this project.

If you changed to a Lotus Notes® or a Lotus Expeditor Client platform, see Configuring the target platform for information about setting the target platform.

If you changed to the Eclipse Rich Client Platform, select Window > Preferences > Plugin-in Development > Target Platform and select your Rational® SDP installation directory (the default is C:\Program Files\IBM\SDP) from the Location drop-down list.

When prompted to reload the target platform, select Yes.

Also in the Deployment section is a link, open the plug-in manifest, that launches the editor for the plug-in descriptor (plugin.xml) of the project. Advanced rich client development will require modifications to this file.

The Connections, Rendering Settings, and Other Settings sections summarize the settings specified on each of their corresponding tabs. The headings themselves are links to their corresponding tabs which are described in sections that follow.

Connections

The Connections tab displays the information about your project's connections. There are two types of connections in HATS, default (also referred to as transformation) and background. Each HATS application has one default connection for the host application whose screens HATS will transform. Background connections are any connections in a project other than the default connection. HATS does not transform screens from background connections. For more information, see Managing connections.

You can select your default host connection from the Default drop-down list.

There is also a list table displaying all of your project connections. The list displays the connection name, host, host type, port number and code page. You can add additional project connections by clicking the Add button which launches the Create a Connection wizard. HATS allows you to specify more than one connection which can be used for your project. For information about using the wizard see Creating a connection.

Note:
If you select a bidirectional (bidi) code page, refer to Additions to HATS files.

To edit an existing connection, select the connection and click Edit to launch the connection editor. For more information see Connection editor.

The Remove button will delete the highlighted connection. If you click Refresh, the list will be updated.

Template

The Template tab displays the template used to surround a transformation.

On this tab, you can change which template to use as the default template. It will be used for all screens in your application unless you specify a different template for a particular screen using an action in a screen customization.

Note:
Newly supplied templates are marked with an asterisk.

The default template is also the template applied to all transformations in the project, and the template applied with the default transformation as the default action of an unmatched screen event. For information about how to modify the action of the unmatched screen event, see Application events.

When creating or modifying the actions of a screen customization, you can override the default template chosen by selecting a different template. You can also edit the template while you are on the Template tab.

You can create your own templates to use for your HATS projects. For more information, see Create a Template wizard.

Rendering

The Rendering tab displays the settings for default rendering, global rules, text replacement, components, widgets, toolbar  RCP-only , application keypad, host keypad and operator information area. This is where you can configure project-level default values for your HATS project.

Default rendering

Default rendering is responsible for transforming host screens that have not been individually transformed. The selected default rendering set attempts to preserve the original host screen structure while extending the functionality of the application by applying GUI design principles. That is, it does more than render host screen non-protected fields as GUI input fields; it can transform function keys into buttons or links, selection lists into drop-downs, and tabular regions into tables.

Notes:
  1. When you create an individual transformation for a host screen, you can prepopulate it with default rendering. For more information, see Create a Transformation wizard.
  2. You can also later insert default rendering into a transformation. For more information, see Insert Default Rendering.

A rendering set is configured by creating a prioritized list of rendering items. Each rendering item defines a specific region in which a specified host component is recognized and then rendered using a specified widget. For example, you can look for function keys in the bottom region of the host screen and then render them as links.

You can create more than one rendering set for your default transformation. If you create additional rendering sets, only one will be used in the default transformation. To create a new set, click the Add button to open the Add Rendering Sets window. Specify a unique Name and Description (optional) for your new rendering set.

If you want the new rendering set as the default, select the Use this rendering set for default rendering check box.

A rendering set can either be blank (no rendering items defined) by selecting the Create empty rendering set button or you can select a set from the Copy new rendering set from existing set pull-down menu. Rendering sets can also be modified or deleted by selecting the Edit or Remove buttons beside your list.

The following list of rendering items are defined as part of the default rendering set:

Notes:
  1. ENPTUI rendering items appear only if you are using a 5250 or 5250W host and only if ENPTUI support was enabled by selecting the Add graphical interface DDS keywords (ENPTUI) rendering support check box during the initial creation of the HATS project.
  2. Light pen rendering items appear only if you are using a 3270 or 3270E host and only if light pen support was enabled by selecting the Add light pen rendering support check box during the initial creation of the HATS project.

You can add a new rendering item to the selected rendering set for all screens in this project as well as edit or remove existing rendering items by selecting the item to be edited or removed and select the appropriate button to the right of the table.

If you select the Add or Edit buttons, enter a name and description for your rendering item. Next, define the screen region in which your rendering item is applied and then designate the host component to use for recognition and the widget to use for rendering. You can also change the order in which the rendering items are applied, select an item in the list and click the Up or Down buttons to move it towards the top or bottom of the list. Refer to the Insert Host Component or Edit Host Component  Web-only  for more details on the last two panels of the wizard.

Notes:
  1. Dojo widgets are not supported in default rendering items.
  2. The dialog component is a special component used in rendering to recognize modal frames (pop-up frames) on the host screen and render them. However, you can not use the dialog component to insert modal frame host components into individual transformations.

The list of rendering items that make up the rendering set is an ordered list. The ordering of the list matters because each rendering item may consume a part of the host screen that another item further down the list may have recognized as well. The higher the rendering item on the list, the higher the priority. The check box next to each rendering item is used to enable or disable the selection.

Components do not always consume the entire region you specify. Suppose you have configured the selection list component to look for selection lists on the entire screen, but only one list was found in the middle of the screen. Only the region in the middle of the host screen will be marked as "consumed". Any remaining "unconsumed" regions of the host screen can still be transformed by lower priority rendering items.

Care should be taken when using the Table component in a default rendering set because the Table component will recognize almost every screen in the selected region, and no rendering items lower in the list will be recognized.

The final rendering item in the default list, Remaining text and input fields, will transform all remaining "unconsumed" screen regions using the Field component and Field widget. This item should be the last item in a rendering set.

In general, the default rendering set attempts to preserve the original host screen structure while extending the functionality of the application by applying GUI design principles. However, to allow default rendering of host screens to be displayed on mobile devices, a certain amount of compacting may be necessary. With compacting, the amount of HTML and blank space is reduced which may possibly display a different structure of the original host screen. To specify that the currently selected rendering set use compacting, select Use compact rendering  Web-only .

Note:
For Web projects optimized for mobile devices, a rendering set, named compact, is created as the default with this setting selected.

Multiple rendering set example

Suppose you want to create one HATS application, and from that application, allow users to access two host applications that look very different from one another. You have decided you want different rendering sets for each, but want to use the power of HATS default rendering and have as few specific screen customizations as possible.

Call one application APPA and the other application APPB:

  1. Create a rendering set specifically tailored to APPA
  2. Create a rendering set specifically tailored to APPB
  3. Create a transformation "APPA" that has a default rendering tag with a parameter for the APPA rendering set
  4. Create a transformation "APPB" that has a default rendering tag with a parameter for the APPB rendering set
  5. Create a screen customization that recognizes only the first screen of APPA and call it APPAfirst, with actions:
    1. set global variable "WhichApp" to "APPA"
    2. apply transformation APPA
  6. Create a screen customization that recognizes only the first screen of APPB, call it APPBfirst, with actions:
    1. set global variable "WhichApp" to "APPB"
    2. apply transformation APPB
  7. Create a screen customization called APPArest, that recognizes true if global variable "WhichApp" equals "APPA", with action: apply transformation APPA
  8. Create a screen customization called APPBrest, that recognizes true if global variable "WhichApp" equals "APPB", with action: apply transformation APPB
  9. Order the screen customizations in your project settings Events tab like so: APPAfirst, APPBfirst, APPArest, APPBrest

Advanced rendering

To change advanced rendering settings, expand the default rendering tree and click Advanced.

Alternate rendering

In this section you can specify that default rendering should be used if nothing is recognized to render during transformation of a HATS component. This function is particularly useful when an application contains screens that have fields which may switch between unprotected and protected states. For example, if this function is not used and an input field component is being used to recognize the region, nothing will be recognized and rendered if the field switches to a protected attribute state.

Use default rendering on component rendering failure
Use this option to specify at the project level the action to be taken if a host component does not recognize a region in a screen event. This option is not selected by default. This causes nothing to be rendered if a region is not recognized by the specified component. If the option is selected, the region is transformed using default rendering.
Rendering set
From this drop-down, select the rendering set to use for the transformation from the list of currently defined rendering sets.
Notes:
  1. If the selected rendering set is later deleted from the project and therefore does not exist at runtime, the default rendering set is used.
  2. You can also specify this function at the individual component level in a screen transformation. For more information see Insert Host Component.
  3. Dojo widgets are not supported in alternate rendering sets.
HTML tables

In this section you can select an option to create better-formed HTML in default rendering.

Close default rendering table data and row tags
Select this option to specify at the project level that all table data and row tags in default rendering be closed, that is, </td> and </tr>.

This option is not selected by default in order to reduce the amount of HTML included in default rendering. Reducing the amount of HTML is desirable for performance sensitive applications. However, selecting this option may be required for other applications, for example, screen reader applications used for accessibility.

How to make default rendering customizations available in new HATS projects

If you want your default rendering customizations to appear the next time you create a new HATS project, follow these steps:

  1. Create a project and customize your default rendering options.
  2. Open the application.hap file for this project. For Web projects, it is located in \workspace_directory\project name\Web Content\WEB-INF\profiles\. For rich client projects, it is located in \workspace_directory\project name\profiles\.
  3. Copy the source between the <defaultRendering> and </defaultRendering> tags in the application.hap file and replace the source between the <defaultRendering> and </defaultRendering> tags in the application.hap file located under the installed HATS offering.

    For Web projects, the complete file path is: 

    <shared_install_directory>\plugins\com.ibm.hats_nnn\predefined\
projects\new\Web Content\WEB-INF\profiles\application.hap

    For rich client projects, the complete file path is: 

    <shared_install_directory>\plugins\com.ibm.hats_nnn\predefined\
projects\rcp\new\profiles\application.hap
    In the file paths above, shared_install_directory is the shared resources directory where you installed the HATS offering using IBM® Installation Manager, and nnn is the version and build level of HATS.
    Note:
    You must repeat this procedure after installing HATS maintenance. A new application.hap file will be located under a new com.ibm.hats_nnn directory structure.

Global rules

Global rules enable pattern recognition and transformation of host input fields and work with customized and non-customized (default rendered) screens. They can be defined at both the project level and at the screen level. Use this section to specify project-level global rules. See Global Rules for where to define screen-level global rules.

If a project-level and a screen-level global rule are both defined for the same input field, the screen-level rule has priority.

As an example, you can create a global rule that renders any input field with the word Country before it as a drop-down containing codes for the various worldwide countries. Project-level global rules are truly global to your HATS application; they work in screens both transformed by the rendering set, and also in custom transformations. This allows you to enable your entire application to recognize a particular host screen pattern without modifying any of your transformations.

A global rule consists of a configured pattern type and a transformation fragment. The pattern type configuration specifies what sort of content to look for on the host screen. It lets you transform specific fields or all fields of a certain size, or those nearest to a string you specify. For example, the pattern to recognize might be an input field preceded by the word Date. The transformation fragment contains the content to use to replace all occurrences of the pattern in all transformations. The transformation fragment might contain a HATS input field component and a calendar widget. This would result in all input fields preceded by the word Date, across the entire application, displaying as a calendar control.

All configured global rules are displayed in the global rules table. Global rules are processed in the order they appear in this list at the beginning of every Apply transformation action. Once an input field is recognized by one global rule in the list, it will not be recognized by a subsequent global rule. The check box next to each item indicates whether the item is enabled or disabled.

  1. Click the Add button to add a global rule definition to the list of global rules for this project. If you do not have a screen capture, you will be prompted to open the host terminal to capture a screen. Creating a new global rule involves entering a Name, Package (for rich client projects), and Description, and associating it with a Create a new transformation fragment. If you are editing a global rule, you can Use an existing transformation fragment.

  2. Next, select a pattern type to use. The pattern types to select from are as follows:

    Each pattern type component can contain a set of customizable settings as described above. As you change settings, the screen on the left is updated to reflect which input fields would match (note that multiple fields will be highlighted if multiple fields match). You can also highlight certain fields on your host screen by selecting the different options beside Highlight fields. If you want to see where the input fields are defined on the screen, select the Input check box. If you want to see what fields are protected, select the Protected check box. If you want to highlight any hidden fields, select the Hidden check box. To modify the colors of the input, protected or hidden fields highlighting, see Using HATS preferences. If you are using an existing fragment, click Finish to update the global rule set and skip the section below.

  3. If you are creating a new fragment, you must now configure the HATS component to be inserted into the transformation fragment. The purpose of global rules is to find input fields; therefore, only input components are displayed. The host screen region that is being used for configuration of this page is denoted by the selection box surrounding the first matched input field from the previous page, but remember that a project-level global rule will act on all matched input fields, on this host screen and all others. Select a component and widget, and configure their settings. Refer to the Insert Host Component or Edit Host Component  Web-only  for more details. Clicking Finish will update the global rules set and create a new transformation fragment in the Transformation Fragments folder. Make certain to save your project settings after finishing the wizard.

Notes:
  1. Dojo widgets are not supported in global rule transformation fragments, and global rules are not used within Dojo widgets.
  2. For rich client projects, input field components with SWT table widgets cannot be rendered using global rules.

If you need to modify the component and widget settings of an existing global rule, you can go to the Rendering tab, select Global Rules and select the transformation fragment from the list then click Edit.

The transformation fragment is initially created with a special HATS component which corresponds to the settings chosen on the third page of the global rule wizard. This component is special because it does not have region attributes. Instead, it dynamically obtains the region to render at runtime. You can edit this component as you would any other HATS component, but on the first page of the wizard, you must select a global rule instead of a screen region. You can insert other valid HATS transformation content into this transformation fragment as well.

Note:
When you create a global rule, and then edit the transformation fragment, you are not able to see the output on either the design or preview tabs. To view the output, you must use the full page preview from the Edit Host Component function while editing either a transformation fragment or a full transformation that makes use of the global rule.

If you do elect to manually modify the transformation fragment associated with a global rule, it should not be done after using the editor from the Rendering tab. Doing this results in the wrong tag being read and the removal of any modifications made.

Project-level and applicable screen-level global rules are both applied in a screen event transformation. You can disable all global rule processing at the screen event level. To disable:

  1. In the HATS Projects view, open the Screen Customizations, or the Screen Combinations, folder that contains the screen event.
  2. Double click the screen event.
  3. Click the Actions tab.
  4. Select the Apply a transformation action.
  5. Click Edit.
  6. Clear the Apply project-level and screen-level global rules check box.

Text replacement

HATS applications can convert text strings on host screens into different text strings, HTML content  Web-only , or images.

Text Replacement displays a table that shows the original text you want to replace, together with the text, HTML content  Web-only , or image to use as the replacement. Also shown is whether the text search is case-sensitive and whether regular expression support is being used. You can add, modify, or remove any text replacement specifications by using the buttons to the right of the table of values. For information about how to specify these settings, see Text Replacement.

Components and widgets

To change settings for individual components and widgets, you must expand them in the tree to see the individual components and widgets. Some of the components and widgets do not have any customizable settings. For information about the settings that can be customized with the Insert Host Component wizard, see Component and widget settings.

You can override the default project settings for components and widgets when you insert them into transformations. Those modified settings only apply to the individual instances of those components or widgets in the transformation. All the other instances of the component or widget for any transformation in the project still use the default project settings, unless you modify them. For example, you have default settings for the VisualTable component. In a single transformation, you can have two VisualTable components; one that uses the default settings from the project settings, and another that uses modified settings.

Components

Components displays a list of host components which can be used to convert elements of a host screen to objects that can be displayed in a GUI. The settings for a host component specify how that component is to be recognized on the host screen. Some of these components can be modified. For information about host components, see Host component settings.

Widgets

If you select Widgets, you will get a list of all HATS widgets which your project can use to display host components in your GUI. Some of these widgets can be modified. When you customize a widget, you specify how the widget will appear on the Web page. For information about widgets and the settings you can modify, see Widget settings.

Toolbar  RCP-only 

The Toolbar settings panel enables you to change settings related to the toolbar in the Transformation view of your rich client application. The toolbar contains application keypad actions, such as Refresh and Default, as well as actions contributed by the Toolbar widget. For more information about the Toolbar widget see Toolbar  RCP-only .

In HATS Web applications, the application keypad is normally placed at the bottom of or in the side bar of the template. For HATS rich client applications, the functions provided by the application keypad exist as buttons on the Transformation view toolbar. This helps the HATS rich client application fit in with other applications in the rich client environment. See Toolbar for more information about the Transformation view toolbar.

On this panel you can select or clear the Show toolbar check box. If you select it, you can set how the toolbar items are displayed, as Text, Image, or Both text and image. This setting applies to all items on the toolbar (including those contributed by the Toolbar widget).

Application keypad

The default application keypad is displayed in the default template. You can customize the following settings for the application keypad:

Show default application keypad
Select the check box if you want a default application keypad defined in templates or transformations to appear in the GUI when users interact with your application.
Select keys to display
If the Show default application keypad check box is selected, you can select the check boxes next to each of the keys that you want to include on the default application keypad in the GUI.
Display as  Web-only 
Select the value to determine whether the selected keys appear as buttons, links, icons, or in a drop-down list.

Host keypad

You can customize the following settings for the host keypad:

Show default host keypad
Select the check box if you want a default host keypad defined in templates or transformations to appear in the GUI when users interact with your application.
Select keys to display
If the Show default host keypad check box is selected, you can select the check boxes next to each of the keys that you want to include on the default host keypad in the GUI. If you want to include all the available keys, you can select Select All. You can select Deselect All to clear all of the boxes that are selected.
Display as
Select the value from the drop-down list to determine whether the selected keys appear as buttons, links, or in a drop-down list.

You can also add a custom host key by clicking the Add button and then entering the Caption and Mnemonic. Click OK when finished.

Operator information area

Operator information area (OIA) allows you to easily determine the state of the host application. You can customize the following settings for the OIA:

Show OIA
Selecting this box will make the OIA visible. Selecting any of the following check boxes allows you to specify what to display:
Secure host connection
Select this box if you want to display whether the HATS connection is SSL secured
Input inhibited indicator
Select this box if you want to display whether the keyboard is locked, preventing input from the keyboard.
System locked indicator
Select this box if you want to display whether the system is locked while waiting for data to be returned. Refreshing the screen can clear the lock.
Message waiting indicator
Select this box if you want to display the message waiting indicator. This is a 5250-only feature where the OIA displays an indicator when a new message is waiting for the user. Once the user visits the Display Messages panel on the 5250 host, the indicator is cleared (until another new message is received).
Notes:
  1. The user must have their message queue delivery type set to *NOTIFY to receive a message waiting indicator.
  2. Selecting this box has no effect for 3270 or 3270E connections.
Asynchronous update
Select this box if you want to display whether asynchronous update is enabled.
Input mode
Select this box if you want to display whether overwrite mode is enabled (if supported by the browser).
Absolute cursor position
Select this box to display the host cursor position.
Cursor row and column
Select this box if you want to display the host cursor row and column position.
Automatic field advance
Select this box if you want to display whether automatic field advance is enabled (if supported by the browser).
Field data
Select this box if you want to display external field data, such as numeric only or field exit required.
Type-ahead field  RCP-only 
Select this box to display the type-ahead field. This field displays the type-ahead data as the user enters it, but the field cannot be directly edited. This setting is configurable only when the Enable type-ahead support setting is selected. See Enable type-ahead support.
Display area layout  Web-only 
Horizontal
Select this button if you want to display the OIA horizontally (across the bottom of the page).
Vertical
Select this button of you want to display the OIA vertically (as a side frame on the page).
Style class  Web-only 
Enter a cascading stylesheet (CSS) class name that controls the appearance of the OIA.

DBCS

You can configure DBCS options for your project if your default connection specifies a DBCS code page. For more information about DBCS settings on the Rendering tab see Rendering tab.

Events

The Events tab displays a list of prioritized screen events (screen customizations and screen combinations) contained in your project as well as application events.

If the check box next to the name of a screen event is selected, that event is enabled for the project. When a screen event is enabled, and the screen recognition criteria match the host screen, HATS performs the actions specified for that event, and no more screen events are checked for matches. When a screen event is disabled, HATS ignores the event. If you want to test certain screen events, you can disable other screen events. To disable a screen event, clear the check box while you are testing.

HATS applications check each incoming host screen against the list of enabled screen events. If there are multiple screen events that match a given screen, the first screen event that matches the screen is applied. The higher priority screen events should be near the top of the list. For example, you might have one screen event that recognizes a few specific screens, and a second one that recognizes a more general set of screens. If the second screen event is higher in the list than the first, a screen might be recognized by the more general screen recognition criteria and perform the associated actions, rather than recognizing the screen by the more specific criteria and performing the associated actions of the first screen event.

If you want to change the priority of any of the screen events, highlight the event by clicking it. Then click either Up or Down to move the event higher or lower in the list. For more information, see Screen event priority.

Note:
If you have a screen event that specifies an identified next screen, the identified screens will take priority. For more information, see Next Screen.

If you want to edit an application event, click the link of the event below Application Events that you want to edit. For more information see Application events.

Screen event priority

You can modify the order of the screen events using the Events tab of the project editor. See Events for more information.

When a HATS application is running and a new host screen is encountered, HATS checks the first enabled screen event in the event priority list to determine if the screen recognition criteria match the host screen. If so, no more screen events are checked for matches, and the actions for the first screen event are performed. If not, the next screen event in the list is checked to determine whether the screen recognition criteria match the host screen. This continues until the last screen event in the list is checked.

If there are no screen recognition criteria in the screen events that match the current host screen, HATS processes the Blank screen event if it has actions and the screen is blank. Otherwise, HATS processes the unmatched screen event. The HATS unmatched screen event is a special screen event that occurs only when no defined screen events match the host screen. The default action of this event is to display the host screen (default transformation) that applies the default template.

You can modify the actions to be taken if a host screen does not match any of your screen events. For example, you can create a Web page that tells the user that the page was not found and gathers information about how the user reached that screen. You can use the Show URL action to present the Web page.

If you want to modify the action of the unmatched screen event, go to the Events tab and click Unmatched screen under the Application Events section to open its editor. Click the Actions tab at the bottom of the editor to display the actions. Click Add, Edit, or Remove to customize the unmatchedScreen.evnt file.

Application events

The rules-based approach used by HATS enables you to customize screens by applying certain actions upon a screen recognition event. You can also associate actions with other HATS events, known as application events. Application events include application occurrences such as connecting and disconnecting from the host server, starting or stopping your HATS application, or when your application encounters an error or an unrecognized host screen. You can configure these application events to perform certain actions when they occur.

To access the application events, go to the HATS Projects view and double click the Project Settings of your HATS project and select the Events tab. On the Events tab in the Application Events section, click the link for an event to open its editor.

Each application event has various actions associated with it.

The following list provides descriptions of the HATS application events and when they might occur along with their associated actions

Start
A start event occurs when starting your HATS application. There is no default action for the start event.

You can specify the following actions for the start event:

Connect
A connect event occurs when your HATS application connects to the host server. For example, upon connecting you might want to configure your project to run a macro to bypass certain screens to display a logon screen. The default action for the connect event is to obtain a connection. The actions of the connect event always run after the start event.

You can specify the following actions for the connect event:

Blank screen
A blank screen event allows you to specify what actions you would like to perform on the default connection whenever the host screen is blank. This optional event contains no actions by default, and is ignored. If your application often displays a blank screen and requires the user to press the Refresh button, you might add a Pause action to this event to allow the host more time to complete drawing its host screens. If you do specify actions for this event, it is checked after exhausting the list of screen events you've provided in the screen event priority list, and just before running the unmatched screen event.

You can specify the following actions for the blank screen event:

There are also special settings you can use to specify how to handle a blank screen received when initially connecting to the host. For more information, see Screen Handling.

Unmatched screen
An unmatched screen event occurs when HATS receives a screen from the host application that does not match any screen events in the HATS application. If you have configured your HATS application to use the default rendering for some screens, then this is a normal occurrence. If you have tried to recognize all possible host screens in screen events, you can configure the unmatched screen event to show a URL that tells the user he has reached an unexpected screen, asks how he got to it, and offers paths back into the proper screens. The default action for the unmatched screen event is to show the default transformation.

You can specify the following actions for the unmatched screen event:

Error
An error event occurs when HATS encounters an application or host error. You might want to add an action that displays an error in the GUI when an error event occurs. The default action for the error event is to show a URL (error.jsp for Web applications) or to show a composite (CustomErrorComposite for rich client applications).

You can specify the following actions for the error event:

Disconnect
A disconnect event occurs when your HATS application disconnects from the host server. The default action for the disconnect event is to release the default connection.

You can specify the following actions for the disconnect event:

Stop
A stop event occurs after stopping your HATS application. The default action for the stop event is to show a URL (stop.jsp for Web applications) or to show a composite (CustomDisconnectComposite for rich client applications).

You can specify the following actions for the stop event:

Note:
If a macro times out and fails to complete while playing as part of the disconnect event, the disconnect event fails to complete, and the HATS connection is not disconnected. Macro time outs are typically caused when the macro encounters an unknown host screen. To configure the Stop event to successfully terminate the host connection when this occurs, perform the following steps:
  1. Click the link for the Stop event to open its editor.
  2. In the editor click the Source tab.
  3. Add the <release enabled="true"/> action prior to the <show/> action.
  4. The Stop event source should look like the following example: 
    <?xml version="1.0" encoding="UTF-8"?>
<event description="" type="stop">
    <actions>
        <release enabled="true"/>
        <show enabled="true" page="stop.jsp" url="/stop.jsp"/>
    </actions>
</event>
  5. Save the project settings file and restart the application.

Other

The Other tab displays the settings for keyboard support, client locale, connection parameter overrides, asynchronous update, global variable overrides, and client settings.

You can customize the default project settings for each of these by clicking on the node in the customization settings tree.

Keyboard support

You can customize the following settings for keyboard support:

Enable keyboard support
Select the check box if you want your users to be able to use the physical keyboard keys to interact with the host. This enables users to press certain physical keys that have been mapped to host AID keys, such as the F1, SYSREQ, RESET, or ATTN keys. Users can toggle this feature off if they want to use a mapped physical keyboard key to interact with the browser instead.

To use keyboard support in HATS Web projects, you must have a supported Web browser. For the list of supported Web browsers and limitations, see "System Requirements for Host Access Transformation Services" at http://www.ibm.com/support/docview.wss?uid=swg27011794 and "Host Access Transformation Services 9.5 - Known issues and workarounds" at http://www.ibm.com/support/docview.wss?uid=swg27046998.

Turn initial keyboard support state on
Select this check box to make the keyboard enabled when the GUI is initially displayed to the user.

Select from the following options to specify if keyboard support will be limited to function keys displayed on the browser page:

Support only host functions displayed on host keypad  Web-only 
Selecting this option will scan the browser page for recognized function buttons or links. If any functions are found, only those are supported. If none are found, all functions are supported. This was the default behavior in some earlier versions of HATS, and applications migrated from these versions will continue to function as they did previously.
Support all mapped host functions  Web-only 
Select this option to have keyboard support work with all mapped functions, regardless of which host key buttons or links may exist on the browser page. This is the default behavior for new HATS applications.

Client locale

Button captions and messages can be displayed in different languages. To acquire the language to display, customize the following client locale settings:

From the client's default locale
For Web applications the language used to display button captions and messages is determined by the language specified by the user's browser. For rich client applications, the language is determined by either the default operating system value or a value specified when the rich client environment was started.
From the server's primary locale  Web-only 
The language used to display button captions and messages is determined by the locale of the server where the application is deployed.
Always use the following language
You can select the language to use for button captions and messages from the drop-down list.

Connection parameter overrides

HATS allows Host On-Demand session parameters to be used as connection parameters for HATS host connections. For more information about these parameters see the Host On-Demand Knowledge Center at http://publib.boulder.ibm.com/infocenter/hodhelp/v11r0/index.jsp and search on session parameters. Information about these parameters is also available in the document at http://www-01.ibm.com/support/docview.wss?uid=swg21251884.

For HATS Web applications, these connection parameters can be overridden on the URL used to access the HATS application. For example, a URL like the following can be entered: 

http://servername:port/appname/index.jsp?host=9.42.141.26&sessionType=1&port=523&
LUName=LU00001&TNEnhanced=true

After the server name, port, and HATS application name, you specify the welcome page index.jsp, followed by a question mark (?) and then the name=value pairs for the parameters, separated by ampersands (&). The values are the text values defined by Host On-Demand, not the values that are used elsewhere in the application.hap file. For example, sessionType=1 for 3270, and sessionType=2 for 5250.

In addition to the Host On-Demand session parameters, the SSLP12FilePath and SSLP12Password parameters can also be overridden. The SSLP12FilePath and SSLP12Password parameters specify the location and password of the PKCS12 keystore file used for SSL connections. For more information, see Security.

For information about how a rich client application user can override connection parameters using the Properties item on the pop-up menu of the Applications view, see Connection Parameters. For information about programmatically starting a rich client application instance using connection parameter overrides, see the HATS Rich Client Platform Programmer's Guide.

To control which connection parameters, if any, can be overridden, select one of the following radio buttons:

Allow all default connection parameters to be overridden by client requests
Selecting this button allows all connection parameters to be overridden except for those listed and selected in the table.
Do not allow any default connection parameters to be overridden by client requests
Selecting this button allows no connection parameters to be overridden except for those listed and selected in the table.

You can provide exceptions to the choice you select by adding or removing connection parameters. To get a list of available connection parameters, click the Add button.

Selecting the type of connection to use when overriding parameters

When connection parameters are overridden at run time, HATS uses the overrides to create a transformation connection that differs from the one defined when the application was created. The choice of which connection HATS uses as a template for creating this new transformation connection is based on whether you specify the connectionName connection parameter:

When HATS creates a basic transformation connection, certain functions are disabled even if they were enabled for the connection chosen as the template connection. With the basic connection, pooling is always disabled, and the connect and disconnect time-outs are ignored, as are the connect and disconnect macros. The HOD connection parameters for the template connection, such as the host name, and port are copied from the template connection, and then any supplied connection parameter overrides are applied to create the new basic transformation connection. Notice that basic connections are always based on the application's default transformation connection.

When HATS creates a complete transformation connection, all connection settings associated with the connection named by the connectionName parameter are used, including pooling settings, connect and disconnect macros, and connect and disconnect time-outs. Your connection parameter overrides, if any, are then applied to create the pool specification used to create the new transformation connection.

If you specify the name of a background connection as the value of the connectionName parameter, and specify no other overrides, you effectively switch which connection will be used as the transformation connection for that application instance.

All HATS connections are based on a pool specification. A pool specification is an internal object that describes the properties of all connections created from it. The HATS toolkit actually creates pool specifications, and the runtime uses these connection files, like main.hco, to create actual Telnet connections at run time. When you specify connection parameter overrides, the HATS runtime will dynamically create a new pool specification object, if needed, to describe the properties of the new connection. Pool specifications are visible in the HATS administration panel for Web applications. Pool specifications dynamically created when parameter overrides are specified, regardless of whether the connectionName parameter is specified, are automatically destroyed when the last active connection is terminated, provided that pooling is not enabled.

Connection parameter overrides can be different for each user accessing a HATS application. For example, if each user specifies a different LUName override, HATS runtime creates a different pool specification for each user. Ensure that pooling is disabled for the original connection so the pool specification is automatically destroyed. If multiple users specify exactly the same overrides, only one pool specification will be created, and reused to create many identically-configured Telnet connections. For example, if an entire department of users specifies a particular host name override, only one new pool specification will be created and destroyed when no more connections are using that specification.

To be able to specify the connectionName parameter as a connection parameter override, the parameter must be enabled for overrides on the Connection Parameter Overrides page on the Other tab in the project settings editor.

The disconnectOnClose parameter

HATS provides automatic disconnect functions to automatically disconnect the host if the browser is closed before the session disconnects. For more information see Automatic Disconnect and Refresh  Web-only . For applications not using the automatic disconnect functions, the disconnectOnClose parameter performs a similar function. It enables the HATS server to reset the host Telnet session immediately if the browser is closed before the session is manually disconnected from the host by the user. Disconnection normally occurs when the user clicks Disconnect. Resetting the Telnet session is accomplished by having a hidden frame in the browser that launches a new browser when the original browser is closed. The new browser window sends a disconnect signal and then closes itself.

The functionality is only enabled when you specify disconnectOnClose=true and you are using a supported version of Internet Explorer. Specification of the disconnectOnClose parameter is case sensitive. A sample URL request follows: 

http://hostname/appname/index.jsp?disconnectOnClose=true

where appname is the name of your HATS application.

The following conditions are true when using the disconnectOnClose parameter:

Asynchronous Update  RCP-only 

For HATS rich client applications the asynchronous update function is enabled by default. You can disable the function by clearing the Enable asynchronous updates box. The primary purpose of the asynchronous updating mechanism is to automatically update the GUI view if the underlying host screen changes because the host sent a new screen. This provides the following advantages:

Automatic Disconnect and Refresh  Web-only 

For HATS Web applications, the automatic disconnect and refresh functions can be performed by either a client pull method using an AJAX implementation or by a server push method using an applet implementation. To enable the AJAX implementation, select the Enable client pull (AJAX) option. To enable the applet implementation, select the Enable server push (applet) option. To disable both of these functions, select Disabled. The default is Disabled.

Using the client pull (AJAX) method

For HATS Web applications, you can configure the client pull (AJAX) implementation method, which includes the auto-disconnect and auto-refresh functions.

The auto-disconnect function provides the ability to detect when the browser has been out of contact with your HATS application for a predefined period of time. When detected, disconnect processing is performed to clean up resources associated with the browser session and thereby reduce the load on the server. To do this, the disconnect event is run, and the disconnect macro (if configured) is run.

The purpose of the auto-refresh function is to automatically refresh the Web page view of your HATS application if the underlying host screen changes because the host sent a new screen. This eliminates the requirement for the user to click the Refresh button to see asynchronously changed screens from the host.

With auto-refresh enabled, a Web page view is not automatically updated in the following cases:

Unlike the server push (applet) implementation method, the client pull (AJAX) method does not require the use of certain browsers, but instead supports all browsers supported by HATS. Also unlike the server push (applet) method, an additional connection to the server is not required, thus simplifying configuration for the HATS Administrator. The client pull (AJAX) method is mutually exclusive of the server push (applet) method. If either of the client pull (AJAX) functions are enabled, then the server push (applet) configuration is ignored.

Notes:
  1. The client pull (AJAX) method, including the auto-disconnect and auto-refresh functions, is supported only for HATS Web, including JSR 286 portlet, screen transformation applications.
  2. This method is not supported in conjunction with the following HATS functions:
    • JSR 168 portlet projects
    • WebFacing projects
    • Linked HATS/WebFacing projects
    • Integration Objects
    • EJB projects
    • Web services
    • Rich client projects
  3. HATS Web applications optimized for mobile devices do not provide keyboard host key support. As a result, auto-refresh support overwrites any data that the user has entered into the GUI view of the HATS application if a new host screen is asynchronously received from the host application.
  4. AJAX polling from a browser running on an iPhone or iPod touch device stops when you switch from the browser to another application. As a result, when you switch from a browser accessing HATS to another application on the device, HATS disconnects the browser session after the Time to wait for disconnect (seconds) interval has passed. You may wish to increase this interval or disable the auto-disconnect function for HATS applications accessed from iPhone or iPod touch devices. For more information, see Client pull (AJAX) settings.
Client pull (AJAX) settings

To configure the auto-disconnect and auto-refresh functions, use the following settings:

Polling interval (seconds)
The interval in seconds at which the browser will poll the HATS application to restart the disconnect timer, if enabled, and check for host screen updates. The value is specified in seconds to one decimal place. The minimum value is 1.0 second. The default is 5.0 seconds. If Disconnect is selected, then the polling interval value must be less than the value in the Time to wait for disconnect (seconds) setting by at least 1 second.
Note:
If an HTTP session idle timeout is configured by selecting the Set timeout option in the WebSphere Application Server Session management settings for the application server, browser polling of the HATS application effectively disables the HTTP session idle timeout functionality. Because of this, the HATS runtime takes responsibility for monitoring the HTTP session idle timeout period and initiates a disconnect of the HATS session, including running the disconnect event, when no user activity is seen before the idle time is exceeded.

If auto-disconnect and auto-refresh are both disabled for the current page, when an HTTP session idle timeout is triggered, HATS disconnects the session and does not run the disconnect event.

Disconnect
Select this option to enable the auto-disconnect function. If selected, the HATS application initiates disconnect processing if the client has not polled the HATS application within the time specified in the Time to wait for disconnect (seconds) field.
Note:
Disconnect processing is performed to clean up resources associated with the browser session and thereby reduce the load on the server. To do this, the disconnect event is run, and the disconnect macro (if configured) is run
Time to wait for disconnect (seconds)
The time in seconds to wait before performing the auto-disconnect function. The value is specified in seconds to one decimal place. The minimum value is 2.0 seconds. The default is 15.0 seconds.
Refresh
Select this option to enable the auto-refresh function. If selected, the browser initiates a refresh if there has been no user input and the poll response indicates that the host screen has changed.

Using the server push (applet) method

Note:
The server push (applet) method is deprecated. While this method is currently supported, IBM reserves the right to remove this function in a future release. You are advised to use the client pull (AJAX) method instead.

There are two functions performed by the server push (applet) implementation method, also known as the asynchronous update applet:

When using the asynchronous update applet, in addition to the connection used to send transformed terminal screens from the HATS server to the user's browser, a separate socket connection is established between the applet running on the client and the HATS server. This separate socket connection is used to pass small messages, between the client and server, relating to asynchronous screen refreshes from the host and notification to the HATS server that the browser has been closed. Typically, the amount of traffic over this separate socket connection is very small. The sequence of events which occurs to set up this separate socket connection is as follows:

  1. The user enters the HATS application URL in the browser (using a link or typing in the address bar).
  2. The HATS server receives the request and sends a response to the browser, which includes the asynchronous update applet Java™ code.
  3. Once the applet is downloaded to the client, it attempts to communicate directly back to the HATS server by opening a separate socket connection. The local port used on the client for making this socket connection is chosen at random from the available unused ports on the client, and is not configurable. The remote HATS server IP name and port information that the applet attempts to connect to are supplied by the server when the applet is downloaded to the client. If a value of 0 is specified for the server's port number in the HATS application configuration on the server, then one random, unused port number above 1024 is chosen on the HATS server and supplied to the applet as a parameter. The port number that has been chosen by the server can be seen by viewing the page source of the HATS transformation in the browser. Search the page source for the value specified for PARAM NAME="port". For more information about the applet parameter settings, see Server push (applet) settings.

In order to run the applet, a Java-enabled browser is needed. See "System Requirements for Host Access Transformation Services" at http://www.ibm.com/support/docview.wss?uid=swg27011794 for the current list of supported browsers.

Note:
The applet does not work with HATS portlets. For more information, see WebSphere Portal and HATS.
Server push (applet) settings

To configure the server push (applet) implementation method use the following settings:

Host name
This is the host name or IP address of the server where the HATS application will run. If the server is in a horizontally clustered environment, the host name should be changed by editing the application.hap file after the applications file is deployed to the server.

The browser-side applet uses a TCP/IP socket to communicate with the HATS server. The host name of the server hosting the HATS application is needed to create the socket. If HATS is deployed on the same Web server specified by the browser's URL, then the host name parameter doesn't need be specified and the applet will use the Web server's IP address to establish the socket connection. If the HATS application is on a different server, the host name parameter must be specified with either a host name or an IP address.

Port for server socket
The port on the server that the client should use to communicate with the server. A zero (0) specifies that a random unused port above 1024 is used. You can also specify a range of ports, such as 2043-4544, or a list of ports delimited by commas (,), such as 3045, 1345, 9596.
Note:
If HATS is vertically clustered (multiple HATS instances on the same physical server) a different port must be used by each of the HATS instances. If you choose to use a value other than zero (0), you must specify at least as many ports as you have HATS instances. As each HATS instance starts, it tries the specified ports until it finds one that is free.
Time to wait for disconnect (seconds)
The time, in seconds, that the application waits to disconnect the user after the browser is closed. This can occur if you are away from the browser for some time and you want to ensure the application disconnects. The value is specified in seconds to one decimal place. The default is 300.0 seconds (5 minutes). Valid values are numbers greater than or equal to 300.0 seconds.

Additional browser specific settings as well as non-Windows mask settings can be specified for the applet. These settings can be changed by editing the application.hap file.

When you create a new project, a tag will be generated in the file Web Content/WEB-INF/profiles/application.hap within the <classSettings> tag. Following are the default settings for the applet: 

<class name="com.ibm.hats.common.AppletSettings">
   <setting name="disconnectDelay" value="300000"/>
   <setting name="enable" value="false"/>
   <setting name="hostname" value=""/>
   <setting name="ie" value="disconnect|refresh"/>
   <setting name="nonWindows" value="disconnect|refresh"/>
   <setting name="other" value="disconnect|refresh"/>
   <setting name="port" value="0"/>
</class>

A brief explanation of each parameter:

disconnectDelay
This parameter is set from the Time to wait for disconnect (seconds) setting in the GUI for the Enable server push (applet) settings. Whenever the browser closes or loads a new page (that is, the user browses away from the HATS application), the applet will wait this amount of time before disconnecting the user from the host. If it is set too low, users may be disconnected when going from one page in the application to the next. There is no real danger in setting it too high, but resources on the server and host will be held for a user who has closed the browser until the time period has passed. The default value is 300000 milliseconds (5 minutes).
enable
Use this setting to configure which automatic disconnect and refresh update method to use. Specify AJAX to configure the client pull (AJAX) method, specify true to configure the server push (applet) method, and specify false to disable both methods. The default is false. If true is specified, a listening socket is established on the given port. Each browser that connects to this application will have the applet tag inserted in the page.
hostname
The host name or the IP address of the HATS server must be configured in the application.hap file to allow the applet to connect back to the HATS server.
Note:
For horizontal clustering, the host name should be changed by editing the application.hap file. Hand editing the .hap file needs to occur after the .ear has been deployed using the WebSphere Application Server Admin (on the server).
port
Select the port on the server that the client should use for communicating with the server. Zero (0) specifies a random port above 1024; you can also specify a range of ports (for example, 2043-4544) or a comma-delimited list of ports (for example, 3045,1345,9596). The default value is random.
Notes:
  1. If HATS is behind a firewall, a zero (0) value should not be specified because it can be difficult to let arbitrary ports go through the firewall.
  2. For vertical clustering, if HATS is behind a firewall, a port range can be specified. If HATS is on the Web server, zero (0) or a range can be specified instead of a port number. In both cases, it is highly recommended that port numbers are specified individually on the Web servers.

The following browser-related settings determine the features to be used for a given browser or environment:

nonWindows
Specify settings for browsers that run under operating systems other than Windows. The possible options are disconnect, refresh, local. The algorithm looks for l d and r and doesn't care about separators; in order for any options to apply, they must be listed in both the operating system setting and the browser setting; (example: nonWindows=dr other=dr). The default value is disconnect|refresh.
ie
Specify settings for all versions of Internet Explorer. The default value is disconnect|refresh|local
other
Specify settings for other browsers (for example, Opera, Mozilla). The default value is disconnect|refresh.

The following values may be used for the browser-related settings listed above:

disconnect(d)
When the browser is closed, this setting causes the host-side connection from the HATS server to the host to be cleaned up after expiration of the disconnectDelay timer (specified in the application.hap file). This works in any Java-enabled browser.
Note:
For all browsers except Internet Explorer, when the user browses away from the HATS application, this setting will cause the host-side connection to be cleaned up after expiration of the disconnectDelay timer. For more on Internet Explorer settings see disconnectAlways below.
disconnectAlways
This feature enables Internet Explorer to have the same asynchronous update applet-disconnect behavior as all other browsers (non-Internet Explorer). To illustrate: This feature enables you to specify that for Internet Explorer, the session should be cleaned up after the disconnectDelay timer has expired when either the browser is closed or the user browses away from the HATS application.

To change the Internet Explorer behavior, replace disconnect with disconnectAlways. The parameter list for Internet Explorer then appears as follows: 

<setting name="ie" value="disconnectAlways|refresh|local"/>
.
refresh(r)
Allow the server to automatically refresh the page when new content becomes available; this should work in any Java-enabled browser.
local(l)
Refresh only the presentation space of the page; this only works reliably in Internet Explorer V7 and later releases of Internet Explorer V6; it may cause JavaScript errors and browser failures in other environments.

To enable asynchronous update applet client-side tracing, you must specify an HTML parameter, appletJavaConsoleTrace=true, on the HATS entry servlet Web address. For example, 

http://myhost/myhats/entry?appletJavaConsoleTrace=true
Notes:
  1. This is client-side tracing as opposed to the HATS server-side tracing and complements the server-side tracing for debugging applet issues.
  2. Enable this trace only when requested by IBM support personnel.

Global variable overrides

You can use this feature to pass data from the user into the application. For example, you can allow the user to supply a user ID and password, and use them to run a macro.

For HATS rich client applications, the user overrides global variables using the Properties item on the pop-up menu of the Applications view. For more information, see Variables.For information about programmatically starting a rich client application instance using global variable overrides, see the HATS Rich Client Platform Programmer's Guide.

For HATS Web applications, to override a local global variable, you add an HTML parameter hatsgv_varName=newValue to the client's HTTP request. To override a shared global variable, the parameter name is hatssharedgv_varName.

To allow the user to create and set the value of a shared global variable named UserID, you can supply an input field by adding the following statement to the body of the <HATS:Form> tag of a transformation JSP: 

<INPUT name="hatssharedgv_UserID" type="TEXT" size="10">

Any value supplied by the user becomes the new value of the shared variable UserID. If you create the value by JavaScript, instead, and do not want the user to be able to enter the new value, you can use a hidden input field and supply the value yourself:

<INPUT name="hatssharedgv_UserID" size="10" type="HIDDEN" value="alice">

To create a new global variable or change the global variable's value in the URL, something like the following URL can be used in a GET request:

http://hostname/appname/entry?hatsgv_UserID=bob

To control which HATS global variables, if any, can be created or changed by a user's client request, click one of the following radio buttons:

Allow all global variables to be overridden by client requests
This button allows you to override all global variables except for any listed and selected in the table.
Do not allow any global variables to be overridden by client requests
If you click this button, you will not be able to override any global variables except for those listed and selected in the table.

You can add a global variable exception by clicking the Add button. There you can either type a global variable name in the text box or select it from the drop-down list. Select the Shared global variable check box to indicate a global variable that can be shared. For more information, see Interacting with global variables.

If you want to edit a table entry, click Edit. The Remove button will delete the highlighted global variable from the list of exceptions.

Note:
The default for applications migrated from HATS V4 is to allow all global variables to be overridden by client requests. You can change that here after importing the application. The default for new HATS V5, or later, applications is to disallow any global variables to be overridden by client requests.

Client settings

You can customize the following client settings:

Enable HTTP compression  Web-only 
Select this box to use HTTP compression to reduce the number of bytes being transferred between the HATS runtime, which is running on the WebSphere Application Server, and the user's browser. This reduces the transfer time between the HATS runtime and the browser (which improves response time) and reduces the number of bytes flowing in the network (which improves network utilization).
Notes:
  1. To determine if compression is working properly and to see before and after page sizes in bytes, you can enable tracing by updating the trace.UTIL line in the runtime.properties file (or runtime-debug.properties file if running in debug mode in the HATS Toolkit). For example: trace.UTIL=7. For more information, see Appendix A. Runtime properties files. In the trace file, search for the runtime.filters.CompressionFilter trace entries. For example: 
    +--------------------------------------+
Text UTIL runtime.filters.CompressionFilter.doFilter()
 17.50.10.140 11/27/06 Servlet.Engine.Transports : 1
enable compression: true 0000CBAx-81SRWWVmQfQ8-_47oK:-1

+--------------------------------------+
Text UTIL runtime.filters.CompressionFilter.doFilter()
 17.50.10.140 11/27/06 Servlet.Engine.Transports : 1
size before: 25315 0000CBAx-81SRWWVmQfQ8-_47oK:-1

+--------------------------------------+
Text UTIL runtime.filters.CompressionFilter.doFilter()
 17.50.10.140 11/27/06 Servlet.Engine.Transports : 1
size after: 4264 0000CBAx-81SRWWVmQfQ8-_47oK:-1
  2. This feature is not applicable when running the HATS application on WebSphere Portal Server.
  3. HATS ensures the "Accept-Encoding" HTTP header contains "gzip" before compressing a page.
  4. You must restart the application server if you want changes made to compression-related settings picked up while the application is running on the server.
  5. JavaScript (.js) and cascading stylesheet (.css) files are not compressed by this new function. You must configure HTTP compression within your HTTP server to provide compression for these types of files. See the documentation of your HTTP server for more information.
  6. This setting can only be specified at the project level. It cannot be specified for individual transformation JSPs
  7. If you are migrating projects from HATS 5.0.x, 6.0, or 6.0.1 you must manually update the web.xml file with appropriate tags. See Special migration considerations for more information.
Suppress sending unmodified fields  Web-only 
Select this box to specify that HATS should not send modified input field data to the host when the contents of the field are identical to the data supplied by the host.

Clear this box to specify that HATS should send modified input field data even when the contents of the field are identical to the data supplied by the host. For example, if the host filled a field with ABC and the user typed ABC into the field, the typed data will be returned to the host.

Note:
This setting can only be specified at the project level. It cannot be specified for a single transformation JSP.
Include protected, read-only labels in default tab order  RCP-only 
Select this box to specify that the default tabbing order of fields on the transformation view should include protected, read-only fields.

Clear this check box to specify that the default tabbing order should not include protected, read-only fields.

Enable automatic field advance
Select this box to specify that when a user completely fills an input field with data, focus automatically advances to the next input field.

For Web applications, you can selectively disable this function for an individual transformation by adding the following lines just after the </HATS:Form> tag in the transformation file. To selectively enable the function specify true instead of false. 

<script> 
autoAdvance = false;
</script>

For rich client applications, you can selectively disable this function for an individual transformation by overriding the needsAutoAdvanceSupport method on the individual transformation as shown below. To selectively enable the function return true instead of false. 

public boolean needsAutoAdvanceSupport(boolean preferredValue) {
return false;
}
Note:

For DBCS considerations when using this setting see Enable automatic field advance.

Include host and non-host input fields
Select this box to specify that when auto advance is enabled, focus automatically advances to the next input field in the order of the input fields on the transformed screen without regard to the order of the input fields on the host screen.

Clear this box to specify that when auto advance is enabled, focus automatically advances to the next input field in the order of the input fields on the host screen.

Initial cursor position
The position of the host application's cursor normally controls the initial input focus location for your screen transformation. In some limited cases, it might be desirable to have the host application's cursor location ignored, and instead give the initial focus to the first item on the transformation. This is intended for highly-customized transformations where the order of host input fields has been changed. With this feature enabled, the initial focus placement will be the first item on the screen transformation rather than the input field containing the host cursor.
Notes:
  1. The Initial cursor position setting does not appear in the GUI as a configurable setting. It must be set in the source of the transformation file.

    For Web applications, you can enable this feature for a transformation by adding the following lines just after the </HATS:Form> tag in your transformation:

    <script> 
initialInputFocusFromCursor = false;
</script>

    For rich client applications, you can enable this feature for a transformation by overriding the isInitialFocusAtCursorPosition method on the individual transformation as shown below. 

    public boolean isInitialFocusAtCursorPosition() {
return false;
}
  2. Be certain to test your transformation carefully. Many host applications rely on the cursor position for proper behavior. For example, a macro button placed on a transformation may cause the invoked macro to begin entering data in the wrong location on the host application, since the cursor may be in a different location than expected.
nextFieldForDropDown  Web-only 
Use this setting to specify that the cursor position be moved to the next input field when a selection is made from a drop-down list. The default for new projects created in HATS V7.5.0.2, or later, is true. The default for projects created before HATS V7.5.0.2 is false.
Notes:
  1. This setting does not appear in the GUI as a configurable setting. It must be set in the source of the application.hap file as shown below. 
    <class name="com.ibm.hats.common.RuntimeSettings">
         <setting name="nextFieldForDropDown" value="true"/>
</class>
  2. This setting is effective only when Enable automatic field advance is selected.
Overwrite mode (initial)
Select this box to initially enable overwrite mode (if it is supported by the browser). If enabled, text entered into an input field overwrites text at the cursor position one character at a time. If not enabled, text entered into an input field is inserted at the cursor position pushing existing text ahead. The user can toggle from this initial setting using the Insert key.
Note:

For DBCS considerations when using this setting see Overwrite mode (initial).

Select all text on focus
Select this box if you want all text in a field to be selected when the field receives focus, which is typical behavior for a Web application. Clear this box if you want no text selected when the field receives focus which is typical behavior for a terminal emulator.
Notes:
  1. For Web applications:
    • The default is selected.
    • This setting does not affect the Overwrite mode (initial) setting behavior.
    • This setting is only valid when Internet Explorer is used as the browser for the application.
  2. For rich client applications:
    • The default is cleared.
    • When selected, this setting functions like the Overwrite mode (initial) setting in that characters are overwritten as a user types into the field.
    • Text is selected only when the keyboard is used to tab into the field. Text is not selected when clicking the mouse in the field.

  3. For DBCS considerations when using this setting, see Select all text on focus.

Enable busy page  Web-only 
Select this box to display a busy-page message when multiple requests are submitted by the user before processing has completed on the initial request. Clear this box if you do not want a busy-page message displayed. If cleared, you cannot submit any more requests until the server returns a response.
Enable arrow key navigation  RCP-only 
Select this box to allow use of the up, down, right, and left arrow keys to navigate to non-protected host fields on the rendered screen. If the Rendering tab, Field widget, Allow cursor positioning on protected fields setting is also selected, the arrow keys can be used to navigate to both non-protected and protected host fields. This is typical behavior for a terminal emulator application. Clear this box if you do not want to allow use of the arrow keys for navigation.

You can selectively disable this function for an individual transformation by overriding the needsArrowKeyNavigationSupport method on the individual transformation as shown below. 

public boolean needsArrowKeyNavigationSupport(boolean preferredValue) {
return false;
}

To selectively enable the function return true instead of false.

Notes:
  1. Navigation is always based on host field positions, not on the UI position of a field.
  2. When this function is used in conjunction with screen combinations, the algorithm to calculate the next input field will first attempt to navigate to an appropriate field from the same screen as the current field. If an appropriate field does not exist, the next screen (based on the ID of the screen) will be searched to find an appropriate input field.
Enable type-ahead support  RCP-only 
Select this box to enable type-ahead support. If enabled, the user can begin typing data intended for input fields on the next screen (or screens) sent by the host, before they are received and processed by HATS. As the next screen (or screens) are received, HATS sends the previously typed data (type-ahead data) including any keys that submit the input to the host.

If screen customizations exist for these screens, all actions defined in the customization are executed, including applying transformations. However, the type-ahead data is not actually placed into the rendered transformation before being submitted to the host. Instead, it is sent directly to the host as previously typed, bypassing the transformation completely. In this manner, this functions much like a terminal emulator's type-ahead support. What this means to the user is that type-ahead data must conform to what each native host screen expects, not what the applied transformation expects.

If you clear this box, the Type-ahead field setting is cleared in Operator Information Area on the Rendering tab. For information about displaying the type-ahead data in the operator information area, see Type-ahead field.

Notes:
  1. Only host aid keys along with their host data, for example, userid[tab]password[enter], and host navigation keys, for example, tab and home, can be typed ahead.
  2. Application keys and commands, for example, the Disconnect command, which is the default command for the key sequence CTRL+D, cannot be typed ahead.
  3. Key remapping at the RCP Runtime Extension plugin level is supported for host keys and commands in type-ahead mode.

Macro Content Assistance

Use these settings to select which macros to enable for content assistance. While editing a macro on the Source tab of either the Macro Editor or the Visual Macro Editor, press Ctrl+Space to invoke content assistance.

All the macros
Select this radio button to enable content assistance for all of the macros in the project.
Selected macros
Select this radio button to enable content assistance for only those macros selected in the list of macros.
Macros
Select which macros to enable for content assistance.
Select All
Enabled only when the Selected macros radio button is selected. Click this button to select all macros in the list.
Deselect All
Enabled only when the Selected macros radio button is selected. Click this button to clear the selection of all macros in the list.

Portlet settings

These settings apply only to HATS standard (JSR 168 or JSR 286) portlet projects. They can be used to help develop a portlet communication solution. For more information, see Portlet communication. For considerations when using bidirectional language support, see Portlet support.

JSR 168 portlets

Use these settings to define properties received through WebSphere Portal from other JSR 168 portlets (HATS or non-HATS) on the portal server. Click Add to add a new property. In the Property field enter the name of the property that is being received. The name must match the property name used by the sending portlet, for example, the same property name used by the Send global variable action in a HATS JSR 168 sending portlet. In the Global variable field enter the name of the global variable to use to store the value of the received property. If the global variable is indexed, enter the index to use. Select the Shared check box if the global variable is a shared global variable.

When you click Finish, the property is added to the project's application.hap file. In addition, a Web Services Description Language (WSDL) file is created, if one does not already exist, and a receive property is defined in the WSDL file. The name of the WSDL file is <project_name>.wsdl. The WSDL file is required to wire the portlets using the WebSphere Portal wiring tool. The portlet.xml file is updated to reference the location of WSDL file.

If you click Remove, the property is removed from the project's application.hap file, but it is not removed from the WSDL file. You can edit the WSDL file and use the WSDL editor to remove the property.

Note:
If you do not remove the property from the WSDL file, the HATS portlet runs properly as-is.

JSR 286 portlets

Use these settings to define events received through WebSphere Portal from other JSR 286 portlets (HATS or non-HATS) on the portal server. Click Add to add a new event. In the Event name field enter the name of the event that is being received. The name must match the event name used by the sending portlet, for example, the same event name used by the Send global variable action in a HATS JSR 286 sending portlet. In the Global variable field enter the name of the global variable to use to store the value of the received event.

Note:
Event names within a single portlet must be unique.

Click Advanced to set more options if necessary.

On the Advanced Options page, specify either Overwrite the global variable with the new value, or Overwrite a specific index of the global variable with the new value, including the Index to overwrite and the Event payload type of the object. Use the Browse button to assist in entering a valid value type. The type you select must be Serializable. If not, an error message is displayed. The type also must match the type used by the sending portlet, for example, the same type used by the Send global variable action in a HATS JSR 286 sending portlet. Select the Shared check box if the global variable is a shared global variable.

Note:
The Event payload type specification is supported only for JSR 286 portlets. If you manually add the type parameter to the application.hap file source in a JSR 168 project, it is ignored.

When you click Finish, the event is added to the project's application.hap file, and the portlet.xml file is updated. No WSDL files are involved with JSR 286 portlet communication.

Source

The Source tab displays the tags and values in the application.hap file for all the settings you selected, or for which you took the defaults, in your project. As you make changes on other tabs in the project editor, the tags and values displayed under the Source tab change to match.

You can also make changes to the tags and values in the application.hap file directly by editing the source under the Source tab, and they will be reflected on the appropriate tabs of the project editor.

Using HATS preferences

You can use HATS preferences to control the appearance and behavior of HATS Toolkit. These preferences make HATS Toolkit more accessible or simplify programming tasks. To work with HATS preferences, click Window > Preferences and select HATS in the tree view. For quick help on any preference, place your cursor on it and press F1.

You can modify these preferences:

Hide file extensions for known file types
By default, the HATS Projects view does not display common file extensions such as .jsp. For example, all the files in the Templates folder have the .jsp extension. Clear this check box if you want the HATS Projects view to display all file extensions.
Show HATS tips
HATS tips provide helpful suggestions for new users. If you do not want to see HATS tips as you use HATS Toolkit, clear this check box.
Show migration warning
You can decide whether HATS should display a migration warning when it finds projects which have yet to be migrated to HATS V9.5 projects.
Prompt to display terminal window
You can decide whether HATS should display a dialog asking you if you want to turn on the display terminal when you test your project using Debug on Server (for Web projects) or Debug (for rich client projects). This can also be turned off by selecting the check box on the dialog when it pops up.
Show extract hidden fields warning
You can decide whether HATS should display a dialog warning you when it encounters a hidden field on a captured screen when one of the following events occurs:
Show fully qualified Java class name for rich client artifacts
Select this box to show the fully qualified package name for HATS Java source artifacts (for example rich client templates and rich client transformations) in the HATS Projects view. By default this box is not selected and the HATS Projects view will show only the Java class name for the artifact. For example, assume a rich client project contains a transformation with the fully qualified name myProj.transformations.SignOn. By default, only SignOn will be displayed under the Transformations folder of the HATS Projects view. If this box is selected, SignOn (myProj.transformations) is be displayed.

This preference has no affect on what is displayed under the Java Source folder of the HATS Projects view.

Show incompatible JRE warning
If HATS detects an incompatible JRE, it can warn you with a message. Select this box to display a warning dialog that the current JRE is incompatible with HATS. You must change the JRE manually. Clear this box to suppress the warning dialog.
Perform license settings check on workbench startup

HATS checks the license settings of projects in a workspace on startup and prompts the user to update the license settings if any of the projects don't match the master license settings. Clear this check box to disable checking the license settings at startup.

Selection filters
This list of check boxes enables you to select which types of files you want displayed in the HATS Projects view. For example, if you never work with common images or style sheets, you can clear that check box and they will not appear in the HATS Projects view. If you have novice users and you do not want them to work with macros or Java source files, you can clear those check boxes and those files will not be displayed.
Host terminal Preferences
Prompt for all macro prompts before debugging a macro
If selected, a dialog will appear when you first debug your macro, and will allow you to enter values for all prompts at once. If not selected, you will be prompted with a dialog that requests only the value for the current prompt that your macro is stepping through. You will have to enter a value for every prompt, one-by-one. This preference is only used when debugging a macro, it has no effect when playing your macro in HATS Toolkit or when running of your macro or HATS application.
Show macro prompt/extract name warning
Select this box if you want HATS to warn you when you have entered a macro prompt or extract name that is not valid for use with Integration Objects.
Fixed font size
This preference is designed for users with impaired vision. You can specify that the size of the text on the host terminal should not change when the window is expanded or contracted. For example, if you require large type, you can set a large fixed font size and use the scroll bars to view different parts of the host terminal screen.
Screen capture highlighting colors
Colors are used to identify input fields, protected fields, hidden fields, and screen regions that match patterns. Use these preferences to change the colors that are used for these purposes.

There are more preferences which govern other behaviors related to HATS. To use these preferences, expand HATS in the preferences tree and click one of the sub categories:

Accessibility
Alert recognition errors with audible alarm
Select this box to play an audible alert (beep) when there is a recognition error, for example, on the Subfile component settings page. This is useful if the developer must be alerted to use screen reader software to read the message area.
BMS Import
These settings are only used when BMS source files are added to the Maps folder within the HATS project without using the BMS Import wizard.
Host code page
The code page used for the BMS maps being imported.
BMS file code page
The code page used for the BMS file when it was transferred to the workstation.
Default Java Packages
Use this panel to configure default Java package names for HATS artifacts that are Java source files (rich client transformations, rich client templates, rich client macro handlers, business logic, custom widgets, custom components, and RESTful services). A package name makes up the first part of a fully qualified Java class name (for example, for the Java class name com.myCompany.MyClass, the package name is com.myCompany)

When a package name is created for a new artifact, the name of the project is substituted for {project name}. Formatting on this substitution occurs to ensure a valid package name is created (for example, spaces are converted to underscores).

Host Simulation
TCP/IP Port Range
During trace recording and playback, HATS host simulation function uses a range of ports to record or playback host communication with the host terminal or your HATS application. A range of ports is used to allow trace recording and playback on multiple sessions concurrently. Use these fields to set the range of ports. The default starting port in the range is 7021, and the default ending port is 7050.
Time Delay Settings
Delay
Use the options in this drop-down to set the time delay for host simulation to wait during playback before responding to requests from the host terminal or your HATS application. Options are No Delay (host simulation responds with the next screen immediately), Random (host simulation waits a random delay, within defined minimum and maximum times, before responding) , and Actual (host simulation waits the amount of time it actually took the screen to appear during recording). The default is No Delay. If you select Random, use the Minimum and Maximum fields to set delay value ranges.
Minimum (ms)
If the Delay setting is Random, use this field to set the minimum delay in milliseconds that host simulation will wait before responding with the next screen during playback.
Maximum
If the Delay setting is Random, use this field to set the maximum delay in milliseconds that host simulation will wait before responding with the next screen during playback.
Integration Object
Automatically generate Integration Object when saving macro
Select this check box if you want an Integration Object to be generated each time you save a macro. Clear the check box if you prefer to create Integration Objects manually. See Using Integration Objects for information about creating Integration Objects from macros.
Automatically generate EJB Access Bean in HATS EJB Project when an Integration Object is created
Select this check box if you want an EJB Access Bean to be generated in your HATS EJB Project whenever you create an Integration Object. If you have selected the Automatically generate Integration Object when saving macro preference, an EJB Access Bean will be created along with the Integration Object when you create or modify a macro.
Template to be used for Integration Object generation
If you create new Integration Object templates, as described in the HATS Web Application Programmer's Guide, use this preference to specify the template to be used when you create Integration Object file.
Template to be used for Integration Object BeanInfo generation
If you create new Integration Object templates, as described in the HATS Web Application Programmer's Guide, use this preference to specify the template to be used when defining an Integration Object BeanInfo file.
Target Platform  RCP-only 
Prompt to install HATS runtime plug-ins in target platform (rich client only)
The HATS runtime plug-ins must be installed in a target platform in order to test a HATS rich client plug-in in the local test environment for the target platform. When you create a new project and select a target platform, or later change the target platform, the HATS Toolkit will detect if the HATS runtime plug-ins are installed on the selected target platform. Select this box to have the toolkit prompt you to have the runtime plug-ins installed if they are not detected in the target platform.
Transformation
These preferences are used when you create a new blank transformation.
Include a Free Layout Table (Web only)
When you create a blank transformation, the default height and width of the table is retrieved from this setting. By default, this setting is initialized to 100% unless you specify something different. You can also specify measurements in pixels by selecting Pixels from the drop-down menu.
Note:
If a host component is inserted after the table in the transformation, the rendered component will not be displayed when run on server because the table uses 100% of the screen
Except when the project is optimized for mobile devices
Select this preference to prevent including a free layout table in new blank transformations in projects that are optimized for mobile devices.
Open the Properties view after inserting a host component
Select this box to open the Properties view after inserting a host component in a transformation.
Visual Macro Editor
Show screen actions by default
Select this preference to show actions on macro screen objects by default. Clear this preference to hide the actions by default. You can click the action toggle on the macro screen to show/hide the actions for the specific screen. This preference only affects macros opened in the Visual Macro Editor for the first time. The default is selected.
Restrict number of screen actions shown
Specifies the maximum number of actions displayed for a macro screen object. This is useful for complex macros where the interface is too complex if all actions are shown. The default is 5.

When you modify your HATS preferences, you can click Apply to see the results immediately in HATS Toolkit. Click OK to save your new preferences and close the Preferences window, or Cancel to exit without saving. If you click Cancel, only those changes you have made since you clicked Apply are cancelled.

You can return your HATS preferences to their initial values by clicking Restore defaults.

If you configure your HATS preferences on one HATS Toolkit, and you want to copy them to other development workstations, from the Rational SDP menu bar select File > Export > General > Preferences to save your preferences as an .epf file. Transfer the file to each workstation where you want to use it, or make it available over your network. Select File > Import > General > Preferences to import the preferences file.

Use of other Rational SDP preferences

HATS Toolkit appearance and behavior can also be affected by using other preferences available with Rational SDP.

For example, you can use the Label Decorations preference to enable other toolkits such as Java Compile and CVS to decorate HATS labels and images displayed in the HATS Projects view. When there is an error, a red-mark can be displayed next to the file. When checking out files from a CVS repository, version numbers can be displayed next to the file names. To access the Label Decorations preference in Rational Application Developer:

  1. From the menu bar select Window > Preferences.
  2. Expand the General > Appearance tree view.
  3. Select Label Decorations.
    Notes:
    1. Decoration preferences are similarly located in other versions of Rational SDP.
    2. For more information see the Rational SDP Help system and search on Label decorations.