Working With Macros In HATS

By -

As a developer using Host Access Transformation Services (HATS), you can add macros into your HATS application. It is good to use macros in application to boost them and make applications user friendly.


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. Or in general, Macros are tiny programs that you can record to do repetitive tasks faster and more efficiently.

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.
  • To connect or disconnect a particular host connection.
  • To generate an Integration Object.
  • In a transformation of host applications.


Types of Macros

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

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.

Naming Convention for Macros

One thing that often confuses users that are just starting to use macros is what to name the macro.  It’s a good idea to name the macro something descriptive, but you do have to follow few rules.

  • Macros must start with a letter
  • You can’t use a space, period (.), exclamation mark (!), or the characters @, &, $, # in the name. (To keep things simple, I usually recommend avoiding special characters and use only letters, numbers and the underscore)
  • Macro names cannot include spaces.  If you want the look of a space, use the underscore
  • They cannot be more than 255 characters in length
  • Names must be unique.
  • Macro Names should be named related to actions we are performing. e.g For Login Macro Name should be Login or Login_Macro

That’s it!  You can’t name a macro something like 654578@&, but you can name it Macro_Zone.

Macro Editors

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.

  • The Macro Editor

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

Using The Macro Editor you can 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.


  • Advanced Macro Editor

The Advanced Macro Editor (AME) gives you the ability to set macro and screen-level attributes, edit screen descriptions; and add actions, links (next screen connections), and variables.

The basic Macro Editor can be opened by right-clicking on the macro and selecting Open With -> Macro Editor. The Advanced Macro Editor can then be opened from the Macro Editor Overview page. Prompts and Extracts can also still be edited from the Macro Editor.

The Advanced Macro Editor is a graphical user interface (with buttons, input fields, list boxes, and so on) for editing the parts of a macro.


  • Visual Macro Editor

The Visual Macro Editor (VME) gives you the ability to visually develop HATS macros. The VME combines many of the features of the HATS host terminal, basic Macro Editor, and Advanced Macro Editor, and allows for offline development of macros. It also allows flows to be copied between macros and provides drag-and-drop support for adding new screens. The VME is the default editor for HATS macros. When you double-click on a macro object (.hma file), the VME opens.

The VME is composed of the four parts:

  1. Design tab
  2. Palette view
  3. Integrate terminal
  4. Source tab


Creating a Macro

  1. In HATS Toolkit, select your HATS project and open the host terminal.
  2. Record a simple macro to use as a holder for the script:
    1. Click the Record Macro icon. The Record Macro wizard opens.
    2. Click Finish to accept the default values. The Define Screen Recognition Criteria wizard opens.
    3. Click Finish to accept the default values. The title bar on the host terminal window should display recording….
    4. Click the Stop Macro icon. The Define Screen Recognition Criteria wizard opens.
    5. Click Finish to accept the default values.
    6. Click the Save Macro icon.

You can edit the macro further using any of the HATS macro editors.

Editing a Macro

  1. Edit the macro that you just recorded.
    1. Double-click the name of the macro that you just recorded in the Macros folder in the HATS Project View.
    2. Click the Source tab at the bottom of the editor to open the source view.
    3. Or View Macro in Visual editor to edit it using visual editor.

Click File > Save (or press Ctrl + S) to save the macro script.

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 > HATS Macro and click Next to display the Import a HATS 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 WebSphere Host Publisher or IBM Host On-Demand macros or HATS macro. To export these macros, select File > Export > HATS > HATS Macro or File > Export > HATS > Host Publisher/HOD Macro and click Next. Host Publisher macros are typically in a directory path \hostpub\Studio\IntegrationObjects. These macros are exported as .macro files. This file extension works for both Host Publisher and Host On-Demand, but Host On-Demand uses as a default looks for .mac files.

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

Click Finish when done.

Macro Preventions

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