Modifying a ZIETrans project

When you create a project using the ZIETrans 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 ZIETrans 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 ZIETrans project should not be confused with settings applied throughout ZIETrans. ZIETrans-wide settings can be applied from Window > Preferences > ZIETrans.

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 ZIETrans 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 , 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
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 ZIETrans 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 ZIETrans Web 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 ZIETrans Projects view and select either Run on Server or Debug on Server.
  2. For more information about testing modes see Testing your project in ZIETrans Getting Started.

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 ZIETrans, default (also referred to as transformation) and background. Each ZIETrans application has one default connection for the host application whose screens ZIETrans will transform. Background connections are any connections in a project other than the default connection. ZIETrans 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. ZIETrans 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.

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 ZIETrans 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, application keypad, host keypad and operator information area. This is where you can configure project-level default values for your ZIETrans 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 ZIETrans 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 ZIETrans 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. 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 ZIETrans 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 ZIETrans 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 ZIETrans 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.
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 ZIETrans projects

If you want your default rendering customizations to appear the next time you create a new ZIETrans 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\.
  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 ZIETrans 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
    In the file paths above, shared_install_directory is the shared resources directory where you installed the ZIETrans offering using IBM® Installation Manager, and nnn is the version and build level of ZIETrans.
    Note:
    You must repeat this procedure after installing ZIETrans 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 ZIETrans 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 ZIETrans 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 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 ZIETrans 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 ZIETrans 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.

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 ZIETrans 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 ZIETrans 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 ZIETrans 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 ZIETrans 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

ZIETrans 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 ZIETrans 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.

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 ZIETrans 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.
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, ZIETrans performs the actions specified for that event, and no more screen events are checked for matches. When a screen event is disabled, ZIETrans 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.

ZIETrans 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 ZIETrans application is running and a new host screen is encountered, ZIETrans 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, ZIETrans processes the Blank screen event if it has actions and the screen is blank. Otherwise, ZIETrans processes the unmatched screen event. The ZIETrans 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 ZIETrans enables you to customize screens by applying certain actions upon a screen recognition event. You can also associate actions with other ZIETrans events, known as application events. Application events include application occurrences such as connecting and disconnecting from the host server, starting or stopping your ZIETrans 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 ZIETrans Projects view and double click the Project Settings of your ZIETrans 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 ZIETrans application events and when they might occur along with their associated actions

Start
A start event occurs when starting your ZIETrans 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 ZIETrans 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 ZIETrans receives a screen from the host application that does not match any screen events in the ZIETrans application. If you have configured your ZIETrans 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 ZIETrans 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).

You can specify the following actions for the error event:

Disconnect
A disconnect event occurs when your ZIETrans 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 ZIETrans application. The default action for the stop event is to show a URL (stop.jsp for Web 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 ZIETrans 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 ZIETrans Web projects, you must have a supported Web browser.

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.
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 ZIETrans 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.
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

ZIETrans allows Host On-Demand session parameters to be used as connection parameters for ZIETrans host connections. For more information about these parameters see the Host On-Demand Knowledge Center at https://www.ibm.com/support/knowledgecenter/SSS9FA_13.0.0/com.ibm.hod.doc/WebSphereHOD.html 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 ZIETrans Web applications, these connection parameters can be overridden on the URL used to access the ZIETrans 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 ZIETrans 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.

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, ZIETrans uses the overrides to create a transformation connection that differs from the one defined when the application was created. The choice of which connection ZIETrans uses as a template for creating this new transformation connection is based on whether you specify the connectionName connection parameter:

When ZIETrans 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 ZIETrans 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 ZIETrans 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 ZIETrans 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 ZIETrans 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 ZIETrans 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 ZIETrans application. For example, if each user specifies a different LUName override, ZIETrans 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

ZIETrans 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 ZIETrans 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 ZIETrans application.

The following conditions are true when using the disconnectOnClose parameter:

Automatic Disconnect and Refresh  Web-only 

For ZIETrans 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 ZIETrans 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 ZIETrans 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 ZIETrans 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 ZIETrans. Also unlike the server push (applet) method, an additional connection to the server is not required, thus simplifying configuration for the ZIETrans 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 ZIETrans Web, screen transformation applications.
  2. This method is not supported in conjunction with the following ZIETrans functions:
    • Integration Objects
    • EJB projects
    • Web services
  3. ZIETrans 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 ZIETrans 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 ZIETrans to another application on the device, ZIETrans 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 ZIETrans 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 ZIETrans 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 ZIETrans application effectively disables the HTTP session idle timeout functionality. Because of this, the ZIETrans runtime takes responsibility for monitoring the HTTP session idle timeout period and initiates a disconnect of the ZIETrans 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, ZIETrans disconnects the session and does not run the disconnect event.

Disconnect
Select this option to enable the auto-disconnect function. If selected, the ZIETrans application initiates disconnect processing if the client has not polled the ZIETrans 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, support for this feature may be removed 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 ZIETrans server to the user's browser, a separate socket connection is established between the applet running on the client and the ZIETrans 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 ZIETrans 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 ZIETrans application URL in the browser (using a link or typing in the address bar).
  2. The ZIETrans 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 ZIETrans 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 ZIETrans 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 ZIETrans application configuration on the server, then one random, unused port number above 1024 is chosen on the ZIETrans 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 ZIETrans 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.

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 ZIETrans 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 ZIETrans server. The host name of the server hosting the ZIETrans application is needed to create the socket. If ZIETrans 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 ZIETrans 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 ZIETrans is vertically clustered (multiple ZIETrans instances on the same physical server) a different port must be used by each of the ZIETrans instances. If you choose to use a value other than zero (0), you must specify at least as many ports as you have ZIETrans instances. As each ZIETrans 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 ZIETrans 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 ZIETrans server must be configured in the application.hap file to allow the applet to connect back to the ZIETrans 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 ZIETrans 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 ZIETrans is behind a firewall, a port range can be specified. If ZIETrans 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 ZIETrans 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 ZIETrans 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 ZIETrans 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 ZIETrans entry servlet Web address. For example,

http://myhost/myZIETrans/entry?appletJavaConsoleTrace=true
Notes:
  1. This is client-side tracing as opposed to the ZIETrans server-side tracing and complements the server-side tracing for debugging applet issues.
  2. Enable this trace only when requested by a 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 ZIETrans 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 <ZIETrans: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?teagv_UserID=bob

To control which ZIETrans 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 new ZIETrans 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 ZIETrans runtime, which is running on the WebSphere Application Server, and the user's browser. This reduces the transfer time between the ZIETrans 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 ZIETrans 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 ZIETrans application on WebSphere Portal Server.
  3. ZIETrans 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
Enable Minify JavaScript Feature  Web-only 
Select the check box to enable the minify JavaScript file feature on the ZIETrans project. The minify JavaScript feature will remove the unnecessary code contents like code comments and extra space (formatting), convert variables into shorter variables and so on, without affecting the processing of the resources by the browser in ZIETrans.
Notes:
  1. If ‘Compress default javascript' option is selected, then it will compress the ZIETrans default JavaScript file, which is under the below ZIETrans project folder :
    \Web Content\common
    \Web Content\common\scripts
    \Web Content\ZIETransadmin\scripts
  2. If ‘Compress all javascript' option is selected, then it will compress all the ‘ZIETrans JavaScript files which are located at the below ‘ZIETrans project' folder:
    \Web Content\
  3. Users who do not want to get compressed javascript file, can set the property, ‘avoidCompressJS', in the Source tab of Project, to manually mention the names of the JavaScript files with relative path in value (separated by comma (,)). (Already compressed or minified JS file names (abc.min.js) must be given in values to avoid being compressed again, as they are already compressed). For example:
    <setting name="avoidCompressJS" value="\bootstrap.min.js,\common\bidishape.js"/>
    After selecting these features, while doing an ‘Export project', a dialog box showing the ‘Compress JavaScript progress bar' will be displayed and the process of compression for the javascript file will begin as per the given options.
  4. In a workspace, if a system crash, IDE crash or an abnormal condition occurs during a JavaScript compress process, the javascript files which already got compressed are reverted back to their original stage in the same project with the same workspace by default, when the IDE is restarted. system will take care to revert back original file in same project. (The crash recovery of the project to the original stage will occur only if at least one file related to that project is open at the time of system crash, for which, an ‘export project' operation is being carried out by enabling the compress JavaScript option).
  5. If an error is displayed on the console for a javascript definition or declaration during the Compress operation, then all the errors should be fixed for the file before re-running the export project operation. An Example of Error during Compress operation is shown below:
    INVALID_OCTAL_LITERAL. This style of octal literal is not supported in strict mode. at lxgwfunctions.js line 53 : 15
    The Compress operation of the javascript file has failed due to an error in one of the javascript files. Correct those JS and re-run the export project.
  6. This feature is applicable when running the ZIETrans application on a WebSphere Portal Server.
Enable same origin policy protection  Web-only 
Select this box to prevent CSRF attack on the ZIETrans, which is running on a ZIETrans supported application Server, and the user's browser. This will discard the request that is originated from a URL that has no protocol, or request originated from an unauthorized origin/website.
Notes:
  1. To protect against CSRF attack, declare the ZIETrans running URL as the ‘param-value', in web.xml under the ‘HatsCSRFValidationFilter' section, for param-name= target.origin. For example:
    <param-value>http://localhost:9080/Test/entry</param-value>
  2. To determine if the CSRF validation is working properly, uncheck the box in client setting and attempt a CSRF attack. This will now allow the modification of ZIETrans data by a different source. The same operation will not be allowed from a different origin, if the client setting check-box is selected.
  3. This feature is not applicable when running the ZIETrans application on a WebSphere Portal Server.
  4. The application server must be restarted for the changes made to origin policy-related settings to be picked up while the application is running on the server.
  5. After enabling origin policy, the default URL, /entry, /ZIETransadmin/admin , /index.jsp and the default project context path ( http://localhost:9080/Test/ ) will be secure from CSRF attack if the origin policy is enabled.
  6. Users can customize to secure more custom URLs. If a user has added a new servlet, then it has to be configured in web.xml file, as shown below to secure it from a CSRF attack.For example:
    http://localhost:9080/Test/transfer
       <filter-mapping>
    			<filter-name>HatsCSRFValidationFilter</filter-name>
    		  <url-pattern>/transfer</url-pattern>
       <filter-mapping>
  7. Users can enable multiple origin sources by adding the source list as the ‘param-value' while configuring, under the filter ‘HatsCSRFValidationFilter' section, against param-name = source.origin. For example:
    <param-value>http://ZIETrans:9081/index, http://ZIETransapp.com/, http://citi.com</param-value>
Enable token based protection  Web-only 
Select this box to prevent CSRF attack on the ZIETrans, which is running on a ZIETrans supported application Server, and the user's browser. This will discard the request even if the attacker is able to bypass the same origin policy.
Notes:
  1. To determine if the CSRF validation is working properly, uncheck the box in client setting and try a CSRF attack. This will permit the modification of ZIETrans data by a different source, if the ‘Enable same origin policy' option is unchecked. The same operation will not be allowed from a different origin, if this check-box is selected, and if an attacker is able to bypass the origin policy, then a token based protection will not allow to modify ZIETrans data by CSRF attack.
  2. This feature is not applicable when running the ZIETrans application on a WebSphere Portal Server.
  3. The application server must be restarted for the changes made to token based settings to be picked up while the application is running on the server.
  4. Token based check, when enabled, will secure the default URL /entry, /index.jsp and the default project context path from CSRF attack, and if the origin policy is enabled then /entry, /ZIETransadmin/admin , /index.jsp and the default project context path ( http://localhost:9080/Test/ ) will be secured from CSRF attack.
  5. Users can customize to secure more custom URLs. If a user has added a new servlet, then it has to be configured in web.xml file, as shown below to secure it from a CSRF attack, and has to add the INPUT HIDDEN FORM field name HatsCSRF in the respective jsppage and the value can be appended by the HatsCSRFValidationFilter token..For example:
    http://localhost:9080/Test/transfer
       <filter-mapping>
    			<filter-name>HatsCSRFValidationFilter</filter-name>
    		  <url-pattern>/transfer</url-pattern>
       <filter-mapping>
    <INPUT TYPE="HIDDEN" NAME="HatsCSRF" VALUE="">
  6. If both of the protection features have been enabled, then unknown sources cannot modify ZIETrans data, and if an attacker is able to bypass the same origin policy, then the token based protection will restrict the modification of ZIETrans user data.
Suppress sending unmodified fields  Web-only 
Select this box to specify that ZIETrans 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 ZIETrans 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.
Enable XSS Policy protection  Web-only 
In the web.xml file, provide the below instructed value to protect against XSS attack on the ZIETrans, which is running on a ZIETrans supported application Server, and the user's browser. This will discard XSS attack.
Notes:
  1. To protect against XSS attack, in the web.xml file, under the filter ‘HatsHeaderSecurityFilter' section, update the ‘param-value' from "NO" to "YES". Listed three policies can be enabled and disabled independently by giving respective value "YES" or "NO".
    • "Content-Security-Policy"
    • "X-Content-Type-Options"
    • "X-XSS-Protection"
    The policies are disabled by default. For example:
       <param-value>YES</param-value>
  2. To determine if the XSS validation is working properly, set the ‘param-value' to "NO" in web.xml ‘HatsHeaderSecurityFilter' section
  3. This feature is not applicable when running the ZIETrans application on a WebSphere Portal Server.
  4. The application server must be restarted for the changes made to XSS policy protection-related settings to be picked up while the application is running on the server.
  5. Users can customize to secure more custom URLs. If a user has added a new servlet, then it has to be configured in web.xml file, as shown below to secure it from an XSS attack.For example:
    http://localhost:9080/Test/transfer
       <filter-mapping>
    			<filter-name>HatsHeaderSecurityFilter</filter-name>
    		  <url-pattern>/transfer</url-pattern>
       <filter-mapping>
     
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 </ZIETrans:Form> tag in the transformation file. To selectively enable the function specify true instead of false.

<script> 
autoAdvance = false;
</script>
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 </ZIETrans:Form> tag in your transformation:

    <script> 
    initialInputFocusFromCursor = false;
    </script>
  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 ZIETrans V7.5.0.2, or later, is true. The default for projects created before ZIETrans 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 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.

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.

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 ZIETrans preferences

You can use ZIETrans preferences to control the appearance and behavior of ZIETrans Toolkit. These preferences make ZIETrans Toolkit more accessible or simplify programming tasks. To work with ZIETrans preferences, click Window > Preferences and select ZIETrans 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 ZIETrans 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 ZIETrans Projects view to display all file extensions.
Show ZIETrans tips
ZIETrans tips provide helpful suggestions for new users. If you do not want to see ZIETrans tips as you use ZIETrans Toolkit, clear this check box.
Show migration warning
You can decide whether ZIETrans should display a migration warning when it finds projects which have yet to be migrated to ZIETrans V1.0 projects.
Prompt to display terminal window
You can decide whether ZIETrans 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). 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 ZIETrans should display a dialog warning you when it encounters a hidden field on a captured screen when one of the following events occurs:
Show incompatible JRE warning
If ZIETrans 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 ZIETrans. You must change the JRE manually. Clear this box to suppress the warning dialog.
Selection filters
This list of check boxes enables you to select which types of files you want displayed in the ZIETrans 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 ZIETrans 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 ZIETrans Toolkit or when running of your macro or ZIETrans application.
Show macro prompt/extract name warning
Select this box if you want ZIETrans 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 ZIETrans. To use these preferences, expand ZIETrans 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 ZIETrans 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 ZIETrans artifacts that are Java source files (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, ZIETrans host simulation function uses a range of ports to record or playback host communication with the host terminal or your ZIETrans 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 ZIETrans 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 ZIETrans EJB Project when an Integration Object is created
Select this check box if you want an EJB Access Bean to be generated in your ZIETrans 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 ZIETrans 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 ZIETrans Web Application Programmer's Guide, use this preference to specify the template to be used when defining an Integration Object BeanInfo file.
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 ZIETrans preferences, you can click Apply to see the results immediately in ZIETrans 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 ZIETrans preferences to their initial values by clicking Restore defaults.

If you configure your ZIETrans preferences on one ZIETrans 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

ZIETrans 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 ZIETrans labels and images displayed in the ZIETrans 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.