Screen Recognition

 

+
Search Tips   |   Advanced Search

 

 

Valid next screens

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.

In the Macro Editor, the Links tab provides the user interface for storing the names of candidate macro screens into the <nextscreens> element of a macro screen.

In the figure above, the Screen Name listbox 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 listbox contains a list of candidate macro screens for Screen1 (Do not confuse this listbox, 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 listbox contains a list of the names of all other macro screens .

Although the figure above shows only one screen in the Available Screens list, that is because this figure is from a macro with only two macro screens in it, Screen1 and Screen2. Instead, 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 listbox 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 listbox 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 listboxes. ScreenS is added to the listbox on the right, and removed from the listbox on the left.

  7. In the same way, move the names of any other macro screens that you want to the Valid Next Screens listbox for ScreenR.

  8. Suppose that you 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. 

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

The figure above 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 an ellipsis (...). The <nextscreens> element contains three <nextscreen> 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.

 

Entry screens, exit screens, and transient screens

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 Macro Editor, you make these settings on the General tab of the Screens tab. At the top of the tab, under the Screen Name field, are listboxes for Entry Screen, Exit Screen, and Transient Screen. For each of these listboxes, specify a boolean value (the default is false) or an expression that evaluates to a boolean value.

In the source view, these settings appear as attributes of the <screen> element. In Figure 32, above, you can see these three attributes in the <screen> element for ScreenR: entryscreen, exitscreen, and transient.

 

Entry screens

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

When the macro playback begins, the macro runtime searches through the macro script and finds all the macro screens that are designated as entry screens. Then the macro runtime adds the names of these entry macro screens to the runtime list of valid next screens. Finally the macro runtime tries in the usual way to match one of the screens on the list to the current 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

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 can also be 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. Therefore:

 

Exit screens

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

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

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.

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

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

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

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

 

Timeout Between Screens (Macro tab)

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

Whenever the macro runtime starts to perform screen recognition, it checks to determine whether the Timeout Between Screens value is set for the entire macro and whether a Timeout value is set for the macro screen. 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 and displays a message such as the following:

    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.

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

 

Timeout (Links tab)

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

If the timer expires before the macro runtime has completed screen recognition, then the macro runtime displays the Macro timed out error message.

 

Recognition limit (General tab of the Screens tab)

The recognition limit, <recolimit>, can optionally occur inside a <screen> element, on the same level as the <description>, <actions>, and <nextscreens> elements.

The Set Recognition Limit checkbox and the Screens Before Error input field are located on the General tab of the Screens tab.

By default the Set Recognition limit checkbox is cleared and the input field is disabled. If you select the checkbox, then the Macro Editor sets the default value of the Screens Before Error input field to 100. Set the value to a larger or smaller quantity.

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.

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 absent. 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 runtime displays an error message such as the following and then terminates the macro:

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, then use the source view to add a goto attribute to the <recolimit> element and specify the name of the target macro screen as the value of the attribute (<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.

Use the target macro screen for any purpose. Some possible uses are:

 

Home