Novell exteNd Composer™ 5250 Connect 5.0 www.novell.
Legal Notices Copyright © 2000, 2001, 2002, 2003, 2004 SilverStream Software, LLC. All rights reserved. Title to the Software and its documentation, and patents, copyrights and all other property rights applicable thereto, shall at all times remain solely and exclusively with SilverStream and its licensors, and you shall not take any action inconsistent with such title. The Software is protected by copyright laws and international treaty provisions.
Online Documentation: To access the online documentation for this and other Novell products, and to get updates, see www.novell.com/documentation. Novell Trademarks eDirectory is a trademark of Novell, Inc. exteNd is a trademark of Novell, Inc. exteNd Composer is a trademark of Novell, Inc. exteNd Director is a trademark of Novell, Inc. jBroker is a trademark of Novell, Inc. NetWare is a registered trademark of Novell, Inc. Novell is a registered trademark of Novell, Inc.
not be called "JDOM", nor may "JDOM" appear in their name, without prior written permission from the JDOM Project Management (pm@jdom.org). THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
Contents About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 1 Welcome to exteNd Composer and 5250 User Interface 11 Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 About exteNd Composer Connects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Connection Pool Management and Deployed Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 6 Advanced Features 107 The 5250 Multi Row Wizard. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Handling System Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 A Java Code Pages 133 About Encodings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
About This Guide Purpose The guide describes how to use exteNd Composer 5250 Connect, referred to as the 5250 Component Editor. The 5250 Component Editor is a separately-installed component editor in exteNd Composer. Audience The audience for the guide is developers and system integrators using exteNd Composer to create services and components which integrate 5250 applications.
Chapter 3, Creating a 5250 Component, describes the parts of the component editor. Chapter 4, Performing 5250 Actions, describes how to use the basic 5250 actions, as well as the 5250 Multi Row Wizard. Chapter 5, Logon Components, Connections and Connection Pools, describes how to create logon components, connections and connection pools. Chapter 6, Advanced Features, describes dealing with multi-row and multi-screen data, and gives some tips on handling systems messages.
System input Operating system objects 9
5250 Connect User’s Guide
1 Welcome to exteNd Composer and 5250 User Interface Chapter 1 Before You Begin Welcome to the 5250 Connect Guide. This Guide is a companion to the exteNd Composer User’s Guide, which details how to use all the features of Composer, except the Connect Component Editors. If you haven’t looked at the Composer User's Guide yet, please familiarize yourself with it before using this Guide. exteNd Composer provides separate Component Editors for each Connect, like 5250.
About exteNd Composer Connects exteNd Composer is built upon a simple hub and spoke architecture (Fig.1-1). The hub is a robust XML transformation engine that accepts requests via XML documents, performs transformation processes on those documents and interfaces with XML-enabled applications, and returns an XML response document. The spokes, or Connects, are plug-in modules that "XML- enable" sources of data that are not XML-aware, bringing their data into the hub for processing as XML.
exteNd Composer Connects can be categorized by the integration strategy each one employs to XML-enable an information source. The integration strategies are a reflection of the major divisions used in modern systems designs for Internetbased computing architectures. Depending on your B2B needs and the architecture of your legacy applications, exteNd Composer can integrate your business systems at the User Interface, Program Logic, or Data levels.
What is the 5250 (TDS) Connect? The 5250 Connect XML-enables IBM AS/400-legacy system data using the User Interface integration strategy by hooking into the Terminal Data Stream (TDS). The term 5250 is commonly used to refer to the generic "dumb terminal" types used to connect to IBM AS/400 mid-range systems. When connecting to an IBM AS/400, the 5250 TDS uses IBM’s EBCDIC character-encoding scheme. The 5250 TDS, which was developed in the 1960s, emerged as that generation’s standard, and persists today.
About exteNd Composer’s 5250 Component Much like the XML Map component, the 5250 component is designed to map, transform, and transfer data between two different XML templates (i.e., request and response XML documents). However, it is specialized to make a TN5250 connection to an AS/400 application, process the data using elements from a DOM to a terminal session, and then map the results of the terminal session to an output DOM.
What Applications Can You Build Using the 5250 User Interface Component Editor? exteNd Composer, and consequently the 5250 Connect, can be applied to the the following types of applications: 1 Business to Business Web Service interactions such as supply chain applications. 2 Consumer to Business interactions such as self-service applications from Web Browsers. 3 Enterprise Application Integrations where information from heterogeneous systems is combined or chained together.
2 Getting Started with the 5250 Component Editor Chapter 2 The Sample Transactions For demonstration purposes, three transactions are used throughout this document in the samples presented: PART, GORD, and MENU. These transactions represent typical transactions used by operators. The PART transaction represents a scenario in which an operator uses a SKU number to drive an inquiry to a database. The GORD transaction represents a scenario in which an order for an item or several items is placed.
Creating a 5250 Connection Resource Once you have the XML templates in place, your next step will be to create a Connection Resource to access the AS/400 transaction. If you try to create a 5250 Component in the absence of any available Connection Resources, a dialog will appear, asking if you wish to create a Connection Resource. By answering Yes to this dialog, you will be taken to the appropriate wizard.
4 Click Next. The second page of the wizard appears. 5 Select the TN5250 Connection type from the pull-down menu. The dialog changes appearance to show just the fields necessary for creating the 5250 connection. 6 In the Host or IP Address field, enter the physical address or alias for the machine to which you are connecting. Your system administrator will provide you with this information, which is defined in a separate host file. 7 In the Telnet Port field, enter the number of the port.
11 The Terminal Type field lists the various types of terminals supported by 5250 components, including different screen sizes (i.e. 24x80 and 27x32). Select from the drop down list box the type of terminal you are using. 12 In the DBSC Support field, select from the drop down list box your choice of your Default, Double Encoding or SO/SI Using Ox1F. 13 In the DBCS Code Page field, select from the drop down list box the appropriate code page. 14 Click the checkbox to enable Version 2.
About Constant and Expression Driven Connections You can specify Connection parameter values in one of two ways: as Constants or as Expressions. A constant-based parameter uses the static value you supply in the Connection dialog every time the Connection is used. An expression-based parameter allows you to set the value using a programmatic expression (that is, an ECMAScript expression), which can result in a different value each time the connection is used at runtime.
4 Create an expression (optionally using the pick lists in the upper portion of the window) that evaluates to a valid parameter value at runtime. 5 Click OK. About Code Page Support Code Page support in exteNd Composer Connection Resources allows you to specify which Character Encoding scheme to use when translating characters sent between exteNd Composer and other host systems. exteNd Composer data uses Unicode character encoding (the Java and XML standard).
Creating a Style Sheet Resource An additional resource associated with the 5250 Connect is the style sheet resource. This allows you to create a style sheet with which to display the emulation screen in the native environment pane. ¾ To create a Style Sheet Resource: 1 Select File>New> xObject from the Composer menu, then open the Resource tab and select Terminal Style Sheet.
3 Click the Next button. The Style Sheet Editor window appears. 4 Use the Style Sheet Editor as described below to configure your style sheet: Style Sheet - Select a style sheet from this drop down list to change the appearance of the emulation screen in the native environment pane. This field initially contains the name you specified on the first page of the Terminal Style Sheet wizard. To create a new style sheet, type a name over one of the names in the list.
Border Style - Select one of three pre-defined borders from this drop down list. You cannot edit this control. Transparent Background - Select this check box if you want the GUI to have a transparent background. 5 Click OK. The newly created style sheet resource appears in Composer’s detail pane.
into a terminal when prompted. A short time later, the host responds by returning data to the terminal screen, and the operator relays this information to the customer. This session could be carried out by an exteNd Composer Web Service that uses a 5250 Component. The requested part number might be represented as a data element in an XML input document. The looked-up data returned from the host would appear in the component’s output document.
3 Creating a 5250 Component Chapter 3 Before Creating a 5250 Component As with all exteNd Composer components, the first step in creating a 5250 component is to specify the XML templates needed. For more information, see Creating a New XML Template in the Composer User’s Guide. Once you’ve specified the XML templates, you can create a component, using the template’s sample documents to represent the inputs and outputs processed by your component.
3 Enter a Name for the new 5250 Component. 4 Optionally, type Description text. 5 Click Next. The XML Input/Output Property Info panel of the New 5250 Component Wizard appears. 6 Specify the Input and Output templates as follows. 28 Type in a name for the template under Part if you wish the name to appear in the DOM as something other than “Input”.
7 Select a Template Category if it is different than the default category. Select a Template Name from the list of XML templates in the selected Template Category. To add additional input XML templates, click Add and choose a Template Category and Template Name for each. To remove an input XML template, select an entry and click Delete. Select an XML template for use as an Output DOM using the same steps outlined above.
As above, to add additional temp or fault XML templates, click Add and choose a Template Category and Template Name for each. Repeat as many times as desired. To remove an XML template, select an entry and click Delete. 11 Click Next. The Connection Info panel of the Create a New 5250 Component Wizard appears. 12 Select a Connection name from the pull down list. For more information on the 5250 Connection, see “Creating a 5250 Connection Resource” on page -18. 13 Click Finish.
About the 5250 Component Editor Window The 5250 Component Editor includes all the functionality of the XML Map Component Editor. It contains mapping panes for Input and Output XML documents as well as an Action pane. There are two key differences, however. The first is that the 5250 Component Editor also includes a Native Environment pane common to all Connects. It contains a 5250 emulator and appears black until you select the Record button in the 5250 Component Editor window.
Input pane Output pane ScreenDoc DOM Action Model pane Native Environment pane About the 5250 Native Environment Pane The 5250 Native Environment pane provides 5250 emulation of your AS/400 environment. From this pane, you can perform the following: Map data from an Input XML document (or other available DOM) and use it as input for a 5250 screen field.
About 5250 Keyboard Support The 5250 Native Environment pane supports the use of several attention identifier or AID keys: Enter, Clear, PA1-3, and F1-24. The function for each attention key varies, depending on the host application.
The new screen is displayed in the Native Environment pane. A Map Screen action appears in the Action Model. The Map Screen action is where you will add, change, and delete actions for this particular screen. Each time a new screen block is received as you build the component, a new Map Screen action is created. The Map Screen action calculates and records how many TDS fields were received for this particular screen.
About the ScreenDoc DOM Whenever a Map Screen action executes, a new screen is displayed in the Native Environment Pane (NEP). Each time a screen displays in NEP, an XML representation of the screen is created in the ScreenDoc DOM. (To make this DOM visible, you may need to select a View from the menu bar, then the Window Layout choice next pick the XML Layout Tab, and finally move ScreenDoc to the Visible list and click OK.
Attribute Meaning Length The fixed length of the field Row The screen row (1-24) where the field begins starting from the top 5250 Connect User’s Guide
About 5250-Specific Menu Bar Items View Menu Keypad Tool Bar—This selection displays a keypad tool bar for the 5250 terminal keys. It is docked to the top of the native environment pane. You can drag the keypad from this location, changing it to a floating window. When you close the floating window, the keypad returns to the native environment pane. To remove the keypad from sight, select View, then Keypad Tool bar from the menu bar.
About 5250-Specific Context Menu Items The 5250 Connect also includes context menu items that are specific to this Connect. To view the context menu, place your cursor in a field in the native environment pane and click the right mouse button. The context menu appears as shown. The function of the context menu items are as follows: Map - Allows you to create a Map action. This is done by highlighting a source in the Input DOM, then highlighting a source in the Native Environment Pane.
About 5250-Specific Buttons The 5250 Connect includes two additional tools on the component editor tool bar: the Record button and the Connect/Disconnect button. The Record button enables the automatic creation of actions in the Action Model as you interact with screen transactions. The Connect/Disconnect button controls your connection to the host. They appear as shown.
5250 Connect User’s Guide
4 Performing 5250 Actions Chapter 4 About Actions An action is similar to a programming statement in that it takes input in the form of parameters and performs specific tasks. Please see the chapters in the Composer User’s Guide devoted to Actions. Within the 5250 Component Editor, a set of instructions for processing XML documents or communicating with non-XML data sources is created as part of an Action Model.
About 5250-Specific Actions The 5250 Connect includes several actions that are specific to the 5250 and are not a part of the core exteNd Composer product. Table 4-1 5250 Action Description Map Screen Indicates location in the Action Model to place actions relative to a specific transaction screen. Multi Row This action allows you to specify the mapping of many-to-many data relationships between a DOM and the 5250 screen.
Multi Row The Multi Row action can be used to input data from an XML document to a 5250 screen, or to output data from a 5250 screen to an XML document. This action essentially creates repeat loops within the Action Model that map multiple rows of data automatically from one document or screen to another. The Multi Row action is discussed in detail in “The 5250 Multi Row Wizard” on page -107.
5250 Specific Expression Builder Extensions TN5250 Connection Resources have two items that are accessible from Action Expression Builder dialogs: the UserID and Password. These are for the UserID and Password fields that appear in the initial Composer screen when a connection is established. The user can map these variables into the screen, which eliminates the need for typing them into a map action that puts them into the screen.
Recording a 5250 Session The 5250 component, like all UI components, differs from other components because a major portion of the Action Model is built for you automatically. This happens by interacting with a live session from the host in the Native Environment pane and Composer recording your activity as a set of actions in the Action Model. In other components, you must manually create actions in the Action Model, which then perform mapping, transformation, and transferring tasks.
Record button Connect/Disconnect button NOTE: In addition to the buttons found on the XML Map Component Editor tool bar, the 5250 Component Editor includes a Record and Connect/Disconnect button as shown above. 2 Click the Record button. An input screen appears in the Native Environment pane and a “Map Screen” action is recorded in the Action Model pane.
3 Type in a UserID, Password, and any other requisite information. For the example shown, a UserID, Password, Program/Procedure entry, and Current Library entry are required. 4 Press the Enter key on the keyboard, or if you have the Toolbar visible (View>Keypad Toolbar), click the Enter button. In this example, an ENTER PART screen appears in the 5250 pane. 5 Drag the SKU data from the Input DOM to the SKU field in the 5250 ENTER PART screen.
NOTE: You can also use the Map Action to map the Input SKU to the ENTER PART screen SKU field; however, dragging and dropping is much quicker and easier. For more information on the Map Action feature, see the exteNd Composer User’s Guide. 48 6 Click the Enter button in the 5250 pane. The 5250 ENTER PART screen is populated with the SKU’s associated data. 7 Drag and drop an element from the ENTER PART screen to the Output DOM, for example, the SKU number.
Editing a Previously Recorded Action Model You will undoubtedly encounter times when you need to edit a previously recorded action model. Unlike editing other components, editing a 5250 component requires extra attention. When a 5250 component executes, it plays back a sequence of actions that expect certain screens and data to appear in order to work properly.
2 Navigate to the action in the Action Model where you’d like to make your edit and highlight the action. 3 Click the Toggle Breakpoint button. The highlighted action becomes red.
4 Click the Start Animation button. The animation tools become active. Run to Breakpoint/End 5 Click the Step to Breakpoint/End button. The Action Model executes all of the actions from the beginning to the breakpoint you set in step 3 above and appears as shown. Record button Pause button 6 Click the Pause button on the animation tool bar. 7 In the Component Editor tool bar, click the Record button. 8 Execute any additional actions that you’d like to make to the Action Model.
9 Select File, then Save, or click the Save button on the Component Editor tool bar. 10 Follow the instructions in “Using the Animation Tools” on page 58 to test your component. Editing Attention Keys Whenever you press Enter on the keyboard or click one of the many attention keys in the 5250 Native Environment pane while recording a session, an action is recorded in the Action Model. An example of this is shown below.
2 Navigate to the action in the Action Model after which you’d like to add the action and highlight the action. 3 Click the Toggle Breakpoint button. The highlighted action becomes red. Start animation 4 Toggle breakpoint Click the Start Animation button. The animation tools become active.
Run to Breakpoint/End 5 Click the Run to Breakpoint/End button. The Action Model executes all of the actions from the beginning to the breakpoint you set in step 3 above and appears as shown. Record button 54 6 Click the Pause button on the animation tool bar. 7 In the Component Editor tool bar, click the Record button. 8 Use Composer's drag and drop features to add new Map actions that interact with the screen. The new action will be added directly under the highlighted line.
9 Select File, then Save, or click the Save button on the Component Editor tool bar. 10 Follow the instructions in “Using the Animation Tools” on page 58 to test your component. About Adding Alias Actions If you are adding Map Actions in a loop that will be using an alias, perform the following steps: ¾ To Add an Alias Action to a previously recorded Action Model: 1 Open a component. 2 From the Action menu, select New Action, then Map. The Map Action dialog box displays.
Deleting an Action The following procedure explains how to delete an action in a previously recorded session ¾ To Delete an Action to a previously recorded Action Model: 1 Highlight the action line you want to delete 2 Click the right mouse button and select Delete from the menu. You may also highlight the line and press the Delete button on your keyboard. Executing your 5250 Component Composer includes animation tools that allow you to test your component.
¾ To execute a 5250 component: 1 Open a 5250 component. The 5250 Component Editor window appears. Execute button Animation tools 2 Select the Execute button. The actions in the Action Model execute and, when complete, a message appears. 3 Click OK.
4 From the View menu, select Expand XML Documents. This expands all of the parents, children, data elements, etc. of the XML Documents, which allows you to see the results of the executed component. If you do not expand the XML Documents, you won’t see if the data you wanted to move from the 5250 environment made it to the Output DOM.
2 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. Step Into button 3 Click the Step Into button. The first Map Screen action becomes highlighted. 4 Click the Step Into button again. The instruction that enters the command “PART” into the input field of the Native Environment pane becomes highlighted. 5 Click the Step Into button again. The word “PART” appears in the input line of the Native Environment pane.
6 Click the Step Into button again. The ENTER PART screen appears in the Native Environment pane. 7 Click the Step Into button again. In the Action Model, the instruction for dragging and dropping the SKU from the Input DOM to the SKU field of the ENTER PART screen field becomes highlighted.
8 Click the Step Into button again. The SKU data from the Input DOM appears in the SKU field of the ENTER PART screen. 9 Click the Step Into button again. The ENTER PART screen becomes populated with the data associated with the SKU number. 10 Click the Step Into button again. In the Action Model, the instruction to drag the SKU data from the ENTER PART screen to the Output DOM becomes highlighted.
11 Click the Step Into button again. The SKU data from the ENTER PART screen appears in the SKU field of the Output DOM. 12 Continue to click the Step Into button until all the data elements from the ENTER PART fields appear in the Output DOM, as shown. 13 Once complete, the following message appears.
Component with Connection Action The Component with Connection Action is unique because it lets your 5250 component call another component which will share the same connection. The action allows you to break up a large component into a main 5250 component and any number of sub-components so it is easier to maintain the Action Model. The ability to have the main component share with the sub-component the connection greatly reduces the amount of connection overhead and transaction navigation at run time.
3 From the Component Type pull down list, select the name of the component type. From the Component Name pull down list, select the name of the Component. 4 Select the passed ID if you need to change it from the pull down list. Select the returned ID if you need to change it from the pull down list. Click OK. 5 The following action appears in the map pane.
6 Animate the Main component and step into the Component with Connection action, the sub-component will now open. See how the screen changed to the component entitled “5250Called.” 7 Click on the Pause button on the Animation tool bar to enable the Record button.
8 Click on Record button and record the sub-component actions. 9 Save the component before stopping the animation process. 10 The 5250 Called window will now switch back to the 5250 Caller window.
Using Style Sheets in the Native Environment Pane The Style Sheet feature of the 5250 Component Editor provides you with options as to how you want to view the Native Environment pane. ¾ To apply a Style Sheet to the Native Environment pane: 1 From the Component menu on the 5250 Component Editor window, select Style Sheets. The Style Sheet Editor dialog appears. 2 Choose a Style Sheet from the Style Sheet drop down list.
Using Other Actions in the 5250 Component Editor In addition to the Map Screen and Multi Row action, 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. Handling Errors and Messages This section describes common errors you may see while executing the animation tools.
To correct this error, you must determine why the field count has changed and then try one of the following remedial actions. Double-click the Map Screen action that failed in the Action Model and change the field count variable to the correct number of fields.
There are additional circumstances where field counts can get out of sync. For example: 70 A spooler message from a print job arrives unexpectedly. To remedy this, the user would delete the errant Map Screen action from the Action Model. Applications that send the same screen but with a variable number of fields.
5 Logon Components,Connections and Connection Pools Chapter 5 This section discusses certain features available in the 5250 Connect designed to maximize performance of deployed services. About 5250 Terminal Session Performance The overall performance of any service that uses back-end connectivity is usually dependent on the time it takes to establish a connection and begin interacting with the host. Obtaining the connection is “expensive” in terms of wait time.
When you have a need for multiple tiers of pooling based on multiple security challenges within your system. (For example, users may need one set of logon credentials to get into the network, another to get into the mainframe, and another to get into the CICS region.) Serial log-in requirements may dictate the use of multiple logon components. When your service needs stateful “session-based” connections. When you need the performance advantages available through connection pooling.
The TN5250 connection resource is designed to make an individual connection to the host on an as-needed basis. The connection is made just-in-time and discarded as soon as the client is done. It is not reused in any way. This is the type of connection resource we created in Chapter 2 of this Guide. The Logon Connection, on the other hand, is different. It defines a pool of User IDs and passwords, each of which can make its own connection (TN5250).
A Connection Resource is always required in order to get to the host. (This is true for any Composer service that uses 5250 components.) For simplicity, this diagram shows the Connection Resource going directly to the host; in the real world, there may be intervening security layers. The Logon Component contains Actions (an action model) designed to find a particular screen of interest in the host program.
The Logon Connection’s Role in Pooling The Logon Connection differs from the ordinary “host-direct” connection resource in that it manages pooling (the sharing of connection instances and Logon Component instances at runtime). In the context of a Composer service, pooling not only allows reuse of (open) connections at runtime, it also increases the effective bandwidth of a deployed service. Consider the simple case where you’ve designed a 5250 component that uses a regular connection resource.
In this diagram, Logon Connection D is associated with four connections based on four UIDs (user IDs or credentials: A-thru-F). One is in use; another (UID ‘F’) is alive but not being used; and two are inactive but available (i.e., valid UIDs have been assigned, so these two connections can be made live at any time). How Many Pools Do I Need? It’s possible for several different 5250 components to draw from the same connection pool. It’s also possible for different components to draw from different pools.
How Do I Implement Pooling? To create the various objects required for pooling, you’ll go through the following basic steps (each of which will be discussed in greater detail in the sections to follow): 1 First, you’ll create a basic connection resource. The resource will be a standard TN5250 terminal connection. 2 Next, you’ll create a Logon Component that uses the connection resource defined in Step 1.
Instead of calling the Logon Component directly, using (for example) a Component Action, you will associate the Logon Component with a special connection resource called a Logon Connection. When your 5250 Terminal Component executes, it executes via the Logon Connection, which in turn executes the Logon Component. Logon, Keep Alive, and Logoff Actions The Logon Component provides several screen-management capabilities that are important factors in overall performance.
Logon Actions Actions you place in the Logon group are primarily concerned with signing into the host security screen and then navigating through the host menu system to a launch screen where each 5250 Terminal component’s Action Model will start. It is important that any 5250 Terminal component using a Logon component be able to start execution at the same common screen.
Maximizing Performance with the Logon Component The Logon Actions must be structured properly and therefore always begin and end with a Map Screen Action as shown in the screen below. The final Map Screen action in the Logon block guarantees that control is not turned over to the 5250 Component before the screen of interest has arrived in the connection. Without this, the 5250 Component could start at an invalid screen, throw an exception, and possibly corrupt a transaction.
NOTE: When possible, use the Try/On Error action to trap potential logon errors that may be recoverable. Otherwise, the UserID trying to establish the failed logon will be discarded from the pool decreasing the potential pool size. The pool size will remain smaller until you manually reset the discarded connections using the exteNd Composer Enterprise Server Console for 5250. See “Managing Pools” on page -100 for more details.
Keep Alive actions will be executed multiple times, at intervals defined by the Keep Alive parameter defined on the Pool Info dialog of the Logon Connection. The Inactivity Lifetime parameter (just below Keep Alive on the Pool Info dialog) tells Composer how long it should wait, in the event the connection is not actually used by a 5250 Terminal Component, before relinquishing the connection.
Maximizing Performance with Keep Alive Actions Map Screens must also be processed at the beginning and end of the Keep Alive section. Not only does the Keep Alive section prevent the connection from closing, but it must make sure that the proper launch screen is present when the execution is completed. Therefore, the first Map Screen checks to make sure that during the time the connection was available but not in use, that an unexpected screen didn’t arrive from the host.
Logon Component Life Cycle Each time a User ID is activated from the Logon Connection Pool, an instance of the Logon Component is created and associated with that User ID. Then the Logon actions are executed until the desired launch screen is reached. At this point the 5250 Terminal component execution begins. When it is finished another 5250 Terminal component using the same Logon Connection may begin executing, starting from the same launch screen.
Every Logon Connection is associated with a given Logon Component.
3 It allows a single User ID to use multiple connections if this is supported by the host system 4 It keeps a connection active to prevent host timeouts during inactive periods 5 It lets you specify when to remove a connection from the active pool 6 It sets a timeout period to use for a fully active pool to provide a free connection 7 It lets you specify error handling dependent on the state of the Logon Component used by the Logon Connection Many-to-One Relationship of Components to Logons In ord
Creating a Connection Pool Overview When creating a 5250 Terminal component, you normally first create the Connection object it needs. Similarly, when creating the objects comprising a Connection Pool, you must create certain objects first, starting (in essence) at the host and working your way backwards to the 5250 Terminal Component that will access the host.
Creating a Logon Component ¾ To create a 5250 Logon Component: 1 From the Composer File menu, select New > xObject, then open the Component tab and select 5250 Logon. The Header Info panel of the New xObject Wizard appears. 88 2 Type a Name for the connection object. 3 Optionally, type Description text. 4 Click Next and the Connection Info panel appears.
5 Select a standard terminal Connection from the drop down list. 6 Click Finish and the Logon Component Editor appears. NOTE: Recording actions follows a series of steps. The cursor must be positioned over Logon; turn Record on; when you are done, turn Record off. Position the cursor to KeepAlive; turn Record on; when you are done, turn Record off. Position the cursor to Logoff; turn Record on, when you are done, turn Record off.
9 Create the needed SEND Key actions in the KeepAlive section of the Action Model (a quick way is to copy an existing SEND key action, Paste it, and then modify the key code sent). 10 Record Logoff actions for properly exiting the host. 11 Save and Close the Logon Component. Creating a Logon Connection Using a Pool Connection ¾ To create a 5250 Logon Connection: 1 90 From the Composer File menu, select New > xObject, then open the Resource tab and select Connection or you can click on the icon.
2 Type a Name for the connection object. 3 Optionally, type Description text. 4 Click Next and the Connection Info panel appears. 5 For the Connection Type select “5250 Logon Connection” from the drop down list. 6 In the Connect Via control, select the Logon Component you just created. 7 Click on the Pool Info button and the Pool Info dialog appears.
8 Enter a Pool Size number. This represents the total number of connections you wish to make available in this pool. For each connection, you will be expected to supply a UserID/Password combination later. 9 Enter a KeepAlive time period. This number represents (in minutes) how often you wish to execute the KeepAlive actions in the associated Logon Component whenever the connection is active but free (i.e. not being used by a 5250 Terminal component).
12 Checking Override UID/PWD means you wish to specify User ID/Password combinations for use in the connection pool. When checked, this activates the Set USERIDs button. Click on the button to display the Set USERIDs and PASSWORDS dialog. Add Delete Paste On the Toolbar there are three icons: Add which adds an empty row, Delete, which deletes a highlighted row and Paste which allows you to copy/paste information from a spreadsheet into the table.
NOTE: If the Enable Telnet Environment checkbox from the logon component's connection is not checked, both the Pool Device Names checkbox and the Set Device Names… button are disabled. 16 Enter the required Device Names and click OK. On the Toolbar there are three icons: Add which adds an empty row, Delete, which deletes a highlighted row and Paste which allows you to copy/paste information from a spreadsheet into the table. For more on this, see the following Note.
20 Optionally check the Reuse connection only if expression is true control. This control allows you to enter an ECMAScript expression that evaluates to true or false based on some test of the launch screen. The purpose of the expression is to check to make sure the launch screen is the proper one each time a new 5250 Component is about to reuse an active free connection.
Maximizing Performance of 5250 Logon Connection To prevent 5250 Components from beginning execution on a connection that may have been left on an invalid screen by a previous 5250 component, the Logon Connection Resource allows the connection itself to check for the presence of the launch screen. This is accomplished by using the option titled “Reuse connection only if expression is true” on the Pool Info dialog of the Logon Connection.
¾ To create a 5250 Logon Connection: 1 From the Composer File menu, select New > xObject, then open the Resource tab and select Connection, or you can click on the icon. The Header Info panel of the New xObject Wizard appears. 2 Type a Name for the connection object. 3 Optionally, type Description text. 4 Click Next and the Connection Info panel appears. 5 For the Connection Type select “5250 Logon Connection” from the drop down list.
6 In the Connect Via control, select the Logon Component you just created. 7 The Screen wait (seconds) field displays the amount of time in seconds that a 5250 Terminal component will wait for a the next screen to arrive in the Map Action Pane. 8 Click the Session Connections radio button and then on the Session Info button.
Creating a 5250 Terminal Component That Uses Pooled Connections At this point, you are ready to create a 5250 Logon Component that can use the Connection Pool. For the most part, you will build the component as you would a normal 5250 Terminal Component, the only difference being the Connection you specify on the Connection Panel of the New Component Wizard. (You’ll specify a Logon Connection instead of a regular TN5250 Connection.
Maximizing Performance of 5250 Terminal Components Once the launch screen is obtained by the logon Component’s logon actions, it is handed to the 5250 Terminal Component that uses the connection. Then the 5250 Terminal component (when finished executing) leaves the screen handler back at the launch screen. If the 5250 Component finishes without being on the launch screen,(i.e.
NOTE: If you are not using the exteNd app server, enter a URL of this form: http://:/exteNdComposer/Console 2 Click on the exteNd Composer link You should see the main console page.
3 102 Click on the 5250 link in the left (nav) frame. The 5250 Console General Properties Screen will come into view.
Logon Components,Connections and Connection Pools 103
4 Click the Console button. A browser popup window (the Connection Pool Management Screen) displays with table if a connection exists for the 5250 Connect. 5 To initialize a Logon Connection Pool, enter its deployment context, the word "connection", and the actual connection name in the text field near the bottom of the screen. (See illustration above.) Then click the Initialize Pool button. NOTE: Refer to the appropriate Composer Enterprise Server guide for more detailed information.
Button Name Action Reset Discarded Resets the Discarded connections which are then reflected in the table Reset (Pool) Resets the Available and Discarded connections which are then reflected in the table Refill (Pool) Refills the pool with the maximum number of connections Additional Buttons on 5250 Connection Pool Manager Console Refresh Console Shows the current status of the connection pool Initialize Pool Initializes a Logon Connection Pool by entering a relative path to the deployed lib dire
Screen Synchronization Screen synchronization has special ramifications for users of pools. If a situation arises in which a user leaves a connection without the screen returning to its original state, the next user will begin a session with the screen in an unexpected state and an error will occur. To prevent this, we have a screen expression which the user can specify in the connection pool.
6 Advanced Features Chapter 6 The 5250 Connect includes several advanced features not available in other Composer Connects. Two of these features: Multi Row processing and Screen Handling, will be discussed in this chapter.
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 Composer tutorial, theses procedures are not intended for following along stepby-step.
3 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. 4 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.
5 The applicable header data is dragged and dropped from the input DOM to the corresponding field in the 5250 ENTER ORDER screen: Table 6-2 110 From: DOM Field To: 5250 ENTER ORDER Screen Field ODATE DATE: OCUST CUST: ONAME NAME: OBADDR BILL TO: (First line) OBCITY BILL TO: (Second line) OBST BILL TO: (Second line, 2-character field to the right of city) OBZIP BILL TO: (Second line, 5-character field to the right of state) OSADDR SHIP TO: (First line) OSCITY SHIP TO: (Second line) OSS
From: DOM Field To: 5250 ENTER ORDER Screen Field OPAY PAYMENT METHOD: OPAYINFO ACCOUNT #: The 5250 ENTER ORDER screen appears as shown.
6 The area of repetitive rows that will be selected for the Multi Row action is identified. 7 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.
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. 2 ¾ 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.
Expression builder 114 2 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. 3 In the Representing field, click the Expression builder button. The Expression builder window appears. 4 Expand the Input element in the XPath Content frame.
5 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. 6 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, Composer automatically creates an Alias. In this example, Composer created the alias called OITEM.
7 ¾ Click Next. The Iterate screen of the Multi Row Wizard appears. To iterate to the next record: NOTE: If you are outputting data, see “To use the Multi Row Wizard to output data:” on page -119. ¾ 116 1 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 -116), there is only one page of data, so there is no check mark in the Can Iterate to Next Record Set box. 2 Click Finish.
3 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: Table 6-3 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.
The final Action Model appears as shown. 118 4 Select File, then Save from the 5250 Component Editor menu bar, or click the Save button. 5 Follow the instructions in “To run the animation:” on page -58 to test your component.
¾ To use the Multi Row Wizard to output data: 1 Create a component per the instructions in “To create a new 5250 Component:” on page -27. For this example, a component called “5250SampleOutput” is created. The component is shown below in the 5250 Component Editor. Record button 2 Click the Record button. A sign on screen appears in the Native Environment pane.
3 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. 4 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.
8 The FILE BROWSE screen appears as shown. 9 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.
10 Edit the fields if desired. When satisfied with the parameters, click Next. The second panel of the Multi Row Wizard appears. Expression builder 11 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. 12 In the Representing field, click the Expression builder button. The Expression builder window appears.
14 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. 15 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, Composer automatically creates an Alias. In this example, Composer created the alias called ACCINFO.
16 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. 17 Check the Can Iterate to Next Record Set box. 18 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. 19 Click Next.
2 ¾ 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: 1 Highlight the Add all multi row map actions here! comment in the Action Model if not already highlighted. 2 Navigate to the first instance of ACCINFO in the Output DOM pane.
The Output DOM appears as shown. ¾ 4 Select File, then Save from the 5250 Component Editor menu bar, or click the Save button. 5 Follow the instructions in “To run the animation:” on page -58 to test your component. To edit the Multi Row Actions: 1 126 Click on the MultiRow Action that you wish to change in the Action Pane. The dialog box appears.
2 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.
Handling System Messages 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.
¾ ¾ General steps to creating a Screen Handler 1 Create a working 5250 Component that uses a 5250 Connection Resource. 2 Reproduce and capture the screen you wish to handle in a ScreenDoc DOM. 3 Select a field/data combination on the screen to uniquely identify this screen to the screen handler. 4 Add the screen handler to the Connection Resource by supplying a screen identity expression and an AID key for dispatching the screen.
4 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.” 5 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]) 6 Stop Animation by pressing Shift-F5, sign off the host system, and close the component, but do not save it.
14 Click on OK to save the Handler, and click on OK to save the connection. 15 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.
5250 Connect User’s Guide
A Java Code Pages Appendix A About Encodings exteNd Composer’s ability to perform character encoding conversions is tied directly to the Java VM in use. The supported encodings vary between different implementations of the Java 2 platform. Sun's Java 2 Software Development Kit, Standard Edition, v. 1.2.2 for Windows or Solaris and the Java 2 Runtime Environment, Standard Edition, v. 1.2.2 for Solaris support. The encodings can be found at the Sun web page: http://java.sun.com/products//jdk/1.
5250 Connect User’s Guide
B 5250 Glossary Appendix B AID Key Any of the following 5250-supported keys: Table B-1 5250 Key PC Key Enter Enter Clear ESC F1 through PF12 F1 through F12 F13 through F24 Shift F1 through Shift F12 PA1 through PA3 Ctrl F1 through Ctrl F3 Field A unit of data contained in a TDS. A field may be a label to display on the screen, an item of data, or special blank non-display fields. Each field has its own attributes that determine how it is displayed and if the area can be modified.
Multi Row Transform A special action for mapping repeating rows of data within a 5250 screen between a DOM and the 5250 screen. This action also transforms the ScreenDom and creates a hierarchical view of the screen. This action along with a Multi Row Group action, a Decision action, and additional Repeat actions are created by the Multi Row Wizard. Special care should be taken when editing any of these actions.
C Testing Appendix C Environmental Differences between Animation Testing and Deployment Testing There are significant environmental differences between Animation testing in Composer and Deployment testing. Both types of testing are needed to adequately verify the components and services you build. The differences are detailed in the table below. Table C-1 Testing in Composer Deployment Testing OS Win98 or WinNT or Win 2000. WinNT, Win2000 or Sun Solaris. Platform JRE (Java Runtime Environment).
Testing in Composer Deployment Testing Service and Component Inputs Input documents frequently come from sample XML documents on the local machine as well as DOMs from other services or components. Input documents are passed into the services and components via Service Triggers, or DOMs from other services or components.
D Reserved Words Appendix D The following terms are reserved words in exteNd Composer Connect for 5250 and should be avoided in any user created labels or scripts.
5250 Connect User’s Guide
Index Numerics 5250 (TDS) Connect 14 5250 component about 15 before creating 27 creating new 27 executing 56 steps commonly used to create 17 5250 component editor about the window 31 getting started 17 5250 Logon Component 77 5250 native environment pane 32 5250 session, recording 45 5250 specific actions 42 component menu 37 context menu 38 Expression Builder extensions 44 Map Screen 42 menu bar items 37 Multi Row 43 Send Attention Key 43 view menu 37 A About Adding Alias Actions 55 action menu 68 Action
D DBSC Support and code page defined 71 Deleting an Action 56 discarded connections 105 DOM 31 drag and drop 47, 107 20 L E EBCDIC 14 ECMAScript expressions 21 Enable Telnet Environment 94 environmental differences between animation and deployment testing 137 error messages connection pools 100 errors and messages 68 expression-based parameters 19, 21 exteNd Connects 12 F field, definition of 135 field count 69 Field Style Map 24 F key mappings 33 Form Map 24 G global variables in ECMAScript GORD 17 I
N PART 17 Pool Device Names 93 pools checking status 105 initializing 105 refilling 105 resetting 105 Screen Field Count Changed 68 screen handlers 128 Screen Synchronization 106 Screen wait 19 Send Attention Key about 43 definition of 136 Set Device Names 94 Start Column 113 Start Line 113 Static versus Dynamically Created Documents/Elements 96 steps in creating 88 Style Sheet 24, 38 applying 67 using in the native environment pane Style Sheet Editor window 24 Style Sheet resource creating 23 system mess
using to input data 108, 112 using to output data 119 X XML templates XSL 15, 138 144 25
