Setup and Calling i5/OS Programs (RPG, CL, COBOL)

WebSphere Development Studio Client (WDSc)
for i5
And EGL
Setup and
Calling i5/OS Programs
(RPG, CL, COBOL)
from
Bob Cancilla
IBM EGL Eco System Team
March 2006
Table of Contents
Introduction ......................................................................................................................... 1
Installing EGL Runtime Resources .................................................................................... 2
Install EGL Runtime ....................................................................................................... 2
Install Samples for this White Paper ............................................................................... 4
EGL and the i5 – Calling i5 Programs ................................................................................ 6
Calling an i5 Program from EGL........................................................................................ 8
i5 RPG Program .............................................................................................................. 8
EGL Dynamic Web Project ............................................................................................ 8
Copy JT400.JAR to your Project .................................................................................... 8
Customize the EGL Build File ...................................................................................... 10
Create an EGL JSF Web Page ...................................................................................... 17
Create EGL Code to call the RPG Program.................................................................. 18
Create EGL Web Page .................................................................................................. 22
Trouble Shooting .............................................................................................................. 28
Verify connection to your i5 ......................................................................................... 28
Trace Your Web Application ........................................................................................ 28
Determining what went wrong on the i5....................................................................... 30
User Customizable CL Programs...................................................................................... 33
Commitment Control – QVGNRNCL .......................................................................... 35
Libraries and library list control – QVGNSETP........................................................... 36
i
Introduction
This paper describes the process of configuring the WDSc and your i5/OS (or OS/400)
based machine to enable Enterprise Generation Language (EGL) to call programs (RPG,
COBOL, CL, CL Commands, or programs written in any supported language) on the
your i5 or iSeries machine.
Calling an existing i5/OS program from EGL is incredibly simple, but requires a bit of
setup and testing. In this paper we will work you through the process of installing the
EGL server side library QEGL on your iSeries that contains the IBM provided programs
to evoke a job on the System i and call your program.
EGL leverages the i5 Toolbox for Java™ which in turn utilizes the i5’s Remote
Command Host Server (QZRCSRVSD in the QSYSWRK subsystem).
Some simple setup and testing is required to insure that you can access and utilize these
facilities.
In this paper we will discuss:





Installing support for the EGL Runtime
EGL and the i5 runtime environment.
Configuring your EGL Web Project to access the iSeries and call a program
The actual code to call an i5 program
Debugging and Resolving problems
1
Installing EGL Runtime Resources
To call i5 programs on your i5 machines under i5/OS (or OS/400) you will need at least
one license for the WDSc Advanced Edition software. The WDSc grants you an
unlimited use license for the i5 EGL runtime support.
EGL requires that some runtime resources be installed on your iSeries machine. You will
need the QEGL.ZIP, QEGL.SAVF files, and the document “EGL Server Guide for
iSeries Version 6, Release 0.
The “EGL Server Guide for iSeries” may be found on the web at:
http://www.elink.ibmlink.ibm.com/public/applications/publications/cgibin/pbi.cgi?CTY=
US&FNC=SRX&PBL=SC31-6841-01#
Install EGL Runtime
Here are the instructions (also found in the document “EGL Server Guide for iSeries”).
1. Locate the file QEGL.ZIP and QEGL.SAVF on the workstation with WDSc
Advanced Edition and EGL installed.
2. Go to the directory where you installed the WDSc Advanced Edition.
The file should be located in:
<%INSTALL
DIRECTORY%>\radi_prod\eclipse\plugins\com.ibm.etools.egl.generators.cobol.i
seriesruntime_6.0.0.1\executables\.
Note: If you take the default installation options for the WDSc the install
directory would normally be: X:\Program Files\IBM\Rational\SDP\6.0 (where
“X” is the drive letter of the drive where you installed the product).
2
Figure 1: Windows Explorer location of iSeries installation files
3. Log on to your i5 machine and create a save file in a library of your choosing:
CRTSAVF MYLIB/QEGL
4. FTP the file QEGL.SAVF from your PC to the i5 using the “Replace” option.
5. Once the file has been successfully transferred to the i5 then restore the QEGL
library using the command:
RSTLIB SAVLIB(QEGL) DEV(*SAVF) SAVF(MYLIB/QEGL)
Note: be sure to replace MYLIB with the name of the library you placed the
SAVF in.
6. You should now have a library on your system named QEGL. Use the
WRKLIB QEGL to verify that the library exists.
3
7. Do a CHGOBJOWN on the library and all of its objects to insure that it complies
with your security policy. It is critical that you define *PUBLIC *USE as access
rights for the library and all of its objects.
8. Use WRKOBJPDM to locate the EGL Provided CL Program named
QVGNRNCL.
9. Copy this program to each library on the system that contains programs you wish
to call from EGL.
Note: The CL source for this program is provided in the QEGL library source
file named QVGNSAMP. See the “EGL Server Guide for iSeries” for
instructions on customizing this program and the next section for a description.
Install Samples for this White Paper
When you downloaded this document, you should also have downloaded a ZIP file
containing an i5/OS SAVF named QEGLSAM. It contains the library QEGLSAM which
in turn contains the objects:
QEGLSAMP -- library
QEGLRPGSRC
EGL001R – a simple RPG Program member
QEGLCLPSRC
EGL001C – a simple CL Program that calls EGL001R
EGLTSTDTA – a test data area
EGL001R – compiled RPG Program
EGL001C – compiled CL Program
The zip file will also contains a Project Interchange files:
EGLCALLSAM.ZIP – project interchange format file which contains:
EGLCALLWEB – an EGL Web Project
EGLCALLWEBEAR – Enterprise application project
To install follow these steps:
1. Log on to your i5 machine and create a SAVF to receive the library.
CRTSAVF MYLIB/QEGLSAMP
2. FTP QEGLSAMP.SAVF to “MYLIB” on your i5 machine replacing the SAVF
QEGLSAMP.
4
3. Restore the QEGLSAMP library using the command:
RSTLIB SAVLIB(QEGLSAMP) DEV(*SAVF) SAVF(MYLIB/QEGLSAMP)
4. As described above change the object owner to conform to your standards and be
sure that the objects contained in QEGLSAMP have at least *PUBLIC *USE
object access rights.
You may import the following files or follow the step by step instructions in the next
section to work through creating a project and
In the WDSc import the project provided in Project Interchange format file:
EGLCALLSAM.ZIP
Do a File, Import, and Select Project Interchange from the list. Use the browse button to
locate the ZIP file EGLCALLSAM.zip. Select all of the projects in the zip file (click the
Select All button), then click finish.
5
EGL and the i5 – Calling i5 Programs
Calling a RPG, COBOL, CL, or other program on the i5 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. EGL takes into account
the many possible library list, commitment control, and other runtime options that may
affect how you run your jobs.
EGL uses the System i Toolbox for Java™ to call programs on the i5. The toolbox in
turn uses the i5 Remote Command server that is a part of the i5 Host Servers.
The Remote Command server in i5/OS consist 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.
Figure 2: EGL Call to i5 Program flow
6
Figure 2 illustrates the typical flow of a call from an EGL program to an i5/OS
application program.
In this scenario an EGL developer may be working on WDSc on their workstation and
running an EGL application under the WebSphere Test Environment.
The workstation will utilize the Java Toolbox to establish a connection with the Remote
Command server on the i5 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.
The program QVGNSVR will be invoked. This program in turn will call the
QVGNRNCL CL program that starts commitment control in the job (if required) and
then call the QVGNSETP CL program to add any required libraries to the job’s library
list.
Finally the user program will be called.
Return parameters will be returned up the path back to the invoking EGL program.
7
Calling an i5 Program from EGL
In this section we will walk through the steps involved in creating an EGL Dynamic Web
Project and create a simple JSF based Web Page that calls an RPG program on an iSeries.
i5 RPG Program
The program we are going to call is named EGL001R. It is an RPG program with two
numeric input parameters that will add the two pararmeters and return a result.
Here is the RPG Source:
Figure 3: EGL001R RPG Program
As you can see this program when called is passed three variables “p1, p2, and p3”. It
adds p1 to p2 and stores the result in p3.
This program had been compiled into the library RCANCILL on the i5 in our example.
Be sure you substitute the name of the library you use.
EGL Dynamic Web Project
Create a new EGL Dynamic Web Project. The project in this example is called
“EGLCALLWEB”.
Copy JT400.JAR to your Project
EGL uses the i5 Java Toolbox classes to communicate with an i5/OS based machine.
You must locate the j400.jar file located in the <% Install directory %>
\rwdi_shared\eclipse\plugins\com.ibm.etools.iseries.toolbox_6.0.1\runtime directory and
copy it into the Webcontent\\Web-Inf\lib directory.
Note: if multiple versions of the directory exist look for the one with the highest version
number.
8
Figure 4: Search for j400.jar
Copy the jt400.jar file to the Web-Inf\lib\ directory in your project as shown below.
9
Figure 5: WDSc EGL Project after copy
Figure 5 illustrates the jt400.jar file after the copy.
Customize the EGL Build File
The EGL build file contains the information necessary for EGL to communicate with
your target environment. The Build File must be configured once for each project to
define options that will control the generation of the executable program code.
Expand “Dynamic Web Projects”. Expand the
project “EGLCALLWEB”. Expand
“EGLSource”.
Locate the EGL Build file. This will be the project
name with the extension .eglbld. In this example it
is EGLCALLWEB.eglbld.
10
Double click the build file to open it.
Figure 6: EGL Build File
Figure 6 illustrates the EGL Build file after it is customized. When you first open the
build file you will see all possible options. Locate the following options and be sure they
are set exactly as illustrated.
Option
dbms
genDataTables
genProject
genProperties
j2ee
linkage
sqlJNDIName
system
Value
DB2
YES
EGLCALLWEB
GLOBAL
YES
CallI5
WIN
The yellow highlighted text for the “linkage” option contains the value “CallI5” this can
be any name you wish to code. We will use this name in the next step.
11
Figure 7: Build file options
Locate the Outline view in your workspace. It should be below the Project Navigator. If
it does not show up, click the >>3 and select it. Then click on EGLCALLWEB.eglbld to
select it.
12
Figure 8: Add Build File Part
Right click on the EGLCALLWEB.eglbld to display the context menu and select add
part.
Figure 9: Add EGL Build Part
Select “Linkage Options” from this dialog and click Next.
13
Figure 10: Name the Linkage options
On the dialog page displayed in Figure 10 above type the name of the linkage option that
you originally type in the “linkage” option in the build descriptor.
Once this one time set up for your project is done you can now create your EGL Web
Program that will call the RPG Program.
14
Figure 11: EGL Linkage options
When the dialog opens click on the “Add” button by the red numeral 1 in Figure 11
above.
Click inside the “Program Name” field and type the i5/OS name of the program you wish
to call. In this case it is EGL001R.
Note: You may add as many programs as you may need to this list. EGL programs in
the project may call any number of programs on your iSeries or other machines.
Then click in the field labeled “Type” (the red numeral 2). Click the downward pointing
arrow and select “remoteCall” (see the red numeral 3) from the list of choices. Click any
where in the dialog and press Enter to make sure the change applies. You will see the
program name EGL001R and “remoteCall” appear in the right hand list of linkage
options (red numeral 4).
Click in the following fields and provide the following properties exactly as listed below:
Property
pgmName
Value
EGL001R
type
remoteCall
conversionTable
CSOE037
kibrary
RCANCILL
Comment
should appear – you cannot
modify
should appear – you cannot
modify
CS letter O (Oh) E zero 37
See note 1 below.
Name of the i5/OS library
15
location
remoteBind
remoteComType
remotePgmType
where the program resides
on the i5.
elcrtp67.rtp.raleigh.ibm.com This is the TCP/IP name of
your machine or the IP
address. See note 2 below.
GENERATION
Select from drop down list.
JAVA400
Select from drop down list
EXTERNALLYDEFINED Select from drop down list
Note 1: EGL handles conversions from ASCII or UNICODE to EBIDIC for the i5
machine. 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.
Figure 12: Completed Linkage options
After completing the entry for these properties, save the Linkage options. Press CTRL +
S to save the entries. You may close the Linkage Option view at this time.
16
Create an EGL JSF Web Page
You may now create the program that will call the EGL001R RPG program.
Figure 13: New Faces JSP File
Be sure the Web Perspective is open as indicated by the rend numeral 1 in Figure 13
above. If the Web perspective is not open, select Window, Open Perspective and choose
Web from the menu or click other if Web is not in the list and select Web from the list
that appear.
Right click on WebContent. Select New, then “Faces JSP Page” in the context menu.
In the new Faces JSP Dialog type a name for your JSP file. In this example we named
the page “CALLEGL001R.” Click finish.
Select and delete the “Place content here” text you see on the page. You can select the
text you type then click on the properties tab at the bottom of the screen, click on “text”
and adjust the appearance if you wish.
17
Figure 14: EGL Faces JSP File
Right click anywhere on the web page and select “Edit Page Code” from the context
menu that appears.
Create EGL Code to call the RPG Program
The EGL Pagehandler appears. The pagehandler is a type of EGL program that controls
interaction with a Java ServerFaces web page.
Since our RPG program contains three numeric parameters and i5/OS defaults to
unsigned decimal numeric fields 15 bytes long with 5 decimal places, we must define
some variables to interact with the program.
We will insert these variables immediately following the:
viewRoot UIViewRoot:
record declaration. Note: this is an EGL special record variable that provides access to
the various parts of the web page.
18
Figure 15: Pagehandler with variables added
Figure 15 illustrates what your code should look like after you have declared the three
variables. We are using the PACF primitive data type. PACF is similar to DECIMAL
but uses the letter “F” instead of the letter “C” in the sign bit of a packed decimal field.
“F” indicates that the number is a positive unsigned number while “C” is a positive
signed number. See “packed decimal” data types in the i5/OS reference library. You
may also look up “Decimal” and “PACF” in the EGL help system.
We now need a simple EGL function and statement to call our RPG program.
19
Figure 16: Completed EGL Pagehander
Figure 16 illustrates the completed pagehandler code required to call the RPG Program
EGL001. As you can see the code is very intuitive and simple.
In this program we defined program variables that will contain input from an HTML
form be passed to the RPG program via the “call” statement and a variable to contain the
result returned from the RPG program and displayed on the web page.
In this program as in all EGL JavaServer Faces web programs, there is a Function named
“onPageLoad()”. This function is always invoked when the page is first loaded. In this
case we have nothing to do other than display the HTML form that we are about to
create.
When a user enters data into the two input fields “Parm1” and “Parm2” we need a
function that will call our RPG program and display the result. This function is the
“callRPG()” function.
20
Note that in this function we use the syslib.RemoteUser(“userid”, “password”) EGL
built-in function to set the user-id and password for the logged in user. You would
normally write a routine that stores user information in a session or other persistent area
of storage. This routine is simplified for illustration purposes.
Note that the Java Toolbox used to access your i5 requires that you authenticate prior to
every call to the i5 insuring security and integrity of the system.
Finally we have a simple call statement:
call EGL001R parm1, parm2, result;
In this statement we specify the program name that we had previously defined in the EGL
Build File’s Linkage options. The parameters are IN/OUT type parameters meaning that
we will set parm1 and parm2 to the values we get from the HTML form as input to the
program. The RPG program will return parm1 and parm2 and the third variable “result”
which is the result of the calculation in the RPG program.
We can now create the web form to capture input from the user, call the RPG program,
and display the result.
21
Create EGL Web Page
Figure 17: Create Web Page
Be sure that the “Page Data” view shown in the lower left corner of Figure 17 is visible.
Expand the Item that corresponds to the name of your Pagehandler file (CALLEGL001R)
and expand “Actions”.
Under CALLEGL001R you should see the three variables that we created in the
pagehandler. Under actions you should see the “callRPG() function we created.
Select all three of the variables, then drag and
drop them on to the web design area below the
page title.
Note the prompt indicating that you are about to
create new controls on the page.
22
Figure 18: Configure Data Control
When you drop the three variables on the page you will see the “Configure Data
Controls” dialog illustrated in Figure 18 above. Be sure that the “Updating an existing
record” radio button is selected. This will default the control types to “Input field with
message”. Click the drop down arrow to the right of the “result” field and change it to
“Output field”.
Click the options button.
23
Figure 19: Options
Unclick the “Delete button” as this will not be required in this web page. You may wish
to change the default “Submit button” label as we did to “Calculate” in this example.
Click Ok, and then click Finish on the main dialog.
24
Figure 20: Bind Action to Submit button
One last step and you are ready to run your application. Drag and drop the function
“callRPGG()” from the Page Data view on to the “Calculate” button to bind the clicking
of the button to the function you created to call the RPG EGL001R program.
25
Figure 21: Verifying the properties and binding of the Submit Button
As illustrated in Figure 21 above, click the Submit button (red numeral 1). Click on the
“Properties” tab (red numeral 2). Click the down arrow (red numeral 3) and select “All
Properties”. The mapping to the callRPG() function is displayed in the properties list at
red numeral 4.
You may now save your page, start your WebSphere Application server and run it on the
server.
If you have followed the instructions you should see something like the following:
26
Figure 22: Completed Web Page after call to EGL001R
Here the user entered the digit 1 in the Parm 1 field, the digit 2 in the parm 2 field,
clicked the “Calculate” button and got the number 3 back from the RPG program.
While it has taken many pages to present and explain all of this, the initial set up is a one
time activity. Configuring the build descriptor, creating a “Linkage options”, web page,
and writing the few lines of EGL code should take you on average less than 5 minutes.
As you can see it is much more difficult to explain than to do.
27
Trouble Shooting
In our example, we are working with the integrated WebSphere Application server that
exists in the WDSc, connecting to a remote i5 machine over a network, using an i5/OS
Remote Command Server job and calling a program on your machine.
There are many potential points of failure in what appears to the EGL developer as a
simple process. Understanding what is happening where and when and how to identify
and resolve problems is a key part of enabling EGL to call programs on your i5.
Most problems have to do with either network configuration, insuring that the Remote
Command Server is running, and that your i5/OS objects have proper authorization to be
used by the user running your web application.
Verify connection to your i5
In the linkage options page of the EGL build file we defined the network name (URL) of
the i5 machine that we contained the RPG program we wanted to call.
If you are having a problem with nothing happening at all when you run the web page,
open a command prompt and “Ping” your machine. This will verify that the network
name for your i5 can be resolved from your desktop machine and you can communicate.
Figure 23: ping machineName
Note that in this case the machine responded and its IP address 9.42.133.75 was returned.
Trace Your Web Application
The WDSc and EGL tooling offers you a trace facility that can help determine exactly
what is going on in your web application.
Locate the web.xml file in your WEB-INF directory as
illustrated to the left. Double click to pen the web.xml file or
Web Descriptor in the WDSc provided editor.
28
Locate and click to select the “Source” tab at the bottom of the web.xml editor view.
Figure 24: web.xml trace controls
Locate the vgj.trace.type entry in the web.xml file. Change the value from 0 to -1 (minus
one).
Locate the vgj.trace.device.options and change its value from 2 (none) to 0 (zero).
0 – displays the trace on the WDSc console
1 – writes the trace to a file
2 – suppresses the output
Now run your application on the WebSphere Application Server. Click and select the
“Console” view at the bottom of the page.
29
Figure 25: EGL Trace Output from Console
Figure 25 illustrates the output of a successful execution of the web page. If an error had
occurred, you would see error messages displayed in the trace. Note, you may double
click the “Console” tab to enlarge the small console window to full screen size to make it
easier to read. Double click it again to restore it to its normal size.
At this point if a security exception is displayed, make sure that you have specified a
properly authorized user profile and password.
Determining what went wrong on the i5
The most common errors and issues in calling a program on the i5 are properly setting the
i5/OS library list and object authorities for your program and the objects used by the
program.
You can use iSeries Navigator to analyze what is happening on your i5 machine.
30
Figure 26: iSeries Navigator - Remote Command Server
Since EGL uses the Java Toobox for i5, communications between EGL and your program
is handled by the Remote Command server.
Expand your machine in the left column as show in Figure 26 above. Expand “Servers”.
Click on “iSeries ACCESS”. After a moment you will see a list of iSeries Acess servers
appear in the right hand column.
Verify that the Remote Command server is “Started”.
NOTE: this is the first point of failure! This server must be started!
If the server is started, right click and select
“Server Jobs” from the context menu as
illustrated in the figure to the left.
31
Figure 27: Remote Command Server Jobs
The server daemon (server job) for the Remote Command Server is Qzrcsrvsd. Its
worker jobs that process your requests are named Qzrcsrvs. The jobs are started under
the user profile QUSER and the SWAP ID API is issued to switch to the user profile you
authenticate with.
The JOBD (Job Description) used by this server is: QZRCSRVS
As you can see the prestarted jobs Qzrcsrvs are listed. Note that some are completed and
have spool files available. You may right click on a job and select Job log or several
other options.
Look for ESCAPE and DIAGNOTIC messages in the job log. The most likely issues
pertain to authorities or library list issues.
Note: you should see a job with the user id you are using to access the i5. You may have
to examine the job logs of several jobs in order to find the correct job.
In the job log you should see:
This tells you that user profile of RCANCILL from a machine at IP address 9.48.52.16
connected to the job.
Work with your i5 System administrator to isolate and resolve any issues that may occur.
Also see the subsequent section titled User Customizable CL Programs which provide
some options to resolve Commitment Control and Library List issues.
32
User Customizable CL Programs
EGL provides two CL programs with source code to enable customers to handle
exceptional conditions pertaining to Commitment Control (QVGNRNCL) and the
handling of libraries and library lists (QVGNSETP).
It is important to note that the majority of customers do NOT require any modifications
to these CL programs and EGL will run if the instructions in Install EGL Runtime are
followed.
No two i5 installations are the same however and it is possible that some customization
may be required.
You can find the source for these two program in the QEGL library in the QVGNSAMP
source file:
Figure 28: QVGNSAMP CL Source
33
Figure 29: Remote System Explorer View of QVGNSAMP CL Source File
34
Commitment Control – QVGNRNCL
Figure 30: QVGNRNCL -- Commitment Control CL Program
This program determines from your EGL program and build file if commitment control is
required and issues the STRCMTCTL command if required.
It is rare that this program needs to be modified.
It is however important to note that if modifications are required, the executable (PGM
object) must be copied to each library containing programs to be called by an EGL
program.
35
Libraries and library list control – QVGNSETP
36
Figure 31: QVGNSETP -- handle libraries and library lists
This program will use the system library list and either the QUSRLIBL library list or a
custom user library list based on the JOBD in use. Additionally, this CL program
contains in its comments instructions for creating a data area that contains additional
libraries you may need, or you may add a statement at line 8000 to explicitly add libraries
using the ADDLIBLE CL Command.
NOTE: the source member name for this CL program is VGNSETP be sure you compile
it as QVGNSETP (adding the letter Q) or it will not be recognized. This program need
only exist in the QEGL library.
37