Customizing your ZIETrans project

After following the steps in Creating a basic ZIETrans project, you have a ZIETrans project that looks a lot like the original host application. Now it's time to customize the project. By performing customization, you can:

There are other, advanced customization tasks you can do as well. They are summarized in Performing other customization tasks and described more fully in the ZIETrans User's and Administrator's Guide, and the ZIETrans Web Application Programmer's Guide.

Understanding how a ZIETrans application works

To understand the purpose of the customization techniques described in this chapter, and how they work together, you must first understand how a ZIETrans application processes a host screen to convert it to a GUI. When a user accesses a ZIETrans application, a request is sent to the ZIETrans application, running on a WebSphere® Application Server. The ZIETrans application forwards the request to the host application and receives a host screen. The ZIETrans application transforms the host screen, using the customization you have created in the ZIETrans project, and sends the transformation to the user. Each time the user interacts with the ZIETrans application, the process is repeated.

The ZIETrans application uses a rules-based approach to determine how to convert each host screen. ZIETrans applications can contain a list of screen events (screen customizations and screen combinations), which specify criteria used to match host screens. Each screen event also lists actions to be taken when a match is found. Your ZIETrans application compares each host screen to its ordered set of screen events, and when the first match is found, it performs the specified actions. You do not have to specify how to convert every single screen from your host application. If there is no matching screen event for a host screen, ZIETrans performs the actions defined for the unmatched screen application event, which by default applies the default transformation. See Working with screen events for more information.

Understanding ZIETrans resources

Each ZIETrans project contains a set of different types of resources (artifacts). You can see the resource types listed under the project name in the ZIETrans Projects view in the ZIETrans Toolkit. This section defines the key resource types. For definitions of other ZIETrans resources see the Glossary.

Connection
A connection is a set of parameters, stored in an .hco file, used by ZIETrans to connect to a host application. Learn more about connections in the ZIETrans User's and Administrator's Guide.
Screen event
A screen event is a ZIETrans event that is triggered when a host screen is recognized by matching specific screen recognition criteria. There are two types of screen events, screen customizations and screen combinations.
Screen customization
A screen customization is a type of screen event designed to perform a set of actions when a host screen is recognized. A screen customization definition, stored in a .evnt file, includes a set of criteria for matching host screens, and a list of actions to be taken when a host screen matches these criteria. Screen customizations are described in Working with screen events.
Screen combination
A screen combination is a type of screen event designed to gather output data from consecutive, similar host screens, combine it, and display it in a single output page. The screen combination definition, stored in a .evnt file, includes a set of screen recognition criteria for both the beginning and ending screens to be combined, how to navigate from screen to screen, and the component and widget to use to recognize and render the data gathered from each screen. Screen combinations are described in Working with screen events.
Screen capture
A screen capture is an XML representation of a host screen, stored in a .hsc file, used to create or customize a screen customization, screen combination, transformation, global rule, or macro. Screen captures are useful because they enable you to customize an application even when not connected to the host. They are also useful in creating macros which are the core of ZIETrans Integration Object and Web services support.

Screen captures of video terminal (VT) host screens can be used to create or customize a macro using the Visual Macro Editor and as the check-in screen when configuring pooling. They cannot be used to create screen customizations, screen combinations, transformations, default rendering, or global rules.

Macro
A macro, stored in a .hma file, automates interactions with the host. It can send commands to the host, enter data into entry fields, extract data from the host, and be used to navigate screens on behalf of the user. Macros are described in the ZIETrans User's and Administrator's Guide.
Template
A template, stored in a .jsp file (for Web projects), controls the basic layout and style (such as color and font) of the application. It also defines the appearance of areas that are common in most of your GUI, such as a banner and a navigation area. Templates are described in Updating your project's template.
Transformation
A transformation stored in a .jsp file (for Web projects), defines how host components should be extracted and displayed using widgets in your GUI. Transformations are described in Working with transformations.

Using the host terminal screen as you work

As you develop your ZIETrans project, much of your work will involve screens from your host application. You will use the ZIETrans host terminal to connect to and interact with your host application and use it for these tasks:

Each of these tasks is described in the following sections.

Note:
You also use the host terminal when creating host simulation traces to work with offline when you are not connected to the host. For more information see Using host simulation in the ZIETrans User's and Administrator's Guide.

To open a host terminal session, select your project in the ZIETrans Projects view, then click the Open ZIETrans Host Terminal icon on the main tool bar to open the host terminal session. You can also open the host terminal from the pop-up menu by right-clicking any resource in your project, selecting Open Host Terminal, and then selecting the connection to use. If you leave your host session active, you can move around in it as you customize your project, creating screen events and transformations from the active screens. If you prefer, you can navigate to a few screens in your host application and click the Create Screen Capture icon on the host terminal tool bar to create screen captures that you can use to create screen events and transformations.

Table 2 shows the icons that appear on the host terminal screen.

Table 2. ZIETrans host terminal screen icons
Icon Description
Create ZIETrans Screen Customization
Create a new ZIETrans screen customization, based on the current screen. The drop-down list shows the screen customizations whose recognition criteria this screen matches.
Create ZIETrans Screen Combination
Create a new ZIETrans screen combination, based on the current screen. The drop-down list shows the screen combinations whose recognition criteria this screen matches.
connect
Connect this host session (disabled when the host session is connected)
disconnect
Disconnect this host session (enabled only when the host session is connected)
capture screen
Capture this screen
Create ZIETrans Transformation
Create a new ZIETrans transformation, based on the current screen
open macro
Open a macro. Use the drop-down list to select a macro.
play macro
Play a macro. Use the drop-down list to select a macro.
record macro
Start recording a macro
stop macro
Stop recording a macro
save macro
Save the recorded macro
step into macro
Step Into (F5) each macro action for debugging purposes
step over macro
Step Over (F6) the macro screens for debugging purposes
step return macro
Step Return (F7) in the macro for debugging purposes
resume macro
Resume (F8) playback of the macro
define macro screen recognition criteria
Define the screen recognition criteria for a macro
add a prompt action
Add a prompt action into the current macro (enabled only when recording a macro)
add an extract action
Add an extract action into the current macro (enabled only when recording a macro)
record a loop macro
Record a loop into the current macro (enabled only when recording a macro)
add prompt actions for all fields
Add prompt actions into the current macro for all fields on the screen (enabled only when recording a macro)
add extract actions for all fields
Add extract actions into the current macro for all fields on the screen (enabled only when recording a macro)
show/hide keypad
Show or hide the keypad in the host terminal window
show/hide OIA
Show or hide the textual Operator Information Area (OIA)
Note:
When you use the host terminal through the ZIETrans Toolkit, different actions such as minimizing the terminal window or shifting to a new perspective can cause the terminal window to lose focus and not regain it. Click the terminal window at the cursor position to restore the focus to the terminal window.

Host screen preview

To see what the currently displayed host screen looks like when the ZIETrans application runs in a production environment, click the Host Screen Preview tab at the top of the Host Terminal window. The host screen preview first searches the screen event list in the order specified for your project, and applies the matching screen event. If there are no matching screen event defined for the current screen, the project level template and default rendering rules are applied to the screen.

Working with screen captures

Another way to work with host screens is to navigate to several screens on your host terminal and use the Create Screen Capture icon, shown in the table above, to capture representations of host screens. After you have captured some host screens, you can work with them without being connected to the host computer. You must create screen captures in order to modify default rendering items or create global rules.

When you create screen captures, they are stored in the Screen Captures folder within your project. To work with a screen capture, expand the folder in the ZIETrans Projects view, then double-click the name of the screen capture to start the screen capture editor. The editor shows the host screen; click the Preview tab at the bottom to see how this screen would be transformed by your project.

Click the Host Screen tab at the bottom to return to the host screen. From this tab you can use the icons on the toolbar at the top of the editor to create a screen customization, screen combination, or transformation based on this screen capture. The name of the screen event or transformation defaults to the name of the screen capture.

Note:
Screen captures of video terminal (VT) host screens can be used to create or customize a macro using the Visual Macro Editor and as the check-in screen when configuring pooling. They cannot be used to create screen customizations, screen combinations, transformations, default rendering, or global rules.

Updating your project's template

Typically, the pages displayed by your ZIETrans application consist of two elements:

A template allows you to control the overall appearance of your application. A template is a JSP file in ZIETrans Web projects.

Review the examples of transformed screens in A ZIETrans 3270 example and A ZIETrans 5250 example. In the Web example, the transformed screen includes three main areas: a graphic title banner, a vertical navigation bar which contains application keypad buttons, and the host information area. The template provides a consistent appearance for the pages in an application and enables you to personalize your ZIETrans application. You can use the same template in more than one application.

Although every screen in your application will normally use the same template, you can define a screen event so that it applies a transformation that uses a different template. The new template applies to host screens matching the screen event. (See Working with screen events for more information about screen events.)

You can either modify a template that comes with ZIETrans or create a new template. Launching the Create a Template wizard allows you to create a blank template, a template based off one of the templates shipped with ZIETrans, or a Web page (Web projects only). For your ZIETrans Web projects, you may want to create a template based off your company's Web site.

To change the template for your ZIETrans project, follow these steps:

  1. In the ZIETrans Projects view, click the plus sign Plus sign to expand the resources for the project.
  2. Double-click Project Settings to open the project editor.
  3. Click the Template tab at the bottom of the project editor to view the Template page.
  4. Review the templates provided with the ZIETrans Toolkit and select the one that most closely resembles the way you want your application to look. Save your changes.
  5. Use the editor to modify the template. To open the editor, expand your project in the ZIETrans Projects view. For Web projects, expand the Web Content and Templates folders.

You can also change the default project template by expanding the Templates folder. Right-click on the desired template and select Set as Default Template.

For more information about creating and editing templates see the ZIETrans User's and Administrator's Guide

Editing default rendering

Default rendering is responsible for transforming host screens that have not been individually customized. Default rendering works to change host components on the screen to widgets in the GUI. Certain host components are mapped to specific widgets for conversion in the default transformation. A default list of mapping items is defined for projects. This list is called a rendering set. You can modify the rendering set to suit your needs.

The items in the rendering set are processed in the order in which they are listed. After a rendering item has been applied to a region of the host screen, that region has been consumed and will not be processed again.

To access the default rendering set, follow these steps:

  1. In the ZIETrans Projects view, locate the name of your project. If the list of resources associated with this project is not already expanded, click the plus sign Plus sign to expand it.
  2. Double-click Project Settings.
  3. At the bottom of the editor window, click the Rendering tab.
  4. In the list of rendering items, click Default Rendering. The list of rendering sets appears in the upper table on the right. Using the buttons beside the table, you can add, edit, or remove rendering sets.
  5. In the upper table, select the rendering set you want to edit. The mapping items contained in the rendering set are displayed in the lower table on the right.

As you can see, there are several items defined in a rendering set. A check box precedes each item. When the box is selected, the item is active, and the default transformation uses the item, if ZIETrans finds the component on the screen. If there is an item that you do not want to use in your project, you can clear the check box rather than removing the item entirely. Using the buttons beside the table, you can add, edit, or remove items. The Up and Down buttons allow you to reorder the rendering items.

To define additional default rendering items, follow these steps:

  1. You create new default rendering items from a screen capture. Begin by creating a screen capture, as described in Using the host terminal screen as you work, for each default rendering item you plan to create.
  2. Click Add to add a new item to the list.
  3. In the New Default Rendering Item window, supply a unique name and optionally provide a description for the item.
  4. In the Select Screen Region dialog:
    1. Select a previously captured screen that contains a component for which you want to assign a widget.
    2. In the graphic of the selected screen, draw a rectangle around the region of the screen that contains the component. For example, click and hold the left mouse button and move the mouse until the rectangle surrounds the intended region.
    3. Click Next.
  5. In the Rendering Options dialog:
    1. Select the component from the list of components. If necessary, click the component settings component settings icon to change the default settings.
    2. Select the widget from the list that you want to assign as the default widget for the component. If necessary, click the widget settings widget settings icon to change the default settings.
    3. Click Finish.

For more information about default rendering see the ZIETrans User's and Administrator's Guide.

Creating global rules

Global rules are used to transform specific input fields based on certain criteria. They apply to both customized screens and screens rendered using default rendering. In addition to defining global rules at the project-level, they can also be defined at the screen-level which gives you more control over when the rules are applied.

Each global rule item is defined in a transformation fragment, which can be included in other transformations. You can edit the transformation fragments just like you edit transformations, using all of the options available with transformations.

For more information about global rules see the ZIETrans User's and Administrator's Guide.

Working with screen events

A ZIETrans event is a resource that performs a set of actions based on a certain state being reached. There are two types of ZIETrans events, application events and screen events. For more information about application events see the ZIETrans User's and Administrator's Guide. A screen event is a ZIETrans event that is triggered when a host screen is recognized by matching specific screen recognition criteria. There are two types of screen events, screen customizations and screen combinations.

A screen customization is a ZIETrans screen event designed to perform a set of actions when a host screen is recognized. Examples of screen customizations include recognizing a screen and transforming it into a GUI for the user or playing a macro to skip the screen. The screen customization definition includes a set of screen recognition criteria and a list of actions to be taken when a host screen matches the screen recognition criteria. Screen-level global rules and text replacement settings are also included. Use the Create a Screen Customization wizard to create a new screen customization.

A screen combination is a ZIETrans screen event designed to gather output data from consecutive, similar host screens, combine it, and display it in a single output page. An example of a screen combination includes recognizing a screen that contains only partial output data and navigating through all subsequent screens to gather all of the remaining data to display for the user. The screen combination definition includes a set of screen recognition criteria for both the beginning and ending screens to be combined, how to navigate from screen to screen, and the component and widget to use to recognize and render the data gathered from each screen. Also, it includes a list actions to be performed one or more times, screen-level global rules and text replacement settings. Use the Create a Screen Combination wizard to create a new screen combination.

Actions that can be performed in a screen event are listed below. For more details see the ZIETrans User's and Administrator's Guide.

Creating a new screen customization

To create a new screen customization, follow these steps:

  1. Select your project in the ZIETrans Projects view and expand its resources.
  2. To base the screen customization on an active host terminal, bring up the host terminal, navigate to the screen you want to use, and click the Create ZIETrans Screen Customization icon on the host terminal tool bar. To base it on a screen capture, right-click that screen capture in the tree and select New ZIETrans > Screen Customization. The screen customization is based on the selected host terminal screen or screen capture, and the name of the screen customization defaults to one built from text found on the host terminal screen or from the name of the screen capture. Either of these methods starts the Create a Screen Customization wizard.
  3. On the Screen Customization page:
  4. On the Screen Recognition Criteria page:
  5. On the Actions page:

You do not have to define your screen customization completely when you define it. You can edit it later and modify its screen recognition criteria and actions.

Creating a new screen combination

To create a new screen combination, follow these steps:

  1. Select your project in the ZIETrans Projects view and expand its resources.
  2. To base the screen combination on an active host terminal, bring up the host terminal, navigate to the screen you want to use, and click the Create ZIETrans Screen Combination icon on the host terminal tool bar. To base it on a screen capture, right-click that screen capture in the tree and select New ZIETrans > Screen Combination. The screen combination is based on the selected host terminal screen or screen capture, and the name of the screen combination defaults to one built from text found on the host terminal screen or from the name of the screen capture. Either of these methods starts the Create a Screen Combination wizard.
  3. On the Screen Combination page:
  4. On the Begin Screen Recognition Criteria page:
  5. On the Screen Region page:
  6. On the Rendering Options page:
  7. On the Screen Navigation page:
  8. On the End Screen Recognition Criteria page:
  9. On the Action page:

You do not have to define your screen combination completely when you define it. You can edit it later and modify its screen recognition criteria and actions.

Ordering and enabling your screen events

Your ZIETrans application checks each incoming host screen against an ordered list of screen events. It is essential to have the screen events for your project listed in the correct order. 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 one is listed before the first, it might be applied to one of the screens to which you wanted to apply the first, more specific screen event.

You can reorder your screen events, or review the order in which they are checked, in the Project Settings editor. After you have created your project's screen events, double-click Project Settings in the ZIETrans Projects view. In the editor, click the Events tab. Review the list of screen events and use the Up and Down buttons if you want to change the order. The screen event that you want checked first should be at the top of the list.

You can use the check boxes next to each screen event in the list to enable or disable the screen event. When the box is selected, the screen event is active. If you clear the check box, the ZIETrans application will not use that screen event. Disabling some screen events can be useful during testing and debugging, and will improve performance if you have a lot of screen events that you do not use.

Note:
You can also specify a prioritized list of Next Screens within a screen event to improve performance. For more information see the ZIETrans User's and Administrator's Guide.

Working with transformations

A transformation defines the way in which a host screen is converted into a GUI page. The transformation specifies how to treat each part of the host screen.

Understanding host components and widgets

In host applications, data can be presented in many different ways, such as menus, tables, and command prompts. These are known as host components. Your ZIETrans application converts them into graphical elements, or widgets, for displaying data on a GUI.

ZIETrans comes with a default set of host components, representing the most frequently used methods of presenting data, as well as a set of widgets associated with each one. These host components and widgets are listed in Table 3. As you develop your ZIETrans application, you select a region on the host screen, select a host component (which is responsible for finding specific contents in that region, and select a widget (which is responsible for rendering the output of the host component.

For example, if a host application has a menu in which the user is required to select one of the several choices, you can design your ZIETrans application to display the menu on a GUI as a drop-down list. Alternatively, you can have the menu appear as a list of radio buttons, from which the user makes a choice, or as a list of links or buttons. You can even develop a custom component or widget.

Table 3. ZIETrans host components and their corresponding widgets
Host component Widget
Command line
List
Popup
Radio button (data entry)
Text input
Combo box (Dojo)  Web-only 
Filtering select (Dojo)  Web-only 
Text box (Dojo)  Web-only 
Field
Field
Function key
Button
Button table
Drop-down (selection)
Link
Radio button (selection)
HTML DDS keyword
Label
Input field
Calendar  Web-only 
Check box
List
Popup
Radio button (data entry)
Text input
Combo box (Dojo)  Web-only 
Date text box (Dojo)  Web-only 
Filtering select (Dojo)  Web-only 
Text box (Dojo)  Web-only 
Validation text box (Dojo)  Web-only 
Input field with hints
List
Popup
Radio button (data entry)
Combo box (Dojo)  Web-only 
Filtering select (Dojo)  Web-only 
Item selection
Check box
Drop-down (data entry)
Link (item selection)
List
Popup
Radio button (item selection)
Text input
Combo box (Dojo)  Web-only 
Filtering select (Dojo)  Web-only 
Light pen (attention)
Button
Link
Radio button (selection)
Light pen (selection)
Check box
Scrollbar field (ENPTUI)
Scrollbar (ENPTUI)
Selection field (ENPTUI)
Button
Check box
Link
Radio button (selection)
Selection list
Button
Button table
Drop-down (selection)
Link
Radio button (selection)
Combo box (Dojo)  Web-only 
Filtering select (Dojo)  Web-only 
Subfile
Subfile (check box)
Subfile (drop-down)
Subfile (popup)
Table
Graph (horizontal bar)
Graph (line)
Graph (vertical bar)
Table
Enhanced grid (Dojo)  Web-only 
Table (field)
Graph (horizontal bar)
Graph (line)
Graph (vertical bar)
Table
Enhanced grid (Dojo)  Web-only 
Table (visual)
Graph (horizontal bar)
Graph (line)
Graph (vertical bar)
Table
Enhanced grid (Dojo)  Web-only 
Text
Label
URL
Link

How ZIETrans uses transformations

A ZIETrans transformation is a powerful tool, containing all the information needed to convert components from host screens into widgets on GUI pages. A transformation can be used when it is associated with a screen event. The screen event, described in Working with screen events, includes a list of actions to be taken when a host screen matches its screen recognition criteria. Applying a transformation to the host screen is one of the actions that can be taken.

The easiest way to associate a transformation with a screen event is to create the transformation at the same time that you create the screen event.

Creating a new transformation

There are many ways to create a new transformation. When you create a screen event and apply a transformation as one of the actions, ZIETrans will by default create a transformation with the same name, based on the same host screen, and associate it with the screen event. Because the transformation is named and associated with a host screen, it is created without the use of a wizard.

You can also create a transformation in other ways:

Either of these methods starts the Create a Transformation wizard. If you create a transformation directly from a screen capture or from a host terminal, you will have to associate it with a screen event later by editing the screen event and adding the transformation as an action. This process is described in ZIETrans User's and Administrator's Guide.

The Create a Transformation wizard asks you to select the target project, supply a name for the transformation, and indicate on which screen the transformation is based. The wizard creates the transformation and opens it in the transformation editor so that you can add host components and widgets.

Editing a transformation

While editing a transformation in a ZIETrans Web project, you can use the ZIETrans Components drawer in the Palette view of the Page Designer to drag new components onto the page. You can use the Properties view to modify the settings for the current components. For more information about editing transformations in ZIETrans Web projects, see Editing transformations for Web projects in the ZIETrans User's and Administrator's Guide.

For ZIETrans Web projects, in addition to using the Palette view to edit your transformation, you can use icons on the main toolbar and items from the ZIETrans Tools menu on the menu bar. The following table lists the icons available on the main toolbar.

Table 4. ZIETrans transformation editor main toolbar icons
Icon Description
insert host component
Insert a host component into the transformation.
edit host component
Edit a host component
transform host component for Dojo editing
Transform a host component for Dojo editing
insert default rendering
Insert the default rendering of a screen or partial screen into the transformation
edit default rendering
Edit the default rendering

In addition to the icons on the main toolbar, for ZIETrans Web projects you can use functions from the ZIETrans Tools menu on the menu bar to insert items into a transformation while editing the transformation. These functions are listed in the table below.

Insert Function Description
Insert Tabbed Folder Inserts a folder with tabs. This function is deprecated in ZIETrans V1.0. For alternatives see Insert Tabbed Folder in the ZIETrans User's and Administrator's Guide.
Insert Macro Key Adds a button, link, or drop-down list to enable the end user to execute a macro.
Insert Global Variable Inserts a global variable as text, or as a prompt for a global variable with input fields.
Insert Operator Information Area Inserts the Operator Information Area which shows terminal attributes on the screen.
Insert Host Keypad > Default Keypad Adds the default host keypad.
Insert Host Keypad > Custom Keypad Adds a customized host keypad containing only the keys that you select.
Insert Host Keypad > Individual Key Adds individual host keys that you select.
Insert Application Keypad > Default Keypad Adds the default application keypad.
Insert Application Keypad > Custom Keypad Adds a customized application keypad to the template on your Web page, containing the keys that you select.
Insert Application Keypad > Individual Key Adds individual application keys that you select to the template on your Web page.
Insert All Host Components Inserts all possible host components found on a selected screen capture.
Insert Stored Screen Inserts a screen that you have stored when combining multiple host screens.
Insert Integration Object Properties > Input Inserts inputs from a specified Integration Object JSP page.
Insert Integration Object Properties > Output Inserts outputs from a specified Integration Object JSP page.
Insert Forward to ZIETrans Application Adds a button that forwards JSP control information to the ZIETrans application started by the user.

Performing other customization tasks

You can also do the following kinds of customization on your ZIETrans project.

Auto advance

The auto advance function provides the ability to have focus advance automatically to the next input field in the GUI when a user completely fills an input field. With this feature enabled, GUI focus behaves more like how cursor movement behaves in a typical terminal emulator; after a user has completely filled in a field on the host screen, the cursor automatically moves to the beginning of the next field. To enable this feature on every page of your ZIETrans application, in the Project Settings editor, on the Other tab, select Client Settings and select the Enable automatic field advance check box.

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>

For more information about the auto advance function, see the ZIETrans User's and Administrator's Guide.

Displaying function keys (PF keys)

Many host screens include a list of function keys (PF keys) and their assignments. You can choose to display these keys graphically in your ZIETrans application. For more information about displaying function keys, see the description of host keypad in the ZIETrans User's and Administrator's Guide.

Replacing text strings from the host screen

Your ZIETrans application can replace text strings on host screens with different output on GUI pages. These text strings must be protected text strings, that is, strings that are used only on the screen and never passed to the host application as input. For example, you can replace the text string used as a field label or prompt. You can replace text with different text, HTML coding  Web-only , or images. Java regular expression support can be use as part of the text replacement algorithm. Text strings can even be replaced with a button or link that sends a host key.

You can define text replacement in various ways within a project:

If you define text replacement for the same text in both the project settings and in a screen event with different replacement output, the screen event definition takes precedence. If you define text replacement for the same text in both the screen event and component tag level, the component tag level text replacement takes precedence.

Text replacement using another text string attempts to maintain the original screen layout. If the replacement text is longer than the text to be replaced, the replacement text is truncated to fit into the original field size. However, if there is available white space between the text replacement field and the next host component, the replacement string uses that white space for the next characters of your replacement string.

Text replacement with either HTML strings  Web-only  or images does not preserve the original screen layout, because the replacement output might not fit into the original field size. This might cause undesirable formatting results in the GUI.

Note:
The field widget has an option to render the output on a character by character basis. If you use the field widget, with this option set, to render the section of the host screen that is replaced with an image, undesirable formatting will occur.

When replacing text with any chosen replacement, be sure to test your text replacements carefully to be sure that they do not give unexpected results.

For more information about text replacement see the ZIETrans User's and Administrator's Guide.

Using macros

You can record a macro to create a set of steps to be taken automatically, such as providing information for entry fields or selecting menu options. For example, to access a host application, a user needs to log on to the system with a user ID and password. Logging on to the system is a good candidate for a macro, because your project can traverse the logon screens for the user of your application. Also, using the Visual Macro Editor you can edit the macro to add a conditional path to take if the user ID or password have expired.

To record a simple logon macro, follow these steps:

  1. Highlight a project in the ZIETrans Projects view, and click the Open ZIETrans Host Terminal icon ( Open ZIETrans Host Terminal icon).
  2. Start from the host terminal screen displaying the logon screen, and click the Record Macro icon ( record macro icon).
  3. On the Record Macro panel, select the target project, give the macro a name, such as mylogon, and optionally, add a description. Click Finish.
  4. On the Define the starting screen of the macro panel, you can name the screen or accept the default name. For this example, name the screen logon. Select an area of the screen to be used to recognize the screen. Since a logon screen usually has static text, you can select any text on the screen. Notice that the Strings check box is selected. You should select the At a specified position option of the string position criteria, since the selected text should always be in the same location. The Row and Column fields are filled in with the coordinates of the screen area you selected. Click Next.
  5. On the Recognition Criteria for Screen panel, the text used to recognize the screen is already defined for you, using information collected from the previous screen. Click Finish.
  6. On the host terminal screen displaying the logon screen, enter the user ID and password required and press the Enter key. To the left of the host screen, the progression of the macro displays in the Macro Navigator pane.
  7. There might be other screens that always appear during logging on to a host that are not necessary for the end user to see. Take any action that you would normally take on these screens when logging on, until you navigate to a screen from which you can access the host application for your project. This screen might have some explicit text on it that indicates that an application can be accessed, such as Sign-on complete or Main Menu.
  8. Click the Stop Macro icon ( stop macro icon).
  9. On the Define the exit screen of the macro panel, give the exit screen a name, such as finalscreen. This time, you are defining recognition criteria for the last screen in the macro. Most likely, this is the screen that has the Sign-on complete or Main Menu text on it. You can select this text to be used to recognize the exit screen for the macro. If the text you select will always be located at the same position on the screen, select the At a specified position option of the string position criteria. Otherwise, select the Anywhere on the screen option. Click Next.
  10. On the Recognition Criteria for Screen panel, the text used to recognize the screen is already defined for you, using information collected from the previous screen. Click Finish.
  11. You now have recorded a macro that logs a user on to the system. To add this macro to your project, click the Save Macro icon ( save macro icon).
  12. Now you can close or minimize the host terminal screen, and you can see the macro named mylogon under the Macros folder of your project in the ZIETrans Projects view.

You can run the mylogon macro as an action in a screen customization to log a user on to the host system.

For more information about recording and using macros, refer to the ZIETrans User's and Administrator's Guide and the ZIETrans Advanced Macro Guide.

Creating background connections

When you create a project, you define a connection to the host to handle all transformations. You can define background connections to different hosts to run Integration Objects and macros. Secure Sockets Layer (SSL), Web Express Logon (WEL), pooling, and user lists are supported on these connections. For information about defining connections, refer to the ZIETrans User's and Administrator's Guide.

Defining global variables

You can define global variables to hold data from, for example, an area of the screen, and make that data available to business logic, templates, transformations, and macro prompts. For information about global variables, refer to the ZIETrans User's and Administrator's Guide.

Applying business logic

You can specify a Java method to be called as one of the actions in a screen event, to perform business logic. To add business logic to your ZIETrans project, in the ZIETrans Projects view, right-click on your project and select New ZIETrans > Business Logic. A wizard prompts you for a target project, a class name and a package name and then a stub class is created in the Source directory for the project. For more information about adding business logic to your ZIETrans project, refer to the ZIETrans Web Application Programmer's Guide

Using keyboard support

In addition to representing host-application buttons as part of the screen presentation, you can enable your users to interact with your application by using the keyboard. Refer to the ZIETrans User's and Administrator's Guide for more information.

Creating Integration Objects and EJB projects

You can create Integration Objects from the macros in ZIETrans Web projects and ZIETrans EJB projects. Refer to the ZIETrans Web Application Programmer's Guide for more information on Integration Objects.

ZIETrans EJB projects have no folders for Screen Customizations, Screen Combinations, Screen Captures, or Web Content. EJB projects contain only connections, macros, and Integration Objects. ZIETrans EJB project support is deprecated in ZIETrans V1.0. While support continues for now, HCL reserves the right to remove this capability in a subsequent release of the product. Refer to the ZIETrans Web Application Programmer's Guide for more information on creating and alternatives to using EJB projects.

Integration Objects can be used in Web Services. Refer to the ZIETrans Web Application Programmer's Guide for more information.

You can also create Model 1, Struts, or JSF Web pages to run your Integration Objects. Refer to the ZIETrans User's and Administrator's Guide for more information.

Specifying a workstation ID

In the editor for a 5250 connection you can specify Workstation ID properties. Workstation ID settings include None, Prompt user, Use a specified value, and Use an HTTP session variable  Web-only .

For more information about workstation IDs, refer to the ZIETrans User's and Administrator's Guide.

Using print support

You can add support to your ZIETrans project for local viewing and printing of files from the host application. Refer to the ZIETrans User's and Administrator's Guide for more information.

For a ZIETrans 5250 print support step-by-step example, go to the ZIETrans Infocenter located at https://zietrans.hcldoc.com/help/index.jsp.

Subfile support

ZIETrans can recognize a subfile on a 5250 host screen using the subfile component, and render it in the GUI using the subfile (check box), subfile (drop-down) or subfile (popup) widgets. See a sample host screen containing a subfile Figure 8 and the same screen as rendered by the subfile (drop-down) widget in Figure 9.

For more information about subfile support, refer to the ZIETrans User's and Administrator's Guide.

Figure 8. Subfile host screen
Figure 9. Subfile with default rendering

Using Extended Field Attributes

Fields on 5250 host screens can be marked with specific "check" keywords. Check keywords allow the host application to tell the emulator how certain fields need to react to specific key presses (this key is normally "field exit"). For example, when a field is marked as "auto enter", once a user supplies X number of characters into the field (X being the size of the field), the emulator automatically submits the page back to the host application for processing.

The following 5250 check keywords are supported:

  1. Validity checking:
  2. Keyboard control:

    A field on a host screen can also be marked to allow only a certain type of input. For example, the user name and password field on a typical IBM® i Sign On screen allows only uppercase letters and digits. With this information available, ZIETrans can generate text boxes which, on the client, restrict key presses based on the field type. For example, if a host screen field is marked as "numeric only", only numerals (and other numeric support characters) will be allowed to be entered into the generated text box. This will reduce the chance of the screen becoming locked or being returned to the user with a message they may have never seen before (since most emulators restrict input).

  3. Input restrictions:

By default, support for all of these field attributes is enabled. To disable client-side numeric value formatting, follow these steps to edit your project settings file:

  1. In the ZIETrans Projects view, open the project you want to update.
  2. Double-click Project Settings.
  3. Click the Project Settings Source tab.
  4. For Web applications, in the following class names, add or change the enableCheckAttributes setting to:
    <setting name="enableCheckAttributes" value="false"/>
    
    com.ibm.hats.transform.widgets.FieldWidget
    com.ibm.hats.transform.widgets.CalendarWidget
    com.ibm.hats.transform.widgets.InputWidget
    com.ibm.hats.transform.widgets.PopupWidget
    com.ibm.hats.transform.widgets.TableWidget

By disabling this setting, the user loses support for the following attribute checking:

You can also add these settings manually to any component in your transformations.

For Web applications add the following settings to the component:

<ZIETrans:Component ... widgetSettings="enableCheckAttributes:false|
enableInputRestrictions:false"/>
Note:
To use the "auto enter" feature, the auto advance feature must be enabled; see below for more information.

For more information about extended field attributes, refer to the ZIETrans User's and Administrator's Guide, and the ZIETrans Web Application Programmer's Guide.

Enabling Enhanced Non-Programmable Terminal User Interface (ENPTUI)

ENPTUI enables an enhanced user interface on non-programmable terminals (NPT) and programmable work stations (PWS) over the 5250 full-screen menu-driven interface, taking advantage of 5250 display data stream extensions. These extensions can be also accessed via the DDS programming interface. Graphical DDS keywords specify the GUI controls to be displayed.

ZIETrans recognizes these 5250 display data stream extensions when used, and renders them into appropriate GUI controls. The following subset of graphical DDS keywords are supported:

For more information about ENPTUI support, refer to the ZIETrans User's and Administrator's Guide.

5250 HTML DDS keyword support  Web-only 

DDS programmers can use the HTML keyword to imbed raw HTML data into the 5250 data stream. ZIETrans will enable data that is sent from a host application in the HTML DDS keyword to be rendered in the browser.

For more information about HTML DDS support, refer to the ZIETrans User's and Administrator's Guide.