        |  |
 |
 |
 |
 |
 |
 |
 |
 |
 |
|
T27 Connect User's Guide
CHAPTER 5
For demonstration purposes, this guide uses a menu-driven system interface called MARC, Menu-Assisted Resource Control, 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 T27 terminals.
The T27 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 T27 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 T27 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 T27 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 T27 Components, such as:
Drag-and-drop mapping of Input DOM elements to T27-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 input XML document that contains several transactional commands for the MARC system to process. The goal of this particular component is to process these commands on MARC to determine the last job completed and place the name of that job in the Output DOM.
Create a T27 Component per the procedure shown in Chapter 3, "Creating a T27 Component".
Once created, the T27 Component Editor window appears, with the words "T27 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.
Drag the MARCINPUT/LOGIN node from the Input DOM to the first field in the Native Environment Pane. (Don't worry about exact placement within the field.) "SALES2" (without quotation marks) appears as your usercode and a new Set Screen Text action appears automatically in the Action Model.
Again, drag the MARCINPUT/LOGIN node from the Input DOM, but this time place it in the second field in the Native Environment Pane. ("SALES2" will not appear in the password field because it is a protected field on this screen.) A second Set Screen Text action appears automatically in the Action Model. If you examine the two actions, you will notice that they differ only in their row/column placements.
Press the F12 Key. You will see that a Send Key Transmit Action is added to your Action Model.
In response to the Set Screen Text and Send Key Actions, the T27 screen redraws itself into the Home Menu:
As discussed above in Chapter 4, "The Check Screen Action" it is a wise idea to make sure you are on the correct screen before proceeding. To do this, begin by dragging your cursor over the word "MARC" 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 word starts and ends. Using your 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 word "MARC" does 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. The MARC program has a relatively quick response time. (Even so, 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 your Action Model.
Now, let's map something from the Native Environment panel back to the Output DOM. Suppose you are interested in verifying what type of Unisys mainframe you're working on. The lower left-hand corner of the emulator screen tells you this information. Click and Drag your cursor from the word Unisys to the beginning of the word MARC. Again, as you click and drag, the onscreen row/column coordinates of the selected area are displayed in the status line.
Drag the information you have highlighted into the SYSINFO node of the Output DOM. A new Map Action appears in the Action Model:
Having verified that you are on the correct screen and using the correct system, you can begin typing some commands. Click anywhere in the "Choice:" field of the T27 environment pane and type JD.
NOTE: Unisys commands are often case-sensitive and are often entered in ALL CAPS.
A new Set Screen Text action appears automatically in your component's action list. Notice that the letters `JD' are already in the action along with the screen coordinates for the field.
Being a T27 connection, nothing will happen until you press the Transmit key, so press F12 again to add another Send Key Transmit action to the model.
In response to the `JD' command you transmitted, the host program sends a new menu screen shown below.
As always, it is a good idea to make sure you are on the expected screen, so highlight the letters "JD" at the top of the screen and right click to create another Check Screen Action to evaluate your screen's readiness to continue. In this example, the expression will be set to:
Screen.getText(1,11,2) == "JD"
Click OK and your Check Screen action appears in the action list.
Drag the MARCINPUT/JOBS node from the Input DOM to the Choice: field in the Native Environment Pane. "C" (without quotation marks) appears in the field and a new Set Screen Text action appears automatically in the Action Model. In this menu, "C" is an abbreviation for "Completed Jobs".
Add another Check Screen Action to ensure that you are in the correct menu. This time, check for the word "OUTPUT":
In the Native Environment Pane, select the name of the first completed job by highlighting the terminal-screen text in row 8 from column 35 to wherever the text ends, by clicking and dragging the mouse. The text will appear highlighted.
Lift your finger off the mouse button and place the mouse over the selected text. Click-drag the selection to the Output DOM MARCOUTPUT/COMPLETEJOBS node. The selected text is inserted into the DOM at the desired location, and a new Map Action is generated in the Action Model automatically.
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 T27 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 T27 Component requires extra attention. When a T27 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 T27 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 MARC example (above), the goal was to find out what jobs had been completed and map the name of the most recent of those jobs to the Output DOM. The name of this job could have been used as input to another component or to a web service.
By simple visual inspection of the OUTPUT menu of the terminal emulator screen, it's easy to see that several jobs were complete, not just the one mapped in the example. Suppose you wanted know the job numbers, names and times of completion for all jobs? To do this, you would need to iterate through several lines of the terminal screen, placing the key values in the Output DOM. This could be accomplished using 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 T27 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 a single value from the list of completed jobs into a single pre-exising node in the Output DOM. Here, each job 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 T27 Component. The T27 Component Editor window appears.
Select the Execute button. All the actions in the Action Model execute in order. 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" 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 T27 Component using Animation Tools:
Open a T27 Component. The component appears in the T27 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 becomes active.
Click the Step Into button. The first Check Screen action becomes highlighted.
Click the Step Into button 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.
T27-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 T27 interaction (via an Action Model) challenging. Suggestions on how to deal with these issues, as well as an example, are given below.
A common requirement in T27 computing is to capture a data set that spans multiple screens. If this is the case, most Unisys hosts will display a "+" sign in the Action field to indicate that the data continues on the next screen.
It is not always obvious how many screens' worth of data there may be. Generally, the only clue that you have 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 T27 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 F12), 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. MARC 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, MARC makes 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.
A completed Action Model which scrolls through two screens of data and eliminates redundancies would look something like the one below.
NOTE: In order to accomodate the large size of this screen, this action model picks up where the one in "Recording a T27 Session" earlier in this chapter left off.
The following tips may be helpful to you in building reliable T27 Components.
Always follow a Set Screen Text Action with a Send Key Action.
Always follow your Send Key Action 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 T27 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 the Details button on 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 © 2003 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved. more ...
