A Host On-Demand macro is a XML script that allows a Host On-Demand client to interact automatically with a host application running on a terminal emulator session (a 3270 Display session, a 5250 Display session, a VT Display session, or a CICS Gateway session). A Host On-Demand macro is usually written to perform a specific task or set of tasks involving a single host application.

Compared to a human operator, a macro interacts with a host application more quickly and with a smaller risk of error. A macro does not require that the person who runs it be trained in operating the host application. A macro can in many instances run unattended. A macro can be used again and again. A macro can be copied and distributed to multiple users. And most importantly, a macro can serve as a part of a broader solution to a customer requirement that involves both host applications and workstation applications.

An unsophisticated user can create a basic macro for automating a tedious or time-consuming interaction with a host application. The user navigates the host application to the screen at which he or she wishes to start, selects the Record Macro icon, and performs a task using the host application. For each application screen that the user visits, Host On-Demand records an impression of the application screen and the user's input to the application screen. When the user plays back the recorded macro starting at the same application screen as before, Host On-Demand recognizes each host application screen based on the previously recorded impression and repeats the actions that the human operator previously performed.

A more sophisticated user can add to or improve a recorded macro using the Host Access Macro Editor (Macro Editor). This tool, which is available by clicking an icon on the session panel, provides a graphical user interface (consisting of input fields, text boxes, checkboxes, and so on) with which a user can modify or add features to each screen interaction with the host application. Besides allowing a user to edit and enhance the macro's screen recognition behavior and user input, the Macro Editor provides features that allow a user to add more intelligent behavior to the macro, such as choosing between alternate paths through an application, skipping a screen that should not be processed, or backing up to a previous screen. And there are more powerful capabilities including the ability to read and process data from the session screen, to notify the operator of status, to prompt the operator for an important decision, to download or upload files from the host, and to automate the printing of application screens.

The Macro Editor also provides programming features. A user with programming experience can add functionality to a Host On-Demand macro by creating and manipulating variables, using arithmetic and logical expressions, writing if-then-else conditions, chaining to another macro, calling Java methods stored in external Java libraries, launching native applications, and writing trace information.

The Code Editor, a text editor that is launched from the Macro Editor, allows the user to view and modify the XML elements that make up the macro script, and also to cut and paste text through the system clipboard.

This book contains macro code samples throughout. The chapter Sample macro code contains an example of a macro that reads entries from a sample CICS database and writes them into a Microsoft Excel spreadsheet.

The Macro Manager toolbar is a toolbar that contains icons for common macro operations. All of these icons can be used by macro developers, while at least one of the icons is also for users of macros (the Play macro icon). Figure 1 shows the Macro Manager toolbar. (For the purpose of illustration, this figure is inaccurate in one respect: it shows all the buttons on the toolbar enabled at the same time.)

To view the Macro Manager toolbar follow these steps:

1. Start a Host On-Demand client.
2. Start a terminal emulator session (3270 Display session, 5250 Display session, VT session, or CICS Gateway session).
3. Click View > Macro Manager

Depending on your company's configuration of the display session, you might notice that a few of the icons on the Macro Manager toolbar also appear on the main toolbar. This placement is for extra convenience and should not cause you any concern. The icons work the same no matter which toolbar they appear on.

To step through the process of recording and playing back a simple macro, see Recording and playing back a simple macro.

The Macro Editor (the full name is the Host Access Macro Editor) is a graphical user interface (with buttons, input fields, list boxes, and so on) for editing the parts of a macro. Figure 2 shows the Macro Editor.

You will probably use the Macro Editor for most of your macro development. It is more powerful (in terms of managing data more easily) than the Code Editor described in the next subsection, although it cannot do everything that the Code Editor can do.

Both the Macro Editor and the Code editor edit macros. Both tools read from and write to the same type of underlying macro source, an XML script. However, each tool is better for certain tasks.

The Macro Editor provides a graphical user interface that is powerful and user-friendly. It is the superior tool for creating and editing macros.

On the other hand, the Code Editor provides a text editor interface that allows you to edit directly the XML elements of which a macro is made. Figure 3 shows the Code Editor displaying a macro script.

To understand macro scripts you do not need to learn a great deal about XML, just the basics of the syntax. If your knowledge of XML syntax needs brushing up, you can learn more about it in XML syntax in the Host On-Demand macro language. However, almost all of what you need to know is covered in this subsection.

As you probably know already, an XML script consists of a collection of XML elements, some of which contain other XML elements, in much the same way that some HTML elements contain other HTML elements. However, unlike HTML, XML allows a program developer to define new XML elements that reflect the structure of the information that the developer wishes to store. The Host On-Demand macro language contains approximately 35 different types of XML elements for storing the information needed to describe a macro. This macro language is described at length in The macro language.

This book, when referring to an XML macro element, uses the element name enclosed in angle brackets. Examples: <HAScript> element, <screen> element.

<SampleElement attribute1="value1" attribute2="value2">
...
</SampleElement>

In the begin tag, the attributes are specified by using the attribute name (such as attribute1), followed by an equals sign (=), followed by an attribute value enclosed in quotation marks (such as "value1"). Any number of attributes can occur in the begin tag.

<SampleElement attribute1="value1" attribute2="value2"  />

Figure 10 shows a conceptual view of a sample macro script containing three <screen> elements.

The figure above shows an <HAScript> element (HAScript) that contains instances of the major types of subelements: an <import> element (Import), a <vars> element (Variables), and three <screen> elements (Screen1, Screen2, and Screen3).

All macro scripts are structured like this, except that most have more screens. If there were 50 screens in the above macro, then the diagram above would look much the same, except that after Screen3 there would be additional screens: Screen4, Screen5, and so on, up to Screen50. (However, the order in which the screens are stored does not necessarily represent the order in which the screens are executed when the macro is played.)

The <HAScript> element is the master element of a macro script. (HAScript stands for Host Access Script.) It encloses the entire macro and also contains, in its begin tag, attributes that contain information applicable to the entire macro, such as the macro's name. For an example of an <HAScript> element see Figure 12.

The <import> element is used to import Java classes and is optional. Importing Java classes is an advanced topic that is not discussed until Creating an imported type for a Java class.

The <vars> element is used to declare and initialize variables belonging to one of the standard data types (boolean, integer, double, string, or field). Using standard variables is an advanced topic that is not discussed until Variables and imported Java classes.

The <screen> element is used to define a macro screen. The <screen> element is the most important of the elements that occur inside the <HAScript>. As you can see in Figure 10 above, a macro script is composed mostly of <screen> elements (such as Screen1, Screen2, and Screen3 in the figure). Also, most of the other kinds of XML elements in a macro script occur somewhere inside a <screen> element.

For the purpose of getting you acquainted with the Macro Editor, this section consists of a very simple comparison between the Macro tab of the Macro Editor and the <HAScript> element described in the previous section.

The Macro Editor has four tabs: Macro, Screens, Links, and Variables. The first tab, the Macro tab, corresponds very closely to the <HAScript> element. In fact, the Macro tab is the graphical user interface for some of the information that is stored in the attributes of the begin tag of the <HAScript> element.

Therefore, as the <HAScript> element is the master element of a macro script and contains in its attributes information that applies to the entire macro (such as the macro name), similarly the Macro tab is the first tab of the Macro Editor and provides access to some of the same global information.

Figure 11 shows the Macro Editor with the Macro tab selected.

In the figure above you can see that the Macro tab has input fields for Macro Name, Description, and other information, along with several checkboxes. You should notice two fields:

• The Macro Name field contains the name that you assign to the macro. This is the same name that you will select when you want to edit the macro or run the macro. Macro names are case-sensitive. For example, ispf_usp is a different name than Ispf_usp, ispf_usP, ISPF_USP, and so on.
• The Use Variables and Arithmetic Expressions In Macro checkbox determines whether the Macro object uses the basic macro format or the advanced macro format for this macro. In the figure above this checkbox is not selected, indicating that the basic macro format will be used (see Choosing a macro format).

<HAScript
     name="ispf_ex1"
     description=" "
     timeout="60000"
     pausetime="300"
     promptall="true"
     author=""
     creationdate=""
     supressclearevents="false"
     usevars="false"
     ignorepauseforenhancedtn="false"
     delayifnotenhancedtn="0">

...

</HAScript>

An application screen is a meaningful arrangement of characters displayed on the Host On-Demand session window by a host application.

As you probably realize, you are already very familiar with the concept of an application screen. An example of an application screen is the ISPF Primary Option Menu, which is displayed in Figure 13. (This same application screen is displayed in Figure 5.)

In the figure above you can see that this application screen has menu selections displayed in a row across the top (Menu, Utilities, Compilers, Options, and so on), function key assignments displayed in a row across the bottom (F1=Help, F2=Split, and so on), a title near the top (ISPF Primary Option Menu), a list of options along the left side (0 through V), and an input field in which to type an option number or letter (Option ===>). When the user provides input, for example by typing a 3 (for Utilities) followed by the enter key, the ISPF application removes all these visible items from the session window and displays a different application screen.

Although the concept is not very intuitive at this point, there might be in the same macro several macro screens that refer to the same application screen. Because of the way macro screens are linked to one another, the macro runtime might visit the same application screen several times during macro playback, processing a different macro screen at each visit.

Also, one macro screen might refer to more than one application screen. When several application screens are similar to each other, a macro developer might build a macro screen that handles all of the similar application screens.

Nevertheless, each macro screen corresponds to some application screen. When you record a macro, the Macro object creates and stores a macro screen for each application screen that you visit during the course of the recording. If you visit the same application screen more than once, the Macro object creates and stores a macro screen for each visit. Similarly, when you play back a recorded macro, the macro runtime processes a single macro screen for each application screen that it visits during the course of the playback.

Figure 14 shows a conceptual view of a <screen> element:

The figure above shows a <screen> element (Screen1) that contains the three required subelements: a <description> element (Description), an <actions> element (Actions), and a <nextscreens> element (Valid Next Screens).

All <screen> elements are structured in this way, with these three subelements. (A fourth and optional type of subelement, the <recolimit> element, is discussed later in this book.)

The <screen> element is the master element of a macro screen. It contains all the other elements that belong to that particular macro screen, and it also contains, in its begin tag, attributes that contain information applicable to the macro screen as a whole, such as the macro screen's name.

The <description> element contains descriptors that enable the macro runtime to recognize that the <screen> element to which the <description> element belongs is associated with a particular application screen. The descriptors and the <description> element are described in Screen description and recognition.

The <actions> element contains various actions that the macro runtime performs on the application screen, such as reading data from the application screen or entering keystrokes. The actions and the <actions> element are described in Macro actions.

The <nextscreens> element (Valid Next Screens in Figure 14) contains a list of the screen names of all the <screen> elements that might validly occur after the current macro screen. The <nextscreens> element and the elements that it encloses are described in Screen Recognition, Part 2.

This section shows some of the ways in which the Screens tab of the Macro Editor is related to the XML <screen> element described in the previous section. Figure 15 shows the Macro Editor with the Screens tab selected:

In the figure above, notice that the Screens tab contains:

• A Screen Name listbox at the top of the tab.
• Three subordinate tabs, labeled General, Descriptions, and Actions.

Currently the General tab is selected.

In the Screen Name listbox at the top of the Screens tab, you click the name of the macro screen that you want to work on (such as Screen1), and the Macro Editor displays in the subtabs the information belonging to that macro screen. For example, in Figure 15 the listbox displays the macro screen name Screen1 and the subtabs display the information belonging to Screen1. If the user selected another macro screen name in the listbox, perhaps Screen10, then the Macro Editor would display in the subtabs the information belonging to macro screen Screen10.

In the Screen Name input field under the General tab, you type the name that you want to assign to the currently selected macro screen. A screen name such as Screenx, where x stands for some integer (for example, Screen1), is a temporary name that the Macro object gives to the macro screen when it creates the macro screen. You can retain this name, or you can replace it with a more descriptive name that is easier to remember. (When all your macro screens have names such as Screen3, Screen10, Screen24, and so on, it is difficult to remember which macro screen does what.)

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

   <screen name="Screen1" entryscreen="true" exitscreen="false" transient="false">
      <description>
         <oia status="NOTINHIBITED" optional="false" invertmatch="false" />
      </description>
      <actions>
         <mouseclick row="4" col="15" />
         <input value="3[enter]" row="0" col="0" movecursor="true"
                   xlatehostkeys="true" encrypted="false" />
      </actions>
      <nextscreens timeout="0" >
         <nextscreen name="Screen2" />
      </nextscreens>
   </screen>

You must choose the format that you want your macro to be stored in: either the basic macro format or the advanced macro format.

The basic macro format is the default format. It supports a basic level of function but it does not include support for expression evaluation, variables, or some other features supported by the advanced macro format. Nevertheless, you should choose the basic macro format initially unless you already know that you are going to use expressions and variables. You can easily switch your macro to the advanced macro format later on. (In contrast, if you start out with the advanced macro format it is much more difficult to switch your macro to the basic macro format.)

You must write strings and the two special characters single quote (') and backslash (\) differently in the macro depending on whether you have chosen the basic macro format or the advanced macro format. Also, some characters that are ordinary characters in the basic macro format are used as operators in the advanced macro format.

For input fields on all other tabs than those listed above, always use the rules for the basic macro format.

The following two sections describe these differing rules.

The boolean values true and false can be written with any combination of uppercase and lower case letters (such as True, TRUE, FALSE, falsE, and so on).

An example of a input field that requires a boolean value is the Entry Screen field on the General tab of the Screens tab. Enter true to set the condition to true or false to set the condition to false.

A string is any sequence of characters and can include leading, trailing, or intervening blank characters. Strings in some input fields must be represented differently depending on whether the macro has been set to use the basic macro format or the advanced macro format. See Representation of strings and special characters, treatment of operator characters.

'apple'
'User4'
'Total number of users'
'   This string has 3 leading blanks.'
'This string has 3 trailing blanks.   '

apple
User4
Total number of users
   This string has 3 leading blanks.
This string has 3 trailing blanks.   

A conditional expression can contain arithmetic expressions, variables, and calls to methods of imported Java classes.

If an item of data belongs to one standard data type (boolean, integer, double, or string) but the context requires a different standard data type, then when the data is evaluated (either when the Macro Editor saves the data or else when the macro runtime plays the macro) it is automatically converted to the standard data type required by the context, if possible.

The following subsections discuss the conversions that can occur for each standard data type.

As an example, this chapter uses a scenario from a macro recorded in a previous chapter, Recording and playing back a simple macro. This macro contains only two macro screens, Screen1 and Screen2.

The scenario begins at the point at which the macro runtime has performed all the actions in Screen1 and is ready to search for the next macro screen to be processed.

The list of valid next screens is just a list that can hold macro screen names. The macro runtime creates this list at the beginning of macro playback (before playing back the first macro screen), and discards this list after macro playback is complete. Initially the list is empty (except possibly for transient screens, which are described later in this chapter).

During macro playback, each time the macro runtime needs to determine the next macro screen to be processed, it performs the three steps 1(a), 1(b), and 1(c) using the list of valid next screens.

In stage 1 the macro runtime determines the next macro screen to be processed. As stated in the previous section, stage 1 includes three steps.

In step 1(a) the macro runtime collects the names of macro screens that can occur after the current macro screen, and adds these names to the list of valid next screens. There may be just one such screen on the list or several. In the example scenario, the macro runtime would look in the <nextscreens> element of Screen1, find one name (Screen2), and add that name to the list (see Table 9).

In step 1(b), the macro runtime periodically checks each macro screen on the list to determine whether it matches the application screen.

There is a time factor here. Because of an action that the macro runtime has just performed in the current macro screen (in Screen1, typing '3[enter]' as the last action of the <actions> element), the host application is in the process of changing the session window so that it displays the new application screen (the Utility Selection Panel) instead of the old application screen (ISPF Primary Option Menu). However, this change does not occur immediately or all at once. The change takes some hundreds of milliseconds and may require several packets of data from the host.

Therefore, during step 1(b), every time the OIA line or the session window's presentation space is updated, the macro runtime again checks the macro screen (or screens) named in the list of valid next screens to determine whether one of them matches the application screen in its current state.

Eventually the session window is updated to the extent that the macro runtime is able to match one of the macro screens on the list to the application screen.

In step 1(c), the macro runtime removes all the macro screen names from the list of valid next screens (except transient screens if any).

In stage 2, the macro runtime makes the selected macro screen (the one that matched the application screen in step 1(b)) the new current macro screen.

Finally, in stage 3, the macro runtime performs the actions in the <actions> element of Screen2.

At this point, if you are reading this book for the first time, you might want to skip the rest of this chapter and begin the next chapter. Later, if you have a question about how the macro runtime processes a macro screen, you can return to this chapter to learn more.

The rest of this chapter describes the same processing sequence as in the overview but provides more information about each step.

In this step the macro runtime places the names of candidate macro screens on the list of valid next screens.

In this step the macro runtime matches one of the macro screens named in the list of valid next screens to the current application screen.

This process is called screen recognition because the macro runtime recognizes one of the macro screens on the list as corresponding to the application screen that is currently displayed in the session window.

After screen recognition has succeeded, the macro runtime immediately begins its next task, which is cleaning up the list of valid next screens (step 1(c)).

This is a simple step. The macro runtime removes the names of all the candidate macro screens, whether recognized or not, from the list of valid next screens.

If the list contains the names of transient screens, those names remain on the list (see Transient screens).

Because the macro runtime executes actions much more quickly than a human user does, unforeseen problems can occur during macro playback that cause an action not to perform as expected, because of a dependency on a previous action.

To avoid this type of problem, the macro runtime by default inserts a delay of 150 milliseconds after every Input action or Prompt action in every macro screen, and a delay of 300 milliseconds after the last action of every macro screen (see Pause Between Actions (Macro tab)).

You should leave this feature enabled, although you can disable it if you want. You can change the delays from 150 milliseconds and 300 milliseconds to other values.

If you want to change the duration of the delay for a particular macro screen, you can do so (see Set Pause Time (General tab of the Screens tab)).

Also, for any particular action, you can increase the delay by adding a Pause action after the action (see Pause action (<pause> element)).

The Description tab on the Screens tab of the Macro Editor gives you access to the information stored inside the <description> element of a macro screen. Figure 20 shows a sample Description tab:

In the figure above, the Screens tab of the Macro Editor is selected. The name of the currently selected screen, Screen2, is displayed in the Screen Name field at the top of the Screens tab. Below the Screen Name field are the General, Description, and Actions subtabs. The Description tab is selected.

As you look at Description tab in the figure above, you can see that it has an upper area and a lower area.

The upper area contains controls that operate on a single descriptor element considered as a whole. In particular, the Descriptor listbox situated in the upper left corner of the Description tab contains the name of the currently selected descriptor. In the figure above, the currently selected descriptor is a Field Counts and OIA descriptor at the top of the list. (Descriptors do not have names. Field Counts and OIA is the type of the descriptor.)

The lower area of the Description tab displays the contents of the currently selected descriptor. Because the currently selected descriptor is a Fields Counts and OIA descriptor, the lower area of the Description tab presents the contents appropriate to that type of descriptor. If the user created and selected another type of descriptor, such as a String descriptor, then the lower area would present the contents appropriate to a String descriptor.

Caution: Although the Macro Editor presents the Fields Counts and OIA descriptor as a single descriptor containing three tests, in fact the macro language defines these three tests as three separate and independent descriptors. See Field Counts and OIA descriptor.

The lower area of the Description tab in Figure 20 also displays, for each of these three tests in the Field Counts and OIA descriptor, two more fields, labeled Option and Inverse Descriptor. You can ignore these two fields for now. They are described in the section Default combining method.

During macro recording the Macro object adds one or more descriptors to the new <description> element of each new macro screen that it creates.

The recorded descriptions work rather well for at least three reasons.

First, the three parts of the Field Counts and OIA descriptor can be applied unfailingly to every possible application screen. That is, every application screen has some number of fields (perhaps the number is 0), some number of input fields (perhaps 0), and an input inhibited indicator that is either set or cleared.

Second, the combination of a Number of Fields descriptor and a Number of Input Fields descriptor provides a pretty reliable description of an application screen, because application screens typically contain many fields. For example, the Utility Selection Panel shown in Figure 6 currently contains 80 fields of all types, 3 of which are input fields. The ISPF Primary Option Menu shown in Figure 5 currently contains 116 fields of all types, 3 of which are input fields. When application screens contain many fields, there is less chance of the macro runtime confusing two application screens with one another because each contains the same number of fields and the same number of input fields.

Third, and perhaps most important, during screen recognition the macro runtime compares the new application screen to a short list (usually a very short list) of macro screens called valid next screens (see Closer look at stage 1). Therefore a single macro screen need not be differentiated from every other macro screen in the macro, only from the other screens in the list of valid next screens. Frequently the list consists of a single macro screen.

Macro recording is a very useful feature because it quickly provides a framework for your macro. However, for some macro screens the recorded description might not be sufficient to allow the macro runtime to reliably distinguish one application screen from another similar application screen. In such cases you should improve the recorded description.

Often the most straightforward way to improve a recorded description is to add a String descriptor. For example, if the macro screen is for the Utility Selection Panel shown in Figure 6, then you might add a String descriptor specifying that the application screen contains the string 'Utility Selection Panel' somewhere in row 3. Of course you are not limited to using a String descriptor. Some situations might require that you use one or more of the other descriptors (such as a Cursor descriptor, Attribute descriptor, or Condition descriptor) to assure that the application screen is correctly recognized.

For each individual descriptor in the macro description, the macro runtime evaluates the descriptor and arrives at a boolean result of true or false.

For example, if the descriptor is a String descriptor, then the macro runtime looks in the application screen at the row and column that the descriptor specifies, and compares the string at that location with the string that the descriptor specifies. If the two strings match, then the macro runtime assigns a value of true to the String descriptor. If the two strings do not match then the macro assigns a value of false to the String descriptor.

Usually a macro screen contains more than one descriptor.

However, if a macro screen contains only one descriptor (and assuming that the descriptor does not have the Inverse Descriptor option set to true) then if the single descriptor is true the entire description is true, and the macro runtime recognizes the macro screen as a match for the application screen. In contrast, if the single descriptor is false, then the entire description is false, and the macro screen is not recognized.

If you have more than one descriptor in a <description> element, then you must use either the default combining method described in this section or the uselogic attribute described in The uselogic attribute.

The uselogic attribute of the <description> element allows you to define more complex logical relations among multiple descriptors than are available with the default combining method described in the previous section.

If you use the uselogic attribute, then the macro runtime ignores the Inverse Descriptor settings and the Optional settings in the individual descriptors.

You have to add the uselogic attribute to the <description> element manually using the the Code Editor. The Macro Editor does not provide a control for this.

<description uselogic="(1 and 2) or (!1 and 3)" />
   <oia status="NOTINHIBITED" optional="false" invertmatch="false"/>
   <string value="&apos;Foreground&apos; row="5" col="8"/>
   <cursor row="18" col="19" optional="false" invertmatch="false"/>
</description>

(1 and 2) or (!1 and 3)

Remember that if you use the uselogic attribute, then the macro runtime ignores the Inverse Descriptor settings and the Optional settings in the individual descriptors.

Each type of descriptor is stored as an individual XML element situated within the <description> element of one macro screen.

The macro runtime searches inside the entire rectangular area of text for the string you specify. If the macro runtime finds the string inside the rectangular area of text, then it evaluates the string descriptor as true. If not, then it evaluates the string descriptor as false.

The Cursor descriptor specifies a row and column location on the application screen, such as row 10 and column 50. For either the row value or the column value you can use an integer or any entity that evaluates to an integer (such as a variable, an arithmetic expression, or a call to an external Java method).

If the two locations are the same then the macro runtime evaluates this descriptor as true. Otherwise the macro runtime evaluates this descriptor as false.

When you are editing a Cursor descriptor and you want to specify the correct row and column values, you can use the Current button. The Current button is situated immediately to the right of the Row and Column fields in the Cursor descriptor window.

The attribute descriptor specifies a 3270 or 5250 attribute and a row and column location on the application window.

During screen recognition the macro runtime compares the specified attribute (such as 0x3) to the actual attribute at the row and column specified. If the attributes are the same, then the macro runtime evaluates the descriptor as true. Otherwise the macro runtime evaluates the descriptor as false.

This descriptor can be useful when you are trying to differentiate between two application screens that are very similar except for their attributes.

The Condition descriptor specifies a conditional expression that the macro runtime evaluates during screen recognition, such as $intNumVisits$ == 0. For more information on conditional expressions see Conditional and logical operators and expressions.

If the conditional expression evaluates to true then the macro runtime evaluates this descriptor as true. Otherwise the macro runtime evaluates this descriptor as false.

The Condition descriptor increases the flexibility and power of screen recognition by allowing the macro runtime to determine the next macro screen to be processed based on the value of one or more variables or on the result of a call to a Java method.

The Custom descriptor allows you to call custom description code.

To use a Custom descriptor you need the separate Host Access Toolkit product.

To create a Custom descriptor you must use the Code Editor to add an <customreco> element to the <description> element of the macro screen. For more information on this element see <customreco> element.

As you might remember, the macro runtime can go through the screen recognition process a number of times before matching a macro screen to an application screen (see Re-doing the evaluation). Therefore, if a <description> element contains one or more Variable update actions, then the macro runtime will perform the Variable update actions each time that it evaluates the <description> element.

<description>
   <oia status="NOTINHIBITED" optional="false" invertmatch="false" />
   <varupdate name="$boolUpdate$" value="true" />
   <attrib value="0x4" row="1" col="1" plane="COLOR_PLANE" optional="false"
               invertmatch="false" />
</description>

If you want the macro runtime to perform a Variable update action in a <description> element in some other sequence than first, you can change the order of execution by using the <description> element's uselogic attribute instead of the default combining rule (see The uselogic attribute).

In specifying the parameters of an action, remember that, in general, any context that accepts an immediate value of a particular standard data type also accepts any entity of the same data type. For example, if an input field accepts a string value, then it also accepts an expression that evaluates to a string, a value that converts to a string, a string variable, or a call to an imported method that returns a string (see Equivalents).

However, there are a few fields in which you cannot use variables (see Using the value that the variable holds).

The Actions tab on the Screens tab of the Macro Editor allows you to create and edit actions. When you create an action in the Actions tab, the Macro Editor inserts the new action into the <actions> element of the currently selected screen. Figure 27 shows a sample Actions tab:

In the figure above, the Screens tab of the Macro Editor is selected. The name of the currently selected screen, Screen1, is displayed in the Screen Name field at the top of the Screens tab. Below the Screen Name field are the General, Description, and Actions subtabs. The Actions tab is selected.

As you look at the Actions tab in the figure above, you can see that, like the Description tab, it has an upper area and a lower area.

The upper area contains controls that operate on a single action element considered as a whole. In particular, the Action listbox situated in the upper left corner of the Actions tab contains the name of the currently selected action. In the figure above, there is no currently selected action, because no action has been created yet.

The lower area of the Actions tab displays the contents of the currently selected action, if any. If the currently selected descriptor is an Input action, then the lower area of the Actions tab presents the contents appropriate to that type of action. If the user creates or selects another type of action, such as an Extract action, then the lower area presents the contents appropriate to an Extract action.

<new input action>
<new extract action>
<new prompt action>
<new message action>
<new pause action>
<new xfer action>
<new comm wait action>
<new trace action>
<new mouse click action>
<new box select action>
<new run program>
<new variable update action>
<new play macro action>
<new perform action>
<new conditional action>
<new print start action>
<new print extract action>
<new print end action>
<new sql query action>
<new file upload action>

Input action1(0,0)
<new input action>
<new extract action>
<new prompt action>
<new message action>
<new pause action>
<new xfer action>
<new comm wait action>
<new trace action>
<new mouse click action>
<new box select action>
<new run program>
<new variable update action>
<new play macro action>
<new perform action>
<new conditional action>
<new print start action>
<new print extract action>
<new print end action>
<new sql query action>
<new file upload action>

When the macro runtime processes this macro screen, it performs the actions in the same order in which they are listed in the Actions listbox. To change the order of the actual actions, click the Change Order button to the right of the Actions listbox.

The Box selection action draws a marking rectangle on the session window, simulating the action in which an actual user clicks on the session window, presses mouse button 1, and drags the mouse to create a marking rectangle.

The Comm wait action waits until the communication status of the session changes to some state that you have specified in the action. For example, you might create a Comm wait action to wait until the session was completely connected.

The Conditional action provides the functions of an if-statement or of an if-else statement.

The Extract action captures text from the session window and stores the text into a variable. This action is very useful and is the primary method that the Macro object provides for reading application data (short of using programming APIs from the toolkit).

If you have the IBM Host Access Toolkit product, then you can use the Extract action to read data from any of the available data planes. For more information see Using the Toolkit to capture data from any data plane.

The FileUpload action is a powerful and useful action that allows you to create, append data to, replace, or update a table in a host database. This action is a companion to the SQLQuery action, which allows you to send an SQL statement to a host database (see .

You can use the FileUpload action in any type of Host On-Demand session that supports macros (3270 Display, 5250 Display, VT Display, or CICS Gateway).

The database server to which you connect can be on a different host than the host running your emulator session.

The Input action sends a sequence of keystrokes to the session window. 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).

This action simulates keyboard input from an actual user.

The Message action displays a popup window that includes a title, a message, and an OK button. The macro runtime does not terminate the action until the user clicks OK.

The Mouse click action simulates a user mouse click on the session window. 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.

The Pause action waits for a specified number of milliseconds and then terminates.

More specifically, the macro runtime finds the <pause> element, reads the duration value, and waits for the specified number of milliseconds. Then the macro runtime goes on to perform the next item.

You should type the number of milliseconds in the Duration input field. The default is 10000 milliseconds (10 seconds).

The Perform action 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 action. However, the Perform action is useful in certain scenarios, for example, when you want to invoke a method that does not return a value.

The PlayMacro action launches another macro.

When the macro runtime performs a PlayMacro action, it terminates the current macro (the one in which the PlayMacro action occurs) and begins to process the specified macro screen of the target macro. This process is called chaining. The calling macro is said to "chain to" the target macro. There is no return to the calling macro.

You must specify in the PlayMacro action the name of the target macro and, optionally, the name of the macro screen in the target macro that you want the macro runtime to process first.

You can have the macro runtime transfer all of the variables with their contents from the calling macro to the target macro.

The Print actions allow you to print text from the session window of a 3270 Display session. You can print the entire application screen, or you can print a rectangular area of text from the application screen. You can use the same printer setup options and most of the same page setup options that are available for a 3270 Printer session.

You can use the Print actions only with a 3270 Display session.

The Print actions do not create a host print session. Rather, the Print actions print data that is displayed in the 3270 Display session window (screen print).

Although the Macro Editor presents Print Start, Print Extract, and Print End as separate types of action, in fact the Macro object stores all three using the <print> element.

The Prompt action provides a powerful way to send immediate user keyboard input into the 3270 or 5250 application or into a variable.

A typical use of this action, but by no means the only use, is to permit the user to provide a password. Many scenarios require that a macro log on to a host or start an application that requires a password for access. Because a password is sensitive data and also typically changes from time to time, you probably do not want to code the password as an immediate value into the macro.

With the Prompt action, you can display a message that prompts the user for a password and that lets the user type the password into the input field. After the user clicks OK, the macro runtime types the input into the session window at the row and column location that you specify. The input sequence can include action keys such as [enterreset], so that if the user types MyPassword[enterreset] the macro runtime not only can type the password into the password field but also can type the key that completes the logon or access action. (Or, you can put the action key into an Input action that immediately follows the Prompt action.)

The Run program action launches a native application and optionally waits for it to terminate. You can provide input parameters for the application and store the return code in a variable.

You can launch any application that can be run by the system runtime.

The SQLQuery action is a very useful and powerful action that allows you to send an SQL statement to a host database, retrieve any data resulting from the SQL statement, and then either write the data into a global variable, write the data into a file, or display the data. (A companion action, FileUpload, allows you to send a File Upload command to a host database. See

You can use the SQLQuery action in any type of Host On-Demand session that supports macros (3270 Display, 5250 Display, VT Display, or CICS Gateway).

The database server to which you connect can be on a different host than the host running your emulator session.

You can create an SQL statement manually, compose and test an SQL statement using the SQL Wizard, or import an SQL statement either from the current session or from a library of SQL statements.

The SQLQuery action supports only SQL statements of type Select. It does not support SQL statements of type Insert, Update, or Delete.

The Trace action sends a trace message to a trace destination that you specify, such as the Java console.

Use the Trace Text input field to specify the string that you want to send to the trace destination.

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

The value can be an arithmetic expression and can contain variables and calls to imported methods. 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.

boolVisitedThisScreen = true;
intVisitCount = intVisitCount + 1;
dblLength = 32.4;
strAddress ="123 Hampton Court";

The value that you provide must belong to the correct data type for the context or be convertible to that type (see Automatic data type conversion).

The Xfer action (pronounced "transfer action" or "file transfer action") transfers a file from the workstation to the host or from the host to the workstation.

Set Entry Screen to true if you want the macro screen to be considered as one of the first macro screens to be processed when the macro is played back. You might have only one macro screen that you mark as a entry screen, or you might have several.

When the macro playback begins, the macro runtime searches through the macro script and finds all the macro screens that are designated as entry screens. Then the macro runtime adds the names of these entry macro screens to the runtime list of valid next screens. Finally the macro runtime tries in the usual way to match one of the screens on the list to the current session window.

When the macro runtime has matched one of the entry macro screens to the session window, that macro screen becomes the first macro screen to be processed. Before performing the actions in the first macro screen, the macro runtime removes the names of the entry macro screens from the runtime list of valid next screens.

Setting Exit Screen to true for a macro screen causes the macro runtime to terminate the macro after it has performed the actions for that macro screen. That is, after the macro runtime performs the actions, and before going on to screen recognition, the macro runtime looks to see if the current macro screen has the exit screen indicator set to true. If so, then the macro runtime terminates the macro. (The macro runtime ignores the <nextscreens> element of an exit screen.)

Therefore you would set Exit Screen to true for a macro screen if you wanted the macro screen to be a termination point for the macro.

When the macro runtime prepares to play back a macro, at the point where the macro runtime adds the names of entry screens to the runtime list of valid next screens, the macro runtime also adds the names of all macro screens marked as transient screens (if any) to the end of the list.

The names of these transient screens remain on the runtime list of valid next screens throughout the entire macro playback. Whenever the macro runtime adds the names of new candidate macro screens (from the <nextscreens> element of the current macro screen) to the list, the macro runtime adds these new candidate names ahead of the names of the transient screens, so that the names of the transient screens are always at the end of the list.

Whenever the macro runtime performs screen recognition, it evaluates the macro screens of all the names on the list in the usual way. If the macro runtime does not find a match to the application screen among the candidate macro screens whose names are on the list, then the macro runtime goes on down the list trying to match one of the transient macro screens named on the list to the application screen.

If the macro runtime matches one of the transient macro screens to the current application screen, then the macro runtime does not remove any names from the list. Instead, the macro runtime performs the actions in the transient macro screen (which should clear the unexpected application screen) and then goes back to the screen recognition process that it was pursuing when the unexpected application screen occurred.

As you know, after the macro runtime has performed all the actions in the <actions> element of a macro screen, then the macro runtime attempts to match one of the screens on the list of valid next screens to the new application screen (see How the macro runtime processes a macro screen).

Sometimes, unforeseen circumstances make it impossible for the macro runtime to match any of the macro screens on the list of valid next screens to the application screen. For example, a user might type an input sequence that takes him to an application screen unforeseen by the macro developer. Or, a systems programmer might have changed the application screen so that it no longer matches the description in the <description> element of the corresponding macro screen.

When such a scenario occurs, the result is that the macro appears to hang while the macro runtime continually and unsuccessfully attempts to find a match.

The Timeout Between Screens checkbox and input field are located on the Macro tab and specify a timeout value for screen recognition. By default, if the checkbox is enabled, this value applies to each and every macro screen in the macro. However, you can change the value for a particular macro screen by using the Timeout field on the Links tab (see the next section).

Macro timed out: (Macro=ispf_ex2, Screen=screen_address_type)

To use the Timeout Between Screens field, select the checkbox and type a value for the number of milliseconds to wait before terminating the macro. By default the checkbox is checked and the timeout value is set to 60000 milliseconds (60 seconds).

The Timeout input field on the Links tab specifies a timeout value for screen recognition for a particular macro screen. If this value is non-0, then the macro runtime uses this value as a timeout value (in milliseconds) for screen recognition for this macro screen, instead of using the value set in the Timeout Between Screens field on the Macro tab.

If the timer expires before the macro runtime has completed screen recognition, then the macro runtime displays the message in Figure 47.

The macro runtime keeps a recognition count for every macro screen that includes a <recolimit> element. When macro playback begins the recognition count is 0 for all macro screens.

Recolimit reached, but goto screen not provided, macro terminating.

If you use the goto attribute, the macro runtime does not terminate the macro but instead starts processing the macro screen specified in the attribute.

Because the macro runtime executes actions much more quickly than a human user does, unforeseen problems can occur during macro playback that cause an action not to perform as expected, because of a dependency on a previous action.

One example is a keystroke that causes the application screen to change. If a subsequent action expects the application screen to have already changed, but in fact the application screen is still in the process of being updated, then the subsequent action can fail.

Timing-dependent errors between actions can occur in other situations, if the macro runtime performs each action immediately after the preceding action.

Notice that Pause Between Actions affects every macro screen. Therefore this one setting allows you avoid timing errors throughout the macro, without having to change each macro screen that might have a problem.

If you want a longer or shorter "pause between actions" for a particular macro screen, or if you have only a few macro screens in which a "pause between actions" is important, then you can use the Set Pause Time setting on the General tab of the Screens tab.

By default this checkbox is disabled.

If you enable this setting for a macro screen, then the macro runtime uses the specified number of milliseconds for the "pause between actions" for this particular macro screen.

For example, if for ScreenA you select the Set Pause Time checkbox and set the value to 500 milliseconds, then the macro runtime waits 250 milliseconds after each Input action and Prompt action in ScreenA except the last one, and waits 500 milliseconds after the last action in ScreenA..

When the macro runtime processes a macro screen with Set Pause Time enabled, it ignores the setting of the Pause Between Actions option on the macro tab, and uses only the value in the Set Pause Time setting.

If you need an additional pause after one particular action in a macro screen, you can add a Pause action after the action. The wait that you specify in the Pause action is in addition to any wait that occurs because of a Pause Between Actions or a Set Pause Time.

Suppose that you have a macro screen, ScreenB, with the following bug: the macro runtime starts processing the actions in ScreenB before the host has completely finished displaying the new application screen. Although this timing peculiarity might not pose a problem for you in most situations, suppose that in this instance the first action in ScreenB is an Extract action that causes the macro runtime to read data from rows 15 and 16 of the application screen. Unfortunately the macro runtime performs this action before the host has had time to write all the new data into rows 15–16.

In short, as a result of this timing problem the macro runtime has read rows 15 and 16 of the new application screen before the host could finish update them.

This process does not present problems for a human operator, for various reasons that are not important here.

However, this process does present problems for the macro runtime during screen recognition. Recall that during screen recognition the macro runtime tries to match the application screen to one of the valid next macro screens every time the screen is updated and every time an OIA event occurs (see Re-doing the evaluation). Therefore the macro runtime might find a match before the screen is completely updated. For example, a String descriptor might state that recognition occurs if row 3 of the application screen contains the characters "ISPF Primary Option Menu". When the host has updated row 3 to contain these characters, then the macro runtime determines that a match has occurred, regardless of whether the host has finished updating the remainder of the application screen.

Using variables requires that you use the advanced macro format for your macro (see Choosing a macro format). Therefore, if you want to add variables to a macro that is in the basic macro format, you must decide whether to convert the macro to the advanced macro format. If you have an old macro in the basic macro format that many users rely on and that works perfectly, you might want to leave the macro as it is.

However, remember that all recorded macros are recorded in the basic macro format. So, if you have recently recorded a macro and are beginning to develop it further, then you might simply not have gotten around to switching to the advanced macro format.

You are attempting to use an advanced macro feature. If you choose to continue,
your macro will automatically be converted to advanced macro format. Would you
like to continue?

The scope of every variable is global with respect to the macro in which the variable is created. That is, every variable in a macro is accessible from any macro screen in the macro. All that an action or a descriptor in a macro screen has to do to access the variable is just to use the variable name.

Because a variable belongs to the entire macro, and not to any one screen, it seems appropriate that there is a separate high-level tab for Variables. The Variables tab allows you to:

• Create a variable
• Remove a variable
• Import a Java class as a new variable type

To create a variable belonging to a standard data type, use the Variables tab in the Macro Editor. Figure 49 shows a sample Variables tab:

In the figure above, the Variables tab of the Macro Editor is selected. The name of the currently selected variable, $strUserName$, is displayed in the Variables listbox. Three other fields contain information that the macro runtime needs to create this variable: the Name input field, the Type listbox, and the Initial Value input field.

The Variables listbox contains the names of all the variables that have been created for this macro. It allows you to select a variable to edit or to remove, and it also contains a <new variable> entry for creating new variables.

Variable1($strUserName$)

You have probably noticed that the variable name $strUserName$ is enclosed in dollar signs ($). This is a requirement. You must enclose the variable name in dollar signs ($) wherever you use it in the macro.

The Name input field displays the name of the currently selected variable, $strUserName$. You can change the name of the variable by typing over the old name. Mostly you should use this field only for assigning a name to a newly created variable. Although you can come back later at any time and change the name of this variable (for example to $strUserFirstName$), remember that you might have already used the variable's old name elsewhere in the macro, in some action or descriptor. If you change the name here in the Variables tab, then you must also go back to every place in the macro where you have you used the variable and change the old variable name to the new variable name.

You can choose any variable name you like, although there are a few restrictions on the characters you can choose (see Variable names and type names). You do not have to choose names that begin with an abbreviated form of the data type (such as the str in the string variable $strUserName$), as this book does.

string
integer
double
boolean
field
java.util.Hashtable

The Remove button removes the currently selected variable.

The Import button and the Import popup window are discussed in Creating an imported type for a Java class.

During macro playback, when the macro runtime processes a call to a Java method, the macro runtime searches all the available Java library files and class files for the class to which the method belongs, until it finds the class.

Deploying a Java library or class consists of placing the library file or class file containing the class in a location where the macro runtime can find it during macro playback.

All other Java classes containing methods invoked by a macro script must be deployed by you to a location where the macro runtime can find them. Depending on the environment, you can deploy the Java classes as class files or as libraries containing Java classes.

For more information on deploying Java libraries and classes, see "Deploying customer-supplied Java archives and classes" in Planning, Installing, and Configuring Host On-Demand.

The PlayMacro action, in which one macro "chains to" another macro (a call without return), allows you to transfer all the variables and their values belonging to the calling macro to the target macro. The target macro has access both to its own variables and to the transferred variables (see PlayMacro action (<playmacro> element)).

A field variable is a type of string variable. It holds a string, just as a string variable does, and you can use it in any context in which a string variable is valid.

For more information, see Variable update action with a field variable.

The macro runtime assigns initial values to variables at the start of the macro playback, before processing any macro screen.

Every variable in a macro has an initial value, whether or not the variable is used in a parameter list. The initial value may be either a default initial value (see Table 22) or an initial value assigned by the macro writer.

A parameter list exists outside the macro to which it pertains. It is not stored in the macro itself, but rather is passed to the macro runtime when macro playback begins.

When the macro runtime prepares to play a macro, the macro runtime first initializes each variable in the macro to the initial value defined in the macro itself for that variable.

The macro runtime then looks for a parameter list. If a parameter list is provided, then the macro runtime processes each name-value pair in the parameter list, re-initializing each named variable to the value specified in the list.

The macro runtime then continues with macro playback in the usual way.

A parameter list initializes variables only in the macro that the end user launches with the parameter list. A parameter list does not initialize variables of the same name that occur in a subsequent macro that the original macro chains to. (For more information on chained-to macros see PlayMacro action (<playmacro> element).)

Do not confuse the above situation with the transferring of variables that can occur when one macro chains to another. If macro A chains to macro B, macro A can pass all its variables and their current values to B (see Transferring variables). Use this feature to pass values from the calling macro to the chained-to macro.

$importedVar.calculateRow()$

Also, you can use the Perform action to call a method when you do not need the return variable of the method or when the method has no return value (void) (see Perform action (<perform> element)).

When you add a method call (such as $prp.get('Group Name')$) to a macro script, the Macro Editor does not verify that a called method or constructor exists in the class to which the variable belongs. That check is done by the macro runtime when the call occurs.

The method must be a public method of the underlying Java class.

To prevent confusion between normal variables and HML variables, variable names beginning with HML are reserved. If you try to create a variable beginning with HML, Host On-Demand generates an error message.

The methods invoked with $HMLSystemUtil$ allow you to obtain information about applet, Java properties and OS environments.

$FormatNumberToString()$ is deprecated in favor of $HMLFormatUtil.numberToString()$. The former has the same input parameters and return type as the latter (see numberToString()).

$FormatStringToNumber()$ is deprecated in favor of $HMLFormatUtil.stringToNumber()$. The former has the same input parameters and return type as the latter (see stringToNumber()).

When Record Password is enabled (this is the default setting) and the end user types characters into a 3270 or 5250 non-display input field during macro recording, Host On-Demand records the input key sequence as an Input action and encrypts the input key sequence in the Input action using the Password option of the Input action.

For example, suppose that Record Password is enabled, that you are recording a macro, and that you type a logon password (such as "MyPassword") into a 3270 or 5250 non-display input field. Host On-Demand creates an Input action, encrypts the logon password, stores the encrypted password into the Input action, and writes the Input action into the macro script being recorded.

Encrypting the input key sequence in the Input action provides a degree of security, because a casual unauthorized person cannot discover the input key sequence by editing or viewing the recorded macro script. Host On-Demand does not decrypt an encrypted input key sequence in an Input action until Host On-Demand processes the Input action during macro playback. However, a clever foe who gains access to the macro script can still discover the input key sequence by editing the Input action to direct the input key sequence into a normal displayable field during macro playback (see Password).

The advantage of having the input key sequence recorded in an Input action is that during macro playback the macro runs automatically without the user having to intervene. However, if a required input sequence changes (for example, if a password expires and a different password must be used) then the Input action must be updated with the new input key sequence.

When Record Password is disabled, and the end user types an input key sequence into a 3270 or 5250 non-display input field during macro recording, Host On-Demand discards the input key sequence and creates a Prompt action in the recorded macro script instead of an Input action. The Prompt action contains information about the length of the input key sequence and the row and column location on the screen where the input key sequence is to be directed, but does not contain the input key sequence itself. Consequently, an unauthorized person viewing, editing, or even running the macro script cannot discover the input key sequence.

During macro playback, when Host On-Demand processes the Prompt action, it pops up a prompting window containing an input field and a message indicating that the end user should type some input. (The default message is Password, but after macro recording is complete you can edit the Prompt action to specify a different message.) When the end user types an input key sequence into the input field of the prompting window and clicks OK, then Host On-Demand closes the prompting window and types the same input key sequence into the 3270 or 5250 non-display field in the session window at the specified row and column location.

Thus, disabling Record Password provides greater security than enabling it, because when Record Password is disabled the input key sequence is not stored in the macro script, not even in encrypted form. Instead, the end user provides the input key sequence during macro playback, when Host On-Demand processes the Prompt action.

When Host On-Demand creates the Prompt action during macro recording, it turns on the Password Response option in the Prompt action. This option causes Host On-Demand, during macro playback, to use asterisks (*) to display the characters that appear in the input field of the prompting window when the user types the input key sequence (see Password Response).

A macro that interacts with more than one session can be stored in any of the locations that an ordinary macro can be stored.

A macro that interacts with more than one session is launched by a single session, just as an ordinary macro is launched. However, all the sessions that the macro interacts with must be active (connected) before the macro is launched (see Run-time requirements).

The various sessions that the macro interacts with can be of different types (3270 Display, 5250 Display, VT Display, or CICS Gateway) or all of the same type, and can be connected to different hosts or to the same host.

A Host ID field has been added to the macro descriptors and macro actions that support this feature. The value in the Host ID field identifies the active session to which the descriptor or action applies (see Specifying a Host ID).

When you build a macro screen that refers to a session other than the original session that launches the macro, there are at least two techniques that you can use.

The first technique is to make each macro screen refer to one and only one active session. That is, all the descriptors and all the actions within any one macro screen should refer to the same active session. This technique allows you great flexibility and makes it simple to write, debug, and maintain your macro screens.

For example, the first 10 macro screens of your macro could interact with the original session, the next 8 macro screens could interact with a second session, and the final 4 macro screens could interact with the original session again.

The Macro object uses this first technique in storing recorded material when you record a macro that interacts with more than one active session. Whenever you switch from one active session to another, the Macro object completes and stores the current macro screen and then creates a new macro screen to hold the descriptors and actions for the first application screen of the newly selected session (see One recorded macro screen refers to one session window).

Therefore, when you record a macro that refers to more than one session, the Macro object builds the macro using the first technique.

The second technique is to allow a macro screen to refer to more than one active session. Either the descriptors refer to two or more active sessions, or the actions do, or both. If the descriptors refer to two or more active sessions, then the macro runtime evaluates each descriptor with reference to the session window of the specified session. If the actions refer to two or more active sessions, then the macro runtime executes each action against the session window of the specified session.

The second technique requires users to edit the macro, with either the Macro Editor or the Code Editor, to add references to more than one session within one macro screen (see Referring to different sessions in the same macro screen).

This second technique is more flexible than the first technique and in some situations can be necessary. However, this second technique usually makes it somewhat more complicated to write, debug, and maintain your macro screens.

For clarity, this section describes in more detail the processing of descriptors and actions for multiple sessions during macro playback.

For the first requirement, whenever the end user launches a macro, the macro runtime, as part of the preparations for running the macro, scans the entire macro script for Host ID fields and compiles a list of sessions that the macro accesses. The macro runtime then verifies that each session in the list is started and connected. If one of the sessions is not started and connected, then the macro runtime displays an error message and terminates the macro playback.

The second requirement is just an extension of the ordinary requirement that the end user position the session that launches the macro at the application screen expected by the first macro screen of the macro. Just as the first macro screen of an ordinary macro expects to find the session window positioned at a particular application screen, so the first macro screen that interacts with a session other than the original session expects to find the session window of that session positioned at a particular application screen.

In the Macro Editor, a Host ID input field is displayed in the editing window of each descriptor or action that can refer to a session other than the original session that launches the macro (see the lists of descriptors and actions in Implementation). In the Code Editor, the hostid attribute is valid in the corresponding XML elements.

If, instead, you let the Host On-Demand client assign the session ID automatically, then the session ID can be different (for example, C) than the session ID that you use in the macro script (such as B), and if so then the Host ID value is also different (C:3270 Display instead of B:3270 Display). Consequently, when the end user launches the macro, the macro runtime can terminate the macro playback with an error because the macro contains a reference (B:3270 Display) to a session that is not active and connected.

This section describes issues involved in recording a macro that interacts with more than one session. Each of the following subsections deals with an issue.

When you want to use the second technique described earlier for building macro screens (see Two techniques for building macro screens), the technique of referring to more than one session in the descriptors or in the actions of the same macro screen, you must use the Macro Editor or the Code Editor to manually add the references to additional session or sessions.

For example, if you have recorded a macro screen that interacts with a 3270 Display session, and you want to add to that macro screen references to a 5250 Display session, then you must open the macro script with the Macro Editor or the Code Editor and then manually add the appropriate descriptors or actions to the 5250 Display session.

If you are using the Macro Editor, then use can use the Current button in descriptors to gather data from sessions other than the session from which the Macro Editor was launched (see Using automatic editing features with other sessions).

The Macro window of the Disable Functions does not have a separate option for enabling or disabling the recording of a macro that interacts with more than one session. Instead, this function is considered part of the Record Macro option.

Even though the Macro Editor window appears on top of the session window, you can still use the session window.

Drag the Macro Editor window to one side of the screen so that you can see the area on the session window that you want to work with. Then click on the session window to make it the current window. (The Macro Editor might still overlap part of the session window.)

In input fields that require a string, you must specify the string in the manner required by the format that you have selected for the macro, either the basic macro format or the advanced macro format (see Representation of strings and special characters, treatment of operator characters).

String -- Invalid expression -- Resetting to previous value.

In contrast, if you have selected the basic macro format, but you specify a string that is surrounded with single quotes, then you will not get an error message, but the Macro Editor will treat the single quotes as part of the string.

If you wish to edit this macro, then you can do so either with the Macro Editor or the Code Editor.

You can edit the XML text of a macro script directly with the Code Editor (see Code Editor).

You can cut and paste text between the Code Editor and the system clipboard. This is a very important feature, because it allows you to transfer text between the Code Editor and other XML editors or text editors.

Also, you cannot use comment brackets <!-- --> outside the <HAScript> element. If you do so then the Code Editor will discard those comment brackets and the surrounded text when it saves the script.

<message title="'Instructions'"  value="'Check the java console'" />

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

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

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

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

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.

invertmatch

Optional boolean. See Inverse Descriptor.

hostid

Optional string. See Specifying a session.

The <boxselection> element draws a marking rectangle on the session window, simulating the action in which a user clicks on the session window, holds down mouse button 1, and drags the mouse to create a marking rectangle (see Box selection action (<boxselection> element)).

srow

Required integer. The row coordinate of the starting corner of the marking rectangle.

scol

Required integer. The column coordinate of the starting corner of the marking rectangle.

erow

Required integer. The row coordinate of the ending corner of the marking rectangle.

ecol

Required integer. The column coordinate of the ending corner of the marking rectangle.

type

Optional (default SELECT). Specify SELECT to draw a marking rectangle or DESELECT to remove a marking rectangle.

hostid

Optional string. See Specifying a session.

None.

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.

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.

hostid

Optional string. See Specifying a session.

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.

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.

invertmatch

Optional boolean. See Inverse Descriptor.

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

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

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

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

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.

invertmatch

Optional boolean. See Inverse Descriptor.

hostid

Optional string. See Specifying a session.

The <custom> element allows you to invoke a custom Java program from inside the <actions> element of a macro screen. However, you must use the separate Host Access Toolkit product.

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 out to custom description code. To use the <customreco> element you must have the separate Host Access Toolkit product.

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

id

Required string. The identifier that you have assigned to this custom description.

optional

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

invertmatch

Optional boolean. See Inverse Descriptor.

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.

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

None.

This <extract> action captures data from the session window (see Extract action (<extract> element)).

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. This name is useful only if you are using the IBM Host Access Toolkit product.

planetype

Required. The plane from which the data is to be extracted. To access a data plane other than the TEXT_PLANE you need the IBM Host Access Toolkit product (see Using the Toolkit to capture data from any data plane). 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 session window.

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

hostid

Optional string. See Specifying a session.

The <fileupload> element creates, replaces, appends data to, or updates a table in a host database (see FileUpload action (<fileupload> element)).

url

Required string. The database URL for the database server to which the file upload command 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).

filename

Required string. The complete path and name of the local file containing the data to be added to the table in the host database (see File Name and File Type).

filetype

Required integer. The type of the local file containing the data to be added to the table in the host database (see File Name and File Type). Valid values are:

• 0 - ASCII text (*.txt)
• 1 - Comma Separated Values (*.csv)
• 2 - Lotus 1-2-3 (*.wk1)
• 3 - Microsoft Excel BIFF3 (*.xls)
• 4 - Microsoft Excel BIFF4 (*.xls)
• 5 - XML (*.xml)

uploadtype

Required string. The type of file upload operation to perform. Valid values are:

• append - Append rows to an existing table in the host database (see Append).
• create - Create a new table in the host database (see Create). When you use this upload type, you must also specify the following attribute:
  • fielddesctable
• replace - Replace the contents of an existing table in the host database (see Replace).
• update - Selectively update part of an existing table (see Update). When you use this upload type, you must also specify the following attribute:
  • keycolumns

fielddesctable

String (required when uploadtype is create). The name of the table in the host database from which the database server is to read the column names and column widths for the new table (see Create).

keycolumns

String (required when uploadtype is update). The name or names of the column or columns that you want to update (see Update).

The <filexfer> action transfers a file from the workstation to the host or from the host to the workstation (see Extract action (<extract> element)).

direction

Required. Use send to transfer a file from the workstation to the host, or receive to transfer a file from the host to the workstation.

pcfile

Required string. The name of the file on the workstation (see Basic parameters).

hostfile

Required string. The name of the file on the host (see Basic parameters).

clear

Required boolean. Set to true for a 3270 Display session or false for a 5250 Display session (see Advanced parameters).

timeout

Required integer. A timeout value in milliseconds (the default value is 10000 milliseconds). The macro runtime terminates the transfer if this timeout expires before the file is transferred.

options

Optional string. Any additional parameters required by your host system.

pccodepage

Optional integer, such as 437. The local code page to use in mapping characters from the workstation's character set to the host's character set and vice versa. The default value is the code page specified in the session configuration.

hostorientation

Optional. For BIDI sessions only (Arabic and Hebrew). Specifies whether text orientation for the host file is right-to-left or left-to-right.

pcorientation

Optional. For BIDI sessions only (Arabic and Hebrew). Specifies whether text orientation for the local file is right-to-left or left-to-right..

pcfiletype

Optional. For BIDI sessions only (Arabic and Hebrew). Specifies whether the local file type is visual or implicit.

lamalefexpansion

Optional boolean. For BIDI sessions only (Arabic only). Specifies whether Lam-Alef expansion is on.

lamalefcompression

Optional boolean. For BIDI sessions only (Arabic only). Specifies whether Lam-Alef compression is on.

hostid

Optional string. See Specifying a session.

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

name

Required. The name of the macro. Macro names are case-sensitive!

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 Choosing a 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 ignorepauseoverride 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).

blockTerminalInput

Optional. When the value of this attribute is true, keyboard inputs and mouse clicks are ignored while the macro is playing. The events are discarded. There is no indication to the user that input is blocked unless you create a Message action to indicate this.

ignorepausetimeforenhancedtn

The ability to ignore the macro pausetime attribute when running in a contention-resolution environment is now available. A new attribute, “ignorepausetimeforenhancedtn”, has been added to the <HAScript> macro element. This attribute allows you to ignore both the pausetime attribute in <HAScript> and the pause attribute in <screen>. Possible values for this attribute include:

True: Both the pausetime attribute in <HAScript> and the pause attribute in <screen> are ignored. No pause occurs after input/prompt actions or between screens. This is the default value.

False: The pausetime attribute in <HAScript> and the pause attribute in <screen> are not ignored.

Note that ignorepausetimeforenhancedtn has no effect when running in a non-contention-resolution environment. That is, even if ignorepausetimeforenhancedtn is true, the pausetime attribute in <HAScript> and the pause attribute in <screen> will not be ignored if running in a non-contention-resolution environment.

See the "Macro Programming Guide" for information on ignorepauseforenhancedtn and delayifnotenhancedtn, two other attributes that affect the way that macros are executed in a contention-resolution environment. To view or modify the value for ignorepausetimeforenhancedtn, use the Code Editor of the Macro Editor.

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

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

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.

None.

The <input> element sends a sequence of keystrokes to the session window. 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)).

value

Required string. The sequence of keys to be sent to the session window (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 Code Editor to encrypt the sequence of keys contained in the value attribute when the Code Editor is closed (see Password).

hostid

Optional string. See Specifying a session.

The <message> element displays a popup window that includes a title, a message, and an OK button. The macro runtime waits until the user clicks OK before going on to the next action (see Message action (<message> element)).

title

Optional string (the default is the macro name). A string to be displayed in the caption bar of the popup window.

value

Required string. The message to be displayed in the popup window.

The <mouseclick> element simulates a mouse click on the session window 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)).

row

Required integer. The row of the row and column location on the session window where the mouse click occurs.

col

Required integer. The column of the row and column location on the session window where the mouse click occurs.

hostid

Optional string. See Specifying a session.

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.

name

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

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

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 <numfields> element is a descriptor that states the number of 3270 or 5250 fields of all types that exist in the session window (see Number of Fields descriptor (<numfields> element)).

number

Required integer. The number of fields in the session window.

optional

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

invertmatch

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

hostid

Optional string. See Specifying a session.

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

number

Required integer. The number of fields in the session window.

optional

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

invertmatch

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

hostid

Optional string. See Specifying a session.

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

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.

invertmatch

Optional boolean. See Inverse Descriptor.

hostid

Optional string. See Specifying a session.

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

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

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

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.

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

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). Macro names are case-sensitive!

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 <print> element provides printing functions. Three primary print actions (start, extract, and end) are specified through the action attribute (see Print actions (<print> element)).

action

Required. The print action to be performed. Must be one of the following: start, extract, end.

• start:

  The macro runtime instantiates a print bean object for the current macro using the Printer Setup options and Page Setup options that you specify (see Print Start).

  Because of the great number of printer setup options and page setup options, and because changing one option might require several other options to be adjusted, you should not use the macro language to specify printer setup options and page setup options. Instead, use the Macro Editor to create a Print start action and use the Printer Setup and Page Setup windows to specify these options (see Printer Setup and Page Setup).

• extract:

  The macro runtime copies the text from a rectangular area of the session window that you specify and sends the text to the current print bean (see Print Extract).

• end:

  The macro runtime terminates the print bean if one exists (see Print End).

srow

Required integer when action is extract. The row of the first pair of row and column coordinates for the rectangular area of text to be printed.

scol

Required integer when action is extract. The column of the first pair of row and column coordinates for the rectangular area of text to be printed.

erow

Required integer when action is extract. The row of the second pair of row and column coordinates for the rectangular area of text to be printed.

ecol

Required integer when action is extract. The column of the second pair of row and column coordinates for the rectangular area of text to be printed.

assigntovar

Optional variable. Specifies the name of a variable to contain the return code from the print action.

hostid

Optional string. This attribute is available only when the action is extract. See Specifying a session.

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 session window (see Prompt action (<prompt> element)).

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 session window at which you want the macro runtime to start typing the input from the user.

col

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

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 session window (see Default Response).

clearfield

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

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

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.

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 <runprogram> element launches a native application and optionally waits for it to terminate. You can provide input parameters for the application and store the return code into a variable (see Run program action (<runprogram> element)).

exe

Required string. The path and name of the native application (see Launching the native application).

param

Optional string. Any arguments that should be specified when the native application is launched.

wait

Optional boolean. Setting this attribute to true causes the macro runtime to wait until the native application terminates.

assignexitvalue

Optional variable. The name of a variable into which the return value from native application should be stored.

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

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

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

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 global variable $HMLSQLUtil$. You can retrieve the data by calling methods on the variable (see Storing the data into a global variable ($HMLSQLUtil$)).
• 1 - The data is written into a file (seeWriting the data into a file ). When you use this output type, you must also specify the following attributes:
  • outfilename
  • outfiletype
  • overwrite
  • inbrowser
• 2 - The data is displayed on the workstation monitor (see Displaying the data). When you use this output type, you must also specify the following attribute:
  • holdondisplay

outfilename

String (required when outputtype is 1). The complete path and name of the output file (see Writing the data into a file).

outfiletype

Integer (required when outputtype is 1). The type of the output file (see Writing the data into a file). Valid values are:

• 0 - ASCII text (*.txt)
• 1 - Comma Separated Values (*.csv)
• 2 - Lotus 1-2-3 (*.wk1)
• 3 - Microsoft Excel BIFF3 (*.xls)
• 4 - Microsoft Excel BIFF4 (*.xls)
• 5 - XML (*.xml)
• 6 - HTML (*.html)

overwrite

Boolean (required when outputtype is 1). Whether to overwrite the file or append to it (see Writing the data into a file).

• Setting this attribute to true causes the specified file, if it exists, to be overwritten with the data. If the file does not exist then it is created.
• Setting this attribute to false causes data to be appended to the specified file, if it exists. If the file does not exist then it is created.

inbrowser

Boolean (required when outputtype is 1). Setting this attribute to true causes the macro runtime, after writing the data into the specified file, to display the file's contents in the default browser (see Writing the data into a file).

holdondisplay

Boolean (required when outputtype is 2). Setting this attribute to true causes the macro runtime, after displaying the data, to wait for a response from the end user before starting to process the next macro action (see Displaying the data).

mlprops

Optional string. This attribute contains the file settings when outfiletype is 5 (XML) or 6 (HTML). The format of this attribute is:

mlprops="key1@@value1
@@key2@@value2@@key3@@value3"

where key1, key2, key3, and so on are the names of HTML or XML settings, and where value1, value2, value3, and so on are the values of the HTML or XML settings. Although you can use the Code Editor to modify the settings of this attribute manually, IBM recommends that you modify these settings by changing the corresponding settings in the SQL Wizard and saving the values to the Macro Editor (see Using the SQL Wizard).

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

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

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.

invertmatch

Optional boolean. See Inverse Descriptor.

hostid

Optional string. See Specifying a session.

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

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 Java console.

value

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

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.

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

None.

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

name

Required. The name of the variable.

value

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

NOTE: This sample requires Microsoft Excel or IBM DB2.

This sample macro reads transaction records from the CICS transaction amnu, which is a very small sample database, and writes the records into an Excel spreadsheet or IBM DB2.

<install>\HOD\xx\doc\macro\samples\amnu