Practical web services for RPG lab exercises

Session: Practical Web Services for RPG

http://www.ibm.com/systems/i/software/iws/

Page 1 of 60

http://www.ibm.com/systems/i/software/iws/index.html

Agenda

AGENDA............................................................................................................................................................................................2

LAB INFORMATION..........................................................................................................................................................................3Lab Prerequisites........................................................................................................................................................................3Software and Tool Requirements................................................................................................................................................3Lab Setup....................................................................................................................................................................................3Objectives...................................................................................................................................................................................4Notes...........................................................................................................................................................................................4Where to Find More Information...............................................................................................................................................4

FICTIONAL CASE STUDY – OVER THE TOP COFFEE.........................................................................................................5

PRACTICAL WEB SERVICES FOR RPG....................................................................................................................................6

LAB EXERCISES..............................................................................................................................................................................7

EXERCISE 1: REVIEW THE EXAMPLE COFFEE BEAN INVENTORY APPLICATION..............................................................................7EXERCISE 2: CREATE AN IBM INTEGRATED WEB SERVICES SERVER FOR I...................................................................................9EXERCISE 3: REVIEW STARTING/STOPPING AN INTEGRATED WEB SERVICES SERVER.................................................................13EXERCISE 4: REVIEW THE IBM INTEGRATED WEB SERVICES SERVER FOR I...............................................................................14

Exercise 4a: Server Properties................................................................................................................................................14Exercise 4b: Manage Deployed Services................................................................................................................................18Exercise 4c: Example 1 - Test the ConvertTemp Web Service................................................................................................21Exercise 4d: View the SOAP Message Tracing Logs..............................................................................................................29

EXERCISE 5: DEPLOY RPG BUSINESS LOGIC AS A WEB SERVICE................................................................................................31Exercise 5a: The CoffeeBeanInventory Web Service..............................................................................................................32Exercise 5b: The WarehouseCoffeeBeanInventory Web Service............................................................................................38

EXERCISE 6: TEST DEPLOYED WEB SERVICES ON IBM I..............................................................................................................44Exercise 6a: Test Operation getitems......................................................................................................................................46Exercise 6b: Test Operation additem......................................................................................................................................47Exercise 6c: Test Operation changeitem.................................................................................................................................49Exercise 6d: Test Operation removeitem................................................................................................................................51

EXERCISE 7: CONSUME THE “WAREHOUSECOFFEEBEANINVENTORY” WEB SERVICE FROM AN RPG CLIENT...........................53Exercise 7a: Generate and Review Client Stub Code.............................................................................................................54Exercise 7b: Review Client Source Code and Create Application..........................................................................................57Exercise 7c: Consume the WarehouseCoffeeBeanInventory Web Service............................................................................59

Page 2 of 60

Lab Information

Lab Prerequisites

To get the most out of this lab you should be familiar with RPG and Web development concepts. Experience with the IBM Web administration for i GUI could also be helpful, but it isn’t necessary.

This is a self-guided lab to gain hands-on experience working with the Integrated Web Services Server available with IBM i starting in release 5.4.

Software and Tool Requirements

IBM Personal Communications Software must be installed on the lab computers. Web browser (Firefox or IE) must be installed on the lab computers. IBM i server running 6.1 (or above) with prerequisites installed. Prerequisites

documented at: http://www.ibm.com/systems/i/software/iws/support.html .

Lab Setup

The following preparatory steps have been completed for you:

All the necessary software prerequisites and tools are installed on the lab computers and server.

The necessary lab user profiles, user libraries, files, and programs have been created on the lab server. Lab user profiles have been authorized to the appropriate objects.

These are the steps you should perform before completing any of the lab exercises:

o 1. Bring up an IBM i 5250 terminal session by double-clicking on the icon on your PC desktop. Ensure you bring up the correct system used for this lab.

o 2. Sign on using your assigned lab userid and password. During the lab you will be instructed when to use IBM i commands.

o 3. Bring up a Web browser by double-clicking on the Firefox or Internet Explorer icon on your PC desktop. This Web browser will be used for working with the IBM integrated web services server for i.

Page 3 of 60

http://www.ibm.com/systems/i/software/iws/support.html

Objectives

The example application you will be working with during the Integrated Web Services lab exercises is based on a fictional case study about a coffee store called “Over the Top Coffee. Please read the section in this lab titled “Fictional Case Study – Over the Top Coffee” for some background information about this fictional coffee store.

This lab has the following objectives:

Review the Over the Top Coffee store’s in-house coffee inventory application Create an IBM integrated web services server for i Review the IBM integrated web services server for i Deploy RPG business logic as a web service Test deployed web services using the IBM i Web Services Test Client

Notes Please do NOT change or edit anything on the lab server other than what you are

instructed to do during the lab.

Throughout the lab, when you see INVENTRYxx, you should replace xx with your assigned team number.

Where to Find More Information


Page 4 of 60


Fictional Case Study – Over the Top Coffee

"Over the Top Coffee" is a local coffee store in the city of Seattle who focuses on delivering the best and most premium coffee beans at a fair price. Their Coffee Inventory application was written in RPG and is currently a "Green Screen" 5250 application which was architected 10 years ago. It is an excellent application, efficient, well tuned, and perfect for Over the Top Coffee’s in-house inventory needs.

The Over the Top Coffee store has recently received word from their “green (unroasted) coffee beans” supplier that they’ve upgraded their Warehouse Coffee Ordering application so it is now directly accessible to their clients via a new coffee ordering web service. Over the Top Coffee would like to automate their coffee supply ordering process by writing a RPG client program (to run nightly) that will run a check against the store’s local coffee inventory and automatically order more coffee from their supplier’s warehouse (via the new “WarehouseCoffeeBeanInventory” web service). More coffee will be ordered whenever the combined sum of each coffee product’s in stock inventory count and its on order inventory count is less than 25 items.

Page 5 of 60

Practical Web Services for RPG

The integrated web services server and the integrated web services client for ILE enables ILE applications to play in the web services and SOA arena with very little effort, knowledge and resources. The convergence of web services and IBM i technologies can help enterprises liberate these core business assets by making it easier to enrich, modernize, extend and reuse them well beyond their original scope of design.Many businesses are seeing benefits in moving their information technology (IT) infrastructure to make greater use of standards as they roll out new applications and services, and to better exploit their existing infrastructure. In doing this, businesses have recognized that they need to become more flexible, allowing them to address new business opportunities more quickly by reusing more of their existing assets, including currently running business processes and applications.

By choosing to move to a Service Oriented Architecture (SOA), businesses can ensure that they design and build their IT infrastructure using an architectural style that supports service orientation. By linking together your business as a set of connected services, your IT infrastructure will be more flexible and responsive, allowing your business to be more flexible and responsive in turn.

The question for businesses is how to get there? Companies are hampered by the very technologies they rely on to run their businesses. Many of their core information IT applications written in integrated language environment (ILE) languages such as RPG and COBOL have been in service for years — even decades. Developed and optimized over a period of years, these applications are difficult to link to new technologies such as web services and SOA — until now.

Getting started with web services and SOA on IBM i is easier than ever with the Integrate web services server for IBM i. The bottom line is that flexible businesses require flexible IT, and the path to flexible IT is web services and SOA.

Integrated Web Services for IBM i http://www.ibm.com/systems/i/software/iws/

Page 6 of 60


IBM Integrated Web Services for i – Server Lab

Lab Exercises

Exercise 1: Review the example Coffee Bean Inventory Application

Introduction: "Over the Top Coffee" is a local coffee store in the city of Seattle who focuses on delivering the best and most premium coffee beans at a fair price. Their Coffee Inventory application was written in RPG and is currently a "Green Screen" 5250 application which was architected 10 years ago. It is an excellent application, efficient, well tuned, and perfect for Over the Top Coffee’s in-house inventory needs.

Objective: In this exercise you will review the “Green Screen” view of Over the Top Coffee’s in-house coffee bean inventory application, along with some of the source code behind its internal RPG business logic.

o 1. With a 5250 session, run the example Coffee Bean Inventory Application by issuing the following commands from a command line:

a. ADDLIBLE LIB(INVENTRYxx) b. CALL PGM(COFFEE)

Note: You can add, change, or remove Coffee Bean inventory items from this displayed screen.

Press F3 or F12 to exit the example Coffee Bean Inventory application’s display screen.

Page 7 of 60

o 2. With a 5250 session, examine the RPG source code used to generate the Coffee Bean Inventory application’s RPG business logic. This business logic is self contained in an IBM i service program and will later be deployed on an IBM integrated web services server for i (Exercise 3).

o a. Issue STRPDM, Option 3. Specify file QRPGLESRC, library INVENTRYxx where xx is your assigned student number), and member name ITEM*. Press Enter.

o b. The following file members will be displayed. View the files using Option 5=Display and F3=Exit.

i. Member ITEMPR is the prototype definitions for the externalized Coffee Bean Inventory business logic procedure interfaces.

ii. Member ITEM is the RPG procedure interfaces for the prototype definitions defined in member ITEMPR.

Note: PCML information needs to exist to deploy an ILE program or service program on the IBM Integrated web services server for i. When you examine the ITEM RPG source code, you will notice Program Call Markup Language (PCML) information was specified to be included in the compiled RPG module via the following RPG Header specification (H-specs).

h NOMAIN PGMINFO(*PCML:*MODULE)

o c. Using this H-spec is the easiest way to ensure the proper PCML information is available. The PCML information can also be generated manually using an editor.

** END OF EXERCISE 1 **

Page 8 of 60

Exercise 2: Create an IBM Integrated Web Services Server for i

Objective: In this exercise you will create an IBM integrated web services server for i to use throughout the rest of these lab exercises.

o 1. With a browser, open the IBM Web Administration for i GUI.

http://<hostname>:2001/HTTPAdmin

o 2. You will first have to enter your assigned team user id and password and press OK, before the IBM Web Administration for i GUI will be shown.

o 3. On the IBM Web Administration for i console, you should be viewing the Manage Application Servers page. If not, here is how to get there: click on the Manage Tab then click on the Application Servers sub-tab.

o 4. Click on the Create Web Services Server link.

Page 9 of 60

o 4. The Create Web Services Server wizard is displayed.

o a. Step 1 of 3: Read the displayed panel and then select Next.

o b. Step 2 of 3: Read the displayed panel and then select Next.

Page 10 of 60

o c. Step 3 of 3: A summary of the Create Web Services Server wizard is displayed.

o d. Click on the Servers tab and write down the server name, server root, server port (hint: the server URL contains the web services port number), and context root. Record the above information in the Team Information handout. You will use this information throughout the rest of these lab exercises.

o e. Click on the Services tab to see the URL for the ConvertTemp example web service that the Create Web Services Server wizard automatically deploys on each new web services server instance that is created.

o f. Click Finish so that the new web services server can be created.

Page 11 of 60

o g. While you are waiting for the Create Web Services Server wizard to complete you’ll notice the status in the upper left hand corner of the IBM Web Administration for i GUI has a status of “Creating”. Eventually the status will change to “Running”, however it might take a few moments before it does.

Note: The name of your new web services server should be displayed in the Server drop-down list.


Page 12 of 60

Exercise 3: Review Starting/Stopping an Integrated Web Services Server

Objective: In this exercise, you will review starting/stopping an integrated web services server <WSERVICEyy>.

o 1. From the IBM Web Administration for i GUI, you should be viewing the Manage Application Servers page with your web services server <WSERVICEyy> selected in the Server drop-down list. If not, here is how to get there: Click on the Manage Tab, click on the Application Servers sub-tab, then select your web services server <WSERVICEyy> from the Server drop-down list.

o 2. If the status of your web services server <WSERVICEyy> says “Stopped”, click on green start icon to start your web services server and then click on the Start button.

Then confirm your selection:

o 3. If the status of your web services server <WSERVICEyy> says “Creating” or “Starting”, click on the blue restart button to refresh the status of your web services server.

o 4. If the status of your web services server <WSERVICEyy> says “Running”, no further action is necessary to start your web services server. Note: The red stop button is also shown below. This button can be used to manually stop a web services server.


Page 13 of 60

Exercise 4: Review the IBM Integrated Web Services Server for i

Objective: In these exercises you will review properties of your IBM i web services server instance.

o From the IBM Web Administration for i GUI, you should be viewing the Manage Application Servers page with your web services server <WSERVICEyy> selected in the Server drop-down list. If not, here is how to get there: Click on the Manage Tab, click on the Application Servers sub-tab, then select your web services server <WSERVICEyy> from the Server drop-down list.

Exercise 4a: Server Properties

o 1. Select “Server Properties” on the left side of the browser display to expand the Server Properties links, then click on the Properties link.

o a. Review the information displayed under the Application Server tab. This tab shows information pertaining to your <WSERVICEyy> web services server instance.

Page 14 of 60

o b. Click on the Ports tab and review what information is shown.

o c. Click on the Web Services Server tab and review what information is shown.

Note: This is the screen you would use to change a web services server’s context root. The default value is /web, however this property can be changed as long as the web services server is stopped. If the web services server is running, than the context root field is grayed out and un-editable. In addition, this panel allows you indicate what web service protocols are allowed to be used and various information relating to the WSDL file associated with the web service.

o d. Click the OK button.

Page 15 of 60

o 2. Stop your web services server <WSERVICEyy>.o a. Click the red stop button in the upper left hand corner of the IBM Web Administration

for i GUI.


o b. Wait for the status of your web services server <WSERVICEyy> to go from “Running” to “Stopped” status.

o 3. Under the Server Properties link on the left side of the browser display, click on the Server Tracing link.

o a. Click on the Web Services tab and review what information is shown. Change the Message tracing value from Disabled to Enabled and then click the Apply button.

Note: The Message Tracing output will be reviewed in an exercise later on in this lab.

Page 16 of 60

o 4. Start your web services server <WSERVICEyy>.

o a. Click the green start button in the upper left hand corner of the IBM Web Administration for i GUI.


o b. Wait for the status of your web services server <WSERVICEyy> to go from “Stopped” to “Running” status. You might have to hit the blue refresh button a few times until the status changes to Running.

o 5. Under the Server Properties link on the left side of the browser display, click on the View HTTP Servers link.

o a. Review the View HTTP Server information on the right side of the browser display.

Page 17 of 60

Exercise 4b: Manage Deployed Services

o 1. With your <WSERVICEyy> server selected in the Server drop-down list, click “Manage Deployed Services” on either the left or center of the browser display.

o 2. The Manage Deployed Services panel is displayed. An example web service called ConvertTemp is deployed with all new IBM integrated web services server for i instances.

o a. Select the radio button next to the ConvertTemp service and click on the Properties button.

Page 18 of 60

o b. Examine the properties for the ConvertTemp web service by reviewing the information shown on the General tab.

o c. Click on the rest of the tabs and examine the displayed properties. The Operations tab lists the web service operations for the service and whether they are Enabled (thus can be invoked) or Disabled (and thus cannot be invoked). The Library List tab lists the libraries that will be added to the library list when the web service implementation code is invoked. The WSDL tab allows you to regenerate the WSDL file associated with the web service and also modify it. The Connection Pool tab lists the properties associated with the pool of jobs associated with the web service. Finally, the Request Information tab allows you to specify what transport information should be passed to the web service implementation code. Prior to invoking the web service implementation code, any selected transport information will be added to the job as environment variables.

o d. After reviewing all property tabs, click the OK button.

o e Review the Web Services Description Language (WSDL) file for the ConvertTemp web service by clicking on the “View definition” link.

Note: The Web Services Description Language (WSDL) is a XML-based language that provides a model for describing web services. Although WSDL files look confusing, they indicate where a web service resides, what input parameters it accepts, and what output parameters it returns. They also allow programming languages (JAVA, .NET, C, C++, RPG,

Page 19 of 60

COBOL) on other platforms to interact with the native business logic found in your IBM i ILE Programs and Service Programs.

o f. After reviewing the ConvertTemp WSDL file, close the window or tab opened when you clicked the “View definition” link.

Page 20 of 60

Exercise 4c: Example 1 - Test the ConvertTemp Web Service

An example web service called ConvertTemp is deployed with all new IBM i Web Service Server instances. This service converts temperatures in Fahrenheit to temperatures in Celsius and can be used as a test to verify whether or not a new web services server is working successfully. Follow the below steps to test your new web services server <WSERVICEyy> using the ConvertTemp web service.

o 1. With your <WSERVICEyy> web services server selected in the Server drop-down list, click “Manage Deployed Services” on either the left or center of the browser display.

o 2. The “Manage Deployed Services” panel will be displayed. Invoke the built-in IBM i Web Services Test Client using the following steps:

o a. Select the radio button next to the ConvertTemp web service and click on the Test Service button.

Page 21 of 60

o b. The IBM Web Service Test Client for i will be invoked. Displayed on the left is the WSDL Navigator panel, on the right is the Actions panel, and along the bottom you will find the Status panel.

o 3. In the Actions panel, click the converttemp operation.

o a. After clicking the converttemp operation, the Actions panel is updated with information allowing the coverttemp operation to be invoked. Click Add to next to input parameter param0.

Page 22 of 60

o b. Click Add next to input parameter _TEMPIN and specify a value of 32 in the input field, then click the Go button.

Page 23 of 60

o c. The converttemp operation’s return parameter data will be displayed in the Status panel at the bottom of the IBM i Web Services Test Client browser display.

Note: The return value in the Status panel has a value of 0, which is correct because 32 degrees Fahrenheit is 0 degrees Celsius.

o 4. You can review the converttemp operation’s response in more detail by viewing the Source link. The Source link displays the Request and Response SOAP message details and can be a very useful tool for problem determination.

o a. Make the Status panel larger by dragging the top line of the Status panel up toward the Actions panel using your mouse. Then click on the Source link on the far right of the Status panel.

Page 24 of 60

o b. The Status panel will display the SOAP message details for the request and response SOAP envelopes. The request SOAP envelope was sent to the ConvertTemp web service by the IBM Web Service Test Client for i. The response SOAP envelope was returned from the ConvertTemp web service.

o c. You can stop showing the SOAP envelopes in the Status panel by clicking on the Form link on the far right of the Status panel.

o d. You can exit the IBM Web Service Test Client for i by closing the browser tab that contains the IBM Web Service Test Client for i window.

Page 25 of 60

o 5. In the Navigator panel, click the converttemp_XML operation.

o b. After clicking the converttemp_XML operation, the Actions panel is updated with information allowing the coverttemp_XML operation to be invoked. Click Add to next to input parameter param0.

Page 26 of 60

o b. Click Add next to input parameter _TEMPIN and specify a value of 32 in the input field, then click the Go button.

o c. The converttemp_XML operation’s return parameter data will be displayed in the Status panel at the bottom of the IBM i Web Services Test Client browser display. Since you called the converttemp_XML operation instead of the converttemp operation, the response is given in XML format.

Note: The return value in the Status panel has a value of 0, which is correct because 32 degrees Fahrenheit is 0 degrees Celsius.

Page 27 of 60

o 4. You can review the converttemp operation’s response in more detail by viewing the Source link. The Source link displays the Request and Response SOAP message details and can be a very useful tool for problem determination.

o a. Make the Status panel larger by dragging the top line of the Status panel up toward the Actions panel using your mouse. Then click on the Source link on the far right of the Status panel.

Page 28 of 60

Exercise 4d: View the SOAP Message Tracing Logs

o 1. With your <WSERVICEyy> web services server selected in the Server drop-down list, click “View Logs” in the lower left corner of the browser display.

Page 29 of 60

o 2. Page down in the list of Application Server Logs for server <WSERVICEyy> and click on

/www/<WSERVICEyy>/lwi/logs/lwistdout.txt log file.

o 3. You should see SOAP message details from your previous tests of the ConvertTemp web service. Both the incoming message and the outgoing message should be in the log file.


Page 30 of 60

Exercise 5: Deploy RPG Business Logic as a Web Service

Introduction: "Over the Top Coffee" is a local coffee store in the city of Seattle who focuses on delivering the best and most premium coffee beans at a fair price. Their Coffee Bean Inventory application was written in RPG and is currently a "Green Screen" 5250 application which was architected 10 years ago. It is an excellent application, efficient, well tuned, and perfect for Over the Top Coffee’s in-house inventory needs.

Objective: In these exercises you will deploy the following RPG Business Logic as web services:

Exercise 5a: Over the Top Coffee’s coffee bean inventory procedures. We will call this the “CoffeeBeanInventory” web service.

Exercise 5b: Over the Top Coffee’s supplier’s new Warehouse Coffee Ordering web service. We will call this the “WarehouseCoffeeBeanInventory” web service.

Note: Exercise 5b would normally be the supplier’s responsibility and the web service would run on one of the supplier’s servers, however in this lab we are going to use this web service as another example of how to deploy RPG business logic.

Page 31 of 60

Exercise 5a: The CoffeeBeanInventory Web Service

This exercise will go through the steps required to successfully deploy the CoffeeBeanInventory web service. The CoffeeBeanInventory web service will provide database access procedures that work with Over the Top Coffee’s Coffee Bean Inventory application. The externalized RPG database access logic that will be deployed is self contained in a ILE Service Program called ITEM.

o 1. With your <WSERVICEyy> web services server selected in the drop down field of the IBM Web Administration for i GUI, select “Manage Deployed Services” on either the left or center of the browser display.

o 2. The Manage Deployed Services panel is displayed. Click on the Deploy button to begin the Deploy New Service Wizard.

o a. Step 1 of 9: Read the first panel and then select Next.

Page 32 of 60

o b. Step 2 of 9: Enter the following values to reference the RPG business logic (ILE service program) for the CoffeeBeanInventory web service, then select Next.

o c. Step 3 of 9: Enter the following values or accept the default values and then select Next.

Page 33 of 60

o d. Step 4 of 9: Select Expand All and set the following Usage and Count fields as indicated, then select Next.

Note: By setting the Count field for parameter INVENTORY on procedure GetItems() to a value of RTNCOUNT (instead of the default value of 100) there is a slight performance gain. The performance gain is a result of the web service only having to return an array in parameter INVENTORY that is the exact size needed, as opposed to, having to return an array of 100 elements which has all of the unneeded array elements set to default values.

o e. Step 5 of 9: Take the default value “Use server’s user ID” and select Next.

Page 34 of 60

o f. Step 6 of 9: Take the default values for the library list entries and select Next.

o g. Step 7 of 9: Take the default values for transport information to be passed and select Next.

Page 35 of 60

o h. Step 8 of 9: Take the default values for WSDL options and select Next.

o i. Step 9 of 9: Review the final summary panel and select Finish.

Note: The Deploy New Service wizard will go off and generate the necessary Web artifacts and finish building the newly deployed web service.

Page 36 of 60

o j. When the Deploy New Service Wizard completes, click on the “Manage Deployed Services” link and verify the newly deployed web service is in “Running” status. You may need to select the Refresh button a few times, if the wizard is still busy creating the new web service in the background.

Page 37 of 60

Exercise 5b: The WarehouseCoffeeBeanInventory Web Service

This exercise will go through the steps required to successfully deploy the WarehouseCoffeeBeanInventory web service. The WarehouseCoffeeBeanInventory web service will provide a procedure to order more supplies from Over the Top Coffee’s main supplier. The RPG business logic that will be deployed is self contained in a ILE Service Program called ORDERF.


o 2. The Manage Deployed Services panel is displayed. Click on the Deploy button to begin the Deploy New Service Wizard.

o a. Step 1 of 9: Read the first panel and then select Next.

Page 38 of 60

o b. Step 2 of 9: Enter the following values to reference the RPG business logic (ILE service program) for the WarehouseCoffeeBeanInventory web service, then select Next.

o c. Step 3 of 9: Enter the following values or accept the default values and then select Next.

Page 39 of 60

o d. Step 4 of 9: Select Expand All and set the following Usage fields as indicated, then select Next.

o e. Step 5 of 9: Take the default value “Use server’s user ID” and select Next.

Page 40 of 60

o f. Step 6 of 9: Take the default values for the library list entries and select Next.

o g. Step 7 of 9: Take the default values for the transport information to be passed and select Next.

Page 41 of 60

o h. Step 8 of 9: Take the default values for WSDL options and select Next.

o i. Step 9 of 9: Review the final summary panel and select Finish.

Note: The Deploy New Service wizard will go off and generate the necessary Web artifacts and finish building the newly deployed web service.

Page 42 of 60

o j. When the Deploy New Service Wizard completes, click on the “Manage Deployed Services” link and verify the newly deployed web service is in “Running” status. You may need to select the Refresh button a few times, if the wizard is still busy creating the new web service in the background.

o 3. Click the WarehouseCoffeeBeanInventory service’s View definition link and record this service’s URL path in the Team Information handout. You will need this URL path when you implement the RPG client program to consume Over the Top Coffee’s supplier’s ordering inventory web service called WarehouseCoffeeBeanInventory in exercise 7. The WarehouseCoffeeBeanInventory service’s URL path should be of the following form:

http://<hostname>:<port>/web/services/WarehouseCoffeeBeanInventory?wsdl


Page 43 of 60

Exercise 6: Test Deployed Web Services on IBM i

Objective: In these exercises you will test the CoffeeBeanInventory web service operations that were deployed in exercise 5a.


o 2. The “Manage Deployed Services” panel will be displayed. Invoke the built-in IBM i Web Services Test Client using the following steps:

o a. Select the radio button next to the CoffeeBeanInventory web service and click on the Test Service button.

Page 44 of 60

o b. The IBM Web Service Test Client for i will be invoked. Displayed on the left is the WSDL Navigator panel, on the right is the Actions panel, and along the bottom you will find the Status panel.

Page 45 of 60

Exercise 6a: Test Operation getitems

Objective: In this exercise you will test the getitems operation found in web service CoffeeBeanInventory.

o 1. In the Actions panel, click the getitems operation.

o a. After clicking the getitems operation, the Actions panel is updated with information allowing the getitems operation to be invoked. Click the Go button. The getitems operation’s return parameter data will be displayed in the Status panel at the bottom of the IBM i Web Services Test Client browser display.

Note: The INVENTORY parameter in the Status panel can be expanded in order to view the return parameter data. The RTNCOUNT parameter contains how many items were returned by the getitems operation.

Page 46 of 60

Exercise 6b: Test Operation additem

Objective: In this exercise you will test the additem operation found in web service CoffeeBeanInventory.

o 1. In the Actions panel, click the additem operation.

o a. After clicking the additem operation, the Actions panel is updated with information allowing the additem operation to be invoked. Fill in the following values.

Page 47 of 60

o b. In the Actions panel, click on the Go button to invoke the additem operation. The operation’s return parameter data will be displayed in the Status panel at the bottom of the IBM i Web Services Test Client browser display.

Note: A return value of 1 means the operation was successful. A return value of 0 means the operation was unsuccessful.

Page 48 of 60

Exercise 6c: Test Operation changeitem

Objective: In this exercise you will test the changeitem operation found in web service CoffeeBeanInventory.

o 1. In the Actions panel, click the changeitem operation.

o a. After clicking the changeitem operation, the Actions panel is updated with information allowing the changeitem operation to be invoked. Update the input parameters as follows:

Page 49 of 60

o b. In the Actions panel, click on the Go button to invoke the changeitem operation. The operation’s return parameter data will be displayed in the Status panel at the bottom of the IBM i Web Services Test Client browser display.


Page 50 of 60

Exercise 6d: Test Operation removeitem

Objective: In this exercise you will test the removeitem operation found in web service CoffeeBeanInventory.

o 1. In the Actions panel, click the removeitem operation.

o a. After clicking the removeitem operation, the Actions panel is updated with information allowing the removeitem operation to be invoked. Update the input parameters as follows:

Page 51 of 60

o b. In the Actions panel, click on the Go button to invoke the removeitem operation. The operation’s return parameter data will be displayed in the Status panel at the bottom of the IBM i Web Services Test Client browser display.



Page 52 of 60

Exercise 7: Consume the “WarehouseCoffeeBeanInventory” Web Service from an RPG Client

Introduction: The Over the Top Coffee store has recently received word from their “green (unroasted) coffee beans” supplier that they’ve upgraded their Warehouse Coffee Ordering application so it is now directly accessible to their clients via a new coffee ordering web service. Over the Top Coffee would like to automate their coffee supply ordering process by writing a RPG client program (to run nightly) that will run a check against the store’s local coffee inventory and automatically order more coffee from their supplier’s warehouse (via the new “WarehouseCoffeeBeanInventory” web service). More coffee will be ordered whenever the combined sum of each coffee product’s in stock inventory count and its on order inventory count is less than 25 items.

Objective: In these exercises you will create the RPG client program (responsible for ordering more coffee) that will consume the “WarehouseCoffeeBeanInventory” web service you deployed (Exercise 5b).

Exercise 7a: Generate RPG stub code and create service program containing stub code.

Exercise 7b: Create the RPG application that uses the stub code to consume web service.

Page 53 of 60

Exercise 7a: Generate and Review Client Stub Code

Before you can create a web service client application, you must first generate the client stubs using the wsdl2ws.sh tool. The wsdl2ws.sh tool uses the WSDL file that is passed to create the client stubs. We will be using the WSDL file for the WarehouseCoffeeBeanInventory web service. To generate the client stubs from your WSDL source file, complete the following steps.

o 1. Generate the client stub code responsible for communicating with the WarehouseCoffeeBeanInventory web service.

o a. Ensure your web services server is in a running state.

o b. Start a QSHELL session by issuing the QSH CL command from an IBM i command line and pressing Enter.

o c. Run the below wsdl2ws.sh tool from QSHELL to generate the client stubs by typing in the following command and pressing Enter:

/QIBM/ProdData/OS/WebServices/V1/client/bin/wsdl2ws.sh -lrpg -o/INVENTRYxx –s/qsys.lib/INVENTRYxx.lib/WCBISTUB.srvpgmhttp://<hostname>:<port>/web/services/WarehouseCoffeeBeanInventory?wsdl

Note: Replace INVENTRYxx with your team’s directory. In addition, replace the host name and port in the WSDL URI with your server’s host and port. The URL path to your WarehouseCoffeeBeanInventory WSDL should be documented in your Team Information handout you received with this lab.

The above command will generate RPG and C files because the RPG stub transparently uses the C stub. The files will be stored in directory specified for the –o option. A service program, INVENTRYxx/WCBISTUB will be created from the generated stub code. A successful invocation of the wsdl2ws.sh tool will look like the following:

Page 54 of 60

o 2. Let us examine what is generated by the wsdl2ws.sh tool Issue the following commands within QShell:

o a. cd /INVENTRYxx

o b. ls

You should see the following files displayed in the QSHELL output:

ORDERINVENTORYInput.c ORDERINVENTORYInput.h ORDERINVENTORYResult.c ORDERINVENTORYResult.h WarehouseCoffeeBeanInventoryPortType_util.rpgle WarehouseCoffeeBeanInventoryPortType_util.rpgleinc WarehouseCoffeeBeanInventoryPortType_xsdtypes.rpgleincWarehouseCoffeeBeanInventoryPortType.c WarehouseCoffeeBeanInventoryPortType.cl WarehouseCoffeeBeanInventoryPortType.h WarehouseCoffeeBeanInventoryPortType.rpgle WarehouseCoffeeBeanInventoryPortType.rpgleinc

As has been previously mentioned, when you use the tool, C stubs files will get generated. In addition, 6 files will get generated (the XXXX below is the WSDL portType name):

XXXX.cl --- CL source to create service programXXXX.rpleinc --- RPG web service includeXXXX.rpgle --- RPG web service implementation codeXXXX_util.rpgleinc ---- RPG utility routines includeXXXX_util.rpgle ---- RPG utility routinesXXXX_xsdtypes.rpgleinc ---- standard data types include

From the perspective of a person wanting to write an application to invoke a web service, the only files you need to look at are XXXX.rpgleinc and XXXX_xsdtypes.rpgleinc. That is it. The XXXX.rpgleinc file will contain the WSDL-defined types, the two web service stub routines:

stub_create_XXXXstub_destroy_XXXX

And the functions corresponding to the web service operations whose names start with "stub_op_".

o c. Exit QSHELL by pressing F3=Exit

Page 55 of 60

o d. Examine the WarehouseCoffeeBeanInventoryPortType.rpgleinc file by issuing the following CL command:

edtf '/INVENTRYxx/WarehouseCoffeeBeanInventoryPortType.rpgleinc'

You will see the following types:

D ORDERINVENTORYInput_t... D DS qualified based(Template) D isNil_ORDERINVENTORYInput_t... D 1n D ITEMNO likeds(xsd_string) D REQCOUNT likeds(xsd_int)

D ORDERINVENTORYResult_t... D DS qualified based(Template) D isNil_ORDERINVENTORYResult_t... D 1n D RTNCOUNT likeds(xsd_int)

The types that start with the xsd_ prefix are primitive types and are defined in WarehouseCoffeeBeanInventoryPortType_xsdtypes.rpgleinc.

You will also see the following function prototypes:

D stub_create_WarehouseCoffeeBeanInventoryPortType... D PR 1N extproc('stub_create_WarehouseCoff+ D eeBeanInventoryPortType@') D this likeds(This_t) D stub_destroy_WarehouseCoffeeBeanInventoryPortType... D PR 1N extproc('stub_destroy_WarehouseCof+ D feeBeanInventoryPortType@') D this likeds(This_t)

These functions are used to obtain and destroy a web service interface handle. Before a web service operation can be invoked, a web service interface handle needs to be obtained. The handle will be passed to functions representing the web service operations when invoking a web service operation. Below are the functions representing the web service operations:

D stub_op_orderinventory_XML... D PR 1N extproc('orderinventory_XML@')D this likeds(This_t) D Value0 likeds(ORDERINVENTORYInput_t) D out likeds(xsd_string)

D stub_op_orderinventory... D PR 1N extproc('orderinventory@') D this likeds(This_t) D Value0 likeds(ORDERINVENTORYInput_t) D out likeds(ORDERINVENTORYResult_t)

Go to the next exercise to see how the stub code is used in an RPG application.

Page 56 of 60

Exercise 7b: Review Client Source Code and Create Application

o 1. With a 5250 session, review the RPG source code for the RPG client application that consumes the WarehouseCoffeeBeanInventory web service provided by Over the Top Coffee’s supplier.

o a. Issue STRPDM, Option 3. Specify file QRPGLESRC, library INVENTRYxx (where xx is your assigned student number), and member name ORDERMORE. Press Enter.

o b. File member ORDERMORE will be displayed. Open the ORDERMORE source code for editing using Option 2=Edit and notice the following statements.

WsStub.endpoint = 'http://<hostname>:<port>/web/+ services/WarehouseCoffeeBeanInventory';

Action Required: Replace the <hostname> and <port> variables with the hostname and port information for your <WSERVICEyy> web services server. This information can be found in the Team Information handout you received with this lab.

The statements of interest in the file are the following:

stub_create_WarehouseCoffeeBeanInventoryPortType(WsStub) – the function call obtains a handle to the web service interface that is capable of communicating with the WarehouseCoffeeBeanInventory web service.

stub_op_orderinventory(WsStub:Input:Result) – this function call results in web service request being sent out to web service and returns any response. Note that it is called multiple times since the code is in a loop.

stub_destroy_WarehouseCoffeeBeanInventoryPortType(WsStub) – this function call destroys the web service interface handle.

o c. Press F3=Exit and save the updated source file member.

Page 57 of 60

o 2. With a 5250 session, compile the RPG source code for the RPG client application that consumes the WarehouseCoffeeBeanInventory web service provided by Over the Top Coffee’s supplier. Do not forget to replace INVENTRYxx with your assigned team library in the following commands.

o a. ADDLIBLE INVENTRYxx

o b. CRTRPGMOD MODULE(INVENTRYxx/ORDERMORE) INCDIR('/INVENTRYxx') SRCFILE(INVENTRYxx/QRPGLESRC) DBGVIEW(*SOURCE)

o c. CRTPGM PGM(INVENTRYxx/ORDERMORE)

MODULE(INVENTRYxx/ORDERMORE) BNDSRVPGM(QSYSDIR/QAXIS10CC INVENTRYxx/WCBISTUB)

The one thing to note when creating the RPG application is the two service programs that are bound to when creating the program. QSYSDIR/QAXIS10CC is the web service client engine that handles all the serialization and deserialization of SOAP messages, and the sending and receiving of SOAP messages over the HTTP and HTTPS transports. The other service program, INVENTRYxx/WCBISTUB, is the service program that is created by the wsdl2ws.sh tool and contains the stub code that the tool generates.

Page 58 of 60

Exercise 7c: Consume the WarehouseCoffeeBeanInventory Web Service

o 1. With a 5250 session, view Over the Top Coffee’s current inventory items by calling their in-house 5250 "Green Screen"Coffee Bean Inventory application and reviewing how many in stock and on order items they have for each inventory item by issuing the following commands from a command line:

o a. ADDLIBLE LIB(INVENTRYxx)

o b. CALL PGM(COFFEE)

Note: For most inventory items, the In Stock Amount plus the Quantity on Order Amount do not currently add up to a sum of 25.

Press F3 or F12 to exit the example Coffee Bean Inventory application’s display screen.

o 2. Now let us call our RPG client application (ORDERMORE) from a command line to order more inventory items for Over the Top Coffee. Anytime a coffee item’s Total Quantity is less than 25, more coffee will be ordered to get that total amount equal to 25. Normally this type of program would be run from a batch job running at night, however you are going to call this program interactively.

Remember: Total Quantity = In Stock Amount + Quantity on Order Amount

Issue the following commands from a command line:


o b. CALL PGM(ORDERMORE)

Page 59 of 60

o 3. Now call Over the Top Coffee’s in-house 5250 “Green Screen” Coffee Bean Inventory Application again to see if each coffee item’s Total Quantity is equal to or greater than 25 now that the order more coffee application (ORDERMORE) was called. Remember when the order more coffee application (ORDERMORE) was called it consumed the WarehouseCoffeeBeanInventory web service to order more inventory item’s from Over the Top Coffee’s supplier. Issue the following commands from a command line:


o b. CALL PGM(COFFEE)

Note: If you now add up the In Stock Amount plus Quantity on Order Amount for each coffee inventory item, they should now add up to a Total Quantity value of 25 or greater.


Page 60 of 60

Date post:	24-May-2015
Category:	Technology
Upload:	common-europe
View:	2,825 times
Download:	2 times

Practical web services for RPG lab exercises

Technology