Introducing advanced macros

As a developer using Z and I Emulator for Transformation (ZIETrans) Toolkit, you can incorporate macros into your ZIETrans application. The ZIETrans User's and Administrator's Guide introduces the use of macros in ZIETrans 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 ZIETrans macros:

Adapting Host On-Demand macros for use in ZIETrans

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

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

Working with macros in HCL ZIETrans

You can work with macros in several different ways within HCL ZIETrans 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.
Note:
An action within a macro is not the same thing as an action triggered by an HCL ZIETrans 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 ZIETrans 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:

  1. In HCL ZIETrans Toolkit, select your HCL ZIETrans 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 ZIETrans 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 ZIETrans 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.