        |  |
 |
 |
 |
 |
 |
 |
 |
 |
 |
|
3270 Connect User's Guide
CHAPTER 2
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. And the MENU transaction represents a scenario in which an operator navigates through a menu-driven application to get to a particular screen. The PART, GORD, and MENU transactions are used to show you how to build Composer serviceComposer services that do the same things as the real life scenarios.
There are many ways to go about creating 3270 components; however, the most commonly used steps in creating a simple 3270 component are as follows:
Before you can create a 3270 Component, you need to create a Connection Resource to access the mainframe transaction.
When you create a Connection Resource for the 3270 Component, you have two choices: a TN3270 Connection or an EPI 3270 Connection. You can use the TN3270 Connection when you want to connect to an IBM mainframe environment, regardless of the application or Transaction Processing Monitor you are using. The EPI 3270 Connection is available when you want to connect directly to a CICS application region, that supports the External Presentation Interface (EPI) API. This connection allows you to utilize TCP/IP to access the EPI gateway on a CICS host.
You can specify Connection parameter values in one of two ways: as Constants or as Expressions. A constant based parameter uses the value you type in the Connection dialog every time the Connection is used. An expression-based parameter allows you to set the value using a programmatic expression, which can result in a different value each time the connection is used at runtime. This allows the Connection's behavior to be flexible and vary based on runtime conditions each time it is used.
For instance, one very simple use of an expression driven parameter in a EPI 3270 Connection would be to define the User ID and Password as PROJECT Variables (e.g. PROJECT.XPATH("USERCONFIG/MyDeployUser"). This way when you deploy the project, you can update the PROJECT Variables in the Deployment Wizard to values appropriate for the final deployment environment. At the other extreme, you could have a custom script that queries a Java business object in the Application Server to determine what User ID and Password to use.
To switch a parameter from Constant driven to Expression driven:
Click the RMB in the parameter field you are interested in changing.
Select Expression from the context menu and the editor button will appear or become enabled.
Click on the button and then create an expression that evaluates to a valid parameter value at runtime.
To create a 3270 Connection Resource:
From the Composer File menu, select New, then xObject, then open the Resource tab and select Connection.
NOTE: Alternatively, you can highlight Connection in the Composer window category pane, right click your mouse button, then select New.
To select an EPI 3270 Connection:
Select EPI 3270 Connection if you are connecting to a CICS application through the CICS Java Gateway.
In the Gateway URI field, enter the physical address of the machine to which you are connecting. In the example above, tcp://localhost.2006 is an alias for a physical machine where tcp:// is the protocol, localhost is the name of the machine, and 2006 is the default gateway to CICS.
NOTE: The Gateway URI field is case sensitive.
In the Server field, enter the region alias or server name. Your system administrator will provide you with this name, which is defined in a separate client initialization file.
The Screen wait (seconds) field, displays the amount of time in seconds that a 3270 Terminal component will wait for the arrival of the next screen in the Map Screen Action pane.
Enter a UserID and Password. They are simply defined here (password is encrypted). The user will have access to UserID and Password from ECMAScript, allowing them to map UserID and Password as a variable into the screen. This way, no one ever sees the passwords.
Select the Default check box if you'd like the settings you've entered to become the default settings for subsequent 3270 Connections.
Click on Advanced to display the System Handling dialog.
For more details on adding screens and AID keys to handle them, refer to the Screen Handling procedures mentioned in "Handling System Messages" below.
Click Finish. The newly created resource connection object appears in the Composer Connection Resource detail pane.
To select a TN3270 Connection:
Select a TN3270 Connection type i f you are using an application other than CICS.
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.
In the Telnet Port field, enter the number of the port. The default port number is 23.
In the Code Page field, specify a code page (See "About Code Page Support" on page 19).
The Screen wait (seconds) field, displays the amount of time in seconds that a 3270 Terminal component will wait for the arrival of the next screen in the Map Screen Action pane.
In the Delay (ms)/Small Size (bytes) field, enter an appropriate setting. This setting helps solve network performance issues by waiting extra time (ms) for a complete packet to arrive when the packet received is smaller than (bytes). In the above example, the network is instructed to wait an additional 1600 ms for a complete packet to arrive when the packet received is smaller than 24 bytes. An additional parameter, -waitEOR, allows a `screen complete' state to be determined by waiting for a packet containing EOR (End of Record).
Enter a UserID and Password. These are not actually submitted to the host during the establishment of a connection. They are simply defined here (password is encrypted). The user will have access to UserID and Password from ECMAScript, allowing them to map UserID and Password as a variable into the screen. This way, no one ever sees the passwords.
In the Terminal Type field, lists the various types of terminals supported by 3270 components, including different screen sizes (i.e. 24x80 and 27x32). Select from the drop down list box the type of terminal you are using.
Click on Advanced to display the System Handling dialog.
For more details on adding screens and AID keys to handle them, refer to the Screen Handling procedures mentioned in "Handling System Messages" below.
Select the Default check box if you'd like the settings you've entered to become the default settings for subsequent TN3270 Connections.
Click Finish. The newly created resource connection object appears in the Composer Connection Resource detail pane.
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). Existing legacy and other host systems use a variety of character encoding schemes (i.e., Code Pages) specific for their language or usage. A mechanism is needed to translate the character encoding between these systems if they are to communicate with one another. This is handled in exteNd Composer by specifying the Code Page used by a host system in the Connection Resource used to access that system. For more information on encoding, see Java Code Pages.
A special feature of 3270 Connections is the ability to handle unpredictable message screens received during a terminal session that would be problematic to a 3270 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 3270 Component interacting with a system transaction. These system messages are usually dispatched by a user hitting an AID key after having read them.
Both types of 3270 Connections (TN3270 and EPI 3270) allow 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 3270 Component that uses a 3270 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 3270 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.
a. 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.)
b. Animate the component by pressing F5.
c. Run to the Breakpoint by pressing F9.
d. Pause the Animation by pressing F6.
e. Initiate the system message.
f. 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 Composer window, select the Connection Resource for the component and open it.
On the Connection Info tab, press click on the Advanced button and the System Screen handling dialog appears.
Check to Enable TN3270E protocol support. If the checkbox is unchecked, disable and clear the Resource Name Text field.
Enter the Resource Name used in the TN3270 Connect, leave blank if the Server is supplying the name. If you right-click on the Resource Name field, you can change the value from a constant to an Expression and use ECMAScript to fill in the value.
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.
An additional resource associated with the 3270 Connector 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:
Select File>New>xObject from the Composer menu, then click on the Resource tab and select Terminal Style Sheet.
NOTE: Alternatively, you may highlight Terminal Style Sheet in the Resource section of Composer's category pane, click your right mouse button, and select New.
Type a Name for the new style sheet. Optionally, you may type in Description text.
Click the Next button. The Style Sheet Editor window appears.
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.
Set Default - Select this button to make the currently selected style sheet the default for a component.
Form MapCell Width/Height - Modify these settings for drawing characters that may be truncated by changing font types.Background - Select this button to see background color options for the style sheet.
Field Style Map3270 Style - This control lists the styles available from the TDS. You cannot edit these values. Select the style you wish to map to a new style you create.GUI Style - This control lists available styles you create. Type over an existing style to create a new one, then specify its Font, Foreground, and Background using the corresponding buttons.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.
Click OK. The newly created style sheet resource appears in Composer's detail pane.
In addition to a connection resource, a 3270 component may also require that you have already created XML templates so that you have sample documents for designing your component. See Chapter 5, Creating XML Templates in the exteNd Composer User's Guide for more information.
In many cases, your input documents will be designed to contain data that a terminal operator might type into the transaction interactively. Likewise, the output documents are designed to receive data returned to the screen as a result of the operator's input. For example, in a business scenario, a terminal operator may receive a phone request from a customer interested in the price or availability of an item. The customer gives the operator a SKU number, which he or she enters into the system. This represents a SKU number in an input document. Likewise, when the operator's terminal receives information back from the mainframe, based on the SKU, and the operator provides this information back to the customer, this represents the output document.
Also, if your component design calls for any other xObject resources such as custom scripts or code table maps, it is best to create these before creating the 3270 Component. For more information, see the exteNd Composer User's Guide.
Copyright © 2003 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved. more ...
