This chapter describes several timing issues involved in processing actions and the resources available for dealing with these issues.
This section addresses HATS macro timing parameters from a macro script level. For example, while there are multiple ways to affect the timing of macro execution from various places in the HATS Toolkit graphical user interface (including the macro editors), the explanations here deal with the results of those actions as they are implemented in the XML script of the macro itself, not with the various ways (tabs in the macro editors, and so on) of causing them to be placed in the script.
There are several timing parameters that influence macro execution. Most timing parameters control delays in various parts of the macro's execution. This allows the macro to be resilient, robust, and successful in an environment where host response time and certain other variables might be unpredictable. The most common reason for adding delay in a macro is to allow the screen coming from the host to complete its arrival before it is processed by the macro. This delay can usually be reduced or totally avoided if enough additional description -- for example, looking for strings of characters on various parts of the screen -- is added to the screens that the delay addresses.
In a HATS macro, there are elements and there are attributes that modify elements (attributes are also referred to as parameters). Elements are framed by opening and closing angle bracket tags and attributes are normally included within an element's tags, such as in this example of the screen element with a modifying pause attribute:
<screen pause=15000>
The elements and attributes discussed in this chapter are:
The pausetime attribute of the <HAScript> element controls two things:
Exactly where, and on which screens, delays of pausetimevalue /2 and pausetimevalue are executed is explained in more detail below. The default value for pausetimevalue (if no explicit pausetime attribute is defined) is 300 milliseconds.
The pause attribute (not to be confused with the <pause> element) overrides the pausetime attribute. To be more precise, if a pause attribute is defined within an element, it is used to override, for only that screen, the pausetime attribute defined (explicitly or by default) in the <HAScript> element for the macro. This means that when the pause attribute is defined for a screen, the pausetime attribute is ignored, and the value of that screen's pause attribute is used in calculating any pausetime-related delays that occur during that <screen> element's processing. The pause and pausetime attributes are not affected by, and do not affect, the processing of any <pause> elements.
The <pause> element is used to insert an explicit delay into the processing of a screen's actions. One or more <pause> elements can be placed before, in between, and after other actions defined in a screen's <actions> element. The pause and pausetime attributes are not affected by, and do not affect, the processing of any <pause> elements.
The ignorepauseforenhancedtn attribute of the <HAScript> element, when set to "true," causes the macro runtime to skip Pause actions (<pause> elements) during macro playback if the session is running in a contention resolution environment. See ignorepauseforenhancedtn=true/false for additional information on the use of this attribute.
The ignorepauseoverrideforenhancedtn attribute of the <pause> element, when set to "true" in a particular <pause> element, causes the macro runtime to process that <pause> element (wait for the specified number of milliseconds) even if the ignorepauseforenhancedtn attribute is set to "true" in the <HAScript> element. See ignorepauseoverrideforenhancedtn=true/false for additional information on the use of this attribute.
The delayifnotenhancedtn attribute of the <HAScript> element, when set to a non-zero value, causes the macro runtime to automatically pause the specified number of milliseconds whenever the macro runtime receives a notification that the Operator Information Area has changed. This attribute is useful for allowing the same macro to run successfully in both a contention resolution environment or a non-contention resolution environment. See delayifnotenhancedtn=(milliseconds) for additional information on the use of this attribute.
For non-exit screens (the exitscreen attribute is set to "false"), a delay of pausetimevalue is executed once after a screen's actions have all been executed, but before the registration or recognition of the next screen begins. If the pause attribute is defined for the screen, then the value of pause is used instead of the value of pausetime for the post-actions delay.
For macro screens defined as exit screens (the exitscreen attribute set to "true"), the pausetime attribute (and any pause attribute defined for that exit screen) is essentially ignored and there is no additional delay automatically executed after all of the screen's actions are completed. This keeps the macro engine from adding extra delays once it has navigated to the final screen of the macro.
In addition, for all macro screens, the macro sleeps for pausetimevalue /2 after each <prompt> or <insert> that is not the last action on the screen.
For example, if pausetime="1000" and no pause attribute is defined for the screen, as shown in Figure 21, the macro will sleep for 500 ms after the first action (a prompt), 500 ms after 4th action and (if the current screen is not an exit screen) 1000 ms after all the actions are played, for a total of 2000 ms.
<actions>
<prompt...
<extract...
<extract...
<prompt...
<insert...
</actions>In a macro, <pause> elements are executed inline wherever they are placed, and are not overridden by the pausetime attribute or pause attribute settings, but might be overridden by the ignorepauseforenhancedtn attribute of the <HAScript> element if it is set to "true".
To expand upon the above example, if pausetime="1000" and no pause attribute is defined for the screen, shown in Figure 22, the macro will sleep for 500 ms after the first action (a prompt), 500 ms after 4th action (a prompt), 500 ms after 5th action (an insert), 150 ms after the 6th action (the <pause> element), and (if the current screen is not an exit screen) 1000 ms after all the actions are played, for a total of 2650 ms.
<actions>
<prompt...
<extract...
<extract...
<prompt...
<insert...
<pause value="150"/>
</actions>Note that if this were an exit screen, the total sleep time would be 1650 ms. Also note that the ignorepauseforenhancedtn attribute of the <HAScript> element, and the ignorepauseoverrideforenhancedtn attribute of the <pause> element, if set, will effect whether the explicit <pause> element in this example is executed or ignored.
In a macro, after all actions for a screen have been processed (including sleeping after all actions based on the pausetime or pause attribute value), the nextscreen is registered and a timer (timeout clock) is started. The macro attempts to recognize the screens at the time of registration and, if no screen is recognized, starts an iterative recognition process for the nextscreens, which is triggered by PSEVENTs and OIAEVENTs generated by data coming in from the host. Each time a PSEVENT or OIAEVENT arrives from the host, the macro tries to recognize the nextscreen again.
The screen recognition process continues to try to recognize the incoming screen data. It might fail several times before succeeding (messages are not logged for these failures). The timeout parameter for the macro sets an upper limit on how long each screen's recognition process (not the whole macro) will try to recognize the incoming screen. Note that the screen recognition engine is not in a "busy" loop. The engine waits to be triggered by incoming PSEVENT and OIAEVENT occurrences to do each additional comparison. If the timeout value is exceeded before the screen is recognized, screen recognition fails. The timer is stopped when a screen is recognized.
This section discusses the scenario in which an action does not perform as expected because a previous action has side effects that have not completed.
There are two attributes that let you add a pause after actions during runtime:
Because the macro runtime executes actions much more quickly than a human user does, unforeseen problems can occur during macro playback that cause an action not to perform as expected, because of a dependency on a previous action.
One example is a keystroke that causes the application screen to change. If a subsequent action expects the application screen to have already changed, but in fact the application screen is still in the process of being updated, then the subsequent action can fail.
Timing-dependent errors between actions can occur in other situations, if the macro runtime performs each action immediately after the preceding action.
The pausetime attribute of the <HAScript> element specifies a time period for the macro runtime to wait as follows:
Through HATS Version 5, the pausetime attribute was implemented as a pause after every type of action, not just after Input and Prompt actions. It is now implemented as follows:
By default, the pausetime attribute is enabled and the timeout value is set to 300 milliseconds. Therefore by default the macro runtime:
Notice that the pausetime attribute affects every macro screen. Therefore this one setting allows you avoid timing errors throughout the macro, without having to change each macro screen that might have a problem.
If you want a longer or shorter pause between actions for a particular macro screen, or if you have only a few macro screens in which a pause between actions is important, then you can use the pause attribute of the <screen> element.
By default, this attribute is not specified.
If you specify this attribute for a macro screen, then the macro runtime uses the specified number of milliseconds for the pause between actions for this particular macro screen.
For example, if for ScreenA you set the pause attribute to 500 milliseconds, then the macro runtime waits 250 milliseconds after each Input action and Prompt action in ScreenA except the last one, and waits 500 milliseconds after the last action in ScreenA.
When the macro runtime processes a macro screen with the pause attribute of the <screen> element specified, it ignores the setting of the pausetime attribute of the <HAScript> element , and uses only the value in the pause attribute.
If you need an additional pause after one particular action in a macro screen, you can add a Pause action after the action. The wait that you specify in the Pause action is in addition to any wait that occurs because of a pausetime or pause attribute.
Suppose that you have a macro screen, ScreenB, with the following bug: the macro runtime starts processing the actions in ScreenB before the host has completely finished displaying the new application screen. Although this timing peculiarity might not pose a problem for you in most situations, suppose that in this instance the first action in ScreenB is an Extract action that causes the macro runtime to read data from rows 15 and 16 of the application screen. Unfortunately the macro runtime performs this action before the host has had time to write all the new data into rows 15-16.
Analyzing this problem, you verify that:
In short, as a result of this timing problem the macro runtime has read rows 15 and 16 of the new application screen before the host could finish updating them.
The reason for this problem is that the unenhanced TN3270 protocol does not include a way for a host to inform a client that the host application screen is complete. (TN3270 implements a screen-oriented protocol, 3270 Data Stream, over a character-oriented connection, Telnet). Therefore, the host cannot send several blocks of data to the client and then issue a message to indicate that the application screen is complete and the user can now enter data. Instead, each block arrives without any indication about whether it is the last block for this application screen. From the client's point of view, something like the following events occur:
This process continues until the host has completely displayed a new host application data screen. The client still waits, not knowing that the host application screen is complete. (For more information, see How the macro runtime processes a macro screen).
This process does not present problems for a human operator.
However, this process does present problems for the macro runtime during screen recognition. Recall that during screen recognition the macro runtime tries to match the application screen to one of the valid next macro screens every time the screen is updated and every time an OIA event occurs (see Repeated screen evaluations). Therefore the macro runtime might find a match before the screen is completely updated. For example, a String descriptor might state that recognition occurs if row 3 of the application screen contains the characters "ISPF Primary Option Menu". When the host has updated row 3 to contain these characters, then the macro runtime determines that a match has occurred, regardless of whether the host has finished updating the remainder of the application screen.
There are three approaches to solving this problem:
The following subsections describe these solutions.
This approach works sometimes but can be awkward and unreliable. You add enough descriptors to the description part of ScreenB so that the macro runtime will not recognize the ScreenB until the critical portion of the application screen has been updated.
Inserting a delay is the best solution if the session is an ordinary TN3270 session or if the session is a TN3270E session without contention-resolution. That is, after the Input action (in ScreenA in our example) that causes the host to send a new application screen, insert a pause of several hundred milliseconds or longer. This delay allows enough time for the host to update the application screen before the macro runtime starts processing the actions in the next macro screen (ScreenB).
In this scenario there are several ways to insert a pause after the Input action:
If your macro has to run both on ordinary TN3270 sessions and also on TN3270E sessions with contention-resolution enabled, the XML macro language has several attributes that can help you. See Attributes that deal with screen completion.
TN3270E (Enhanced) is an enhanced form of the TN3270 protocol that allows users to specify an LU or LU pool to which the session will connect and that also supports the Network Virtual Terminal (NVT) protocol for connecting to servers in ASCII mode (for example, in order to log on to a firewall).
Contention-resolution mode is an optional feature of TN3270E, supported by some but not all TN3270E servers, that solves the client's problem of not knowing when the host has finished updating the application screen. If the client is running a TN3270E session and is connected to a server that supports contention-resolution, then the macro runtime does not recognize a new macro screen until the host has finished updating the application screen.
Host On-Demand has three element attributes that address problems that the macro developer encounters when trying to support a single version of a macro to run on both the following environments:
You will have to add these attributes using the source view.
The ignorepauseforenhancedtn attribute of the <HAScript> element, when set to true, causes the macro runtime to skip Pause actions (<pause> elements) during macro playback if the session is running in a contention-resolution environment. You can use this attribute if you developed a macro to run in a non-contention-resolution environment (you inserted Pause actions) and you now want the macro to also run in a contention-resolution environment without unnecessary delays (you want the Pause actions to be ignored).
With this attribute set to true, the macro runtime processes Pause actions (waits the specified number of milliseconds) in a non-contention-resolution environment but ignores Pause actions in a contention-resolution environment.
Notice, however, that setting this attribute to true causes the macro runtime to skip all Pause actions (<pause> elements) in the macro, not just the pauses that have been inserted in order to time for the application screen to be updated. The next subsection addresses this secondary problem.
The ignorepauseoverrideforenhancedtn attribute of the <pause> element, when set to true in a particular <pause> element, causes the macro runtime to process that <pause> element (wait for the specified number of milliseconds) even if the ignorepauseforenhancedtn attribute is set to true in the <HAScript> element.
Set this attribute to true in a <pause> element if you want the <pause> element always to be performed, not skipped, even in a contention-resolution environment with the ignorepauseforenhancedtn attribute set to true in the <HAScript> element.
The delayifnotenhancedtn attribute of the <HAScript> element, when set to a non-zero value, causes the macro runtime to automatically pause the specified number of milliseconds whenever the macro runtime receives a notification that the OIA (Operator Information Area) has changed.
You can use this attribute if you developed a macro in a contention-resolution environment (you did not need to insert Pause actions) but you now want the macro to run also in a non-contention-resolution environment (some macro screens might need a Pause action to allow time for the application screen to be completed).
With this attribute set to true, then when the macro is run in a non-contention-resolution environment the macro runtime inserts a pause for the specified number of milliseconds each time it receives a notification that the OIA has changed. For example, if you specify a pause of 200 milliseconds then the macro runtime waits for 200 milliseconds every time the OIA changes.
The cumulative effect of the macro runtime pausing briefly after each notification of a change to the OIA is that the application screen is completed before the macro runtime begins processing the actions of the new macro screen. The macro runtime inserts these extra pauses only when it detects that the session is running in a non-contention-resolution environment.
A limitation of this attribute is that the macro runtime adds these extra pauses during every screen, not just during screens in which screen update is a problem. However, the additional time spent waiting is small. And more importantly, this attribute lets you quickly adapt the macro to a non-contention resolution environment, without having to test individual screens and insert a pause action in each screen with a screen update problem.