Building a Web service from an RPG program using

Building a Web service from an RPG program using
IBM Rational Developer for Power Systems Software
Skill Level: Intermediate
Service Enabling IBM i Applications Scenario
Page 1
Building a Web service from an RPG program using IBM Rational Developer for Power Systems
Software
Web Services tackle the problem of inefficient distributed computing, because system components need to be loosely coupled and dynamically bound to provide greater flexibility, scalability,
lower overhead costs, and hence, better business growth. The architecture involves a relationship
between Service providers, brokers, and requesters. More specifically, Service requesters submit
a request to a Service broker, which finds the right service from a Service provider. Web Services
development tools allow you to develop this service.
The Web Service wizard (shown in figure below) creates a Web Service, using a JavaBean generated by the IBM i Program Call wizard, to call one or more server programs or service program
procedures on the IBM i. The Web Service wizard works in the context of a Web Project and allows for creation, deployment, testing, generation of a proxy, and publication to a Universal Description, Discovery, and Integration (UDDI) registry of Web services.
Page 2
Service Enabling IBM i Applications Scenario
Various approaches to create web service from the modular IBM i applications:
Pre-requisite for this scenario is that IBM i Applications are modular (callable) either using *PLIST
parameters or using ILE service programs. The recommendation is to use service program over
just callable program due to better performance with service programs.
There are 3 ways the web services could be created using the web services wizards provided in
Rational Developer for Power Systems:
1. Three Step process
a. Create PCML document
b. Create Program Call Bean using program call bean wizard
c. Create a web service from program call bean using web services wizard
2. Two Step process
a. Create PCML document
b. Create Web Service from PCML document using IBM i program web service wizard (combines step b and c from previous scenario)
3. One Step process
a. Create a Web Service from modular IBM i Application using web services wizard in
Remote System Explorer (combines steps a, b and c from 3 step process scenario)
Service Enabling IBM i Applications Scenario
Page 3
o
1. Three Step process

a. Create PCML document (requires source code compilation)
Create PCML document from RPG Module using CRTRPGMOD CL command
either through 5250 session or Remote System Explorer perspective in Rational Developer for Power.
Page 4
Service Enabling IBM i Applications Scenario
Service Enabling IBM i Applications Scenario
Page 5
b. Create program call bean using program call bean wizard
Use IBM i => Program Call Bean wizard to create program call bean to invoke RPG
module.
Page 6
Service Enabling IBM i Applications Scenario

c. Create a web service from program call bean using bottom up Java
Bean Service
Use Program call bean in Web Services wizard (Bottom up Java Bean Web service) to
create and test the web service.
Service Enabling IBM i Applications Scenario
Page 7
o
2. Two Step process

a. Create PCML document using text editor or source code compilation


b. Create web service from PCML document bottom up iSeries web service
wizard

Page 8
same as described in the 3 step process
Use the web services wizard (Bottom up iSeries Program Web Service option) to create and test web service.
Service Enabling IBM i Applications Scenario
Service Enabling IBM i Applications Scenario
Page 9
o
3. One Step process

a. Create web service from IBM i Application using Web Service wizard
which combines all the 3 steps describes above in a single step


Page 10
Invoke the new web services wizard in the Remote System Explorer
perspective.
Next screen it shows web services wizard (Bottom up IBM i Program Web
Service option) to create and test web service.
Service Enabling IBM i Applications Scenario
IBM Toolbox for Java
All the above wizards use IBM Toolbox for Java Classes.
Core IBM Toolbox for Java classes are stored in jt400.jar file. Every System i is shipped with
jt400.jar in multiple directories. If your desktop development tool - for example, Rational Application Developer (RAD), does not have jt400.jar in the development environment, you can add an
external jar reference by copying jt400.jar from IBM i to your desktop system. Another way to get
Toolbox classes is to download the jar file from the product Web site. Rational Developer for
Power is shipped and preconfigured to use Toolbox classes.
For more information on IBM Toolbox for Java visit:
http://www.ibm.com/servers/eserver/iseries/toolbox/
This web site has a Programmer‟s Guide link which brings you to the IBM i V7R1 Info Center.
Spend some time reviewing documentation. You will find that this Web site contains many useful
resources – Javadoc, examples, and product features, and others.
Service Enabling IBM i Applications Scenario
Page 11
Service Enabling IBM i Applications Scenario –
using PCML (Two Step process)
Using Program Call Markup Language (PCML) and Rational Developer for Power Systems
– IBM i program web services wizard:
In this lab you will explore features of IBM Toolbox for Java and use Rational Developer for Power Systems to create Web Service from PCML document using the web services wizard.
 What you should be able to do:
o
At the end of the lab, you should be able to:

Create a web service from PCML document using web services wizard

Test the web service in WebSphere Application Server.
 Steps:
o
The steps in this lab are:

Start Rational Developer for Power Systems

Create, Publish and Test Web Service from the RPG Module

Test the Web Service using Web Services Java Proxy Client
 Skill Prerequisites
o
Page 12
Prerequisite skills for this lab are:

High level understanding of IBM i programs and concepts

Understanding of Java programming language concepts and beginner Java
programming skills
Service Enabling IBM i Applications Scenario
Required Material
o
Client system requirements:

o
IBM Rational Developer for Power Systems V8.5
Lab information sheet:
Variable
Description
Demonet IBM i
<team_number>
Team Number
99
<IBMi>
IBM i hostname
iseriesd.demos.ibm.com
<IBMi_userid>
IBM i user ID
SOADEMO
<IBMi_password>
IBM i password
demo4you
<app_lib>
Application library
FLGHT400
<app_lib_modules>
Application Library Modules
FLGHT400M
<workspace>
Workspace
C:\PoT\SOAiV85\workspace
<team_dir_local>
Team directory local
C:\PoT\SOAiV85\teamxx
o
If you trying to do the lab in your environment then you may download the Flight
Reservation System application libraries from the IBM Redbooks Site.
SG24-7284 - Building SOA-based Solutions for IBM System i Platform
http://www.redbooks.ibm.com/abstracts/sg247284.html?Open
Click on Additional Material and download flght400.zip
Service Enabling IBM i Applications Scenario
Page 13
1.1
Start Rational Developer for Power Systems
Skip to next section if ….
You are already in Rational Developer for Power Systems and you have started WebSphere Application
Server
Start Rational Developer for Power Systems
__1.
Go to Start => All Programs => IBM Software Development Platform => IBM Rational Developer for Power Systems Software V8.5 => IBM Rational Developer for Power Systems Software
__2.
In the workplace launcher window, enter <workspace> (shown by default) in the workspace field and press OK. (Please make sure that Use this as a default and do not ask
again is NOT checked). Note: if not prompted for the workspace go to the next step.
Important!
Please make sure that Use this as a default and do not ask again is
NOT checked
__3.
Page 14
On the Welcome page. Click X to close or press Workbench icon.
Service Enabling IBM i Applications Scenario
Service Enabling IBM i Applications Scenario
Page 15
Start WebSphere Application Server
Start WebSphere Application Server
This is very important before invoking the web services wizard,
as the wizard will fail.
__4.
In current perspective (Remote System Explorer by default). Select Window => Open
Perspective => Other. Select Web Perspective and click OK.
__5.
In the Web Perspective, click on Servers tab (bottom of screen). Select WebSphere
Application Server 8.5 and press Start button.
__6.
You should see console view with startup messages. Once WebSphere Application
Server is started you will see Server view with status “Started, Synchronized”.
Page 16
Service Enabling IBM i Applications Scenario
__7.
Another way to make sure WebSphere Application Server is started is to see the console
view with message “Server server1 open for e-business”.
Troubleshooting
If the WebSphere Application Server does not start. Please check
server connection type and admin port.
To check configuration, double click on WebSphere Application
Server 8.5 under server view. You may manually provide the
connections settings and select SOAP connector port instead of
RMI port which is more compatible with firewalls.
Click on X and save the configuration when prompted.
Service Enabling IBM i Applications Scenario
Page 17
1.2
Create, Publish and Test Web Service from the RPG Module
Open Web Perspective
__1.
Make sure you are in Web Perspective; otherwise go to Window => Open Perspective
=> Other. In the Open Perspective window, select Web and click OK.
Create a Web Project
__2.
Page 18
Create a Web project: Select File => New => Web Project
Service Enabling IBM i Applications Scenario
__3.
In New Web Project window,
Enter Name: FSxxService (where xx is your team number)
Click Next.
Select Target Runtime : WebSphere Application Server V8.5
Enter EAR Project Name : FSxxServiceEAR (where xx is your team number)
Service Enabling IBM i Applications Scenario
Page 19
__4.
Page 20
On Web Module settings page, it allows you to change the context root and other parameters for the project. Click Finish.
Service Enabling IBM i Applications Scenario
__5.
Under Project Explorer Expand FSxxService project => Click on WebContent folder.
Import PCML Document
__6.
Select File -> Import from menu. In Import window, expand General Category and select File System and click Next.
Service Enabling IBM i Applications Scenario
Page 21
__7.
Page 22
Click Browse next to From Directory field. Navigate to
<team_dir_local>\RPGWebServices_lab directory and click OK.
Service Enabling IBM i Applications Scenario
__8.
Back in import window, select nfs404.pcml file and make sure FSxxService/WebContent is selected in Into Folder field and click Finish.
Service Enabling IBM i Applications Scenario
Page 23
Review PCML Document
__9.
Double click on nfs404.pcml document. Double click on nfs404.pcml editor window to
maximize the window. This document was created using CRTRPGMOD command either
in 5250 session or Remote System Explorer.
FINDFLIGHTS method has :
3 Input and 2 output parameters
One of the output parameter is a structure (FLIGHTINFO), which occurs 50 times
FLIGHTINFO structure is also defined in the document.
FINDFLIGHTS method is located in nfs400 service program.
Please DO NOT make any changes.
__10.
Double click on nfs404.pcml editor window to revert back to original size.
__11.
Close the nfs404.pcml editor view by clicking on „X‟
Page 24
Service Enabling IBM i Applications Scenario
Create and Test RPG Web Service
__12.
Right click on PCML document nfs404.pcml. Select Web Services => Create Web Service.
Service Enabling IBM i Applications Scenario
Page 25
__13.
Page 26
Next you will see Web Service wizard with Bottom up IBM i Program Web Service. Ignore
the error message (The service implementation selected is invalid) for now.
Service Enabling IBM i Applications Scenario
__14.
First, we will select Web Service creation options. This wizard allows you to Develop, Assemble, Deploy, Install, Start and Test the web service. Use the dial to look at various options. Move the bar to Test position as shown below. The Test option allows you to test
the web service using Web Services Explorer.
__15.
Next, we will setup Service Implementation parameters. Click on browse next to Service
Implementation box.
Service Enabling IBM i Applications Scenario
Page 27
__16.
RPG modules that we are using in this lab have been compiled into a service program
NFS400.srvpgm (not a part of this lab exercise – it has been compiled prior to this lab).
We have to manually enter service program name because PCML generator does not
have this information. Compiling RPG modules to service programs is a standard practice
for deploying RPG modules. In addition, bundling RPG modules in a service program will
result in better performance when using Program Call class.
Click on + sign next FLIGHTINFO node to expand it. Review the FLIGHTINFO structure.
Click on + sign next FINDFLIGHTS node to expand it. Review the input and output parameters.
Then click on FINDFLIGHTS to select it which shows the program object information.
Change the Program Object field from nfs404 to nfs400.
Page 28
Service Enabling IBM i Applications Scenario
__17.
Next, we will set runtime configuration which involves authentication and library list information. Click Edit next to Runtime configuration.
__18.
On Configure Authentication dialog, check the signon values, it should list <IBMi> hostname, <IBMi_userid> userid and <IBMi_password> password. (Please refer to lab information section of the lab) Click Next.
Configure Authentication
On this screen you can specify program call J2C connector information by specifying the JNDI name which will be configured
using WebSphere Application Server Administrative Console.
Usage of JNDI names is recommended for the production environment.
Service Enabling IBM i Applications Scenario
Page 29
__19.
On Configure Runtime Environment dialog, we will specify the library list required to execute the application. Enter library <app_lib> (Please refer to lab information section of
the lab) and click Add.
Also enter another library <app_lib_modules> (Please refer to lab information section of
the lab) and click Add.
__20.
Page 30
Change library position of <app_lib_modules> to *FIRST by selecting the list box and
click Finish.
Service Enabling IBM i Applications Scenario
__21.
On Select Service Implementation screen, click OK.
__22.
Back in Web Service dialog, make sure WebSphere v8.5 Server server and IBM WebSphere JAX-RPC web service runtime is selected under configuration and click Next.
__23.
After few seconds you will see the next dialog, Service Endpoint Interface Selection.
Take the default values and click Next.
Service Enabling IBM i Applications Scenario
Page 31
__24.
On the Web Services Java Bean Identity dialog, it shows WSDL port name, WSDL file
name and various methods the wizard is going to generate.
There are 2 methods generated for each java bean (RPG procedures) :
For examples for FINDFLIGHTS procedure it will generate :
findflights and findflights_XML
Click Next
__25.
Page 32
At this stage the wizard will generate WSDL, publish and deploy the web service to the
WebSphere Application Server. On Test the Web Service Dialog, click Launch button
next to Test Facility.
Service Enabling IBM i Applications Scenario
__26.
You will see the Web Services Explorer in a separate browser window. Click findflights
link to test findflights method.
Generated Methods
Web Services Wizard generates two methods to give developers
flexibility in using the Program Call bean. For example, in a Web
services integration scenario, developers may want use the method that returns an XML document, and for Java integration scenario the method that returns a Java object.
Service Enabling IBM i Applications Scenario
Page 33
__27.
Enter following input parameters:
FROMCITY: Albany
TOCITY: Atlanta
FLIGHTDATE: 09122010
Click Go
You should see 9 flights returned in the status pane.
You may also test findflights_XML method which will return XML document.
__28.
Close the browser and go back to Rational Developer for Power Systems window and
click Next.
__29.
On Web Service Publication dialog, click Finish.
Page 34
Service Enabling IBM i Applications Scenario
Review the Generated code
__30.
Make sure you are in Web perspective, otherwise open Web Perspective by going to
Window => Open Perspective => Web.
__31.
Expand FSxxService project. (where xx is your <team_number>)
__32.
In Project Navigator expand
FSxxService\Java Resources : src\iseries.wsbeans.findflights folder.
Spend some time reviewing the files
Java Classes generated by Web Services Wizard
Web Services Wizard generates various Java classes and two properties files:
FLIGHTINFO.java: this class captures information stored in FLIGHTINFO data
structure defined in the nfs404 RPG program.
FINDFLIGHTSInput.java: this class encapsulates input parameters to pass to the
RPG program
FINDFLIGHTSResult.java: this class encapsulates output parameters that are returned from the RPG program
FINDFLIGHTSServices.java: this class performs RPG program call using Toolbox
classes
Service Enabling IBM i Applications Scenario
Page 35
__33.
Let‟s take a closer look at FINDFLIGHTSServices.java. Double click on
FINDFLIGHTSServices.java. Two methods in this Java Bean invoke nfs404 RPG program, the difference is in the methods‟ return parameters:
findflights(…): returns FINDFLIGHTSOutput object
findflights_XML(…): returns a String object that contains an XML document
Expanding editor view
To expand editor view, double click on the window title. Double
click on the window title again to revert back to the original size.
Click X to close the editor view.
Page 36
Service Enabling IBM i Applications Scenario
__34.
Examine the WSDL document. Expand Web Content => WEB-INF => wsdl folder.
Double click on FINDFLIGHTSServices.wsdl document. Check various methods with
input and output parameters. Select the FINDFLIGHTSServices port and check the port
address in the properties view.
Click X to close the WSDL editor.
Service Enabling IBM i Applications Scenario
Page 37
1.3
Test the Web Service using Web Services Java Proxy Client
In this step, we will see how to create Web Service Client Proxy using WSDL document
and test the web service created in the previous step.
Generate Web Service Client.
__35.
Right click on FINDFLIGHTSServices.wsdl and select Web Services => Generate
Client.
__36.
This wizard let‟s you develop, assemble, deploy, install, start and test the client. Use the
bar in the left side and move to Test position. Click on Client project: FSxxService link
Page 38
Service Enabling IBM i Applications Scenario
__37.
On the Specify Client Project Setting dialog, enter
Client Project : FSxxServiceClient
Client EAR Project will be set accordingly : FSxxServiceClientEAR
Click OK.
__38.
Back in Web Service Client dialog, Click Next.
__39.
On Web Service Proxy Page dialog, click Next. If you see any overwrite warning for
web.xml click Yes to all to proceed. This will take few seconds as the wizard will publish
and deploy the project to WebSphere Application Server.
Service Enabling IBM i Applications Scenario
Page 39
__40.
On Web Service Client Test dialog, it shows various methods which are available. Click
Finish.
__41.
After few moments, you should see the browser with Web Service test client.
Troubleshooting
If you see HTTP Error Code: 404: FileNotFoundExcpetion.
Close the browser view. Expand FSxxServiceClient project =>
WebContent =>sampleFINDFLIGHTSServicesProxy.
Right click on TestClient.jsp and select Run As => Run on Server. This happens because code creation and publishing processes
conflict with each other.
Page 40
Service Enabling IBM i Applications Scenario
__42.
Click findflights method in the left navigation. Enter following input parameters:
TOCITY: Atlanta
FLIGHTDATE: 09122010
FROMCITY: Albany
Click Invoke.
You will see 9 flights returned in Results pane.
You may test findflights_XML method.
Service Enabling IBM i Applications Scenario
Page 41
Review Generated Code
__43.
In Project Navigator expand
FSxxServiceClient\Java Resources : src\iseries.wsbeans.findflights folder. Spend
some time reviewing the files.
__44.
Expand WebContent\sampleFINDFLIGHTSServicesProxy folder to look at the test
clients JSPs.
Congratulations!!!
You have completed this lab.
Page 42
Service Enabling IBM i Applications Scenario
Notices
© Copyright IBM Corporation 1992, 2012 All rights reserved.
U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP
Schedule Contract with IBM Corp.
This information was developed for products and services offered in the U.S.A. IBM may not offer the
products, services, or features discussed in this documentation in other countries. Consult your local
IBM
representative for information on the products and services currently available in your area. Any
reference to an IBM product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product, program, or service
that does not infringe any IBM intellectual property right may be used instead. However, it is the user’s
responsibility to evaluate and verify the operation of any non -IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter des cribed in this documentation. The furnishing of this documentation does not give you any license to these patents. You can
send license inquiries, in writing, to:
IBM Director of Licensing IBM Corporation
North Castle Drive
Armonk, NY 105041785 U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property
Department in your country or send inquiries, in writing, to:
IBM World Trade Asia Corporation
Licensing
2-31 Roppongi 3-chome, Minatoku Tokyo 106, Japan
The following paragraph does not apply to the United Kingdom or any other country where such
provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION
PROVIDES THIS PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OR CONDITIONS OF
NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some
states do not allow disclaimer of express or implied warranties in certain transactions, theref ore, this
statement may not apply to you.
″
″
This information could include technical inaccuracies or typographical errors. Changes are periodically
made to the information herein; these changes will be incorporated in new editions of the publication.
IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not
in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not
part of the materials for this IBM product and use of those Web sites is at your own risk.
Service Enabling IBM i Applications Scenario
Page 43
Licensees of this program who wish to have information about it for the purpose of enabli ng: (i) the
exchange of information between independently created programs and other programs (including this
one) and (ii) the mutual use of the information which has been exchanged, should contact:
Intellectual Property Dept. for WebS phere Software IBM Corporation
3600 Steeles Ave. East
Markham, Ontario
Canada L3R 9Z7
Such information may be available, subject to appropriate terms and conditions, including in some cases,
payment of a fee.
The licensed program described in this documentation and all licensed material available for it are
provided by IBM under terms of the IBM Customer Agreement, IBM International Program License
Agreement or any equivalent agreement between us.
Any performance data contained herein was determined in a controlled environmen t. Therefore, the
results obtained in other operating environments may vary significantly. Some measurements may have
been made on development-level systems and there is no guarantee that these measurements will be the
same on generally available systems. Furthermore, some measurements may have been estimated through
extrapolation. Actual results may vary. Users of this document should verify the applicable data for their
specific environment.
Information concerning non-IBM products was obtained from the suppliers of those products, their
published announcements or other publicly available sources. IBM has not tested those products and
cannot confirm the accuracy of performance, compatibility or any other claims related to non -IBM
products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of
those products.
All statements regarding IBM’s future direction or intent are subject to change or withdrawal without
notice, and represent goals and objectives only.
Copyright license
This information contains sample application programs in source language, which illustrates programming techniques on various operating platforms. You may copy, modify, and distribute these
sample programs in any form without payment to IBM, for the purp oses of developing, using, marketing or distributing application programs conforming to the application programming interface for
the operating platform for which the sample programs are written. These examples have not been th oroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, service ability, or function of these programs.
Each copy or any portion of these sample programs or any derivative work, must include a copyright
notice as follows:
© (your company name) (year). Portions of this code are derived from IBM Corp. Sample Programs. ©
Copyright IBM Corp. 1992, 2009. All rights reserved
Trademarks and service marks
The following terms are trademarks or registered trademarks of International Business Machines
Corporation in the United States, other countries, or both.
Page 44
Service Enabling IBM i Applications Scenario
•
•
•
•
•
IBM i
IBM
OS/400
Rational
WebSphere
Microsoft, Windows, and the Windows logo are trademarks of Microsoft Corporation in the United States,
other countries, or both.
Other company, product or service names may be trademarks or service marks of others.
Service Enabling IBM i Applications Scenario
Page 45