Editing a screen customization

A screen customization is a HATS resource with two parts: a set of screen recognition criteria used to match one (or more) host screens, and a list of actions to be taken when a host screen matches the screen recognition criteria.

When you create your project in HATS Studio, you 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 on BMS map sets, see Importing BMS map sets.

The recognition criteria and the actions you define for the screen customization are saved in a screen customization (.evnt) file. You can use the screen customization editor to view and modify those criteria and actions.

You can see the screen customizations you have created by expanding the Screen Customizations node of the HATS Project View tab of the HATS Studio. You can invoke the screen customization editor by double clicking on the name of the screen customization.

Overview

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

Screen Recognition Criteria

You set screen recognition criteria that HATS uses to match host screens. Host screens can be recognized by any combination of criteria including how many input fields or total 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. The Screen Recognition Criteria tab of the screen customization editor displays the screen recognition criteria that you set for the screen customization. You can add, edit, or remove criteria on this tab.

Note:

When using the Create a Screen Customization wizard, you should not select screen recognition criteria which contains half double-byte (DBCS) characters. Any DBCS character selected must be completely included in the selection region.

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. This will include input fields, protected text fields, and hidden fields. These are the first two criteria shown on the Screen Recognition Criteria 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 number of fields and input fields for the screen specified on the Overview tab. If you change the screen being used for this screen customization, click Refresh to update the values for the screen you choose.

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 customization 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 shows 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 customization, click Refresh to update the values for the initial cursor position row and column on the screen you choose.

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 choose 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, HATS 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, HATS checks the optional criteria. For a screen to match the criteria, HATS 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, HATS must find both text strings or the cursor position for the screen to match. Because HATS checks non-optional criteria first, HATS looks for the text strings first. If HATS 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 choose 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 at the bottom of the Screen Recognition Criteria tab. If you have set a string location as a screen recognition criterion, it is shown in the table. The table shows what part of the screen contained the string, shows 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 Recognition 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

If you click Add and select Global variable criterion, you need to either specify a global variable from the Global Variable drop-down list or type in the value. Specify the Verification logic by checking one of the five bullets:

This global variable exists
This global variable does not exist
Check the length of this global variable where you can specify how the length will be compared from the drop-down list, as well as the length to compare.
Check the integer value of this global variable where you can specify how the integer value will be compared from the drop-down list, as well as the integer value to compare.
Check the string value of this global variable where you can specify how the string value will be compared from the drop-down list, as well as the string value to compare.

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 information on advanced global variable programming, refer to the HATS 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).

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

Actions

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

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 HATS runtime in the order that they are listed. If you want to display the transformed host screen to the end 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 choose to use a Play macro action or a Send key action in a customization, that action must be the last action in the list.

When all the actions in the customization have been performed, HATS 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 customization's actions. Checking 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 HATS runtime will send an [enter] to the transformation host at the end of the action list. An aid key is sent if:

No command parameter is received by the servlet from an Apply transformation action and
No macro has been run against the transformation host via a Play macro action and
No Send key action has sent the transformation host a screen-changing aid key.

So, if the action list contains an Apply transformation action, and the end user sends the F2 command in response to the transformation, the [pf2] command will be sent rather than any default command. Likewise, if the customization 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:

Apply transformation
Execute business logic
Extract global variable
Insert data
Set global variable
Show a URL
Forward to URL
Play macro
Perform macro transaction
Send key
Disconnect
Pause

All the action types you have defined for the screen customization 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 choose, 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 customization, you can select the transformation you want to apply from the drop-down list of transformations defined in the project.

The Template field has "(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 browser window 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 end 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 you did this, no other actions would occur. The immediate sending of these keys applies only to the current transformation, and not to all transformations in the project.

You can turn off global rules processing by unchecking the Apply global rules check box.

Execute business logic action

If you decide to execute some business logic as the action of this screen customization, 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 HATS Project View tab of the HATS Studio. If you have not created the Java code for this business logic, right click in the HATS Project View tab of the HATS Studio, and click New HATS > Business Logic to invoke the Create Business Logic wizard.

For more information on business logic, see the HATS Programmer's Guide.

Extract global variable action

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. You can extract information from the screen and define it as a global variable. When you extract a global variable, you can specify a name 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). If you selected an existing global variable in the Name field before you clicked Advanced, click one of the following radio buttons specifying how HATS should handle the extracted data:

Overwrite the existing value with this new value
Overwrite the existing value with this new value, starting at the specified index
Append this new value to the end of the existing value
Insert this new value into the existing value, at the specified index

For the two options that use a specified index, 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 choose. 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, so the value of "sample[0]" is "a", and the "b" in the value has an index of 1, so the value of "sample[1]" is "b", and so on. Assume that you extract a new set of values "e f g".

If you click the Overwrite the existing value with this new value radio button, the value "a b c d" of "sample" is changed to "e f g".
If you click the Overwrite the existing value with this new value, starting at the specified index radio button, and assume an index of 2, the value "a b c d" of "sample" becomes "a b e f g" .
If you click the Append this new value to the end of the existing value radio button, the value "a b c d" of "sample" becomes "a b c d e f g".
If you click the Insert this new value into the existing value, at the specified index radio button, and assume an index of 2, the value "a b c d" of "sample" becomes "a b e f g c d".

Selecting the Shared check box will allow the global variable to be shared between all applications in the same .ear file.

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

Insert data action

You can highlight certain fields on your host screen by selecting the different options beside Highlight fields. If you want to see where the input fields are defined on the screen, select the Input check box. If you want to see what fields are protected, select the Protected check box. If you want to highlight any hidden fields, select the Hidden check box. To modify the colors of the input, protected or hidden fields highlighting, see Using HATS preferences.

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 between all applications in the same .ear file.

Note:

Inserting information onto a host screen must occur before any transformation occurs for the global variable to appear in the Web page. See Actions for information on modifying the order of the actions.

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

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:

Overwrite the existing value with this new value
Overwrite the existing value with this new value, starting at the specified index
Append this new value to the end of the existing value
Insert this new value into the existing value, at the specified index.

For the two options that use a specified index, 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 choose, 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 between all applications in the same .ear file.

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

Show URL action

If you want to show a Web page as the action of this screen customization, specify the URL (uniform resource locator) address of the Web page in the URL field. With Internet Explorer Version 6.0 or later and Netscape^(TM) Version 6.2 or later, the Web page is shown surrounded by the default template, similar to the way a transformation is shown. Once the Web page loads, you can go back to your HATS application by pressing the Continue Application button at the bottom of the Web page. For a list of supported Web browsers and limitations, refer to HATS Getting Started.

When you specify the target of the Show URL action, it means that your browser 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 your browser has direct access to the target page. Be sure to give the complete URL for the target, since you 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 HATS application (a "cross-domain" access), your browser settings may need to be adjusted to allow the off-server target page to be loaded.

In Internet Explorer Version 6.0, 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 choose the desired setting for Access data sources across domains. Choose Enable to allow the target page to load. Choose 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

The forward to URL action enables you to pass control from a transformation-oriented HATS project 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. To add a forward action to an event, specify the following parameters:

The JSP to which control is passed. In addition to invoking the Integration Objects, this JSP can interact with the user if information is needed.
The startStateLabel of the first Integration Object to be executed. This value is used by the HATS entry servlet to store the HTTP session object so that it will be available to the Integration Objects.
Note:
This parameter is only required if the transformation connection needs to be passed to the JSP/Integration Object logic.

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 Administration 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:

The HATS project has already established a default connection and you want the JSP/Integration Object logic to use this connection. In this case, the JSP that gains control should drive an Integration Object that is not first-in-chain. The Integration Object that is driven will locate the connection to use by looking up the connection in the HTTP session object using the start state label that was associated with the Integration Object when it was created. This label should match the label that was specified as part of the forward to URL definition. In this case, note that when control is returned to the transformation-oriented project, a check will be made to see if the host screen has been updated. If it has, all remaining actions in the action list associated with the current event will be ignored. If the host screen has not been modified, the remaining actions will be honored.
The HATS project has already established a default connection, but you want the JSP/Integration Object logic to use a new background connection. In this case, the JSP that gains control should drive an Integration Object that is either first-in-chain or not chained at all. The Integration Object will cause a new background connection to be established and perform its designated task against that connection. Note that the startStateLabel does not need to be specified in the forward to URL definition in this situation.
A default connection has not been started. This will be the case if you add the forward to URL action to the Start event or to the Connect event (before the obtain action is executed). In this scenario, many possibilities exist. For example, the JSP that gains control can drive an Integration Object that gets its own background connection, performs a designated task, and is programmed to return control to the HATS entry servlet. At that point, the HATS entry servlet can continue with the event processing and establish a default connection. Another possibility would be that the JSP drives an Integration Object that is first-in-chain. The Integration Object establishes a connection, performs a task, and then passes the connection to the HATS entry servlet to be used as the default connection.

When you use the forward action, control does not return automatically to the HATS entry servlet after the Integration Objects have been run. The JSP must explicitly pass control back to the HATS entry servlet. If the default connection was not made before the forward action, and the Integration Objects used the default connection, pass the connection to the HATS entry servlet to be used as the default connection. In this case set a request parameter on the HttpServletRequest before forwarding the request to the HATS entry servlet. The parameter is CommonConstants.HATS_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:

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

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

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

If you wish to pass the connection to the HATS entry servlet, 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 HATS application. In that case, you can use the code that is identified to drive your HATS entry servlet and pass the connection established by the JSP/Integration Object logic to the HATS entry servlet 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 customization, it is the last action applied. Be sure to use very specific criteria for recognizing that screen, so 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 customization. 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 execute 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 executed 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 customization for that screen, you should clear the Apply a transformation check box on the Actions page of the wizard. You can create another screen customization 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 end user to run a macro from the transformed screen. In this case, the end 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 HATS Studio using the host terminal. For more information on 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 legacy 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, choose 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.

Portlet Prepresentation

When using Portlet Prepresentation , you can add Prepresentation Begin and End delimiters using the Add Block Delimiter button.

The Prepresentation Begin and End allow you to enclose actions that must be performed in the prepresentation phase of portlet processing. Use the Add Block Delimiter button when implementing portlet messaging or cooperative portlets. Click the Add Block Delimiter button once to insert the prepresentation begin delimiter and click Add Block Delimiter again to insert the prepresentation end delimiter. Use the Up and Down buttons to move the action needing execution in the block delimiter higher or lower in the list. When the action needs to be invoked will determine the location of the prepresentation block. When executing a screen customization, you can trigger the prepresentation action first or at the top of the Actions list. If you want to execute the prepresentation action after user interaction on the screen, you would trigger the event at the bottom of the Actions list. For more information on how to use the block delimiter with portlets, see the HATS Programmer's Guide.

Text Replacement

The Text Replacement tab displays a table in which you can specify protected host screen text you want to replace, the text, HTML or image with which you want to replace the original protected text, and whether the texts are case sensitive. 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 used, it will only search for exact text that you entered in the Replace text box. Checking 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.

To replace with text or HTML, simply type in the text you want replaced in the window below. If you enter HTML code, HATS will highlight it in red so that the you will know whether or not 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: The cascading style sheet (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.

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 re-ordering your text replacement items or by making them more specific, so they do not accidentally replace previous strings.

Note:

Care should be taken when using text replacement. Text replacement with a disparate number of characters in the strings can cause changes in the HTML representation of the screen. Depending on the widget used for presenting a region of a screen, text on a line of the screen could 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.

Text replacement truncates strings that are longer then the text being replaced. Sometimes the text it truncated to maintain the layout of the original host screen on the Web page. Truncation only occurs on text rendered using the field widget (or in some cases of the table widget).

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

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 screen customizations 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 Searches application event priority list 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:

Unmatched screen
Error
Disconnect
Stop

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 sc-name.evnt file for all the information supplied for the screen customization, where sc-name is the name you gave to the screen customization when you created it. As you make changes on other tabs in the screen customization 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 customization editor.

Screen customization priority

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

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

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

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

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

Inhibited Screens

If you want your HATS application to recognize inhibited screens, modify each HATS screen customization that could be used to recognize inhibited screens.

An inhibited screen, also called an input-inhibited or keyboard-locked screen, is a screen containing a message notification or partial output, on which the keyboard is not enabled. Usually the user must press a certain key, such as the Escape key, to move to the next screen. By default HATS applications do not recognize inhibited screens. If you want your HATS application to recognize inhibited screens, modify each HATS screen customization that could be used to recognize them.

Follow these steps to modify the screen customization:

In the HATS Project View, expand your project and the list of screen customizations.
Click on a screen customization to start the screen customization editor.
At the bottom of the editor, click the Source tab.
Find the line that contains the string status="NOTINHIBITED". Change "NOTINHIBITED" to "DONTCARE".
Save the change by clicking File > Save or pressing Ctrl-S.

Repeat this process for each screen customization that you want to recognize inhibited screens.

Application Events

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

To access the application events, go to the HATS Project View and double click the Project Settings of your HATS project and select the Events tab.

Each application event has various actions associated with them.

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

Start

A start event occurs when starting your HATS application on a Web browser. There is no default action for the start event.

You can specify the following actions for the start event:

Execute business logic
Set global variable
Show a URL
Forward to URL
Perform macro transaction
Pause

Connect

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

You can specify the following actions for the connect event:

Obtain transformation connection
Execute business logic
Set global variable
Show a URL
Forward to URL
Play macro
Perform macro transaction
Disconnect
Pause

Blank screen

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

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

Execute business logic
Set global variable
Show a URL
Forward to URL
Play macro
Perform macro transaction
Disconnect
Pause

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

Unmatched screen

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

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

Apply transformation
Execute business logic
Extract global variable
Inset data
Set global variable
Show a URL
Forward to URL
Play macro
Perform macro transaction
Send key
Disconnect
Pause

Error

An error event occurs when HATS encounters an application or host error. You might want to add an action that displays an error JSP when an error event occurs. The default action for the error event is to show a URL. The URL which is displayed is error.jsp.

You can specify the following actions for the error event:

Execute business logic
Set global variable
Show a URL
Forward to URL
Play macro
Perform macro transaction
Pause

Disconnect

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

You can specify the following actions for the disconnect event:

Release default transformation connection
Execute business logic
Set global variable
Show a URL
Forward to URL
Play macro
Perform macro transaction
Pause

Stop: A stop event occurs after stopping your HATS application on a Web browser. The default action for the stop event is to show a URL. The URL which is displayed is stop.jsp
You can specify the following actions for the stop event:

Importing BMS map sets

HATS now 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 HATS 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 HATS.

You must first copy the BMS map sets from the host to your local file system. This is a manual step outside of HATS 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.

Click File > Import > BMS map sets into HATS to open the Import wizard.
Select the BMS map set files you want to import from the list and the destination of the imported files.
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.
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.
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.
You can also choose Overwrite existing screen captures without warning.
Click Finish.

BMS capture files are stored in a separate Maps folder within the HATS project. By default, the Maps folder is not visible in the HATS Project 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 HATS Project View.

Hovering your mouse cursor over the map name displays a small image of the map.
When you click on a map in the project view, the Properties view is updated to show details about the selected map. If there are named fields in the map, you can use the Properties view to modify the contents of those fields. By making copies of maps to alter the contents of named fields within the copies, you can create different customized versions of maps that accurately reflect the way the screen will be shown by the application.
Double clicking on a map brings up an editor page that shows how the map would display on a 3270 screen. Double clicking on the map set folder name will show the map source in an editor.
Right clicking on a map name in the Project view adds a Generate Screen Captures selection to the popup context menu. Selecting this launches the Generate screen captures wizard that can be used to select one or more BMS capture files to be used to create a screen capture. You can elect to create separate screen captures for each BMS map selected or merge selected BMS maps into a single screen capture. Maps cannot be merged if fields overlap. The Overwrite existing resources without warning check box can also be selected if needed.
Note:
If separate screen captures are generated and more than one file is selected, the names of the screen capture files are generated automatically.

Once the your screen captures have been created, you can begin to create HATS screen customizations.