        |  |
 |
 |
 |
 |
 |
 |
 |
 |
 |
|
UTS Connect User's Guide
CHAPTER 5
For demonstration purposes, this guide uses a simple demo interface offered for demonstration purposes by a third party. The transactions shown here in the form of screen captures will be representative of the type of transactions commonly used by operators on UTS terminals. Unlike the exercises in the Composer Tutorial, these steps are not meant to be followed by the user, but are merely given here for illustrative purposes.
The UTS Component differs from other components in that a major portion of the Action Model is built for you automatically. This happens as you interact with the host in the Native Environment pane as part of a live UTS session. Composer records your interactions as a set of auto-generated actions in the Action Model. Typically, in other exteNd Composer components (such as a JDBC Component), you must manually create actions in the Action Model, which then perform the mapping, logging, transformation, communication, and other tasks required by the component or service. By contrast, when you create a UTS Component, you record requests and responses to and from the host, which end up as actions in the Action Model. In addition, you can add standard actions (Map, Log, Function, etc.) to the Action Model just the same as in other components.
NOTE: In order to successfully build a UTS Component, you should be familiar with the specifics of the host application you intend to use in your XML integration project.
The following example demonstrates several common tasks that you will encounter in building UTS Components, such as:
Drag-and-drop mapping of Input DOM elements to UTS-screen prompts
Drag-and-drop mapping from the Native Environment Screen to the Output DOM
The use of ECMAScript expressions to manipulate Screen object elements
The following example starts with an XML document that contains several parameters used as input to a guest book page. The goal of this particular component is simply to sign a guest book on the demo system and receive some information back from the terminal. Several screen messages will be placed in the Output DOM.
Create a UTS Component per the procedure shown in Chapter 3, "Creating a UTS Component".
Once created, the UTS Component Editor window appears, with the words "UTS Terminal" in the center of the Native Environment Pane, indicating that no connection has yet been established with a host.
Click the Record button. You are automatically connected to the host that you selected in the Connection Resource for the component. An input screen appears in the Native Environment pane as shown below.
Begin by checking the screen to make sure you have arrived at the expected place. This should always be the first action when you arrive at a new screen in a UTS Component (or any terminal component for that matter). To do this, use the left button on your mouse to highlight some text on the native environment panel and then right click and select Check Screen. The Check Screen dialog window appears, with an expression already entered as shown below:
Click OK and the Check Screen action is added to the action model.
Reposition your cursor to the space just after the arrow prompt in the Native Environment pane. In this UTS application, exact placement in the entry fields is important. Drag the SCREENPUT/Login node from the Input DOM to the second column of the 24th row of the Native Environment Pane. You will notice when you drag the item that the text appears after the arrow prompt and a new Set Screen Text action appears automatically in the Action Model.
Position your cursor after the text that was entered and press the Enter Key. You will see that a Send Key Transmit Action is added to your Action Model and the screen changes in response.
As discussed in "The Check Screen Action" on page -32, it is a wise idea to make sure you are on the correct screen before proceeding. To do this, drag the cursor over the words "Thank you" in the upper left-hand corner. Notice that the status line of the component editor window in the lower left corner will indicate the row and column location where the words start and end. Using the right mouse button in the Native Environment pane, click Check Screen. A Check Screen action including a Screen.getText method automatically appears, verifying that the words "Thank you" do appear where expected on the screen.
Decide whether the default Screen Wait time (in this case 60 seconds) is going to be adequate for this Check Screen action. Careful testing of the component should be done in order to verify that this timeout value is safe. Click on OK to enter the Check Screen action into the Action Model.
The "Thank you" screen is not terribly interesting from a demonstration standpoint, so let's move to the "Sign in" screen instead. As indicated on the terminal screen, this is acheived by pressing the F1 key. Make sure your focus is on the native environment pane before you press the F1 key. Pressing F1 with focus at any other place in Composer will bring up the online help system. Another Send Key action is added to the model and the screen changes to the Guest Book.
As always, verify that you are on the correct screen. Highlight the word "Guest Book" and right click to select Check Screen. Click OK to add this action to the Action Model.
Now, instead of having to type the information into the guest book, you can use the data that already exists in your Input DOM and map it to appropriate fields in the Native Environment Pane. From the input DOM, drag the SCREENINPUT/LName node into the "Last Name:" field on the terminal screen. Again, as you click and drag, the onscreen row/column coordinates of the selected area are displayed in the status line and a new Set Screen Text action appears in the model
Proceed by dragging all the remaining nodes from the Input DOM into the appropriate fields on Guest Book screen. The Sign-in screen will begin to look filled out, and several new Set Screen Text actions will appear in your action model.
After signing the guest book, proceed with the rest of the Demo by pressing F1 again, which changes the screen and adds another Send Key Transmit action to the model.
As always, it is a good idea to make sure you are on the expected screen, so highlight the screen text "Background/Foreground" and right click to create another Check Screen Action. The Screen and Action model now look like this:
Next, drag some information from the screen into the Output DOM. Highlight and drag the first paragraph on the terminal screen into the MSG1 node. Drag the second paragraph into the MSG2 node. The following actions are added and the Output DOM now looks like this:
Now, use the Ctrl-Drag method to map the produts shown on the screen into the Product node of the Output DOM. Placing the cursor on the left-most character of the top product in the list, hold down Ctrl and the left mouse key and drag to the bottom, right-most character of the product list. The following action is added to the model:
The SCREENINFO/Products Node of the output DOM will now contain the list of products from the terminal screen.
If you were sucessfully able to follow all the steps outlined above, your complete Action Model would now look like this:
Obviously, this is a fairly simple component.that does not accomplish much real work. In using Composer to build UTS components, your initial recorded component may only be a starting point. For this reason, it is important to study how to edit existing action models.
You will encounter times when you need to edit a previously recorded action model. Unlike the situation with other components, editing a UTS Component requires extra attention. When a UTS Component executes, it plays back a sequence of actions that expect certain screens and data to appear at certain times in order to work properly. So when editing a component you must be careful not to make the action model sequence inconsistent with the host program execution sequence you recorded earlier (i.e., don't break it!).
In general, to ensure successful edits, the following recommendations apply:
Exercise extreme care when using Cut, Copy, and/or Paste to delete, move, or replicate actions in your Action Model. Actions that were created automatically during a "Record" session will often create data dependencies that are easily overlooked in the editing process.
When you need to use drag-and-drop to add new Map actions to your Action Model, click the Start Animation button in the Action Pane toolbar and step to the line of interest in your Action Model; then Pause animation and turn on Record mode. At this point, you can safely drag to and from the screen. Following this procedure will prevent your Action Model from getting out of sync with the host or conflicting with previously mapped DOM data.
The following procedure will explain how to change an existing action or add new actions to a previously recorded session.
To Change an existing action in a previously recorded Action Model:
Open the component that includes the Action Model you'd like to edit. The component appears in the UTS Component Editor window.
Navigate to the action in the Action Model where you'd like to make your edit or after which you'd like to add additional actions and highlight that action.
Click the Toggle Breakpoint button (or press F2). The highlighted action becomes red (Animation will be discussed in further detail below).
Click the Start Animation button. The animation tools (in the Actions pane's toolbar) become enabled.
Click the Step to Breakpoint/End button. The Action Model executes all of the actions from the beginning of the Action Model to the breakpoint you set in step 3 above.
Edit the action to make any changes you wish to the current line by right-clicking on the action and selecting Edit Action. Or, if you wish to add new actions, use Composer's drag and drop features to add new Map actions that interact with the screen. The new actions will be added directly under the highlighted line.
The following procedure explains how to delete an action in a previously recorded session
To Delete an Action to a previously recorded Action Model:
Highlight the action line that you want to delete and click on the right mouse button. Select Delete from the menu. You may also highlight the line and press the Delete button on your keyboard.
In the example above, the goal was to sign a guest book and place some information from the terminal into the Output DOM.
One of the items mapped was the product list. In real life, in order to map something like a product list, you would want to have each product map into its own node in an Output DOM. This requires an iterative loop, for example a Repeat/While loop, which is explained in detail in Chapter 8 of the Composer User Guide in the section titled "The Repeat While Action." Often, in UTS components you will find that you need to perform some form of looping in order to read the values from the terminal window. Make sure you are very familiar with this chapter of the User Guide.
Below is an example of a completed Action Model containing a Repeat/While loop that fills in an Output DOM with several values obtained from the terminal window. In the example above, you used drag and drop to place all the values from the Product List into a single pre-existing node in the Output DOM. Here, each product has been placed in it's own node along with some sub-nodes which could also be used as attributes.
As mentioned previously, Composer includes animation tools that allow you to easily test your component. There is also an Execution button on the UTS Component Editor tool bar, which allows you to execute the entire Action Model and verify that your component works as you intend. While testing, pay close attention to your Screen Wait Time values in all Check Screen actions to make sure they are appropriate and that Set Screen Text and other actions work as intended.
Open a UTS Component. The UTS Component Editor window appears.
Select the Execute button. All the actions in the Action Model execute in order. This is an excellent way to determine whether the Screen Wait times you indicated in your Check Screen Actions are accurate or if you require additional Check Screens in your Model. If the component executes successfully, a message appears as follows.
After executing the component, you may want to double check the contents of your DOMs to be sure all of the appropriate data mappings occurred as expected. To make all data elements visible, select Expand XML Documents from the View menu. This expands all of the parents, children, data elements, etc. of the DOM trees, so that you can easily see the results of execution of the component. If your execution had a problem, you can use the Animation tools to pinpoint where the difficulty occurred. This process is described in the next section.
In the Action Model, you'll find animation tools that allow you to test a particular section of the Action Model by setting one or more breakpoints. The Toggle/Breakpoint tool was introduced briefly in the section above, "Editing or Adding to an Existing Action" on page -47, but all the animation tools will be explored in more detail below. Using these tools, you can run through the actions that work properly, stop at the actions that are giving you trouble, and then troubleshoot the problem actions one at a time.
The following procedure is a brief example of the functionality of the animation tools. For a complete description of all the animation tools and their functionality, please refer to the exteNd Composer User's Guide.
To run a UTS Component using Animation Tools:
Open a UTS Component. The component appears in the UTS Component Editor window.
NOTE: Animation and Recording are mutually exclusive modes in the component. In order to record during animation, you must either pause, or stop animation and then turn on record mode.
Click the Start Animation button in the Action Model tool bar, or press F5 on the keyboard. All of the tools on the tool bar become active, and a connection is established with the host. The Native Environment Pane makes the terminal connection..
Click the Step Into button. The first Check Screen action becomes highlighted.
Click the Step Into icon again. The Check Screen action (above) executes and the next action becomes highlighted.
Click the Step Into button repeatedly to execute actions one-by-one.
Click other buttons (Step Over, Run To Breakpoint, Pause, etc.) as desired to control the execution of the component. Note that you can set a breakpoint at any time during execution by clicking the mouse on an action line and hitting F2 or using the Set Breakpoint button.
UTS-based computing differs from other types of computing (including other terminal-based interactions) in the following ways:
Retrieval of data sets may require repeated roundtrip communications with the Unisys host. One query may bring many screens' worth of data, which must be captured through multiple "page forward" commands, etc.
Information that spans screens may be (and often is) partially duplicated on the final screen.
These factors can make automating a UTS interaction (via an Action Model) challenging. Suggestions on how to deal with these issues are given below.
A common requirement in UTS computing is to capture a data set that spans multiple screens. It is not always obvious how many screens' worth of data there may be. In cases where the screen contains a line that says something like "Page 1 of 4," it's a straightforward matter to inspect the screen at the point where this line occurs (using one of the ECMAScript Screen-object methods described earlier, in the section titled "UTS-Specific Expression Builder Extensions" on page -34) and construct a loop that iterates through all available screens. But sometimes it's not obvious how many screens' worth of data there may be. In some cases, the only clue that you have may be the presence of a "More" command (for example) at the top or bottom of the screen, which changes to "Back" (or "End," or some other message) when you reach the final screen. In other cases, you may be told how many total records exist, and you may be able to determine (by visual inspection) how many records are displayed per screen; hence, you can calculate the total number of screens of information awaiting you. There may be the presence of a the + sign in the Action field which changes to "Return" when you reach the final screen.
The point is that if your query results in (potentially) more than one screen's worth of information, you must be prepared to iterate through all available screens using a Repeat/While action, and stop when no additional screens are available. You will have to supply your own custom logic for deciding when to stop iterating. Your logic might depend on one or more of the following strategies:
Determine the total number of screens to visit by "scraping" that information, if available, off the first screen.
Divide "total records" (if this information is available) by the number of records per screen (if this is known in advance), and add one.
Visit screens one-by-one and break when a blank record is detected.
Visit screens one-by-one until a special string (such as "End" or "Go Back") is detected.
Visit screens one-by-one until two consecutive identical screens have been encountered.
Obviously, the strategy you use will depend on the implementation specifics of the host application in question.
In UTS host applications, it's common for the final screen of a multiscreen result set to be "padded" with data from the previous screen. In this way, the appearance of a full screen is maintained.
Consider the following two screen shots. The top one shows the first screen's worth of information after transmitting a command that returns two screens of information. Notice the + sign in the Action field of the first screen indicating that there is more data to follow.
Pressing the Transmit Key (or Enter), brings up the second screen. There are several things to notice about this second (and, in this case, final) screen:
The + sign in the Action: field has been replaced by the word "REturn". Sending the Transmit Key here would return you to the Job and Task Display Menu.
The second screen shows exactly the same records as the first one, except for job number 2111/2111, which drops off to make room for four of the 1621 jobs because the second screen is limited to listing 17 lines of jobs. (The first screen had only 14 lines of data, because there were three lines worth of header information). The majority of this screen is showing us redundant data.
Another + sign appears on the screen, this time in marking the fourth-to-last job on the screen. The system provides us with a convenient way to see where the list splits and where the data ceases to be redundant.
In most cases, you will not want to capture this sort of redundant data. Fortunately, the demo system used here has made it fairly simple to detect and reject redundant records by placing the + sign at the first column to the left in the list where the data begins to be new. This can be used along with ECMAScript as an easy and convenient way of maintaining unduplicated lists. The basic steps to do this would be:
Create a Switch Statement depending on whether the screen is continued or not.
Within each case of the Switch Statement, enter a Repeat While loop and fetch each record to place it into a variable as shown in the example above.
After the loop is complete, send a Transmit Key to go on to the next screen.
The following tips may be helpful to you in building reliable UTS Components.
Always follow a Set Screen Text Action with a Send Key Action.
Always follow your Send Key Actions with a Check Screen Action.
Remember that the default Screen Wait values used in Check Screen actions are set when you initially created your Connection resource. To change the default Screen Wait time, you must change the property of the Connection Resource.
Remember also that Screen Wait timeout values may need to be increased, for load-sensitive applications. Careful testing will reveal these sorts of problems.
Be careful when editing a previously recorded Action Model. Deleting or modifying a single Set Screen Text Action can (and will!) throw your entire Action Model off course.
In addition to the Set Screen Text, Send Key and Check Screen actions, you have all the standard Basic and Advanced Composer actions at your disposal as well. The complete listing of Basic Composer Actions can be found in Chapter 7 of the Composer User's Guide. Chapter 8 contains a listing of the more Advanced Actions available to you.
In testing a UTS Component, you may encounter errors relating to Set Screen Text, Send Key and/or Check Screen actions. The result is a dialog similar to the following:
This section discusses possible error conditions and how to deal with errors like these.
Most of the errors you are likely to encounter at execution time will be related to Check Screen actions. Generally speaking, your Check Screen errors will be timeout errors which means that the go-ahead criteria you specified in the Check Screen setup dialog were not met within the Screen Wait imeout period. Clicking on Details in the error dialog will verify this. Therefore, you should first try to determine whether slow host response might be the real problem (in which case, the solution is to increase the Screen Wait time for the Check Screen action in question). If the error still occurs after the Screen Wait time has been increased, then you can be sure the error is due to an incorrect or inappropriate go-ahead condition in your Check Screen action.
This error happens when the ECMAScript expression you used for your Check Screen go-ahead happens to evaluate as false at execution time. Once again, it's important to realize that this sort of error can be triggered simply on the basis of slow host response (timeout). When the host is slow to respond, it means that your ECMAScript expression will be evaluated on the basis of whatever is in the screen buffer as of the moment of timeout. If no data (or insufficient data) have arrived, the expression is bound to evaluate as false.
To fix this sort of problem, either increase the Screen Wait time for this Check Screen action (if you suspect that the problem is host latency) or try modifying the logic in your ECMAScript expression.
Errors generated by Composer from Set Screen Text action will, in general, be rare. This is because you are given a great deal of leeway in your ability to send whatever you like to the screen. Where you will more often run into trouble is on the application side. Unisys hosts are very particular about the input they will accept. If the text you send in your Set Screen Text action is not what the host expects, you will receive host-side errors and the rest of your Composer Action model will not proceed as expected.The way to avoid problems here is to make sure that for every Set Screen Text/Send Key action combination, there is always a corresponding Check Screen action.
When you have a large Action Model (containing dozens or hundreds of Set Screen Text, Send Key and Check Screen actions), simply locating the action that's responsible for an error can be a challenge. One way to find the problematic action is to:
Select and Copy some of the text in the error dialog. (Click the Details button if need be, to expose the full error description. Highlight the relevant text, such as cursor coordinates. Then use Control-C to Copy.)
Of course, if you have multiple Check Screen actions that are based on identical go-ahead criteria, the foregoing technique won't necessarily be helpful. If that's the case, set a breakpoint at the midpoint of your Action Model, and run the component. If the error doesn't occur, move the breakpoint to a spot halfway between the original breakpoint and the end of the action list. (Otherwise, if the error does happen, set the breakpoint at a spot one quarter of the way down from the top of the action list.) Run the component again. Keep relocating the breakpoint, each time halving the distance between the last breakpoint or the top or bottom of the action list, as appropriate. In this way, you can quickly narrow down the location of the problematic action. (Using this "binary search" strategy, you should be able to debug an Action Model containing 128 actions in just 7 tries.)
You can perform second-based timing of your Action Model's actions by wrapping individual actions (or block of actions) in timing calls.
Click into the Action Model and place a new Function Action immediately before the action you wish to time. (Right-mouse-click, then New Action > Function.)
In the Function Action, enter an ECMAScript expression of the form:
Insert a new Function Action immediately after the action you wish to time.
In the Function Action, enter an ECMAScript expression of the form:
Create a Map Action that maps endTime – startTime to a temporary DOM element. (Right-mouse-click, New Action > Map.)
Run the Component. (Click the Execute button in the main toolbar.)
If you do extensive profiling of your Action Model, you will probably find that the overwhelming majority of execution time is spent in Check Screen actions. Two implications of this worth considering are:
ECMAScript expressions (in Map and/or Function actions) will seldom, if ever, be a performance consideration for the component as a whole.
Overall component performance rests on careful tuning of Screen Wait timeout values in Check Screen actions.
Finally, remember that testing is not truly complete until the deployed service has been tested (and proven reliable) on the app server.
For additional performance optimization through the use of shared connections, be sure to read the next chapter on Logon Components.
Copyright © 2004 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved. more ...
