Screen recognition

Recognizing valid next screens

As described in How the macro runtime processes a macro screen, the macro runtime typically finds the names of macro screens that are candidates for becoming the next macro screen to be processed by looking in the <nextscreens> element of the current macro screen. That is, the macro screen contains within itself a list of the macro screens that can validly be processed next. Entry screens and transient screens are exceptions.

Entry screens, exit screens, and transient screens

You can use the entry screen, exit screen, and transient screen settings to mark macro screens that you want the macro runtime to treat in a special way. In the source view, these settings appear as attributes of the <screen> element.

In Figure 1, you can see these three attributes in the <screen> element for Screen1: entryscreen, exitscreen, and transient.

For information about where these settings are made using the VME, see General tab, and using the AME, see Screens tab.

Entry screens

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

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

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

Macro with several entry screens

The entry screens are evaluated in the order that they appear in the macro script. One of the situations in which you might have several entry screens in the same macro is when a host application begins with a series of application screens one after another, such as application screen A, followed by application screen B, followed by application screen C. For instance, screen A might be a logon screen, screen B a screen that starts several supporting processes, and screen C the first actual screen of the application.

In this situation, you might want the user to be able to run the macro whether the user was at application screen A, B, or C.

Entry screen as a normal screen

If you mark a screen as an entry screen, it can still participate in the macro as a normal screen and be listed in the <nextscreens> lists of other macro screens.

For example, you might have a host application that has a central application screen with a set of menu selections, so that each time you make a menu selection the application goes through several application screens of processing and then returns to the original central application screen.

In this situation, suppose that macro ScreenA is the macro screen corresponding to the central application screen. Both of the following would apply:

Exit screens

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

You can have any number of exit screens for a macro. Here are some examples of situations in which there could be several exit screens.

Transient screens

A transient macro screen is used to process an application screen that has the following characteristics:

An example of such an application screen is an error screen that the application displays when the user enters invalid data. This error screen appears at unpredictable times (whenever the user enters invalid data) and as a macro developer the only action that you want to take for this error screen is to clear it and to get the macro back on track.

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

Transient screens are considered for the entry screen without being marked as entry screens. If a transient screen is selected as the entry screen, its actions execute, and then the macro checks all of the entry screens and all of the transient screens to decide which screen to match next.

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

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

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

Example of handling of transient screen

Suppose that the macro runtime is doing screen recognition and that it has the names of three macro screens on the list of valid next screens: ScreenB and ScreenD, which are the names of candidate screens, and ScreenR, which is the name of a transient screen. The macro runtime performs the following steps:

  1. When the host terminal's presentation space is updated, the macro runtime evaluates the names on the list of valid next screens in the usual way.
  2. Suppose that an unexpected application screen has occurred, so that neither ScreenB nor ScreenD matches the current application screen, but that ScreenR does match the current application screen.
  3. Because a transient screen has been recognized, the macro runtime does not remove any names from the list of valid next screens.
  4. The macro runtime makes ScreenR the current macro screen to be processed.
  5. The macro runtime performs the actions in ScreenR. These actions clear the unexpected application screen.
  6. The macro runtime ignores the <nextscreens> element, if any, in ScreenR.
  7. The macro runtime returns to the previous task of screen recognition in step 1 above. The list of valid next screens has not changed. This time, suppose that an expected application screen is displayed and that the macro runtime finds that ScreenD matches it. Therefore:
    1. The macro runtime makes ScreenD the next macro screen to be processed.
    2. The macro runtime removes the names ScreenB and ScreenD from the list of valid next screens. The name ScreenR remains on the list.
    3. The macro runtime begins processing the actions in ScreenD.

Timeout settings for screen recognition

This section discusses the scenario in which the macro runtime cannot advance because it cannot match a screen on the list of valid next screens to the current application screen. There are two fields that let you set a timeout value that terminates the macro if screen recognition does not succeed before the timeout expires:

Screen recognition

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

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

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

Timeout attribute on the <HAScript> element

The timeout attribute on the <HAScript> element can be set using the Timeout between screens setting in the VME, see General tab, and in the AME, see Figure 61. This attribute specifies a timeout value for screen recognition. By default, if specified the value applies to each and every macro screen in the macro. However, you can change the value for a particular macro screen by using the timeout attribute on the <nextscreens> element, see Timeout attribute on the <nextscreens> element).

Whenever the macro runtime starts to perform screen recognition, it checks to determine whether the timeout value is set for the entire macro or whether a timeout value is set for the macro screen's list of next screens. If a timeout value is set, then the macro runtime sets a timer to the number of milliseconds specified by the timeout value. If the timer expires before the macro runtime has completed screen recognition, then the macro runtime terminates the macro. An Error page is displayed in the browser, and a message such as the following is written to the server console:

Figure 12. Error message for screen recognition timeout
Macro timed out: (Macro=ispf_ex2, Screen=screen_address_type)

Notice that this message displays the name of the macro and the name of the screen that was being processed when the timeout occurred. For example, if the screen specified in this message is ScreenA, then the macro runtime had already performed all the actions in ScreenA and was trying to match a macro screen in the Valid Next Screens list for ScreenA to the application screen.

If the macro is playing in the host terminal, the following message is displayed:

Figure 13. Error message shown for host terminal
The host terminal does not match any expected screens.

When specified, the default timeout value is set to 60000 milliseconds (60 seconds).

The timeout attribute on the <nextscreens> element specifies a timeout value for screen recognition. It can be set using the Source tab in the VME and using the Timeout field in the AME, see Figure 73. If this value is non-zero, then the macro runtime uses this value as a timeout value (in milliseconds) for screen recognition for macro screens on the current list of valid next screens, instead of using the value set in the timeout attribute on the <HAScript> element.

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

Recognition limit

The recognition limit allows you to take some sort of action if the macro runtime processes a particular macro screen too many times. If the macro runtime does process the same macro screen a large number of times (such as 100), then the reason is probably that an error has occurred in the macro and that the macro is stuck in an endless loop.

The recognition limit is not an attribute in the begin tag of the <screen> element, but rather a separate element (the <recolimit> element) that optionally can occur inside a <screen> element, on the same level as the <description>, <actions>, and <nextscreens> elements.

The <recolimit> element can be added using the Set Recognition Limit check box and the Screens Before Error input field both the VME and AME, see Screens tab.

When the recognition limit is reached, the macro runtime either terminates the macro with an error message (this is the default action) or starts processing another macro screen that you specify.

You should notice that the recognition limit applies to one particular screen and that by default it is not specified. You can specify a recognition limit for any macro screen, and you can specify the same or a different recognition limit value for each macro screen in which you include it.

Determining when the recognition limit is reached

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

Suppose that a macro includes a macro screen named ScreenB and that ScreenB contains a <recolimit> element with a recognition limit of 100. Each time the macro runtime recognizes ScreenB (that is, each time the macro runtime selects ScreenB as the next macro screen to be processed), the macro runtime performs the following steps:

  1. The macro runtime detects the presence of the <recolimit> element inside ScreenB.
  2. The macro runtime increments the recognition count for ScreenB.
  3. The macro runtime compares the recognition count with the recognition limit.
  4. If the recognition count is less than the recognition limit, then the macro runtime starts performing the action elements of ScreenB as usual.
  5. However, if the recognition count is greater than or equal to the recognition limit, then the macro runtime performs the action specified by the <recolimit> element. In this case macro runtime does not process any of the action elements in ScreenB.

Action when the Recognition limit is reached

The default action when the recognition limit is reached is that the macro terminates and an Error page is displayed in the browser. The following error message is written to the server console:

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

If you want the macro runtime, as a recognition limit action, to go to another macro screen, you can set thegoto attribute in the General screen properties panel. Use the Goto Screen Name input field and specify the name of the target macro screen as the value of the attribute (see <recolimit> element).

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

You can use the target macro screen for any purpose. Some possible uses are: