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 Application events. 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, like the screen customization, it includes a list of actions to be taken, screen-level global rules, and text replacement settings. Use the Create a Screen Combination wizard to create a new screen combination.

Create a Screen Customization wizard

In your ZIETrans project, use the Create a Screen Customization wizard to define screen customizations. You must have the host terminal open or a screen capture before you use the screen customization wizard. BMS maps can also be used to create screen captures used for screen customizations. For more information about BMS map sets, see Importing BMS map sets.

You can do any of the following actions to access the wizard:

For details on settings available in the wizard see Editing screen events.

The settings you define for the screen customization are saved in a screen customization (.evnt) file. You can see this file by expanding the Screen Customizations folder in the ZIETrans Projects view. Use the screen event editor to view and modify the screen customization file.

Create a Screen Combination wizard

In your ZIETrans project, use the Create a Screen Combination wizard to define screen combinations. You must have the host terminal open or a screen capture before you use the screen combination wizard. BMS maps can also be used to create screen captures used for screen combinations. For more information about BMS map sets, see Importing BMS map sets.

You can do any of the following actions to access the wizard:

For details on settings available in the wizard see Editing screen events.

The settings you define for the screen combination are saved in a screen combination (.evnt) file. You can see this file by expanding the Screen Combinations folder in the ZIETrans Projects view. Use the screen event editor to view and modify the screen combination file.

Editing screen events

You can invoke the screen event editor by double clicking on the name of either a screen customization or screen combination .evnt file. The following sections describe each tab of the screen event editor.

Overview

The Overview tab of the screen event editor summarizes all of the information you specified when you created the screen event. It contains the name and description of the screen event, the name and an image of the screen that was used to create the screen recognition criteria, a summary of the actions to be taken, and a summary of the screen recognition criteria. For screen combinations, this tab also contains a summary of the navigation, component, and end screen recognition criteria settings. On this tab, you can modify the description of the screen event, and you can select a different screen to associate with the screen event. The selected screen is used whenever you make changes to the screen event, such as modifying screen recognition criteria, or adding actions.

Screen Recognition Criteria or Begin Screen

The Screen Recognition Criteria tab displays when editing a screen customization event. The Begin Screen tab displays when editing a screen combination event. In both cases the tabs display the screen recognition criteria that you set to match host screens that will trigger the screen event. Host screens can be recognized by any combination of criteria including how many total fields or input fields are on the screen, the coordinates of the cursor's position, and text strings on the screen within a defined rectangle or anywhere on the screen. You can add, edit, or remove criteria on this tab.

Note:

For considerations when using DBCS support see Screen recognition criteria / Begin screen.

Associated screen capture

This option displays only on the Begin Screen tab for a screen combination event. Click the Change button to select a different screen capture to associate with the beginning screen of the screen combination.

Fields criteria

You can use the Total number of fields on a screen, the Number of input fields on a screen, or both as screen recognition criteria. The Total number of fields setting includes input fields, protected text fields, and hidden fields. These are the first two criteria shown on the tab.

If you select the check box for these criteria, they are used to recognize the screen. The fields next to each field criterion show the total number of fields and input fields for the screen specified on the Overview tab. If you change the screen being used for this screen event, click Refresh to update the values for the screen you select.

Note:
If you are using field criteria to recognize screens that have a certain number of fields, and another screen does not contain the same number of fields, that screen is not recognized. For example, one screen might have a list of ten files with ten fields. If the host displays a screen with only eight files in the list and eight fields, the second screen does not match the number of fields criterion of the screen event that matched the first screen.

For an explanation of the Optional and Invert check boxes, see Optional versus non-optional screen recognition criteria and Inverted match of screen recognition criteria.

Cursor position criteria

To use the initial position of the cursor as a screen recognition criterion, either by itself or in conjunction with other criteria, select the Cursor position check box. The fields next to the cursor position criterion show the row and column of the cursor position for the screen specified on the Overview tab. If you change the screen being used for this screen event, click Refresh to update the values for the initial cursor position row and column on the screen you select.

For an explanation of the Optional and Invert check boxes, see Optional versus non-optional screen recognition criteria and Inverted match of screen recognition criteria.

Optional versus non-optional screen recognition criteria

You can select whether the screen recognition criteria you set is optional or non-optional. If you do not select the Optional check box, the recognition criterion is considered non-optional. How you use the Optional check box corresponds to the Host On-Demand screen descriptor attribute, optional.

If you have both optional recognition criteria and non-optional recognition criteria, ZIETrans checks the non-optional criteria first. If all the non-optional criteria match, the screen matches. If at least one of the non-optional criteria does not match, ZIETrans checks the optional criteria. For a screen to match the criteria, ZIETrans must find all non-optional criteria, or at least one optional criterion. Otherwise, the screen fails to match. The following example explains this concept in greater detail.

Note:
Non-optional does not mean required.

Suppose you defined cursor position location and two text strings with the values shown in the following example:

Cursor position recognition  Optional     
                             Row: 1   Column: 1

String recognition           Non-optional   
                             String 1: Welcome
                             Start position: Row: 1   Column: 6
                             End position:   Row: 1   Column: 12

                             String 2: Username
                             Start position: Row 20   Column 10
                             End position:   Row 20   Column 17

In this example, ZIETrans must find both text strings or the cursor position for the screen to match. Because ZIETrans checks non-optional criteria first, ZIETrans looks for the text strings first. If ZIETrans cannot find both text strings in the specified regions of the host screen, then it checks to see whether the optional criterion (cursor position) can be found.

Inverted match of screen recognition criteria

You can select whether the screen recognition criteria you set matches or does not match the host screen. If you select the Invert check box, the recognition criterion must not match the screen for the criterion to be considered true.

Conversely, if you clear the Invert check box, the recognition criterion must match the screen for the criterion to be considered true.

How you use the Invert check box corresponds to the screen descriptor attribute, invertmatch.

Additional criteria

String criterion

Text string location criteria are shown in the Additional Criteria section of the tab. If you have set a string location as a screen recognition criterion, it is shown in the table. The table shows the type of screen location containing the text, some of the characters of the text selected, and whether the text is case-sensitive, optional or invert.

If you highlight a row of the table that defines a string criterion and click Edit, or if you click Add, the Screen Criterion dialog appears. In the dialog panel, you can either modify or specify text string information. You also can select attributes for the string (case sensitive, optional or invert). The panel shows the screen selected on the Overview tab.

You can select any text on the screen by drawing a rectangle around the text. Place your cursor at any point on the screen, click and hold the left mouse button, and move the cursor to another location on the screen to draw the rectangle. The fields on the right of the dialog show the text you selected and the starting and ending row and column numbers of the rectangle. You can specify the part of the screen that should contain the text by clicking one of the radio buttons for Anywhere on the screen, At a specified position, or Within a rectangular region. If the text you selected must be case-sensitive to be recognized as matching the screen recognition criteria, select the Case sensitive check box.

For an explanation of the Optional and Invert check boxes, see Optional versus non-optional screen recognition criteria and Inverted match of screen recognition criteria.

Click OK when you have finished your selections.

Global variable criterion

You can use global variables to define your screen recognition criteria by clicking the down arrow beside the Add button and selecting Global Variable Criterion. If you use global variable criterion, you must either specify a global variable from the Global Variable drop-down list or type in the value. Specify the Verification logic by selecting one of the five bullets:

For an explanation of the Optional and Invert check boxes, in the Attributes section, see Optional versus non-optional screen recognition criteria and Inverted match of screen recognition criteria.

For more information about advanced global variable programming, see the ZIETrans Web Application Programmer's Guide.

Color criterion

You can define your screen recognition criteria by color by clicking the down arrow beside the Add button and selecting Color Criterion. This will open a panel in which you can select the row and column position as well as the foreground and background color.

For an explanation of the Optional and Invert check boxes, see Optional versus non-optional screen recognition criteria and Inverted match of screen recognition criteria.

Compare region to value criterion

The Compare region to value criterion allows the comparison of text from a selected region of the host screen and to a hard coded value.

Start by drawing a box around the region of the terminal or type in the coordinates for the recognition in the Define Region section. The Current value on the terminal will also be shown in the text box.

Next, you can specify what the region will be compared to and how it will be compared. In the Define Comparison section, select how your region will be compared by selecting from the drop-down list next to Region, and enter what it will be compared to in the Value text box.

Comparison Type will either be Numeric or Text (with the a Case sensitive check box option).

Attributes can also be defined. For an explanation of the Optional and Invert check boxes, see Optional versus non-optional screen recognition criteria and Inverted match of screen recognition criteria.

Click OK when you have finished your selections.

Compare region to region criterion

The Compare region to region criterion allows the comparison of one region on the host screen to another region of the same host screen.

First select the First Region tab and start by drawing a box around the region of the terminal or type in the coordinates for the recognition in the Define Region section. The Current value on the terminal will also be shown in the text box.

Next, you can specify how these regions will be compared in the Define Comparison section by selecting from the drop-down menu between Region 1 and Region 2.

Comparison Type will either be Numeric or Text (with the a Case sensitive check box option).

Attributes can also be defined. For an explanation of the Optional and Invert check boxes, see Optional versus non-optional screen recognition criteria and Inverted match of screen recognition criteria.

Repeat the same steps for the Second Region tab then click OK when you have finished.

Condition criterion

The Condition criterion allows you to specify a conditional expression that the macro runtime evaluates during screen recognition, such as $intNumVisits$ == 0.

During screen recognition the macro runtime evaluates the conditional expression and obtains a boolean result.

If the conditional expression evaluates to true then the macro runtime evaluates this descriptor as true. Otherwise the macro runtime evaluates this descriptor as false.

The Condition criterion increases the flexibility and power of screen recognition by allowing the macro runtime to determine the next macro screen to be processed based on the value of one or more variables or on the result of a call to a Java™ method.

In the Condition input field, enter a conditional expression that the macro runtime evaluates during screen recognition.

For an explanation of the Optional and Invert check boxes, see Optional versus non-optional screen recognition criteria and Inverted match of screen recognition criteria.

Custom criterion

The Custom criterion allows you to call custom description code.

In the Class name input field, specify the name of the Java class containing the method you want to run, or click Browse to select the class name from the Source directory.

For an explanation of the Optional and Invert check boxes, see Optional versus non-optional screen recognition criteria and Inverted match of screen recognition criteria.

Rendering (screen combination only)

The Rendering tab is displayed only for a screen combination event. Use this tab to set which component to use to recognize the information to be gathered by the screen combination. Also, use this tab to set which widget to use to render the component. A subset of the ZIETrans components and widgets are supported in screen combination events. See Insert Host Component for more information about using ZIETrans components and widgets.

You can click the Change Region button to change the screen capture and the region of the screen to be considered by the component.

You can also use the following setting in projects to control when the results of the screen combination are first displayed to the user in relation to when the screen combination completes.

use dynamic, cached content loading  Web-only 
Leave this box clear to specify that ZIETrans should navigate through all of the screens of the screen combination and combine all of the results before displaying the results to the user. Select this box to specify that ZIETrans should begin displaying the results to the user as soon as the results from the first screen are gathered and continue updating the display of the results as the screens are navigated.

Navigation (screen combination only)

The Navigation tab is only displayed for a screen combination event. This tab displays the commands necessary to navigate from the begin screen, through intermediate screens, to the end screen of the screen combination. Use the Add, Edit, and Remove buttons to set commands for Up Movement and Down Movement navigation directions. In the Add command or Edit command dialog that appears, there are three command options. Multiple commands per navigation direction can be set by clicking the Add button multiple times. Below are the three command options that can be set.

Send key
Use this option to select a host key to send to the host system.
Insert text
Use this option to insert text at the current cursor location.
Set cursor position
Use this option to set the current cursor position on the host screen.

End Screen (screen combination only)

The End Screen tab is only displayed for a screen combination event. This tab displays the criteria you set that defines the end of the screen combination. You can add, edit, or remove criteria on this tab. You can select one of three types of end criteria, Iteration count only, Screen descriptor only, or First match of either the iteration count or the screen descriptor.

Select ending criteria

Iteration count only
Select this, along with the Number of iterations setting, to specify that this screen combination ends after a fixed number of screens.
Screen descriptor only
Select this, along with the other screen recognition settings, for example the Total number of fields, the Number of input fields, the Cursor position, or the Additional Criteria, to define the end screen for the screen combination.
First match of either iteration count or the screen descriptor
Select this, along with all of the other settings, to specify that the screen combination ends either after a fixed number of screens or when the end screen is recognized, whichever occurs first.

Number of iterations

Select this box to set the number of times to perform the navigation defined on the navigation tab. When the number is reached the end screen is assumed to be reached.

Associated screen capture

Click the Change button to select a different screen capture to associate with the ending screen of the screen combination.

Screen descriptor settings

The screen descriptor settings for the end screen are the same as the recognition criteria settings for the begin screen. See Screen Recognition Criteria or Begin Screen for an explanation of these settings.

Actions

The Actions tab of the screen event editor displays the configured actions for the screen event.

If you want to change the order of the actions, select one and click Up or Down to move that action higher or lower in the list.

You can also Edit or Remove any actions which appear in the list as well as Add a new action.

These actions are performed by the ZIETrans runtime in the order that they are listed. If you want to display the transformed host screen to the user with some prefilled fields, for example, be sure to modify the host screen (using an Insert data action, for example) before you display the transformed host screen (using an Apply transformation action). If you use a Play macro action or a Send key action in a screen event, that action must be the last action in the list.

When all the actions in the screen event have been performed, ZIETrans may send a default command to the transformation host in order to drive the host application off of the currently-recognized screen. Otherwise, an infinite loop might occur through the actions in the screen event. Selecting Send a host key when the list completes to cause screen to change lets you determine which key to send after completion of the action list. By default, the ZIETrans runtime will send an [enter] to the transformation host at the end of the action list. An aid key is sent if:

So, if the action list contains an Apply transformation action, and the user sends the F2 command in response to the transformation, the [pf2] command will be sent rather than any default command. Likewise, if the screen event ends with a Play macro action, no default command will be sent.

You can add, edit, or remove actions on this tab. These are the possible actions:

All the action types you have defined for the screen event and their descriptions are shown in the table on the Actions tab. If you highlight a row of the table and click Edit, the Edit Action dialog appears.

If you click Add, the Select an Action wizard appears. The first panel shows a list of all the actions available. You can select the action you want to occur by clicking the radio button of that action and click Next. Depending on the action you select, the rest of the panel displays information that you can specify for that action.

Note:
You cannot change the action type in the Edit Action dialog. You can change only the information that applies to the action.

Apply transformation action

If you decide to apply a transformation as an action of this screen event, for ZIETrans Web projects you can select the transformation you want to apply from the drop-down list of transformations defined in the project.

For more information, see Working with transformations.

The Template field has the (default template) selected by default. Unless you select a different template to be applied with this particular transformation, the template that surrounds the transformation in the GUI is the template you specified as the default template for the project. The drop-down list contains all the templates defined in the project.

Click Immediate host keys if you want some host keys that the user presses to be sent to the host immediately instead of waiting until all actions have been performed. Select the check boxes of the keys that should be sent to the host immediately. If a host key is sent immediately, no other actions will occur. The immediate sending of these keys applies only to the current transformation, and not to all transformations in the project.

You can disable project-level and screen-level global rules processing by clearing the Apply project-level and screen-level global rules check box.

Execute business logic action

If you decide to run some business logic as the action of this screen event, you must specify in the fields provided the fully qualified Java class name and the Java method for the business logic you want to perform. You can click Browse next to the Class name field to select a class in which the business logic method is defined. You can select any class defined under the Source folder in the ZIETrans Projects view tab of the ZIETrans Toolkit. If you have not created the Java code for this business logic, right click in the ZIETrans Projects view tab, and click New ZIETrans > Business Logic to invoke the Create Business Logic wizard.

For more information about business logic, see the ZIETrans Web Application Programmer's Guide.

Extract global variable action

You can extract information from the host screen and define it as a global variable.

For the region of the host screen, you define the starting and ending rows and columns for the area of the screen you want to assign as a global variable.

In the Advanced section, use the Plane to extract drop-down list to select the data plane to extract. The options are:

Note:
For information about the format and contents of the different data planes in the Host Access Class Library (HACL) presentation space model, see Host Access Class Library Planes -- Format and Content at http://www-01.ibm.com/support/knowledgecenter/SSS9FA_13.0.0/com.ibm.hod.doc/doc/hacl/DWYL0M88.HTML.

When you extract data for the global variable, you can specify a name for a new global variable or select an existing global variable name from the drop-down list for the Name field.

To specify how text extracted from multiple rows of the host screen is defined in a global variable, click Advanced. You must select one of the radio buttons to specify if the extraction should be treated as one string or as a list of strings (indexed). When you select the Extract this region as one string option, the extracted data is saved in a global variable as a single object in the form of a 2-dimensional character array. When you select the Extract this region as a list of strings option, the data is extracted as a 2-dimensional character array and broken up into individual 1-dimensional arrays, each one representing a single extracted row and stored in an index in the global variable.

If you selected an existing global variable in the Name field before you clicked Advanced, you must click one of the following radio buttons specifying how ZIETrans should handle the extracted data:

For the two options that use a specified index, you must enter the number of the index in the Index field.

The following example illustrates how the variable value is modified based on the option you select. Start with an existing indexed variable named "sample". The values of "sample" are "a b c d". The "a" in the value has an index of 0, therefore the value of "sample[0]" is "a", and the "b" in the value has an index of 1, therefore the value of "sample[1]" is "b", and so on. Assume that you extract a new set of values "e f g".

Selecting the Shared check box will allow the global variable to be shared.

For more information about global variables, see Interacting with global variables.

Insert data action

Use the mouse or the Start row and Start column settings to set the region on the host screen where you want data inserted. You can highlight certain fields on the 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.

Click Next then select whether the data is a string or a global variable by clicking the appropriate radio button. To insert a string, type the text in the entry field provided. To insert a global variable, select the name of an existing global variable from the drop-down list or type in the name of the global variable. If you want to use a shared global variable from a different application, you will need to type the name in the field.

If the value of the global variable is indexed (contains a list of strings), click Advanced. You must click one of the radio buttons to specify whether all of the strings are inserted at the specified position one after the other or if the strings are inserted as separate lines into a rectangular region of the screen.

Selecting the Shared check box will allow the global variable to be shared.

For more information about global variables, see Interacting with global variables.

Note:
Inserting information onto a host screen must occur before any transformation occurs for the global variable to appear in the GUI. See Actions for information about modifying the order of the actions.

Set global variable action

You can set global variables to be used by other objects within your project and also by other projects in the .ear. When you set a global variable, you can specify a name or select an existing global variable name from the drop-down list for the Name field. If you select an existing indexed global variable, click Advanced to specify how to handle the setting of the value. The following options are available:

For the two options that use a specified index, you must enter the number of the index in the Index field.

For an example of how a variable value is set based on the option you select, see Extract global variable action.

If you are setting the global variable to a fixed value, type the value in the entry field.

If you are setting the global variable to a calculated value, you specify the operands to be used and the operation of the calculation. The operands can be either fixed values that you enter into the field, or you can use the values of existing global variables for the calculation. If you use an existing indexed global value, and you want to specify an index of the variable to use as the operand, click Advanced. Enter the number of the index in the Index field.

Selecting the Shared check box will allow the global variable to be shared.

For more information about global variables, see Interacting with global variables.

Remove global variable action

Use this action to remove one or more global variables. You can remove one local or one shared global variable, all local global variables, all shared global variables, or all local and shared global variables. For either the One local or the One shared option, enter the name of the global variable you want to remove or select the name from the corresponding drop-down list.

Note:
Names of shared global variables, created in another ZIETrans Web application that runs in same .ear file may not appear in the drop-down list of shared global variables. To remove one of these shared global variables, enter its name in the entry field for the One shared option.

For more information about global variables, see Interacting with global variables.

Show URL action  Web-only 

If you want to show a Web page as the action of this screen event, you must specify the URL (uniform resource locator) address of the Web page in the URL field. The Web page is shown surrounded by the default template, similar to the way a transformation is shown. After the Web page loads, the user returns to the ZIETrans application by clicking the Continue button at the bottom of the Web page.

If embedded objects are not supported or not allowed by the browser, for example, objects with data type of html, this action shows a link to the Web page instead of showing the contents of the Web page.

When you specify the target of the Show URL action, the client's workstation must have access to the target page. Because of this, you may not be able to specify a target Web page that is protected by your enterprise firewall, for example, unless the client's workstation has direct access to the target page. Be sure to give the complete URL for the target, since the client may not otherwise be able to resolve the host name of the target page. If the target page is not on the application server hosting the ZIETrans application (a "cross-domain" access), the browser settings may need to be adjusted to allow the off-server target page to be loaded.

For example, in Internet Explorer V6.0, or later, go to the Tools menu and select Internet Options, then the Security tab. The browser displays the Web content zone in the lower right corner of the browser window. If the page is in the Internet zone, for example, you may need to adjust the Internet zone settings to allow the target page to load. Choose the correct zone, and then press the Custom Level button. Scroll to the Miscellaneous settings, and select a setting for Access data sources across domains. Select Enable to allow the target page to load. Select Prompt to be prompted before loading the target page. If you select Disable, you may be unable to load the target Web page.

Forward to URL action  Web-only 

The forward to URL action enables you to pass control from a transformation-oriented ZIETrans Web application to a JSP that invokes one or more chained Integration Objects. This enables you to use Integration Objects that you have already created. The Integration Objects can use the existing connection or a background connection.

This action is supported in ZIETrans Web projects

To add a forward action to an event, you must specify the following parameters:

Note:
If you plan on running a large JSP, set the JVM system property com.sun.tools.javac.main.largebranch=true and then restart the server. You can set JVM properties by using the administrative console, by setting up arguments for the JVM, or by creating a Custom Property.

The forward to URL allows multiple ways to manage the connection that will be used by the JSP/Integration Object logic. For example:

When you use the forward action, control does not return automatically to the ZIETrans application after the Integration Objects have been run. The JSP must explicitly pass control back to the ZIETrans application. If the default connection was not made before the forward action, and the Integration Objects used the default connection, you must pass the connection to the ZIETrans application to be used as the default connection. In this case you must set a request parameter on the HttpServletRequest before forwarding the request to the ZIETrans application. The parameter is CommonConstants.ZIETrans_EXISTING_CONN. You can obtain the value needed for this parameter by calling the getHPubEndChainName method on the last Integration Object in the chain.

For example, in a Web project, the FORM might look like this:

<FORM NAME="exampleLink" METHOD="GET" 
ACTION='<%= response.encodeURL(request.getContextPath()+"/entry")%>'>
<INPUT TYPE="HIDDEN" NAME="<%= CommonConstants.ZIETrans_EXISTING_CONN %>" 
VALUE="<%= ExampleIO.getHPubEndChainName()%>" />
<INPUT TYPE="submit" VALUE="Return to ZIETrans application" />
</FORM>

You can also use the ZIETrans Tools menu to Insert Forward to ZIETrans Application. This option will automatically insert the code with one exception. It will not include the following line:

<INPUT TYPE="HIDDEN" NAME="<%= CommonConstants.ZIETrans_EXISTING_CONN %>"
       VALUE="<%= IntegrationObjectName.getHPubEndChainName() %>" />

If you want to pass the connection to the ZIETrans application, you must then edit the JSP and add the line of code right after the "FORM NAME=" line of code.

In all other cases (when the default connection was opened before the forward action was invoked, or when the Integration Objects do not use the default connection), you do not have to return the connection. You can omit the first INPUT statement from the example in those cases.

Note:
It is possible for the JSP/Integration Object logic to be the first entry into your ZIETrans application. In that case, you can use the code that is identified to drive your ZIETrans application and pass the connection established by the JSP/Integration Object logic to the ZIETrans application to be used as the default connection (if the connection was created from the default connection definition).

Play macro

If you recorded a macro, you can select it from the drop down box to play it. The macro will begin playback whenever this event is selected. It should be noted that the Play macro action runs a macro on the current connection. The Perform macro transaction, however creates a new connection to run the macro on.

To play a macro, select the Play macro bullet from the Add Action list, then select the name of the macro to play from the drop-down list. If you define a macro to be played as an action of this screen event, it is the last action applied. Be sure to use very specific criteria for recognizing that screen, to ensure that the macro will not be played on other screens. For example, if you are using a string criterion, specify that it must be found at the exact location, rather than anywhere on the screen. Make sure that the screen on which the macro ends does not satisfy the criteria for starting the macro. When you record a macro, be sure that the final screen is not the screen that is recognized by the screen event. If the recognized screen is the final screen of the macro, a loop will be created and the option to send a key to force the screen to change will not run when play macro is performed.

Ordinarily you will not apply a transformation and play a macro as actions on the same screen. If both actions are specified, the transformation will be applied, and the macro will be run only after the user interacts with the transformed screen. The playing of a macro is always the last action to be taken. If you want a macro to be played automatically when a screen is recognized, do not apply a transformation to that screen. When you create the screen event for that screen, you should clear the Apply a transformation check box on the Actions page of the wizard. You can create another screen event for the last host screen to which your macro will navigate, and apply a transformation to govern the appearance of the Web page derived from that final screen.

You can insert a macro button into a transformation to enable the user to run a macro from the transformed screen. In this case, the user can either interact with the transformed screen or click the macro button to cause a macro to begin running at the current host screen.

You can record macros in the ZIETrans Toolkit using the host terminal. For more information about importing macros, see Macros and host terminal.

Perform macro transaction

Selecting this action enables you to play a recorded macro on a new instance of a designated connection, even a connection to a different host. After clicking the Perform macro transaction button, select which macro you want to play in the Play a macro drop-down list and what connection to use in the Perform on connection drop-down list.

Note:
If there is a connect macro defined for the designated connection, the connect macro will be run before your selected macro is run.

Send key

This action sends a specified key to the host screen. Once you have selected the location on the screen to apply your action, select which key to send to your host screen.

Select either PF and PA keys or Other host keys from the bulleted list. Then click the drop-down menu of the bullet you selected and select the key.

Keep in mind that the key you select must change the host screen in some way or an infinite loop of the action results.

The Send key action must always run last when considering the order of your action list.

Disconnect

The Disconnect action immediately performs the disconnect event. By default, the disconnect event disconnects and releases the default connection.

Pause

The Pause action allows you to specify the amount of time (in milliseconds) before continuing with normal processing.

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 tab to specify screen-level global rules. See Global rules for details on how to define a global rule.

Screen-level global rules allow you to use default rendering for a screen and in addition customize the input fields on the screen. For example, by using the Find input fields within a specified region pattern type in your screen-level global rule, you can pinpoint an input field to customize on a screen, for example data within a table, while still using default rendering for the screen.

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

Text Replacement

The Text Replacement tab displays a table in which you can specify the original protected host screen text that 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. Click the Add button to create new text replacement parameters.

You can either select the text you want to replace from the selection window, or type in the text in the Replace text box.

If the Case sensitive check box is selected, it will only search for exact text that you entered in the Replace text box.

To replace with text, type in the text you want replaced in the window below.

If you enter HTML code  Web-only , ZIETrans will highlight it in red allowing you to know whether your code is valid.

Clicking the Insert icon lets you add a button or a link. The settings for Insert Button and Insert Link are:

Caption
The text that you want to appear on the rendered buttons or links
Action key
The host AID key to send to the host when the buttons or links are clicked.
Style class  Web-only 
The cascading stylesheet (CSS) class name that controls the appearance of the buttons or links. The default for buttons is 'HATSBUTTON'. The default for links is 'HATSLINK'

You can also replace text with images by clicking the Image radio button and selecting one from the drop-down list, or clicking the Import button.

Selecting the Regular expression check box allows you to use Java regular expression support as part of the text replacement algorithm. Regular expressions are patterns of characters that describe a set of strings. You can use regular expressions to find and modify occurrences of a pattern. For example, specifying:

Replace: ([\.\-|_\w]+)@([\-\_\.\w]+)
With: <a href="mailto:$1@$2" class="HATSLINK">$1@$2</a>

would result in the following replacement, which converts an e-mail address on a host screen to a link.

Original host screen text: user@company.com
Replacement text: 
<a href="mailto:user@company.com" class="HATSLINK">user@company.com</a>

You can add, modify, or remove any text replacement specifications by using the buttons to the right of the table of values. The text can be replaced at the project level, rendering item level, transformation level as well as the component level.

If you have a list of text replacements, text or HTML created by one text replacement might be replaced by a subsequent text replacement. For example, if you replace a string on the host screen with <img src="yourImage.jpg">, and a subsequent text replacement replaces sr with another string, the <img> tag will no longer work properly, because the src parameter has changed. You can avoid this situation by reordering your text replacement items or by making them more specific, to ensure they do not accidentally replace previous strings.

Notes:
  1. Care should be taken when using text replacement. Text replacement with a disparate number of characters in the strings can cause changes in the GUI representation of the screen. Depending on the widget used for presenting a region of a screen, text on a line of the screen can be contracted, expanded, or forced to a new line. Also, it is generally not efficient to replace strings consisting of a single character or text that has protected fields between it.
  2. By default, text replacement truncates strings that are longer than the text being replaced. Sometimes the text is truncated to maintain the layout of the original host screen on the transformation. Truncation only occurs on text rendered using the field widget (or in some cases of the table widget).

    To enable text replacement of short strings with longer strings, you can add a source setting, truncateToPreserveLength. The values for this setting are true and false. The default value when the setting is not specified is true, which has no effect on your project. Specifying false enables the longer text replacement. To use this setting, you must not be using default rendering. If you use default rendering, the setting is ignored.

    The truncateToPreserveLength setting is a project level setting. It affects all text replacements in the project. If you use this setting, verify that all of your renderings appear as you want them and that any alignment issues that might arise are not problems.

    To enable the setting for the entire project, open the source view of the application.hap file. Locate the class for the transform, and add the highlighted setting as shown in the following example:

    <class name="com.ibm.hats.transform">
       <setting name="truncateToPreserveLength" value="false" />
    </class>
  3. Using the selection text window can be very helpful but the actual text which appears in the Replace field is what will actually be replaced. Text replacement cannot be applied across multiple lines or non-protected fields. You cannot select and replace multiple lines of text by using the preview field.
  4. To replace text with images when the ZIETrans application is accessed through a proxy server, you must configure the ZIETrans application to use the proxy server. For instructions see Configuring ZIETrans applications to use a proxy server.

Next Screen

The Next Screen tab allows you to identify the next likely screens to occur after the screen you are on.

Click the Add button to add screens to the list. You can use the Up or Down buttons to modify the order in which your screens are compared or the Remove button to remove a screen.

If none of the next likely screens in the list match, your application can either Search application event priority list or Execute application event.

The Search application event priority list option searches the event priority list in your project settings for the next screen. This is the default. The Execute application event drop-down list allows you to select an error (or other) event if none of the next likely screens in the list match. The events listed are:

For more information, see Application events.

Using the Next Screen can improve performance if you can predict what screen likely appears next.

Source

The Source tab displays the tags and values in the se-name.evnt file for all the information supplied for the screen event, where se-name is the name you gave to the screen event when you created it. As you make changes on other tabs in the screen event 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 source file, and they are reflected on the appropriate tabs of the screen event editor.

Inhibited screens

The operator information area (OIA) status of a ZIETrans connection is one of the screen matching criteria used by ZIETrans to determine if a screen matches one of the configured screen events. If the OIA status is not a match, then ZIETrans will not match the corresponding screen event, and you will see the default transformation instead of the custom transformation or action. This section provides methods that can be used to handle screens that are input-inhibited (keyboard locked) or that have a nonmatching OIA status.

Recognition criteria

ZIETrans, by default, adds the following recognition criteria for the OIA status to all screen events:

<oia invertmatch="false" optional="false" status="NOTINHIBITED"/>

This means that the OIA status must be NOTINHIBITED, in addition to the other matching criteria, for ZIETrans to evaluate the screen as a match. If the OIA status is anything else, the screen will not be considered a match even if other criteria are met. As a result, the default transformation will be displayed in the browser.

To have ZIETrans ignore the OIA status for a specific screen event, simply change the recognition criteria from NOTINHIBITED to DONTCARE, by following these steps:

  1. In the ZIETrans Projects view, expand your project and the list of screen events (screen customizations or screen combinations).
  2. Double-click on the screen event to start the screen event editor.
  3. At the bottom of the editor, click the Source tab.
  4. Find the line that contains the string status="NOTINHIBITED". Change NOTINHIBITED to DONTCARE.
  5. Save the change by clicking File > Save or pressing Ctrl+S.

If the host screen is in fact inhibited, or locked, you must press a specific key or key combination, such as Ctrl+R (host Reset) or Escape (host Clear), to unlock the screen or to move to the next screen.

Automated handling of inhibited screens

You can enable ZIETrans to automatically recognize and handle an inhibited, or locked, screen by creating a special screen customization for that purpose. To do that:

  1. On the Screen Recognition Criteria tab for the screen customization, clear and remove all criteria.
  2. On the Source tab for the screen customization change the OIA line to have invertmatch="true". When you are done, it should look like this:
    <oia invertmatch="true" optional="false" status="NOTINHIBITED"/>
  3. On the Actions tab of the screen customization, add an action that will clear the OIA status and restore it back to NOTINHIBITED. The correct action to be taken may be different in each case. For example, in some cases simply sending a host key of Enter (or some other host key) may be sufficient to clear the OIA status and restore it back to NOTINHIBITED. However, in other cases, it may be necessary to run a macro that will change the cursor position or send a sequence of several host keys to return the host connection to a state in which the OIA status is NOTINHIBITED.
  4. In the ZIETrans Project Settings editor, select the Events tab and then sort the Screen Event Priority list such that the special screen customization is at the top of the list. This ensures that ZIETrans will detect and handle screens with an INHIBITED OIA status first, before attempting to match any other screen event.

Handling multiple inhibited screens

In some cases there may be more than one inhibited, or locked, screen, each with a different action needed to clear that condition. It may therefore be necessary to create and use more than one special screen customization to handle such cases. In addition to changing invertmatch to true on the OIA line on the Source tab, it may be necessary to add other criteria on the Screen Recognition Criteria tab, so that each screen customization is unique and will only be triggered when appropriate.

For example, a host screen may become locked if the user attempts to type text into a protected field. In this case, perhaps a Cursor in protected area of display message appears. To clear this condition, the user would have to move the cursor to a non-protected area. A special screen customization can be created to automate this. In addition to having invertmatch="true" for the OIA area, it would also look for the message text Cursor in protected area of display. If a match exists, the customization can have the action of running a macro to move the cursor out of the protected area and thus clear the OIA status.

On the same system, perhaps there is a second condition in which the screen may become locked if, for example, the user presses an invalid function key. In this case, the text on the error screen says Invalid function key pressed. To clear this condition, the user might have to press the Enter key. Another special screen customization could be created to automate this. It would also have invertmatch="true" for the OIA area, but it would match the text Invalid function key pressed. For the action, this screen customization would send the Enter key to the host.

Depending on the specific environment, it may be easiest to handle inhibited screens by simply setting the OIA criteria to DONTCARE and allowing the users to handle the situation just as they would with a terminal emulator. As shown above, however, you can also enable ZIETrans to automatically recognize and handle inhibited screens if you create one or more special screen customizations.

Importing BMS map sets

ZIETrans enables you to create screen captures from Customer Information Control System (CICS®) Basic Mapping Support (BMS) map sets. BMS maps are screen definitions files for CICS. Each map defines all or part of a screen and a CICS application typically displays one or more maps to create a complete screen image. Maps contain both static and dynamic areas or fields.

The source for BMS maps is organized in groups called map sets. One map set contains one or more maps. Map sets exist in source form as one map set per source file. When ZIETrans imports BMS Maps, the import takes place at the map-set level. It is not possible to import an individual map.

Maps initially exist on the host system and must be placed on your local file system (or appear to be on the local file system) and have an extension of .bms before being imported to ZIETrans.

You must first copy the BMS map sets from the host to your local file system. This is a manual step outside of ZIETrans that can be done by either physically copying the files to the file system or by connecting the file system to the host using networking software. The file should not be transferred as a binary file. It must be readable locally on your workstation.

  1. Click File > Import > ZIETrans > BMS map sets into ZIETrans to open the Import wizard.
  2. Select the BMS map set files you want to import from the list and the destination of the imported files.
  3. Click on the pull down arrow to select the country Host code page. This is the code page that was used to create the BMS map on the host.
  4. Click on the pull-down arrow to select the BMS file code page. This is the code page used for the BMS file when it was transferred to the workstation.
  5. You have the option to Overwrite existing maps without warning and to Generate one screen capture per map using the map name as the screen capture name.
    Note:
    You may not want to automatically create screen captures if any of the maps need to be combined with other maps to form a screen.
  6. You can also select Overwrite existing screen captures without warning.
  7. Click Finish.

BMS capture files are stored in a separate Maps folder within the ZIETrans project. By default, the Maps folder is not visible in the ZIETrans Projects view unless there are imported maps. Within the Maps folder is a separate folder for each map set, and within each folder, a separate file for each map (using extension .bmc). Additionally, the original source is stored in the file system (extension .bms) and is shown in the folder containing its associated maps. You can edit the source by double clicking the file. If the source is edited and saved, the maps are automatically regenerated and overwritten except for maps that have been modified through the Properties view.

You can also import BMS maps by dragging a BMS source file into the <project>/bmsmaps folder in the Navigator view. The file must be placed directly in the bmsmaps folder and not in any subfolders. If errors occur while importing maps this way, messages will be displayed in the Problems view.

Note:
The source is saved as a reference only and has no function within the project other than to be displayed in the editor. When it is displayed, the entire map set is displayed and no attempt is made to highlight the definition of the particular map that is being displayed in the editor.

After BMS maps are imported, there are several actions that can be taken from the ZIETrans Projects view.

Once your screen captures have been created, you can begin to create ZIETrans screen events.