building a web service from an rpg program using ibm rational

Service Enabling IBM i Applications Scenario

Building a Web service from an RPG program using

IBM Rational Developer for Power Systems Software

Skill Level: Intermediate


Building a Web service from an RPG program us-ing IBM Rational Developer for Power Systems Software Web Services tackle the problem of inefficient distributed computing, because system compo-nents 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 gen-erated 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 al-lows for creation, deployment, testing, generation of a proxy, and publication to a Universal De-scription, Discovery, and Integration (UDDI) registry of Web services.


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 wi-zard (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 scena-rio)


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 Ra-tional Developer for Power.


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.


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.


o 2. Two Step process

a. Create PCML document using text editor or source code compilation

same as described in the 3 step process

b. Create web service from PCML document bottom up iSeries web service wizard

Use the web services wizard (Bottom up iSeries Program Web Ser-vice option) to create and test web service.


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

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.


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 Applica-tion 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.

http://www.ibm.com/servers/eserver/iseries/toolbox/


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 Pow-er 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 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


Required Material

o Client system requirements:

IBM Rational Developer for Power Systems V8.5

o 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

http://www.redbooks.ibm.com/abstracts/sg247284.html?Open


1.1 Start Rational Developer for Power Systems

Skip to next section if ….

You are already in Rational Developer for Power Sys-tems and you have started WebSphere Application Server

Start Rational Developer for Power Systems

__1. Go to Start => All Programs => IBM Software Development Platform => IBM Ration-al Developer for Power Systems Software V8.5 => IBM Rational Developer for Pow-er Systems Software

__2. In the workplace launcher window, enter <workspace> (shown by default) in the work-space 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. On the Welcome page. Click X to close or press Workbench icon.


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


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


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. Create a Web project: Select File => New => Web Project


__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 num-ber)


__4. On Web Module settings page, it allows you to change the context root and other para-meters for the project. Click Finish.


__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 se-lect File System and click Next.


__7. Click Browse next to From Directory field. Navigate to <team_dir_local>\RPGWebServices_lab directory and click OK.


__8. Back in import window, select nfs404.pcml file and make sure FSxxSer-vice/WebContent is selected in Into Folder field and click Finish.


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‟


Create and Test RPG Web Service

__12. Right click on PCML document nfs404.pcml. Select Web Services => Create Web Ser-vice.


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


__14. First, we will select Web Service creation options. This wizard allows you to Develop, As-semble, Deploy, Install, Start and Test the web service. Use the dial to look at various op-tions. 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.


__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 pa-rameters.

Then click on FINDFLIGHTS to select it which shows the program object information.

Change the Program Object field from nfs404 to nfs400.


__17. Next, we will set runtime configuration which involves authentication and library list infor-mation. Click Edit next to Runtime configuration.

__18. On Configure Authentication dialog, check the signon values, it should list <IBMi> host-name, <IBMi_userid> userid and <IBMi_password> password. (Please refer to lab in-formation section of the lab) Click Next.

Configure Authentication

On this screen you can specify program call J2C connector in-

formation by specifying the JNDI name which will be configured

using WebSphere Application Server Administrative Console.

Usage of JNDI names is recommended for the production envi-

ronment.


__19. On Configure Runtime Environment dialog, we will specify the library list required to ex-ecute 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. Change library position of <app_lib_modules> to *FIRST by selecting the list box and click Finish.


__21. On Select Service Implementation screen, click OK.

__22. Back in Web Service dialog, make sure WebSphere v8.5 Server server and IBM WebS-phere 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.


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


__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 me-

thod that returns an XML document, and for Java integration sce-

nario the method that returns a Java object.


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


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 re-

turned from the RPG program

FINDFLIGHTSServices.java: this class performs RPG program call using Toolbox

classes


__33. Let‟s take a closer look at FINDFLIGHTSServices.java. Double click on FINDFLIGHTSServices.java. Two methods in this Java Bean invoke nfs404 RPG pro-gram, 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.


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


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


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


__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 Serv-

er. This happens because code creation and publishing processes

conflict with each other.


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


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.


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 described in this docu-

mentation. 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 Licens-

ing IBM Corporation

North Castle Drive

Armonk, NY 10504-

1785 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, Minato-

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


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 Soft-

ware 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 pro-

gramming techniques on various operating platforms. You may copy, modify, and distribute these

sample programs in any form without payment to IBM, for the purposes of developing, using, market-

ing 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 o-

roughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, servicea-

bility, 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.


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

building a web service from an rpg program using ibm rational

Documents