Macro language features

This chapter describes the syntax, editing, hierarchy, commenting and debugging features of the Host On-Demand macro language.

Syntax and editing

XML syntax in the Host On-Demand macro language

A Host On-Demand macro is stored in an XML script using Host On-Demand macro language XML elements. This section describes some of the conventions of XML and gives examples from the Host On-Demand macro language:

Source view editing

You can edit the XML text of a macro script directly in the source view.

You can cut and paste text between the source view and the system clipboard. This is a very important feature because it allows you to transfer text between the source view and other XML editors or text editors.

Hierarchy of the elements

Figure 82 lists the begin tags of all the XML elements in the Host On-Demand macro language supported in HCL ZIETrans. This list is not valid in terms of XML syntax and does not indicate where more than one element of the same type can occur. However, the indentation in this list does shows which XML elements occur inside other XML elements. For example, the first element in the list, the <HAScript> element, which is not indented at all, is the master element and contains all the other elements. The second element, the <import> element, occurs inside an <HAScript> element and contains a <type> element, and so on.

Figure 82. Hierarchy of elements in the Host On-Demand macro language supported in HCL ZIETrans
<HAScript>                 Encloses all the other elements in the script.
   <import>                Container for <type> elements.
      <type>               Declares an imported data type (Java class).
   <vars>                  Container for <create> elements.
      <create>             Creates and initializes a variable.
   <screen>                Screen element, contains info about one macro screen.
      <description>        Container for descriptors.
         <attrib>          Describes a particular field attribute.
         <cursor>          Describes the location of the cursor.
         <customreco>      Refers to a custom recognition element.
         <numfields>       Describes the number of fields in the screen.
         <numinputfields>  Describes the number of input fields in the screen.
         <string>          Describes a character string on the screen.
         <varupdate>       Assigns a value to a variable.
      <actions>            Container for actions.
         <commwait>        Waits for the specified communication status to occur.
         <custom>          Calls a custom action.
         <extract>         Copies data from the host application screen.
         <else>            Allows you to insert an else-condition.
         <if>              Allows you to insert an if-condition.
         <input>           Sends keystrokes to the host application.
         <mouseclick>      Simulates a mouse click.
         <pause>           Waits for the specified amount of time.
         <perform>         Calls a Java method that you provide.
         <playmacro>       Calls another macro.
         <prompt>          Prompts the user for information.
         <trace>           Writes out a trace record.
         <sqlquery>        Sends an SQL statement to a host database, retrieves 
                           data, and writes it or displays it. 
         <varupdate>       Assigns a value to a variable.
      <nextscreens>           Container for <nextscreen> elements.
         <nextscreen>         Contains the name of a valid next macro screen.
      <recolimit>             Takes action if recognition limit is reached.

The hierarchy of the elements and the corresponding structure of the macro script are discussed in numerous places in this document. In particular, see the following sections:

For descriptions of individual elements, see Macro language elements.

Inserting comments into a macro script

You can insert a comment anywhere inside an <HAScript> element by using XML-style comment brackets <!-- --> around the text of your comment.

Comments are useful for:

Comment errors

The source view will display an error message in the following situations:

Also, you cannot use comment brackets <!-- --> outside the <HAScript> element. If you do so then the source view will discard those comment brackets and the surrounded text when you save the script.

Examples of comments

Following are some examples of the use of comment brackets <!-- --> to insert comments:

<!--
A multi-line comment that comments on
the following <screen> element
-->
<screen name="Screen1" entryscreen="true" exitscreen="false" transient="false">

<!-- A comment on the following <description> element -->
<description>
   <oia status="NOTINHIBITED" optional="false" invertmatch="false" />
</description>

<!-- A comment on the following <actions> element -->
<actions>
   <mouseclick row="4" col="16" />
   <input value="3[enter]" row="0" col="0" movecursor="true"
             xlatehostkeys="true" />
</actions>
<!--
BEGIN
An accidental comment that surrounds part of
a <nextscreens> element,  thereby corrupting
the macro script.
You will get an error when you try to save
this macro script
<nextscreens timeout="0" >
   <nextscreen name="Screen2" />
END of accidental comment
-->
</nextscreens>
</screen>

Debugging macro scripts with the <trace> element

When you are debugging, you can use the <trace> element to send text and values to a trace output destination. In particular, if you include the name of a variable in the output, then the macro runtime will display both the name and the value of the variable in the output, enclosed in curly braces {}. Here is an example:

Figure 83. Example of using the <trace> element
<vars>
<create name="$var1$" type="string" value="'original'" />
</vars>
.
.
<actions>
<trace type="SYSOUT" value="'Before update: '+$var1$" />
<varupdate name="$var1$" value="'updated'" />
<trace type="SYSOUT" value="'After update: '+$var1$" />
</actions>

The code shown in the figure above prints the following text to the console:

Figure 84. Output from example of using the <trace> element
Before update: +{$var1$ = original}
After update: +{$var1$ = updated}

Notice that the <trace> action displays each variable in curly braces {} that contain both the variable name and the contents of the variable.