Incorporating macros

HATS supports macro-based customization to speed up the host application process. HATS supports skip-screen macros, prompt macros, and string extract macros. Skip-screen macros are navigational macros that move the user from one screen to another screen without displaying intervening screens. When running a skip-screen macro, HATS does not display any of the bypassed screens of the macro to the user. After the skip-screen macro has finished, HATS processes the ending screen (comparing the screen to the defined screen recognition criteria).

Prompt macros contain events to request input from users during the host session. For example, you can use a prompt macro to ask a user for their user ID and password before logging them into a host application.

Extract macros contain events to extract host screen information as a string. You can use an extract macro to connect to a directory-type host application and extract the results of doing a search in the directory. For example, you can use an extract macro to extract the results of a search for "Smith" in a phone book application.

You can record macros in HATS Studio using the HATS host terminal. On the HATS host terminal screen, click Record Macro. The Record a Macro wizard appears and enables you to name the macro, give it a description, and specify where the macro is saved. Click Finish when you have specifed these items. You can then use the HATS host terminal screen to navigate through the host application to any screen.

If you want the macro to prompt the user for information, click Insert Prompt to display the Insert Prompt wizard. You can give the prompt a name and a default value. If the information the end user provides, such as a password, should not be displayed on the host screen, click the Password protect input checkbox. The Row and Column fields of the Position section of the wizard define where on the host screen the prompt information provided by the end user is placed. If you place your cursor at a location on the host screen, such as the field for a password, before you begin recording the macro, the Row and Column fields are filled with those values. The Handle Macro Prompt section of the wizard enables you to determine how the prompt is processed. You can select one of the following radio buttons:

Show handler

You can select a .jsp file to prompt the end user for the necessary information, and include a button for the user to submit the information. A default macro handler is shipped with HATS, and it is named default.jsp. You can find this file by clicking the HATS Project View tab of the HATS Studio and expanding the project name, and expanding Macros > Macro Event Handlers. If you want to create your own handler, ensure that you return control to the HATS runtime.

Set prompt to string

If you know what value should be returned from a prompt, you can enter that string in the String field.

Set prompt to global variable

If you want the value of the prompt to be provided by a global variable, enter a name for the global variable in the Name field or select an existing variable using the drop-down menu next to the Global variable field.

Click OK when you have made your selections.

If you want the macro to extract information from the host screen, click Insert Extract and select an area on the host screen to display the Insert Extract wizard. You can specify a name for the extract. The Start row, Start column, End row, and End column fields of the Position section of the wizard define from where on the host screen the information is extracted. If you mark a region of the host screen with a rectangle after you click Insert Extract, the Position section fields are filled with the values when the Insert Extract wizard is displayed. The Handle Macro Extract section of the wizard enables you to determine how the prompt is processed. You can select the following check boxes:

Show handler

You can select a .jsp file to display the extracted information to the end user. A default macro handler is shipped with HATS, and it is named default.jsp. You can find this file by clicking the HATS Project View tab of the HATS Studio and expanding the project name, and expanding Macros > Macro Event Handlers. If you want to create your own handler, ensure that you return control to the HATS runtime.

Save as global variable

You can enter a name for the global variable in the Name field or select an existing variable using the drop-down menu. You must specify the extraction format by selecting one of the following radio buttons:

• Extract this region as one string
• Extract this region as a list of strings.

If you selected an existing global variable in the Name field, you must specify how to handle the existing variable by selecting one of the following radio buttons:

• Overwrite the existing value with this new value
• Append this new value to the end of the existing value.

Click OK when you have made your selections.

Do not create a macro whose only step is to insert an extract. If you do this, when the user supplies a value, the page will not change, and there will be no way for the user to move to another page.

You can also import macros recorded with other programs, such as the IBM WebSphere Host Publisher or IBM Host On-Demand. To import these macros, select File > Import > HOD/Host Publisher Macro and click Next to display the Import a HOD/Host Publisher Macro dialog. Click Add and navigate to the location of the macro on the file system. Host Publisher macros are typically in a directory path \hostpub\Studio\IntegrationObjects.

When a macro is listed in a project, it can be defined to run as the action of a screen customization, when the screen recognition criteria match the host screen. Playing a macro must be the last action performed for a screen customization.

You can also create a button to play the macro using the transformation editor. See Insert Macro Key wizard for more information.

Macros recorded or imported in HATS Studio are saved in a HATS macro (.hma) file. You can use the macro editor to view and modify those macros.

You can see the macros defined in your project by expanding the Macros node of the HATS Project View tab of the HATS Studio. You can invoke the macro editor by double-clicking on the name of the macro.

The following sections describe each tab of the macro editor.

Overview tab

The Overview tab of the macro editor summarizes information about the macro, such as the name and description. The only item you can modify on this tab is the description of the macro.

You can click Editor to launch the Host On-Demand macro editor, and modify settings for the macro. A separate window opens for the macro editor. Refer to Host On-Demand help documentation for more information on the Host On-Demand macro editor.

Prompts and Extracts tab

The Prompts and Extracts tab of the macro editor lists the configured macro prompts and extracts, and how they are handled when the macro is played. You can edit the HATS-specific properties of a prompt or an extract by selecting it in the table and clicking Edit.

Source tab

The Source tab displays the tags in the macro-name.hma file for all the attributes and values for the macro, where macro-name is the name you gave to the macro when you created it or imported it. As you make changes on other tabs in the project editor, the tags and attributes displayed in the tags of the source file change to match.

You can also make changes to the tags and attributes in the source file, and they are reflected on the appropriate tabs of the macro editor. For more information about the tags in the macro-name.hma file, refer to Macro files (.hma) and Appendix C. Macro script syntax.

Macro hints and tips

Set display for macro execution on AIX

When deploying a HATS application to run on WebSphere Application Server on the AIX platform, if the HATS application executes any macros, you must set the DISPLAY value for the machine:

export DISPLAY=<hostname>:0

Do not end macro on customized screen

Running a macro is one of the actions that you can specify to be executed when a host screen matches a screen customization's recognition criteria. 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.