Macro language elements

This chapter describes the Host On-Demand macro language elements and their attributes, and shows you how to use the macro language elements to create your macros.

Specifying the attributes

XML requirements

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:

<mouseclick row="4" col="51" />

Advanced format in attribute values

As you might 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 non-alphanumeric characters).

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, you must enter the string in the advanced format.

<input value="'3[enter]'" row="0" col="0" movecursor="true"
             xlatehostkeys="true" encrypted="false" />

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:

<screen name="Screen1" entryscreen="true" exitscreen="true" transient="false" >
   ...
</screen>

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

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

promptall
Optional boolean (the default is false). If this attribute is set to true then the macro runtime, before performing any of the actions inside the <actions> element, collects user input for any <prompt> elements inside the element. More specifically:
  1. The macro runtime searches the <actions> element to find any <prompt> elements that occur within it.
  2. The macro runtime displays the prompts for all the <prompt> elements immediately (all the prompts are combined into one popup).
  3. The macro runtime collects the user input for all the popup windows.
  4. The macro runtime now performs all the elements in the <actions> element as usual, in sequence.
  5. When the macro runtime comes to a <prompt> action, it does not display the popup window for user input, but instead performs the <prompt> action using the input from step 3 above.

The promptall attribute of the <HAScript> element performs the same function for all the <prompt> elements in one macro (see <HAScript> element).

XML samples

Figure 85. Example for the <actions> element
<actions promptall="true">
   ...
</actions>
 

<attrib> element

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:
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 attribute.
invertmatch
Optional boolean. See Invertmatch attribute.

XML samples

Figure 86. Example for the <attrib> element
<attrib value="0x3" row="4" col="14" plane="COLOR_PLANE"
            optional="false" invertmatch="false" />
 

<comment> element

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

Attributes

None.

XML samples

Figure 87. Example for the <comment> element
<screen name="Screen2" entryscreen="false" exitscreen="true"
               transient="false">
   <comment>This comment provides information about this macro screen.
   </comment>
   ...
</screen>

Alternate method for inserting comments

An alternate method for inserting a comment is to use the XML-style comment brackets <!-- -->. See Inserting comments into a macro script.

<commwait> element

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 states:
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 88. Example for the <commwait> element
<commwait value="CONNECTION_READY" timeout="10000" />

<condition> element

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 attribute.
invertmatch
Optional boolean. See Invertmatch attribute.

XML samples

Figure 89. Example 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

The <create> element creates and initializes a variable (see Creating a 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 an imported type for a Java class).
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.

XML samples

Figure 90. Example 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

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 attribute.
invertmatch
Optional boolean. See Invertmatch attribute.

XML samples

Figure 91. Example for the <cursor> element
<cursor row="4" col="14" optional="false" invertmatch="false" />

<custom> element

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:

  1. 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.
  2. 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'"  />
  3. 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 92. Example for the <custom> element
<custom id="'MyProgram1'" args="'arg1 arg2 arg3'" />
<custom id="'MyProgram2'" args="'arg1 arg2'" />

<customreco> element

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

The steps for creating a custom descriptor are as follows:

  1. Choose a string to identify the custom description, such as MyCustomDescriptor01. An identifier is required because you can have several types of custom descriptions.
  2. 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.
  3. 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 attribute.
invertmatch
Optional boolean. See Invertmatch attribute.

XML samples

Figure 93. Example for the <customreco> element
<customreco id="'MyCustomDescriptor01'" optional="false" invertmatch="false" />

<description> element

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). 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 94. Example for the <description> element
<description uselogic="true">
   ...
</actions>
 

<else> element

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:

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 95. Example for the <else> element
<if condition="($var_int$ > 10)">
   ...
</if>
<else>
   ...
</else>

<extract> element

The <extract> element 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:
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 attribute.
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 runtime error.
screenorientation
Optional string. Use this attribute to define the host screen orientation to use for the extract during macro playback at runtime. Options are LTR and RTL.

XML samples

Figure 96. Example for the <extract> element
<extract name="'Get Data'" srow="1" scol="1" erow="11" ecol="11"
            assignto="$strText$" planetype="TEXT_PLANE" />

<HAScript> element

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 attribute on the <HAScript> element). By default the Macro Editor sets this value to 60000 milliseconds (60 seconds).
pausetime
Optional integer. The delay for the "pause between actions" (see The pausetime attribute). 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).
ignorepauseoverride
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 97. Example 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

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:

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 98. Example 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

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 99. Example 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

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.
row
Optional integer (default is the current position of the text cursor). Row at which typing begins.
col
Optional integer (default is the current position of the text cursor). Column 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 (movecursor attribute)).
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 (xlatehostkeys attribute)).
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 Encrypted attribute).

XML samples

Figure 100. Example for the <input> element
<input value="'3[enter]'" row="4" column="14" movecursor="true"
            xlatehostkeys="true" encrypted="false" />
 

<mouseclick> element

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.

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 101. Example for the <mouseclick> element
<mouseclick row="20" col="16" />
 

<nextscreen> element

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 Recognizing 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

Figure 102. Example for the <nextscreen> element
   <!--
   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

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).

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

Figure 103. Example for the <nextscreens> element
   <!--
   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

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 attribute.
invertmatch
Optional boolean (the default is false). See Invertmatch attribute.

XML samples

Figure 104. Example for the <numfields> element
<numfields number="10" optional="false" invertmatch="false" />

<numinputfields> element

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 attribute.
invertmatch
Optional boolean (the default is false). See Invertmatch attribute.

XML samples

Figure 105. Example for the <numinputfields> element
<numinputfields number="10" optional="false" invertmatch="false" />
 

<oia> element

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

Attributes

status
Required. The value can be:
optional
Optional boolean (the default is false). See Optional attribute.
invertmatch
Optional boolean. See Invertmatch attribute.

XML samples

Figure 106. Example for the <oia> element
<oia status="NOTINHIBITED" optional="false" invertmatch="false" />

<pause> element

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.
ignorepauseoverride
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 107. Example for the <pause> element
<pause timeout="5000">   

<perform> element

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 108. Example 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

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.
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 109. Example for the <playmacro> element
<playmacro name="ispf_ex1.mac" startscreen="ScreenA"
                 transfervars="Transfer" />

<prompt> element

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:'.
description
Optional string. A description of this action. This description is not displayed.
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.
len
Required integer. The number of characters that the user is allowed to enter into the prompt input field.
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.
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.
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.
movecursor
Optional boolean. Setting this attribute to true causes the macro runtime to move the cursor to the end of the input.
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.
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.
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. 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.
screenorientation
Optional string. Use this attribute to define the host screen orientation to use for the prompt during macro playback at runtime. Options are LTR and RTL.

XML samples

Figure 110. Example 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

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).

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 111. Example for the <recolimit> element
<recolimit value="1" goto="RecoveryScreen1" />

<screen> element

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 The pause attribute).

XML samples

Figure 112. Example for the <screen> element
<screen name="ScreenB" entryscreen="false" exitscreen="false"
            transient="false">
   <description>
      ...
   </description>
   <actions>
      ...
   </actions>
   <nextscreens>
      ...
   </nextscreens>
</screen>   
 

<sqlquery> element

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://myHost.
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.
userid
Optional string. The user ID required to access the database, if one is required.
password
Optional string. The password required to access the database, if one is required.
statement
Required string. The SQL statement.
outputtype
Required integer. The destination where the data resulting from the SQL statement is to be directed. The valid value is: 0 - The data is stored in the macro variable $HMLSQLUtil$. You can retrieve the data by calling methods on the variable.

XML samples

Figure 113. Example 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

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).
optional
Optional boolean (the default is false). See Optional attribute.
invertmatch
Optional boolean. See Invertmatch attribute.

XML samples

Figure 114. Example 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

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:
value
Required string. The string that is to be sent to the trace destination.

XML samples

Figure 115. Example for the <trace> element
<trace type="SYSOUT" value="’The value is ’+$strData$" />

<type> element

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

Figure 116. Example for a <type> element
   <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

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 variable). The <vars> element must occur after the <import> element and before the first <screen> element.

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

Attributes

None.

XML samples

Figure 117. Example 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

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 118. Example 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>