Timing issues

This chapter describes several timing issues involved in processing actions and the resources available for dealing with these issues.

Macro timing and delay characteristics

This section addresses HCL ZIETrans 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 HCL ZIETrans 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 an HCL ZIETrans 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:

What each element and attribute is for

The pausetime attribute of the <HAScript> element controls two things:

  1. A delay of pausetimevalue /2 (in milliseconds) that occurs after most <prompt> and <insert> elements defined in a screen's actions, and
  2. A one-time delay of pausetimevalue (in milliseconds) that occurs after all of a screen's actions have been executed (for most screens)

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.

How the HCL ZIETrans macro processing engine uses these timing elements and attributes

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.

Figure 21. Example 1 for pausetimevalue
<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.

Figure 22. Example 2 for pausetimevalue
<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.

What happens after a screen's actions have completed

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.

High-level, textual flow of macro engine processing

  1. ScreenX is recognized.
  2. ScreenX actions are completed. Note that there is the addition of pausetimevalue /2 (or pauseattributevalue /2) after each action if the action is a <prompt> or <insert> and is not the last action in the set of actions.
  3. Macro play stops here if the current screen is an exit screen.
  4. ScreenX pausetimevalue delay (set by the pausetime attribute or overridden by a local pause attribute for this screen) is completed.
  5. Register nextscreens.
  6. Start a timeout clock for nextscreens.
  7. Recognition processing of nextscreens loops, doing a new recognition based on each PSEVENT or OIAEVENT, the arrival of which might be controlled or affected by contention resolution if it is active, until...
  8. A nextscreen is recognized, in which case the timeout timer is stopped. The process returns to the top of the sequence and starts again, or the timeout timer (timeout attribute of the <HAScript> element) expires and the macro ends with a timeout error.

Pause after an action

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:

Speed of processing actions

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

The pausetime attribute of the <HAScript> element specifies a time period for the macro runtime to wait as follows:

Through HCL ZIETrans 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.

The pause attribute

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.

Adding a pause after a particular action

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.

Screen completion

Recognizing the next macro screen too soon

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 cause: Unenhanced TN3270 protocol

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:

  1. A block of commands and data arrives. The client sets the input inhibit indicator, processes the block, and displays the new data on the specified parts of the host terminal. The client then clears the input inhibit indicator and waits.
  2. 30 milliseconds pass.
  3. Another block of commands and data arrives. The client processes the block as in step 1 above. This block causes a different part of the screen to be updated. The client waits.
  4. 50 milliseconds pass.

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.

Solutions to early macro screen recognition

There are three approaches to solving this problem:

The following subsections describe these solutions.

Add more descriptors

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.

Insert a delay after the input action

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.

Use the contention-resolution feature of TN3270E

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.

Attributes that deal with screen completion

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.

ignorepauseforenhancedtn=true/false

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.

ignorepauseoverrideforenhancedtn=true/false

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.

delayifnotenhancedtn=(milliseconds)

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.