EGL
& the iSeries
An iSeries guide to learning
Enterprise Generation Language
Table of Contents
iSeries EGL ......................................................................................................................... 3
First Steps............................................................................................................................ 3
Enable EGL Tools in the Workbench ............................................................................. 3
Allow EGL to Access your iSeries Database ................................................................. 4
Create a Project for the Course ....................................................................................... 7
Import Database Table Descriptions into Project ........................................................... 9
Create and Test an EGL JSF Web Page........................................................................ 13
Configure the WebSphere Application Server ............................................................. 23
Create a Server .......................................................................................................... 23
Start the WebSphere Administrative Console .......................................................... 25
Configure Global Security ........................................................................................ 26
Configure JDBC Provider ......................................................................................... 29
Configure Data Source .............................................................................................. 31
iSeries EGL
This document provides basic procedures for creating a Dynamic Web project,
configuring and working with an iSeries and EGL.
First Steps
We recommend creating a RAD workspace that contains your iSeries settings. So when
you start RAD create a new workspace name. Complete the following activities before
trying to create a project and work with EGL.
Enable EGL Tools in the Workbench
BEFORE CREATING A PROJECT you must enable EGL in your version of RAD.
This must be accomplished for each workspace you create.
Figure 1: Enabling EGL
First select “Windows (1) from your workbench menu.
Then select “Preferences” from the context menu
The “Preferences” (2) dialog will open.
Expand “Workbench” (click the +) and click on “Capabilities” (3)
Make sure that the check box for “EGL Developer” is checked (4)
Then click the “OK” (5) button to apply your changes.
Allow EGL to Access your iSeries Database
To setup the access to DB2 on the AS400, the following can be set in the preferences for
EGL in the WDSC preferences windows (Window->Preferences->EGL->SQL Database
Connections). This connection uses the JT400 toolkit provided by the AS/400 operating
system (it can be downloaded from the AS/400) and does not require DB2 Connect.
Note: if you have installed a version of the DB2 Universal Database on your local
machine, the jt400 driver is located in x:\Program Files\IBM\SQLLIB\tools\jt400.jar
where “x” is the drive where you installed DB2. Note SQLLIB is the DB2 install
directory.
where Connection URL is
jdbc:as400:hostname


where hostname is the TCP/IP host name for the target AS400 qualified
with its domain. (ping the hostname to see what the domain name is. If it
does not require the domain name, then most likely these preferences will
not need the domain name).
In the example above, “transaction isolation”=”none” turns off journalling
on the AS/400 when updates (add/change/delete) are done to a table.
Database name is the name of the host system
Userid and password are a valid userid and password for the target AS/400
Database Vendor Type for the AS400 toolkit should be selected.
The JDBC Driver and JDBC Driver class will be chosen based on the above Database
Vendor Type.
The JT400.jar file must be located and used for the Class Location.. This jar file can be
obtained from the AS/400.
NOTE:
After the setup in the preferences, the library list for the connection user profile (userid)
must include in its library list the library containing the tables you wish to use. Make
sure that this profile is authorized to access the library (collection) and tables.
Create a Project for the Course
The following steps will guide you through the creation of a Dynamic Web Project used
in this scenario.
Figure 2: Create Project
1.
2.
3.
4.
Select “New” on the workbench menu
Select “project” from the context menu
Locate and expand Web and click on “Dynamic Web Project”
Click Next
5. Provide a project name – we used iSeriesEGLWeb
6. Click Next
7. Make sure the check box for “EGL Support with JSF” is selected.
8. Click Next
9. Check the “Create new project build descriptor(s) automatically radio button is
selected.
10. Provide the JNDI name to connect to your iSeries database. We used:
jdbc\RTAS64. the format is always jdbc\machineName (name of your iSeries
machine).
11. Click Next
12. Make sure that “Use default Page Template for the Web site” is checked and that
the “Sample page template” radio button is selected.
13. Choose the B_blue.htpl example with the two columns as illustrated.
14. Click Finish
The wizard will now create your project. You may be prompted with a message asking
you if it is all right to switch to the “Web Perspective”. Respond “Yes” to this prompt.
We will be working in the “Web Perspective”.
Your workspace should now look similar to the following illustration.
Figure 3: Workbench with new EGL Project
In figure 3 above, expand Dynamic Web Pages in the Project Explorer and note that your
iSeriesEGLWeb project now appears. Spend a few moments and explore the directories
and artifacts created by the wizard for you. We will be working extensively in the “EGL
Source” directory.
Also pay attention to the Perspective indicators (marked with the red 2 in figure 1) and
make sure that Web is selected. If for some reason it is not, then Select Window in the
workbench menu, then “Open perspective”, and “Web” from the list.
Import Database Table Descriptions into Project
In this activity, we will connect to your iSeries and import the table definitions for the
database tables we will use in this project.
Figure 4: Use the EGL Data Parts Wizard
1. Select your project and right click to display the context menu.
2. Select “New” from the context Menu
3. Select other from this menu.
4. Locate and expand the “EGL” folder in the “New” dialog.
5. Select “EGL Data Parts”
6. Click Next
Figure 5: Select your iSeries Data
The “New EGL Data Parts” wizard will guide you through creating the database table
definitions into your project as EGL Records and EGL Data Access Function Libraries.
1. VERY IMPORTANT – be sure you select your project (iSeriesEGLWeb) name!
2. Select the database connection for your iSeries (as illustrated in figure 5).
3. Select each table you wish to import. Use the Control key and click to select
multiple tables. Each selected table will be highlighted.
4. Click the top arrow to add tables to the selected tables list.
5. Verify that you have selected the tables listed. Repeat steps 2, 3, and 4 until the
list is correct. If you accidentally select “EGL Web Sample” you may click on it
in the tables list (5) and click the right arrow button (4) to remove it.
6. Click Next when you have the correct tables selected.
Figure 6: Create EGL data artifacts
We will now walk through the steps necessary to map database tables into EGL for use as
record descriptions and generate the basic data access functions used by EGL.
1. In dialog A, note the red error symbol and message stating “No key in table –
ITEM”.
2. Click on the tab for the Item table.
3.
4.
5.
6.
In the box labeled “Choose the key” select ITEM_ID.
Click the right facing “add” arrow to add the field to the “Key fields” window.
Verify that “ITEM_ID” was added to the window.
Click Next to continue
7. Verify that the project name is “iSeriesEGLWeb”, and that the Data package is
“data” and that the Library package is “libraries”.
8. Click Finish.
Note that the wizard will run for a minute or two. A pop-up dialog will appear notifying
you that the resources have been created. Click “Yes” on this dialog. You may see
several additional dialogs which will all disappear when the tasks are completed.
Figure 7: Generation results
Note that a view will appear (center bottom of your workspace) named “Generation
Results”. There should be one for each database table you had selected. Click the tabs at
the bottom of the window and verify that the generation completed with no errors.
Figure 8: EGL Build Descriptor
Select the iSeriesEGLWeb.eglbld file in the EGLSource directory in the Project Explorer
view in your workbench. Double click to open the build descriptor.
Click the check box for “Show only specified options”. You should see something
similar to what is displayed in figure 8. Note that your machine will be displayed in
place of our iSeries (RTPAS64.RTP.RALEIGH.IBM.COM).
Create and Test an EGL JSF Web Page
Please bear with us and just follow these instructions. We will provide detailed
explanation later in the course. This exercise verifies that everything is properly
configured for use in the detailed tutorial sections of the book.
Figure 9: Create a Faces JSP file
1. Expand the Dynamic Web Projects and your iSeriesEGLWeb project in the
Project Explorer View.
2. Right Click on the WebContent folder.
3. Click New in the context menu.
4. Click Faces JSP File
Figure 10: Create Faces JSP
1. In the File Name field of dialog “A” type the name “testCustomer”.
2. Check the box labeled “Create from page template”
3. Click the Next button.
4. In dialog “B”, click the “Sample page template” radio button.
5. Click the A_blue.htpl template as illustrated.
6. Click the Finish button.
Figure 11: Customize page title
Select the text “Place your page content here” as illustrated above.
Replace the text by typing: “Test iSeries Access to Customer Table” and press Enter two
or three times to insert some blank lines.
Figure 12: Basic JSF Page
Ok, so we couldn’t resist! We selected our text, clicked on Properties at the bottom of
the page. We clicked the “B” (bold) button, the A with a plus (increase text size) one
time, then clicked the box next to the label “Color:“ and selected Navy.
Figure 13: Add EGL Record to Web Page
The palette is much like an artist’s palette and contains drawers full of tools. You select
tools from the palette and drop them on the “canvas” or web design area.
1. Click on the EGL “drawer” with the folder symbol. It will expand and show you
“Record”, “New Field”, and “Service”.
2. Click on “Record” to select it.
3. Move your mouse to where it is positioned in the example (at number 3) and left
click on the page.
Figure 14: Display Record in JSF DataGrid
In this simple example, we will display the contents of the Customer table on the web
page in a simple JSF DataGrid. A datagrid is a form of table that displays data in a row
and column table based structure. We will go into details later as there are many
presentation options you may wish to use to create an attractive high performance web
page.
1. Select Customer from the list (item 1) above.
2. Click the “Array” check box to enable array support.
3. Unclick (remove the check) Add controls to display the EGL elements on the web
page. (we will illustrate this later).
4. Click OK.
Figure 15: Select columns for datagrid
1. Click the “None” button to deselect all fields in the record.
2. Click the check box in front of customer_id, first_name, last_name, phone to
select them.
3. Click the finish button
You will see a pop-up dialog which should rapidly disappear indicating that the wizard is
generating your List Control (JSF datagrid).
Figure 16: JSF Page with DataGrid
Your web page should now look like figure 16.
Now for a little programming!
Figure 17: Open PageHandler EGL Program object
Follow the following instructions to open the EGL PageHandler program.
1. Right click anywhere in the web page
2. Select “Edit Page Code”
Note that the EGL program editor will open with the Pagehandler file for this web page
opened and skeleton code generated.
We will need to modify the skeleton just a bit to get our page working:
Figure 18: Page handler with Content Assist
In figure 18 we added an “import” statement following the existing “import data.*;”
statement.
Add “import” statement:
You will need to type:
import libraries.*;
as illustrated in figure 18 above.
Add database select statement
Let’s use the editor’s content assist facility to help type this. Do the following:
Type the letters “cus” as illustrated in figure 18.
Then press CTRL + Space (press and hold the control key then press the spacebar).
Select CustomerLibrary from the list and double click “CustomerLibrary”. Type a period
“.” after CustomerLibrary. Then press CTRL + Space again.
Figure 19: Add function
Select the function “selectCustomer” from the code assist prompt and double click it to
insert the code into your Pagehandler file.
Your code should now look like this:
Figure 20: Completed Pagehandler program
Note that content assist does a lot of typing for you!
Now you must save your EGL source and generate some Java.
With the source selected (testCustomer.egl tab at the top is blue) press Ctrl+S (save).
Note: you can use “File, Save” from the menu or press the Save icon on the workbench
tool bar (looks like a diskette).
Ooops, we have an error!
Figure 21: Error in Pagehandler
Notice that there is an “X” in a red circle in the left margin of the editor, and that
“sqlStatusData” is underscored in red. The tool is telling us that we did not define a field
or data record to contain the SQL return code returned from our function.
Create a line below customer Customer[];
Type “sqlStatusData st” and press Ctrl + Space to invoke content assist.
Figure 22: Create StatusRecord for SQL Return code
Select and double click “StatusRecord – data (record)”
Type the trailing semi-colon “;” at the end of the inserted text.
Save your file (Ctrl + S) again.
Figure 23: Pagehandler with errors resolved
Your file should now look like the one in figure 23. Note that the asterisk in front of
“testCustomer.eg” in the title tab has disappeared indicating that the file has been saved
and not modified. If you modify the file, the asterisk will appear warning that you will
need to save it again.
You may now right click anywhere within the source page and select “Generate” from
the context menu or just be sure that your source file is selected and press Ctrl + G.
Now click on testCustomer.JSP and save it (Ctrl + S).
Configure the WebSphere Application Server
A full function instance of the WebSphere Application Server is installed on your
machine. It was installed when you installed your Rational tools. This version is
integrated with tooling to allow you to test applications within the tool’s workbench and
to debug your code.
You must configure the server to access the iSeries database.
Create a Server
Select the Servers view at the bottom center of your workspace.
Figure 24: Server View
The tools used for the screen capture in Figure 24 all ready has a server configured. We
will customize it for our example.
Right click anywhere within the white space in the Server’s view window. Click “New”,
then “Server” as illustrated in Figure 24. Note: if you have an existing server we suggest
you create a new one for each workspace that you create.
Figure 25: New Server
Select WebSphere v6.0 Server and click the finish button at the bottom of the New Server
dialog.
Figure 26: Servers view
When this is complete you will see a display similar the one below.
Select the server, right click, and click start. The status of the server will change from
“Stopped” to “Starting” and will then transition to “Started”. This may take as long as a
couple of minutes the first time you start the server. Be patient.
Start the WebSphere Administrative Console
Figure 27: Start the Administrative Console
Right click on your server and select “Run administrative console” from the context
menu.
Figure 28: Log into console
As illustrated above, type a User Id in the User ID: field and click the Log in button. You
may type anything in the User ID field. It is not validated. It is however used in various
logs.
You may wish to double click the Blue “Admin Console” tab to maximize the screen in
the workbench and make the web interface easier to work with. Note: you can double
click any title tab in the workbench to maximize the view to full screen. You double
click the tab a second time to restore it to its original size and location.
Configure Global Security
Figure 29: Admin Console – Security
First we will need to create a JAAS J2C Authentication entry to pass a userid and
password to the iSeries.
1. Click the Security tab’s plus sign to expand its choices in the left menu (item 1).
Then click on Global Security. The body of the page in the right hand side will be
displayed.
2. Scroll down to “JAAS Configuration” click the plus sign to expand the options
under “JAAS Configuration”. Then click on “J2C Authentication data”.
Figure 30: J2C Authentication Data
Click on “New” to create a new entry as illustrated in figure 30.
Figure 31: J2C Authentication data
Create an “Alias” of your choosing. This will appear on the previous screen when we are
done and is used to identify the information you are providing. I used my machine name
and the word User.
Provide the userid that can access iSeries data (your own or other designated profile).
Provide the Password for this user profile
Optionally provide a description of this J2C data set.
Click Apply
Then Click OK
NOTE: We always recommend clicking Apply before clicking OK!
Figure 32: Global Security
Your Global Security web page should be similar to the one depicted above. Note the
messages at the top of the page. When you modify the WebSphere console configuration
you must save it. Click the word “Save” (Blue with underscores) in the gray box at the
top of the screen.
Figure 33: Save changes
Click the “Save” button to save your changes.
Configure JDBC Provider
Figure 34: Review Global Security - Configure JDBC Provider
After you have saved the changes described above, your screen should look similar to
figure 34. If you did not previously have an additional J2C data set, you will only have
the one you just created. We will now proceed to configuring the JDBC Provider for
your iSeries database.
1. Review the settings for the J2C Authentication data.
2. Expand the Resources menu item if it is not all ready expanded. Click on JDBC
Providers.
Figure 35: JDBC Providers
In figure 35 you may have one or more pre-existing JDBC Providers defined. We will
need to add one for the iSeries. Click the New button.
NOTE: There are two parts to enabling the WebSphere Application Server to access a
database. The first part is defining a JDBC provider for the type of database system and
the second part is defining the specific resources you wish to access by creating a “Data
Source”.
Once we define the JDBC Provider for the iSeries you do not need to ever define another
instance of this. You would skip to the “Create Data Source” step below.
Figure 36: Create JDBC Provider
The following steps will create the iSeries DB2 JDBC Provider for you.
1. Select “DB2” from the “Select the database type” drop down list.
2. Select “DB2 UDB for iSeries (ToolBox)” from the “Sect the provider type” drop
down list. NOTE: be certain to select the “ToolBox” choice and NOT “Native”.
3. From “Select the implementation type” drop down list, choose “Connection pool
data source”.
4. Click the Next Button
5. Review the data displayed in the dialog. If everything seems correct click
“Apply” and then “Ok”. Again we recommend clicking Apply before Ok.
6. In this box type the path to your jt400.jar file. In our example we downloaded the
JTOpen files from http://www-03.ibm.com/servers/eserver/iseries/toolbox/ and
unzipped them to D:\rad\jtopen. Our path is therefore: D:\rad\jtopen. Note yours
may vary.
7. Verify that “DB2 UDB for iSeries (ToolBox)” is displayed as indicated (item 6).
8. Click the save link as indicated (item 7). Be sure to click the “Save” button in the
next dialog (not illustrated).
Configure Data Source
A data source is the mapping to the physical machine and database on that machine. You
may create many data sources for each “JDBC Provider”.
Figure 37: Configure Data Source
After you have saved your configuration changes, you will see the dialog illustrated in
figure 37. Click on “DB2 UDB for iSeries (ToolBox)” to create the data source.
Figure 38: Define Data Source
Figure 38 illustrates the steps in defining an iSeries DB2 UDB Data Source.
1. Click on the Data Sources link (item 1)
2. Click the “New” button to add a data source
3. Edit the description to refer to your specific machine (ours is RTPAS64).
4. Select the J2C Authentication Data entry you had previous created back in the
Global Security configurations (item 4).
5. Provide the name of your machine. This probably is the fully qualified network
name of your machine.
6. Click Apply and then Ok
7. Save your configuration
You have now completed configuring the WebSphere Application Server. Click the
login button and close the Admin Server view.
Add WebSphere Variable
One additional step in configuring your WebSphere Application Server is to define the
path where the server can locate the JDBC driver.
Figure 39: Configure WebSphere Variables
1. Locate “Environment” on the menu in the left column of the Admin Console.
Click the plus to expand it and then click on “WebSphere Variables.
2. Scroll the list that appears in the main window to the right until you locate
“OS/400 TOOLBOX JDBC DRIVER PATH. Click on the link.
Figure 40: WebSphere Variables
You will define the path on your computer to the location of the OS/400 JDBC Driver.
1. Type the path in the “Value” field.
2. Click Apply, then Ok and Save your configuration.
Test Your WebSphere JDBC Provider
The last step in the process is testing the JDBC Provider and Data Source that you just
configured!
Figure 41: Testing Your JDBC Provider & Data Source
1.
2.
3.
4.
5.
6.
Expand Resources in the Admin Console menu and click on “JDBC Providers”.
On the left screen that appears click on “DB2 UDB for iSeries (Toolbox).
Click on Data Sources
Click on the checkbox in the select column to select the iSeries JDBC provider.
Click the Test connection button
You should see a message like the one depicted in figure 41 (item 6) indicating
that the test was successful.
Congratulations! You have no configured your local copy of the WebSphere Application
Server to access the database on your iSeries.
Customize the Web.XML File for your Project
Figure 42: Customize the WEB.XML file
A last set up step is to customize your WEB.XML file.
1. Locate and double click your web.xml file in your project. It should be located in
the WEB-INF folder in your WebConent Folder.
2. Be sure that the “jdbc” name is set exactly as it was configured in the WebSphere
Application server with the fully qualified machine’s network name (for example:
jdbc /RTPAS64.RTP.RALEIGH.IBM.COM)
3. Also update the WebSphere Bindings JNDI name.
Save the configuration using Ctrl-S or close and save the web.xml file.
Test Your Application
Figure 43: Test your application
Click on testCustomer.jsp to select it in the Project Explorer. Click “Run” in the context
menu and then click “Run on Server”.
Your application may take a few moments to start but it will start and web page will
appear in your workspace that looks like the following:
Closing Notes
You have now configured the runtime environment for your workspace and project. As
long as you wish to access data from the iSeries machine we configured, you will not
have to perform any additional configuration.
You may now just work on your EGL applications and test them at any point by using the
“Run on Server” option.