Screen description and recognition

 

Terms defined

A descriptor is an XML element that occurs in the <description> element of a macro screen and that states an identifying characteristic of the application screen that the macro screen corresponds to.

For example, a macro screen named ScreenB might contain a String descriptor (<string> element) that states that row 3 of the application screen contains the string ISPF Primary Option Menu. During macro playback, when the macro runtime is determining which macro screen to process next, and when ScreenB is a candidate, the macro runtime compares the descriptor in ScreenB with the actual application screen. If the descriptor matches the actual application screen (row 3 of the application screen really does contain the string), then the macro runtime selects ScreenB as the next macro screen to be processed.

Screen recognition is the process that the macro runtime performs when it attempts to match a candidate macro screen to the current application screen

When the macro runtime needs to determine the next macro screen to be processed, the macro runtime places the names of candidate macro screens (usually found in the <nextscreens> element of the current macro screen) onto a list of valid next screens. Then, as the host application updates the host terminal with the new application screen, the macro runtime compares the descriptors of each macro screen on the list with the new application screen. Eventually the application screen is updated to the extent (for example, the string ISPF Primary Option Menu appears in row 3) that the macro runtime can match one of the macro screens on the list to the application screen. The matched macro screen becomes the next macro screen to be processed

Screen description is the process of adding descriptors to the <description> element of a macro screen. You engage in screen description when you go to the Description tab of a macro screen and create or edit a descriptor (such as the String descriptor in the previous example). Likewise, the Macro object during macro recording creates one or more descriptors for each new macro screen that it creates.

 

Description tab

 

Sample Description tab

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.

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.

Looking more closely at the lower area of the Description tab in, 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.

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.

The lower area of the Description tab in Figure 14 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.

Create a new descriptor

Looking again at the Descriptor listbox in Figure 14 , 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. Here is the list from Figure 14:

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 listbox would then look like this:

String descriptor(3, 29)
Fields Counts and OIA
<new string descriptor>
<new cursor descriptor>
<new attribute descriptor>
<new condition descriptor>
<new variable update>

In the figure above, 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 the figure above, see Evaluation of descriptors.

 

Recorded descriptions

 

What information is recorded

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

For the first macro screen of the macro being recorded, the Macro object creates only one descriptor, a Field Counts and OIA descriptor with the following contents:

Therefore, when the recorded macro is played back (without having been revised in any way), the macro runtime matches the first macro screen to its corresponding application screen based entirely on whether the input inhibited indicator is cleared.

For every other application screen of the macro after the first application screen, the Macro object likewise creates only one descriptor, a Field Counts and OIA descriptor, but with different contents:

Therefore, when the recorded macro is played back (without having been revised in any way), the macro runtime matches every macro screen after the first one to its corresponding application screen based on whether the input inhibited indicator is cleared, and whether the count of input fields in the macro screen's description matches the number of input fields in the application screen.

 

Why the recorded descriptions work

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

 

Recorded descriptors provide a framework

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 improve the recorded description.

Often the most straightforward way to improve a recorded description is to add a String descriptor. 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.

 

Evaluation of descriptors

This section describes in detail how the macro runtime determines whether a macro screen matches an application screen.

 

Practical information

Before you read through the following subsections, here are the be aware of the following facts:

 

Overview of the process

Here is an overview of the process.

  1. The macro runtime evaluates each descriptor individually and arrives at a boolean result for that descriptor, either true or false.

  2. The macro runtime then combines the boolean results of the individual descriptors to determine whether the description as a whole is true (the macro screen matches the application screen) or false. To combine the results of the individual descriptors the macro runtime uses either the default combining method or the uselogic method.

    1. With the default combining method:

      1. The macro runtime inverts the boolean result of any descriptor that has the Inverse Descriptor option set to true.

      2. The macro runtime combines the boolean results of the individual descriptors using:

        • The setting of the Optional option for each descriptor.

        • The default rule for combining descriptors.

    2. In contrast, with the uselogic method:

      1. The macro runtime ignores the settings for Inverse Descriptor and Optional.

      2. The macro runtime combines the results of individual descriptors using a rule that you provide in the uselogic attribute.

 

Evaluation of individual descriptors

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.

 

Default combining method

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

When to use the default combining method

The default combining method is appropriate for only two scenarios:

You should not use the default method for any other scenario, unless you thoroughly understand how the default combining method works.

The default combining method uses:

Inverse Descriptor

Every descriptor has an Inverse Descriptor option that is set to false (the default) or true. You can see the Inverse Descriptor option as a listbox below and to the right of the Number of Fields input field in Figure 14. The macro language uses the invertmatch attribute of the descriptor element to store this option.

By default this option is false, so that it has no effect on the evaluation of the descriptor.

If this setting is true, then the macro runtime inverts the boolean result that it obtains from evaluating the descriptor, changing true to false or false to true.

For example, if the macro runtime determines that a String descriptor is true (the string in the descriptor matches the screen in the application window), but the String descriptor has the Inverse Descriptor option set to true, then the macro runtime changes the String descriptor's result from true to false.

Optional

Every descriptor has an Optional option that is set to either false (the default) or true. You can see this option as a listbox below the Number of Fields input field in Figure 14. The macro language uses the optional attribute of the descriptor element to store this option

The Optional option states how a individual descriptor's result is to be treated when the macro runtime uses the default combining rule to combine the boolean results of the descriptors. By default this option is set to false, signifying that the descriptor's result is required rather than optional.

Default combining rule

As stated earlier, the default combining rule is appropriate for only two scenarios:

If you want the description as a whole to be true only if ALL the descriptors are true, then set the Optional setting of all the descriptors in the description to false (the default setting).

In contrast, if you want the description as a whole to be true if AT LEAST ONE of the descriptors is true, then set the Optional setting of all of the descriptors in the description to true.

You should not use the default combining rule in any other scenario where you have multiple descriptors in one macro screen, unless you understand the rule and its implications thoroughly.

Also, not set the Optional settings of multiple descriptors in one macro screen differently (some true, some false) unless you understand the rule and its implications thoroughly.

Here is the rule:

  1. Evaluate all the required descriptors (that is, descriptors for which the Optional field is set to false).

    1. If all are true, then the screen matches.

    2. Otherwise, go to step 2.

  2. Start evaluating the optional descriptors (descriptors for which the Optional field is set to true).

    1. If any optional descriptor is true, then the screen matches.

    2. Otherwise, keep evaluating optional descriptors.

  3. If you reach here, then the macro screen does not match the application screen.

 

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.

HATS adds a default uselogic attribute to the <description> tag when you record the macro. It will be regenerated if you edit the macro in the host terminal or in the advanced macro editor. It will not be regenerated if you edit the macro in the source view.

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

The value of the uselogic attribute is a simplified logical expression whose terms are 1-based indexes of the descriptors that follow. Figure 17 shows an example of a <description> element that contains a uselogic attribute (some of the attributes of the <string> element are omitted for clarity):

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

In the figure above the value of the uselogic attribute is:

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

This logical expression is not a regular logical expression (as described in Conditional and logical operators and expressions) but rather a simplified style of logical expression used only in the uselogic attribute. The rules for this style of logical expression are:

In the example in Figure 17 the macro runtime will determine that the description as a whole is true if:

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.

 

The descriptors

 

Overview

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

You do not have to understand all the types of descriptors at first. Instead begin by becoming familiar with just two types:

These types of descriptors are sufficient to reliably describe many and perhaps even most application screens. However, if these types are not sufficient, then turn for help to one of the other types of descriptors.

Table 9 lists all the types of descriptors and shows the number of descriptors of each type that are allowed to exist in one macro screen (more specifically, in one <description> element belonging to one <screen> element):

Type of descriptor: Number of this type of descriptor allowed per macro screen:
Field Counts and OIA 1 (required)
String descriptor 0 or more
Cursor descriptor 0 or 1
Attribute descriptor 0 or more
Condition descriptor 0 or more

The following subsections describe each type of descriptor in detail.

 

Field Counts and OIA descriptor

Required

The Field Counts and OIA descriptor is required and must be unique. That is, every Description tab (<description> element) must contain one and only one Field Counts and OIA descriptor.

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

Presents three separate and independent descriptors as if one

For user friendliness and for certain design reasons that are not discussed here, the Macro Editor presents the Field Counts and OIA descriptor as one descriptor (see Figure 14). However, in fact each of the three parts of the Field Counts and OIA descriptor on the Description tab of the Macro Editor corresponds to a separate and independent descriptor in the underlying XML macro language. Specifically:

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

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 the table above 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.

You can reinforce these ideas in your mind by looking at a Field Counts and OIA descriptor first as it appears on the Description tab of the Macro Editor and then in the source view. Figure 14 shows a Field Counts and OIA descriptor on the Description tab of the Macro Editor. 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 teh source view, you see the following:

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

Now suppose if you will 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

Set the first two fields to blank tells the Macro Editor 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.

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

Wait for OIA to Become Uninhibited descriptor (<oia> element)

Table 11 shows:

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

In almost all scenarios you can accept the default setting for this descriptor, which is true (on the Description tab) and NOTINHIBITED (in the macro language). Then, during screen recognition:

These are the results that you would want and expect. You typically do not want the macro runtime to recognize the macro screen and immediately start processing its actions while the input inhibited indicator is still set. An important timing issue is involved here, which read about separately (see Screen completion). But no matter how you resolve that issue, almost always leave this descriptor at the default setting, which is true.

However, if you have a scenario in which you want the macro runtime to ignore the input inhibited condition, then set this descriptor to false on the Description tab (the equivalent setting in the macro language is DONTCARE).

Number of Fields descriptor (<numfields> element)

The Number of Fields descriptor specifies a particular number of 3270 (or 5250) fields. Use an integer in the Number of Fields input field, or any entity that evaluates to an integer (such as a variable, an arithmetic expression, or a call to an external Java method).

During screen recognition the macro runtime:

  1. Evaluates this descriptor and obtains an integer result.

  2. Counts the number of fields in the application screen (in its current state).

  3. Compares the two numbers.

If the two numbers are equal then the macro runtime evaluates this descriptor as true. Otherwise the macro runtime evaluates this descriptor as false.

When the macro runtime counts the fields in the host terminal it counts all types of 3270 (or 5250) fields, including input fields.

If you do not want to use this descriptor then set the Number of Fields input field to blank.

Number of Input Fields descriptor (<numinputfields> element)

The Number of Input Fields descriptor is very similar to the Number of Fields descriptor described in the previous section. The difference is that the Number of Input Fields descriptor specifies a number of 3270 (or 5250) input fields, whereas the Number of Fields descriptor specifies a number of fields of all types, including input fields.

Use an integer in the Number of Input Fields field, or any entity that evaluates to an integer (such as a variable, an arithmetic expression, or a call to an external Java method).

During screen recognition the macro runtime:

  1. Evaluates this descriptor and obtains an integer result.

  2. Counts the number of input fields in the application screen (in its current state).

  3. Compares the two numbers.

If the two numbers are equal then the macro runtime evaluates this descriptor as true. Otherwise the macro runtime evaluates this descriptor as false.

If you do not want to use this descriptor then set the Number of Input Fields field to blank.

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. Clear the Use default criteria check box. 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. Click Finish.

 

String descriptor (<string> element)

The String descriptor specifies the following information:

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.

Specifying the rectangular area

You define the rectangular area of text by specifying the row and column coordinates of opposite corners. The default values for these coordinates are (1,1) and (-1,-1), indicating the entire text area of the host terminal (for the significance of negative values such as -1,-1, see Significance of a negative value for a row or column). 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).

The rectangular area can be just large enough to contain the string, or much larger than the string. For example, suppose that the application screen that you want to match to the macro screen has the string 'Terminal and user parameters' in the rectangular area (6,20), (6,37). This rectangular area is exactly large enough to contain the string. If the application screen always has this string at this location, then you might specify the exact rectangular area.

However, suppose that the application screen that you want to match to the macro screen has the same string, 'Terminal and user parameters', located somewhere on it, but that you cannot predict which row of the application screen will contain the string. In this case you could specify the rectangular area (1,1), (-1,-1), indicating that the macro runtime should search every row of the application screen for the identifying string.

For the string value you can use a string or any entity that evaluates to a string (such as a variable, an expression, or a call to an external Java method). The string must be in the form required by the macro format that you have chosen, either basic or advanced.

During screen recognition the macro runtime:

  1. Evaluates the row and column values and obtains an integer result for each value.

  2. Evaluates the string value and obtains a string result.

  3. Looks for the string anywhere within the rectangular block of text in the application screen (in its current state) specified by the row and column values.

If the the macro runtime finds the string within the rectangular block of text then the macro runtime evaluates this descriptor as true. Otherwise the macro runtime evaluates this descriptor as false.

How the macro runtime searches the rectangular area (Wrap option)

If the Wrap option is set to false (the default setting), then the macro runtime searches each row of the rectangular area separately. This method works well when the entire string is contained within one row. For example, if the string is Utility Selection Panel and the rectangular area is (1,1), (24,80), then the macro runtime searches for the string as follows:

  1. Get the first row of the rectangular area. Determine whether the string occurs in the this row. If it does not, then search the next row.

  2. Get the second row of the rectangular area. Determine whether the string occurs in this row. If it does not, then search the next row.

  3. And so on.

In contrast, if the Wrap option is set to true then the macro runtime searches for the string as follows:

  1. Get all the lines of the rectangular area and concatenate them all in order.

  2. Determine whether the string occurs in the concatenated string.

If the string you are searching for can wrap from one line to the next of the host terminal, then set the Wrap option to true. Do not confuse this option with the Unwrap attribute of the Extract action, which is based on fields rather than blocks of text (see Unwrap Text option).

The following description provides an example in which the Wrap option is set to true.

Figure 19 shows rows 14 through 18 of an application screen:

 6  Hardcopy    Initiate hardcopy output
 7  Transfer    Download ISPF Client/Server or Transfer data set
 8  Outlist     Display, delete, or print held job output
 9  Commands    Create/change an application command table
 *  Reserved    This option reserved for future expansion

In the rows above, the first character of each row is a blank space. For example, in row 14, the the first two characters are ' 6', that is, a blank space followed by the numeral 6. Suppose that you want to set up a String descriptor that checks for the following rectangular block of text on this application screen:

Hardcopy
Transfer
Outlist
Commands
Reserved

The steps in setting up the String descriptor for this multi-row block are as follows:

  1. Create a new String descriptor.

  2. Set the values in the Row and Column fields. The row and column location of the upper left corner of the text rectangle above is (14, 5) and the row and column location of the lower right corner is (18, 12).

  3. Set the string value. The string value is: 
    'HardcopyTransferOutlist CommandReserved'

  4. Set the Wrap option to true.

  5. Leave all the other options set to the default.

Notice that in step 3 above the five rows are concatenated as a single string, without any filler characters added (such as a newline or space at the end). However, the string does contain a blank space after 'Outlist' because that blank space does fall within the boundaries of the rectangle.

Use an extracted string in a String descriptor

If you use an Extract action to read text from the screen into a string variable (see Extract action (<extract> element)) then in a subsequent screen you can use the string variable in the String input field of a String descriptor.

For example, in ScreenA you might read a company name from the host terminal into a string variable named $strTmp$, using an Extract action. Then in ScreenB you could use $strTmp$ as the string to be searched for in a String descriptor.

You can do this when extracting multiple lines of text if you have the Wrap option set to true.

The '*' string in a new String descriptor

When you create a new String descriptor the Macro Editor 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.

Multiple String descriptors in the same <description> element

The Macro Editor does not prevent you from creating more than one String descriptor in the same <description> element. You should use as many String descriptors as you need in order to create a reliable description.

You can even define two different strings for the same rectangular block of text in the same <description> element. You might do this if the application screen corresponding to your macro screen displays different strings in the same location at different times. However, if you do define two different strings for the same rectangular block of text, be careful to indicate that both of the strings are not required (both are optional).

 

Cursor descriptor (<cursor> element)

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

During screen recognition the macro runtime:

  1. Evaluates the row value and obtains an integer result.

  2. Evaluates the column value and obtains an integer result.

  3. Looks at the row and column location of the text cursor in the application screen (in its current state).

  4. Compares the row and column location in the descriptor with the row and column location of the text cursor in the application screen.

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.

 

Attribute descriptor (<attrib> element)

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.

Specifying an attribute

Before you specify an attribute, use the Data Plane listbox to select the data plane in which the attribute that you are looking for occurs. If you select <Expression> then specify an expression (such as a variable named $strDataPlane$) that resolves at runtime to one of the data plane strings in the listbox (FIELD_PLANE, COLOR_PLANE, or EXFIELD_PLANE).

Use the Row and Column input fields to specify the Row and Column location on the application screen of the attribute that you are looking for.

Use any of these methods to specify an attribute value:

 

Condition descriptor (<condition>) element

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.

During screen recognition the macro runtime:

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.

 

Custom descriptor (<customreco> element)

Call custom description code. To create, use the source view to add a <customreco> element to the <description> element of the macro screen.

 

Variable update action (<varupdate> element)

The final type of entry that can occur in the Descriptor listbox is the Variable update entry, which is not a descriptor at all, but rather an action that the macro language allows to occur inside a <description> element.

The Variable update action in a <description> element performs the very same type of operation that it performs in an <actions> element, which is to store a specified value into a specified variable.

For information about creating a Variable update action see Variable update action (<varupdate> element).

 

Processing a Variable update action in a description

You should be aware of how the macro runtime processes one or more Variable update actions when they occur in a <description> element:

  1. The macro runtime performs all the Variable update actions immediately, as if they were first in sequence.

  2. The macro runtime then evaluates the remaining items (descriptors) in the description as usual and arrives at an overall boolean result. The Variable update actions have no effect on the boolean result.

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.

For example, suppose that a macro is being played back, that the screen name ScreenB is on the list of valid next screens, and that ScreenB contains a <description> element like the one shown in Figure 20:

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

Each time that the macro runtime tries to match ScreenB to the current application screen:

  1. The macro runtime sees the <varupdate> action and performs it, storing the value true into $boolUpdate$.

  2. The macro runtime evaluates the <oia> descriptor and the <attrib> descriptor and arrives at a boolean result for the entire <description> element.

 

Variable update with the uselogic attribute

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

When a Variable update action is used in a uselogic attribute:

 

Home