From green-screens to Web services: using WebSphere Host Access Transformation Services (HATS) V6

From green-screens to Web services: using WebSphere Host Access Transformation Services (HATS) V6 zseries 3270 example March 30, 2005 Send comments to Rick Hardison (hardison@us.ibm.com) Visit http://websphere.dfw.ibm.com/atdemo/index.html for more labs and live demos 1

HATS Overview Lab instructions Naming conventions Create project Create macros o Connect macro o Data macro o Disconnect macro Set connection parameters o Enable pooling o Set up Connect and Disconnect macros Create Integration Object Create JSF Web pages Create Web service support files Create Web service Test Web service Create and test Web service client 2

Lab Instructions 1. These instructions will show you how to use the HATS plug-in to the IBM Rational Software Development Platform to create a Web service that will access data from a zseries 3270 application. First you will create a HATS project. Next you will create HATS macros that will be used to connect to and navigate through the host application. From one of the macros you will create a HATS Integration Object and from the Integration Object create a Web service. You will test the Web service using the Web Services Explorer. Then you will create a sample client to use your Web service and test it as well. Naming conventions 2. When using HATS to create Web services these naming conventions should be followed. 2.1. Macro names can begin with either an upper or a lower case letter. 2.2. Integration Object names become class names and must begin with an upper case letter. Integration Object names are derived from macro names. So if the macro starts with a lower case letter, then HATS will convert it to upper case when creating the Integration Object name. 2.3. Marco prompt and extract names become method names and must begin with a lower case letter. 2.4. For any of the names mentioned above, a letter following an underscore or a number must be upper case. Create project 3. Start the Studio and the HATS perspective 3.1. Click Start > Programs > IBM WebSphere HATS 6.0 > HATS Studio 6.0 3.2. For workspace name enter c:\myworkspaces\myhatslabs and click OK 4. Launch the Create HATS Project Wizard 4.1. On the Welcome to HATS page, click launch the Create HATS Project Wizard 3

5. Name your project on the Create a Project panel 5.1. For Name: enter MyAccounts 5.2. Uncheck Use default Enterprise Application project 5.3. For Enterprise Application project name: enter MyAccounts.ear 5.4. Click Next 6. Set up your host connection on the Connection Settings panel. Your Web service will use this connection to communicate with the host application. 6.1. For Host name: enter zserveros.dfw.ibm.com 6.2. For Type: select 3270 6.3. Click Next 4

7. Select your default template 7.1. On the Select Default Template panel, from the Template pull down select whichever template you want, for example Swirl.jsp. The template will not be used by your Web service. 7.2. Click Finish 7.3. After finishing, the Project Settings Overview is displayed. Click the X on the editor s settings tab to close this view. 5

8. In the HATS project view, notice your project including all of its folders. You will be looking into these folders as you go through this lab. Create macros 9. Next you will create three macros. We will call them the Connect, Data, and Disconnect macros. The Connect macro will be used to sign on to the system and navigate to a point at which the Data macro will begin. The Data macro will be used to prompt for input, navigate through the application to extract data based on the requested input, and then navigate back to where it can prompt for the next input. Your Web service will ultimately be derived from the Data macro. Finally, the Disconnect macro will be used to sign off of the system. Connect macro Record Connect macro 10. In the HATS project view right click on your project s folder and select Open Host Terminal then select the Main host connection. 11. Here you see the Welcome screen from the host system. You will now record the Connect macro. 12. To start recording your Connect macro, click Record Macro on the toolbar 13. On the Record Macro panel for Name enter AcctConn. Click Finish. 6

14. On the Define the starting screen of the macro panel 14.1. For Screen Name type Welcome 14.2. Drag your mouse around the Welcome to IBM text in the middle of the screen 14.3. Select At a specified position 14.4. Click Finish 15. On the Welcome screen for Selection type, cicsa, and press the Enter key or click the Enter button 16. Next you see the Signon to CICS screen. Click Define Screen Recognition Criteria 7

17. On the Select Screen Recognition Criteria panel, 17.1. For Screen Name type SignonCICS 17.2. Drag your mouse around the screen title, Signon to CICS, at the top of the screen. 17.3. Select At a specified position 17.4. Click Finish 18. On the Signon to CICS screen, type the userid and password and either press the Enter key or click the Enter button. Ask the instructor what userid and password to use or get the current userid and password for the zseries demo system from http://websphere.dfw.ibm.com/atdemo/atdemo_uid_pw.html. 19. On the Sign-on is complete screen click Define Screen Recognition Criteria 8

20. On the Select Screen Recognition Criteria panel 20.1. For Screen Name type SignonComp 20.2. With your mouse draw a box around the Sign-on is complete text at the bottom of the screen 20.3. Select At a specified position 20.4. Click Finish 21. On the Signon Complete screen type the CICS transaction menu and press the Enter key or click the Enter button. 22. On the Operator Instructions screen click Stop Macro 23. On the Define the exit screen of the macro panel 23.1. For Screen Name type MenuInst 9

23.2. With your mouse draw a box around the Operator Instructions text at the top of the screen 23.3. Select At a specified position 23.4. Click Finish 24. In the Macro Navigator notice the macro logic. 25. Click Save Macro Test Connect macro 26. Now you will test the macro you have just created. First navigate the terminal window back to the Welcome screen. Do this by pressing the Clear (Esc) key to exit. On the blank screen that appears next type cesf logoff and press Enter. Another way to get back to the SignOn screen is to disconnect and reconnect the host session from the icons on the host terminal toolbar. 27. After you are back to the Welcome screen, from the Host Terminal toolbar select the Play Macro drop-down and select the AcctConn macro. 10

28. Notice the macro playing and navigating to the Menu Operator Instructions. This is the screen where your Data macro will begin. Data macro Record Data macro 29. At this point you should have the Host Terminal window open at the Operator Instructions screen. If you are not at this screen, follow the instructions above to open the Host Terminal window and play your Connect macro to position the Host Terminal window at the Operator Instructions screen. 30. To start recording your Data macro, click Record Macro on the toolbar 31. When asked if you want to record a new macro or append to the open macro, click New Macro 32. On the Record Macro panel for name enter AcctData. Remember that the naming conventions state that macro names can start with either an upper or a lower case letter. But, Integration Object names must start with an upper case letter. Later in the lab you will create an Integration Object from this Data macro. If you name your macro starting with a lower case letter, HATS will convert it to upper case when creating the Integration Object. Click Finish. 11

33. On the Define the starting screen of the macro panel 33.1. For Screen Name type MenuInst 33.2. With your mouse draw a box around the OPERATOR INSTRUCTIONS text at the top of the screen 33.3. Select At a specified position 33.4. Click Finish 34. Your Web service will access data from the inqy transaction based on an account number. So, you want to create a prompt action that will allow your Web service clients to enter the account number on which to search. 35. On the Menu Instructions screen 35.1. For Transaction type inqy 35.2. With the curson positioned at the Number field, click Add Prompt Action from the toolbar. 12

36. On the Add Prompt Action panel for Name type acctsearchvalue. Remember the naming conventions. This is a macro prompt name that will become a method name so it must start with a lower case letter. 37. Click OK 38. On the Prompt panel, enter an account number value of 11111 and click OK 13

39. On the Operator Instruction screen press Enter or click the Enter button 40. On the File Inquiry screen click Define Screen Recognition Criteria 41. On the Select Screen Recognition Criteria panel 41.1. For Screen Name type MenuInqy 41.2. With your mouse draw a box around the FILE INQUIRY text at the top of the screen 41.3. Select At a specified position 41.4. Click Finish 42. Next you will create the outputs to be provided by your Web service. 43. On the File Inquiry screen drag your mouse around the NUMBER field and click the Add Extract Action icon. 14

44. On the Add Extract Action panel give this extract the name acctnumber. Remember the naming conventions. This extract name will become a method name so it must start with a lower case letter. 45. Click Finish 46. Now drag your mouse around the NAME field and click the Add Extract Action icon. 15

47. Give this extract the name acctname. Remember it must start with a lower case letter. Change the value for the End column field to 30 to allow for the longest name. Click Finish. 48. Drag your mouse around the ADDRESS field and click the Add Extract Action icon. 16

49. Give this extract the name acctaddress. Remember it must start with a lower case letter. Change the value for the End column field to 30 to allow for the longest address. Click Finish. 50. Drag your mouse around the PHONE field and click the Add Extract Action icon. 51. Give this extract the name acctphone. Remember it must start with a lower case letter. Click Finish. 17

52. Continue as above creating extracts for the DATE, AMOUNT, and COMMENT fields naming them acctdate, acctamount, and acctcomment, respectively. 53. Now that you have extracted the results you want, you must navigate the Data macro back to the screen on which it begins so that the host session will be at the correct screen to run the Data macro again for another request. 54. To navigate back to the screen on which the Data macro begins, click the Enter button at the bottom of the Host Terminal window. 55. Notice that you are now back to the Operator Instructions screen. 56. You have finished recording your Data macro so click the Stop Macro button on the toolbar. 18

57. On the Define the starting screen of the macro panel 57.1. For Screen Name type MenuInstEnd. Even though this is the same screen that the macro starts with, you must give it a different name. All screen names within a macro must be different. 57.2. With your mouse draw a box around the OPERATOR INSTRUCTIONS text at the top of the screen 57.3. Select At a specified position 57.4. Click Finish 58. Notice the logic in the Macro Navigator. Click Save Macro on the toolbar to save your Data macro. Test Data macro 19

59. Now you will test the Data macro you have just created. If the Host Terminal is not already at the Operator Instructions screen, then navigate to it. You can do this manually in the Host Terminal window, or disconnect and reconnect the host session and use the Connect macro to play to the Operator Instructions screen. 60. After you are back to the Operator Instructions screen, from the Host Terminal toolbar select the Play Macro drop-down and select the AcctData macro. 61. In the Supply Prompt Values panel enter a value of 11111 and click OK 62. Watch the macro play. In the Extract Results panel select each of the Extract names from the drop down. 20

63. Notice the results for each Extract name. Disconnect macro Record Disconnect macro 64. At this point you should have the Host Terminal window open at the Operator Instructions. If you are not at this screen, follow the instructions given earlier to open the Host Terminal window and play your Connect macro to position the Host Terminal window at the Operator Instructions screen. 65. To start recording your Disconnect macro, click Record Macro on the toolbar 21

66. When asked if you want to record a new macro or append to the open macro, click New Macro 67. On the Record Macro panel for name enter AcctDisc. Click Finish. 68. On the Define the starting screen of the macro panel 68.1. For Screen Name type MenuInst 68.2. With your mouse draw a box around the OPERATOR INSTRUCTIONS text at the top of the screen 68.3. Select At a specified position 68.4. Click Finish 69. On the Operator Instructions screen, either press the Clear (Esc) key or click the Clear button on the host ked pad to Exit. 22

70. On the Blank screen, click Define Screen Recognition Criteria 71. On the Select Screen Recognition Criteria panel, 71.1. For Screen Name type Blank 71.2. Drag your mouse around enough of the blank screen to uniquely identify it from any other screen. 71.3. Select Within a rectangular region 71.4. Click Finish On the Blank screen type cesf logoff then press the Enter key or click the Enter button 23

72. On the Welcome screen click Stop Macro 73. On the Define the exit screen of the macro panel 73.1. For Screen Name type Welcome 73.2. With your mouse draw a box around the WELCOME TO IBM text in the middle of the screen 73.3. Select At a specified position 73.4. Click Finish 74. In the Macro Navigator notice the logic of your Disconnect macro. 75. Click Save Macro 24

Test Disconnect macro 76. Now you will test the macro you have just created. First navigate the terminal window back to the Operator Instructions screen. Do this by playing your Connect macro. 77. After you are back to the Operator Instructions screen, from the Host Terminal toolbar select the Play Macro drop-down and select the AcctDisc macro. 78. Notice the macro playing and navigating back to the Welcome screen. 79. Close the Host Terminal window 80. You have now created Connect, Data, and Disconnect macros. In the HATS Project view, notice the macros in the Macros folder. If you ever need to go back to edit any of these macros, do so by double clicking on it. 25

81. To summarize, the Connect macro will be used to sign on to the system and navigate to a point at which the Data macro will begin. The Data macro will be used to prompt for input, navigate through the application to extract data based on the requested input, and then navigate back to where it can prompt for the next input. Your Web service will ultimately be derived from the Data macro. Finally, the Disconnect macro will be used to sign off of the system. 82. Next you will set up connection parameters for your host connection. Set connection parameters 83. When you deploy your Web service, it will use a connection (a 3270 session) to access your zseries system. You set up the basic configuration parameters for your connection when you first built your project. Now you will define connection pooling parameters and link the macros you just built to the connection. Enable pooling 84. In order to improve performance for your Web service, you will want to implement connection pooling for the connection to be used by the Web service. Connection pooling allows you to specify a number of connections (3270 sessions) that HATS will maintain in a pool that are already connected and ready to be used by your Web service. In other words, HATS will maintain a number of connections in the pool for which the Connect macro has already been run. Therefore, each of the connections will be connected and immediately ready to run the Data macro. This avoids constant connecting and disconnecting from the host system in order to service multiple Web service requests. 85. The connections defined in your project are found in the Connections folder. Open this folder. HATS can support multiple connections for the purpose of collecting and combining data from multiple back end host sites. In this project you have defined just one connection, which by default is named main. Double click on the main connection to set its connection parameters. 26

86. Look through each of the tabs to see the different configuration settings. Then click on the Pooling tab. 87. On the Pooling tab 87.1. Click Enable Pooling 87.2. Set the Connection Limits. For this lab set the limits to a Minimum of 1 and a Maximum of 2. Then click on the Macros tab 27

Set up Connect and Disconnect macros 88. On the Macros tab for the Connect macro use the drop-down and select your Connect macro, AcctConn 28

89. Then for the Disconnect macro, select your Disconnect macro, AcctDisc. Close the editor for your main connection by clicking the X on the main.hco editor tab. 90. When asked if you want to save the changes, click Yes. Create Integration Object 91. A HATS Integration Object is a JavaBean that encapsulates a programmed interaction with a host application. Integration Objects can be used in multiple ways to integrate interaction with a host application into new Java or Web based programs. One use of an Integration Object is to provide the interaction with a host application for a Web service. HATS macros also provide a programmed interaction with a host application. In fact, creating a HATS macro is the first step in creating an Integration Object. 92. The Web service you are building in this project is intended to gather account information from the host system based on an account number submitted by the Web service client. You have just finished creating a HATS Data macro that does just that. So having created your Data macro, you are finished with the hard part of developing your Web service. Now all you need to do is tell HATS to create an Integration Object from your Data macro and then create a Web service from the Integration Object. 93. To create an Integration Object from your Data macro, in the HATS Project View open the Macros folder, right click on your Data macro, AcctData, and select Create Integration Object. 29

94. After HATS finishes creating the Integration Object, you will find it in the HATS Project View in the Source\Integration Object folder. Look for your Integration Object now. Notice it has the same name as the macro used to create it. Your Integration Object name is, AcctData. Due to the required naming conventions, if your macro had started with a lower case letter, HATS would have converted it to upper case in the Integration Object name. 95. In the next section you will create Java Server Faces Web pages that you can use to test your Integration Object. Create JSF Web pages 30

96. This step is not required when building and testing a HATS Web service. However, it is included in this lab to show you how to create Web pages that can be used to access and drive your Integration Object in non-web services environments. You will use the Web pages in this lab to test your Integration Object. 97. HATS V6 allows you to create Model 1, Struts, or JSF Web pages that can be used to access and drive your Integration Objects. In this lab you will create JSF pages. To begin, right mouse click on your Integration Object, AcctData, in the Source\Integration Object folder and select Create JSF Web Pages. 98. Notice and accept the default page names and click Next. 99. Notice how you can click Edit to change the Input Control to use to accept input from the user. For this lab use the default of Edit box and click Next. 31

100. Notice how you can click Edit to change the Output Controls to use to display output to the user. For this lab use the default of Normal text and click Finish. 101. Your input and output JSF pages are created and stored in the \WebContent\JSF Pages folder. To test them and your Integration Object, right mouse click on the input JSF, AcctDataInput, and select Run on Server. 102. HATS provides a function called Display Terminal that will show a display screen for active host connections. This function is intended for use while developing and debugging HATS applications. Click YES to enable the function so you will be able to see the host connection during your testing. 32

103. On the Server Selection panel click Finish. 104. At this point your HATS application, including the JSF pages and the Integration Object, are deployed to the internal WebSphere Test Environment, and a test server is started. After the server is started, notice the display terminal window and that the session is at the Menu Operator Instructions screen. This is because earlier in the lab you configured HATS to enable session pooling and to run the connect macro automatically when the connection to the host is started. 33

105. Position the display terminal window so that you can see it run while focus is given to the studio workbench. In the studio Web browser notice your input JSF Web page. For Acct Search Value enter 11111 and click Submit. 106. At this point a connection is allocated from the connection pool. Your Integration Object is instantiated and then navigates through the host application using the search value supplied by the client. Notice the display terminal as it plays your data macro. 107. Then notice the results displayed on your output JSF Web page. 34

108. Next you will begin the process of creating a Web service. Create Web service support files 109. Before you actually create your Web service, you must first create HATS Web service support files. To do this, in the HATS Project View, right click on your Integration Object and select Create Web Service Support Files. 110. For Project use your project name, MyAccounts. For Class name enter, AcctWS. Since this is a class name it must start with an upper case letter. Click Next. 35

111. Check your Integration Object, AcctData, to include it in the Web service class. You can include more than one Integration Object in a Web service class. In this case you only have the one. Click Finish. 112. In the HATS Project View notice the webserviceclasses folder and files that have been created. 113. Switch to the Navigator view and notice the same files and additional files added to the IntegrationObject folder. 36

Create Web service 114. Now that you have created your Web service support files you can create your Web service and deploy it to the WebSphere Test Environment. To do this, in the Navigator view right click on your Web service class file, AcctWS.java, in the Java Source\webServiceClasses folder and select, Web Services > Create Web service 115. At this point you could click Finish to take all of the defaults, but to see all of the different settings, on the Web Services panel click Next. 37

116. On the Object Selection Page panel notice the bean name and click Next. 117. On the Service Deployment Configuration panel notice that by default the server to which your Web service will be deployed is the WebSphere v5.1 Test Environment. Also notice the project name is your project. Click Next. 118. On the Service Endpoint Interface Selection panel click Next. 38

119. On the Web Service Java Bean Identity panel notice all of the Web service settings. The methods correspond to the Integration Objects you included in the Web service class file. Do not change anything. Click Next. 120. At this point your HATS application including the Web service is published to the WAS Test Environment and the WAS server is started. An actual copy of WAS is brought up within the studio and your HATS application is started. This may take a few moments. After the test server is started the Web Service Publication panel appears. Click Finish. 39

121. When your HATS application is started, the connection to the host system is started and the Connect macro is run leaving the connection at the Menu Operator Instructions screen. You can actually see this by looking at the Display Terminal window. Notice that a host terminal screen has become active. Sometimes this task starts minimized on the Windows task bar so you may need to look for it there and restore it. Notice that it is displaying the Menu Operator Instructions screen. Of course, the end user does not see this screen. It is only displayed at the server for debugging purposes. Now, when you invoke your Web service, you can see how HATS is using the host connection to communicate with the host application. 122. Your Web service is now deployed. Next you will test it. Test Web service 123. One output of creating your Web service is a WSDL (Web Service Description Language) file. You can find this file in the Navigator view in the Web Content\wsdl\webServiceClasses folder. This WSDL file can be used to test your Web service. To do so, right click on the WDSL file, AcctWS.wsdl, then select Web Services > Test with Web Services Explorer. 40

124. The Web Services Explorer comes up in the studio s Web Browser. 125. In the Actions panel under Operations, click on the acctdataprocessws operation. 126. Under inputfromclient notice acctsearchvalue. Remember this is the name of the macro prompt you created in your Data macro to allow the client to provide an account number to search. In this field enter account number 11111. 41

127. So that you can actually see the communication with the host application when the Web service is invoked, you will need to reduce the size of the studio window so that you can see both the studio s Web browser and the host terminal screen at the same time. 128. In the Web Services Explorer Actions panel scroll down, click the Go button. As you do this watch the host terminal screen. 129. At this point a connection is allocated from the connection pool. Your Integration Object is instantiated and then navigates through the host application using the search value supplied by the client. Notice the host terminal screen as the Integration Object runs. If you notice that an error has occurred, then restart the server on the Server tab by right mouse clicking on the server and selecting Restart > Server. 42

130. In the Web Services Explorer maximize the Status panel by double clicking on it. In the Form view scroll down and notice the outputs. Remember these are the macro extracts you created in your Data macro. For example, below notice acctamount and acctnumber, etc. 131. Now scroll back up and switch to the Source view. 43

132. In the Source view notice the SOAP Request Envelope and SOAP Response Envelope. 133. You have now finished creating and testing your Web service. Next you can use the studio to create a sample client application that can use your Web service Create and test Web service client 134. To create a sample client application that can use your Web service, go back to the Navigator view and find your WSDL file, AcctWS.wsdl, in the Web Content\wsdl\webServiceClasses folder. Right click on the WSDL file then select Web Services > Generate Client. 135. On the Web Services panel check Test the Web service and click Next. 44

136. On the Web Services Selection Page notice the URI and click Next. 137. Your sample client must be in a project different from your Web service project. So on the Client Environment Configuration panel, for Client project enter MyAccountsWSClient, and for Client project EAR enter MyAccountsWSClient.ear. Click Next. 45

138. On the Web Service Proxy Page click Next. 139. On the Web Service Client Test panel be sure to check Test the generated proxy. Click Finish. 46

140. At this point your client application is generated, published to the server and started. This may take a few moments. 141. In the Navigator view notice your new client project, MyAccountsWSClient. Also notice the TestClient.jsp. When this jsp is run on the server it can be used to drive your client application. 142. Now notice that the TestClient.jsp has automatically been run on the server and is displayed in the studio s Web Browser. To test the client application, in the Methods frame, click the acctdataprocessws method. 47

143. As you did when you tested using the Web Services Explorer, you should reduce the size of the studio s window so that you can see both the studio and the host terminal screen. Then in the Inputs frame for acctsearchvalue enter 11111 and click Invoke. 144. Notice the activity in the host terminal screen. 48

145. Look for the results in the Result frame of your TestClient.jsp. You may need to scroll down to see the results. Notice the same outputs that correspond to the macro extracts of your Data macro. 146. Congratulations! You have successfully created a HATS Web service. Tested it with the Web Services Explorer. Created a sample client to use your Web service and tested it as well. 147. End of lab 49