Calling IBM i programs from EGL using Rational Business Developer

Calling IBM i programs from EGL, Page 1 of 63
Calling IBM i programs from EGL using Rational
Business Developer
By Claus Weiss
Advisory Software Consultant
IBM Corporation
May 2009
Skill Level: Intermediate
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 2 of 63
Contents
About this tutorial .......................................................................................................................... 3
Section 1. Before you start............................................................................................................. 3
Introduction.................................................................................................................................... 4
Calling an IBM i program from EGL ............................................................................................ 6
IBM i RPG Program .................................................................................................................. 6
Starting the RDI SOA workbench ............................................................................................. 6
Selecting the web perspective.................................................................................................... 8
Create a new EGL Dynamic Web Project ................................................................................. 9
Creating the linkage options for the program call ................................................................... 12
Specify linkage values ......................................................................................................... 19
Adding linkage to build file ................................................................................................. 20
Create the Program interface information using the EGL Services wizard............................. 24
Creating a web page to provide a user interface for the application........................................ 33
Create EGL Code to call the RPG Program............................................................................. 36
Create fields and button on the Web Page ............................................................................... 41
Handling record not found ....................................................................................................... 51
Debugging the RPG program................................................................................................... 52
Visit the EGL Café to get more information, join the community. ............................................. 58
Additional comments ............................................................................................................... 58
Resources ..................................................................................................................................... 60
About the authors......................................................................................................................... 60
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 3 of 63
About this tutorial
This tutorial describes how to write Enterprise Generation Language (EGL) code that calls
programs (RPG, COBOL, CL, CL Commands, or programs written in any supported language)
on your IBM® i machine. The process for you to call
an existing IBM i™ program from EGL has been very much improved in IBM®
Rational® Developer for i™ V7.1 and is even easier in 7.5 with the new EGL services wizard
in RSE.
EGL leverages the IBM i Toolbox for Java™, which in turn utilizes the IBM i’s Remote
Command Host Server (QZRCSRVSD in the QSYSWRK subsystem).
Section 1. Before you start
Important Note: Walk through this scenario and others online as part of the
Enterprise Modernization Sandbox for IBM i. You can also print the scenario from the pdf
files on the right.
About this tutorial:
This tutorial shows you how to do the following:
• Create EGL application that calls IBM i programs (RPG, COBOL, CL and
CL Commands).
• Learn to use IBM® Rational® Business Developer to build and test EGL
application.
Objectives:
This tutorial will guide you through the following steps:
• EGL and the IBM i runtime environment.
• Configuring your EGL Web Project to access the IBM® i
server and call a program
• The actual code to call an IBM i program
• Debugging both RPG and EGL code
Prerequisites:
You should be familiar with one of the IBM® Rational® Software Delivery Platform
products that Rational Business Developer supports, and have knowledge of IBM® i
applications.
System requirements:
Operating Systems:
Microsoft® Windows® 2000 SP4, Windows 2003 Enterprise SP1, Windows 2003
Standard SP1, Windows XP Professional SP2, Windows Vista Business, Windows
Vista Enterprise, Windows Vista Ultimate
Hardware:
Intel® Pentium® III 800 MHz processor minimum (higher is recommended) 1 GB
RAM (1.5 GB RAM recommended)
Minimum: 800 MB of disk space is required for product package installation.
Additional disk space is required for the resources that you develop.
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 4 of 63
Introduction
This tutorial describes how to write Enterprise Generation Language (EGL) code that calls
programs (RPG, COBOL, CL, CL Commands, or programs written in any supported language)
on your IBM i machine.
Calling an existing IBM i program from EGL has been very much improved in V 7.1 and is
even easier in 7.5 with the new EGL services wizard in RSE.
EGL leverages the IBM i Toolbox for Java™ which in turn utilizes the IBM i’s Remote
Command Host Server (QZRCSRVSD in the QSYSWRK subsystem).
In this tutorial we will guide you thru the following steps:
•
•
•
•
EGL and the IBM i OS runtime environment.
Configuring your EGL Web Project to access the IBM i OS server and call a program
The actual code to call an IBM i program
Debugging both RPG and EGL code.
Note: The pictures in these labs show a similar application being
built. Some of the names and icons may be different than the
environment you are working with. Assume that i5/OS and IBM i
are interchangeable.
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 5 of 63
EGL and the IBM i – Calling IBM i Programs
Calling a RPG, COBOL, CL, or other program on IBM i from EGL is as simple as coding:
CALL “myProgram” (parm1, parmN)
The facility is however extremely flexible and supports the many options that may be required
to support many possible options and configurations
In this scenario an EGL developer is working on RDI SOA on their workstation and running an
EGL application under the WebSphere Test Environment.
EGL uses the IBM i Toolbox for Java™ to call programs on the IBM i. The toolbox in turn uses
the IBM i Remote Command server that is a part of the IBM i Host Servers.
The following steps might sound a bit intimidating but don’t worry everything just happens
automatically and you don’t really need to do anything to make this happen:
•
The Remote Command server in IBM i consists of a server daemon program that listens
for TCP/IP requests from “clients”. This program is QZRCSRVSD which runs in the
QSYSWRK sub-system.
•
When the Remote Command Server starts, it starts a number of “worker” jobs that
process requests in the QUSRSYS sub-system. These jobs are all named QZRCSRVS.
•
The workstation will utilize the Java Toolbox to establish a connection with the Remote
Command server on the IBM i (QZRCSRVSD).
•
The remote command server daemon (QZRCSRVSD) will locate an available work job
(QZRCSRVS in the QUSRWRK sub-system).
•
The user is authenticated. The SWAP ID API will be issued to switch the QZRCSRVS
job from QUSERS to the ID passed in by EGL.
Finally the user program will be called.
Return parameters will be returned up the path back to the invoking EGL program.
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 6 of 63
Calling an IBM i program from EGL
In this section we will walk through the steps involved in creating an EGL web project and
create a simple JSF based Web Page that calls an RPG program on IBM i OS.
IBM i RPG Program
The RPG program you are going to call is named GETDATAE. It is a program with one input
parameter of type character that will return two parameters. One of the parameters is a data
structure that is externally defined which contains detail customer data, the other is a character
field that contains feedback data.
Here is the RPG Source:
FCUSTOML3 IF E
K Disk
*
*Input parameter from Web page
DCustnoi
s
like(CUSTNO)
* Data structure to specify output structure to return to caller
D CSTRUC
E DS
extname(customl3:custom01)
D feedback
s
20
c *entry
plist
c
parm
custnoi
c
parm
cstruc
c
parm
feedback
c
eval feedback=*blank
*
c custnoi
chain(E) customl3
c
if
not %found(CUSTOML3)
c
eval feedback= CUSTNOI
c
else
c
eval feedback='0'
c
endif
*
c
return
Figure 1: GETDATAE RPG Program
As you can see this program when called is passed three variables “custnoi, cstruc, and
feedback”. It gets a customer record, the data is stored in cstruc and stores the feedback for the
data access in variable feedback. Variable feedback contains a 0 if the record was found or the
customer number that could not be found if the access wasn’t successful.
Starting the RDI SOA workbench
You need to start the RDI SOA workbench and select a workspace that will contain all the files
you will use in your development project. We suggest you use a new workspace so your
environment fits the environment we used when we created this script and the screen captures.
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 7 of 63
Start RDI SOA V 7.1
• Click StartÆ All programs Æ IBM Software Development Platform Æ IBM
Rational Business Developer for System i Æ IBM Rational Business Developer for
System i
When prompted for a workspace name
• Enter a new name, like in the figure above, so you get a brand new workspace
Tip: Don’t worry about the directory path, accept the default, just specify a unique directory
for the workspace.
• Click OK
The workbench will show:
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 8 of 63
•
Click the x on the Welcome tab to remove the Welcome page.
Selecting the web perspective
In the workbench
• Click the Open perspective button on the top right of the workbench
• Select Other… from the context menu
From the Open Perspective list
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 9 of 63
•
•
Select Web
Click the OK button
Create a new EGL Dynamic Web Project.
The project in this example is called eglcallweb
In the workbench
• Click the New button
• Select the Project… action
From the New Project list
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 10 of 63
•
•
•
Expand the EGL node
Select EGL project
Click the Next> button
On the New EGL project wizard page
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 11 of 63
•
•
•
Enter the project name eglcallweb
Select Web Project
Click the Next button
On the New EGL project page:
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 12 of 63
•
•
•
Make sure WebSphere Application Server V6.1 or 7.0 is selected as target runtime
Select radio button Create a new build descriptor
Click the Finish button
Creating the linkage options for the program call
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 13 of 63
•
•
Expand the project eglcallweb
Expand EGLSource.
Locate the EGL Build descriptor file. The name of this file by default is the project name with
the extension .eglbld.
In this example it is eglcallweb.eglbld.
• Double click the build descriptor file to open it.
The default build descriptor editor opens.
The linkage options are part of the build descriptor file but are handled by a different wizard.
The linkage options describe where remote objects (in our case the program on IBM i) reside
and what interfaces should be used to access them.
Now you will create the linkage option for the program call
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 14 of 63
Locate the Outline view in your workspace. It should be on the upper right side of the Project
Navigator.
If it does not show up,
• Click the Outline tab to select it.
•
•
Right click on the eglcallweb.eglbld node in the tree to display the context menu
Select a Add Part.
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 15 of 63
•
•
Select Linkage Options from this dialog
Click Next >.
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 16 of 63
On the dialog page displayed in the figure above
• Type the name of the linkage option. callsysipgms
Once this one time set up for your project is done you can now use this to create linkages to any
program on IBM i or other systems.
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 17 of 63
When the dialog opens
• Click on the Add button
•
.
Click inside the Program Name field and type the name of the program you wish to call
on IBM i. In this case it is GETDATAE
Note: You may add as many programs as you need to this list. EGL programs in the project may
call any number of programs on your IBM i system or other machines.
•
•
•
Then click in the field labeled Type.
Click the downward pointing arrow
Select remoteCall from the list of choices.
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 18 of 63
• Click anywhere in the dialog and press Enter to make sure the change applies.
You will see the program name GETDATAE and remoteCall appear in the right hand list of
linkage options
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 19 of 63
Specify linkage values
Click in the following fields and provide the following properties exactly as listed below:
Property
pgmName
type
conversionTable
Value
GETDATAE
remoteCall
CSOE037
library
EGLLABv7xx
location
iseriesd.demos.ibm.com
remoteBind
GENERATION
Comment
should appear – as default
should appear – as default
CS letter O (Oh) E zero 37
See note below.
Name of the i5/OS library
where the program resides
on the IBM i system, or
nothing for libl.
This is the TCP/IP name of
your machine or the IP
address.You can use the
IBM demo server:
iseriesd.demos.ibm.com
Select from drop down list.
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 20 of 63
remoteComType
remotePgmType
JAVA400
STATELESS
Select from drop down list
Select from drop down list
Note: EGL handles conversions from ASCII or UNICODE to EBIDIC in the IBM i OS.. The
converstionTable property specifies the code page and language to use for
conversions. The first four characters of the conversion table are always “CSOE”
(letter oh, not zero). The last three digits are the three digit code for your national
language. The code 037 is US English.
After completing the entry for these properties,
• Save the Linkage options. Press CTRL + S to save the entries.
•
Select the tab eglcallwebWebBuildOptions to bring the Build Options editor window
back into focus
Adding linkage to build file
In the Build options editor window
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 21 of 63
•
•
•
Deselect the Show only specified options check box to show all options available for the
Build Options file..
Find the linkage option
Click on the (no Value set) entry field
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 22 of 63
• Click on the little arrow at the end of the field
It will provide you with a list of all linkages available
• Select callsysipgms
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 23 of 63
•
•
•
Select the check box Show only specified options to reduce the number of options
shown in the list
Save by using CRTL+-S
Click the X in the editor tab, to close the editor
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 24 of 63
Create the Program interface information using the EGL Services wizard
In order to re-use the interface description of our RPG program we can use an EGL wizard that
is provided to create an EGL service interface for accessing IBM i programs.
We don’t want to create a Service in this lab but can still use the wizard to easily extract the
required information from the program source and make our life easier. The wizard extracts
descriptions of fields, records, or externally defined structures. We can use the RSE capabilities
to point to RPG program source to get its call interface description and create EGL data
description from it.
You will use the Remote System Explorer (RSE) and its EGL service wizard.
You need to switch to the RSE perspective:
•
•
•
Click the Open perspective button
If the Remote System Explorer shows in the drop down list
o Select Remote System Explorer from the list
Otherwise
o Select other… from the list
o From the Open perspective dialog
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 25 of 63
o Select Remote System Explorer
o Click the OK button
You are now in the Remote System Explorer (RSE) perspective. You need to create a
connection to the IBM i system that contains the Source member for the GETDATAE program
you want to call to get its interface description. In your home environment you most likely
already have an existing connection that can use.
Let’s create the connection. In the Remote System View
•
Click the Define a connection to remote system button
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 26 of 63
In the New connection Dialog:
• Select the IBM i node
• Click the Next> button
On the next page:
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 27 of 63
• Enter iseriesd.demos.ibm.com as the hostname.
The connection name automatically changes to the value of the hostname, don’t change it
unless you get an error message that this connection name already exists.
If you get an error message change the connection name to a name that doesn’t exist.
• Click the Finish button
In the RSE view the new connection will show
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 28 of 63
• Expand the connection by clicking the + plus sign
• Expand the Objects subsystem by clicking the + plus sign
• Expand Library list by clicking the + plus sign
In the Enter password dialog:
• Enter userid egl4rpg
• Enter password egl4you
• Check Save user ID
• Check Save password
• Click the OK button
A job gets created on the IBM i system and you will see the library list for this job.
You will see library EGLLABV7xx inside the library list, this library contains the program
you will call as well as the source for this program.
In the library list:
• Expand the library EGLLABV7xx
• Expand the source file QRPGLESRC
You will use the EGL Services wizard to extract the RPG interface information. You can
use this information for the EGL call to the program, you will not actually use the service
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 29 of 63
interface. You just use the wizard for the convenience of creating the parameters and record
definitions in EGL.
• Right click on member GETDATAE
• Select action EGL Services Æ Create: ExternalType, Interface, and records
In the New EGL Part dialog:
• Select the Create Rest web services checkbox
• Uncheck any of the other check boxes
• Click the Next> button
On the next wizard page:
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 30 of 63
• Click the Browse button for the source folder entry field
To tell the wizard where to store the EGL call interface information you need to select a web
project and a folder inside the project. In the Folder selection dialog :
• Expand your eglcallweb project
• Select the EGLSource folder
• Click the OK button.
Back on the wizard page specify a package name inside the EGLSource:
• In the Package entry field specify: getdataeCall as the name for the package.
If you had a procedure in a Service Program you could specify this information in this
dialog as well. Since you are dealing with a program call no other entry is needed.
• Click the Next> button
The Add protocol dialog comes up:
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 31 of 63
No changes are needed since you will not use the generated service runtime, you are only
interested in the interface.
• Click the Finish button.
On the next wizard page accept the defaults.
• Click on the Next > button
Same for the last page, accept the defaults.
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 32 of 63
•
Click the Finish button
You are done with this wizard and can return to the Web perspective to complete the EGL
coding.
•
•
•
On the upper right corner of the workbench look for the Web perspective button
If it is not showing click on the >> button
Click the Web perspective button
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 33 of 63
Creating a web page to provide a user interface for the application
Now it is time to create the web UI. It provides the input and output fields for the data that is
sent to the RPG program and received from the program.
It also provides a button to invoke the EGL function that calls the GETDATAE RPG program.
•
•
Right click on the WebContent directory.
Select New Æ Web page in the context menu.
In the New Web Page Dialog:
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 34 of 63
•
Type a name for your JSP file. In this example we named the page
CALLEGL001R.jsp.
• Click Finish.
The Page designer will open
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 35 of 63
• Make sure the Design view is active (tab at the bottom of the designer)
• Type Customer Inquiry on the white space in the page designer,
• Click the text that you just wrote, so it has focus
• Click on the Properties tab at the bottom of the screen,
• Adjust the appearance to Heading 2
• Save with CRTL+S.
Now you write some EGL code in the page handler file
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 36 of 63
•
•
Right click anywhere on the white space in the web page
Select Edit Page Code from the context menu that appears.
Create EGL Code to call the RPG Program
The source editor opens with the EGL Pagehandler file for this page. The pagehandler is a type
of EGL program that controls interaction with a Java Server Faces web page. Each JSF web
page is linked to its own pagehandler file.
All code that deals with this page for displaying or retrieving data and setting page attributes
needs to be added to this source file.
You will now write the code in here to call the RPG program and receive the data from the RPG
program to display it on this page.
Next you check the RPG program interface definition that is stored in the getdataeCall package
in the GETDATAE.egl file.
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 37 of 63
In the Web perspective, in the Project explorer view
• Expand the eglcallweb project
• Expand EGLSource
• Expand the getdataeCall package
• Double click on the GETDATAE.egl file to open it in the source editor
Remember, this is the file that got created with the EGL Service wizard from your RPG
program, the variable names and data structure names are carried over from the RPG source..
The EGL function GETDATAE has 3 parameters defined
CUSTNOI a char(7) variable
CSTRUC a record that is defined in this source file
FEEDBACK a char(20) variable
To use these three parameters, you must define them. You define these variables and re-use the
CSTRUC record immediately following the:
viewRoot UIViewRoot:
record declaration.
Note: The UIViewRoot is an EGL special record variable that provides access to the various
parts on the web page. It is in the CALLEGL001R.egl tab
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 38 of 63
The figure above illustrates what your code should look like after you have declared the three
variables.
You are using the following variables
• cinput for the customer number that gets passed to the RPG program
• Feedback to get feedback about success of fetching the record, a char(20)
variable.
• cds is a structure of type CSTRUC, (the basicrecord that got created previously
by the EGL services wizard).
Tip: Make use of content assist (CTRL+ Spacebar) to find the correct datatypes, as shown in
the above figure
This figure shows your variables
Now you need to create a simple EGL function with a couple of statements to call your RPG
program.
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 39 of 63
• Write the function callRPG as shown in the figure above
Here is a bit more information on the code you see in the pagehandler program:
The above figure illustrates the completed pagehandler code required to call the RPG Program
GETDATAE. As you can see the code is very intuitive and simple.
In this program as in all EGL JavaServer Faces web programs, there are two functions
automatically added when a new JSFhandler program gets created.
1. onConstruction()
2. and onPrerender().
These functions are invoked when the page is loaded. You will not use these functions in your
program, since you have no upfront processing to do when loading your webpage. So you leave
these functions empty.
In the UI after a user enters data into the input field cinput, you will add a pushbutton that
allows to invoke your callRPG() function.
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 40 of 63
In callRPG you added two statements that write to Stdout to show in the WAS console that the
call is initiated and that it has been finished, these statement are just there for informational
purposes and can be removed in real code.
Note: In function callRPG you use the syslib.RemoteUser(“userid”, “password”) EGL builtin function to set the user-id and password for the logged in user with constants.
Normally you would write a routine that stores user information in a session variable or
other persistent area of storage, instead of using constants in your code. This routine is
simplified for illustration purposes. Please use the userid and password that fits your sever
(For the IBM demo system use userid: EGL4RPG password: EGL4YOU
Note that the Java Toolbox used to access your IBM i system requires that you authenticate
prior to every call to IBM i OS ensuring security and integrity of the system.
Finally we have a simple call statement:
call “GETDATAE” (cinput, cds, feedback);
In this statement you specify the program name that you had previously defined in the EGL
Build File’s Linkage options and the parameters to pass.
You can now create the web form to capture input from the user, call the RPG program, and
display the result.
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 41 of 63
Create fields and button on the Web Page
Click the Page Data view tab in the lower left corner of the workbench to bring it into focus
• Expand JSFHandler
• Expand Data
• Expand Actions
Under the Data node, you see the three variables that you created in the pagehandler.
Under the Actions node you see the callRPG() function you created.
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 42 of 63
•
•
Select the cinput variable
Drag and drop it on to the web design area below the page title.
A dialog appears indicating that you are about to create a new control on the page.
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 43 of 63
•
•
•
Be sure that the “Updating an existing record” radio button is selected. This will
default the control type to Input field.
Click the label area and change the label to Enter customer number:
Click the Options button.
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 44 of 63
• Unselect both Submit and Delete buttons, you will create a call button in the next step
• Click Ok,
• Click Finish on the main dialog.
Now you will add the button to invoke the callRPG function.
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 45 of 63
•
Make some space underneath the input field by positioning the cursor before the error
message control and click the Enter key a couple of time
To create a button that when clicked on, invokes your callRPG function, in the data view:
• Select the callRPG function in page data view
• Drag it underneath the input field in the page designer
Now a push button gets created on the web page. This button is bound to the function in the
page handler.
One last step and you are ready to run your application.
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 46 of 63
•
Drag and drop the variable cds from the Page Data view on to the web page underneath
the pushbutton.
The Configure Data Controls dialog appears.
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 47 of 63
• Check the Displaying an existing record(read only) radio button
This changes the control type for all fields to output
• Click Finish
You might notice, that there is an additional message control added, you don’t need this control,
one message area is enough on the page.
• Delete the Message control that got added underneath the customer information table,
by selecting the message control in page designer and .clicking the DEL key.
The figure below shows the completed web page
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 48 of 63
•
•
Save your page,
Right click on the page white space and select Run on server from the context menu
If a dialog comes up to select an application server,
• select WAS6.1
• Check the check box Set server as project default or Always use this server
when running this project
• Click Finish
You should see your webpage in the default browser:
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 49 of 63
•
•
Now enter a valid customer number for example 0010100
Click callRPG
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 50 of 63
• The data should appear on the page.
This looks good, if there is time left, let’s add some error handling.
If data does not show up, there might be an error in your application. The first step would be to
look at the console.
•
Double click the Console tab to maximize it in the content area
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 51 of 63
In the example above there is an error message recorded.
•
In the console scroll to the right to see details of the error, here the wrong library was
specified in the build descriptor.
• Fix the problem
• Re-generate the project by right clicking on the project and selecting the Generate
action from the context menu.
• You might have to re-start the server to pick up all changes
• Try running it on the server again
One more enhancement to your code and then you can try debugging.
Handling record not found
The feedback parameter tells you whether the record access for the customer number has been
successful. If the customer exists in the database it returns a 0 otherwise the customer number
will be returned.
Go back to the pagehandler code:
• Right mouse click on the white space in the page designer
• Select Edit Page Code from the context menu
Add the if statement as shown above:
1. You compare variable feedback to zero
2. If it is not zero
3. Use built-in function seterror to write an error message, you concatenate the wrong
customer number in the error message.
4. You set the data structure cds to blank, so older output gets erased from the page.
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 52 of 63
The error message will get displayed in the message control that has been added by default to
the page when you added the customer number input field.
• Save the changes
• Run the application again
Debugging the RPG program
If there are problems with calling the program on i5/OS you can use the build in workbench
integrated debugger to debug the RPG program when it gets invoked from EGL.
Note: If you are in a Lab environment, ask the instructor if the IBM i system is setup for
multiple students doing this exercise. Students need their own userids to successfully work thru
this exercise.
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 53 of 63
If you are in your own environment just make sure your userid has enough authority to debug
programs on IBM i.
To debug the RPG program GETDATAE:
• Switch to the Remote System Explorer perspective
•
•
•
•
•
Expand the connection to the i5/OS server or create a new connection.
Create a filter for library EGLLABBV7xx, xx being your team number
Expand library EGLLABV7xx
Locate program GETDATAE
Right click on it and from the context menu select Debug(Service Entry) Æ Set
Service Entry point
You will see a message telling you, the Service Entry Point is set
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 54 of 63
• Click Ok
In the RSE perspective a new view gets added
This view shows all service entry points on the system and it also allows working with these
Service Entry points.
• Go back to the web perspective
Now run the CALLEGL001R.jsp again.
• Enter a customer number
• Enter a valid customer number 0010200
• Click the callRPG button
The debug perspective will pop up with the RPG source loaded
•
•
Set a breakpoint where you think it is needed (in the figure we set it after the chain
statement). To set a breakpoint, double click in the grey strip beside the line numbers.
Click the debugger run button
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 55 of 63
If the CHAIN was successful the data will show in the variable monitor
• Click run button again to end the program
You could also debug the EGL source
Set a break point in the CALLEGL001.egl source. Open the source in the editor, the editor is
integrated with the debugger and allows setting breakpoints.
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 56 of 63
•
Just edit it and set a breakpoint
Then start it like you normally do but instead of selecting Run on Server,
• Select Debug on server
• Key in a customer number
• Click the CallRPG button
The workbench switches to the debug perspective.
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 57 of 63
The perspective looks familiar, but now it shows the EGL source
If the Service entry point is still active if you specify run in the EGL debug session ,the debug
perspective will show the RPG debug views.
We hope you enjoyed the Lab
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 58 of 63
Visit the EGL Café to get more information, join the community.
The IBM Rational EGL Café
ibm.com/rational/cafe/community/egl
Additional comments
In the tutorial we try to setup the environment to make it easy to get thru the exercises. For non
tutorial environment we suggest some changes to the approach how you use the EGL Services
wizard. Since the wizard is targeting creating a service and not a simple call it actually creates
the Services environment in the EGL project. The service is actually overhead in your project
and not needed for a single call.
Instead we suggest creating a dummy EGL project to contain all the services infra structure.
This project you use as the target for the EGL services wizard. Then you copy the interface
definitions from this dummy project into your real EGL call project. With this approach non of
the services environment gets created for your EGL application runtime and you still get the
EGL interfaces created for your RPG programs.
Using this approach, you will have to copy the jt400.jar file from the dummy EGL project into
the real EGL call project. The EGL services wizard does this automatically for you under the
covers.
The jt400.jar contains the IBM i toolbox runtime classes to access native IBM objects it actually
implements the remote call of the RPG program.
To copy the jt400.jar do the following
The jt400.jar is located under WebContentÆWEB-INFÆLib-
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 59 of 63
Just copy and paste the jar file from the dummy project into the same location in your real call
project.
Summary:
You learned to navigate through the EGL and the IBM i runtime environments, how to
configure your EGL Web Project to access the IBM® i server, and how to call a program. You
learned how to write the actual code to call an IBM i program, and how to debug both RPG and
EGL code.
Visit the EGL Café to get more information, join the community.
The IBM Rational EGL Café
ibm.com/rational/cafe/community/egl
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 60 of 63
Resources
Learn
• Visit the EGL Café at: http://www-949.ibm.com/software/rational/cafe/community/egl
• Visit the Rational Developer for System i resource page on developerWorks for
technical information and best practices.
• Subscribe to the IBM developerWorks newsletter, a weekly update on the best
of developerWorks tutorials, articles, downloads, community activities, webcasts
and events.
• Subscribe to the Rational Edge e-zine for articles on the concepts behind
effective software development.
• Browse the technology bookstore for books on these and other technical topics.
• IBM Enterprise Modernization Solutions
• Read other tutorials related to the Enterprise Modernization Sandbox for
System i.
• Get a Rational Developer for i for SOA Construction product overview.
• See some demos here.
Get products and technologies
• Download trial versions of IBM Rational software.
About the authors
Claus Weiss
Claus Weiss is an advisory software consultant with the Rational Software System i –
Ecosystem team at the IBM Canada Toronto Laboratory. He has degrees in industrial
engineering and computer science from the University of Hamburg in Germany. He
worked as a systems engineer with IBM Germany and joined the IBM Toronto
Laboratory in 1984. He was a developer and team leader for System/38 development
tools. He has been a member of the Design Control Group for the AS/400
development tools. He has worked as a consultant for IBM iSeries Application
Development for the past 10 years, specializing in Visual Tools. Claus is a frequent
speaker at COMMON and other iSeries conferences and a six-time winner of
COMMON's Speaker Excellence award. He is also the lead author of the book title
"Understanding the IBM WebFacing Tool," published by IBM Press, and has
co-authored several IBM Redbooks.
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 61 of 63
Notices
© Copyright IBM Corporation 1992, 2009. 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
intellectualproperty 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 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 10504-1785 U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBMIntellectual 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
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 62 of 63
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 IMPLIEDWARRANTIES OR CONDITIONS
OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some
statesdo not allow disclaimer of express or implied warranties in certain transactions, therefore, 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 beincorporated in new editions of the publication. IBM may make
improvementsand/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 enabling: (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 WebSphere 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 environment. Therefore, the results
obtained in other operating environments mayvary significantly. Some measurements may have been made on
development-levelsystems 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.
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.
Calling IBM i programs from EGL, Page 63 of 63
All statements regarding IBM’s future direction or intent are subject to change orwithdrawal without notice, and
represent goals and objectives only.
Copyright license
This information contains sample application programs in source language, whichillustrates programming 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, marketing or distributing applicationprograms
conforming to the application programming interface for the operatingplatform for which the sample programs
are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot
guarantee or imply reliability, serviceability, or function of these programs.
Each copy or any portion of these sample programs or any derivative work, mustinclude 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
•
iSeries
•
Rational
•
RPG/400
•
System i
Intel® and Pentium® are trademarks of Intel Corporation in the United States, othercountries, or both.
Microsoft, Windows, Windows NT® and the Windows logo are trademarks ofMicrosoft Corporation in the
United States, other countries, or both.
Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in theUnited States, other countries,
or both.
UNIX is a registered trademark of The Open Group in the United States and othercountries.
Linux is a registered trademark of Linus Torvalds in the United States, othercountries, or both.
Other company, product or service names may be trademarks or service marks of others.
Copyright © 2009, IBM® Corporation. All rights reserved. Published by IBM® developerWorks®.