Transform 3270 green screens into Web Services

Transform 3270 green screens into Web Services
by using IBM Rational Host Access Transformation Services
for Multiplatforms
Level: Introductory
April 2010
Contents
IBM Enterprise Modernization Sandbox for System z ..................................................... 1
About this series ...................................................................................................... 4
About this Tutorial .................................................................................................. 4
Objectives .............................................................................................................. 4
Prerequisites ........................................................................................................... 4
System Requirements............................................................................................... 4
Glossary ................................................................................................................. 4
Perspectives............................................................................................................ 5
Open the HATS perspective ......................................................................................................................................6
Prepare the test environment .................................................................................... 7
Use SSL Encryption for the Host Connection ...............................................................11
Lesson checkpoint...................................................................................................13
HATS macro naming conventions ..............................................................................14
Record the FileBrowse macro ....................................................................................14
Navigate to the OPERATOR INSTRUCTIONS screen ...........................................................................................16
Add a macro prompt ...............................................................................................................................................19
Extract the data.......................................................................................................................................................20
The signoff ..............................................................................................................................................................22
Test the FileBrowse macro .....................................................................................................................................23
Test the macro using an incorrect value.................................................................................................................24
Enhancing the macro using the Visual Macro Editor......................................................25
Open the VME.........................................................................................................................................................26
Add a new macro screen .........................................................................................................................................30
Retest the macro......................................................................................................................................................40
Create an Integration Object ..................................................................................................................................40
Create Web Services support files .........................................................................................................................41
Create the Web service ...........................................................................................................................................42
Test the Web service using the Web Services Explorer..................................................48
Test the Web service with a non-numeric value......................................................................................................53
Conclusion .............................................................................................................55
Trademarks............................................................................................................55
Resources ..............................................................................................................55
Before you start
About this series
Walk through this scenario and others online as part of the Enterprise Modernization sandbox for
System z®
About this Tutorial
This tutorial teaches you how to use IBM® Rational® Host Access Transformation Services
(HATS) to create a Web service that exposes logic contained in an IBM® System z® 3270
application. You will learn how to create a HATS project, record a macro to navigate through
the screens of the transaction, generate a Java™ bean wrapper for the macro, and to create
a Web service using the tooling provided in the IBM® Rational® Software Delivery Platform.
Once the Web service is built, you will learn how to use the Web Services Explorer to test
the service.
Objectives
•
Use the HATS Toolkit to create a Web project capable of containing a Web service
•
Use the HATS Host Terminal to record a macro
•
Use the Visual Macro Editor to enhance a macro
•
Create an Integration Object Java class that drives the macro
•
Create a Web service that calls the Integration Object
•
Test the Web service in the Web Services Explorer
•
Total time: 90 minutes
Prerequisites
•
Basic IDE skills
•
Basic understanding of terminal applications
System Requirements
This tutorial requires the Enterprise Modernization sandbox environment.
Glossary
Macro: Automates interactions with the host. Macros can send commands to the host,
enter data into entry fields, extract data from the host, and be used to navigate screens on
behalf of the user. Macros are created in either the HATS Host Terminal or the Visual Macro
Editor.
Integration Object: A bean that encapsulates an interaction with a host screen or a series
of host screens. Integration Objects are constructed from macros and can be included in
Web services or HATS Enterprise JavaBeans (EJB) projects.
Web service: An operation that can be published, located, and invoked programmatically
over the Web. A HATS Web service drives a HATS Integration Object, which invokes a HATS
macro.
Getting Started
Perspectives
Rational workbench uses perspectives to group editors and views that pertain to particular
development tasks.
For example, the IBM® z/OS® Projects perspective contains views such as z/OS Projects,
z/OS File System Mapping, Remote System Details, and so on. The HATS perspective
contains views such as HATS Projects, Navigator, Console, Servers, and so on.
The name of the active perspective appears on the left side of the title bar of the Rational
workbench. In Figure 2, the name of the active perspective is Host Access Transformation
Services. If it says anything else, you will need to manually open the Host Access
Transformation Services perspective.
Figure 1: HATS Perspective in Rational Application Developer
ALT: HATS Projects tab on left, Welcome to HATS right
Open the HATS perspective
When you access the System z Enterprise Modernization Sandbox, Rational Developer for
System z should automatically start up. It will be open to the Remotes Systems
perspective.
1. Open the HATS perspective: select Window > Open Perspective > Other > Host
Access Transformation Services, as shown in Figure 2, and then click the OK button.
The views associated with the Host Access Transformation Services perspective will appear.
Figure 2: Opening the HATS Perspective
ALT: menu command and Open Perspective dialog
Prepare the test environment
By default the Rational workbench internal WebSphere Application Servers are set to
automatically publish every 15 seconds. As a result, sometimes the HATS application will
load, but other times it will appear there is a problem because the HATS application JSP file
will not be fully loaded in the Web browser. Make the following changes to prevent this:
2. Open the Servers view tab at the bottom of the workbench window and then:
2.1Select WebSphere Application Server v7.0
2.2 Right-click and select Open.
Figure 3: Open the server editor
ALT: menu command
3. In the Server section:
3.1 Click the Manually provide connection settings radio button.
3.2 Deselect the RMI radio button.
3.3Click Terminate server on workbench shutdown
Figure 4: Select the SOAP connection type
4. In the Automatic Publishing section, select the Never publish automatically radio
button.
Figure 5: Select Never publish automatically
ALT: Specify when to publish
5. Click File > Save to save the server configuration.
6. Close the server configuration editor window.
Create a HATS project
This section of the tutorial will demonstrate how to create a HATS project and macro. From
within the Host Access Transformation Services perspective, you can launch the wizard to
create a new project. You will use the Host Terminal to record the initial "main path"
macro. In the next section, you will use the Visual Macro Editor to enhance the macro.
1. Click File > New > HATS Project to launch the Create a Project wizard, as shown in
Figure 6 below.
Figure 6. Start to create a new project
ALT: menu command
2. In the Name field, type the name HATS3270SOA.
3. For the Deployment type, select Web, because HATS Web services are hosted in a
Web project.
4. Select WebSphere Application Server v7.0 from the Target server drop-down.
5. In the Enterprise application project field, type the name HATS3270SOA_EAR7. This
unique name will ensure that there are no conflicts when you deploy your application to
the server later. Your panel will look like that shown in Figure 7.
Figure 7: The Create a HATS Project wizard
ALT: referenced options selected or entered
6. Click Next to display the Connection Settings panel. The Connection Settings panel
enables you to set up the connection to your 3270 host system. Your Web service will
use this connection to communicate with the host application.
7. In the Host name field, type zserveros.demos.ibm.com
8. Select 3270E from the Type field.
9. Change the Port to “22.”
10. Accept the default values for the Code page, and Screen size. Your panel will look like
that shown in Figure 8.
Figure 8: Specify the connection settings
11. Click Next.
The Project Theme panel is not important when you build Web services. In a standard
HATS transformation project, a theme controls the basic appearance and behavior
characteristics for the application. For example, you can select the Classic terminal
emulator theme to enable emulator-like features, such as automatic field advance, in your
application by default.
12. Click Next.
The Default Template panel is also not important when you build Web services. In a
standard HATS transformation project, a template controls the basic layout and style (such
as color and font) of the application.
13. Click Finish to create the project.
After a few minutes, the new project will appear in the HATS Projects view, and the Project
Settings editor for the project will open.
If you were building a standard HATS transformation application, you could, at this point,
right-click the project (in the HATS Projects view) and select Debug on Server to run your
application on the server. Because the purpose of this tutorial is to show you how to create
a Web service, you can skip this step.
Use SSL Encryption for the Host Connection
The host that we will be working with requires that the TN3270 connection be made using
SSL encryption, so we will now configure the SSL encryption.
1. Expand the host connection folder (see Figure 9) and double-click the “main”
Figure 9: Opening the host connection
connection to open it in the connection editor.
2. Click the “Security” tab at the bottom of the “main” connection editor panel as shown
in Figure 10 below.
Figure 10: Security settings for the TN3270 connection
3. Click the “Enable SSL” box (see Figure 10 above).
4. Click the “Import” button to import the PKCS12 keystore into the project. Using the
browsing dialog that opens, browse to “My Documents\Downloads\” and select
the file: “CustomizedCAs.p12” file.
5. Enter the password “hod” (lowercase) in the Password input field and click the
“Verify” button. You should get a message dialog as shown below. Click “OK” to
clear the message.
Figure 11: Import CustomizedCAs.p12 succussful
6. Save the “main” connection configuration (Ctl-S , or click the diskette icon on the
tool bar) and then close the connection editing dialog by clicking the
7. Now test the TN3270 configuration by clicking the Host Terminal icon
on the
tool bar, or by doing a right-click on the HATS project (HATS3270SOA) and select
“Open HATS Host Terminal” => “main.” The terminal emulator should open and
you should get the connect screen for zserveros.demos.ibm.com as shown below.
8. If you do not get the welcome screen for zserveros, go back and check the
properties for the host connection. Is the port correct (port 22)? Is the host name
correct (zserveros.demos.ibm.com)? Is SSL encryption enabled and the
CustomizedCAs.p12 file imported correctly?
Lesson checkpoint
In this section, you learned how to:
•
•
•
•
Start the HATS toolkit
Create a new HATS project
Configure the TN3270 connection for SSL encryption.
Verify that the connection properties are correct.
Create the macro
A macro is a script that defines a flow through screens in your application. Typically, a
macro is responsible for performing a very specific task. For example, you might record a
macro that collects information about a customer based on a supplied customer
identification number (this happens to be the scenario described in later steps of this
tutorial). Macros can be input only, output only, input and output, or purely navigational.
The input and output you define in a macro will be the input and output of your eventual
Web service.
For this tutorial, you will create a macro that signs in, navigates to a customer information
application, and retrieves information about a customer.
This tutorial describes using the HATS Host Terminal to record the macro. Macros can also
be created using the HATS Visual Macro Editor (VME), but the Host Terminal allows you to
more quickly create the main flow of your macro. Later in this tutorial, you will use the VME
to add error handling to your macro.
HATS macro naming conventions
Certain naming conventions must be followed when you create Web services using the
WebSphere Application Server run time. These include:
• Method names must begin with a lower case letter.
• Class names must begin with an upper case letter.
• If a method or class name contains an underscore followed by a letter, the letter must
be an upper case letter.
• If a method or class name contains a number followed by a letter, the letter must be an
upper case letter.
Keep these naming restrictions in mind when you create macro names, create prompt
names, and extract names during macro creation. For more information on naming
restrictions, refer to the Rational workbench documentation.
The following tutorial instructions take into account these naming conventions.
Record the FileBrowse macro
In this section, you record the macro. The purpose of this macro is to navigate to the
details view of an account, and then present that information in the Web browser.
1. Right-click the HATS3270SOA project and then click Open HATS Host Terminal >
main, as shown in Figure 12.
Figure 12: Open HATS Host Terminal
ALT: menu command
2. When the DEMOnet screen appears, click the Record Macro button on the toolbar, as
shown in Figure 13.
Figure 13 Click the Record Macro button
ALT: button icon shows red and gray gears
3. On the Record Macro dialog, change the Name to FileBrowse, and then click Finish.
4. On the Define the starting screen of the macro dialog:
a. In the Screen Name field, change the name to Welcome, as shown in Figure 14.
This name, as well as the screen names entered later for the other screens,
will help you identify screens while you edit the macro.
Figure 14. Define screen recognition criteria
ALT: dialog with input field
b. Use your mouse to resize or draw a box around the words WELCOME TO
IBM, as shown in Figure 15. This text is used in screen recognition by HATS
to ensure that the macro is run starting from the correct host screen.
Figure 15: Draw a box around WELCOME TO IBM
ALT: DEMOnet screen shows ZSERVEROS, help desk number
c. For the String position, select At a specified position, as shown in Figure
16.
Figure 16: Select "At a specified position"
ALT: number of fields, and cursor and string position
d. Click Finish.
Navigate to the OPERATOR INSTRUCTIONS screen
As you navigate the host screens, everything you type on the screen, as well as every
keystroke and mouse click, is recorded.
5. On the WELCOME TO IBM screen enter CICSA as the selection, as shown in Figure 17,
and then press Enter.
Figure 17: Enter CICSA as the selection
ALT: screen shows available applications
6. While on the Signon to CICS screen, click the Define Screen Recognition Criteria
button, as shown in Figure 18.
Figure 18. Define criteria
ALT: button shows wand and computer monitor
7. On the Screen Recognition Criteria dialog:
a. Change the Screen Name to Signon.
b. If necessary, clear Total number of fields, Number of input fields, and
Cursor position
c. Select At a specified position
d. Click Finish
8. Sign on by entering the User ID ATDEMO and the Password DEMO4YOU, and then press
Enter.
The next screen is blank except for the text at the bottom of the screen: DFHCE3549 Signon is complete (Language ENU).
9. While you are on the blank screen, click the Define Screen Recognition Criteria
button.
10. On the Screen Recognition Criteria dialog:
a. Change the Screen Name to SignonComplete
b. If necessary, clear Total number of fields, Number of input fields, and
Cursor position
c. Select At a specified position
d. Click Finish
11. Enter the CICS transaction name MENU on the command line at the top of the screen,
as shown in Figure 19, and then press Enter.
Figure 19: Enter "menu" on the blank screen
ALT: cursor after the word menu
The MENU transaction is a sample application in which you can inquire about, browse, add,
and update account information.
Add a macro prompt
Next, you need to define a macro prompt so that data can be "prompted" from an end user.
12. While on the OPERATOR INSTRUCTIONS screen click the Define Screen Recognition
Criteria button.
13. On the Screen Recognition Criteria dialog:
a. Change the Screen Name to OperatorInstructions
b. Resize or draw a yellow box around the text OPERATOR INSTRUCTIONS
c. If necessary, clear Total number of fields, Number of input fields, and
Cursor position
d. Select At a specified position
e. Click Finish
14. On the host screen, type BRWS into the ENTER TRANSACTION field.
15. The cursor will now be in the NUMBER field. Click the Add Prompt Action button, as
shown in Figure 20. Prompts are used to request input from end users during run time.
Figure 20: Click the Add prompt button
ALT: button shows arrow from world to screen
16. On the Add Prompt Action dialog, enter the Name accountNumber, as shown in Figure
21. Make sure that you type the name exactly as shown, with a lowercase "a" and an
uppercase "N".
Figure 21: Name the prompt "accountNumber"
ALT: specify prompt name, value, and position
17. Accept the defaults for the other options, and then click OK.
18. On the Prompt dialog, enter the value 111111, as shown in Figure 22, and then click
OK. This value will not be hard coded into the macro, but will appear in the Number
field on the host screen so that the macro recording can continue.
Figure 22: Enter the number 111111
ALT: dialog with data field
19. Press the Enter key. You should now see the results of the browse operation, as shown
in Figure 23.
Figure 23: The file browse results
ALT: screen shows record's number, name, and amount
Extract the data
Now, you must define the target data (the account information to be queried) as a macro
extract. This will be used as an output variable to the Web service.
20. On the FILE BROWSE screen, click the Define Screen Recognition Criteria button.
21. On the Screen Recognition Criteria dialog:
a. Change the Screen Name to FileBrowse
b. Resize or draw a yellow box only around the text FILE BROWSE
c. If necessary, clear Total number of fields, Number of input fields, and
Cursor position
d. Select At a specified position
e. Click Finish
22. On the FILE BROWSE screen, draw a box around the first entry of results, as shown in
Figure 24, and then click the Add Extract Action button.
Figure 24: Specify the data to be extracted
ALT: button shows arrow from screen to world
23. On the Add Extract Action dialog enter the name results, as shown in Figure 25. Make
sure that you type the name exactly as shown, with a lowercase "r".
Figure 25: Name the extract "results"
ALT: dialog to specify name and position
24. Accept the defaults for the other options, and then click Finish.
The signoff
Now that the query extract has been defined, it is time to signoff.
25. From the File Browse host screen, press the Esc key to return to the OPERATOR
INSTRUCTIONS screen.
Note: By default in HATS, the Esc key is mapped to the Clear function.
26. While on the OPERATOR INSTRUCTIONS screen, click the Define Screen Recognition
Criteria button.
27. On the Screen Recognition Criteria dialog:
a. Change the Screen Name to OperatorInstructionsExit
b. Resize or draw a yellow box around the text OPERATOR INSTRUCTIONS
c. If necessary, clear Total number of fields, Number of input fields, and
Cursor position
d. Select At a specified position
e. Click Finish
28. Press Esc to return to the blank screen.
29. While on the blank screen, click the Define Screen Recognition Criteria button.
30. On the Screen Recognition Criteria dialog:
a. Change the Screen Name to Signoff
b. Click Finish
31. On the blank screen, type CESF LOGOFF, and then press Enter.
32. Click the Stop Macro button to end the macro recording on the WELCOME TO IBM
screen, as shown in Figure 26.
Figure 26: Stop macro recording
ALT: Host Terminal view
33. On the Define the exit screen of the macro dialog:
a. Change the Screen Name to ExitScreen
b. Resize or draw a yellow box around WELCOME TO IBM
c. Clear the Total number of fields, Number of input fields and Cursor
position check boxes
d. Select At a specified position
e. Click Finish.
34. Click the Save Macro button, as shown in Figure 27.
Figure 27: The Save Macro button
ALT: button shows disk and gear
Test the FileBrowse macro
35. Click the little black arrow next to the Play Macro button, and then click FileBrowse.
36. The Supply Prompt Values dialog appears. Enter 111111 in the Value field, as shown in
Figure 28, and then click OK.
Figure 28: Enter the number 111111 into the prompt
ALT: Supply Prompt Values dialog
The FileBrowse macro will automatically perform the following functions:
I.
Enter the text CICSA in the SELECTION field, and then Enter
II. Enter the User ID and Password, and then Enter
III. Enter the transaction name MENU, and then Enter
IV. Enter BRWS in the Transaction input field
V. Enter 111111 in the Number input field and then Enter
VI. Extract the first result from the FILE BROWSE screen, and then Enter
VII. Show the results of the query in the Extract Results dialog
VIII. Navigate back to the OPERATOR INSTRUCTIONS screen
IX. Sign off from CICS
37. Click the X to close Extract Results.
Test the macro using an incorrect value
38. Click the little black arrow next to the Play Macro button and then click FileBrowse.
39. The Supply Prompt Values dialog will appear. Enter some text (such as abc) into the
Value field, and then click OK.
The macro will start, but it will eventually time out, because there is an error condition.
As shown in Figure 29, the text on the title bar of the host terminal indicates that the
macro is still trying to run. Additionally, the Macro Run button will appear as a square red
button. The error message on the host screen is "ACCOUNT NUMBER MUST BE NUMERIC.
Figure 29: Error message due to non-numeric value
ALT: navigator on left, screen on right
Eventually, the message shown in Figure 30 (The host terminal does not match any
expected screens) will appear when the macro times out.
Figure 30: The macro timeout error
ALT: Macro Play Error dialog
Enhancing the macro using the Visual Macro Editor
The HATS Visual Macro Editor, or VME, is a graphical tool for creating new macros from
scratch, or enhancing macros recorded with the HATS Host Terminal. With the VME, you
can add new screens, flows, and actions to your macros. For this tutorial, you will define an
alternate flow for the error condition.
1. From the HATS Projects view in the workbench, expand the Macros folder.
Open the VME
2. Right-click the FileBrowse macro, and then select Open With > Visual Macro Editor
Technology, as shown in Figure 31.
Figure 31: Open the Visual Macro Editor
ALT: menu command
The VME opens, and you see a visual representation of your macro, as shown in Figure 32.
Figure 32: A visual representation of the macro
ALT: scrollable diagram
In order to handle the scenario where an invalid value is supplied, you need to navigate to
the OPERATOR INSTRUCTIONS screen using the VME, supply an invalid value, and then
add the resulting screen into the flow of your macro.
3. Click the VME Connect button (a yellow lightning bolt) near the bottom left of the editor
(just above the Design tab) to show (and connect to) the integrated terminal, as shown
in Figure 33.
Figure 33: Click the green VME Connect button
ALT: button shows green box and check mark
Unless your monitor is set to a high screen resolution, you may want to double-click the
FileBrowse.hma editor tab at the top of the workbench window to maximize the editor.
Your display will look similar to that shown in Figure 34.
Figure 34: The VME integrated terminal
ALT: Welcome screen with selection prompt
4. Click the Play button on the integrated terminal toolbar to play the macro, as shown in
Figure 35.
Figure 35: Click the VME Play Macro button
ALT: diagram above terminal screen
5. Just like in the Host Terminal, in HATS you see a prompt for you to supply a value for
the accountNumber. Supply an invalid value, such as abc, and then click OK.
HATS will play the macro and supply the account number into the appropriate field, but the
macro will stall because it is waiting for the File Browse screen to appear after the Operator
Instructions screen. Notice the error message just above the input fields, as shown in
Figure 36. You will add this screen into the flow of the macro in order to handle this error
scenario.
Figure 36: Account number must be numeric error
ALT: account number must be numeric error
Note: if you wait for 60 seconds, HATS will show a Macro Play Error message, because the
File Browse screen never appears, (the macro expects this screen to follow the Operator
Instructions screen).
Figure 37: A Macro Play Error popup appears when the macro times out
ALT: No expected screens matched
6. If the macro is still playing, click the Stop button on the toolbar to stop the playback, as
shown in Figure 38.
Figure 38: The VME Stop Macro button
ALT: Stop button highlighted
Add a new macro screen
You will now update the macro to handle the case where this error message appears on the
Operator Instructions screen. This screen only appears if a non-numeric value is supplied.
7. While on the screen with the error message, click the Add Screen button on the
integrated terminal toolbar (Figure 39) to open the Add Screen wizard.
Figure 39: The VME Add Screen button
ALT: button shows gear, screen, and plus sign
8. In the Name field, type MustBeNumeric.
9. From the Preceding screen drop-down, select the OperatorInstructions screen. This
tells HATS to prepare this new screen as a possible option after ENTER is sent while on
the Operator Instructions screen.
10. From the Next screen drop-down, select the Signoff screen. Your panel will look like
that shown in Figure 40.
Figure 40: Add a screen to the macro
ALT: Add Screen dialog with referenced options selected
11. Click Next.
12. The Screen Recognition Criteria panel enables you to configure the criteria that HATS
will use to identify the screen. For this screen, you will use text on the screen to identify
it.
a. Clear the check boxes for Total number of fields, Number of input fields,
and Cursor position.
b. Click the Add button to add new String (text) recognition criteria.
c. Use the mouse to select the ACCOUNT NUMBER MUST BE NUMERIC
message.
d. Select the radio button At a specified position.
e. Click OK. Your panel should look like that shown in Figure 41.
Figure 41: Screen recognition criteria for the new screen
ALT: Screen Recognition Criteria dialog
13. Click Next to show the Actions panel.
The Actions panel enables you to control what HATS does when this screen is encountered.
When you recorded the macro in the Host Terminal, HATS created Input actions for all
sequences of keystrokes. You also manually added an Extract action. For this screen, you
will extract the error message and make it available as an output variable to the Web
service.
14. Click the Add button.
15. Select the Extract action option, as shown in Figure 42.
Figure 42: Click the Extract action
ALT: list of actions with descriptions
16. Click Next.
17. In the Name field, type errorMessage.
18. Use the mouse to select the error message ACCOUNT NUMBER MUST BE NUMERIC, as
shown in Figure 43.
Figure 43: Select the error message
ALT: Screen to configure the extract action
19. Click Finish to add the action.
In order to properly exit the application and return to the sign on screen, the CLEAR
command needs to be sent to the host.
20. Click the Add button.
21. Select the Input action.
22. Click the Next button.
23. On the Input panel, click the drop-down list and then select the [clear] command, as
shown in Figure 44. By default, HATS maps the Esc key to the clear command.
Figure 44: Add the [clear] action
ALT: specify action to insert
24. Click Finish to add the action.
The Actions panel should now look like that shown in Figure 45.
Figure 45: The Extract and Input actions have been added to the list
ALT: list of Actions and Details
This indicates that a single extract action will be performed when this screen is
encountered, and then the [clear] command will be sent. (If the Input action is not the last
action in the list, select the Input action and then click the Down button to move the Input
action to the bottom of the list.)
25. Click Finish to add the screen. The result should look like that in Figure 46.
Figure 46: The new screen has been added to the macro
ALT: scrollable diagram with five elements
Notice how the VME has wired the new screen, MustBeNumeric, as a possible screen after
the OperatorInstructions screen and as a preceding screen to the Signoff screen, which
will allow the macro to properly exit the application and sign off.
26. In the design area, click the OperatorInstructions screen one time.
Notice that a "1" and "2" appear on the lines connecting the two possible next screens after
the CustomerInquiry screen. These numbers indicate the order in which HATS will
evaluate the recognition criteria defined in these screens when playing the macro.
Because the FileBrowse screen has a higher priority number (1 versus 2), HATS will first
look to see if this screen appears after Enter is pressed on the Customer Inquiry screen.
If the FileBrowse screen does not appear, HATS will look to see if the MustBeNumeric
screen appears. In this case, the ordering of the next screens is not terribly important,
because both possible next screens are unique and quite different from each other. But, in
other situations, the ordering of the next screens can be very important.
Figure 47: There are now two possible navigation paths in the macro
ALT: element with optional paths is highlighted
27. Save the macro by clicking File > Save.
28. Press the Esc key to return to the blank screen.
29. Type CESF LOGOFF to return to the DEMOnet WELCOME TO IBM screen.
Retest the macro
30. Press the Play button again to test the new flow. You will be prompted to supply a
customer number.
31. In the Value column, type abc (or any non-numeric value).
32. Click OK.
Note that the Extract Results window shows the extracted error message. Also note that
the path the macro took is highlighted in orange in the design area of the VME, as shown in
Figure 48. In addition, the macro correctly completed exiting the host application and
returned to the WELCOME TO IBM screen.
Figure 48: The path the macro took is highlighted in orange
ALT: path not taken is dimmed
Create objects
Create an Integration Object
Integration Objects are beans that encapsulate interactions with a host application.
Integration Objects are supported only by HATS Web applications.
If your HATS application will transform a single host application, with no secondary
connections, you do not need to use Integration Objects. You may need to use Integration
Objects if any of these statements are true:
• Your application connects to more than one host application.
• You want to encapsulate your host interactions into EJB applications or Web services.
• You want to build Web pages based on the inputs and outputs of a macro.
1. If you had maximized the VME, the HATS Project view will not be visible. From the menu
select Window > Reset Perspective.
2. Click Yes when the Reset Perspective dialog appears.
3. From the HATS Projects view, expand the Macros folder.
4.
Right-click the FileBrowse macro, and then click Create Integration Object.
5. Now expand the /HATS3270SOA/Source/IntegrationObject folder. It will contain
the object FileBrowse, which is a Java source file.
Create Web Services support files
Now that the foundation for HATS Web Services support (macros and Integration Objects)
has been built, it is time to create Web Services support files.
6. Right-click FileBrowse in the Integration Object folder and then select Create Web
Service Support Files.
7. On the Choose HATS project and Web service class name dialog, enter the class
name FileBrowseWS, and then click Next.
8. On the Choose HATS Integration Objects and HATS EJB Access Beans dialog,
make sure that the check box next to FileBrowse is selected, and then click Finish.
Create the Web service
You are now ready to create the actual Web service, which includes the WSDL (Web
Services Description Language). A WSDL describes a Web service and its operations,
including its inputs and outputs. The caller of the Web service will consume this WSDL file
in order to know what operations are available, and what inputs required for each (if
applicable).
9. Expand the /HATS3270SOA/Source/webserviceclasses folder.
10. Select the FileBrowseWS file, and then right-click and select Web Services > Create
Web service.
The Web Service wizard will appear. This wizard enables you to generate the actual WSDL,
and to select whether or not to deploy and start the service on the server. The wizard also
enables you to create a sample client. For this tutorial, you will not generate a sample
client, because you have the ability to test the service using the Web Services Explorer.
11. Ensure that the Web service type field says Bottom up Java bean Web Service.
This means that the Web service will be constructed from an existing Java class.
12. Ensure that the Service implementation field says webserviceclasses.FileBrowseWS.
13. Ensure that the first section says Start service. If not, use the slider on the left side to
select Start. This section controls which of the following happens. The service is:
•
Just built
•
Built and installed
•
Built, installed, and started
Figure 49: Confirm the Web service type and service implementation
ALT: dialog with Web service options
14. Ensure that the second section indicates No client, as shown in Figure 50, because you
do not need to build an actual client at this time (you will use the Web Services Explorer
later to test the service).
Figure 50: Confirm the Web service client configuration
ALT: dialog with client configuration options
15. Click Next.
16. Click Next again to bypass the Service Endpoint Interface Selection panel and to show
the Web Service Java Bean Identity panel, as shown in Figure 51.
Figure 51: Service Endpoint Interface Selection
The Web Service Java Bean Identity panel is important, because it shows the name of the
WSDL being created and the operations available on the Web service. You should see
FileBrowseProcessWS in the list of methods.
Figure 52: Confirm the Web service Java Bean identity
ALT: configure the bean as a Web service
17. Click Next to show the Start Server panel, as shown in Figure 53.
Note: if you previously started the server and it is still running, you will not see the Start
Server panel.
Figure 53: Start the application server
ALT: dialog prompting you to start the server
18. Click Start server to publish the Web service on the local server, and to start it.
The server will take a few minutes to start. When it does, the text next to the Start server
button changes from Currently the server is stopped to Currently the server is started, as
shown in Figure 54.
19. Click Finish once the server starts.
Figure 54: The application server started successfully
ALT: message circled in Start Server dialog
Your Web service has been created and is installed on your local WebSphere Application
Server. The next step is to test the service to confirm that it works properly.
Test the Web service using the Web Services Explorer
The IBM Rational Software Delivery Platform provides the Web Services Explorer tool to
test Web services. In this section, you will learn how to test your Web service using this
tool.
1. To launch the Web Services Explorer:
a. Expand the /HATS3270SOA/Web Content/WEB-INF/Web Service
Definitions folder
b. Select the FileBrowseWS WSDL file
c. Right-click and select Web Services > Test with Web Services Explorer
After a few moments, the Web Services Explorer browser window will open, as shown in
Figure 55. Double-click on the title bar to maximize the window.
Figure 55: The Web Services Explorer
ALT: Navigator on left, details on right
2. From the Navigator pane click the plus sign (+) next to
FileBrowseWSSoapingBinding.
3. Again, from the Navigator pane, click the fileBrowseProcessWS link within the
Navigator pane. This will show all input parameters for the Web service in the Actions
pane.
Note: all input parameters that start with HPub are used internally by HATS.
4. Scroll down and find the accountNumber parameter, as shown in Figure 56. Recall that
this is the name of the prompt action that you added to the macro earlier.
Figure 56. Invoke a WSDL Operation
ALT: Navigator on left, details on right
5. In the accountNumber field, supply a valid value (such as 111111), and then click the
Go button at the bottom of the Actions pane, as shown in Figure 57.
Figure 57: Enter a valid customer number to test the Web service
ALT: Navigator on left, Actions on right
When the operation is called, HATS will initiate a new connection to the host system and
play the macro. Prompt actions will be filled from values supplied by the caller, and extract
actions will collect data. Results are then displayed in the Status pane.
6. In the Web Services Explorer Status pane, scroll down and notice the outputs.
Remember that these are the macro extracts that were defined in the macro.
Note: The Status pane in the Web Services Explorer can be resized by grabbing the
upper border of the pane with the mouse and then drag it to the preferred size. Or,
maximize the pane by double-clicking on the title area of the pane.
For example, the results (string): 111111 C. BAKER $0011.00 (Figure 58) is the
data extracted by the macro, based on the account number that you supplied to the
prompt.
Figure 58: The result of the Web service appears in the Status window
ALT: List of string values, with link to Source view
7. Now scroll up and click the Source link in the Status window in order to switch to the
Source view.
8. In the Source view, note the SOAP Request Envelope and SOAP Response
Envelope shown in Figure 59. This is the actual XML that was sent and received during
the operation.
Figure 59: The source shows the contents of the SOAP request and response
ALT: XML code
Test the Web service with a non-numeric value
You will now test the Web service operation with an invalid customer number. Recall how
you created an alternate flow for this scenario in your macro using the Visual Macro Editor.
9. Switch back to the Actions area:
a. Find the accountNumber field
b. Type an invalid value (such as abc)
c. Click Go.
10. Switch back to the Status area:
a. Click the Form link near the top to switch to the Form view
b. Scroll down and find the errorMessage output parameter, as shown in Figure 60
(Note that it shows the extracted error message)
Figure 60: The result of using an incorrect customer number
ALT: list of string values, including errorMessage
The caller of the Web service can use this information to determine what step to take next.
For example, the caller might display the message to a user.
What you have learned
What you did in this exercise:
• Built a simple HATS application
• Recorded a FileBrowse macro that queries based on account number
• Created an Integration Object from the FileBrowse macro
• Created a Web Service support based on the Integration Object.
• A Web Service Descriptor Language (WSDL) file was automatically created during this
process. This file describes the Web service, and could then be used by other tools to
build other Web services applications or clients that can access the Web services enabled
HATS application.
• Tested the Web service using the Web Services explorer which was launched from the
workbench.
Conclusion
This concludes the tutorial on creating a Web service using IBM Rational Host Access
Transformation Services (HATS). This tutorial has shown the tools available to a HATS
developer to create Web services that provide access to proven, critical green screen
application processes and data. These services can be hosted on the proven WebSphere
Application Server, and safely exposed and accessed by external partners or internal
organizations.
Trademarks
IBM and the IBM logo are trademarks of International Business Machines Corporation in the
United States, other countries or both.
Java and all Java-based trademarks and logos are trademarks of Sun Microsystems, Inc. in
the United States, other countries, or both. See Java Guidelines
Share this article
Microsoft, Windows, Windows NT, and the Windows logo are
trademarks of Microsoft Corporation in the United States, other
countries, or both.
Other company, product and service names may be trademarks or
service marks of others.
Digg this story
Resources
Learn
Visit the Rational software area on developerWorks for technical resources and best
practices for Rational Software Delivery Platform products.
Subscribe to the developerWorks Rational zone newsletter. Keep up with developerWorks
Rational content. Every other week, you'll receive updates on the latest technical resources
and best practices for the Rational Software Delivery Platform.
Subscribe to the IBM developerWorks newsletter, a weekly update on the best of
developerWorks tutorials, articles, downloads, community activities, webcasts and events.
Browse the technology bookstore for books on these and other technical topics.
Get products and technologies
Download trial versions of IBM Rational software.
Download IBM product evaluation versions and get your hands on application development
tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.
Discuss
Check out developerWorks blogs and get involved in the developerWorks community.