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 <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 HCL ZIETrans applications.
- This element is ignored by the HCL ZIETrans runtime macro engine.
The <extracts> tag defines to the HCL ZIETrans 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 HCL ZIETrans runtime's macro engine, this element is ignored. For example, if the macro is run through an HCL ZIETrans Integration Object as a Web Service 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 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 HCL ZIETrans 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 HCL ZIETrans 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 HCL ZIETrans 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 HCL ZIETrans runtime's macro engine, this element is ignored, and any required data is supplied by the environment running the macro (Web service 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 HCL ZIETrans 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 HCL ZIETrans global variable displayID. See Macros and host terminal, for more information on the Play macro action.
If instead the macro is run by an HCL ZIETrans Integration Object using a JSP page, a Web service 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 Macros and host terminal for more information on Integration Objects.
Also note that the above macro does not work as a connect macro associated with an HCL ZIETrans connection on the Connection Editor's Macros tab because connect and disconnect macros are special macros run automatically by the HCL ZIETrans connection management subsystem instead of the runtime macro engine. A connect macro can only use a user list for its prompts. See Macros and host terminal for more information on connect and disconnect macros.