Macro language elements

In the macro language the value of every attribute must be enclosed in double quotes. For example, in the following <mouseclick> element the values of the row and col attributes are enclosed in double quotes:

Advanced format in attribute values

As you may remember, even if a macro is in the advanced format, not all input fields in the Macro Editor expect a string to be placed in single quotes ('') (see Representation of strings and special characters, treatment of operator characters). Specifically, the advanced format affects input fields only on the following tabs of the Macro Editor:

Similarly, in the macro language, when you provide a string value for an attribute that corresponds to one of these input fields that is affected by the advanced format, enter the string in the advanced format.

However, if an attribute does not correspond to one of the input fields affected by the advanced format, then you should not write the value enclosed in single quotes, even if the macro is in the advanced format. For example, the name attribute of the <screen> element should never be enclosed in single quotes:

In the descriptions in this chapter of macro language elements, this book indicates such attributes (attributes that are unaffected by the advanced format) by not specifying a data type. For example, the description of the name attribute of the <screen> element is "Required" rather than as "Required string".

Typed data

Most attributes require a particular type of data: boolean, integer, string, double, or imported. For these attributes, the same rules apply as in the Macro Editor:

<actions> element

General

The <actions> element, the <description> element, and <nextscreens> element are the three primary structural elements that occur inside the <screen> element (see Conceptual view of a macro screen).

The <actions> element contains elements called actions (such as simulating a keystroke, capturing data, and others) that the macro runtime performs during macro playback (see Macro actions).

Attributes

XML samples

Figure 73. Examples for the <actions> element

<actions promptall="true">
   ...
</actions>

<attrib> element

General

The <attrib> element is a descriptor that states the row and column location and the value of a 3270 or 5250 attribute (see Attribute descriptor (<attrib> element)).

Attributes

plane

Required. The data plane in which the attribute resides. The valid values are:

FIELD_PLANE
COLOR_PLANE
DBCS_PLANE
GRID_PLANE
EXFIELD_PLANE
Any expression that evaluates to one of the above.

value

Required. A hexadecimal value in the format 0x37. The value of the attribute.

row

Required integer. The row location of the attribute in the data plane.

col

Required integer. The column location of the attribute in the data plane.

optional

Optional boolean (the default is false). See Optional Descriptor option.

invertmatch

Optional boolean. See Invertmatch Descriptor option.

XML samples

Figure 74. Examples for the <attribute> element

<attrib value="0x3" row="4" col="14" plane="COLOR_PLANE"
            optional="false" invertmatch="false" />

<comment> element

General

The <comment> element inserts a text comment as a subelement within a <screen> element. Limitations are:

You cannot use a <comment> element outside a <screen> element.
You cannot use more than one <comment> element inside the same <screen> element. If you do so then the source view will discard all the <comment> elements inside that <screen> element except the last one.
No matter where in the <screen> element you place the <comment> element, the source view will move the comment up to be the first element within the <screen> element.

A better method for inserting comments

A more flexible method for inserting a comment is to use the XML-style comment brackets . See Inserting comments into a macro script.

Attributes

None.

XML samples

Figure 75. Examples for the <comment> element

<screen name="Screen2" entryscreen="false" exitscreen="true"
               transient="false">
   <comment>This comment provides information about this macro screen.
   </comment>
   ...
</screen>

<commwait> element

General

The <commwait> action waits for the communication status of the session to change to some specified value (see Comm wait action (<commwait> element)). You must specify a timeout value.

Attributes

value

Required. The communication status to wait for. The value must be one of the following (see Communication states):

CONNECTION_INIT
CONNECTION_PND_ACTIVE
CONNECTION_ACTIVE
CONNECTION_READY
CONNECTION_DEVICE_NAME_READY
CONNECTION_WORKSTATION_ID_READY
CONNECTION_PND_INACTIVE
CONNECTION_INACTIVE

timeout: Required integer. A timeout value in milliseconds. The macro runtime terminates the action if the timeout expires before the specified communication status occurs.

XML samples

Figure 76. Examples for the <commwait> element

<commwait value="CONNECTION_READY" timeout="10000" />

<condition> element

General

The <condition> element specifies a conditional expression that the macro runtime evaluates during screen recognition. If the expression evaluates to true then the macro runtime evaluates the descriptor as true. If the expression evaluates to false then the macro runtime evaluates the descriptor as false (see Condition descriptor (<condition>) element).

For more information on conditional expressions see Conditional and logical operators and expressions.

Attributes

value: Required expression. The conditional expression that the macro runtime is to evaluate. This conditional expression can contain arithmetic expressions, variables, return values from Java method calls, and other conditional expressions.
optional: Optional boolean (the default is false). See Optional Descriptor option.
invertmatch: Optional boolean. See Invertmatch Descriptor option.

XML samples

Figure 77. Examples for the <condition> element

<description>
   <! Check the value of a variable -->
   <condition value="$intPartsComplete$ == 4"
            optional="false" invertmatch="false" />

   <!-- Check the return value of a Java method -->
   <condition value="$htHashTable.size()$ != 0"$
            optional="false" invertmatch="false" />
</description>

<create> element

General

The <create> element creates and initializes a variable (see Creating a new variable).

The <create> element must occur inside a <vars> element.

Attributes

name: Required. The name that you assign to the variable. There are a few restrictions on the spelling of variable names (see Variable names and type names).
type: Required. The type of the variable. The standard types are string, integer, double, boolean, field. You an also define an imported type representing a Java class (see Creating a new variable).
value: Optional. The initial value for the variable. If you do not specify an initial value then the default initial value depends on the variable type (see Table 16).

XML samples

Figure 78. Examples for the <create> element

<HAScript ... usevars="true" ... >
   <import>
      <type class="java.util.Properties" name="Properties" />
   </import>

   <vars>
      <create name="$prp$" type="Properties" value="$new Properties()$" />
      <create name="$strAccountName$" type="string" value="" />
      <create name="$intAmount$" type="integer" value="0" />
      <create name="$dblDistance$" type="double" value="0.0" />
      <create name="$boolSignedUp$" type="boolean" value="false" />
      <create name="$fldFunction$" type="field" />
   </vars>
   ...
</HAScript>

<cursor> element

General

The <cursor> element is a descriptor that states the row and column location of the text cursor on the host terminal (see Cursor descriptor (<cursor> element)).

Attributes

row: Required integer. The row location of the text cursor.
col: Required integer. The column location of the text cursor.
optional: Optional boolean (the default is false). See Optional Descriptor option.
invertmatch: Optional boolean. See Invertmatch Descriptor option.

XML samples

Figure 79. Examples for the <cursor> element

<cursor row="4" col="14" optional="false" invertmatch="false" />

<custom> element

General

The <custom> element allows you to invoke a custom Java program from inside the <actions> element of a macro screen.

Here is an overview of the process:

Suppose that you have a Java program that you want to invoke as an action during the processing of a macro screen's <actions> element.
In the Macro Editor, add the following line to the <actions> element at the location at which you want to invoke the custom Java program:
```
<custom id="'MyProgram1'" args="'arg1 arg2 arg3'"  />
```
Follow the instructions in the MacroActionCustom class. You will create a class that implements MacroCustomActionListener. The execute() method will be called with an event when the macro runtime performs the <custom> action in step 2.

Attributes

id: Required. An arbitrary string that identifies the custom Java program that you want to run.
args: Optional. The arguments that you want to pass to the custom Java program.

XML samples

Figure 80. Examples for the <custom> element

<custom id="'MyProgram1'" args="'arg1 arg2 arg3'" />
<custom id="'MyProgram2'" args="'arg1 arg2'" />

<customreco> element

General

This <customreco> element allows you to call custom description code.

The steps for creating a custom descriptor are as follows:

Choose a string to identify the custom description, such as MyCustomDescriptor01. An identifier is required because you can have several types of custom descriptions.
Implement the ECLCustomRecoListener interface. In the doReco() method:
1. Add code to check the identification string to verify that it is yours.
2. Add your custom description code.
3. Return true if the custom description is satisfied or false if it is not.
Use the source view to add a <customreco> element to the <description> element of the macro screen. The <customreco> element must specify the identifier you chose in step 2.

The macro runtime performs the <customreco> element after performing all the other descriptors.

Attributes

id: Required string. The identifier that you have assigned to this custom description.
optional: Optional boolean (the default is false). See Optional Descriptor option.
invertmatch: Optional boolean. See Invertmatch Descriptor option.

XML samples

Figure 81. Examples for the <customreco> element

<customreco id="'MyCustomDescriptor01'" optional="false" invertmatch="false" />

<description> element

General

The <actions> element, the <description> element, and the <nextscreens> element are the three primary structural elements that can occur inside the <screen> element (see Conceptual view of a macro screen).

The <description> element contains elements called descriptors, each of which states an identifying characteristic of an application screen (see Screen description and recognition). The macro runtime uses the descriptors to match the macro screen to an application screen.

Attributes

uselogic: Optional boolean. Allows you to define more complex logical relations among multiple descriptors than are available with the default combining method (see The uselogic attribute).

XML samples

Figure 82. Examples for the <description> element

<description uselogic="true">
   ...
</actions>

<else> element

General

The <else> element contains a sequence of macro actions and must occur immediately after an <if> element. The macro runtime evaluates the conditional expression in the <if> element. Then:

If the conditional expression is true:
- The macro runtime performs the sequence of macro actions in the <if> element; and
- The macro runtime skips the following <else> element if there is one.
If the conditional expression is false:
- The macro runtime skips the sequence of macro actions in the <if> element; and
- The macro runtime performs the macro actions in the following <else> element if there is one.

The Macro object uses the <if> element, and if necessary the <else> element, to store a Conditional action (see Conditional action (<if> element and <else> element)).

Attributes

None.

XML samples

Figure 83. Examples for the <else> element

<if condition="($var_int$ > 10)">
   ...
</if>
<else>
   ...
</else>

<extract> element

General

This <extract> action captures data from the host terminal (see Extract action (<extract> element)).

Attributes

For more information on the use of all these attributes see Extract action (<extract> element).

name

Required string. A name to be assigned to the extracted data.

planetype

Required. The plane from which the data is to be extracted. Valid values are:

TEXT_PLANE
FIELD_PLANE
COLOR_PLANE
EXFIELD_PLANE
DBCS_PLANE
GRID_PLANE

srow

Required integer. The row of the first pair of row and column coordinates.

scol

Required integer. The column of the first pair of row and column coordinates.

erow

Required integer. The row of the second pair of row and column coordinates.

scol

Required integer. The column of the second pair of row and column coordinates.

unwrap

Optional boolean. Setting this attribute to true causes the macro runtime to capture the entire contents of any field that begins inside the specified rectangle. See Unwrap Text option.

continuous

Optional boolean. Setting this attribute to true causes the macro runtime to interpret the row-column coordinates as the beginning and ending locations of a continuous sequence of data that wraps from line to line if necessary. If this attribute is set to false then the macro runtime interprets the row-column coordinates as the upper left and lower right corners of a rectangular area of text. See Capturing a sequence of text from the host terminal.

assigntovar

Optional variable name. Setting this attribute to a variable name causes the macro runtime to store the text plane data as a string value into the variable. If the variable is of some standard type other than string (that is, boolean, integer, or double) then the data is converted to that standard type, if possible. If the data cannot be converted then the macro terminates with a run-time error (see Specify the variable in which you want the text to be stored).

XML samples

Figure 84. Examples for the <extract> element

<extract name="'Get Data'" srow="1" scol="1" erow="11" ecol="11"
            assignto="$strText$" />

<HAScript> element

General

The <HAScript> element is the master element of a macro script. It contains the other elements and specifies global information about the macro (see Conceptual view of a macro script).

Attributes

name: Required. The name of the macro.
description: Optional. Descriptive text about this macro. You should include here any information that you want to remember about this macro.
timeout: Optional integer. The number of milliseconds allowed for screen recognition. If this timeout value is specified and it is exceeded, then the macro runtime terminates the macro and displays a message (see Timeout Between Screens (Macro tab)). By default the Macro Editor sets this value to 60000 milliseconds (60 seconds).
pausetime: Optional integer. The delay for the "pause between actions" (see Pause Between Actions (Macro tab)). By default the Macro Editor sets this value to 300 milliseconds.
promptall: Required boolean. If this attribute is set to true then the macro runtime, before performing any action in the first macro screen, collects user input for all the <prompt> elements inside the entire macro, combining the individual prompts into one large prompt. The promptall attribute of the <actions> element performs a similar function for all the <prompt> elements in one <actions> element (see <actions> element).
author: Optional. The author or authors of this macro.
creationdate: Optional. Information about the dates and versions of this macro.
suppressclearevents: Optional boolean (default false). Advanced feature that determines whether the system should ignore screen events when a host application sends a clear screen command immediately followed by an end of record indicator in the data stream. You might want to set this value to true if you have screens in your application flow that have all blanks in them. If there is a valid blank screen in the macro and clear commands are not ignored, it is possible that a screen event with all blanks will be generated by clear commands coming from an ill-behaved host application. This will cause a screen recognition event to be processed and the valid blank screen will match when it shouldn't have matched.
usevars: Required boolean (default false). If this attribute is set to true then the macro uses the advanced macro format (see Basic and advanced macro format).
ignorepauseforenhancedtn: Optional. 3270 Display sessions only. If this attribute is set to true then the macro runtime skips all <pause> elements if the session is a TN3270E session running in contention-resolution mode (see Attributes that deal with screen completion). To re-enable a particular <pause> element see the ignorepauseoverrideforenhancedtn attribute of the <pause> element.
delayifnotenhancedtn: Optional. 3270 Display Sessions only. This attribute specifies a value in milliseconds and has an effect only when the session is not a TN3270E session running in contention-resolution mode. In that situation, this attribute causes the macro runtime to add a pause of the specified duration each time the macro runtime receives a notification that the OIA indicator has changed (see Attributes that deal with screen completion).

XML samples

Figure 85. Examples for the <HAScript> element

<HAScript name="ispf_ex2" description="ISPF Sample2" timeout="60000"
            pausetime="300" promptall="true" author="Owner"
            creationdate="Sun Jun 08 12:04:26 PDT 2003"
            supressclearevents="false" usevars="true"
            ignorepauseforenhancedtn="false"
            delayifnotenhancedtn="0">
   ...
</HAScript>

<if> element

General

The <if> element contains a conditional expression and a sequence of macro actions. The macro runtime evaluates the conditional expression in the <if> element. Then:

If the conditional expression is true:
- The macro runtime performs the sequence of macro actions in the <if> element; and
- The macro runtime skips the following <else> element if there is one.
If the conditional expression is false:
- The macro runtime skips the sequence of macro actions in the <if> element; and
- The macro runtime performs the macro actions in the following <else> element if there is one.

The Macro object uses the <if> element, and if necessary the <else> element, to store a Conditional action (see Conditional action (<if> element and <else> element)).

Attributes

condition: Required. A conditional expression. The conditional expression can contain logical operators and conditional operators and can contain terms that include arithmetic expressions, immediate values, variables, and calls to Java methods (see Conditional and logical operators and expressions).

XML samples

Figure 86. Examples for the <if> element

<vars>
   <create name="$condition1$" type="string"/>
   <create name="$condition2$" type="boolean" value="false"/>
   <create name="$condition3$" type="integer"/>
</vars>
<screen>
   <description>
        ...
   </description>
   <actions promptall="true">
      <extract name="Get condition 1" srow="2" scol="1" erow="2"
               ecol="80" assigntovar="$condition1$"/>
      <extract name="Get condition 2" srow="3" scol="1" erow="3"
               ecol="80" assigntovar="$condition2$"/>
      <extract name="Get condition 3" srow="4" scol="1" erow="4"
               ecol="80" assigntovar="$condition3$"/>

      <if condition=
               "(($condition1$ !='')&&
               ($condition2$)||($condition3$ < 100))">
           ...
      </if>
      <else>
           ...
      </else>
   </actions>
</screen>

<import> element

General

The <import> element, the <vars> element, and the <screen> element are the three primary structural elements that occur inside the <HAScript> element (see Conceptual view of a macro script).

The <import> element is optional. It contains <type> elements each of which declares an imported type based on a Java class (see Creating an imported type for a Java class).

The <import> element must occur after the <HAScript> begin tag and before the <vars> element.

Attributes

None.

XML samples

Figure 87. Examples for the <import> element

<HAScript .... >
   <import>
      <type class="java.util.Properties" name="Properties" />
   </import>

   <vars>
      <create name="$prp$" type="Properties" value="$new Properties()$" />
   </vars>
...
</HAScript>

<input> element

General

The <input> element sends a sequence of keystrokes to the host terminal. The sequence can include keys that display a character (such as a, b, c, #, &, and so on) and also action keys (such as [enterreset], [copy], [paste], and others) (see Input action (<input> element)).

Attributes

value: Required string. The sequence of keys to be sent to the host terminal (see Input string).

row: Optional integer (default is the current position of the text cursor). Row at which typing begins (see Location at which typing begins).

col: Optional integer (default is the current position of the text cursor). Column at which typing begins (see Location at which typing begins).

movecursor: Optional boolean (default is true). Setting this attribute to true causes the macro runtime to move the text cursor to the end of the input (see Move Cursor to End of Input).

xlatehostkeys: Optional boolean (default is true). Setting this attribute to true causes the macro runtime to interpret the name of an action key (such as [enter]) as an action key rather than as a character sequence (see Translate Host Action Keys).

encrypted: Optional boolean (default is false). Setting this attribute to true causes the Macro Editor to encrypt the sequence of keys contained in the value attribute when the Macro Editor is closed (see Password).

XML samples

Figure 88. Examples for the <input> element

<input value="'3[enter]'" row="4" column="14" movecursor="true"
            xlatehostkeys="true" encrypted="false" />

<mouseclick> element

General

The <mouseclick> element simulates a mouse click on the host terminal by the user. As with a real mouse click, the text cursor jumps to the row and column position where the mouse icon was pointing when the click occurred (see Mouse click action (<mouseclick> element)).

Attributes

row: Required integer. The row of the row and column location on the host terminal where the mouse click occurs.
col: Required integer. The column of the row and column location on the host terminal where the mouse click occurs.

XML samples

Figure 89. Examples for the <mouseclick> element

<mouseclick row="20" col="16" />

<nextscreen> element

General

The <nextscreen> element specifies the name of a <screen> element (macro screen) that the macro runtime should consider, among others, as a candidate to be the next macro screen to be processed (see Valid next screens).

The <nextscreen> element must occur within a <nextscreens> element.

Attributes

name: Required. The name of the <screen> element that is a candidate to be the next macro screen to be processed.

XML samples

   <!--
   The effect of the following <nextscreens> element and its contents
   is that when the macro runtime finishes performing the actions in
   the current screen, it adds ScreenS and ScreenG to the runtime list of
   valid next screens.
   -->
   <nextscreens>
      <nextscreen name="ScreenS">
      <nextscreen name="ScreenG">
   </nextscreens>

<nextscreens> element

General

The <actions> element, the <description> element, and the <nextscreens> element are the three primary structural elements that occur inside the <screen> element (see Conceptual view of a macro screen).

The <nextscreens> element contains <nextscreen> elements, each of which states the name of a macro screen that can validly occur after the current macro screen (see Screen Recognition, Part 2).

Attributes

timeout: Optional integer. The value in milliseconds of the screen recognition timeout. The macro runtime terminates the macro if it cannot match a macro screen whose name is on the runtime list of valid next screens to the application screen before this timeout expires (see Timeout settings for screen recognition).

XML samples

   <!--
   The effect of the following <nextscreens> element and its contents
   is that when the macro runtime finishes performing the actions in
   the current screen, it will attempt to recognize ScreenS and ScreenG.
   -->
   <nextscreens>
      <nextscreen name="ScreenS">
      <nextscreen name="ScreenG">
   </nextscreens>

<numfields> element

General

The <numfields> element is a descriptor that states the number of 3270 or 5250 fields of all types that exist in the host terminal (see Number of Fields descriptor (<numfields> element)).

Attributes

number: Required integer. The number of fields in the host terminal.
optional: Optional boolean (the default is false). See Optional Descriptor option.
invertmatch: Optional boolean (the default is false). See Invertmatch Descriptor option.

XML samples

Figure 90. Examples for the <numfields> element

<numfields number="10" optional="false" invertmatch="false" />

<numinputfields> element

General

The <numinputfields> element is a descriptor that states the number of 3270 or 5250 input fields that exist in the host terminal (see Number of Input Fields descriptor (<numinputfields> element)).

Attributes

number: Required integer. The number of fields in the host terminal.
optional: Optional boolean (the default is false). See Optional Descriptor option.
invertmatch: Optional boolean (the default is false). See Invertmatch Descriptor option.

XML samples

Figure 91. Examples for the <numinputfields> element

<numinputfields number="10" optional="false" invertmatch="false" />

<oia> element

General

The <oia> element is a descriptor that describes the state of the input inhibited indicator in the host terminal (see Wait for OIA to Become Uninhibited descriptor (<oia> element)).

Attributes

status

Required. The value can be:

NOTINHIBITED
The macro runtime evaluates the descriptor as true if the input inhibited indicator is cleared, or false if the input inhibited indicator is set.
DONTCARE
The macro runtime always evaluates the descriptor as true.
An expression that evaluates to either NOTINHIBITED or DONTCARE
The macro runtime evaluates the expression and then, depending on the result, evaluates the descriptor as usual.

optional

Optional boolean (the default is false). See Optional Descriptor option.

invertmatch

Optional boolean. See Invertmatch Descriptor option.

XML samples

Figure 92. Examples for the <oia> element

<oia status="NOTINHIBITED" optional="false" invertmatch="false" />

<pause> element

General

The <pause> element waits for the specified number of milliseconds (see Pause action (<pause> element)).

Attributes

value: Optional integer. The number of milliseconds to wait. If you do not specify this attribute then the Macro object will add the attribute "value=10000" (10 seconds) to the element when it saves the script.
ignorepauseoverrideforenhancedtn: Optional boolean (the default is false). For 3270 Display sessions only. Setting this attribute to true causes the macro runtime to process the <pause> element even if the ignorepauseforenhancedtn attribute of the <HAScript> element is set to true (see Attributes that deal with screen completion).

XML samples

Figure 93. Examples for the <pause> element

<pause timeout="5000">

<perform> element

General

The <perform> element invokes a method belonging to a Java class that you have imported (see Creating an imported type for a Java class).

You can invoke a method in many other contexts besides the <perform> element. However, the <perform> element is useful when you want to invoke a method that does not return a value (see Perform action (<perform> element)).

Attributes

value: Required. You must enclose a method call in dollar signs ($), just as you would a variable (see Syntax of a method call). You should specify the parameters, if any, of the method call in the same format that you would use if you were creating a Perform action in the Macro Editor.

XML samples

Figure 94. Examples for the <perform> element

<!-- Call the update() method associated with the class to which
     importedVar belongs (such as mypackage.MyClass).
-->
<perform value="$importedVar.update( 5, 'Application', $str$)$" />

<playmacro> element

General

The <playmacro> element terminates the current macro and launches another macro (see PlayMacro action (<playmacro> element). This process is called chaining macros.

There are restrictions on where in the <actions> element you can place a <playmacro> element (see Adding a PlayMacro action).

Attributes

name: Required. The name of the target macro. The target macro must reside in the same location as the calling macro (see Target macro file name and starting screen).

startscreen: Optional. The name of the macro screen (<screen> element) at which you want the macro runtime to start processing the target macro. Use the value *DEFAULT* or omit this parameter to have the macro runtime start at the usual starting screen of the target macro.

transfervars: Required. Setting this attribute to Transfer causes the macro runtime to transfer the variables belonging to the calling macro to the target macro (see Transferring variables). The default is No Transfer.

XML samples

Figure 95. Examples for the <playmacro> element

<playmacro name="ispf_ex1.mac" startscreen="ScreenA"
                 transfervars="Transfer" />

<prompt> element

General

The <prompt> element displays a popup window prompting the user for input, waits for the user to click OK, and then sends the input to the host terminal (see Prompt action (<prompt> element)).

Attributes

name: Optional string. The text that is to be displayed in the popup window, such as 'Enter your response here:' (see Parts of the prompt window).

description: Optional string. A description of this action. This description is not displayed (see Parts of the prompt window).

row: Required integer. The row on the host terminal at which you want the macro runtime to start typing the input from the user.

col: Required integer. The column on the host terminal at which you want the macro runtime to start typing the input from the user (see Handling the input sequence in the host terminal).

len: Required integer. The number of characters that the user is allowed to enter into the prompt input field (see Response Length).

default: Optional string. The text to be displayed in the input field of the popup window. If the user does not type any input into the input field but just clicks OK, the macro runtime will send this default input to the host terminal (see Default Response).

clearfield: Optional boolean. Setting this attribute to true causes the macro runtime, before sending the input sequence to the host terminal, to clear the input field of the host terminal in which the row and column location occur (see Handling the input sequence in the host terminal).

encrypted: Optional boolean. Setting this attribute to true causes the macro runtime, when the user types a key into the input field of the window, to display an asterisk (*) instead of the character associated with the key (see Password Response).

movecursor: Optional boolean. Setting this attribute to true causes the macro runtime to move the cursor to the end of the input (see Handling the input sequence in the host terminal).

xlatehostkeys: Optional boolean. Setting this attribute to true causes the macro runtime to interpret the names of action keys (such as [enter]) as action keys rather than as sequences of characters (see Action keys and Translate Host Action Keys).

assigntovar: Optional variable name. Setting this attribute to a variable name causes the macro runtime to store the input into the variable whose name you specify here (see Assigning the input sequence to a variable).

varupdateonly: Optional boolean. Setting this attribute to true causes the macro runtime to store the input into a variable and not to send it to the host terminal (see Handling the input sequence in the host terminal). This attribute takes effect only if the assigntovar attribute is set to true.

required: Optional boolean. Setting this attribute to true causes the macro runtime to disable the OK button in the prompt window until the input field of the prompt window contains text. The input field can contain text either because you have specified a Default Response or because the user has typed text into the input field (see Require Response).

XML samples

Figure 96. Examples for the <prompt> element

<prompt name="'ID'" row="1" col="1" len="8" description="'ID for Logon'"
        default="'guest'" clearfield="true" encrypted="true"
        assigntovar="$userID$" varupdateonly="true" required="true"/>

<recolimit> element

General

The <recolimit> element is an optional element that occurs within a <screen> element, at the same level as the <description>, <actions>, and <nextscreens> elements (see Recognition limit (General tab of the Screens tab)).

The <recolimit> element allows you to take action if the macro runtime processes the macro screen in which this element occurs more than some specified number of times.

Attributes

value: Required integer. The recognition limit. If the macro runtime recognizes the macro screen this many times, then the macro runtime does not process the actions of this macro screen but instead performs the specified action.

goto: Optional string (the default is for the macro runtime to display an error message and terminate the macro). The name of a macro screen that you want the macro runtime to start processing when the recognition limit is reached.

XML samples

Figure 97. Examples for the <recolimit

<recolimit value="1" goto="RecoveryScreen1" />

<screen> element

General

The <screen> element, the <import> element, and the <vars> element are the three primary structural elements that occur inside the <HAScript> element (see Conceptual view of a macro script).

Multiple screen elements can occur inside a macro. One <screen> element contains all the information for one macro screen (see The macro screen and its subcomponents).

The <screen> element contains three primary structural elements: the <actions> element, the <description> element, and <nextscreens> (see Conceptual view of a macro screen).

Attributes

name: Required. The name of this <screen> element (macro screen). The name must not be the same as the name of an already existing <screen> element.
entryscreen: Optional boolean (the default is false). Setting this attribute to true causes the macro runtime to treat this <screen> element as a valid beginning screen for the macro (see Entry screens).
exitscreen: Optional boolean (the default is false). Setting this attribute to true causes the macro runtime to treat this <screen> element as a valid ending screen for the macro (see Exit screens).
transient: Optional boolean (the default is false). Setting this attribute to true causes the macro runtime to treat this <screen> element as a screen that can appear at any time and that always needs to be cleared (see Transient screens).
pause: Optional integer (the default is -1). Specifying a value in milliseconds for this attribute causes the macro runtime, for this <screen> element, to ignore the default delay for the "pause between actions" (set using the pausetime attribute of the <HAScript> element) and to use this value instead (see Set Pause Time (General tab of the Screens tab)).

XML samples

Figure 98. Examples for the <screen> element

<screen name="ScreenB" entryscreen="false" exitscreen="false"
            transient="false">
   <description>
      ...
   </description>
   <actions>
      ...
   </actions>
   <nextscreens>
      ...
   </nextscreens>
</screen>

<sqlquery> element

General

The <sqlquery> element sends an SQL statement to a database, retrieves the data resulting from the SQL statement, if any, and then stores the data into a macro variable (see SQLQuery action (<sqlquery> element)).

Attributes

url: Required string. The database URL for the database server to which the SQL statement is sent, such as jdbc:as400://myISeries (see Database URL).

driver: Required string. The fully qualified package name of the driver used to connect with the database server, such as COM.ibm.db2.jdbc.app.DB2DRIVER. This package must be present on the client workstation (see Driver Identifier and Driver Class).

userid: Optional string. The user ID required to access the database, if one is required (see User ID and Password).

password: Optional string. The password required to access the database, if one is required (see User ID and Password).

statement: Required string. The SQL statement (see Statement).

outputtype

Required integer. The destination where the data resulting from the SQL statement is to be directed. Valid values are:

0 - The data is stored in the macro variable $HMLSQLUtil$. You can retrieve the data by calling methods on the variable (see Storing the data into a macro variable ($HMLSQLUtil$)).

XML samples

Figure 99. Examples for the <sqlquery> element

<sqlquery url="'jdbc:as400://elcrtp06'"  
   driver="'com.ibm.as400.access.AS400JDBCDriver'" 
   userid="'myuser'"
   password="Ex0bRtrf73mPrwGrWMT+/g=="
   statement="'SELECT * FROM SQLTEST WHERE ((SQLTEST.DESCRIPT is not null))'"
   outputtype="0" />

<string> element

General

The <string> element is a descriptor that specifies a sequence of characters and a rectangular area of the host terminal in which the sequence occurs (see String descriptor (<string> element)).

The sequence of characters can occur anywhere in the rectangular block.

Attributes

value

Required string. The sequence of characters.

row

Optional integer (the default is to search the entire screen). The row location of one corner of a rectangular block of text.

col

Optional integer. The column location of one corner of a rectangular block of text.

erow

Optional integer. The row location of the opposite corner of a rectangular block of text.

ecol

Optional integer. The column location of the opposite corner of a rectangular block of text.

casesense

Optional boolean (the default is false). Setting this attribute to true causes the macro runtime to do a case-sensitive string compare.

wrap

Optional boolean (the default is false).

Setting this attribute to false causes the macro runtime to search for the sequence of characters in each separate row of the rectangular block of text. If the sequence of characters wraps from one row to the next, the macro runtime will not find it.
Setting this attribute to true causes the macro runtime to check for the sequence of characters occurring in any row or wrapping from one row to the next of the rectangular block of text (see How the macro runtime searches the rectangular area (Wrap option)).

optional

Optional boolean (the default is false). See Optional Descriptor option.

invertmatch

Optional boolean. See Invertmatch Descriptor option.

XML samples

Figure 100. Examples for the <string> element

   <!-- The string must occur in one specific area of a single row  -->
   <string value="'Utility Selection Panel'" row="3" col="28"
               erow="3" ecol="51" casesense="false" wrap="false"
               optional="false" invertmatch="false" />

   <!-- The string can occur in any single row of the session area -->
   <string value="'Utility Selection Panel'" row="1" col="1"
               erow="-1" ecol="-1" casesense="false" wrap="false"
               optional="false" invertmatch="false" />

<trace> element

General

The <trace> element sends a trace message to a trace destination that you specify, such as a console (see Trace action (<trace> element)).

Attributes

type

Required. The destination for the trace data. The destination must be one of the following:

HODTRACE: The Host On-Demand Trace Facility.
USER: A user trace handler.
SYSOUT: The WebSphere console.

value

Required string. The string that is to be sent to the trace destination.

XML samples

Figure 101. Examples for the <trace> element

<trace type="SYSOUT" value="'The value is '+$strData$" />

<type> element

General

The <type> element declares an imported type (such as Properties) that represents a Java class (such as java.util.Properties). After you have declared the type, you can create variables based on the type, create an instance of the Java class, and call methods on the instance (see Creating an imported type for a Java class).

A type can also be used for directly calling static methods (no need to instantiate).

The <type> element must occur inside a <import> element.

Attributes

class: Required. The fully qualified class name of the class being imported, including the package name if any (such as java.util.Properties).
name: Optional. A short name (such as Properties) that you can use elsewhere in the macro to refer to the imported type. If you do not specify a short name, then the short name is the same as the fully qualified class name. There are a few restrictions on the spelling of type names (see Variable names and type names).

XML samples

   <import>
      <type class="java.util.Date" name="Date"/>
      <type class="java.io.FileInputStream"/>
      <type class="com.ibm.eNetwork.beans.HOD.HODBean" name="HODBean"/>
      <type class="myPackage.MyClass" name="MyClass"/>
   </import>

<vars> element

General

The <vars> element, the <import> element, and the <screen> element are the three primary structural elements that occur inside the <HAScript> element (see Conceptual view of a macro script).

The <vars> element is optional. It contains <create> elements, each of which declares and initializes a variable (see Creating a new variable). The <vars> element must occur after the <import> element and before the first <screen> element.

To use variables, set the usevars element in <HAScript> to true.

Attributes

None.

XML samples

Figure 102. Examples for the <vars> element

<HAScript ... usevars="true" .... >
   <import>
      <type class="java.util.Properties" name="Properties" />
   </import>

   <vars>
      <create name="$prp$" type="Properties" value="$new Properties()$" />
      <create name="$strAccountName$" type="string" value="" />
      <create name="$intAmount$" type="integer" value="0" />
      <create name="$dblDistance$" type="double" value="0.0" />
      <create name="$boolSignedUp$" type="boolean" value="false" />
      <create name="$fldFunction$" type="field" />
   </vars>
   ...
</HAScript>

<varupdate> element

General

The <varupdate> element causes the macro runtime to store a specified value into a specified variable. The value can be an immediate value, a variable, a call to a Java method, or an arithmetic expression that can contain any of these values. If the value is an expression, then during macro playback the macro runtime evaluates the expression and stores the resulting value into the specified variable (see Variable update action (<varupdate> element)).

You can also use the <varupdate> action in a <description> element (see Variable update action (<varupdate> element)).

For more information on variables see Variables and imported Java classes.

Attributes

name: Required. The name of the variable.
value: Required string. The value or expression to be assigned to the variable.

XML samples

Figure 103. Examples for the <varupdate> element

<type>
   <type class="mypackage.MyClass" name="MyClass" />
   <type class="java.util.Hashtable" name="Hashtable" />
   <type class="java.lang.Object" name="Object" />
</type>

<vars>
   ...
</vars>

<screen>
   <description>
   ...
   </description>
   <actions>
      <varupdate name="$var_boolean1$"  value="false" />
      <varupdate name="$var_int1$"      value="5" />
      <varupdate name="$var_double1$"   value="5" />
      <varupdate name="$var_string1$"   value="'oak tree'" />
      <varupdate name="$var_field1$"    value="4,5" />

      <!-- null keyword -->
      <varupdate name="$var_importedMC1$"  value="null" />
      <!--  Equivalent to null keyword for an imported type  -->
      <varupdate name="$var_importedMC2$"  value="" />

      <varupdate name="$var_importedMC4$"
                  value="$new MyClass( 'myparam1', 'myparam2' )$" />
      <varupdate name="$var_importedMC5$"
                  value="$var_importedMC4$" />
      <varupdate name="$var_importedMC6$"
                  value="$MyClass.createInstance( 'mystringparam1' )$" />
      <varupdate name="$var_boolean2$"
                  value="$var_importedMC4.isEmpty()$" />
      <varupdate name="$var_int2$"
                  value="$($var_importedMC4.getHashtable()$).size()$" />
      <varupdate name="$var_double2$"
                  value="$var_importedMC4.getMeters()$" />
      <varupdate name="$var_string2$"
                  value="$var_importedMC4.toString()" />
   </actions>
</screen>

Macro language elements

Specifying the attributes

XML requirements

Advanced format in attribute values

Typed data

<actions> element

General

Attributes

XML samples

<attrib> element

General

Attributes

XML samples

<comment> element

General

A better method for inserting comments

Attributes

XML samples

<commwait> element

General

Attributes

XML samples

<condition> element

General

Attributes

XML samples

<create> element

General

Attributes

XML samples

<cursor> element

General

Attributes

XML samples

<custom> element

General

Attributes

XML samples

<customreco> element

General

Attributes

XML samples

<description> element

General

Attributes

XML samples

<else> element

General

Attributes

XML samples

<extract> element

General

Attributes

XML samples

<HAScript> element

General

Attributes

XML samples

<if> element

General

Attributes

XML samples

<import> element

General

Attributes

XML samples

<input> element

General

Attributes

XML samples

<mouseclick> element

General

Attributes

XML samples

<nextscreen> element

General

Attributes

XML samples

<nextscreens> element

General