Rapid Application Development with WSED
Part 1: EGL Development and Test

INTRODUCTION

Enterprise Generation Language (EGL) is a development technology (IDE tooling and programming language) that lets you quickly write full-function  applications that can be deployed in WebSphere Application Server, CICS, IMS, and z/OS batch. EGL enables developers, regardless of their experience with underlying run-time technologies, to quickly deliver enterprise data to browsers (in the future, support for other user interface types is likely to be added).

EGL, which is built on the technology of VisualAge Generator, offers several benefits:

• You can quickly implement business logic by using the EGL procedural language and an EGL language-specific debugger.
• You can focus on the problem your code is addressing rather than on the technical complexities of CICS(R), MQSeries(R), and SQL. For example, you can use similar I/O statements to access different types of external data stores.
• You can code in response to current platform requirements without worrying about future migration. An EGL program written for one target platform can be converted easily for use on another.
• You can produce multiple parts of an application system from the same source. After developing an EGL program, for example, you can generate a Java wrapper, an Enterprise JavaBean (EJB) session bean, and a tier 3 program. This increased efficiency comes into play when you develop software to give users access to a tier 2 servlet, which in turn passes data to a generated Java wrapper, which in turn accesses either a generated program on tier 3 or an EJB Server.
• You avoid having to configure a CICS connector when you deploy a generated program on CICS for MVS. A generated Java wrapper on tier 2 reformats the data to be passed between tier 2 and tier 3.

Section 1 - Build an EGL Server Program

1. From the menu bar of the Workbench window, select File, New, Project…
2. On the New Project - Select page, select Simple from the left-hand list and double click on Project in the right-hand list (to double click on an item is the same as selecting the item and clicking on the default button)
3. On the New Project - Project page,
• set Project Name to ATMServer
• set Use Default checked
• click Finish

1. From the menu bar select Window, Open Perspectives, Other..., or click on the Open a Perspective button in the Perspectives tool bar,  select the menu item, Other...
    
2. In the Select Perspective window, select EGL and click OK

 

Later you will use the RETRIEVE SQL feature, which will create data item definitions based on the column definitions stored in relational database catalog. To identify which database and how to connect to that database,  set the SQL database access information in the Preferences view.

1. From the Workbench menu bar, select Window -> Preferences
2. In the Preferences window,
• in the left hand list expand EGL and select SQL
• on the SQL page,
• set Connection URL to jdbc:db2:AIS
• set Database to AIS
• set User ID and Password if your windows logon userid does not have db2 authority
• set Database vendor type to DB2 UDB V7.2
• set JDBC driver to IBM DB2 APP DRIVER
• set JDBC driver class to COM.ibm.db2.jdbc.app.DB2Driver
• set classpath location to x:\...\sqllib\java\db2java.zip file (x:\... is your DB2 install directory)
• click OK

___ 4. Create an EGL Definitions file

 

EGL definitions are stored in one of 3 file types: program file (extension .eglpgm), definitions file (extension .egldef), or build file (extension .eglbld). Program files contain a single top-level program part, which may embed functions and data parts for the program to reference. The name of the program file must match the name of the program part. A program file can import any number of definitions files, which also contain functions and data parts. A program file is written in EGL source format. A program file is what you test or generate. Definitions files contain any number of functions and data parts. A definitions file can be imported by program files or by other definition files. A definitions file is written in EGL source format. Build files contain any number of build parts, which determine how a program is generated and prepared. A build file can import other build files.  You will create an EGL definitions file called, AIS, to contain a DB2 record definition (account) to use when accessing the account table and a record definition (acctws) to use when communicating with the EGL server program.  By having these records in a separate file, then one definition can be easily maintained and still shared by multiple programs - e.g. by a detail program and or by a list program. By storing all of the record definitions for the AIS database in a separate file, the database administrator could be given the responsibility to create and maintain this file for developers to use.

1. In the Navigator View select ATMServer and type Ctrl+N
2. In the New wizard, select EGL from the list on the left and double click on EGL Definitions File in the list on the right.
3. On the Create EGL Definitions File - Select Container page,
• set Enter or select the folder to ATMServer
• set File name to AIS
• click Next
4. On the Create EGL Definitions File - Add Import Statements page, click Next
5. On Add EGL Part - Select Type of Part to Add page,
• select Record (hint: you can type r to select)
• click Next (hint: you can hit Enter since Next is enabled)
6. On Add a Record Part - Enter Record Name... page,
• set Name to account
• click Next
7. On Add a Record Part - Select Record Organization page,
• select SQL Record (hint: you can type q to select)
• click Next
8. On Add a Record Part - Enter SQL Properties page,
• click Add
• set Name to db2admin.account
• keep Label as T1
• click Finish
9. AIS.egldef is opened in the editor area.
10. In addition, AIS.egldef appears in the Navigator view, and the parts it contains are displayed in the Outline view.  The "SQL" next to account in the Outline view indicates that it will access a relational database.


11. Close the editor for AIS.egldef.

 

EGL provides 2 editors for defining and maintaining parts defined in a program file or a definitions file:  The EGL Parts Editor provides a graphical interface for defining/editing EGL programs, functions, data parts, and build parts. For the new user, this editor is easier because it offers a fill-in-the-blank approach.  We will also use it for a time-saving  feature, RETRIEVE SQL, which will create, on the click-of-a-button,  data item definitions for the account record based on the column definitions stored in relational database catalog.  In the future, RETRIEVE SQL will be available in the EGL Source editor as well. The EGL Source Editor provides a language sensitive text editor, where you specify logic and data parts in a similar way to writing code in any procedural language. In this case, your work is in EGL source format. You will use this editor later when defining the record, acctws.

1. In the Navigator view, right click on AIS.egldef and select

     Open with..., EGL Part Editor
2. In editor for account record, right click in the table (see picture below) and from the context menu select Retrieve SQL


3. Click on  (Show SQL Item Properties)
4. For ACCT_NUMBER set Key to YES (hint: click once to select the row, click a second time to select the column value, click a third time to open the drop down list)


5. Save your changes (Ctrl+S) and close the AIS.egldef file.

 

acctws is a working storage record, a temporary data area defined in a program or function. Later you will declare acctws to be the parameter data area in our server program. The client that calls the server program will pass the account # and the withdrawal amount in acctws. On return, the server program will pass the new account balance in acctws.  To take advantage of copy support (cut and paste) and to explore use of an alternative editor,  you will use the EGL Source Editor to define the acctws record.

1. In the Navigator view, right click on AIS.egldef and select Open with -> EGL Source Editor
2. To add a Record definition for acctws.
• place cursor on the last line (line 30) in the editor
• type Ctrl+Space and double click on Record


• starting where the cursor is placed (one space after record) type acctws and hit Enter
3. Create the data items for acctws by copying those from account
• Using Edit,Copy from the menu bar, copy the level 10 data item, ACCT_NUMBER, from account's record definition and using Edit,Paste, place it between record acctws and end
• Copy the level 10 data item, BALANCE, from account's record definition and paste it in Record acctws after ACCT_NUMBER
• Change the item name from BALANCE to TXN_AMT
• Again, paste the copy of BALANCE from Record acctws just after TXN_AMT line


4. Type Ctrl+S to save your changes.  The source in the editor area should look like:


5. Notice the information displayed in the Outline view. It is a summary of what is in AIS.egldef and enables us to quickly access specific definitions.
   
6. Double click on acctws - Working Storage in the Outline view, and observe that the definition for acctws is now highlighted in the editor area.
7. Double click on the data item, TXN_AMT Pack(10,2), under acctws in the Outline view, and observe that the definition for TXN_AMT is now highlighted in the editor area.
8. Close the AIS.egldef file.

 

By having the data areas defined first, code assist can help when inserting data references into a program's or function's logic. This is much faster and more accurate than doing so by hand. Data areas must be both defined and declared in a program or function before any reference to them is valid. Since the records, account and acctws, are defined in another file, AIS.egldef, the IMPORT statement will link those definitions to our program. These records can be declared as parameters or variables. Parameters are passed to a program or function from an external source, whereas variables are data areas internal to a program or function. In our EGL server program, the record, acctws, will be declared as a parameter and the record, account, will declared as a variable.

1. In the Navigator View select ATMServer and type Ctrl+N
2. In the New wizard, select EGL from the list on the left and double click on EGL Program File in the list on the right.
3. On the Create EGL Program File - Select Container page,
• set Enter or select the folder to ATMServer
• set File name to account
• click Next
4. On the Create EGL Program File - Add Import Statements page,
• click Add...
• on the Add Import dialog, expand ATMServer and double click on AIS.egldef
• click Next
5. On the Add a Program Part - Enter External Name... page, click Next
6. On the Add a Program Part - Enter Program Parameters... page,
• click Add...
• In the Add Parameter dialog, set Parameter name to acctws (hint: use the drop down list) and click OK (TypeDef is automatically set to acctws).

  Note: Parameter name is what our logic will use to refer to this data area. TypeDef points to a corresponding data part definition that eventually (before testing or generating a program) must exist.  Generally, Parameter name will be the same as TypeDef, but this is not required.

• click Next.
7. On the Add a Program Part - Enter Program Variables... page,
• click Add...
• In the Add Variable dialog, set Variable name to account (hint: use the drop down list) and click OK (TypeDef is automatically set to account).

Note: Variable name is what our logic will use to refer to this data area. TypeDef points to a corresponding data part definition that eventually (before testing or generating a program) must exist.  Generally, Variable name will be the same as TypeDef, but this is not required.

• click Finish.
8. account.eglpgm is opened in the editor area. It should look like:
   

 

When writing the logic, code assist (Ctrl+Space) can help you code faster and with greater accuracy.  For example, code assist shortens the time it takes to key EGL statements. By having the data areas defined first, code assist can help when inserting data references in the logic.

1. When working in the EGL Source editor, the logic of a program or function is identified by tags,

Script
ScriptEnd

Here are the steps using code assist:
• add a new line after "account account;" (hint: place the cursor at the end of this line and hit Enter)
• in the new line, type Ctrl+Space (a selection list pop-up appears and the first item in the list, Script, is highlighted

),
hit Enter (because Script is already highlighted, there is no need to select it)

2. Add the script:

   account.ACCT_NUMBER = acctws.ACCT_NUMBER;

   Here are the steps using code assist:
• starting where the cursor is placed, type Ctrl+Space, in the selection list pop-up type res, and hit Enter (result = expression; is pasted into the editor)
• double click on result, type account. (include the decimal point)
• type Ctrl+Space, hit Enter (ACCT_NUMBER is already highlighted in the selection list pop-up)
• double click on expression, type Ctrl+Space, double click on acctws in the selection list pop-up
• type "."(decimal point), type Ctrl+Space, hit Enter (ACCT_NUMBER is already highlighted in the selection list pop-up)
3. Add the script:

   update account on exception
           ezertn();
           end

   Here are the steps using code assist:
• add a new line after "account.ACCT_NUMBER ..."
• on the new line, type Ctrl+Space, type u, double click on update recordName on exception... in the selection list pop-up
• double click on recordName, type Ctrl+Space, hit Enter (since account is already selected)
• double click on statements, type Ctrl+Space, type * (asterisk. The combination of Ctrl+Space and * brings up a list of functions), type ezer, double click on ezertn() in the selection list pop-up (ezertn is a built-in function that immediately returns to the caller)
• add a blank line just after end and place your cursor there
4. Add the remaining script. EGL is not case sensitive, however case is kept as entered. (hint: use code assist for the IF and REPLACE statements)

   if (account not err)
           account.bALANCE = account.bALANCE - acctws.TXN_AMT;
    
       replace account on exception
             ezertn();
       end
       acctws.balance = account.bALANCE;
    end

5. Type Ctrl+S to save your changes. Your workbench should look like (except that the Outline View was moved up to condense the image size): 
6. Fix any errors that are displayed in the Task list for account.eglpgm.
7. Save any changes and close account.eglpgm editor.

Section 2 - Test the EGL server program

 

The EGL server program can be tested independently of a web browser client and WebSphere application server. The EGL is generated into Java code and then debugged using the integrated EGL debugger of WSED. A build descriptor controls the generation of EGL into Java code. Build descriptors are stored in an EGL build file. The build descriptor will have these options set: debug=YES causes special files to be created for use with the debugger genProject and packageName indicate where the generated code will be stored J2EE=NO says to create code that does not require a J2EE container sqlDB identifies the database sqlJDBCDriverClass identifies the jdbc support classes to use system=WIN causes Java code to be generated for the Windows

1. In the Navigator view, select the project ATMServer and type Ctrl+N
2. In the New - Select page, select EGL from the list on the left and double click on EGL Build File in the right-hand list.
3. On the Create EGL Build File - Select Container page,
• set Enter or select the folder to ATMServer
• set File name to accountBuild
• click Finish. accountBuild.eglbld is opened for editing.

1. In the Outline view, right-click on accountBuild, and then select Add part…
2. In Add EGL Build Part - Select Type... wizard, select Build Descriptor and click Next.
3. On the Add a Build Descriptor Part - Enter Build Descriptor Name... page, set Name to debug, and then click Finish.
4. debug is added to the Outline view, and the part opens ready for editing. In the editor,
• set Build option filter drop down list to Java Debugging(Basic). The table of build options changes to show only those relevant for debug.
• set debug drop down list to YES (hint1: click in the value cell once to select, click again to get the drop down button, click again the drop down list opens, click on YES. hint2: to progress to the next option hit the Tab key)
• set genProject to EGLDebug
• set genProperties to Yes
• set J2EE drop down list to NO
• set packageName to ATM
• set sqlDB to jdbc:db2:AIS
• set sqlJDBCDriverClass to COM.ibm.db2.jdbc.app.DB2Driver
• set system option to WIN
• Type Ctrl+S to save your changes
• Click Show only specified options and compare to this:


5. Close and save accountBuild.eglbld

___ 3. Generate Java code from account.eglpgm using the debug descriptor

1. In the Navigator view, right-click on the account.eglpgm file, and then  from the context menu select Generate EGL with -> Java Debugging Build Descriptor.
2. The Generate wizard appears. Make sure that account is selected in the list of parts to generate and click Next.
3. On the Generate - Select one or more Java debugging build descriptors... page,
• in the Build Descriptor column for account select debug(ATMServer/accountBuild.eglbld) from drop-down list (hint: click on the cell once to highlight and click on the drop down list button)
• click Finish
4. In the Generation Results view, verify that "Generation completed for program account with no errors."

1. In Navigator view, right click on EGLDebug and select Properties from the context menu
2. On the Properties window,
• select Java Build Path in left-hand list,
• click on Libraries tab (on the right side)
• click Add Variable... button
• In New Variable Classpath Entry window, select DB2_DRIVER_PATH or DB2JAVA from Defined classpath variables list and click OK
• click OK

1. In the Navigator view, double click on account.eglpgm
2. In the editor, double click in the left-hand margin of the line: account.ACCT_NUMBER = acctws.ACCT_NUMBER;. A blue sphere appears indicating a breakpoint is set for this line.


3. Close account.eglpgm

1. Open a Debug perspective (from the menu bar: Window, Open Perspective, Other..., Debug)
2. From menu bar select Run, Debug...
3. Launch Configurations window opens. Right click on Debug an EGL Java program and select new
• set Name to account
• set Project to EGLDebug using Browse button
• set Class name to ATM.account using Browse button
• click Debug

1. When debugger has stopped on the first line of script in account.eglpgm, in the Variables view (upper right corner) expand the structure account and then expand acctws and account
2. Under acctws, set acct_number=2 and txn_amt=2 in acctws. (hint: double click on the variable name, enter a new value, and hit Enter).


3. Step through the program observing the changes to the account variable (hint: click Run, Step Over from the menu bar, or click Step Over in the tool bar, or hit F6)
4. After the program has terminated, close the debug perspective
5. Close account.eglpgm editor.

Section 3 - Creating Run-time Build Descriptors (Java Class and Java Wrapper)

 

Part of EGL’s power lies in its ability to generate code for many different runtime environments - Java for WebSphere and COBOL for CICS, IMS and z/OS batch. To enable you to control the generation of such code, EGL provides build descriptors. EGL’s Build descriptors are extremely flexible and can be used to define numerous aspects of how code generation should take place.  You will create two build descriptors now that you will actually use in Part2. "win-java" will define how to create a set of Java class files to perform the EGL logic. "wrapper" will define how to create a Java wrapper file which will provide a connector to our EGL server program.

1. In the Navigator view, double click on accountBuild.eglbld
2. In the Outline view, right-click on the accountBuild, and then select Add part…
3. The Add EGL Build Part wizard appears. Select Build Descriptor, and click Next.
4. On the Add EGL Build Part - Enter Build Descriptor Name page, in Name enter win-java, and then click Finish.
5. The win-java part is added to the Outline view, and the part opens ready for editing.
• set Build option filter drop down list to Java Target System (All). The table of build options changes to show only those relevant for generating java.
• set debug drop down to YES (select from drop down)
• set genProject to ATMWeb
• set genProperties to Yes
• set J2EE drop down to YES (select from drop down)
• set packageName to egl
• set sqlDB to jdbc/AIS
• set system drop down to WIN
6. Type Ctrl+S to save your changes
7. Check Show only specified options to reduce the list of options to those entered.  Compare to the list below:

 

An EGL generated Java wrapper is a set of classes that acts as an interface between a servlet or Java program, on the one hand, and an EGL generated program, on the other.  A java wrapper makes calling our EGL server quick and easy for a Java programmer.  It provides methods to call the server and methods to get and set the parameter values. The java wrapper will marshall parameter data between java objects and record structures (for generated COBOL programs), convert data between ASCII and EBCDIC, and handle all communication. When you request that a program part be generated as a Java wrapper, EGL produces a wrapper class for each of the following:  The generated program  Each record or structure that is declared as a parameter in that program  The Java wrapper build descriptor will have these options set: linkage points to a set of options that describe how to call the EGL server program nextBuildDescriptor adds the option settings in another build descriptor to the options defined in this build descriptor such as genProject, genProperties, packageName. system=JAVAWRAPPER causes the Java wrapper classes to be generated

1. In the Outline view, right-click on the accountBuild, and then select Add part…
2. The Add EGL Build Part wizard appears. Select Build Descriptor, and click Next.
3. On the Add EGL Build Part - Enter Build Descriptor Name page, in Name enter wrapper, and then click Finish.
4. The wrapper part is added to the Outline view, and the part opens ready for editing. In the editor,
• set Build option filter drop down to Java Wrapper(All). The table of build options changes to show only those relevant for generating java wrappers.
• set linkage to linkage
• set nextBuildDescriptor to win-java
• set system to JAVAWRAPPER
• select Show only specified options to condense the list of options and verify your entries
5. Type Ctrl+S to save your changes
6. Check Show only specified options to reduce the list of options to those entered.  Compare to the list below:

 

A linkage part defines how the generated java wrapper should invoke a called EGL program. A brief description of the options you will specify: location is the address where the server program executes package specifies the directory where the runtime Java classes can be found remoteBind=Generation causes the linkage information to be generated into the Java Wrapper, otherwise a linkage properties file must be provided at runtime remotePgmType indicates kind of program call conventions to use

1. In the Outline view, right-click on accountBuild, and then select Add part…
2. The Add EGL Build Part wizard appears. Select Linkage Options, and click Next.
3. On the Add EGL Build Part - Enter Build Descriptor Name page, set Name to linkage, and then click Finish.
4. The linkage part is added to the Outline view, and the part opens ready for editing. In the editor,
• click Add... which is at the bottom of the Calllink elements table
• set Program Name to account
• set Type to  remoteCall
• Type Ctrl+S to save your changes
• in Properties of selected callLink elements box
• set location to localhost
• set package to egl
• set remoteBind drop down to GENERATION
• set remotePgmType drop down to EGL
5. Type Ctrl+S to save your changes. Your linkage should look like:


6. Close the account.eglbld file.

 

By setting the default descriptors in the properties for a project, folder, or individual EGL program, then a build descriptor does not have to be specified for each generation request.

1. In Navigator view, right click on ATMServer and select Properties from the context menu
2. On the Properties window,
• select EGL Default Build Descriptors in left-hand list,
• set Target system build descriptor to win-java (ATMServer/accountBuild.eglbld)
• set Java debugging build descriptor to debug (ATMServer/accountBuild.eglbld)
• set Java wrapper build descriptor to wrapper (ATMServer/accountBuild.eglbld)
• Click OK