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

Agenda

...........................................................................................................................................................................................................1
.............................................................................................................................................................................................................1
AGENDA.............................................................................................................................................................................................2
LAB INFORMATION...............................................................................................................................................................................3
Lab Prerequisites.......................................................................................................................................................................3
Software and Tool Requirements...............................................................................................................................................3
Lab Setup....................................................................................................................................................................................3
Objectives...................................................................................................................................................................................4
Notes...........................................................................................................................................................................................4
Where 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...............................................................................................7
EXERCISE 2: CREATE AN IBM INTEGRATED WEB SERVICES SERVER FOR I..................................................................................................9
EXERCISE 3: REVIEW STARTING/STOPPING AN INTEGRATED WEB SERVICES SERVER...................................................................................13
EXERCISE 4: REVIEW THE IBM INTEGRATED WEB SERVICES SERVER FOR I..............................................................................................14
Exercise 4a: Server Properties................................................................................................................................................14
Exercise 4b: Manage Deployed Services................................................................................................................................18
Exercise 4c: Example 1 - Test the ConvertTemp Web Service................................................................................................21
Exercise 4d: View the SOAP Message Tracing Logs..............................................................................................................29
EXERCISE 5: DEPLOY RPG BUSINESS LOGIC AS A WEB SERVICE............................................................................................................31
Exercise 5a: The CoffeeBeanInventory Web Service..............................................................................................................32
Exercise 5b: The WarehouseCoffeeBeanInventory Web Service............................................................................................38
EXERCISE 6: TEST DEPLOYED WEB SERVICES ON IBM I........................................................................................................................44
Exercise 6a: Test Operation getitems......................................................................................................................................46
Exercise 6b: Test Operation additem......................................................................................................................................47
Exercise 6c: Test Operation changeitem.................................................................................................................................49
Exercise 6d: Test Operation removeitem................................................................................................................................51
EXERCISE 7: CONSUME THE “WAREHOUSECOFFEEBEANINVENTORY” WEB SERVICE FROM AN RPG CLIENT................................................53
Exercise 7a: Generate and Review Client Stub Code............................................................................................................54
Exercise 7b: Review Client Source Code and Create Application..........................................................................................57
Exercise 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:

o1. 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.
o2. Sign on using your assigned lab userid and password. During the lab you will be
instructed when to use IBM i commands.
o3. 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

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

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.

o1. 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

o2. 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).

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

ob. 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)

oc. 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.

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

http://<hostname>:2001/HTTPAdmin

o2. 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.

o3. 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.

o4. Click on the Create Web Services Server link.

Page 9 of 60

o4. The Create Web Services Server wizard is displayed.

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

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

Page 10 of 60

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

od. 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.

oe. 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.

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

Page 11 of 60

og. 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>.

o1. 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.

o2. 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:

o3. 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.

o4. 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.

oFrom 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

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

oa. 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

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

oc. 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.

od. Click the OK button.

Page 15 of 60

o2. Stop your web services server <WSERVICEyy>.
oa. Click the red stop button in the upper left hand corner of the IBM Web Administration for i
GUI.


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

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

oa. 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

o4. Start your web services server <WSERVICEyy>.

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


ob. 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.

o5. 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

o1. 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.

o2. 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.

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

Page 18 of 60

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

oc. 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.

od. After reviewing all property tabs, click the OK button.

oe 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.

of. 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.

o1. 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.

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

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

Page 21 of 60

ob. 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.

o3. In the Actions panel, click the converttemp operation.

oa. 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

ob. 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

oc. 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.

o4. 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.

oa. 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

ob. 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.

oc. 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.

od. 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

o5. In the Navigator panel, click the converttemp_XML operation.

ob. 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

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

oc. 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

o4. 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.

oa. 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

o1. 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

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

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

o3. 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.

o1. 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.

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

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

Page 32 of 60

ob. 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.

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

Page 33 of 60

od. 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.

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

Page 34 of 60

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

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

Page 35 of 60

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

oi. 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

oj. 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.

display.

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

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

Page 38 of 60

ob. 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.

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

Page 39 of 60

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

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

Page 40 of 60

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

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

oh. Step 8 of 9: Take the default values for WSDL options and select Next.
Page 41 of 60

oi. 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

oj. 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.

o3. 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.

display.

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

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

Page 44 of 60

ob. 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.
o1. In the Actions panel, click the getitems operation.

oa. 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.

o1. In the Actions panel, click the additem operation.

oa. 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

ob. 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.
o1. In the Actions panel, click the changeitem operation.

oa. 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

ob. In the Actions panel, click on the Go button to invoke the changeitem operation. The


Page 50 of 60

Exercise 6d: Test Operation removeitem

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

o1. In the Actions panel, click the removeitem operation.

oa. 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

ob. In the Actions panel, click on the Go button to invoke the removeitem operation. The



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.

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

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

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

oc. 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.srvpgm
http://<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

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

oa. cd /INVENTRYxx

ob. 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.rpgleinc
WarehouseCoffeeBeanInventoryPortType.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 program
XXXX.rpleinc --- RPG web service include
XXXX.rpgle --- RPG web service implementation code
XXXX_util.rpgleinc ---- RPG utility routines include
XXXX_util.rpgle ---- RPG utility routines
XXXX_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_XXXX
stub_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

od. 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@')

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 Value0 likeds(ORDERINVENTORYInput_t)
D out likeds(xsd_string)

D stub_op_orderinventory...
D PR 1N extproc('orderinventory@')
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

o1. 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.

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

ob. 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.

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

Page 57 of 60

o2. 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.

oa. ADDLIBLE INVENTRYxx

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

oc. 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

o1. 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:

oa. ADDLIBLE LIB(INVENTRYxx)

ob. 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.

o2. 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:


ob. CALL PGM(ORDERMORE)

Page 59 of 60

o3. 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:


ob. 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

Practical web services for RPG lab exercises

Recommandé

Recommandé

Contenu connexe

Tendances

Tendances (20)

Similaire à Practical web services for RPG lab exercises

Similaire à Practical web services for RPG lab exercises (20)

Plus de COMMON Europe

Plus de COMMON Europe (20)

Dernier

Dernier (20)

Practical web services for RPG lab exercises