Macros and host terminal

A macro is an XML script that defines a set of screens. Each screen includes a description of the screen, the actions to perform for that screen, and the screen or screens that can be presented after the actions are performed.

HATS supports macro-based customization to speed up and customize the host application process. Macros can be used for the following functions:

• As an action such as the play macro action or the perform macro transaction action. Playing a macro must be the last action performed for a screen event. For more information see Actions.
• To connect or disconnect a particular host connection. For more information see Macros.
• To generate an Integration Object. For more information, see Creating an Integration Object.
• In a transformation. See Insert Macro Key for more information.

You can use macros to do any or all of the following functions:

Skip-screen

Skip-screen macros are navigational macros that move the user from one screen to another screen without displaying intervening screens.

Prompt

Prompt macros contain steps to request input from users during the host session. They can also set prompts from a user list. For example, you can use a prompt macro to ask a user for a user ID and password before logging into a host application.

Note:

User list prompts can only be used in connect macros.

Prompt macros can also be used by developers to provide constant values or values obtained from global variables.

Extract

Extract macros contain events to extract host screen information as a string, as a list of strings, or as a table. For example, 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.

Macros recorded or imported in HATS Toolkit are saved in a HATS macro (.hma) file. You can see the macros defined in your project by expanding the Macros node in the HATS Projects view of the HATS Toolkit.

HATS provides three different editors you can use to view and modify HATS macros, the Macro Editor, the Advanced Macro Editor, and the Visual Macro Editor. The Visual Macro Editor is the default editor for HATS macros. When you double-click on the name of a macro, the Visual Macro Editor is opened. For more information about the Visual Macro Editor, see the chapter, Visual Macro Editor, in the HATS Advanced Macro Guide.

To open the Macro Editor, right-click on the name of the macro and select Open With > Macro Editor.

The Advanced Macro Editor is opened from the Macro Editor Overview page. For more information about the Advanced Macro Editor, see the chapter, Advanced Macro Editor, in the HATS Advanced Macro Guide.

Macro Editor

The following sections describe each tab of the macro editor.

Overview

The Overview tab of the macro editor summarizes general information about the macro, such as the name, description and last modified date and time. The items you can modify on this tab are the description of the macro, the pausetime, timeout and connection.

Pausetime is the number of milliseconds of delay after each action is performed. Timeout is the number of milliseconds to wait before terminating the macro and Connection lets you select which connection to use from the drop-down menu.

The Open Host Terminal and Advanced Editor buttons are described in detail below.

Figure 75. HATS macro recording

Open Host Terminal

You can click Open Host Terminal to create or work with your macro using the host terminal. Once the terminal opens, you can use any of the icons on the toolbar to record and create your macro.

Host Terminal

You can also use the Host Terminal to edit a previously recorded macro by right-clicking on the nodes in the macro tree and selecting Edit. If you select a screen to edit, this will launch the screen recognition criteria editor which will allow you to modify your screen. If you edit any input that you entered in your screen, a window will open up and allow you to change or modify the input. If you edit the Next Screens node, you will be given a list of available screens to select for your next screen. Select from the list in the order you want your screens to appear.

To debug macro play errors, four icons exist on the Host Terminal toolbar. The icons are designed to help you step through a macro, where a step is defined as playing one action or recognizing one screen. The icons are Step Into, Step Over, Step Return and Resume.

Each of the icons have function keys associated with them. Depending on which view is active (either the Macro Navigator or the Host Terminal) , the F5, F6, F7, and F8 keys will function differently. For instance, if the Macro Navigator is active, pressing F5 will do Step Into, and pressing F6 will do Step Over. If the Host Terminal is active, pressing F5 or F6 will send the AID key to the host. For more information about these and other macro related icons, see Macro related icons.

Table 4 shows the macro icons that appear on the host terminal screen toolbar.

Table 4. Macro icons

Icon	Description
	Open a macro. Use the drop-down list to select a macro.
	Play a macro. Use the drop-down list to select a macro.
	Start recording a macro
	Stop recording a macro
	Save the recorded macro
	Step Into (F5) the macro for debugging purposes
	Step Over (F6) the macro for debugging purposes
	Step Return (F7) in the macro for debugging purposes
	Resume (F8) playback of the macro
	Define the screen recognition criteria for a macro screen
	Add a prompt action into the current macro (enabled only when recording a macro)
	Add an extract action into the current macro (enabled only when recording a macro)
	Record a loop into the current macro (enabled only when recording a macro)
	Add prompt actions into the current macro for all fields on the screen (enabled only when recording a macro)
	Add extract actions into the current macro for all fields on the screen (enabled only when recording a macro)
	Show or hide the keypad in the host terminal window
	Show or hide the textual Operator Information Area (OIA)

Macro related icons

Below is a list of macro related icons on the Host Terminal toolbar:

Record macro

You can record macros in HATS Toolkit using the HATS host terminal. On the HATS host terminal screen, click the Record macro icon. The Record Macro wizard appears and enables you to select the target project, name the macro, give it a description, and see where the macro is saved. The option, Create screen captures automatically while recording, lets you specify that a screen capture automatically be created for every screen navigated while recording the macro. These screen captures can then be used within the Visual Macro Editor if you must later make changes to the macro. This option is selected by default. Click Finish when you have specified these items.

Next the Define Screen Recognition Criteria window appears because HATS forces the first screen to have explicitly defined screen recognition. You can then use the HATS host terminal screen to navigate through the host application to any screen.

If you have a macro already open within the HATS host terminal, the Record macro icon will ask if you want to record a new macro or append to the open macro. If you append to the open macro, then macro recording will begin, and your actions will be appended to the current macro. The location within the macro where recording begins depends on what is selected in the Macro Navigator tree on the left, and whether the current terminal screen matches the screen recognition criteria of the selected node. Specifically:

• If a screen node or an action node is selected in the Macro Navigator, and the current host terminal screen matches the recognition criteria of the selected screen, the new actions will be added at the beginning of the selected node. If an action was selected within the matching screen node, then recording will begin immediately following the selected action within the matching screen.
• If a screen node or an action node is selected in the Macro Navigator window, and the host terminal screen does not match the recognition criteria of the selected screen, then a new screen node will be added to the Next Screens of the selected node, and recording will begin at the new screen node.
• If the high level node is selected in the Macro Navigator window which corresponds to the macro name, then HATS will search through all of the screen nodes and try to find a match for the current terminal screens. If a match is found, recording will begin at the beginning of the matching screen. If a match is not found, then a new screen node will be added to the Next Screens of the last screen and recording will begin at the new screen node.

Do not create a macro whose only step is to insert an extract or add a prompt. 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. If a macro doesn't go back to the host, it will sit and time out.

Note:

If you intend to create an Integration Object from a macro, ensure that you follow these requirements when naming the macro:

• The name of the macro must consist of only letters, digits, or underscore characters.
• The first character of the name cannot be a numeral.
• Double byte (fullwidth) characters are not allowed.

Stop Macro

When you are finished recording your macro, click the Stop Macro icon.

Save Macro

Once you have stopped recording your macro, you will need to save it by clicking the Save Macro icon.

Step Into (F5)

Clicking the Step Into (F5) icon allows you to step from a screen to its first enclosed action, and from action to action. Using the F5 key on your keyboard will perform the same function. This is used for debugging purposes.

Step Over (F6)

Clicking the Step Over (F6) allows you to go from screen to screen (performing all intervening actions). Using the F6 key on your keyboard will perform the same function. This is used for debugging proposes.

Step Return (F7)

Clicking the Step Return (F7) allows you to finish playing the actions under a screen and go to the next screen. Using the F7 key on your keyboard will perform the same function. This is used for debugging proposes.

Resume (F8)

To resume the playback of your macro, you can either click the Resume (F8) icon or press the F8 key on your keyboard. This can be used to run the rest of your macro if you are currently stepping through it.

Define Screen Recognition Criteria

You can 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. For more information see Screen Recognition Criteria or Begin Screen.

Add Prompt Action

If you want the macro to prompt the user for information, click Add Prompt Action to display the Add Prompt Action wizard. You can give the prompt a name and a default value. If the information the user provides, such as a password, should not be displayed on the host screen, click the Password protect input check box.

Note:

Default values that you specify for prompts are stored in macro files unencrypted. The default values display in the clear when you edit prompts using the macro editors. Therefore, while using a prompt to specify a password is an appropriate thing to do, for security reasons you should not specify a default value for the password.

The Row and Column fields of the Position section of the wizard define where on the host screen the prompt information provided by the 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

For HATS Web projects, you can select a .jsp file to prompt the user for the necessary information, and include a button for the user to submit the information. A default macro handler, named default.jsp, is shipped with HATS. You can find this file by clicking the HATS Projects view of the HATS Toolkit, expanding the project name, and expanding Web Content > Macro Event Handlers. If you want to create your own handler, ensure that you return control to the HATS runtime.

Notes:

1. Integration Objects ignore the selected .jsp handler. Instead, an input page is created for the Integration Object, and a prompt for the value is placed in that input page. The generated output page copies the value supplied by the input page into the Integration Object before the Integration Object is run.
2. The Show handler option is disabled when the macro extracts from a plane other than the text plane.

Note:

For HATS rich client projects, you can specify a custom macro handler, or browse to select from the list of custom macro handlers defined in the rich client project, to prompt the user for the necessary information, and include a button for the user to submit the information. A default macro handler, named DefaultMacroHandler, is shipped with HATS. You can find this file in the HATS Projects view, expanding the project name, and expanding Rich Client Content > Macro Event Handlers. If you want to create your own handler, ensure that you return control to the HATS runtime by calling the createButtonArea() and createButtons() methods in the render() method of your custom macro handler. These methods are called in the default implementation of the RcpMacroHandler.render() method. For more information about RcpMacroHandler, see the HATS RCP API Reference section in the HATS Knowledge Center at http://www.ibm.com/support/knowledgecenter/SSXKAY_9.7.0?topic=/com.ibm.hats.doc/doc/rcpjavadoc/index.html.

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. If you click the Advanced button, you can specify whether your variable is shared or indexed. If it is an indexed variable, you also need to specify whether to show all indexes or a single index. For more information, see Interacting with global variables.

Note:

If a prompt value is based on a global variable set by an extract, and promptall is set to true, the extract action is not run before the prompts values are retrieved. Because of this, the global variable used by the prompt does not contain a value. If you use global variables with extracts and prompts, you should set promptall to false.

Integration Objects do not access global variables directly. Instead, the input and output pages for the Integration Object retrieve the global variable value, and set it into the Integration Object before it is run. Only shared global variables can be accessed by Integration Objects.

Set prompt to property from User List

If you want the prompt to access a user list, select the User Profile from the drop-down list. The user profile is the key as to determining whether to use the userid or password as the User List property. For more information, see User List.

Note:

User list prompts can only be used in connect macros.

Use Web Express Logon

If you have configured your HATS application to use web express logon, enter the prompt type as either the user ID or password in the Prompt type drop-down list and enter the application ID in the Application ID field.

Note:

The Prompt type should be prefilled with the correct value.

Click OK when you have made your selections.

Note:

For considerations when using bidirectional language support, see Macro prompt and extract bidirectional options.

Add Extract Action

If you want the macro to extract information from the host screen, select an area on the host screen then click Add Extract Action to display the Add Extract Action 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. When you mark a region of the host screen with a rectangle and then click Add Extract Action, the Position section fields are filled with the values when the Add Extract Action wizard is displayed.

You can specify the Extraction Format as either:

• Extract this region as one string

  Specifies that the extracted text should be saved as a single horizontal string of characters. This option is supported for Integration Objects, global variables and macro handlers.

• Extract this region as a list of strings

  Specifies that the extracted text should be saved as a vertical list of strings. This option is supported for global variables and macro handlers. For an Integration Object, a list of strings is treated as one continuous string.

• Extract this region as a table:

  Specifies that the extracted text should be saved as a table of horizontal and vertical strings, with rows and columns. This option is supported for Integration Objects and macro handlers. For a global variable, strings extracted as a table become one continuous string.

  Table Extract Configuration

  Use this page to format the columns of the table.

  • Column name

    Use this field to change the heading of the selected column.

  • Expand column

    Expanding a column moves characters between columns. When you highlight a column, the Left button moves the last character on each line of the column to the left of the highlighted column to become the first character on each line in the highlighted column. The Right button moves the first character from each line of the column to the right of the highlighted column to become the last character on each line in the highlighted column.

  • Reduce column

    Reducing a column moves characters between columns. When you highlight a column, the Left button moves the first character from each line of the highlighted column to become the last character on each line in the column to the left of the highlighted column. The Right button moves the last character from each line of the highlighted column to become the first character on each line in the column to the right of the highlighted column.

  • Merge

    Use this button to merge two highlighted columns into a single column. The characters in the highlighted columns are joined into one column.

  • Divide

    Use this button to divide a highlighted column into two separate columns. The characters in the highlighted column are divided equally between the two new columns. If there are an uneven number of characters, the left column will contain one more character than the right column.

    Note:

    For considerations when using this function with DBCS support see Recording a macro.

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

For HATS Web applications, you can select a .jsp file to display the extracted information to the user. A default macro handler is shipped with HATS, and it is named default.jsp. You can find this in the HATS Projects view, expanding the project name, and expanding Web Content > Macro Event Handlers. If you want to create your own handler, ensure that you return control to the HATS runtime.

Note:

Integration Objects do not use this option. Instead, the output page will retrieve the extracted data from the Integration Object and display them.

For HATS rich client projects, you can specify a custom macro handler, or browse to select from the list of custom macro handlers defined in the rich client project, to prompt the 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 DefaultMacroHandler. You can find this file in the HATS Projects view, expanding the project name, and expanding Rich Content > Macro Event Handlers. If you want to create your own handler, ensure that you return control to the HATS runtime by calling the createButtonArea() and createButtons() methods in the render() method of your custom macro handler. These methods are called in the default implementation of the RcpMacroHandler.render() method. For more information about RcpMacroHandler, see the HATS RCP API Reference section in the HATS Knowledge Center at http://www.ibm.com/support/knowledgecenter/SSXKAY_9.7.0?topic=/com.ibm.hats.doc/doc/rcpjavadoc/index.html.

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. If you select 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
• Overwrite the existing value with this new value, starting at the specific index.
• Append this new value to the end of the existing value.
• Insert this new value into the existing value, at the specific index.

You can also specify whether this variable is shared by selecting the Shared check box.

Note:

If you extract a value and assign it to a global variable set by an extract, and you plan to use the global variable value for a prompt, you should set promptall to false. When promptall is set to true, the extract action is not run before the prompt values are retrieved. Because of this, the global variable used by the prompt does not contain a value.

Integration Objects do not directly extract to global variables. Instead, the output page for the Integration Object retrieves the data from the Integration Object after it has run, and then sets the global variables. Remember only shared global variables can be accessed by Integration Objects.

Click OK when you have made your selections.

Note:

For considerations when using bidirectional language support, see Macro prompt and extract bidirectional options.

Advanced Options

• Trim

  Trim Removes leading and trailing spaces from the extracted text. Use Trim on a text that may have irregular spacing.

• Custom Macro

  The extract variable will be considered as a custom variable when the Custom Macro option is CHECKED. This will ignore the screen extract and take the value from the custom java class through Custom action.

  Usually, global variables allow users to set custom data during play macro. However, as HATS global variables are being session variables, accessible only from HATS web screen and not accessible through Integration Objects and its extensions like REST APIs, this custom variable option becomes helpful to set any custom values as output variables. Custom variables are applicable only for Integration Objects and its extensions.

  Note:

  User can assign data to custom variable using custom action of macro.

Example:

In following scenario, the custom variable 'var1' is assign to value 'custom value'.

            @Override
            public void execute(MacroCustomActionEvent e) {
                    Macro m=(Macro)arg0.getSource();
                    Vector l=  m.getRuntimeListeners();
                    MacroCustomVarEvent mac=new MacroCustomVarEvent();
            
                    mac.setCustumVarName("var1");
                    mac.setCustomVarValue("custom value");
            
                    for (int i = l.size()-1; i >= 0; i--) {
                        CustomMacroVarListener ml = CustomMacroVarListener)l.elementAt(i);
                        ml.macroCustomVarEvent(mac);
                    }
            }
            
          

Record a Loop

If you want to record a loop in your macro, click Record a Loop then navigate to the screen where the loop will begin. Click Next to define the screen recognition criteria for the first screen in the Click Next to define additional criteria or Finish to return to the main terminal. At the main terminal, perform the actions which will be run during each cycle of the loop then press Next. Determine how your loop will end by selecting either End when a unique screen is recognized or End after a fixed number or iterations and enter the number of loops below. Click Next then navigate to the final screen of the loop and press Finish to complete the loop.

Note:

Significant emphasis should be placed on the screen recognition criteria for the starting and ending screens of the loop. In some cases, you may have a starting screen that is almost identical to the ending screen. You must be careful in distinguishing these screens from one another.

Add Prompt Actions for All Fields

If you select this icon, the Insert All Fields from Global Variables window will open. There you can select a Stored Screen name from the drop-down list. You also have the option of creating a screen capture by selecting the Create a Screen Capture check box. Selecting the Shared check box will take the global variable from the shared list.

Notes:

1. Default values that you specify for prompts are stored in macro files unencrypted. The default values display in the clear when you edit prompts in the host terminal macro editor or the advanced macro editor. Therefore, while using a prompt to specify a password is an appropriate thing to do, for security reasons you should not specify a default value for the password.
2. If you use this option with Integration Objects, HATS will add fields to the Integration Object for each defined global variable. You must write code to set the global variable values and copy them into the Integration Object before it is run. This can be done in the .jsp page that runs the Integration Object. For more information, see Insert Integration Object Properties. Remember only shared global variables can be accessed by Integration Objects.

Add Extract Actions for All Fields

If you select this icon, the Extract All Fields from Global Variables window will open. There you can select a Stored Screen name from the drop-down list. which will be used as a prefix for the global variables created for all fields. If the text of the protected fields should be grabbed at runtime, select the All fields option. If the text for the protected fields will be static in the transformation JSP, select the Input fields option. Selecting the Shared check box will take the global variable from the shared list.

Note:

If you use this option with Integration Objects, HATS will add fields to the Integration Object for each defined global variable. You must write code to copy the data from the Integration Object into shared global variables after the Integration Object is run. This can be done in the .jsp page that runs the Integration Object. For more information, see Insert Integration Object Properties. Remember only shared global variables can be accessed by Integration Objects.

Show/Hide Keypad

This icon allows you to either show the terminal keypad or hide the terminal keypad.

Show Textual OIA

The Show Textual OIA (Operator Information Area) icon allows you to see the exact row and column position of the cursor on your terminal screen. It also tells you whether the input is inhibited or not inhibited.

Host Screen Preview

To see what the current host screen would look like if transformed by the server, click the Host Screen Preview tab at the top of the Host Terminal window. The preview screen will display the host screen you are on as a Web page.

The host screen preview first applies any screen customization defined for the present screen. If there are no screen customizations defined for the current screen, the project level template and default rendering rules are applied to the screen.

The host screen preview applies the order of screen customizations listed in the Events tab of your Project Settings. As soon as it finds a screen recognition match is shows you the screen transformed by the transformation defined in that screen customization (if any). If there is not match, then the default transformation is shown.

The host screen preview will not process any screen customizations defined in the next screen list. Next screens are not processed in the host screen preview. For more information, see Next Screen.

Advanced Editor

You can also click Advanced Editor on the Overview tab to launch the advanced features of the HATS macro editor, and modify settings for the macro. A separate window opens for the macro editor which has the following tabs:

• Macro
• Screens
• Links
• Variables

For more information about the advanced editor features of the macro editor, see HATS Advanced Macro Guide.

Prompts and Extracts

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

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

Prompts and extracts appear in the macro source file in the order that you recorded them. In addition, when you open the macro in the editor, the cursor appears on the same line it was on when you last saved the macro, instead of appearing at the top of the macro file.

By default, content assistance is enabled for all macros in the project. While editing a macro on the Source tab, press Crtl+Space to invoke content assistance. You can configure which macros in the product provide content assistance. For instructions, see Macro Content Assistance.

Working with macro errors

Errors in a macro are summarized in the Problems view, whether you are using the macro editor, text editor, or XML editor. The source code of the macro displays a marker, a red circle with a white X in it, which appears on any lines containing an error.

The macro can be saved even when it contains errors, enabling you to find and fix the errors at a later time, if necessary. However, macros containing errors cannot be played at runtime or in the host terminal.

Importing a macro

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 > HATS > Host Publisher/HOD Macro and click Next to display the Import a Host Publisher/HOD Macro dialog. Click Add and navigate to the location of the macro on the file system.

Exporting a macro

You can export HATS macros as well as IBM Host On-Demand macros. To export these macros, select File > Export > HATS > HATS Macro or File > Export > HATS > HOD Macro and click Next.

Select the Macro files to export along with the destination. You can elect to overwrite the existing resources by selecting the Overwrite existing resources with warning check box.

Click Finish when done.

Macro hints and tips

Preventing an infinite loop

Running a macro is one of the actions that you can specify to be performed 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 that has the macro defined as the action. If the recognized screen is the final screen of the macro, a loop will be created.

Handling transient screens

You can define transient screens along with non-transient screens for your macros. However at runtime, you may see one of your transient screens get recognized unexpectedly.

When comparing macro next screen descriptors, non-transient screen descriptors are compared first, then transient screen descriptors are compared. If the current screen information is updated after comparison of non-transient screen descriptors begins, the updated screen information is used for transient screen descriptor comparison. Therefore, it is possible that if a screen is locked (OIA is input-inhibited) when non-transient screen comparison begins, and then becomes unlocked, with no other changes, before transient screen comparison begins, this can cause non-transient screens to not be recognized, but then subsequently transient screens can be recognized, which is not the expected behavior.

To avoid this unexpected behavior, you can control whether the same screen information is used when comparing non-transient screen and transient screen descriptors. To do this, add the advanced connection setting, screenRecoUseOIASnapshot, and set its value to true. For how to set advanced connection settings, see Configure optional, advanced connection settings.