Introducing advanced macros

As a developer using Terminal Enterprise Access (TEA) Toolkit, you can incorporate macros into your TEA application. The TEA User's and Administrator's Guide introduces the use of macros in TEA 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 TEA macros:

Adapting Host On-Demand macros for use in TEA

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 TEA . This section explains how Host On-Demand macros are adapted for use within TEA.

The macros in a Host On-Demand environment typically run on the user's workstation. In a TEA 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 TEA. This document describes opening a prompt panel on the user's workstation, but this is not done in TEA. Instead, HCL TEA retrieves the data for the macro prompt from an HCL TEA global variable, user list, HCL TEA 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 an HCL TEA user. Instead, the data is copied into an HCL TEA global variable, copied into an HCL TEA Integration Object output property, or sent to the user's workstation in an HTML page. To help the HCL TEA runtime's macro engine provide these additional macro interaction capabilities, the HCL TEA Toolkit encapsulates each Host On-Demand macro script with another layer of XML that provides the HCL TEA 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 HCL TEA, each Host On-Demand macro script is wrapped within the HCL TEA <macro> begin tag and the </macro> end tag. The <macro> tag contains 4 elements:

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"?>
    <associatedConnections default="main">
        <connection name="main"/>
        <extract handler="default.jsp" index="-1" indexed="false"
            name="displayID" overwrite="true" save="true" separator=""
            showHandler="false" variableName="displayID"/>
        <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"/>
    <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 "/>
                <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"/>
            <nextscreens timeout="0">
                <nextscreen name="Screen2"/>
        <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"/>
            <nextscreens timeout="0"/>

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

Working with macros in HCL TEA

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

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.
An action within a macro is not the same thing as an action triggered by an HCL TEA 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 HCL TEA 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.


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:

  1. In HCL TEA Toolkit, select your HCL TEA 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.
  3. 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 HCL TEA 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 HCL TEA macro editors.

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.