Incorporate macros

 

+
Search Tips   |   Advanced Search

 

Overview

HATS supports macros that perform actions on the host application. For example...

Macro Description
Skip-screen Move the user from one screen to another screen without displaying intervening screens.
Prompt Request input from users during the host session. Commonly used to prompt for user ID and password. User list and WEL prompts can only be used in connect macros.
Extract Extract host screen information as a string, data as a table or even a global variable. 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 Studio are saved in a HATS macro (.hma) file. 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.

 

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.

 

Open Host Terminal

Click Open Host Terminal to create or work with your macro.

Edit previously recorded macros 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. 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 and list of available screens to select for your next screen.

Here are the macro icons that appear on the host terminal screen.

Open a macro. Use the drop-down list to select a macro.
play macro Play a macro. Use the drop-down list to select a macro.
record macro Start recording a macro
stop macro Stop recording a macro
save macro Save the recorded macro
Define the screen recognition criteria for a macro
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)

Record a Macro

Record a macro, give it a name and description, and specify where the macro is saved. Click Finish when you have specified these items. Next the Define Screen Recognition Criteria window will appear because HATS forces the first screen to have defined screen recognition. You can then use the HATS host terminal screen to navigate through the host application to any screen.

Stop Macro

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

Save Macro

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

Define Screen Recognition Criteria

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.

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 end user provides, such as a password, should not be displayed on the host screen, click the Password protect input check box. 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 Web Content > 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. 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 indices or a single index.

Set prompt to property from User List

If you want to 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.

User list prompts and Web Express Logon 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 or enter the application ID in the Application ID field.

Click OK when you have made your selections.

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

  • Extract this region as a list of strings

  • Extract this region as a table

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 Web Content > 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. If you selected an existing global variable in the Name field, 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 specify whether or not this variable is shared by checking the Shared check box.

Extracting a global variable as a table will create multiple global variables. You will have one non-indexed global variable with the entire region as well an indexed global variable for each column in the table.

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.

Click OK when you have made your selections.

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 your macro screen recognition criteria and select a text area which will be present on each screen of the loop. Click Next to define additional criteria or Finish to return to the main terminal. At the main terminal, perform the actions which will be executed 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.

Significant emphasis should be placed on the screen recognition criteria for the starting and ending screens of the loop. In some cases a you may have a starting screen that is almost identical to their 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. Checking the Shared check box will take the global variable from the shared list.

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. Checking the Shared check box will take the global variable from the shared list.

Show Keypad

If you want to see and use the terminal keypad, click Show Keypad to display the various keys.

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.

 

Advanced Editor

You can 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:

 

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 tags of the source file change to match.

You can make changes to the tags and attributes in the source file, and they are reflected on the appropriate tabs of the macro editor.

 

Import a macro

You can 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 | 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 with fixed iteration loops continually recognize the same screen and perform different actions. In HATS, you cannot create a screen customization to recognize the same screen a second time and perform a different action than the first time it was recognized. If you attempt to use a Host Publisher macro with fixed iteration looping, your project might go into an infinite loop. Host Publisher macros with fixed iteration looping can be identified by looking at the source code for the macro. The macro contains customreco and custom tags with ID attributes of HPubFixedIterationLoop and HPubIncrementLoop, respectively.

 

Export a macro

You can export HATS macros as well as IBM WebSphere Host Publisher or IBM Host On-Demand macros. To export these macros, select...

File | Export | HATS Macro or File | Export | HOD/Host Publisher Macro | Next

Host Publisher macros are typically in a directory path...

\hostpub\Studio\IntegrationObjects

These macros are exported as .macro files. This files extension works for both Host Publisher and Host On-Demand but Host On-Demand will default and look for .mac files. You will need to change the Host On-Demand filter to look for either *.macro or *.*.

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.

 

Combine multiple host screens

It is a common task to present multiple host screens as a single Web page. HATS allows you to do this by using macros, transformation JSPs and global variables. Different steps must be taken depending on whether or not you wish to preserve the initial host field values when you display the combined screens on the web.

Scenario 1: Using a macro to combine multiple host screens where the screen data which is displayed is static

This scenario creates a JSP to display data from the combined screens. The data that will be displayed is static; that is, it will be written directly into the JSP during the development of your application. The text from the host screens will be written into the JSP, and the JSP will contain input fields for each of the unprotected host fields. Implement this scenario if your screens do not have text that changes day to day, or between sessions.

  1. Create a macro which navigates to all the screens which will be combined, and add macro prompts for all of the host fields on these screens.

    1. Open the terminal by selecting your HATS project in the HATS Project View and clicking the Open HATS Host Terminal toolbar icon

    2. Navigate the terminal to the first screen to be combined

    3. Click the Record Macro button on the terminal and enter a name for the macro and define the screen

    4. Click the new Add Prompt Actions for All Fields button

    5. On the dialog, enter a stored screen name, such as "screen1", and select the Create a Screen Capture check box. Click OK then Finish. This stored screen name is used as a name prefix for global variables which HATS creates for every field on the host screen. The prompts are expected to be handled by global variables with the following name structure: StoredScreenName_r_c_l, where 'StoredScreenName' is the name provided by the user, 'r' is the starting row position of the field, 'c' is the starting column position of the field, and 'l' is the length of the field. These global variables will get their values from the transformation JSP that will be created in step 2. If these global variables will be accessed from other applications within the same EAR, select the Shared check box in the dialog mentioned above.

    6. Navigate to the next screen on the terminal to be combined

    7. Press the new Add Prompt Actions for All Fields button

    8. On the dialog, enter a stored screen name, such as "screen2", and select the Create a Screen Capture check box. Click OK then Finish.

    9. Repeat steps f,g, and h for any additional screens to combine.

    10. Press any additional keys needed for input (such as Enter) and press the Stop Macro button and then the Save Macro button.

  2. Create a Screen Customization for the first of these combined screens, which will apply the transformation JSP that displays all of the combined screens' fields.

    1. On the open terminal, navigate to the first of the combined screens

    2. Press the Create HATS Screen Customization button. In the New Screen Custom wizard which appears, provide a name and screen recognition criteria for the Screen Customization. Then specify as the only action to apply a new, blank transformation, and press Finish. This will generate a new transformation JSP, and automatically launch the Insert Host Component wizard.

    3. On the Insert Host Component wizard, press Cancel to not insert any host component

    4. On the transformation JSP page, select the source tab

  3. To combine the screen, add all of the stored screens from the macro to this transformation

    1. Place the cursor and click after the <HATS:Form> tag

    2. Right click or select the HATS Tools menu, and select the Insert Stored Screen option

    3. Select the stored screen name entered in 1e (screen1). Select the Shared checkbox if the Shared checkbox was selected in step 1e. At runtime, the transformation JSP will gather values for the global variables that are used to handle the macro prompts for the macro created in step 1

    4. Repeat step 3c for other screens that are to be combined (ie screen2)

    5. Edit the combined screen to arranged the combined fields and delete any you don't want to show

    6. Press the HATS Tools > Insert Macro Key button, and select the macro created in step 1 to insert a button that will execute the macro.

Scenario 2: Using macros to combine multiple host screens where the screen data which is displayed is dynamic (realtime), and which preserve the initial host field values

This scenario creates a JSP to display data from the combined screens. The data that will be displayed is dynamic; that is, it will be grabbed from the host in realtime, during the execution of your application. All text from the host screens will be stored in global variables by a macro. A JSP will then display these global variables for all of the host fields. Implement this scenario if your screens contain any data which may change day to day, or between sessions.

  1. Create a macro which navigates to all the screens which will be combined, and add macro extracts for all of the host fields on these screens to retrieve the initial host field values.

    1. Open the terminal by selecting your HATS project in the HATS Project View and clicking the Open HATS Host Terminal toolbar icon

    2. Navigate the terminal to the first screen to be combined

    3. Click the Record Macro button on the terminal and enter a name for the macro. Note this screen is the extract macro starting screen.

    4. Click the new Add Extract Actions for All Fields button

    5. On the dialog, enter a stored screen name, such as "screen1"

    6. The transformation JSP which will be created in Step 4 will show the initial values of the host screen. Navigate to the next screen on the terminal to be combined.

      This stored screen name is used as a name prefix for global variables which HATS creates for every field on the host screen. The prompts are expected to be handled by global variables with the following name structure: StoredScreenName_r_c_l, where 'StoredScreenName' is the name provided by the user, 'r' is the starting row position of the field, 'c' is the starting column position of the field, and 'l' is the length of the field. These global variables will get their values from the transformation JSP that will be created in step 2.

    7. Click the new Add Extract Actions for All Fields button

    8. On the dialog, enter a stored screen name, such as "screen2", and select either Input fields, All fields, or Shared. Click OK then Finish.

    9. Repeat steps f,g, and h for any additional screens to combine.

    10. Press any additional keys needed to navigate to the ending screen for this macro. Note this ending screen needs to be any unique screen, but not the exact same screen as used at the start of this macro (or an infinite loop will result). This is the extract macro ending screen.

  2. Create a macro which picks up where the other macro left off, and navigates back through all the screens which will be combined, and add macro prompts for all of the host fields on these screens.

    1. Open the terminal by selecting your HATS project and clicking the Open HATS Host Terminal toolbar icon

    2. Navigate the terminal to the ending screen of the macro which was created in step 1.

    3. Click the Record Macro button on the terminal and enter a name for the macro

    4. Record the keystrokes needed to navigate from this screen to the first screen of the macro which was created in step 1.

    5. Click the Add Prompt Actions for All Fields button

    6. On the dialog, select the stored screen name from the drop-down used in step 1e, such as "screen1". Click OK then Finish.

    7. Navigate to the next screen on the terminal to be combined

    8. Click the Add Prompt Actions for All Fields button

    9. On the dialog, select the stored screen name from the drop-down used in step 1h, such as "screen2". Click OK then Finish.

    10. Repeat steps f,g, and h for any additional screens to combine.

    11. Press any additional keys needed for input (such as Enter). Click the Stop Macro button, then the Save Macro button.

  3. Create a Screen Customization for the first of these combined screens, which will automatically play the extract macro created in Step 1.

    1. On the open terminal, navigate to the extract macro starting screen from step 1c

    2. Click the Create HATS Screen Customization button. Click Next

    3. Select one or more screen recognition criteria that identify this screen (or accept the default criteria). Click Next

    4. Clear the Apply a Transformation check box and check Play a Macro

    5. Enter the name of the extract macro used in step 1c

  4. Create a Screen Customization for the ending screen of the macro created in step 1, which will apply the transformation JSP that displays all of the combined screens' fields.

    1. On the open terminal, navigate to the extract macro ending screen from step 1j

    2. Press the Create HATS Screen Customization button. In the New Screen Customization wizard which appears, provide a name and screen recognition criteria for the screen customization. Then specify as the only action to apply a new, blank transformation, and press Finish. This will generate a new transformation JSP, and automatically launch the Insert Host Component wizard.

    3. On the Insert Host Component wizard page, press Cancel to not insert any host component at this time

    4. On the transformation JSP page, select the source tab

  5. To combine the screens, add all of the stored screens from the macros to this transformation

    1. Place the cursor and click after the <HATS:Form> tag

    2. Right click or select the HATS Tools menu, and select the Insert Stored Screen option

    3. Select the stored screen name entered in 1e (screen1). Check the Insert global variables for host text (protected fields) check box.

    4. Repeat step 5c for other screens that are to be combined (ie screen2)

    5. Edit the combined screen to arranged the combined fields and delete any you don't want to show

    6. Click the Insert Macro button to insert a button to execute the insert macro created in step 2 onto the combined page. Note instead of inserting a macro button onto this page, you can instead have it automatically execute as the last step of the Screen Customization created in step 4.

 

Macro hints and tips

 

Preventing an infinite loop

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 that has the macro defined as the action. If the recognized screen is the final screen of the macro, a loop will be created.

 

Home