Advanced Macro Editor

The Advanced Macro Editor (AME) gives you the ability to set macro and screen-level attributes, edit screen descriptions; and add actions, links (next screen connections), and variables.

The basic Macro Editor can be opened by right-clicking on the macro and selecting Open With -> Macro Editor. The Advanced Macro Editor can then be opened from the Macro Editor Overview page. Prompts and Extracts can also still be edited from the Macro Editor.

If you open a macro with the Macro Editor, instead of with the VME, then the Macro Editor becomes the default editor for that macro (only that macro).

Note:
Support for the Macro Editor and the Advanced Macro Editor is deprecated in HCL ZIETrans V1.0. While support continues for now, HCL reserves the right to remove these capabilities in a subsequent release of the product. This support is replaced by the Visual Macro Editor.

Using the editor

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

Figure 60. The Advanced Macro Editor
The Advanced Macro Editor

Notes:
  1. The AME is only aware of the <HAScript> element and its contents. This means any prompts or extracts you add or edit using the AME must be manually updated in the HCL ZIETrans <prompts> and <extracts> elements. This is important because a mismatch will cause Integration Objects to fail to run the macro properly, or will cause the macro to behave incorrectly when played with a Perform macro transaction or Play macro action. To minimize problems, we suggest that you use the HCL ZIETrans Macro Editor to define prompts and extracts, and use the AME for advanced logic within the macro as needed. See Adapting Host On-Demand macros for use in ZIETrans for more details on the HCL ZIETrans <prompts> and <extracts> elements.
  2. The AME is not synchronized with the HCL ZIETrans Macro Editor. This means that when you make a change in the AME, it will not be reflected immediately in, for example, the source view. However, when you save and exit one editor, the changes will be reflected in the other.

Macro tab

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

The AME 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 description), similarly the Macro tab is the first tab of the AME and provides access to some of the same global information.

Figure 61 shows the AME with the Macro tab selected.

Figure 61. Macro tab of the AME
The Macro tab of the Advanced Macro Editor

In Figure 61, the Macro tab has input fields for the macro description and other information, along with several check boxes. Also notice the following:

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, macro_1 is a different name than Macro_1, MACRO_1, and so on.

The Use Variables and Arithmetic Expressions In Macro check box determines whether the macro object uses the basic macro format or the advanced macro format for this macro. In the figure above this check box is not selected, indicating that the basic macro format will be used (see Basic and advanced macro format).

Figure 62 shows a sample <HAScript> element that contains the same information as is shown on the Macro tab in Figure 61, as well as some additional information. In the source view, a <HAScript> element is written on a single line; here the element is written on multiple lines so that you can see the attributes.

Figure 62. A sample <HAScript> element
<HAScript
     name="macro_1"
     description=" "
     timeout="60000"
     pausetime="300"
     promptall="true"
     author=""
     creationdate=""
     supressclearevents="false"
     usevars="false"
     ignorepauseforenhancedtn="false"
     delayifnotenhancedtn="0">

...

</HAScript>
In the <HAScript> element in Figure 62 there is an attribute corresponding to each input field of the Macro tab shown in Figure 61. For example, the usevars attribute in the <HAScript> element (usevars="false") corresponds to the Use Variables and Arithmetic Expressions check box on the Macro tab. Figure 62 has additional attributes that are not displayed in Figure 61.

Screens tab

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

Figure 63. Screens tab
The Screens tab of the Advanced Macro Editor
Notice that the Screens tab in Figure 63

contains:

Currently, the General tab is selected.

Notice that there are two Screen Name fields on the Screens tab:

In the Screen Name list box 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 AME displays in the subtabs the information belonging to that macro screen. For example, in Figure 63 the list box 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 list box, perhaps Screen10, then the AME 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 default 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.)

Notice that the subtabs General, Description, and Actions on the Screens tab correspond to the main parts of the XML <screen> element described in the previous section. Specifically:

But what about the <nextscreens> subelement? For usability reasons, the information belonging to the <nextscreens> element is presented in a higher-level tab, the Links tab. You can see the Links tab immediately to the right of the Screens tab in Figure 63.

Figure 64 shows the XML begin tag and end tag of a sample <screen> element named Screen1:

Figure 64. Begin tag and end tag of a <screen> element
   <screen name="Screen1" entryscreen="true" exitscreen="false" transient="false">
   ...
   </screen>

In Figure 64, the ellipsis (...) is not part of the XML text, but indicates that the required elements contained inside the <screen> element have been omitted for simplicity. Notice that the attributes in the begin tag correspond to fields on the General tab in Figure 63. For example, the name attribute (name="Screen1" ) corresponds to the Screen Name input field on the General tab, and the entryscreen attribute (entryscreen="true") corresponds to the Entry Screen list box on the General tab.

Figure 65 shows the XML text for the entire <screen> element including the enclosed elements:

Figure 65. Sample XML <screen> element
   <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>

In Figure 65, notice that the <screen> element contains the required <description>, <actions>, and <nextscreens> elements.

By default the Set Recognition limit check box is cleared and the input field is disabled. If you select the check box, then the macro editor sets the default value of the Screens Before Error input field to 100. You can set the value to a larger or smaller quantity. For more information, see Recognition limit.

Description tab

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

Figure 66. Description tab
Description tab of the Macro Editor

In Figure 66, the Screens tab of the AME 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 the 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 list box 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 you 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.

Looking more closely at the lower area of the Description tab in Figure 66 , you can see that the Field Counts and OIA descriptor contains three tests of identity:

The macro runtime will apply these three tests of identity when it tries to match this macro screen to an application screen.

Note:
Although the AME 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 66 also displays, for each of these three tests in the Field Counts and OIA descriptor, a field labeled Optional. You can ignore this field for now. The Number of Fields and Number of Input Fields descriptors also have a field labeled Inverse Descriptor. You can ignore this field for now as well. These fields are described in the section Default combining method.

Creating a new descriptor

Looking again at the Descriptor list box in Figure 66 , notice that only the first entry is an actual descriptor. The remaining selections, which are all enclosed in angle brackets and all begin with the word new, are for creating new descriptors. Following is the list from Figure 66:

Figure 67. Contents of the Descriptor list box with one actual descriptor
Fields Counts and OIA
<new string descriptor>
<new cursor descriptor>
<new attribute descriptor>
<new condition descriptor>
<new variable update>

For example, if you clicked <new string descriptor>, the Macro object would create a new String descriptor and place it at the start of the list. The lower area of the Description tab would allow you to fill out the various fields that belong to a String descriptor (such as a row and column location and a character string). The Descriptor list box would then look like this:

Figure 68. Contents of the Descriptor list box with two actual descriptors
String descriptor(3, 29)
Fields Counts and OIA
<new string descriptor>
<new cursor descriptor>
<new attribute descriptor>
<new condition descriptor>
<new variable update>

In Figure 68, the currently selected descriptor is now the String descriptor at the top of the list (the 3,29 stands for row 3, column 29). The Field Counts and OIA descriptor is now second on the list.

For information on how the macro runtime handles multiple descriptors, as in Figure 68, see Evaluation of descriptors.

Field Counts and OIA descriptor

The Field Counts and OIA descriptor is required and must be unique. That is, every Description tab must contain one and only one Field Counts and OIA descriptor.

This should not cause you any trouble in practice, for the following reasons:

How three separate and independent descriptors are presented as one

The AME presents the Field Counts and OIA descriptor as one descriptor (see Figure 66). However, in fact each of the three parts of the Field Counts and OIA descriptor on the Description tab corresponds to a separate and independent descriptor in the underlying XML macro language. Specifically:

Table 20 lists these three types of descriptors and shows how many of each can occur within a <description> element:

Table 20. Three types of <description> element descriptors
Type of descriptor: Number of this type of descriptor allowed per macro screen (that is, per <description> element):
<oia> 1 (required)
<numfields> 1 (optional)
<numinputfields> 1 (optional)

As Table 20 shows, only one of each type of these descriptors can occur in a <description> element. The <oia> descriptor is required, but the <numfields> descriptor and the <numinputfields> descriptor are optional. The macro editor enforces these rules.

For example, look at a Field Counts and OIA descriptor first as it appears on the Description tab of the AME and then in the source view. Figure 66 shows a Field Counts and OIA descriptor on the Description tab. The settings of the three parts of the Field Counts and OIA descriptor are set as follows:

Number of Fields:  80
Number of Input fields:  3
Wait for OIA to Become Uninhibited:  true

But if you look at the corresponding <description> element in the source view, you see the following:

Figure 69. A <description> element with three descriptors
<description>
   <oia status="NOTINHIBITED" optional="false" invertmatch="false" />
   <numfields number="80" optional="false" invertmatch="false" />
   <numinputfields number="3" optional="false" invertmatch="false" />
</description>

The XML code fragment in Figure 69 shows that the <description> element contains three separate and independent descriptors, each corresponding to one of the three parts of the Field Counts and OIA descriptor.

Suppose that you change the Field Counts and OIA descriptor settings to be as follows:

Number of Fields:  (blank)
Number of Input fields:  (blank)
Wait for OIA to Become Uninhibited:  true

Setting the first two fields to blank tells the AME that these items are not to be included in the script. If you look again at the corresponding <description> element in the source view you now see:

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

The XML code fragment above shows that the <description> element now contains only one descriptor, an <oia> descriptor corresponding to the Wait for OIA to Become Uninhibited setting in the Field Counts and OIA descriptor.

Wait for OIA to Become Uninhibited descriptor

Table 21 shows:

Table 21. Valid settings for the descriptor Wait for OIA to Become Uninhibited
Setting on the Description tab: Value of the status attribute in the <oia> element: Meaning:
true NOTINHIBITED If the input inhibited indicator in the host terminal is cleared (that is, input is not inhibited) then the macro runtime evaluates the descriptor as true. Otherwise the macro runtime evaluates the descriptor as false.
false DONTCARE The macro runtime always evaluates the descriptor as true.
<Expression> 'NOTINHIBITED', 'DONTCARE', or any expression that evaluates to one of these strings. The macro runtime evaluates the expression and then interprets the resulting string.
Counting fields in the host terminal during macro development

If you want to view the Number of Fields field and the Number of Input Fields field, you can view the values and set the descriptors automatically to the values on the current screen.

To use this feature follow these steps:

  1. Edit the macro in the host terminal. You can also use this feature while recording a macro.
  2. In the host terminal, go to the application screen corresponding to the macro screen that you are working on. The values are always based on the screen shown in the host terminal.
  3. In the tree view on the left, right-click the screen name and select Edit to bring up the Define Screen Recognition Criteria page.
  4. The macro editor displays the total number of fields, the number of input fields, and the cursor position in the current application screen. Check the boxes for the criteria you want to use to recognize this screen.
  5. To set the Number of Fields field and the Number of Input Fields field to the correct values, you can use the Refresh button beside each input field to count the fields in the application screen for you.
  6. Click Finish.
Treatment during screen recognition

During screen recognition, when the macro runtime evaluates individual descriptors and combines the boolean results, the macro runtime treats the <oia> descriptor, the <numfields> descriptor (if it is present), and the <numinputfields> descriptor (if it is present) each as a separate and independent descriptor, one like any other descriptor.

For more information about evaluating multiple descriptors see Evaluation of descriptors

The '*' string in a new String descriptor

When you create a new String descriptor the AME places the string '*' into the String input field as an initial, default value. Just erase this initial string and fill in the string that you want. The asterisk (*) does not mean anything or have any function. The initial string could say 'Default string value' and have the same effect.

Actions tab

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

Figure 70. Actions tab
Actions tab of the Macro Editor

In Figure 70, the Screens tab of the AME 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.

Like the Description tab, the Actions tab 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 Actions list box 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 action 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.

Creating a new action

Looking again at the Actions list box in Figure 70, you should notice that it does not yet contain any actions. The selections, which are all enclosed in angle brackets and all begin with the word new, are for creating new actions. As you can see in Figure 70, part of the Actions list box is not tall enough to show the whole list at once. Following is the entire list:

Figure 71. Contents of the list of an Actions list box with no actions created
<new input action>
<new extract action>
<new prompt action>
<new pause action>
<new comm wait action>
<new trace action>
<new mouse click action>
<new variable update action>
<new play macro action>
<new perform action>
<new conditional action>
<new sql query action>

For example, if you click <new input action>, the Macro object creates a new Input action and places it at the top of the list. The lower area of the Actions tab allows you to fill out the various fields that belong to an Input action (such as the input key sequence). The new Input item is in the selected area of the Actions list box, and the list part of the list box then looks like this:

Figure 72. Contents of the list of an Actions list box with one actual action
Input action1(0,0)
<new input action>
<new extract action>
<new prompt action>
<new pause action>
<new comm wait action>
<new trace action>
<new mouse click action>
<new variable update action>
<new play macro action>
<new perform action>
<new conditional action>
<new sql query 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 list box. To change the order of the actual actions, click the Change Order button to the right of the Actions list box.

In the AME, the Links tab provides the user interface for storing the names of candidate macro screens into the <nextscreens> element of a macro screen. Figure 73 shows a sample Links tab:

In Figure 73, the Screen Name list box at the top of the tab contains a list of all the macro screens in the entire macro. The currently selected macro screen is Screen1. On the right, the Valid Next Screens list box contains a list of candidate macro screens for Screen1. (Do not confuse this list box, which contains the names in the <nextscreens> element of Screen1, with the list of valid next screens that the macro runtime uses when a macro is played back). On the left, the Available Screens list box contains a list of the names of all other macro screens.

Figure 73 shows only one screen in the Available Screens list because this figure is from a macro with only two macro screens in it, Screen1 and Screen2. However, imagine a macro of twenty screens, and suppose that you want to add macro screens to the <nextscreens> list of a new macro screen, ScreenR. You would follow these steps:

  1. On the Links tab, expand the Screen Name list box and scroll down until you find ScreenR.
  2. Select ScreenR.
  3. Because ScreenR is a new screen, there are no macro screen names listed in the Valid Next Screens list on the right.
  4. On the left, the Available Next Screens list box contains the names of all the macro screens in the macro.
  5. Select a screen that you want to add to the list for ScreenR. Suppose that you select ScreenS.
  6. After selecting ScreenS, click the right arrowhead button between the two list boxes. ScreenS is added to the list box on the right, and removed from the list box on the left.
  7. In the same way, move the names of any other macro screens that you want to the Valid Next Screens list box for ScreenR.
  8. Move a total of three screen names: ScreenS, ScreenG, and ScreenY.

When you are done, ScreenR, the currently selected macro screen, has the names of three macro screens in its list of valid next screens.

In the source view, you would see the names of the valid next macro screens, ScreenS, ScreenG, ScreenY, stored inside ScreenR as shown in Figure 74:

Figure 74. Macro screen ScreenR with <nextscreens> element
<screen name="ScreenR" entryscreen="true" exitscreen="false" transient="false">
   <description>
      ...
   </description>
   <actions>
      ...
   </actions>
   <nextscreens>
      <nextscreen name="ScreenS"/>
      <nextscreen name="ScreenG"/>
      <nextscreen name="ScreenY"/>
   </nextscreens>
</screen>
Figure 74

shows the <screen> element for ScreenR, with the name attribute set to "ScreenR". Inside are the three primary structural elements of a <screen> element: the <description> element, the <actions> element, and the <nextscreens> element. The contents of the <description> element and the <actions> element are not shown but are indicated with ellipses (...). The <nextscreens> element contains three <nextscreens> elements, and each <nextscreen> element contains the name of one of the valid next screens: ScreenS, ScreenG, and ScreenY.

For more information about runtime processing see How the macro runtime processes a macro screen.

Variables tab

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

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

Figure 75. Variables tab
Variables tab of the Macro Editor

In Figure 75, the Variables tab of the AME is selected. The name of the currently selected variable, $strUserName$, is displayed in the Variables list box. Three other fields contain information that the macro runtime needs to create this variable: the Name input field, the Type list box, and the Initial Value input field.

The Variables list box 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.

Notice that the entry of the currently selected variable is contained in parentheses after another string:

Variable1($strUserName$)

The string Variable1 is a setting that shows how many variables you have created. It is not saved in the macro script. The real name of the variable is $strUserName$, and you should use this name alone throughout the macro wherever you use the variable.

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.

The Type list box lists the available types for variables and lets you select the type that you want to use for a new variable. The standard types are string, integer, double, boolean, and field. Also, whenever you import a Java class, such as java.util.Hashtable, as an imported type, the Type list box picks up this imported type and adds it to the list of available types, as shown in Figure 76:

Figure 76. Contents of the Type list box after an imported type has been declared
string
integer
double
boolean
field
java.util.Hashtable

You should use this list box for assigning a type to a newly created variable. You can come back later and change the variable's type to another type, but, as with variable names, remember that you might have already used the variable throughout the macro in contexts that require the type that you initially selected. If so, you must go to each of those places and make sure that the context in which you are using the variable is appropriate for its new type.

The Initial Value input field allows you to specify an initial value for the variable. The AME provides the following default values, depending on the type:

Table 22. Default initial values for variables
Type of variable: Default initial value:
string No string
integer 0
double 0.0
boolean false
field (No initial value)
(any imported type) null

To specify a new initial value just type over the default value.

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.

Creating a new variable

To create a new variable in the AME, first click the <new variable> entry at the end of the Variable list box. The AME creates a new variable and assigns to it some initial characteristics that you should modify to fit your needs. The initial values are:

  1. An initial name (such as $a1$).
  2. An initial type (string).
  3. An initial value, which depends on the type (see Table 22).
Note:
If you create a string variable, you must enclose the initial value in single quotes. Otherwise you will see a message stating that the initial value is an invalid expression.

Now you should set the values that you want for the new variable. For example, if you are creating an integer variable that is for counting screens and that should have an initial value of 1, then you might set the initial values as follows:

  1. In the Name input field, type the name $intScreenCount$.
  2. In the Type list box, select the integer data type.
  3. In the Initial Value field, type 1.

Besides the Variables tab, the AME provides access, in several convenient locations, to a popup window for creating new variables. For example, in the Variable update action, the Name list box contains not only all the names of variables that you have already created but also a <New Variable> entry. Click this entry to bring up the popup window for creating a new variable. Variables created using this popup window are equivalent to variables created in the Variables tab.

For information about creating a variable in the Source view, see Creating a variable.

Creating an imported type for a Java class

The way that a Host On-Demand macro imports a Java class is through an imported type. That is, you must first create an imported type and associate it with a particular Java class. You have to do this only once per Java class per macro. Follow these steps to create an imported type:

  1. On the Variables tab, click the Import button. The Import popup window appears.
  2. In the Imported Types list box, select the entry <new imported type>.
  3. Type the Class name for the type, such as java.util.Hashtable. You must type the fully qualified class name, including the package name if any.
  4. Type a Short Name, such as Hashtable. If you do not specify a short name then the AME uses the fully qualified class name as the short name. If you do specify a short name then you can use either the short name or the fully qualified class name when you refer to the imported type.
  5. Click OK.

To create a variable belonging to this imported type, create the variable in the normal way, but select the imported type as the type of the variable. Follow these steps to create a variable of the imported type:

  1. In the Variables list box, click the <new variable> entry at the end. The AME displays the default initial values in the usual way, including a name (such as $a1$), a type (string), and an initial value (blank).
  2. In the Name input field, type the name that you want, such as $ht$.
  3. In the Type list box, select the imported type, such as Hashtable (if you specified a short name when you imported the type) or java.util.Hashtable (if you accepted the default short name, which is the same as the fully qualified class name).
  4. In the Initial Value field, you can either leave the field blank (which results in an initial value of null) or specify a method that returns an instance of the class, such as $new Hashtable()$ (using the short name) or $new java.util.Hashtable()$ (using the fully qualified class name).

Notice that the constructors are enclosed in dollar signs ($). You must use dollar signs around every call to a Java method, just as you must use dollar signs around the name of a variable. (The reason is that the enclosing dollar signs tell the macro runtime that it needs to evaluate the item.)

Going back to the Import popup window, the Imported Types list box allows you to create new types and to edit or delete the types that you have already created. To create a new type, click the <new imported type> entry at the end of the list. To edit a type, select the type in the Imported Types list box and modify the values in the Class and Short Name input fields. To remove a type, select the type and click Remove.

When you specify a short name, you can use any name, with certain restrictions (see Variable names and type names).

For information about creating an imported type in the Source view, see Creating an imported type for a Java class.

Working with actions

The following sections describe all the actions that can be added or edited using the AME. For more information about macro actions and more details about each action, see Macro actions.

Comm wait action

Communication states

You can specify any of the states listed in the Connection Status list box. Table 23 lists the name and significance of each state:

Table 23. Communication states
Communication state: Significance:
Connection Initiated Initial state. Start Communications issued.
Connection Pending Active Request socket connect.
Connection Active Socket connected. Connection with host.
Connection Ready Telnet negotiation has begun.
Connection Device Name Ready Device name negotiated.
Connection Workstation ID Ready Workstation ID negotiated.
Connection Pending Inactive Stop Communications issued.
Connection Inactive Socket closed. No connection with host.

The stable states (that is, the ones that usually persist for more than a few seconds) are:

If you select <Expression> in the Connection Status list box, then you must specify an expression that resolves to one of the keywords that the macro runtime expects to find in the value attribute of the <commwait> element (see <commwait> element). For example, you might specify a variable named $strCommState$) that resolves to CONNECTION_READY.

For more information, see Comm wait action (<commwait> element).

Conditional action

Specifying the condition

Specify in the Condition field the conditional expression that you want the macro runtime to evaluate. 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).

Condition is True (<if> element)

Use the Condition is True tab to specify the actions that you want to be performed if the condition evaluates to true.

The Condition is True tab contains controls that are almost identical to the controls for the Actions tab. Specifically:

Use these controls on the Condition is True tab to create and edit the actions that you want the macro runtime to perform if the condition is true.

Condition is False (<else> element)

Use the Condition is False tab to specify the actions that you want to be performed if the condition evaluates to false.

Like the Condition is True tab, the Condition is False tab contains controls that are almost identical to the controls for the Actions tab. Use these controls on the Condition is False tab to create and edit the actions that you want the macro runtime to perform if the condition is false.

For more information see Conditional action (<if> element and <else> element).

Extract action

Capturing text

The most common use of the Extract action is to capture text that is being displayed in the host terminal.

Here is an overview of the steps to follow. Each step is described in more detail in the following subsections.

  1. Set the Continuous Extract option, if necessary
  2. Specify an area on the host terminal that you want to capture.
  3. Specify an extraction name.
  4. Specify TEXT_PLANE as the data plane.
  5. Specify a variable in which you want the text to be stored.
Note:
If you extract a value and assign it to a global variable set by an extract, and you plan to use the global variable value for a prompt, you should set the promptall attribute to false. When the promptall attribute is set to true, the extract action is not run before the prompts values are retrieved. Because of this, the global variable used by the prompt does not contain a value. Macros recorded in HCL ZIETrans default to promptall=true. For further information regarding the promptall attribute, see The promptall attributes.
Set the Continuous Extract option

If you want to capture a rectangular block of text, then set the Continuous Extract option to false (this is the default value). For more information, see Capturing a rectangular area of the host terminal.

In contrast, if you want to capture a continuous sequence of text that wraps from line to line, then set the Continuous Extract option to true. For more information, see Capturing a sequence of text from the host terminal .

Specify the area of the host terminal

To specify the area of the host screen that you want to capture, type the row and column coordinates of the text area into the Row and Column fields on the Extract action window.

The macro runtime interprets the values differently depending on whether the Continuous Extract option is set to false or true (see Set the Continuous Extract option).

Type the first set of row and column coordinates into the first pair of Row and Column values (labeled Top Corner on the Extract action window) and type the second set of coordinates into the second pair of Row and Column values (labeled Bottom Corner). You can use the text cursor on the host screen as an aid to determine the coordinates that you want.

In the Row (Bottom Corner) input field you can enter -1 to signify the last row of the data area on the host screen. This feature is helpful if your users work with host screens of different heights (such as 25, 43, 50) and you want to capture data down to the last row. Similarly for the Column (Bottom Corner) input field you can enter -1 to signify the last column of the data on the host screen (see Significance of a negative value for a row or column).

Specify an extraction name

You must specify an extraction name, such as 'Extract1'.

Specify TEXT_PLANE as the data plane

In the Data Plane list box click TEXT_PLANE. This is the default.

Specify the variable in which you want the text to be stored

Set the check box labeled Assign Text Plane to a Variable and enter the name of the variable into which you want the text to be stored. The text is returned as a string. In most cases you probably want to store the string in a string variable, so that some other action in your macro can process the string.

However, if you specify a variable of some other standard data type (boolean, integer, double) then the macro runtime converts the string to the format of the variable, if possible. For example, if the text on the screen is 1024 and the variable is an integer variable then the macro runtime will convert the string 1024 to the integer 1024 and store the value in the integer variable. If the format is not valid for converting the string to the data type of the variable then the macro runtime terminates the macro with a run time error. For more information about data conversion see Automatic data type conversion.

Input action

Input string

The String field is an input field in which you specify the key sequence that you want the action to perform.

To specify a key that causes a character to be displayed (such as a, b, c, #, &, and so on), type the key itself.

To specify a key from the Actions Keys list box, scroll the list to the key you want (such as [backspace]) and click Insert Action Key. The name of the key enclosed by square brackets appears at the next input position in the String field. Notice that the keys in the Action Keys list box are not listed alphabetically throughout. You might have to keep scrolling down the list to find the key you want.

Another way to specify an action key is just to type the name itself into the input field, surrounded by square brackets (for example, [backspace]).

The following copy/paste keys occur in the Action Keys list for a 3270 Display Session:

[copy]                  [mark right]
[copyappend]            [mark up]
[cut]                   [paste]
[mark down]             [pastenext]
[mark left]             [unmark]

These keys are not supported by HCL ZIETrans since HCL ZIETrans does not create a Display Session (Host On-Demand Terminal).

For other keys see Mnemonic keywords for the Input action.

For more information, see Input action (<input> element).

Mouse click action

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

Specifying row and column

In the lower area of the Actions window, specify the row and column location on the host terminal where you want the mouse click to occur. Or, you can click on the host terminal itself, and the macro editor updates the values in the Row and Column fields to reflect the new location of the text cursor.

For more information, see <mouseclick> element.

Pause action

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.

Uses for this action are:

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

For more information, see <pause> element.

Perform action

The Perform action invokes a method belonging to a Java class that you have imported (see Creating an imported type for a Java class).

Invoking the method

Type the method call into the Action to Perform field. You must enclose a method call in dollar signs ($), just as you would a variable (see Syntax of a method call). The macro runtime invokes the method. See also How the macro runtime searches for a called method.

For more information see Perform action (<perform> element).

Playmacro action

The PlayMacro action launches another macro.

Target macro file name and starting screen

Use the Macro Name field to specify the name of the target macro.

Use the Start Screen Name list box to select the macro screen in the target macro that you want the macro runtime to process first:

For more information, see PlayMacro action (<playmacro> element).

Prompt action

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

Displaying the prompt window

Parts of the prompt window

You should type the prompt text (such as 'Please type your password:') into the Prompt Name field, not into the Prompt Text field. (The Prompt Text field is an optional field than you can use to store a note containing details about the particular Prompt action.)

The macro runtime displays a prompt window with the following characteristics:

Default Response

In the Default Response field, which is optional, you can type the text of a default response that you want to appear in the input field of the prompt window when the prompt window is displayed. If the user does not type any keyboard input into the input field of the prompt window, but rather just clicks OK to indicate that input is complete, then the macro runtime processes the default response that is contained in the input field.

For example, if the user normally uses ApplicationA but sometimes uses ApplicationB, you could type ApplicationA into the Default Response field. When the macro runtime performs the Prompt action, the prompt window appears with the text ApplicationA already displayed in the input field. The user either can click OK (in which case the macro processes ApplicationA as the contents of the input field) or else can type ApplicationB into the input field and then click OK (in which case the macro processes ApplicationB as the contents of the input field).

Password Response

If you select true in the Password Response list box (the default is false) then when the user types each key into the input field of the prompt window, the macro runtime displays an asterisk (*) instead of the character associated with the key.

For example, with the Password Response list box set to true (or resolving to true at runtime) then if the user types 'Romeo' the macro runtime displays ***** in the input field.

Require Response

If you select true in the Require Response list box (the default is false) then:

Thus, setting Require Response to true has the effects of reminding the end user (by displaying (required) to the right of the input field) that a response is required before proceeding, and of requiring the end user to enter text in the input field before clicking OK (by disabling OK until the input field contains text). However, if the Prompt action contains a Default Response, then OK is enabled and the default response is displayed in the input field.

If you select false in the Require Response list box then:

Thus, setting Require Response to false has the effect of allowing the user to continue processing the macro by clicking OK, even if the input field of the prompt is blank.

If the promptall attribute of the <HAScript> element (or of the <actions> element) is set to true, and you have several prompt actions in the macro (or in the macro screen) with Require Response set to true, then at the start of macro playback (or at the start of the playback of the macro screen), when the macro runtime displays all the prompt input fields in a single prompt window, the macro runtime does not enable the OK button in the prompt window until all required input fields contain text (see The promptall attributes ).

Note:
If a prompt value is based on a global variable set by an extract, and the promptall attribute is set to true, the extract action is not run before the prompts values are retrieved. Because of this, the global variable used by the prompt does not contain a value. If you use global variables with extracts and prompts, you should set the promptall attribute to false. Macros recorded in HCL ZIETrans default to promptall=true.

Processing the contents of the input field

Response Length

The value in the Response Length field specifies not the size of the input field, but the number of characters that the macro runtime allows the user to type into the input field.

For example, if you set the Response Length field to 10, then the macro runtime allows the user to type only 10 characters into the input field.

Action keys and Translate Host Action Keys

Both you (in the Default Response input field) and the user (in the input field of the Prompt window) can use action keys (such as [enterreset], and so on) as you would in the String field of an Input action (see Input string).

The Translate Host Action Keys list box and its effect are exactly like the Translate Host Action Keys list box in the Input action (see Translate host action keys (xlatehostkeys attribute)). If you set this list box to true, which is the default value, then the macro runtime interprets an action key string (such as [enter]) as an action key rather than as a literal string.

Handling the input sequence in the host terminal

Use the Row and Column fields to specify the row and column position on the host terminal at which you want the macro runtime to start typing the input sequence. To have the macro runtime start typing the input sequence at the current position of the text cursor, you can set either or both of the Row and Column fields to 0. As with the Input action, the row and column position must lie within a 3270 or 5250 input field at runtime, or else the host terminal responds by inhibiting the input and displaying an error symbol in the Operator Information Area, just as it responds to keyboard input from an actual user.

You can have the macro runtime clear the contents of the input field before typing begins, by setting the Clear Host Field list box to true.

The Move Cursor to End of Input field has the same function and effects as the button of the same name in the Input action (see Move cursor to end of input (movecursor attribute)).

You can have the macro runtime not display the input sequence in the input field by setting the Don't Write to Screen list box to true. This field is enabled only when the Assign to a Variable check box is selected.

Assigning the input sequence to a variable

You can have macro runtime store the input sequence into a variable by checking the Assign to a Variable check box.

Create a new variable by clicking the <New Variable> entry in the list box. In the popup window for specifying a new variable, you can specify the name of a variable that the current macro inherits from another macro, or you can specify the name of a new variable that you want to create in the current macro. If you want to create a new variable in the current macro, select the Create variable in this macro check box and select the type of the new variable.

The macro runtime stores the input sequence as a string, and consequently you could specify a string variable as the variable to receive the input. However, if the variable is of some other type than string, then the macro runtime tries to convert the input to the data type of the target variable according to the usual rules (see Automatic data type conversion).

SQLQuery action

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 write the data into a Host On-Demand macro variable.

You can create an SQL statement manually or compose and test an SQL statement using the SQL Wizard.

The statement and results section

The SQLQuery action window has two main sections: a statement section and a result section.

The statement section occupies the upper area of the window and includes the following fields: Database URL, Driver Identifier, Driver Class, User ID, Password, and Statement. You can modify the information in this section in two ways:

You can also edit any of the fields at any time by typing into the field.

The result section occupies the lower area of the window and includes the remaining field: Output Result To (the $HMLSQLUtil$ macro variable).

Using the SQL Wizard

You can use the SQL Wizard to create an SQL statement and test it. The graphical user interface of the SQL Wizard makes it much easier to create an SQL statement, compared to typing in the entire text of the SQL statement into the Statement field of the AME. Also, in the SQL Wizard you can run an SQL statement that you are working on and view the results.

  1. Click SQL Wizard to start the wizard.
    • If there is any information already in the fields of the statement section, then HCL ZIETrans uses this information to initialize the corresponding fields in the SQL Wizard.
  2. Use the SQL Wizard to create an SQL statement and test it.
  3. To close the SQL Wizard without changing your macro, click Cancel.
  4. To save the SQL statement to your macro, do one of the following actions:
    • On the Review tab of the SQL Wizard, click Save.
    • On the Results tab of the SQL Wizard, click Save SQL.
    The AME writes the information that you created in the SQL Wizard into the appropriate fields of the statement section. Any already existing information in the fields of the statement section is overwritten. If the information that the AME writes into a field is a string (for example, the information written into the Database URL field), then the AME also automatically correctly formats the string depending on the underlying macro type. The following fields are updated
    • Fields in the statement section:
      • Database URL
      • Driver Identifier
      • Driver Class
      • User ID
      • Password
      • Statement
  5. Click Cancel to close the SQL Wizard.

Using the fields in the statement section

Instead of creating an SQL statement with the SQL Wizard, you can type the information directly into the fields of the statement section. You can also type into any of the fields after you have created an SQL statement.

Database URL

In the Database URL field, type the database URL of the database server that provides access to the database. The format of the database URL depends on the type of Java Database Connectivity (JDBC) driver that you use to access the database (for more information on drivers see Driver Identifier and Driver Class).

The remote server can be located on a host other than the host to which the application session is connected. For example, a SQLQuery action can specify an IBM® i host, even though the same SQLQuery action is part of a macro that is running in a 3270 Display session connected to a System z® host.

Consult the documentation provided by the driver vendor for the proper format for the database URL.

Driver Identifier and Driver Class

The JDBC driver that the SQLQuery action uses to access the database is a Java client package used by the HCL ZIETrans application to communicate with a server program on a remote host. This server program on the remote host provides access to the database.

If you need a JDBC driver, contact the administrator of the remote database server to obtain the driver.

In the Driver Identifier list box of the SQLQuery action window in the macro editor, select Other.

When you select Other in the Driver Identifier list box, then you must type the fully qualified class name of the driver into the Driver Class field. If you do not know the fully qualified class name, contact the provider of the driver. When you type in the name, remember that case is significant (for example, com is different from COM).

User ID and Password

If the database connection requires a user ID and a password, then type the user ID into the User ID field and the password into the Password field.

HCL ZIETrans encrypts the key sequence that you type into the Password field. This encryption works exactly like the encryption used when the Password check box is selected in an Input action (see Encrypted attribute). Remember:

Note:
The default values for prompts are stored in macro files unencrypted. The default values display in the clear when you edit prompts in the macro editors. Therefore, while using a prompt to specify a password is an appropriate thing to do, for security reasons you should not specify a default value for the password.
Statement

Type or paste an SQL statement into the Statement field. If the Statement field already contains an SQL statement, you can edit it (even if the SQL statement was created using the SQL Wizard).

The AME does not check the format of the SQL statement for validity. If the format is invalid, a run time error occurs when the macro runtime processes the SQLQuery action.

You can spread the SQL statement over several lines or write it all on one line. Figure 77 and Figure 78 show the same SQL statement written over several lines and written as one line. Either way is correct.

Figure 77. SQL statement written on several lines
SELECT
   *
FROM
   SQLTEST.EX01
WHERE
   (
      ( SQLTEST.EX01.DESCRIPT is not null )
   )
Figure 78. Same SQL statement written on one line
SELECT * FROM SQLTEST.EX01 WHERE((SQLTEST.EX01.DESCRIPT is not null))

Remember that if you are using the advanced macro format you must enclose the SQL statement in single quotes and follow the rules for special characters. Below, Figure 79 and Figure 80 show the same SQL statement written for the basic macro format and for the advanced macro format:

Figure 79. SQL statement written for the basic macro format
select * from hodtest.ex01 where
      ((hodtest.ex01.descript='Edit Products'))
Figure 80. Same SQL statement written for the advanced macro format
'select * from hodtest.ex01 where
      ((hodtest.ex01.descript=\'Edit Products\'))'

You can use either upper case or lower case for reserved words (such as select) and database names and fields (such as hodtest.ex01.descript), but you must use exact case for matching strings (such as 'Edit Products'). Thus the two SQL statements in Figure 81 are equivalent:

Figure 81. Example of equivalent upper case and lower case
select * from hodtest.ex01 where
      ((hodtest.ex01.descript='Edit Products'))
SELECT * FROM HODTEST.EX01 WHERE
      ((HODTEST.EX01.DESCRIPT='Edit Products'))

Using the result section

The fields in the result section control how the SQLQuery action uses the data resulting from the SQL statement. You can write the data into a Host On-Demand macro variable.

Storing the data into a macro variable ($HMLSQLUtil$)

The default destination for the data resulting from an SQLQuery action is the Host On-Demand macro variable $HMLSQLUtil$. The Host On-Demand runtime always updates this variable with the results of a successful SQLQuery action.

To store data into $HMLSQLUtil$, expand the Output Result To list box and click $HMLSQLUtil$.

To use the data stored in $HMLSQLUtil$ in a subsequent macro action, you must invoke methods from the Host On-Demand Macro Utility library (HML library) associated with $HMLSQLUtil$. See $HMLSQLUtil$.

Using the SQLQuery action with bidirectional languages

For bidirectional languages (Arabic and Hebrew), some specific properties must be set for SQLQuery to work correctly. An Advanced button appears in the AME to access the options. The Advanced button is visible only if your workstation is configured for a bidirectional language.

The additional properties are:

Host-File Type
Specifies whether the host file should be saved in logical or visual format. The default is Visual.
Local-File Type
Specifies whether local files are in logical or visual format. The default is Logical.
Host-File Orientation
Specifies whether the host file should be saved in left-to-right or right-to-left format. The default is Left-to-Right.
Lam-Alef Expansion
Specifies the behavior of the Lam-Alef characters. When receiving Arabic data from the host through the SQL wizard statement, the character Lam-Alef is expanded into two characters, if there is space after the Lam-Alef character: Lam followed by Alef.
Lam-Alef Compression
Specifies the behavior of the Lam-Alef characters. When sending Arabic data to the host through the SQL wizard statement, the characters Lam followed by Alef are compressed into one character and space is added after the Lam-Alef character. This option is enabled for Arabic systems only. The default is on.
Numerals Shape
Specifies the shape of the numeral on the host file at the SQL wizard statement; the numeral shape could be NOMINAL, NATIONAL or CONTEXTUAL. This option is enabled for Arabic systems only. The default is NOMINAL.
Round Trip
Specifies the behavior of numerals, disabling the reversal of the numerals if preceded by Arabic/Hebrew characters. The default is on.
Symmetric Swapping
Specifies the behavior of the symmetric characters, such as brackets; the inversion of the screen causes directional characters to be replaced by their counterparts. The default is on.

For more information, see SQLQuery action (<sqlquery> element).

Trace action

The Trace action sends a trace message to a trace destination that you specify, such as the HCL ZIETrans Toolkit console or the WebSphere® console. In addition, HCL ZIETrans adds macro traces to the HCL ZIETrans runtime trace.

Trace specification

Use the Trace Handler list box to specify the destination to which you want the trace message sent:

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

For more information, see Trace action (<trace> element).

Variable update action

The Variable update action stores a value into a variable. During macro playback the macro runtime performs the action by storing the specified value into the specified variable.

You must specify:

For more information, see Variable update action (<varupdate> element).