Enterprise Generation Language (EGL) for IBM i operating ... · Writing EGL code for the web page...

EGL Introduction IBM Toronto Lab

IBM Rational Business Developer for i for SOA Construction

Enterprise Generation Language (EGL) for IBM i operating system Create a web application using EGL and the Data Access Application Wizard Student Exercises Course code Session Id RDI SOA V7.5 Claus Weiss [email protected] Visit the EGL Cafe at .ibm.com/software/rational/cafe/community/egl IBM Toronto Laboratory

Tuesday, March 17, 2009 © COPYRIGHT IBM Corporation 2008

mailto:[email protected]


Third Edition (January 2009) The information contained in this document has not been submitted to any formal IBM test and is distributed on an "as is" basis without any warranty either express or implied. The use of this information or the implementation of any of these techniques is a customer responsibility and depends on the customer's ability to evaluate and integrate them into the customer's operational environment. While each item may have been reviewed by IBM for accuracy in a specific situation, there is no guarantee that the same or similar results will result elsewhere. Customers attempting to adapt these techniques to their own environments do so at their own risk. Comments concerning this notebook and its usefulness for its intended purpose are welcome. You may send written comments to:

IBM Canada Software Solutions

8200 Warden Ave., Markham, Ontario, L6G 1C7

Attention: Claus Weiss, EGL introduction.

or email to: [email protected]

Copyright International Business Machines Corporation 2008. All rights reserved.

This material may not be reproduced in whole or in part without the prior written permission of IBM.

Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions

set forth in GSA ADP Schedule Contract with IBM Corp.



Overall Lab Guide The objective of the EGL lab for IBM i developers is to have the students work with an EGL application that uses an IBM i operating system DB2 UDB database. The lab is intended to allow hands on experience using the RDI SOA workbench with Rational Business Developer. It shows how easy it is to re-use DB2 UDB data definitions and record definitions in an EGL web application Most of the Web Pages for the application are generated by the EGL Data Access Application wizard. One page is created from scratch by the student to show how the Page Designer tool helps building powerful web pages.

It is assumed that the student is familiar with basic Windows UI operations such as working with the desktop and basic mouse operations such as opening folders and performing drag-and-drop operations. Experience with an Eclipse based workbench like WebSphere Development Studio Client (WDSC), Rational Developer for System i, or Rational Application Developer (RAD) is an asset but is not necessary. The lab will have very detailed instructions on how to proceed. All students can finish the Lab on their own pace.

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.



5 Create an i5/OS EGL web application

Table of Contents EGL for IBM i developers...................................................................................................6

The finished application will contain the following web pages and capabilities ...............................6 Creating the application.......................................................................................................8

First Steps ...........................................................................................................................................8 Starting the RDI SOA workbench..................................................................................................8

Changing workbench preferences ......................................................................................................9 Setup the EGL Tools in the Workbench.........................................................................................9 Changing validation preferences ..................................................................................................10

Create an EGL web project ..............................................................................................................12 Get Database Table Descriptions into the EGL web project............................................................18

Creating a data access connection ................................................................................................20 Selecting the tables(files) to work with ........................................................................................22 Specifying data access details ......................................................................................................22 Setting up the runtime environment .............................................................................................24

Specifying data source for runtime data access................................................................................27 Changing the dateFormat property in the data source..................................................................29

Running the generated Web pages ...................................................................................................33 Skip this step unless the instructor tells you to apply this change and skip to topic Run the web applicaton..............................................................................................................................33 Modifying WAS settings..............................................................................................................33 Run the web application ...............................................................................................................34

Creating a new Login web page .......................................................................................................39 Adding EGL variables und input fields........................................................................................40 Adding context specific message areas to the page......................................................................43 Adjusting properties for the web page..........................................................................................44

Writing EGL code for the web page.................................................................................................47 Adding properties to varables and a record definition .................................................................47 Creating a function to validate the user name ..............................................................................50 Adding a condition for record not found......................................................................................51 Adding a push button to the page .................................................................................................52

Testing the application .....................................................................................................................54 Adding code to change UI control attributes at runtime ..................................................................56

Appendix ...........................................................................................................................62 Specifying the data source name in the project properties ...........................................................62 Specifying the jdbc driver to use ..................................................................................................63

Appendix A .......................................................................................................................66 Specifying the runtime environment for the EGL web application in the EAR deployment descriptor...........................................................................................................................................66 Appendix B........................................................................................................................76

Configure the runtime information in WebSphere Application Server............................................76 Start the server and run the administrative console......................................................................76 Configure Global Security............................................................................................................78 Configure an environment variable ..............................................................................................80 Configure JDBC Provider ............................................................................................................82

Visit the EGL Café to get more information, join the community....................................89


EGL for IBM i developers This document provides basic procedures for creating a Dynamic Web project, configuring EGL, getting database definitions from i5/OS, working with both webtools and Rational Business Developer Extensions and writing some EGL code.

The finished application will contain the following web pages and capabilities You will create a web application with three web pages:

• A login page that has two input fields, and some error handling for these fields

• If the correct username has been entered then the application will display a second web page. You will write the logic to access an employee database to check the username against the employee database.

• The second page shows a search field that allows to filter customer names in a customer database base table and then lists the customers fitting the search criteria in a list on the web page



• From this list the user can then select a specific customer to work with • Clicking on a customer number will show this detail customer data web page.

• All fields from the IBM i table(file) are displayed as input fields and buttons are available to update the record, or delete the current record.

Now you know what you have to build in this Lab. Let’s get started, just follow the detailed instruction in this lab script and you will learn how easy it is to write an EGL data access application.



Creating the application

First Steps In this section we show you how to change some of the workbench preferences so the workbench is set to work best for this EGL project.

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 to use a new workspace so your environment fits the environment we used when we created this script and the screen captures.

• Click Start All programs IBM Software Development Platform IBM Rational Business Developer IBM Rational Business Developer

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:



• Click the x on the Welcome tab to remove the Welcome page.

Changing workbench preferences Before creating a project you should setup the EGL environment to reflect your needs. You customize your workbench environment by using the preferences dialog. For this exercise you will change the defaults for converting IBM i OS DB2 UDB data types in EGL projects and the workbench validation rules.

Setup the EGL Tools in the Workbench Just follow the steps below to change the default for the transformation of data base character field variables on IBM i to EGL data items of type character. The default is to transform them to string type data items.

• First select the Window action from the workbench menu.

• Select Preferences from the context menu

The Preferences dialog will open.



• Expand the EGL node in the preferences tree (click the +) • Click on SQL inside the EGL node

In the EGL type to use for columns containing an SQL character data type

• Select Use EGL type char This will create EGL data items of type char instead of the default type string

• Click the Apply button to apply your changes.

Changing validation preferences We want you to change one more preference to improve the workbench performance, for EGL you don’t need to have validations done since the majority of code is generated for you and validation doesn’t have to run against the generated code.

• In the Preferences tree, scroll down to the Validation node.



• Select the Validation node, so the validation dialog appears on the right of the tree view. • Click the Disable All button, to deselect all validations. • Click the OK button, to leave the preferences dialog.

You are ready to create the EGL web project.



Create an EGL web project The following steps will guide you through creating an EGL Dynamic Web Project. In the RDI SOA workbench you will be using the Web perspective with all the views and editors needed to work with an EGL web application. Switch to the Web perspective by:

• Clicking on the open perspective icon on top right hand side of the workbench • Selecting the Other… action from the context(pop up) menu

The Open Perspective dialog shows:

• Select Web from the tree in the Open Perspective dialog Create the EGL project with the name EGL_lab by following the steps below:



In the Project Explorer view,

• Right click on the white space (or select the New action under File on the workbench menu)

• Select New Project…on the context menu In the New Project dialog



• Expand the EGL node • Select EGL Project as the project to create . • Click the Next > button

On the next wizard page:



• Enter the Project name: EGL_lab • Select Web Project as the project type to create • Click the Next > button



• Make sure WAS 6.1 or WAS 7.0 is selected as target runtime

Note: The WAS runtime needs to be selected not the WAS stub. • Click the Finish button

The wizard will now create the EGL web project and EAR file. Your workspace should look similar to the following illustration.

In the workbench

• Expand the EGL_lab project. Spend a few moments and explore the directories and artifacts created by the wizard for you. You will be working extensively in the EGL Source and WebContent directories. Clean up the workbench views by closing all unnecessary views:

• Click the X on a tab in the content area, to close any dialogs in there. In order to use the toolbox jdbc driver to access the IBM i database at runtime you will have to copy it into your project, or point to it using the project properties. We show you in the next steps how to copy it into your project. The appendix contains instructions how to point to it instead.



Copy the jt400.jar into your project First look for the jt400.jar on your Windows system, normally you find it in this directory: C:\ProgramFiles\IBM\SDP70Shared\plugins\com.ibm.etools.iseries.toolbox_7.1.0.v200801310337\runtime.jt400.jar Depending on where you installed RDI SOA it might be in a different path but will be in SDP70Shared\plugins\ If there is a jt400.jar file with a higher version number available, please use the jar with the highest version number.

• Select the jt400.jar file and right mouse click and select copy In the workbench, in the Project Explorer view

• Expand the EGL_lab project • Expand the WebContent folder • Expand the WEB-INF folder • Select the lib folder • Click Paste on the pop up menu

You are ready to get the database definitions from an IBM i system



Get Database Table Descriptions into the EGL web project In this step, you will connect to your IBM i system and import the table definitions for the database tables used in this project.

• Right click on the EGL_lab project icon in Project Explorer . • Select the New action from the context Menu • Select Other… from this menu. You want to create an application that accesses IBM i DB2 UDB, so you will create an EGL Data Access Application In the Select a wizard dialog:



• Locate and expand the EGL node in the tree. • Select EGL Data Access Application • Click the Next > button You will now create a new database connection for this project. Note: If you already had specified a database connection before, you could re-use this connection instead.



Creating a data access connection

• Make sure your project name EGL_lab is selected • Click the New... button to create a new Database Connection

You now have to specify the connection information, like what relational database you want to use and the server this database is located on.

On the New Connection dialog:

• Select DB2 UDB i5/OS in the Select a Database manager view • Specify the IBM i host name (iseriesd.demos.ibm.com is being used in the picture)

Note: We are using an IBM demo system on the internet. You should be able to access this system from any location. If you are working in a hands-on Lab environment with instructor: Ask the instructor for the system name to use in this lab and the userid and password to use:

For the IBM demo system, specify the following Userid and password, Userid: EGL4RPG Password: EGL4YOU

• Check the Save password check box • Click the Test connection button •



Hopefully you will see a message box indicating successful connection.

• Click the OK button • Click the Next > button on the New connection dialog

Now you have to specify which schemas (libraries) your tables (database files) are located in. Here in this Lab you are working with the schema assigned to your team. To select the schema follow the instructions below

• Deselect the Check box Disable filter • Select the Radio button Selection

A list of all schemas(libraries) is show. • From this list, select EGLLABV7xx (xx being your team number) • Click the Finish button

Now you need to select the tables you need in this application inside the schema. For each of the tables, you will then select which columns(fields) you will work with in the application you are building



Selecting the tables(files) to work with

In the EGL Data Access Application dialog

• Select the EMPLOYEE and CUSTOMER tables as shown in the picture above

• Select the check box for Create web pages, this will cause the EGL wizard to create two

Web pages for each table.

• Click the Next > button

We will now walk through the steps necessary to map database tables into EGL for use as record

descriptions and to generate the basic SQL data access functions that you can use in the EGL

application.

Specifying data access details You also need to specify what information should appear on the web pages for each of the tables. So

the wizard can generate the base web pages for your application.

Each table is represented in a tab in the following dialog.

For each table you need to specify the key fields to be used and the Search fields.



In this application you will display data from the CUSTOMER table, and you will access the

EMPLOYEE table to check for the correct username.

The Search fields are the fields on the web page, allowing the end-users to subset the data they want

to see from these tables.

• For the CUSTOMER table:

o Select key field Customer_ID

o Select Search field Last_Name

• Click on the EMPOYEE tab

For the Employee table we don’t select a Search field (no UI only program access needed)

• Select key field EMPNO 23 Create an i5/OS EGL web application


• Click the Next> button

The next dialog allows you to:

1. Customize the heading that appears in the generated web pages for each column in the tables. 2. Select the columns to be shown in the selection list for the table that is shown on the web

page after the end-user selects the Search criteria.

For the CUSTOMER table:

In the Modify field display name: list • Specify the Customer_ID heading to see what effect this has on the generated web pages

In the Choose summary fields: list • Select the four columns shown in the figure above. These are used on the Customer List web

page. For the EMPLOYEE table there is no need to specify any user interface customization since you will not use a webpage to show data from this table.


Setting up the runtime environment Now you need to specify some code generation information. You need to tell EGL if you want to

generate the data access functions as a service or as a function in an EGL library.

In this Lab you will use the data access functions internally in the EGL application, you have to

specify EGL libraries.

Some more runtime information is needed so the wizard can generate the correct code.. You have a

choice of: 24 Create an i5/OS EGL web application


• Full qualification with the schema(library) you just used to get the table definition, or

• setting the schema(library) name at runtime.

The JDBC i5/OS toolbox classes allow two settings for dealing with names during runtime on IBM i

1. Using SQL naming convention

2. Using i/5/OS native naming conventions.

One of the major differences between these two besides which syntax to use for the schema(library)

name path, is the way the schema(library) name is determined:

• If you use SQL naming, the Username at runtime will be used as the qualified schema name

for accessing tables.

• If you use i5/OS naming, the library list will be searched for a table name

For this Lab use the full qualification of the table name, this is the easiest in our situation, where we

have a fixed location of the table at runtime.

• Make sure that the selected Data access method is EGL libraries

• Select the check box Qualify table names with schema




The summary shows what has been selected, you can go back to make corrections if needed.

• Click the Finish button

Code generation will take a short while.



Specifying data source for runtime data access Now you will need to set the project properties to specify the SQL runtime environment. You will reuse the database connection information that you already specified in the Data Access Application wizard. In the Project Explorer view:

• Right click on project EGL-lab • Select Properties from the context menu

In the properties dialog



• Select EGL Runtime Data Source • Select the Load values from a data tools connection radio button. This allows you to re-use

the connection information you specified earlier.

• Click on the expansion button for the pull down in the Connection: combo box • Select the connection name you created in the previous steps in the Data Access

Application wizard. • Press the Ok button

You might get a message dialog

• Click the Yes button to update the EGL build options. Now you need to regenerate the project:



• Right click the EGL_lab project • Select the Generate action from the context menu The generation will take a couple of moments.

Changing the dateFormat property in the data source You will now need to specify an attribute in the data source definitions for this data base access. The date fields in the data base files on the IBM i system are stored in iso format. You need to specify this in the data source definitions which are stored in the runtime ear file for this project. In the Project explorer view:



• Right click the EGL_labEAR file, this file is automatically created for web projects. Note: In the advanced options in the New project wizard you can actually specify the name for this file. The default is the project name with the postfix EAR.

• Double click on the Deployment Descriptor: EGL_labEAR, to open it in an editor In the editor:

• Click the Deployment tab In the editor: 30 Create an i5/OS EGL web application


From the JDBC provider list,

• select Generated DB2 for AS/400 JDBC provider From the Data source defined in the JDBC provider selected above list,

• select the jdbc/iseriesd.demos.ibm.com data source. This is the name that was created by the Data Access Application wizard

In the Resource properties defined in the data source selected above list, • scroll down until you see the dateFormat property • Click the Edit… button for this list

In the dialog:

• Specify the Value: iso • Click the OK button



Back on the Deployment page in the editor window

• Click the save button in the workbench • Click the X on the editor tab to close the editor

Now you are ready to show data on the generated web pages



Running the generated Web pages Before you try running the generated web application, lets modify the WebSphere Application Server.

Skip this step unless the instructor tells you to apply this change and skip to topic Run the web applicaton

Modifying WAS settings

• Locate the Servers tab, at the bottom center view of the workbench • Select the tab to view all application servers installed

• Double click on the WAS server you are using to open the properties editor In the editor



• In the Server connection types and administrative ports group • Unselect the RMI server connection type, which doesn’t tolerate certain runtime misbehavior • Click the x in the editor tab to close this editor • Specify Yes when asked to save the changes

Run the web application You are ready to run the web pages and try them out. The generated web pages have been created in the WebContent directory in your project. Find the WebContent folder in the Project Explorer view.



• Expand the WebContent folder • Select and right click the customerListPage.jsp file • Select RunAs from the pop up menu • Select Run on Server from the pop up menu

If you don’t have a default server specified you will see a dialog like this show up



• Select WebSphere Application Server v6.1 • Select the Set sever as a project default checkbox • Click the Finish button.

If the dialog doesn’t show up because there is already a default server selected, then you are fine. The web page will show up in the browser window. Your browser should show a page similar to the picture below

• Click the Search button

36

Create an i5/OS EGL web application


Notice, Last_Name is the column you selected when specifying the search field for the customer table. The data access wizard created this window according to your choices. The condition field allows to filter for specific customers to be listed. In our scenario we want you to see all customers. By clicking Search without using a filter, all customers in the database show in the list. The application now accesses the IBM i customer database table and you will see a list of customers show up.

The list is composed of the columns you selected in the data access application wizard. The key column is implemented as a link it allows you to select a specific record to display all fields in an update/delete page.

• Click on the link for one of the customer numbers The details page for this customer will show.

37

Now we want you to create your own login web page and write EGL code to validate the username from the login page against the EMPLOYEE database table.



In the workbench, close all views that remain open in the content area of the workbench. Tto do this:

• Right mouse click on the Browser tab and select Close all, to close all editor and browser windows that might be open.



Creating a new Login web page To create a new web page you will use the web page wizard and the page designer, both these tools are part of the web tools that come with RDI SOA. The page designer supports design of java server faces web pages and also has some additional capabilities to provide tight integration with EGL. Since all your generated webpages are located in the WebContent directory, the new page should also be stored in there.

• Right click on the WebContent directory • Select New from the pop up menu • Select WebPage from the content menu

The new WebPage wizard dialog appears

• Enter a name for the web page (we used myLogin.jsp) • Click the Finish button

The page designer gets invoked and you can start to create the visual layout of your web page. The goal is to create a page with two input fields:

- username - password



After a little while the page design editor will show

• Make sure the Design tab at the bottom of the editor is selected • Enter a heading at the top of the page • Click the Enter key a couple if times to add some space underneath the heading

Adding EGL variables und input fields Now create an EGL variable and an input field on the web page by going thru these steps

• Select the New variable icon in the EGL drawer A retangle will appear in the designer, representing a form that is getting created

• Click inside this rectangle The Create a new EGL variable wizard appears

• Make sure the Type Selection radio button Primitive is selected • Enter a name for the field e.g. username



• Select Data Type char and Dimensions 10 for your 10 character username • Make sure the check box Add controls to display the EGL element on the Web page is

selected, this invokes a wizard to specify the input field characteristics. • Click the OK button

The Configure data controls dialog shows

• Select the radio button Updating a exiting record, if not already selected, this will give the UI control input capabilities

• You might want to change the label by just clicking on it in the list (in the picture we left it unchanged)

• Click the Options… button

The options dialog allows you to specify additional options for this UI control, one of these options is the automatic generation of submit and delete buttons for the Page

. You will create your own buttons for this web page later in this exercise • Unselect the check box for the Submit button • Unselect the check box for the Delete button • Click the OK button

Back in the Configure Data controls dialog • Click the Finish button

The web page in the page designer tool now contains: 1. An input field with the correct heading. 2. An error message to display jsf runtime messages has automatically been added.

You need to make some space for the password input field and a push button. 41 Create an i5/OS EGL web application


3. Left click in front of the Error Message control 4. Then click the Enter key three times

This moves the Error Message control down and allows you to add the password input field.

• Click the New Variable control to select it • Click underneath the Username control in the design panel to indicate where you want to

position this new control The New EGL Data Variable dialog appears



• Enter password for the name of the field • Enter 10 as value for the dimension of the character field • Click the OK button

Now you specify the UI data control properties, since this is a password field you will specify that the data should be shown as secret data.

• Click the little arrow beside the Control Type column in the fields list • Select the Secret Input Field from the Combo box • Click the Finish button

Now your page also contains a password input field.

Adding context specific message areas to the page You will add two error message controls that are directly linked to jsf validation error messages for the specific fields.



• Click on the Enhanced Faces Component Drawer in the Palette This expands the drawer and you can now select from a wide variety of UI controls

• If you can’t see the Display Error controls, click on the little triangle at the bottom of the Enhanced Faces drawer to scroll up.

When you see the Display error control

• Click on the Display error control (not the Display errors control underneath) • Click behind the username input field, (this will position the error control behind it.)

For the password control do the same • Click on the Display error control (not the Display errors control underneath) • Click behind the password input field, (this will position the error control behind it.)

You are almost done with the user interface design. You only need to adjust some properties.

Adjusting properties for the web page



You need to bind the error message controls to the input field controls, at the moment they are positioned close to each other, but the jsf framework doesn’t know that these controls belong together.

• Select the Error Message control behind the username input field • Click on the Properties tab underneath the page design editor • In the Display error messages for this component input field click the expansion button on

the side of the input field • From the list select the text1username input field control (this is the default name page

designer assigned to it when you created the input field) Now you need to do the same for the other Display error message control,

• Select the Error Message control behind the password input field • Go to the Properties tab and select the password input field to be linked, the same way you

specified the link for the username field. The Error Message control at the bottom that handles all messages for the page has to be adjusted to reflect the fact that control specific messages are now displayed in the two message controls you just added.



• Select the page level the Error Messages control Go to the Properties view:

• Click the radio button Show only error messages not associated …. You now want to enhance the title for this page

• Select the heading text on the page The properties for the text get shown in the Properties view

• For the Paragraph type, select Heading 2 • Save your work by clicking the save button on the workbench



Writing EGL code for the web page Now you specify some validation rules for the username field in EGL and you will write the validation routine that checks that the username keyed in on this page, is an employee of the company by comparing it with the employee database.

• Right click somewhere on the white space on your web page • Select Edit Page Code from the context menu

The source editor will show, it contains EGL code that has been generated when you worked with the page designer tool. All pages in an EGL web application have individual EGL Page code attached to them.

You can see that two EGL variables (username/password) have been generated for you. You will now add additional properties to the username variable.

Adding properties to varables and a record definition In EGL properties for variables are specified inside curly brackets. You want to make sure that the user keys in a username and the field is not left blank, jsf can check this for you, and you also want to uppercase any input so it easily matches the employee last names in the database.

• At the end of the username variable statement, before the semicolon, insert a curly bracket {, the corresponding } will be inserted automatically.

• Position the cursor inside the {} brackets • Press ctrl + space bar this shortcut will invoke the content assist feature in the source

editors in the Eclipse workbench (this is true for the RPG source editor as well as the Java editor)

• In the content assist list scroll down to InputRequired and double click on this property The InputRequired = string will be inserted inside the curly brackets



• Add the word yes after the = sign

• Add a comma after the yes • Ctrl + space bar again (for content assist) • Now select UpperCase from the list • Add the word yes after the = sign

You need to get (read) a row from the employee table to check the username from the page against the Last name column in the Employee table. In order to get a row we need to store the data in a record (data structure) that matches the column layout of the employee table.



In EGL records are equivalent to data structures in RPG. So we need to define a record variable (like specifying a data structure name in a D spec). The layout of this record variable is like the column layout of the employee table. The name we use for this variable is empl.

• Position the cursor after the semicolon in the password definition • Click the Enter key, to add a new line • For the name of the variable, enter empl in the new line • Add a blank (blank delimits the variable name) • Enter the character e as a starting character for the data type of this variable, (this will

filter the content assist list to available data types that start with e) • Click ctrl + space bar • Select the Employee – s400a data(record) (in the picture we worked with a different

server torasedu) from the list, (the record data type for each table from the Data Access Application wizard was generated for all tables that you selected to work with)

• Add a semicolon at the end of the finished data definition statement.



Creating a function to validate the user name Now that you have a record variable defined you can write the EGL get statement to retrieve the data into the variable. You will create a new function (procedure) named validate to get the employee record. Notice that there are already two functions defined in this EGL source file. These functions are being invoked each time the associated page to this file is loaded before the page is displayed. If you want to add data to the page or change its look before the user sees it, this is the place to add the code to do this. Go ahead and create the new validate function

• Add the function statement after the end statement of the pre-created functions • Add the get empl ; statement • Position the cursor between the empl and semicolon and right mouse click



We want you to modify the default SQL statement that is associated with a get to the employee table.

• Select SQL statement from the context menu Note: It is important that the cursor position is correct, right before the semicolon when you right mouse click

• Select Add from the context menu This will add the default SQL statement for a get into your source. You can now customize this SQL statement so the where clause reflects that you want to get a row where the LASTNAME column matches the content from the username field.

• In the SQL statement change the where clause to EGLLABV7XX.EMPLOYEE.LASTNAME=:username

Adding a condition for record not found You will need to add some code that handles the condition that a matching employee has been found or not found.



The information what happened to this get request is returned in a SQL return code. You need to add a couple of lines of EGL code that handle a found/not found condition after this SQL statement.

• Enter the following code after the end of the SQL statement

if(sysvar.sqlData.sqlcode != 0) syslib.setError("Please enter a valid username"); else forward to "customerListPage"; end end

• Use content assist to help you writing the code

The two end statements are needed to end the if statement and to end the function. You are almost done, save the changes

• Click ctrl + s, to save. If there are problems in your code the lines with errors are marked with a red icon.

• Fix any problems EGL will re-generate the underlying code as you save these page code files. After everything is fixed there is one more task and then you are done with this page. You need a way of invoking your validate function. To accomplish this go back to the page design editor.

Adding a push button to the page



• Click on the myLogin.jsp editor tab to get back into page designer

• Click on the Page Data view tab, at the left bottom corner of the workbench • Expand the JSF handler node • Expand the Data node, it shows all variables defined in the jsf handler. You now drag

and drop these onto the page.



You need to provide a push button to the page that allows the end user to invoke the validate function:

• Expand the Actions node, it shows all the functions in the jsf handler for this page. • Drag and drop the Validate function onto the page

You will see the tool creates a validate button on the page

.

• Save the page by clicking ctrl + s Now you are ready to test your new page and the EGL code.

Testing the application You will run the application again but now starting with the Login page. You will check the UI constrain that requires input for the username input field and you will check that your code is working, comparing the username input against the employee table.



• Right click the myLogin.jsp file in the WebContent directory • Select RunAs Run on Server

To test the error handling you built into this page: • Click the validate button

You see the validation message for the jsf message that input is required. It is handled as a username field error since it is triggered thru the EGL Input required attribute that you set to yes. The jsf framework is doing the check for you and issuing the message.

Next you test the error routine that you created in the EGL page handler validate function.

• Key in a name that is not in the employee data base (weiss is a name that is not in there)

• Click the Validate button

You see that your user defined error message appears in the message control at the bottom of the page. You also notice that the username is uppercased.



Now let’s test a valid employee name

• Key in a valid username (haas is in the data base) • Click the validate button

Now you see the customer list page that you specified to forward to in the EGL code.

Congratulations your EGL application works.

Adding code to change UI control attributes at runtime If you still have time you can enhance the login page by coloring the input field in error in addition to showing the error message itself. EGL provides some cool interfaces that allow you to work with page control attributes directly from EGL without having to write JavaScript code.



Clean up the workbench and close all editor views and web browsers by:

• Right clicking on a tab of one of the open editors • Selecting the Close All action from the pop up menu

Now open the myLogin.jsp

• Double click on the myLogin.jsp file in the Project Explorer view The page designer tool opens with the web page. Now open the source editor with the EGL page handler code.



• Right click on the white space in the Design page of the page design editor • Select the Edit Page Code action on the pop up menu

The source editor opens the myLogin.egl file. You will add code into the not found branch of the if statement you created before.

• Insert a blank line after the if(sysvar… ) statement by clicking the Enter key at the end of the statement.

• Click the key combination ctrl+shift+z This brings up a dialog showing all controls on the web page in a tree view

• Select the textUsername1 control in the tree view • Click the OK button

Two EGL statements get added, for setting up an environment that allows you to access the attributes of the user name UI control on the web page.



The definition of a variable textUsername1 has been added and a statement that stores a reference to the username control into this new variable. You can now use this variable to access attributes for this control.

In the new line underneath the second statement that got added in the previous step:

• Key in the variable name that was created in the previous step (in the sample picture above textUsername1) and a period indicating you want to invoke a function to access attributes for this control .

• Click ctrl+spacebar (content assist) for a list of all function supported for this UI control • Scroll down to the setStyle(StyleString) this allows you to change the control style by

providing the value of the style as a string. You want to change the background color of the username variable to red if the error condition is true.

59Inside the bracket after the word setStyle:



60

olor:red” ce that this is the normal syntax for style

a semicolon after the bracket

owing up

est your new feature

• Enter the following: “background-cIf you have worked with web styles before you will notidefinitions

• Add• Click crtl+s to save the file • Fix errors if you got some sh

T

• Select the myLogin.jsp file in the Project Explorer view • Select Run As on the pop up menu • Select Run on Server

n the Login page: ng employee name (e.g. weiss)

he username field will appear with a red background.

O• Key in a wro• Click the validate button

T



This concludes the EGL introduction hands-on Lab, we hope you enjoyed the experience. Give EGL a try, write new applications or modernize existing applications. The appendix in this document shows how to set up your data source definition in a project. There are two 2 choices

1. Setting up the data source definition in an EAR file 2. Setting up the data source definition in the server

The appendix will show both approaches. The appendix is for your information to help you setting this up in your own environment at home, don’t use it here in the lab. Some more comments if you want to try EGL at home. You can download a free, time limited trial version, of RDI and RBD V7.5 from the following websites. Visit the EGL café for information about EGL, discussions, blogs, documentation and much more ibm.com/software/rational/cafe/community/egl or google for EGL Café


http://www.ibm.com/software/rational/cafe/community/egl


Appendix In appendix A and Appendix B you will find the instructions how to set up the data source definitions. In Appendix A we show how you can define the runtime and data access environment on a web application (project) base. This is also what you used in this lab. You can also setup the runtime and data access environment on a server level, so you don’t have to do this setup for each web application. In Appendix B we show you how to setup the server, if you decide to go with a server setup If you do the setup in Appendix A you can skip Appendix B. To adjust your project to the data source names that you use in the EAR deployment descriptor or WAS server properties you will have to change the Project properties, here are some hints how to accomplish this.

Specifying the data source name in the project properties In the project, we use EGL_Lab here as the Project name and jdbc/mydata as the data source name.:

• Right click on the EGL_lab project icon • Click on the Properties action in the pop-up menu

In the properties dialog



• Select the EGL Runtime Data Source node from the tree view on the left side of the dialog • Select the radio button Input/modify values manually • Provide the JNDI name to connect to your IBM i database.

We used: jdbc/mydata. By convention the format is jdbc/xxxxx . • Click the OK button • If a message box appears to update the build descriptor, click the OK button

The wizard will now apply these property settings. On the project:

• Use the generate action to re-generate the project and apply the changes to the generated files.

Specifying the jdbc driver to use To access the IBM i DB/2 you will to use the toolbox jdbc drivers. Here we show you how you to point to the driver or copy it into your project. 63 Create an i5/OS EGL web application


In the workbench

• Expand your project. We are showing you both ways to work with the jdbc toolbox driverjt400:

1. Copy and paste the jt400.jar file into the LIB project directory 2. Add the jt400.jar file to the path definition for this project.

Here is a description how to accomplish both, just use one or the other.



Copy the jt400.jar into your project First look for the jt400.jar on your Windows system, normally you find it in this directory depending on where you installed RDI SOA, this is the default location: C:\ProgramFiles\IBM\SDP70Shared\plugins\com.ibm.etools.iseries.toolbox_7.1.0.v200801310337\runtime.jt400.jar

• Select the jt400.jar file and right mouse click and select copy In the workbench, in the Project Explorer view

• Expand the EGL project • Expand the WebContent folder • Expand the WEB-INF folder • Select the lib folder • Click Paste on the pop up menu

You are done, skip to setting up your runtime in Appendix A or B.

Setup the path in your project to point to the jt400.jar If you want to setup the path to point to the location of the jar file do the following:

• In the workbench right click on your EGL project • Select properties from the pop up menu



On the project properties dialog

• Select Java Build Path on the properties tree • Select the Libraries tab in the right dialog • Click the Add External JARs… button • Browse to this location ( this is the default location when installing RDI SOA)

C:\ProgramFiles\IBM\SDP70Shared\plugins\com.ibm.etools.iseries.toolbox_7.1.0.v200801310337\runtime.jt400.jar

• Click the open button The jar is now added to the Libraries properties page

• Click the OK button on the properties dialog You are done Now you can specify the connection information You have a choice of specifying the data source at the application server level using the application server administration console or at the application level using the EAR file descriptor. Specifying the information in the EAR file only makes the information available for this application, specifying it in the Application Server makes it available for all Web applications running in the Application Server. Appendix A shows how specify the connection information in the ear file, Appendix B shows how to specify it in the Application Server. Depending on your needs set up the connection according to one of the descriptions.

Appendix A

Specifying the runtime environment for the EGL web application in the EAR deployment descriptor You will specify the data source to be used at runtime, so the application server knows where the database is located and what database driver to use.



• Expand the EAR node of your project in the Project explorer tree view • Double click on the Deployment descriptor node

This will open the Deployment descriptor editor • Click on the Deployment tab in the editor

You now have to specify the Data Source information, part of this information is the authentication data.

• Scroll down in the editor to the Authentication area • Expand Authentication • Click the Add… button

The JAAS Authentication dialog appears:



• Specify an alias name (any name will do) • Specify the userid for your runtime IBM i system (in the lab we used EGL4RPG) • Specify the password for the userid (in the lab we used EGL4YOU) •

Note: This Userid and Password combination will work for the IBM demo system Now you need to specify the JDBC provider. Since you are using a DB2 UDB IBM i fill out the following information.

• Scroll up to the top in the editor • Click the Add button for the JDBC provider list

You will use the i5/OS toolbox JDBC driver



• Select the IBM DB2 database type • Select the DB2 UDB for i5/OS (Toolbox) JDBC provider type • Click the Next…> button

The wizard needs to give this provider a specific name, so you have the choice of using different providers in the same application.



• Specify a name for the provider (any name will do) • Click the Finish button

Now you need to specify the specific database you want to access using the driver you specified.

• Click the Add button for the Data source defined in the JDBC provider selected above You will use the i5/OS toolbox driver.



• Select the DB2 UDB for i5/OS (Toolbox) provider type • Click the Next > button

Now specify the JNDI name that you have used in the project t creation wizard. Note: This name is case sensitive so be careful and use the exact same name as before in the project wizard (suggested name was jdbc/mydata) The authentication alias to be used for this database access has to be specified as well.



• Specify the JNDI name that you used when you created the EGL project (we suggested to use jdbc/mydata)

• Specify the authentication to be used for both Component managed and Container managed (use the alias that you created earlier)

• Click the Next > button The wizard will now prompt for any required information for this JDBC driver. The server or database name is a required value.



• Specify the server name (in our case s400a) Note: If you access your own server or directly want to access the IBM demo system without the alias s400a, enter the required server name here. (IBM demo system is iseriesd.demos.ibm.com)

• Click the Finish button Now you need to specify the date format, a variable name for this information has already been created. The database tables contain date columns in iso format to make sure this format is used when getting the data, you need to specify this information so the JDBC driver sets up the connection accordingly.



In the list Resource properties defined in the data source selected above:

• Scroll to Name dateFormat • Select dateFormat • Click the Edit button • Specify iso in the value field • Click the OK button

You are done and can save the Deployment descriptor now.

• Save the Deployment descriptor by clicking on the Save icon



When you create the EGL project, you specify the JNDI name in the project by changing the project properties, as shown in the Appendix. This name is stored in the EGL build descriptor that is located in the EGLSource directory You can make sure the JNDI name in the EGL build descriptor and in the application runtime are the same, just check the EGL build descriptor.

• Expand the EGLSource directory • Double click on the .eglbld file • In the edit window make sure the checkbox Show only specified options is checked • Make sure option sqlJNDIName is the same as the JNDI name that you specified in the EAR

file deployment descriptor. (Make sure the Value is exactly the same it is case sensitive) You are done, your project now has the runtime information needed, you can now create the EGL application to access your database as it is described in the hands-on lab.



Appendix B

Configure the runtime information in WebSphere Application Server A full function instance of the WebSphere Application Server is installed on your workstation. You already used it in this hands-on lab to test your application. In the Lab you use pre-defined data source information. In this appendix you learn how to set up the data source information for a System i data base for all applications running in an application server. These instruction are for WAS 6.1, the WAS administration console screens are a bit different from version to version, so if you still use WAS 6.0 the screens will be a bit different, but you should still be able do the setup with these instructions.

Start the server and run the administrative console You will need to invoke the WAS admin console first. For this the server has to be started, if it is not started. In the server view at the bottom of the workbench.

• Select the Server right click on it • Select the Start action from the pop up menu

Now with the server in started mode, run the Admin Console



In the servers view at the bottom center of your workspace

• Right mouse click on the server you want to set up • Select action Run administrative console

You might get asked for a user name, then use your name, this doesn’t have to be any registered user, any name will do.

• .Enter a User ID • Click the Log in page

The administrative console appears in the browser window



Configure Global Security First you will need to create a JAAS J2C Authentication entry to define a userid and password for the I5/OS at runtime.

• Click the Security tab’s plus sign to expand its choices in the left menu. • Click on Secure administration, applications

. The body of the page valid for this action will be displayed in the right hand side. • Scroll to the right until you can see the Authentication options • Expand “Java Authentication and Authorization Services” • Click on “J2C authentication data”.

Now you can add an entry for the I5/OS authentication

• Click on New button to create a new entry. The dialog for entering a new authentication entry opens.



• Enter an alias name, you will use this alias name later when defining the I5/OS UDB DB2 datasource. Any name will do

• Provide a userid that is valid for accessing the System database (your own or other designated profile).

• Provide the Password for this user profile • Optionally provide a description of this authentication entry. • Click the OK button

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.



• Click the Save button to save your changes.

Configure an environment variable You need to specify the path to the toolbox driver. In an later step you will provide a variable name to contain this path information. Now you have to fill the variable with the path information.

• Expand the Environment node on the left side of the admin console • Click on the WebSphere Variables node • Scroll down until you see the OS/400 toolbox JDBC Driver Path link in the list of variables • Click on the link to add a value to this variable



• Enter the path where to find the toolbox driver. The default location in RDI SOA is this. C:/Program Files/IBM/SDP70Shared/plugins/com.ibm.etools.iseries.toolbox_7.1.0.v200801310337/runtime

• Note: Be aware of the forward slashes instead of the default Windows backward slashes for separating directories

•

• Click the Save link on top of the variables list page You can check the path information



By checking the OS/400 Toolbox value entry in the variables list (The picture shows our path info which shows the D: drive being used since our RDI SOA installation used this drive).

Configure JDBC Provider Now you are ready to define the database provider and datasource

• Expand the Resources node • Expand the JDBC node • Click on the JDBC providers node

If you already got a DB2 UDB for i5/OS (toolbox) provider in the list of JDBC providers than go directly to configuring a data source otherwise

• Click the New button



• Select DB2 from the Database type drop down list. • Select DB2 UDB for i5/OS (ToolBox)” from the Provider type drop down list.

NOTE: be certain to select the “ToolBox” choice and NOT “Native”. • From Implementation type drop down list, choose Connection pool data source. • Click the Next Button

On the next panel accept the default for the variable name containing the driver path.

• Click the Next button The summary page appears



• Review the data displayed in the dialog. • If everything seems correct click the Finish button

The JDC providers list appears again, now containing the new provider you have added

• Click the save link in the Messages box on top of the screen • Be sure to click the “Save” button in the next dialog • In the provider list, click the provider Link that you just added to create a data source for this

provider. In the following dialog for this provider



• Click the Data sources link A list of data sources will appear

• Click the New button

• In the JNDI name field enter the jndi name that you use in your EGL project • We use jdbc/mydata in the hands on lab (the picture shows a different name)

Note: This name is case sensitive • Also enter the authentication to be used for this data source, select the alias you created

earlier in this appendix. • Click the Next button



• Enter the IBM i server name, depending on your network you might have to add the entire domain name.

Note: The IBM demo server has the name iseriesd.demos.ibm.com • Click the Next button

• Click the Finish button after verifying everything is correct To change the date format to iso to be able to access some of data in the date fields in the Lab database do the following.



• Click on the link for the new datasource you just created.

• Click on the link Custom properties on the right side of the datasource dialog

• Scroll down to the dateFormat property • Click the dateFormat property



• In the Value input field, and key in iso • Click the OK button

• Click the save link on top of the page • Click the Data sources link on the left side of the dialog



• Select the Select check box for your data source to test the connection information • Click the Test connection button

If everything was setup correct you will get a message indicating a successful connection has been made. Ignore any warning messages.

• Click the Logout button on top of the administration console page •

Now you have setup the WAS environment and all applications running on this server can use the JNDI name jdbc/mydata to connect to this DB2 UDB database on your I5/OS. You can use the hands-on Lab script to create the web application connecting to your server.

Visit the EGL Café to get more information, join the community.



The IBM RationalThe IBM Rational EGL CafEGL Cafééibm.com/rational/cafe/communityibm.com/rational/cafe/community/egl/egl

Enjoy EGL and Rational Business Developer and write great IBM i operating system applications with this powerful tool



Notices

© Copyright IBM Corporation 1992, 2007. All rights reserved.

U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this documentation in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any

reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user’s responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter described in this 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 IBM Intellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia Corporation Licensing

2-31 Roppongi 3-chome, Minato-ku Tokyo 106, Japan



92 Maintain an ILE RPG application using Remote System Explorer

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION ″AS IS″ WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED

WARRANTIES OR CONDITIONS OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, 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 be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.

Licensees of this program who wish to have information about it for the purpose of 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 may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.


93 Maintain an ILE RPG application using Remote System Explorer

All statements regarding IBM’s future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only.

Copyright license

This information contains sample application programs in source language, which illustrates 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 application programs conforming to the application programming interface for the operating platform 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, must include a copyright notice as follows:

© (your company name) (year). Portions of this code are derived from IBM Corp. Sample Programs. © Copyright IBM Corp. 1992, 2007. 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

• i5/OS

• iSeries

• Rational

• System i

• IBM i operating system

Intel® and Pentium® are trademarks of Intel Corporation in the United States, other countries, or both.

Microsoft, Windows, Windows NT® and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.

Other company, product or service names may be trademarks or service marks of others.

Enterprise Generation Language (EGL) for IBM i operating ... · Writing EGL code for the web page...

Documents

Transcript of Enterprise Generation Language (EGL) for IBM i operating ... · Writing EGL code for the web page...