Introducing advanced macros

As a developer using Host Access Transformation Services (HATS) Toolkit, you can incorporate macros into your HATS application. The HATS User's and Administrator's Guide introduces the use of macros in HATS and describes how to create and modify basic macros. This document describes advanced macro functions that you can incorporate into your macro by using the Visual Macro Editor (VME) and the Advanced Macro Editor (AME). These tools provide graphical user interfaces that you can use to modify or add features to each screen interaction with the host application.

Use these editors to make any of these changes to your HATS macros:

Add actions, such as new prompts, mouse clicks, or conditional actions.
Edit and enhance the macro's screen recognition behavior and user input.
Add more intelligent behavior to the macro, such as choosing between alternate paths through an application.

Note:

Support for the Macro Editor and the Advanced Macro Editor is deprecated in HATS V9.5. While support continues for now, IBM reserves the right to remove these capabilities in a subsequent release of the product. This support is replaced by the Visual Macro Editor.

Adapting Host On-Demand macros for use in HATS

This document describes the Host On-Demand macro language and its use. It is extracted from the Host On-Demand Macro Programming Guide Version 10, with sections modified to match the implementation of macros and the use of the editors within HATS . This section explains how Host On-Demand macros are adapted for use within HATS.

The macros in a Host On-Demand environment typically run on the user's workstation. Although in a HATS rich client environment macros typically run on the user's workstation, in a HATS Web environment macros typically run on a centralized server. Because of this difference, prompting for data to use in a macro must be done differently in HATS. This document describes opening a prompt panel on the user's workstation, but this is not done in HATS. Instead, HATS retrieves the data for the macro prompt from a HATS global variable, user list, HATS Integration Object input property, or the user through an HTML entry form sent to the user's workstation. Similarly, data extracted from a host screen cannot be immediately displayed on the workstation of a HATS user. Instead, the data is copied into a HATS global variable, copied into a HATS Integration Object output property, or sent to the user's workstation in an HTML page. To help the HATS runtime's macro engine provide these additional macro interaction capabilities, the HATS Toolkit encapsulates each Host On-Demand macro script with another layer of XML that provides the HATS Toolkit and runtime with additional information about the macro script.

The Host On-Demand macro scripts described in this document begin with a <HAScript> tag and end with a </HAScript> tag. In HATS, each Host On-Demand macro script is wrapped within the HATS <macro> begin tag and the </macro> end tag. The <macro> tag contains 4 elements:

The <associatedConnections> tag defines connection definitions to associate with this macro.
- This helps the Toolkit when building drop-down lists of macro names as you build and configure HATS applications.
- This element is ignored by the HATS runtime macro engine.
The <extracts> tag defines to the HATS macro engine how to handle data extracted from a host screen while a macro is running. The information in this element is also used to indicate the size and type of Integration Object output properties to be created if the macro is used to create an Integration Object.
- If the macro is played through a play macro action or a perform macro transaction action, this element controls whether extracted data is stored into a global variable or sent to the user's workstation with an HTML page.
- If this macro is played outside the HATS runtime's macro engine, this element is ignored. For example, if the macro is run through a HATS Integration Object as a Web Service or as an EJB or a set of JSP pages, the extracted data is copied into output properties of the Integration Object and thus made available to the Web service, EJB Access Bean, or JSP pages, respectively.
- Although the <extracts> tag is not used by an Integration Object at run time, the <extracts> tag is used to create an Integration Object from the HATS macro, should you choose to do so. In particular, the structure of an Integration Object's output properties is determined by this element. The information in the <extracts> element must agree with the actual <extract> actions found inside the Host On-Demand macro script itself. Otherwise, the data being extracted at run time will not fit correctly into the Integration Object's output properties, which might cause a loss of data. This is especially important when extracting tables of data, because the <extracts> tag will record the name, width, and number of elements in each column of data. The Host On-Demand macro's <extract> tag must indicate the same area so that parsing the data into the column output properties works correctly.
The <prompts> tag describes for the HATS macro engine how to handle data required to complete running the macro. The information in this element also is used to indicate the size and type of Integration Object input properties to be created if the macro is used to create an Integration Object.
- If the HATS macro engine is running the macro (using a Play macro or Perform macro transaction action) during a screen customization, this element controls whether the required data is obtained from a global variable, from a specified string literal, or is requested from the end user with an HTML page.
- If this macro is played outside of the HATS runtime's macro engine, this element is ignored, and any required data is supplied by the environment running the macro (Web service, EJB, or Integration Object, for example).
- Although the <prompts> tag is not used by an Integration Object at run time, the <prompts> tag is used if you choose to create an Integration Object from the HATS macro. In particular, the structure of an Integration Object's input properties is determined by this element. The information in the <prompts> element must agree with the actual <prompt> actions found inside the Host On-Demand macro script itself. Otherwise, the data being supplied by the Integration Object at run time will not satisfy the data required for the Host On-Demand macro's <prompt> actions, which can cause the macro to play incorrectly.
The <HAScript> tag is the Host On-Demand macro script described in this document.

The following example shows the structure with a simple macro containing two prompts and a single extract:

Figure 1. Simple macro structure

<?xml version="1.0" encoding="UTF-8"?>
<macro>
    <associatedConnections default="main">
        <connection name="main"/>
    </associatedConnections>
    <extracts>
        <extract handler="default.jsp" index="-1" indexed="false"
            name="displayID" overwrite="true" save="true" separator=""
            showHandler="false" variableName="displayID"/>
    </extracts>
    <prompts>
        <prompt handler="default.jsp" name="password" separator=""
            source="handler" value="" variableIndex="0"
            variableIndexed="false" variableName="" welApplID="" welIsPassword="false"/>
        <prompt handler="default.jsp" name="userID" separator=""
            source="handler" value="" variableIndex="0"
            variableIndexed="false" variableName="" welApplID="" welIsPassword="false"/>
    </prompts>
    <HAScript author="" blockinput="false" creationdate=""
        delayifnotenhancedtn="0" description=""
        ignorepauseforenhancedtn="false" name="SignOn" pausetime="300"
        promptall="true" supressclearevents="false" timeout="60000" usevars="false">
        <screen entryscreen="true" exitscreen="false" name="Screen1" transient="false">
            <description uselogic="1 and 2">
                <oia invertmatch="false" optional="false" status="NOTINHIBITED"/>
                <string casesense="false" col="35" invertmatch="false"
                    optional="false" row="1" value=" Sign On "/>
            </description>
            <actions>
                <extract assigntovar="" continuous="false" ecol="79"
                    erow="4" name="displayID" planetype="TEXT_PLANE"
                    scol="70" srow="4" unwrap="false"/>
                <prompt assigntovar="" clearfield="false" col="53"
                    default="" description="" encrypted="false" len="10"
                    movecursor="true" name="userID" required="false"
                    row="6" title="" varupdateonly="false" xlatehostkeys="true"/>
                <mouseclick col="53" row="7"/>
                <prompt assigntovar="" clearfield="false" col="53"
                    default="" description="" encrypted="true" len="10"
                    movecursor="true" name="password" required="false"
                    row="7" title="" varupdateonly="false" xlatehostkeys="true"/>
                <input col="0" encrypted="false" movecursor="true"
                    row="0" value="[enter]" xlatehostkeys="true"/>
            </actions>
            <nextscreens timeout="0">
                <nextscreen name="Screen2"/>
            </nextscreens>
        </screen>
        <screen entryscreen="false" exitscreen="true" name="Screen2" transient="false">
            <description uselogic="1 and (2 and 3 and 4)">
                <oia invertmatch="false" optional="false" status="NOTINHIBITED"/>
                <cursor col="7" invertmatch="false" optional="false" row="20"/>
                <numinputfields invertmatch="false" number="1" optional="false"/>
                <string casesense="false" col="32" invertmatch="false"
                    optional="false" row="1" value=" i5/OS Main Menu " wrap="false"/>
            </description>
            <actions/>
            <nextscreens timeout="0"/>
        </screen>
    </HAScript>
</macro>

The example macro in Figure 1 interacts with its environment differently depending on the engine playing the macro:

If this macro is run by the runtime macro engine in the connect event as a play macro action, for example, the user is prompted by an HTML input form for user ID and password, and the 5250 workstation display ID is stored in the HATS global variable displayID. See HATS User's and Administrator's Guide, for more information on the Play macro action.
If instead the macro is run by a HATS Integration Object using a JSP page, a Web service, an EJB Access Bean, or developer-supplied business logic, the macro fails if the Integration Object does not have the required values available in its getUserID and getPassword methods when the macro is run. This is because an Integration Object supplies its own macro engine where all prompts get data from Integration Object getters, and all extracts place data into Integration Object setters. The names and types of the Integration Object's input properties and the output property are determined by the data in the <prompts> element and the <extracts> element, respectively. See HATS User's and Administrator's Guide, for more information on Integration Objects.
Also note that the above macro does not work as a connect macro associated with a HATS connection on the Connection Editor's Macros tab because connect and disconnect macros are special macros run automatically by the HATS connection management subsystem instead of the runtime macro engine. A connect macro can only use a user list for its prompts. See HATS User's and Administrator's Guide, for more information on connect and disconnect macros.

Working with macros in HATS

You can work with macros in several different ways within HATS Toolkit:

You can record macros in the HATS Toolkit using the host terminal. After you record a macro, it is listed in the HATS Projects view, in the Macros folder. For more information, see the chapter, Macros and host terminal, in the HATS User's and Administrator's Guide.
To edit a macro, double-click the macro name in the HATS Projects view to open the default editor for the macro. The default editor for HATS macros is the Visual Macro Editor. For more information, see Visual Macro Editor.
To use the basic HATS Macro Editor, right-click the macro name and select Open With > Macro Editor. If you open the basic Macro Editor for a macro in this way, then it becomes the default editor for that macro. The tabs on the bottom of this editor enable you to work with the macro in different ways, including editing the XML source of the macro in the source view. For more information, see the chapter, Macros and host terminal, in the HATS User's and Administrator's Guide.
On the Overview page of the basic HATS Macro Editor, click Advanced Editor to work with a macro using the Advanced Macro Editor.

Definitions of terms

provides the definitions of a few terms that you will encounter in this book.

Table 1. Definitions of terms
Term	Definition
action	An action is an instruction that specifies some activity that the macro runtime is to perform when it plays back the macro (such as sending a sequence of keys to the host, displaying a prompt in a popup window, capturing a block of text from the screen, and other actions). See Macro actions. Note: An action within a macro is not the same thing as an action triggered by a HATS event.
application screen	An application screen is a meaningful arrangement of characters displayed on the host terminal by a host application. See Application screen.
descriptor	A descriptor is an instruction that describes one characteristic of an application screen. Descriptors are also called screen recognition criteria. See Screen description.
host terminal	A connection in HATS Toolkit to the host application where you record and run macros.
macro runtime	The macro runtime is the program module that plays back a macro when the macro is started. Specifically, the macro runtime reads the contents of the current macro script and generates the macro playback.
macro screen	A macro screen is a set of instructions that tells the macro runtime how to manage a particular visit to a particular application screen. See Macro screen.
macro script	A macro script is an XML script in which a macro is stored. When you play a macro, the macro runtime executes the instructions in the script. See Macro script.
source view	The source view shows the XML source of a macro.
valid next screen	A valid next screen is a macro screen that, during macro playback, is a valid candidate to be the next macro screen to be processed. See Stages in processing a macro screen.

Samples

You can create a new macro by copying a macro script from this document. This section assumes that you are copying an entire macro script, starting from the beginning designator <HAScript> and ending with the </HAScript> ending designator. To create a new macro in this way, perform the following steps:

In HATS Toolkit, select your HATS project and open the host terminal.
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.
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. In the source view, delete the lines beginning with <HAScript> and ending with </HAScript>.
4. Copy the entire text of a macro script from this document to the system clipboard.
5. Paste the macro script into the source view.
6. Click File > Save (or press Ctrl+S) to save the macro script.

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

Note:

Not all samples in this book are complete macro scripts. A complete macro script starts and ends with the element <HAScript> and does not contain ellipses (ellipses indicate missing information in the samples). Other samples are macro code snippets and need to be pasted into the appropriate location inside an existing, complete macro.