Contents


Building a Web service from a RPG program by using IBM Rational Developer for System i for SOA Construction

Enabling services in IBM i (previously known as i5/OS) applications by using Program Call Markup Language (PCML)

Comments

Before you start

Learn what to expect from this tutorial and how to get the most out of it.

About this series

Work through this scenario and others as part of the Enterprise Modernization Sandbox for IBM® i™.

About this tutorial

  • This tutorial teaches you how to create Web services in front of an RPG application by using the Web Services wizard in Rational Developer for System i for SOA Construction.
  • This tutorial uses a Program Call Markup Language (PCML) document to retrieve interface definitions of the RPG application.

Objectives

You will learn how to:

  • Start IBM® Rational® Developer for System i for SOA Construction
  • Create, publish, and test a Web service from the Report Program Generator (RPG) module
  • Test the Web service by using a Web services Java proxy client

Prerequisites

  • You should be familiar with one of the IBM Software Delivery Platform products that Rational Developer for System i supports and have knowledge of IBM System i applications.
  • High-level understanding of IBM i5/OS programs and concepts
  • Understanding of Java programming language concepts and beginner Java programming skills

System requirements

Operating system options

Microsoft® Windows® 2000 SP4, Windows 2003 Enterprise SP1, Windows 2003 Standard SP1, Windows XP® Professional SP2, Windows Vista® Business, Windows Vista Enterprise, or Windows Vista Ultimate

Hardware

  • Intel® Pentium® III with an 800 MHz processor, minimum (higher is recommended)
  • 512 MB RAM (1 GB RAM recommended)
  • 800 MB of disk space, minimum, which is required for product package installation. Additional disk space is required for the resources that you develop.

Introduction to the Web Services wizard

Web services tackle the problem of inefficient distributed computing with system components that are loosely coupled and dynamically bound to provide greater flexibility and scalability. This results in lower overhead costs and thus, 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 help you develop this service.

The Web Services wizard (shown in Figure 1) creates a Web service by using Java™Beans technology generated by the IBM i5/OS Program Call wizard to call one or more server programs or service program procedures on the i5/OS. The Web Service wizard works in the context of a Web project and enables you to create, deploy, test, generate a proxy, and publish to a Universal Description, Discovery, and Integration (UDDI) registry of Web services.

Figure 1. Web Services wizard
Launched from Remote System Explorer
Launched from Remote System Explorer

Various approaches

The prerequisite for this scenario is that i5/OS applications must be modular (callable), either by using PLIST parameters or using Integrated Language Environment (ILE) service programs. The recommendation is to use a service program rather than just a callable program for better performance.

There are three ways Web services can be created by using the Web services wizards provided in Rational Developer for i for SOA Construction:

  • 3-step process
    1. Create PCML document.
    2. Create a Program Call bean by using the Program Call Bean wizard.
    3. Create a Web service from a program call bean by using the Web Services wizard.
  • 2-step process
    1. Create a PCML document
    2. Create a Web service from a PCML document by using the i5/OS program Web Services wizard (combines Step 2 and 3from the 3-step process)
  • 1-step process
    1. Create a Web service from a modular i5/OS application by using the Web Services wizard in the Remote System Explorer (combines steps 1, 2, and 3 from the 3-step process).

3-step process

  1. Create a PCML document from an RPG module (requires source code compilation) by using the CRTRPGMOD CL command, either through a 5250 session (Figure 2) or through the Remote System Explorer perspective in Rational Developer for System I for SOA Construction (Figure 3).
Figure 2. Command view during a 5250 session for creating a PCML document
systemi5.ws view: Create RPG Module (CRTRPGMOD)
systemi5.ws view: Create RPG Module (CRTRPGMOD)
Figure 3. Remote System Explorer view
Drop-down menu selections: Compile (Prompt) > CRTRPGMOD
Drop-down menu selections: Compile (Prompt) > CRTRPGMOD
  1. Create a Program Call bean by using the System i Program Call wizard (Figure 4) to invoke the RPG module.
Figure 4. Program Call wizard
FINDFLIGHTS selected on L, Edit Program fields, R
FINDFLIGHTS selected on L, Edit Program fields, R
  1. Use a Program Call bean in the Web Services wizard (Figure 5), with the bottom-up Java Bean Web service option, to create and test a Web service.
Figure 5. Web Services wizard
Svc. implement.: myPackage.GETFLIGHTINFOServices
Svc. implement.: myPackage.GETFLIGHTINFOServices

2-step process

  1. Create PCML document by using the text editor or source code compilation as described in the 3-step process
  2. Create a Web service from a PCML document by using the IBM® iSeries® Web Services wizard (Bottom up iSeries Program Web Service option), as Figure 6 shows.
Figure 6. Web Services wizard
Svc. implement.: workspace7101 > FINDFLIGHTS.pcml
Svc. implement.: workspace7101 > FINDFLIGHTS.pcml

1-step process

  1. Create a Web service from an i5/OS application by using the Web Services wizard in the Remote System Explorer, which combines all of the three steps describes previously into a single step
    • Invoke the new Web Services wizard in the Remote System Explorer perspective (Figure 7).
    • The screen that follows shows the Web Services wizard (Bottom up i5/OS Program Web Service option) to create and test a Web service.
Figure 7. Remote System Explorer view
Drop-down menus: Web Services > Create Web Service
Drop-down menus: Web Services > Create Web Service

All of these wizards use the IBM Toolbox for Java Classes. The core classes are stored in the jt400.jar file. System i software includes a jt400.jar file in multiple directories. If your desktop development tool (for example, Rational Application Developer) does not have the jt400.jar file in the development environment, you can get the toolbox classes in either of these ways:

  • Add an external JAR (JavaArchive) reference by copying the jt400.jar file from System i to your desktop system.
  • Download the JAR file from the product Web site.

Rational Developer for System i is preconfigured to use the toolbox classes.

Check the IBM Toolbox for Java site for more information. This Web site includes a Programmer's Guide link that takes you to the iSeries V5R4 Information Center. Spend some time reviewing the documentation. This Web site offers many useful resources, such as the Javadoc, examples, and product feature descriptions.

Service-enabling i5/OS applications by using PCML, 2-step process

In this tutorial, you will explore features of IBM Toolbox for Java and use Rational Developer for System i to create a Web service from a Program Call Markup Language (PCML) document by using the Web Services wizard.

By using PCML and Rational Developer for System i SOA Construction i5/OS program Web Services wizard, you should be able to do these tasks when you have completed this tutorial:

  • Create a Web service from a PCML document by using the Web Services wizard.
  • Test the Web service in an IBM® WebSphere® Application Server test environment.

Summary of steps

  1. Start Rational Developer for System i.
  2. Create, publish, and test the Web service from the RPG module.
  3. Test the Web service by using the Web services Java proxy client.

Prerequisite skill and knowledge

  • A high-level understanding of IBM i5/OS programs and concepts
  • An understanding of Java programming language concepts and beginner Java programming skills

What you will need

Client system requirements

Rational Developer for System i Version 7.1

Tutorial access information

See Table 1. Keep this handy for reference throughout the tutorial.

Table 1. Tutorial access information
VariableDescriptionDemoNet System i
<team_number>Team number99
<Systemi> System i hostnameiseriesd.dfw.ibm.com
<Systemi_userid>System i user IDSOADEMO
<Systemi_password> System i passworddemo4you
<app_lib>Application library FLGHT400
<app_lib_modules> Application library - modulesFLGHT400M
<workspace>Workspace C:\PoT\SOAiV71\workspace
<team_dir_server>Team directoryNA
<team_dir_local>Team directory, local C:\PoT\SOAiV71\teamxx

Flight Reservation System application

This tutorial is based on a theoretical Flight Reservation System application, which you need to download. You also need a user ID, password, and other information for access and navigation.

If you doing this tutorial in your environment, you can download the Flight Reservation System application libraries from the IBM Redbooks site:

  1. Go to SG24-7284 - Building SOA-based Solutions for IBM System i Platform.
  2. Click Additional Materials (Figure 8) and download the flght400.zip file.
Figure 8. IBM Redbooks download area
Pointer to Additional Materials
Pointer to Additional Materials

Get your system and work area ready

Skip to next section if...
You are already in Rational Developer for System i and you have started WebSphere Application Server Test Environment

Start Rational Developer for System i

  1. Go to Start > All Programs > IBM Software Development Platform > IBM Rational Developer for System i > IBM Rational Developer for System i.
  2. In the workplace launcher window, enter <workspace> (shown by default) in the workspace field and click OK.

Important:
Make sure that "Use this as a default and do not ask again" is not checked.

  1. On the Welcome page, click the X to close or click the Go to the Workbench icon (see Figure 9).
Figure 9. Welcome screen
Workbench icon on far right
Workbench icon on far right

Start the WebSphere Application Server test environment

Important:
It is very important to start the server test environment before invoking the Web services wizard, because the wizard will fail otherwise.

  1. In the Remote System Explorer perspective, select Window > Open Perspective > Other.
  2. Select the Web perspective, and click OK.
  3. In the Web perspective, click the Servers tab at the bottom of screen (Figure 10).
  4. Right-click WebSphere Application Server 6.1, and select Start from the drop-down menu.
Figure 10. i5/OS Remote System Explorer view
Servers tab after Properties and Quick Edit tabs
Servers tab after Properties and Quick Edit tabs

Next, you should see the Console view with startup messages. After WebSphere Application Server is started, you will see the Servers view (Figure 11) with the status showing as Started.

Figure 11. Servers view
3 columns: Server, Status, State
3 columns: Server, Status, State

Tip:
Another way to make sure that the WebSphere Application Server test environment is started is to check the Console view, which will show this message: Server server1 open for e-business (Figure 12).

Figure 12. Console view
Message shows in screen output beside WSVR0001I
Message shows in screen output beside WSVR0001I
Figure 13. WebSphere Application Server, Server Overview perspective
2 sections: General, Server
2 sections: General, Server

Create, publish, and test the Web service from the RPG module

Open the Web perspective

  1. Select Window > Open Perspective > Other.
  2. In the Open Perspective window, select Web and click OK.

Create a Web project

  1. Select File > New > Dynamic Web Project.
  2. In New Dynamic Project view (Figure 14), enter this information:
    • Project Name: FSxxService (where xx is your team number)
    • Target Runtime: Select WebSphere Application Server V6.1
    • EAR Project Name:FSxxServiceEAR (where xx is your team number)
  3. Click Next.
Figure 14. New Dynamic Project view
Use default & Add project to EAR checked (default)
Use default & Add project to EAR checked (default)
  1. In the project facets window, you can add various components support to the project.
  2. Click Next.
  3. In the Configure Web module settings window, you can change the content root and other parameters for the project.
  4. Click Finish.
  5. In the Project Explorer, expand Dynamic Web Projects > FSxxService project, and then click the WebContent folder (see Figure 15).
Figure 15. Project Explorer
Shows the WebContent folder selected

Import the PCML document

  1. Select File > Import from the menu.
  2. In the Import view, expand the General category and select the File System folder (Figure 16).
Figure 16. Import view
Shows the File System folder selected
Shows the File System folder selected
  1. Next to the From Directory field, click Browse.
  2. Navigate to the<team_dir_local>\RPGWebServices_lab folder (Figure 17), and click OK.
Figure 17. Select the directory to import from
"Import from directory" view
  1. Back in the Import view, select the check box for the nfs404.pcml file, make sure that FSxxService/WebContent is selected in the Into Folder field, and click Finish (Figure 18).
Figure 18. Import resources from the local file system
Import view for File system
Import view for File system

Review the PCML document

  1. Double-click the nfs404.pcml document tab (Figure 19). This document was created by using the CRTRPGMOD command, either in a 5250 session or in the Remote System Explorer.

The FINDFLIGHTS method includes 3 input and 2 output parameters:

  • One of the output parameters is a structure (FLIGHTINFO), which occurs 50 times.
  • FLIGHTINFO structure is also defined in the document.
  • The FINDFLIGHTS method is located in the nfs400 service program.

Important:
Do not change any values.

Figure 19. Code in the nfs404.pcml file editor view
Screen output of code
Screen output of code
  1. Close the nfs404.pcml editor view by clicking the X.

Create and test the RPG Web service

  1. Close the nfs404.pcml editor view by clicking the X.
  2. Right-click the PCML document named NFS404.pcml and then select Web Services > Create Web Service (Figure 20).
Figure 20. Project Explorer view
Make the latter 2 selections in the drop-down menu
Make the latter 2 selections in the drop-down menu

Next, you will see the Web Services wizard (Figure 21) with a Web service type of Bottom up iSeries Program Web Service. For now, ignore the error message that says "The service implementation selected is invalid."

Figure 21. Web Services wizard
Error message flagged by red bullet with white Xe
Error message flagged by red bullet with white Xe

First, you will select Web Service creation options. This wizard helps you to develop, assemble, deploy, install, start, and test the Web service.

  1. Use the dial to look at various options.
  2. Move the bar on the left to the Test position (Figure 22). This option enables you to test the Web service by using the Web Service Explorer.
Figure 22. Web Services view
The "dial" is a semi-circle arc of 6 icons
The

Next, you will set up Service Implementation parameters.

  1. Next to the Service implementation field, click Browse (Figure 23).
Figure 23. Service implementation selection
Above that is the field for Web service type
Above that is the field for Web service type

Note:
RPG modules for this tutorial have already been compiled to a service program, NFS400.srvpgm, for you (that is not a part of this tutorial exercise). You must manually enter the service program name, because the PCML generator does not include this information. Compiling RPG modules to service programs is a standard practice for deploying RPG modules. Also, bundling RPG modules in a service program will result in better performance when using the Program Call class.

  1. Click the + sign next to the FLIGHTINFO node on the left to expand it. Review the FLIGHTINFO structure.
  2. Click the + sign next to the FINDFLIGHTS node to expand it, and then select FINDFLIGHTS (Figure 24). This will show the program object information on the right.
Figure 24. Program call definitions
9 fields with values on R, all but one populated
9 fields with values on R, all but one populated

Next, you will configure the runtime, which involves authentications and library list information.

  1. Next to Runtime configuration, click Edit (Figure 25).
Figure 25. Select Service Implementation view
Runtime configuration field shows FINDFLIGHTS
Runtime configuration field shows FINDFLIGHTS
  1. In the Configure Authentication dialog (Figure 26), check Specify signon values, which should list these values, which you'll find in Table 1:
    • Host name: <Systemi>
    • User ID: <Systemi_userid>
    • Password: <Systemi_password>

Important:
Check Column 1 in Table 1 for anything between arrow brackets to find the correct <values to type>.

  1. Click Next.
Figure 26. Signon values
3 fields where you must enter info from Table 1
3 fields where you must enter info from Table 1
  1. In the Configure Runtime Environment dialog (Figure 27), enter <app_lib> for the library, and then click Add.
  2. Also enter another library, <app_lib_modules>, and click Add.
Figure 27. Configure Runtime Environment
2 columns: Library and Library Position
2 columns: Library and Library Position
  1. Change the library position of <app_lib_modules> to *FIRST by selecting from the list (Figure 28) and then click Finish.
Figure 28. Change the Library Position field
*FIRST is an option from a drop-down menu
*FIRST is an option from a drop-down menu
  1. On the Select Service Implementation screen, click OK.
  2. Back in the Web Service dialog, under Configuration (Figure 29), make sure that WebSphere v6.1 Server is selected as a target server, and click Next.
Figure 29. Web Service dialog
Link says Server: WebSphere v6.1 Server
Link says Server: WebSphere v6.1 Server

After a few minutes, you will see the next dialog: Service Endpoint Interface Selection.

  1. Accept the default values, and click Next.

The Web Services Java Bean Identity dialog (Figure 30) shows WSDL port name and WSDL file name fields plus various methods that the wizard is going to generate. There are two methods generated for each of the JavaBeans (RPG procedures). For example, for the FINDFLIGHTS procedure, the wizard will generate these two methods:

  • findflights
  • findflights_XML
  1. Click Next.
Figure 30. Web Services Java Bean Identity dialog
Methods are listed with boxes checked beside them
Methods are listed with boxes checked beside them

At this stage, the wizard will publish the Web service to the WebSphere Application Server test environment.

  1. In the Test the Web Service dialog, click the Launch button next to Test Facility. This will launch the Web Services Explorer in a separate browser window.
  2. Click the findflights link (Figure 31) to test the findflights method.
Figure 31. Test the Web Service dialog
Navigator (directory) on left, Actions on right
Navigator (directory) on left, Actions on right

The Web Services wizard generates two methods to give developers flexibility in using the Program Call bean. For example, in a Web services integration scenario, you may want to use the method that returns an XML document, and for a Java integration scenario, you may want to use the method that returns a Java object.

  1. Enter the following input parameters:
    • FROM CITY: Albany
    • TO CITY: Atlanta
    • FLIGHT DATE:09122008
  2. Then click Go.

You should see 9 flights returned in the Status pane (Figure 32).

You can also test the findflights_XML method, which will return an XML document.

Figure 32. Actions view
Subtitle is Invoke a WSDL Operation
Subtitle is Invoke a WSDL Operation
  1. Close the browser, go back to the Rational Developer for System i view, and click Next.
  2. In the Web Service Publication dialog, click Finish.

Review the generated code

  1. Open the Web perspective by selecting Window > Open Perspective > Web.
  2. Expand the Dynamic Web Projects > FSxxService project (where xx is your <team_number>).
  3. In the Project Explorer (Figure 33), expand this folder:
    FSxxService\Java Resources: src\iseries.wsbeans.findflights
  4. Spend some time reviewing the files.
Figure 33. Project Explorer view
Expanded view: iseries.wsbeans.findflights folder
Expanded view: iseries.wsbeans.findflights folder

The Web Services wizard generated various Java classes and two properties files:

  • FLIGHTINFO.java: This class captures information stored in the FLIGHTINFO data structure, which is 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 the RPG program call by using Toolbox classes.
  1. To take a closer look, double-click FINDFLIGHTSServices.java.

Two methods in this Java bean invoke the nfs404 RPG program; the difference is in the methods' return parameters:

  • findflights(...) returns the FINDFLIGHTSOutput object
  • findflights_XML(...) returns a string object that contains an XML document

Expand the editor view

  1. To expand the editor view, double-click the window title (see Figure 34).
  2. Double-click the window title again to revert back to the original size.
  3. Click the X to close the editor view.
Figure 34. Expanded editor view
Shows code in FINDFLIGHTSServices.java
Shows code in FINDFLIGHTSServices.java
  1. Examine the WSDL document:
    1. Expand the Web Content > WEB-INF > wsdl folder (Figure 35).
    2. Double-click the FINDFLIGHTSServices.wsdl document.
    3. Check various methods with input and output parameters.
    4. Select the FINDFLIGHTSServices port, and check the port address in the Properties view (Figure 35).
  2. Click the X to close the WSDL editor.
Figure 35. Web Content folder contents
Properties tab is near bottom of screen
Properties tab is near bottom of screen

Test the Web service by using the Web services Java proxy client

In this step, we will see how to create Web service client proxy by using a WSDL document and then how to test the Web service that you created in the previous step.

Generate the Web service client

  1. Right-click FINDFLIGHTSServices.wsdl, and select Web Services > Generate Client.

This wizard enables you to develop, assemble, deploy, install, start, and test the client.

  1. Move the bar on the left side to the Test client position (Figure 36).
  2. Click the Client project: FSxxService link.
Figure 36. Move the bar to the Test client position
Bar on left, link under Configuration on right
Bar on left, link under Configuration on right
  1. In the Specify Client Project Setting dialog, enter this information:
    • Client project:FSxxServiceClient
    • Client EAR project:FSxxServiceClientEAR
  2. Click OK.
  3. Back in Web Services dialog (Figure 37), click Next.
Figure 37. Web Services dialog
Both options listed under Configuration
Both options listed under Configuration
  1. In the Web Service Proxy Page dialog, click Next. If you see an overwrite warning for the web.xml file, click Yes to all to proceed.

The Web Service Client Test dialog (Figure 38) shows various methods that are available.

  1. Click Finish.
Figure 38. Web Service Client Test dialog
Options for testing, methods, Run on test server
Options for testing, methods, Run on test server

After few moments, you should see the browser with a Web service test client.

  1. Click the findflights method in the left navigation pane (Figure 39), and then enter these input parameters:
    • TO CITY:Atlanta
    • FLIGHT DATE: 09122008
    • FROM CITY: Albany
  2. Click Invoke.

You will see 9 flights returned in results pane.

You can test the findflights_XML method.

Figure 39. Web Services Test Client view
Methods on left, Inputs on right
Methods on left, Inputs on right

Review the generated code

  1. In the Project Navigator, expand this folder:
    FSxxServiceClient\Java Resources: src\iseries.wsbeans.findflights
  2. Spend some time reviewing the files.
  3. Expand the WebContent\sampleFINDFLIGHTSServicesProxy folder to look at the test client's JavaServer Pages (JSPs).

You have completed this tutorial.


Downloadable resources


Related topics


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational
ArticleID=310882
ArticleTitle=Building a Web service from a RPG program by using IBM Rational Developer for System i for SOA Construction
publish-date=06032008