IBM eNetwork Host Access Beans Reference

Host Access Beans for Java


Appendix A. Macro Script Syntax

After a macro script has been created using the Macro bean, you might want to manually edit it. Manually editing macro scripts should only be performed by advanced users. This guide to the macro script syntax contains the following sections:

Contents

Introduction

Macro Syntax

The Most Powerful Macro

Recolimit Demonstration

Introduction

The IBM Host On-Demand uses XML because a macro is better suited to the state machine model (the main reason for the move: XML is tailor made for a state machine).

The idea of a state machine may be fairly new to you. The idea behind a state machine, especially in the IBM Host On-Demand macro context, is simple. Think of how you use a host system from a terminal or a terminal emulator (like IBM Host On-Demand). The process you follow when you interact with a host system is illustrated in these steps:

  1. The host sends an expected screen down to you at your terminal.
  2. You look at and understand which screen is presented to you.
  3. You take the required actions based on your understanding (type keystrokes, and so forth).
  4. Another screen is presented after these actions.
  5. If you see the screen you expected, you do this all over again.
  6. If you do not see the screen you expected, call the help desk or handle the error.

This is the idea behind a state machine in the Macro context (although the Macro can't call the help desk for you). The states are the screens you expect to see, and you take actions on those screens to change from one state, or screen, to another. That's it, see a screen, perform the action, see the next screen. It is easier to understand (and program) a macro with this approach than having several if-then-else and do-while programming statements. Remember, see a screen, perform the action, see the next screen.

Now that you understand that a macro is a series of screens with their actions associated with them, take a look at how well suited XML is to coding a macro. Here is an example of how to specify a logon macro:

<HAScript>
<screen name="Logon" startscreen="true">
	<description>
		<string value="Please Logon" casesense="true"/>
		<cursor row="12" col="10"/>
	</description>
	<actions>
		<prompt name="ID" row="12" col="10" len="8"/>
		<prompt name="Password" row="13" col="10" len="8"/>
		<input value="[enter]"/>
	</actions>
	<nextscreens>
		<nextscreen name="Logon.Complete"/>
	</nextscreens>
</screen>
</HAScript>

These few lines of code demonstrate the power of this new syntax. All the screens you expect to see for a task (like logging on) are coded within <screen> elements in XML. You describe the screen in a <description> element, specify the actions for the screen in an <actions> element, and specify the screen you want to see next in a <nextscreens> element.

With the above example, keep in mind that the actions fire in sequence. The screen element describes a logon screen with the text Please Logon on the screen and the screen's cursor position at row 12, column 10. If the Macro logic sees a screen matching this description, it prompts the user for an ID and Password, places the prompt results at the specified row and column positions, and sends the ENTER key, effectively logging on the user. The nextscreens element specifies the name of another screen element that appears later in the macro. If the next screen does not appear, the Macro logic fires an error.

Although there are a large number of valid XML elements, XML is not complicated. A screen is specified with a description, actions, and the next screens. When a macro is played and a screen matching the description appears, the actions are executed for that screen and the Macro logic monitors the host for any next screens specified.

Macro Syntax

The following details each valid macro element:

<HAScript>
	<screen>
		<comment>
		<description>
			<oia>
			<cursor>
			<numfields>
			<numinputfields>
			<string>
			<attrib>
			<customreco>
		<actions>
			<prompt>
			<input>
			<extract>
			<message>
			<trace>
			<xfer>
			<pause>
			<mouseclick>
			<boxselect>
			<commwait>
			<custom>
		<nextscreens>
			<nextscreen>
		<recolimit>

The following XML elements and their attributes are valid in the IBM Host On-Demand Macro XML namespace. This description of the elements is structured like an actual macro file. Note: the element and attribute values are not case sensitive. Attention: all characters in a macro must be UNICODE characters. Most text editors support this by default, because they use the ASCII character set, which is at the lower end of the UNICODE character set.


The < HAScript > element is the main enclosing element for the macro. All other elements at this level that are not HAScript are ignored by the parser.

Attributes:

Text Between Elements

Example

<HAScript name="Logon Macro" description="Logs me on"
	 author="btwebb" creationdate="12/29/1998"
	 promptall="true" pausetime="500" timeout="10000" > ... </HAScript>


<screen> element - The enclosing element for the screen.

Attributes

Text Between Elements

Example

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


<comment> element - The comment element for the screen. This can contain any valid unicode character.

Attributes

Text Between Elements

Example

<comment> ... </comment>


<description> element - The enclosing element for the description associated with the screen.

Attributes

Text Between Elements

Example

<description> ... </description>


<numfields> element - The total number of fields on the screen. This element is optional. The number of fields not used if not specified.

Attributes

Text Between Elements

Example

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


<numinputfields> element - The total number of input fields on the screen. This element is optional. The number of input fields is not used if not specified.

Attributes

Text Between Elements

Example

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


<oia> - specifies an OIA condition to match. This element is optional, default is to wait for inhibit status.

Attributes

Text Between Elements

Example

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


<string> element - describes the screen based on a string.

Attributes

Text Between Elements

Example

<string value="hello" row="1" col="1" optional="false" invertmatch="false" />
<string value="hello" row="1" col="1" erow="11" ecol="11"
	casesense="false" optional="false" invertmatch="false" />
<string value="hello" />


<cursor> element - describes the screen based on the position of the cursor.

Attributes

Text Between Elements

Example

<cursor row="1" col="1" optional="false" invertmatch="false" />


<attrib> element - describes the screen based on an attribute. This is an advanced feature and should only be used if needed. Usually all the other description elements are enough to describe a screen.

Attributes

Text Between Elements

 Example

<attrib value="0x01" row="1" col="1" plane="COLOR_PLANE" optional="false"
	invertmatch="false" />


<customreco> element - The Macro logic will call out to any custom recognition listeners for the custom element to have the listener do its own custom screen recognition logic.

Attributes

Text Between Elements

Example

<customreco id="id1" />


<actions> element - The enclosing element for the actions associated with the screen

Attributes

Text Between Elements

Example

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


<prompt> element - specifies a prompt to be handled for the screen.

Attributes

Text Between Elements

Example

<prompt name="ID" row="1" col="1" len="8" description="ID for Logon" 
default="btwebb" clearfield="true" encrypted="true" />


<extract> element - specifies an extract to be handled for the screen.

Attributes

Text Between Elements

Example

<extract name="Get Data" srow="1" scol="1" erow="11" ecol="11" />


<input> element - specifies keystrokes to be placed on the screen.

Attributes

Text Between Elements

Example

<input value="IBM[tab]is cool[enter]" row="1" col="1" movecursor="true"
	xlatehostkeys="true" />


<message> element - specifies a message to be sent to the user.

Attributes

Text Between Elements

Example

<message value="We are cool" title="Message from IBM" />


<trace> element - specifies a string to be sent to one of several trace facilities.

Attributes

Text Between Elements

Example

<trace value="hello" type="HODTRACE" />


<xfer> element - transfers a file to or from a host system.

Attributes

Text Between Elements

Example

<xfer direction="send" pcfile="c:\myfile.txt" hostfile="myfile text A0" />


<pause> element - causes the Macro bean to sleep for the given amount of milliseconds. This action is useful for pausing in between several file transfers.

Attributes

Text Between Elements

Example

<pause value="2000" />


<mouseclick> element - simulates a user mouse click on the Terminal bean. This essentially sets the cursor at a given row and column position.

Attributes

Text Between Elements

Example

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


<boxselect> element - used for either marking or unmarking the marking rectangle on the Terminal bean.

Attributes

Text Between Elements

Example

<boxselect srow="1" scol="1" erow="11" ecol="11" type="SELECT" />


<commwait> element - used for performing a communication status wait during a macro's execution.

Attributes

Text Between Elements

Example

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


<custom> element - enables the user to have an exit to Java code, see Javadoc for the MacroActionCustom class.

Attributes

Text Between Elements

Example

<custom id="custom1" args="IBM means world class computers n'all" />


<nextscreens> element - contains all the valid next screens to be recognized after the current screen's actions have been executed.

Attributes

Text Between Elements

Example

<nextscreens> ... </nextscreens>


<nextscreen> element - screen that forces a next screen. Multiple nextscreen elements are allowed. If a screen appears that is in the macro but is not a next screen, the macro will go into an error state. If the next screen refers to a screen element that doesn't exist, the Macro will have a parse error.

Attributes

Text Between Elements

Example

<nextscreen name="screen1" />


<recolimit> element - advanced use only. Used to enforce a limited amount of time a screen can be recognized in a row before it goes to the screen indicated in the goto attribute. This element is useful for screen looping where you know exactly how many times you'll see a given screen in a row. It also is a safeguard against infinite screen recognition.

Attributes

Text Between Elements

Example

<recolimit value="3" goto="endscreen" />


The Most Powerful Macro

This section gets its name because the following example demonstrates how all of the elements and their attributes can be used in a macro.

<HAScript

name="Logon Macro"
description="Logs me on"
author="btwebb"
creationdate="12/29/1998"
promptall="false"
pausetime="500"
timeout="10000" >
<screen name="Logon" entryscreen="true">
	<comment>
		The screen description and actions for this screen 
		are a little out of control, but they demonstrate
		how to use everything. Normally, a screen element 
		would not be so full. But then, this is the King of Macros!
	</comment>
	<description>
		<oia status="NOTINHIBITED" optional="false"
		invertmatch="false" />
		<string value="Please Logon" casesensitive="true"/>
		<cursor row="12" col="10"/>
		<numinputfields number="2" optional="false"
		invertmatch="false" />
		<numfields number="10" optional="false" invertmatch="false" />
		<string value="Welcome" row="1" col="1"
		optional="false" invertmatch="false"/>
		<string value="Enter ID" row="1" col="1" erow="11"
		ecol="11" casesense="false" optional="false"
		invertmatch="false" />
		<string value="USERID" />
		<attrib value="0x01" row="1" col="1"
		plane="COLOR_PLANE" optional="false" invertmatch="false" />
		<customreco id="logon" />
	</description>
	<actions promptall="true">
		<prompt name="ID" row="11" col="10" len="8"
		description="ID for Logon" default="btwebb" clearfield="true"
		encrypted="true" />
		<prompt name="Password" row="13" col="10" len="8"/>
		<extract name="Get Data" srow="1" scol="1" erow="11" ecol="11" />
		<message value="We are cool" title="Message from IBM" />
		<trace value="logging on" type="HODTRACE" />
		<custom id="logon" args="IBM means world class computers n'all" />
		<input value="[enter]" movecursor="true" xlatehostkeys="true"/>
	</actions>
	<nextscreens timeout="20000">
		<nextscreen name="Logon.Complete"/>
	</nextscreens>
</screen>
<screen name="Logon.Complete" exitscreen="true">
	<comment>
		This screen just checks to see if we're logged on OK then hits the ENTER key. 
		Because it is a stop screen we don't have to specify any nextscreens element.
	</comment>
	<description>
		<oia status="NOTINHIBITED" optional="false" invertmatch="false" />
		<string value="Logon Successful, hit ENTER to continue" casesensitive="true"/>
	</description>
	<actions>
		<input value="[enter]"/>
	</actions>
</screen>
<screen name="MessageRecevied" transient="true">
	<comment>
		This screen demonstrates the idea of a transient screen. 
		Say our host system can send us asynchronous messages 
		while we're logging on, we just want to clear them. 
		This screen handles this and is valid anytime a message screen appears. 
		No nextscreens needed here.
	</comment>
	<description>
		<oia status="NOTINHIBITED" optional="false" invertmatch="false" />
		<string value="Message received, hit CLEAR to continue"/>
	</description>
	<actions>
		<input value="[clear]"/>
		<xfer direction="send.txt" pcfile="c:\myfile.txt" 
		 pcfile="myfile text a0" />
		<pause value="2000" />
		<boxselect srow="2" scol="3" erow="2" ecol="30" />
		<mouseclick row="23" col="1" />
		<input value="logoff[enter]" />
		<commwait value="CONNECTION_READY" timeout="10000" />
		<message value="Success" title="Macro Message" />
	</actions>
</screen>
</HAScript>

Recolimit Demonstration

This macro demonstrates how to extract a list that exists on multiple screens using the recolimit and invertmatch attributes. The behavior of this macro is as follows:

  1. Assume we get to the ExtractScreen.Main screen (recolimit is 1).
  2. Data is extracted and PF8 is sent to page down.
  3. The ExtractScreen.Main is matched again (recolimit is 2), and so on.
  4. If recolimit becomes 25, meaning that ExtractScreen.Main was recognized 25 times, the actions for ExtractScreen.Main will not be executed the 25th time. Instead, the actions for ExtractScreen.Complete will be executed. The actions are not executed for ExtractScreen.Main to keep from extracting twice if the ExtractScreen.Complete screen is reached before the recolimit is reached.
  5. If ExtractScreen.Complete is matched before the recolimit reaches 25, then we'll just get all the data in the system.
<HAScript

name="Extracter Macro"
description="Gets me data from a list"
author="btwebb"
creationdate="12/29/1998"
promptall="false"
pausetime="500"
timeout="10000" >
<screen name="ExtractScreen.Main">
	<comment>
		We'll assume there would be other screens that log us on 
		 and get us to this point.
		This screen is the main extraction screen, 
		 and extracts data only if there is no blank
		line at the bottom of the screen indicating 
		 there isn't any more data (ala invertmatch="true").
		To be safe we'll apply a recolimit of 25. 
		This screen does an extract, then pages down with PF8.
	</comment>
	<description>
		<oia status="NOTINHIBITED" optional="false" invertmatch="false" />
		<string value="Data Screen"/>
		<string value="           " row="24" col="1" erow="24" ecol="11" invertmatch="true" />
	</description>
	<actions promptall="true">
		<extract name="Get Data" srow="2" scol="1" erow="24" ecol="80" />
		<input value="[pf8]"/>
	</actions>
	<nextscreens timeout="20000">
		<nextscreen name="ExtractScreen.Main"/>
		<nextscreen name="ExtractScreen.Complete"/>
	</nextscreens>
	<recolimit value="25" goto="ExtractScreen.Complete"/>
</screen>
<screen name="ExtractScreen.Complete">
	<comment>
		This screen is the final extraction screen, 
		 and extracts data and sends an exit command.

Note: It is only different from the main screen in that the blanks must be there.
		Assume there would be other screens to take care of logging off.
	</comment>
	<description>
		<oia status="NOTINHIBITED" optional="false"
 invertmatch="false" />
		<string value="Data Screen"/>
		<string value="           " row="24" col="1" erow="24" ecol="11"/>
	</description>
	<actions promptall="true">
		<extract name="Get Data" srow="2" scol="1" erow="24" ecol="80" />
		<input value="exit[enter]"/>
	</actions>
	<nextscreens timeout="20000">
		<nextscreen name="ExtractScreen.Complete"/>
	</nextscreens>
</screen>
</HAScript> 


[ Top of Page | Previous Page | Next Page | Table of Contents ]