       |  |
5250 Connect User's Guide
CHAPTER 6
The 5250 Connect includes several advanced features not available in other Integration Manager Connects. Two of these features: Multi Row processing and Screen Handling, will be discussed in this chapter.
As discussed previously, the 5250 Connect includes drag and drop capabilities that allow you to drag data from an XML document into a 5250 or from a 5250 screen into an XML document quickly and easily; however, in cases where there are a variable number of rows, and possibly multiple screens of data, using the drag and drop method is not effective. To resolve this issue, the 5250 Connect includes a Multi Row Wizard that allows you to specific the mapping of many-to-many data relationships between a DOM and the 5250 screen. The Multi Row Wizard, which appears as an option in the Action> New Action menu of a 5250 component, can be used to input data from an XML document to the repeating area of a 5250 screen, or to output the repeating data from a 5250 screen to an XML document. The Multi Row Wizard essentially creates repeat loops within the Action Model that map multiple rows of data automatically from one document or screen to another until complete, regardless of the number of rows or number of screen pages.
There are many ways the Multi Row Wizard can be used when inputting or outputting multiple rows of data to and from XML documents and 5250 screens, and not every scenario can be addressed in this document. Two basic sample components are provided here that should give you a clear understanding of how the Multi Row Wizard is generally used.
The first procedure shows you a component that uses the Multi Row Wizard to input multiple elements of data from an XML document to a 5250 screen. The second procedure shows a component that uses the Multi Row Wizard to output multiple rows of data from a 5250 screen to an Output DOM.
The procedures in this section are strictly for demonstration purposes. Unlike the Integration Manager tutorial, theses procedures are not intended for following along step-by-step.
To prepare for using the Multi Row Wizard to input data:
First, a component is created per the instructions in "To create a new 5250 Component:" on page -21. For this example, the component is called "5250Sample." The component is shown below in the 5250 Component Editor.
The Record button is clicked and a sign-on screen appears in the Native Environment pane.
After signing on, the user navigates to the correct screen. In this example we must type a UserID and Password, and in the Program/Procedure field, "GORD" would be entered.
Enter is pressed on the keyboard.
NOTE: Alternatively, Enter may be selected on the 5250 tool bar within the Native Environment pane. To view this tool bar, select View from the 5250 Component Editor menu bar, then Keypad Toolbar.
This example then displays an "ENTER ORDER" 5250 screen in the Native Environment pane.
The applicable header data is dragged and dropped from the input DOM to the corresponding field in the 5250 ENTER ORDER screen:
The area of repetitive rows that will be selected for the Multi Row action is identified.
For multi-row actions, the user needs to define the area that contains repeating data either manually or by highlighting the area. In this example, the user drags the cursor over the line item input field area in the 5250 ENTER ORDER screen, beginning in the upper left corner and moving to the lower right corner. A gray background highlight appears over the drag marquee.
NOTE: Make sure that you start your drag process with your cursor outside of the first field. If you start dragging within a field, Integration Manager assumes you are trying to move the field itself.
To use the Multi Row
Wizard to input data:
NOTE: If you are outputting data, see "To use the Multi Row Wizard to output data:" on page -85.
From the 5250 Component Editor menu, select Action, then New Action, then Multi Row. The Multi Row Wizard appears. The wizard automatically fills in the dialog based on the area you highlighted.
If you would like to edit the fields or you did not highlight an area, you would do so as follows:
NOTE: The 5250 screen is comprised of 24 lines x 80 columns.
Start Line—This is the first row from the top where you want the wizard to start counting rows.
Start Column—This is the first column where you want the wizard to begin. Column 1 is the first column on the left.
# Records Down—This is the number of records you want the wizard to include in the loop.
# Records Across—It is a common practice for COBOL programmers to list records down a page and then continue to wrap records back to the top. The result is several records side-by-side down a page. You would use this field to specify how many records are listed side-by-side in a given row.
# Lines/Record—If a record is longer than 80 characters, it wraps to the next line. If it exceeds 160 characters, it wraps to a third line. You need to indicate how many lines are required per record.
# Columns/Record—This field indicates how many columns are included in the record, 80 being the maximum.
Edit the fields if desired. When satisfied with the parameters, click Next. The second panel of the Multi Row Wizard appears.
To set up a repeat action in the Multi Row Wizard:
NOTE: If you are outputting data, see "To use the Multi Row Wizard to output data:" on page -85.
After completing the first panel of the Multi Row Wizard, continue as follows.
Select the Input radio button in the Use XML As area. This panel is used to create a repeat action for processing the multiple elements or screen rows. Its use is similar to the basic "Repeat for Element" action available in all components.
In the Representing field, click the Expression builder button. The Expression builder window appears.
Navigate to the OITEM element and double click. The expression appears in the comment pane in the bottom of the window. For this example, the OITEM element is the one on which we will loop.
Click OK. You are returned to the second screen of the Multi Row Wizard, which now appears with the new expression in the Representing field.
NOTE: When using the Expression builder, Integration Manager automatically creates an Alias. In this example, Integration Manager created the alias called OITEM. For more information on Aliases, please see the Integration Manager User's Guide.
Click Next. The Iterate screen of the Multi Row Wizard appears.
To iterate to the n
ext record:
NOTE: If you are outputting data, see "To use the Multi Row Wizard to output data:" on page -85.
This screen allows you to tell the Multi Row Wizard what to do when it encounters an end of page. In the example (see "To add Multi Row Actions to input data:" on page -83), there is only one page of data, so there is no check mark in the Can Iterate to Next Record Set box.
Click Finish. The Multi Row actions you created in the wizard appear in the Action Model pane, with the Add all multi row map actions here! comment highlighted.
To add Multi Row Actions to input data:
Highlight the Add all multi row map actions here! comment in the Action Model if not already highlighted.
Navigate to the first instance of OITEM in the Input DOM pane.
Drag and drop the children of OITEM into the applicable fields in the first row of line item fields in the 5250 screen as follows:
|
From: Input DOM |
To: ENTER ORDER 5250 Screen |
|---|---|
|
OISKU |
PART |
|
OIDESC |
DESCRIPTION |
|
OIQTY |
QTY |
|
OICOST |
COST |
The Input DOM and ENTER ORDER 5250 screens appear as shown.
The Action Model pane appears as shown.
Notice that Map actions within the Multi Row actions block reference fields by their relative position in the row and not their absolute position within the screen. So the target of the first Map action is $RECORD/FIELD[1]. Using drag and drop to create your Map actions within the context of the Multi Row will create and assign these field indexes for you automatically.
Select File, then Save from the 5250 Component Editor menu bar, or click the Save button.
Follow the instructions in "To run the animation:" on page -41 to test your component.
To use the Multi Row Wizard to output data:
Create a component per the instructions in "To create a new 5250 Component:" on page -21. For this example, a component called "5250SampleOutput" is created. The component is shown below in the 5250 Component Editor.
Click the Record button. A sign on screen appears in the Native Environment pane.
Navigate to the correct screen. For this example, you would type in a UserID and Password and in the Program/Procedure field, "MENU" would be entered.
Press Enter on the keyboard. This example displays an "INSTRUCTIONS" 5250 screen in the Native Environment pane.
NOTE: Alternatively, you may select Enter on the 5250 tool bar within the Native Environment pane. To view this tool bar, select View from the 5250 Component Editor menu bar, then Keypad Toolbar.
In this example, "BRWS" is entered in the TRANSACTION field and "10001" in the NUMBER field.
Press Enter on the keyboard. A "FILE BROWSE" 5250 screen appears.
For multi-row actions the user needs to define the area that contains repeating data either manually or by highlighting the area. In this example, the user identifies the data area and drags the cursor it, beginning in the upper right hand corner and moving to the lower left hand corner. A gray background highlight appears over the drag marquee.
NOTE: Make sure that you start your drag process with your cursor outside of the first field. If you start dragging within a field, Integration Manager assumes you are trying to move the field itself.
From the 5250 Component Editor menu, select Action, then New Action, then Multi Row. The Multi Row Wizard appears. The wizard automatically fills in the dialog based on the area you highlighted in the previous step.
Edit the fields if desired. When satisfied with the parameters, click Next. The second panel of the Multi Row Wizard appears.
Select the Output radio button for Use XML As. This panel is used to create a repeat action for processing the multiple elements or screen rows. Its use is similar to the basic "Repeat for Element" action available in all components.
In the Representing field, click the Expression builder button. The Expression builder window appears.
Navigate to the ACCINFO element and double click. The expression appears in the comment pane in the bottom of the window. For this example, the ACCINFO element is the one on which we will loop.
Click OK. You are returned to the second screen of the Multi Row Wizard, which now appears with the new expression in the Representing field.
NOTE: When using the Expression builder, Integration Manager automatically creates an Alias. In this example, Integration Manager created the alias called ACCINFO. For more information on aliases, please see the Integration Manager User's Guide.
Click the Next button. The Iterate screen of the Multi Row Wizard appears. This screen tells the wizard what to do when it encounters an end of page.
Select F1 from the Iterate by attention key pull down list.
NOTE: The 5250 screen itself contains the instructions for the iteration keys. For this example, the FILE BROWSE screen included instructions that said to use the F1 key to page forward.
To complete the Boundary parameter page of the Multi Row Wizard:
Select the Blank Record radio button. This tells the wizard that a blank record indicates the end point of the loop action. You may also use the Expression builder to set a different indicator for the loop's end point. For more information on using the Expression builder, please see the Integration Manager User's Guide.
Click Finish. The Multi Row actions you created in the wizard appear in the Action Model pane, with the Add all multi row map actions here! comment highlighted.
To add the Multi Row Actions to output data:
Highlight the Add all multi row map actions here! comment in the Action Model if not already highlighted.
Navigate to the first instance of ACCINFO in the Output DOM pane.
Drag and drop the data from the 5250 FILE BROWSE screen to the Output DOM as follows:
|
From: FILE BROWSE |
To: Output DOM |
|---|---|
|
NUMBER |
ACCTID |
|
NAME |
NAME |
|
AMOUNT |
BALANCE |
Select File, then Save from the 5250 Component Editor menu bar, or click the Save button.
Follow the instructions in "To run the animation:" on page -41 to test your component.
To edit the Multi Row Actions:
Click on the MultiRow Action that you wish to change in the Action Pane. The dialog box appears.
Click on the appropriate tab, edit the fields and click OK. Refer to the Previous sections on using the MuliRow Wizard to Input or Output data.
A special feature of 5250 Connections is the ability to handle unpredictable message screens received during a terminal session that would be problematic to a 5250 Component during its execution. One example of this type of message screen is when the system administrator broadcasts notices to terminals warning them of system shutdowns or other events. The arrival of this screen is both unpredictable and unwanted during the normal execution of a 5250 Component interacting with a system transaction. These system messages are usually dispatched by a user hitting an AID key after having read them.
A TN5250 Connection allows you to define special screen handlers to respond to screens you wish to exclude from component processing. You can also define multiple screen handlers for a single connection. By defining screen handlers in the Connection Resource, you can define your handlers once and multiple components can take advantage of them by using the same connection.
NOTE: Connection screen handlers are not restricted to messages from the System Administrator. You can define a screen handler to respond to any screen received in the terminal data stream.
General steps to creating a Screen Handler
Create a working 5250 Component that uses a 5250 Connection Resource.
Reproduce and capture the screen you wish to handle in a ScreenDoc DOM.
Select a field/data combination on the screen to uniquely identify this screen to the screen handler.
Add the screen handler to the Connection Resource by supplying a screen identity expression and an AID key for dispatching the screen.
Specific steps to creating a Screen Handler
Create your 5250 Component as you normally would (i.e. create a Connection and other Resources as necessary and then build the component)
If your ScreenDoc DOM is not already visible, select View/Window Layout from the menu bar, followed by clicking the XML Layout tab. Then move ScreenDoc to the Visible list and click OK.
Save the component but leave it open. Capture the particular screen you wish to handle as follows.
NOTE: This will take some coordination with your system operator/administrator or whoever is responsible for generating the message screen you wish to handle.
Set a breakpoint on an action in the first Map Screen after the map Screen containing your Log in actions. (If this is a Logon Component, then set the breakpoint on the first action in the KeepAlive or Logout section.)
Press Enter and the system message screen will appear in the Native Environment Pane and the XML representation of the message will appear in the Screen Doc pane.
Choose a test field whose data will serve to identify this screen as one you wish to handle. For instance, you may choose the screen title field whose data is "Display Messages."
Hover your mouse pointer over the test field's XML representation in the ScreenDoc and note its full XPath location (e.g. ScreenDoc/SCREEN/FIELD[5])
Stop Animation by pressing Shift-F5, sign off the host system, and close the component, but do not save it.
In the Integration Manager window, select the Connection Resource for the component and open it.
On the Connection Info tab, click on the Advanced button and the Advanced dialog appears.
Check the Enable Telnet Environment checkbox to enable Telnet protocol support per RFC 2877 and RFC 1572.
Click on the Add button to add a line to define Screen handler.
In the Expression field, type an expression comparing the test data against the test field's XPath (e.g. ScreenDoc.XPath("string(SCREEN/FIELD[5])")= =" Display Messages").
NOTE: The XPath string function is applied to make sure the comparison works properly.
In the AID/DispatchKey field, select a key to send in response to the screen.
Click on OK to save the Handler, and click on OK to save the connection.
Test your System Screen Handler by animating the component past the Logon Map Screen actions, setting a breakpoint, initiating the system message, and continuing your animation past an Enter Send Key action.
Copyright © 2004 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved. more ...
