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:
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.
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:
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:
The macro runtime searches the <actions> element to find any <prompt>
elements that occur within it.
The macro runtime displays the prompts for all the <prompt>
elements immediately (all the prompts are combined into one popup).
The macro runtime collects the user input for all the popup windows.
The macro runtime now performs all the elements in the <actions>
element as usual, in sequence.
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).
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.
The <comment> element inserts a text comment as a sub-element
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.
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:
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.
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)).
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.
<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.
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.
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.
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:
Add code to check the identification string to verify that it
is yours.
Add your custom description code.
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.
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).
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.
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 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.
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).
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.
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).
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.
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.
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).
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.
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.
<!--
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).
<!--
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>
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).
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.
<!-- 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.
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.
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.
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).
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.
<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).
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.
<!-- 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:
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.
<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).
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.
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)).