Features of the macro language

Use of XML

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:

• XML code is made up of elements. The Host On-Demand macro language contains about 35 XML elements.

• Element names in the macro language are not case-sensitive, except in the sense that write an element in the same combination of upper and lower case in both the begin tag and the end tag. All of the following are correct (the ellipsis "..." is not part of the XML text but is meant to indicate that the element contains other elements):

  <screen>   ...      </screen>
  <Screen>   ...      </Screen>
  <scrEen>   ...      </scrEen>

  However, customarily the master element is spelled HAScript and the other elements are spelled with all lower case.

• Each XML element has a begin tag and an end tag, as shown in the examples below from the Host On-Demand macro language.:

  <HAScript> ... </HAScript>
  <import> ... </import>
  <vars> ... </vars>
  <screen> ... </screen>
  

• Optionally you can combine the begin tag and end tag of an XML element into one tag. This option is useful when the XML element includes attributes but not other elements. For example,

  <oia ... />
  <numfields ...  />

• An element can contain attributes of the form attribute_name="attribute_value". For example:

  <oia status="NOTINHIBITED" optional="false" invertmatch="false"/>
  <numfields number="80" optional="false" invertmatch="false"/>
  

  You can use a pair of empty double quote characters (that is, two double quote characters with nothing in between) to specify that the attribute is not set to a value.

  <HAScript name="ispf_ex1" description="" timeout="60000" ... author="" ...>
     ...
  </HAScript>

• An element can include other entire elements between its begin tag and end tag, in much the same way that HTML does. In the example below a <description> element contains two elements: an <oia> element and a <numfields> element.

  <description>
     <oia status="NOTINHIBITED" optional="false" invertmatch="false">
     <numfields number="80" optional="false" invertmatch="false"/>
  </description>

Source view

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 70 lists the begin tags of all the XML elements in the Host On-Demand macro language supported in HATS. 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 70. Hierarchy of elements in the Host On-Demand macro language supported in HATS

<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 the <HAScript> element see Conceptual view of a macro script.

• For the <screen> element see Conceptual view of a macro screen.

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:

• Organizing a macro script by providing descriptive text.

• Documenting a macro script by explaining complexities.

• Debugging a macro script by commenting out executable elements in order to determine which remaining element is causing a problem.

Comment errors

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

• Nested comments

• A comment that comments out part of an executable element.

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

Here 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 71. 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 72. 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 brackets {} that contain both the variable name and the contents of the variable.