EGL Best Practices White Paper
EGL Best Practices
Purpose of this white paper: The purpose of this white paper is to outline a set of best practices
that should be used when developing Web Applications with Rational Application Developer/EGL.
Intended audience: Anyone developing Web Applications with RAD/EGL. This includes
developers in the following four categories;
1. Web Developers: Specifically the audience of web developers who do not have extensive
knowledge in Java and/or J2EE.
2. VisualAge Generator Migration: Web applications that have been developed using VAGEN
can be migrated to RAD/EGL. The application developers who maintain these applications
will need to understand the set of best practices that will increase their likelihood of success.
3. Informix i4GL Migration: Web applications that have been developed using the Informix
4GL can be migrated to RAD/EGL. The application developers who maintain these
applications will need to understand the set of best practices that will increase their likelihood
of success.
4. WebSphere Developer for zSeries (WDz) and WebSphere Development Studio ClientAdvanced Edition (WDSC-AE) COBOL Generation: Web applications developed with
WDz can generate COBOL that is deployed on the mainframe while Web applications
developed with WDSC-AE can generate COBOL that is deployed to iSeries. These developers
can also benefit from these EGL best practices.
From a development role point of view, the audience is as follows;
1. Development Executives: The white paper will be technical in nature and may not be suitable
for the development executive. However, any development executive should be able to glean
from browsing the content that using the product will be good for them.
2. Project Managers: The content of this white paper should be able to be used by technical
project managers to influence the way they manage their project.
3. Architects: No matter how RAD a development product becomes, there is always an
architecture component to an application. From these set of best practices, the architect should
be able to optimally set up their application architecture to maximize productivity and quality
of results.
4. Developers: In all development environments, there are good ways of implementing
functionality and poor ways. This white paper will provide a leg up for developers to get it
right the first time.
5. Testers: Knowing how things should be developed can help testers ensure that quality
requirements are met.
1
Company Confidential
EGL Best Practices White Paper
Artifacts produced: A white paper. For the purpose of an initial sizing, the white paper should not
exceed 25 pages.
Pre-requisites: Assuming that the audience is the set of roles described above, the only assumption is
that they have been introduced to EGL. Although after reading the white paper, someone may be more
accepting of EGL, the white paper is not intended to be the initial introduction to EGL.
2
Company Confidential
EGL Best Practices White Paper
Detailed Topics:
Part I – Conceptual Understanding of EGL
This section should provide a boilerplate to most or all white papers or articles on EGL. It will provide a consistent view of
EGL in a concise form. In the case where you have not read anything about EGL, this provides a bit of context and
background.
Overview (Sales and Marketing…Value Proposition)
 What is EGL?
o The Enterprise Generation Language (EGL) is a highly productive and intuitive 4th
Generation language (4GL) that simplifies complex runtimes and enhances quality by
reducing the amount of hand-written code needed for application development. With
EGL, you are able to deploy code that is optimally built for the target execution
platform without the need for changes to the source code.
3

How does EGL fit in the Rational/IBM Tools Offering?
o EGL is offered in all Rational Software Development Platform products and all
WebSphere Studio v5.1.2 products as well as WebSphere Studio Application Developer
Integration Edition v5.1.1.

What is the value proposition for using EGL?
o EGL as a language can be easily understood by application developers currently skilled
in a procedural language. When combined with the capabilities of the Java Server
Faces (JSF) framework, it enables traditional programmers to produce applications that
take advantage of developing for the Web environment while employing the traditional
programming practices they are already familiar with. EGL is also able to leverage
existing legacy executables via it’s’ ability to access callable executables on remote
systems such as the CICS environment on the mainframe.

EGL Productivity (versus hand-coding development)
o Although no productivity metrics are available, the high level of abstraction that EGL
gives in separating the EGL developer from the underlying datastores and the target
execution environment provide for an increase in developer productivity.

How do you use EGL (10,000 foot view)?
o EGL development is a component of the Rational Software Development Platform and
the WebSphere Studio tools. Specialized editors and views for EGL development are
contained in EGL “perspectives” in the development environment. Application
programs can be generated, from the EGL source code, which run on a multitude of
different execution platforms. The base EGL language is generated into either Java or
COBOL depending upon the target execution environment. Generation for the different
target environments is controlled by “build descriptor” files that control the generation
process. The original EGL source need not be changed to generate for a different target
execution platform.
Company Confidential
EGL Best Practices White Paper
Technical Introduction
 EGL Terms and Vocabulary
o Arrays
 Static – A collection of structure items, records or data items that is defined
with a specific number of elements.
 Dynamic Array – A declared collection of records with no specific number of
elements defined.
o Assignments – Used to copy or place data or values into an area of memory.
o Build Descriptor Parts – A part that contains information that controls the generation
process and is used to generate and prepare EGL output.
o CallLink Element – Specifies the type of linkage used in an EGL Call statement.
o Content Assist – During editing of an EGL source file, Content Assist presents possible
code additions, based upon the editing context, for the source file.
o DataItem Part – Defines an area in memory that cannot be subdivided. A dataItem
part is a standalone part unlike an item in a structure.
o DataTable Part – Composed primarily of these components:
 A structure with each top-level item defining a column.
 An array of values that are consistent with those columns. Each array element
defines a row.
o EGL build path and eglpath – Each EGL and EGL Web project is associated with this
path so the project can reference parts in other projects.
o EGL Editor – An editor in the WebSphere Studio environment that guides you with
Content Assist specific for EGL development.
o Expressions – A snippet of code that can be evaluated to produce a value.
o Form Group Part – The From Group part is a collection of forms and is generated as a
separate output.
o Form Part – A form part is an organization of data that is presented to the user. There
are 2 kinds of form parts. The first kind of form part contains data that is sent to a
display in a test application. The second kind of form part contains data that is sent to a
printer in any kind of EGL application.
o Function Part – A logical unit that either contains the first code in the program or is
invoked from another function. A Function Part can contain the following properties:
 Return Value – The data the Function Part returns to the caller.
 Parameters – Referenced memory allocated and passed by another logic part.
 Variables – Allocated memory that is local to the function.
4
Company Confidential
EGL Best Practices White Paper
o Library Part – Contains a set of functions, variables and constants that can be used by
programs, pageHandlers or other libraries. It is used to maximize reuse of common
code and values.
o Linkage Properties File – Used at Java runtime to give details on how a generated
Java program, or wrapper, calls a generated Java program in a different process.
o PageHandler Part – Provides data and services to a JSP and controls a user’s run-time
interaction with a Web page.
o Primitive Types – Each EGL primitive characterizes an area of memory and are of two
kinds:
 Character  CHAR – A single-byte character.
 DBCHAR – Double-byte character.
 HEX – Hexadecimal character.
 MBCHAR – Multi-byte character. Combination of single-byte and
double-byte characters.
 String – A field of varying length.
 UNICODE – Double-byte characters that conform to UTF-16 encoding.
5

Date & Time –
 DATE – Refers to a specific calendar date that has a fixed length of
eight digits.
 INTERVAL – A span of time that has a length from two to twentyseven digits.
 TIME – An instance in time that has a fixed length of six digits.
 TIMESTAMP – Refers to the current time and has a length ranging
from two to twenty digits.

Large Objects –
 BLOB – Binary Large Object with a length ranging from 1 byte to 2
gigabytes.
 CLOB – A Character Large Object with a length ranging from 1 byte to
2 gigabytes.
Company Confidential
EGL Best Practices White Paper

Numeric  BIGINT – An 8 byte area that stores an integer of up to 18 digits.
Equivalent to type BIN, length 8, no decimal places.
 BIN – Binary number.
 DECIMAL – Packed decimal numbers whose sign is represented by a
hex C, for a positive number, or a hex D, for a negative number, in the
right half of the rightmost byte.
 FLOAT – An 8 byte area that stores a double-precision floating-point
number with up to 16 significant digits
 INT – A 4 byte area that stores an integer of up 9 digits. Equivalent to
type BIN, length 4 with no decimal places.
 MONEY – Refers to currency amounts. Stored as DECIMAL values.
 NUM – Numbers whose sign is represented by a sign-specific hex value
in the left half of the rightmost byte. For ASCII, the value is 3 for a
positive number and 7 for a negative. For EBCDIC, the value is F for a
positive number and D for a negative.
 NUMC – Numbers whose sign is represented by a sign-specific hex
value in the left half of the rightmost byte. For ASCII, the value is 3 for
a positive number and 7 for a negative number. For EBCDIC, the value
is F for a positive number and C for negative.
 PACF – Packed decimal number whose sign is represented by a hex F
for a positive number or a hex D for a negative number.
 SMALLFLOAT – A 4 byte area that stores single-precision floatingpoint numbers with up to 8 significant digits – A 2 byte area that stores
an integer of up to 4 digits. Equivalent to type BIN, length 2, no decimal
places.
 SMALLINT – A 2 byte are that stores an integer of as many as 4 digits.
Equivalent to type BIN, length 2, no decimal places.
o Program Parts – This is the central logical unit when EGL is generated to COBOL or
Java. Programs always have a function called MAIN that represents the logic that runs
at program startup.
 Main Programs – The starting point of a new run unit or the target of a
Transfer statement.
 Called Programs – Programs that are called from other called or main
programs with the expectation of control returning to the calling program.
Called programs expect input parameters to be passed.
6
Company Confidential
EGL Best Practices White Paper
o Record Parts – Defines a series of memory areas. Records are used to manipulate data
internal to the program and to access data from disk storage.
 ALT_PCBRecord – This record type describes the layout of a Program Control
Block (PCB) that lets a COBOL program change the destination for an outgoing
message.
 BasicRecord – This type of record has a structure but no properties. It is used
for internal processing and cannot access disk storage.
 DB_PCBRecord – This type of record describes the layout of a Program
Control Block (PCB) that determines a COBOL program’s access to a DL/I
database.
 DLISegment – This record type holds the data to be read or written from a DL/I
database segment.
 GSAM_PCBRecord – This record type describes the layout of a Program
Control Block (PCB) that determines a COBOL program’s access to a simple
sequential dataset such as a tape file or SYSIN.
 IndexedRecord – Allows you to work with a file that is accessed by a key
value.
 IO_PCBRecord – This type of record describes the layout of a Program Control
Block (PCB) that lets a COBOL program communicate with a user through a
terminal.
 MQ Record – This record type is used to access an MQSeries message queue.
 PSBDataRecord – This is a fixed record type that is used to interact with the
system variable DLILib.psbData, which contains both the name of the runtime
PSB and an address with which that PSB is accessed.
 PSBRecord – This record type defines the structure of the runtime Program
Specification Block (PSB).
 RelativeRecord – This record type allows you to access a fixed length file that
uses an integer to represent the sequential position of a record in the file.
 SerialRecord – This type is used to sequentially access a file or dataset.
 SQLRecord – This record type is used to access relational databases.
 VGUIRecord – This record defines a generatable part which allows a
VGWebTransaction program to communicate with a specific Web page.
o Resource Associations – This is a part created in a Build Descriptor. The Resource
Association relates record parts to files and/or queues on the target platform.
o
7
Service - A set of operations that can be invoked by a client, which is an application
component that resides on the same or another platform. A service that you develop in
EGL can be deployed in either or both of these ways:
 EGL Service - Can be accessed from EGL code either directly or by way of a
TCP/IP connection. The client can be a program, handler, library, or other
service.
 Web Service - Can be accessed from code that runs in a Web application server.
The client can be a JSP, servlet, or Java™ client application; or a script or an
executable program written in any of several languages such as C++, Perl,
Visual Basic, or JavaScript™. Access is by way of an HTTP connection.
Company Confidential
EGL Best Practices White Paper
o System Libraries – The EGL System Libraries are a collection of shared functions and
variables that are available to all EGL programs, pageHandlers, services and custom
libraries.
 ConsoleLib – This system library provides console UI functionality to EGL
programs.
 ConverseLib – The Converse library system words perform operations on textbased screens in an EGL program.
 DateTimeLib – The date and time system variables allow you to retrieve the
system date and time in a variety of formats.
 DLILib – This system library provides system words for invoking DL/I
functions directly.
 J2EELib – The J2EE system words perform operations on Request and Session
attributes.
 JavaLib – This system library provide access to native Java programs and
classes.
 LobLib – The Large Object library functions perform operations on character
and binary large object data types.
 MathLib – The mathematical system words perform operations such as absolute
value, cosine, natural log and rounding.
 ReportLib – This system library establishes a framework containing all
components that are needed to interact the with JasperReports library.
 ServiceLib – This system library provides functions that allow EGL programs
to interact with Web Services.
 StrLib – The string handling system functions provide operations such as
comparing or concatenating strings.
 Syslib – The system library functions provide support for such items as
exception handling and status, native Java program access, options for file and
database access, and data conversion.
 VGLib – This system library provide functions for such operations as
determining the target system the program is executing on.
8
Company Confidential

9
EGL Best Practices White Paper
EGL Application Architecture
o EGL applications should be architected to follow the Model/View/Controller model of
application development. In the M/V/C model, the programming artifacts for the three
model components should be separate to ensure that, for example, there is no business
logic in the Controller portion of the model. Following the M/V/C model will ensure
that the EGL code constructed is as reusable as possible. For example, if properly
separated, EGL business logic and data access modules could be shared among both
Web development and Text User Interface development. The following diagram
diagrams how to separate the various application development components to promote
isolation and reuse of the various components.
Company Confidential

EGL Best Practices White Paper
EGL and JSF
o Java Server Faces (JSF) is a server side user interface component framework for Java
based Web applications. In other words, JSF is a set of tools and pre-built, standard
web-page components that can be used to develop EGL Web applications.
The JSF framework manages the user interface state across server requests and offers a
simple model for the development of dynamic web pages.
JSF components are graphical, consistent and easy to use. When combined with EGL,
they are implemented through simple drag & drop development, coupled with nonprocedural property setting.
Part II – EGL Best Practices
 Development Process
This section provides an overall view of the development process and how it relates to
EGL. We can refer to RUP and ensure to those that use RUP that EGL can play within the
RUP methodology.
 Relationship with RUP and iterative development
 When you should introduce the style elements of an application
 Parallel development
o One of the advantages of EGL development for Web pages is that the work of
developing the business logic and the work of designing and creating the JSP
Web pages can be performed in parallel.
The application developers have the ability to prototype and develop EGL
applications with a simple Faces JSP. The developer doesn’t need to worry
about what the Web page is to look like in the final product, at least during the
initial development of an application. The developer tests with a rudimentary
Faces JSP that contains all of the components necessary to verify an application
works.
While the application developer is creating and testing the business logic, others,
like graphic designers, can work on the styles to produce a style sheet that has
the “look and feel” that the Web page requires. This should ensure a common
design across all Web pages since one person or group is performing all of the
page design.
Once a final style has been created, it can be given to the EGL developers who
can then incorporate that Web page into their applications.
10
Company Confidential
EGL Best Practices White Paper
 Roles for a typical EGL project
o EGL Developer
 This individual understands procedural programming techniques. Is
also familiar with the datastores that are to be accessed from the EGL
applications being developed.
o Web Page Designer
 This individual understands the corporate standards for Web page
design and is able to build the necessary style templates for use in
EGL/JSF development.
o Javascript Developer
 This individual understands the Javascript language and how to modify
the Web page JSP source, if necessary, to enhance the functionality of
the Web application.
o J2EE Developer
 This individual understands the J2EE test environment. They are able to
assist with testing the EGL applications in the WebSphere Test
Environment. They are also able to assist in preparing the EGL
applications for deployment.
 Simplifying the initial steps - Using Cloudscape and the Test Container
o Initially, when starting development EGL prototypes or applications, you can
speed the development process by using the embedded Cloudscape database
and the built-in WebSphere Test Environment. The Cloudscape database gives
you a built-in relational database that can be used to develop SQL queries
before the development and production databases have been created and
populated. The WebSphere Test Environment gives you an instance of the
WebSphere Application Server that can be used for testing of web pages in the
development environment without having to deploy to a standalone WebSphere
Application Sever instance.

Team Development
This section provides guidelines on how you can set up your project for local and
distributed teams. Additionally, team development use cases will differ after the
application is deployed to production.
 Supported Source Control Systems
o Source Control is provided by the base Eclipse software and is not specific to
EGL. There are many supported Source Code Control Systems. They include:
 Aldon Lifecycle Manager Team Repository
 Aldon Lifecycle Manager Team Repository for iSeries
 Concurrent Versions System (CVS)
 Merant PVCS
 Perforce P4WSAD Team Provider
 Rational ClearCase/ClearQuest
 Serena ChangeMan Professional
11
Company Confidential
EGL Best Practices White Paper
 Specific functionality in a team development environment is dependant upon the Source
Control System being used. The descriptions below are a generalization and not
targeted at a specific Source Control System.
Source Code Control Systems follow one of two models:
Pessimistic Model
In the pessimistic model, files are checked out and locked while editing
is performed. After the updates are complete, the file is checked back in.
Optimistic Model
In this model, the file to be updated is obtained from the source
repository. Once editing is complete, the file is merged with other
developer’s work, if necessary and released back into the source
repository.
o Typically, team development starts with developers loading a project into the
workspace from the source repository. Projects must first be created in the
workspace before a version can be loaded from the repository.
When loading a project from a repository, it is preferable to load a version that
comes directly from a main code stream and not from a branch, if possible.
If it is necessary to branch from the main code stream, minimize the depth of the
branching to try to keep a stable, unified branch.
During development, version often rather than making many changes to the
code and then versioning when all updates are complete. You can synchronize
with the source repository at any time and commit changes made to files in the
project or projects under development. It’s much more difficult to merge
changes into a code stream when there are many changes to reconcile. This is
especially true if there are many developers maintaining code in a project.
o If there are different assigned roles in the team development environment, such
as a class of developers that only deal with pages and not pageHandlers, then
you need to ensure that your permissions and authorities in the source
repository are set appropriately, if supported by the Source Control System
being used. This will prevent inappropriate updates to development artifacts by
unauthorized developers. It can also prevent inadvertent updates being made.
It’s also important to consider team roles when defining EGL projects. If there
are different developers working on SQL access vs. business logic for example,
then a project structure can be created to isolate these development efforts. To
accommodate the above situation, you could create a project to contain the
functions and records layouts needed for SQL access and different project for
the business functions thereby minimizing the number of developers working on
a single project.
12
Company Confidential
EGL Best Practices White Paper
o For post-Production code changes relating to bug fixes, you will need to create
a branch off of the existing production mainline in the source repository. As
with normal team development, version any changes back in to the production
mainline as soon as possible. This will ensure that developers performing
incremental fixes on the production mainline will always retrieve the current
copy of the productions source code – complete will all prior bug fixes.

Prototyping
This section provides guidelines on how you can use EGL to quickly prototype your
application in an iterative development methodology and move the prototype to production
code without having to throw away what you have done in the prototype.
 Prototyping without a database
o Initial program design can start independent of any databases in place. Start by
performing screen or page design and application flow. Screens and pages can
be created with default text placed in the fields to give reviewers an opportunity
to see what the applications would look like in every day use.
Even at this early stage, it is important to devote the time necessary to develop
the prototype with a well planned, modular design.
 Prototyping with a lightweight database (Cloudscape) and lightweight app server (test
container)
o As the prototype begins to mature, rudimentary database access can be
provided. The Rational Software Development Platforms come with a
lightweight Cloudscape database. Database tables can be quickly created in
Cloudscape to provide database access to the early prototype. Add records to
the prototype and begin creating the database access functions required.
There is a utility, CloudView that allows you to administer the embedded
Cloudscape databases. The executable for CloudView is found in the following
location:
Radinstdir\runtimes\base_v6\cloudscape\bin\embedded\cview.exe
If developing a J2EE application, the built-in WebSphere Test Environment
(WTE) can be used as the application server for server testing. Define a new
test server and create all necessary datasources required by the prototype
application.
 Stubbing out application functions.
o As development of the prototype continues, identify the functions necessary to
satisfy the business requirements of the application. It’s not necessary to fully
flesh out the functions at this point in time. After all, it’s just a prototype.
Create the identified functions and either leave them empty or place a minimal
amount of logic in them to simulate real-world execution.
 Moving beyond the prototype
o At the completion of a successful prototyping exercise, you will have a
prototype that has been designed with modular programming practices in mind.
13
Company Confidential
EGL Best Practices White Paper
It contains (most) all of the function stubs that are required, rudimentary
database access and the screens or web pages that have been approved by the
end-users. You can now take this prototype and continue the process of
developing a production-ready application. You can switch the Cloudscape
database access to the true database access for on-going testing. The function
stubs that have been created can now be fully realized and all of the required
business logic put in place.

Application Architecture
This section provides guidelines on how you can set up your application architecture. Even
though you implement with a RAD/EGL product, you still need to provide an application
architecture. EGL can help you do this. For example, you may want to isolate a set of
commonly used functions in an EGL library rather than burying the functions in a page
handler.
Some sub-topics include;
 How can validation functions be re-used?
o Validation functions, or any commonly used functions, can be re-used by
placing them in an EGL Library member. Functions, and other artifacts, that
are placed in Library Members are available to all programs and page handlers
in the project.
You can also create libraries of functions and artifacts that are available to
programs and page handlers across multiple projects in a workspace. Include
artifacts from other projects by modifying the EGL Build Path in a project
Properties.
If you have artifacts that are common across multiple application development
projects then create a shared artifacts, or common-code, project. You can then
keep all common code in one shared project.
 How to integrate with external 3rd party packages such as report writers and business
rules engines?
o If no callable interface exists, it may be possible, in the Java environment, to
access the 3rd party packages by utilizing the Java class integration capabilities
of EGL. From EGL, you have the ability to access both system (static) and
custom Java classes (creating new instances).
o Java class integration
14
Company Confidential
EGL Best Practices White Paper
 How can you partition your application to package up functionality that can be re-used?
o Applications should be divided to make the maximum use of reusability. For
example, you can create an EGL project with a set of services in the form of
EGL functions. These services can then be re-used with any number of
departmental applications and shared across many projects.
A typical example of one such function is a login service. You don’t want every
department to create their own separate login functionality, so you write it once
and make it available to all thereby increasing productivity and reducing test
time by not having to test a function that’s already been tested.

EGL Coding
This section provides guidelines on how you can set up your project for local and
distributed teams. Additionally, team development use cases will differ after the
application is deployed to production.
Sub topics include;
 EGL Coding Value Proposition
o Language richness
 The EGL language is very rich in its’ set of features and capabilities.
EGL is capable of accessing many different types of datastores from
relational databases to DL/I databases as well as MQSeries queues and
serial files. EGL can also be used to construct applications for many
different runtime environments from the Web to batch mainframe
programs.
o Language abstraction
 EGL maintains a high-level of abstraction from the target execution
platforms it executes on and the datastores it accesses.
For target execution platform support, platform specific information is
defined in Build Descriptors thereby keeping platform specific
information out of the EGL code.
For access to datastores, specific datastore information is defined in the
Build Descriptors and record definitions. The EGL code uses the same
data access verbs no matter what the underlying datastore happens to be.
 The following is the EGL implementation pattern for EGL Web applications.
o Add EGL Data and Functions to EGL library,
o Create JSF Page
o Realize the page with JSF controls
o Bind JSF controls with EGL Data Elements
o Implement and bind EGL page handler actions with JSF controls
o Deploy to Server and Test
Notice the implementation pattern begins with creation of the EGL code first, not
the JSF Page. You can minimize the number of naming problems between controls
on a JSF page and data elements and functions in a pageHandler if you begin by
creating EGL artifacts first.
15
Company Confidential
EGL Best Practices White Paper
 Encapsulation/Scoping with EGL
o One of the difficulties of application is knowing where to code certain artifacts.
When developing EGL Web applications, which is based on the
Model/View/Controller (M/V/C) model, it is important to, as closely as possible,
follow that model.
EGL pageHandlers, which are the Model part of M/V/C, should contain no logic
except that which is needed to control the “View” part of M/V/C, which is the
JSF page. Data access and business logic functions should be coded in EGL
libraries. These library artifacts can then be called from the pageHandlers.
When coding the data access functions, the records associated with the data
access logic should be placed in the same EGL library file as the function
performing the I/O.
When creating the library functions for business logic and data access, we also
need to keep in mind what the scope of the code being developed is. If we are
developing logic that will only be used by a single project, then those functions
should be defined in the project being developed. If, however, the functions
being developed may be reused by other projects, then a “global” project should
be created to contain those shareable artifacts. If a common artifacts project is
created, then other developers can include the common code in their
workspaces.
If there is a common project created, there should be a single contact for
changing the contents of that project. It is not advisable, from a security and
auditing standpoint, to have many developers with the authority to change
common artifacts.
16
Company Confidential
EGL Best Practices White Paper
 Naming Conventions. The goal of EGL naming conventions is to apply a simple and
consistent method for naming EGL artifacts in the development workspace. It is hoped
that by using a common naming convention across all EGL development groups, the
artifact names in the workspace will be have a consistent look and be more easily
recognizable by individuals not involved with the initial construction of the EGL
programs and artifacts. Naming conventions should be periodically reviewed and
should be updated as needed to ensure the conventions stay applicable and relevant to
the current development environment.
o Project Names
 Project names in the workspace should be constructed as to be selfdocumenting in their description. The system acronym should also be
included as a part of the name. The name should differentiate between
Web, terminal and batch type of project.
The name should also include an identifier to easily differentiate projects
from other artifacts in the workspace. Project names should start with a
lowercase letter and be in camel case. For example:
thisIsMy[system-name]DBUpdate[type identifier][project identifier]
Valid type identifiers are:
Web
Batch
Text
TUI
Valid project identifiers are:
Project
Prj
Proj
17
Company Confidential
EGL Best Practices White Paper
o Package Names
 When creating new packages to contain EGL artifacts, all packages
should be created under the EGLSource folder as seen in the Project
Navigator view. Package names should be unique in a project. You
achieve uniqueness in package names by making the initial part of the
package name an inversion of your organization’s Internet domain name.
For example, the IBM domain name is “ibm.com”, and the EGL
packages begin with “com.ibm”. By doing this, you gain some
assurance that the names of Web programs developed by your
organizations will not duplicate the names of programs developed by
another organization and can be installed on the same server without
possibility of a name collision.
The package name should include the system acronym as a part of the
name. The name should also include an identifier to easily differentiate
packages from other artifacts in the workspace. The package names
should start with a lowercase letter and be in camel case. For example:
[internet name inversion][system acronym][package identifier]
Valid package identifiers are:
Package
PKG
Pkg
o Program Names
 Program names must be unique so as to prevent duplicate name
collisions with other programs in the same project. The program name
should include the system acronym for the program under development.
The name should also include an identifier to easily differentiate
programs from other artifacts in the workspace. Program names should
start with a lowercase letter and be in camel case. For example:
thisIsMy[system acronym]DBUpdate[program identifier]
Valid program identifiers are:
Program
Prog
PGM
Pgm
18
Company Confidential
EGL Best Practices White Paper
o Faces JSP Names
 Faces JSP names must be unique to prevent naming collisions with other
JSPs in the same EGL project. Faces JSP names should also include the
system acronym for the JSP under development and convey the purpose
of the JSP. The name should also include an identifier to easily
differentiate JSPs from other artifacts in the workspace. Faces JSP
names should start with a lowercase letter and be in camel case. For
example:
thisIsMy[system acronym]EmployeeUpdate[JSP identifier]
Valid JSP identifiers are:
Page
JSP
o Page Handler Names
 Page handlers require no special naming since they are generated from
the Faces JSP by the EGL/JSF tooling in the development environment.
o Library Package Names
 Library Packages are simple packages created to hold EGL Library
Members. They should be created under the EGLSource folder in the
Project Navigator view. If multiple Library packages are created, the
package names must be unique to prevent naming collisions with other
Library Packages and should include the system acronym for the system
under development. The library package names should start with a
lowercase letter and be in camel case. For example:
My[system acronym]EGLLibraries
o Library Member Names
 Library member parts contain sets of functions, variables and constants
that can be used by programs, page handlers or other libraries. Library
member names must be unique to prevent naming collisions with other
library members in the same EGL project. Library names should also
include the system acronym for the library under development and
convey the general purpose of the library member. The library member
name should also include an identifier to easily differentiate library
members from other artifacts in the workspace. The library member
names should start with a lowercase letter and be in camel case. For
example:
thisIsMy[system acronym]Customer[lib member identifier]
Valid library member identifiers are:
Library
Lib
19
Company Confidential
EGL Best Practices White Paper
o ALT PCB Record Names
 ALT_PCBRecords are used to describe the layout of a PCB that lets a
COBOL program change the destination for an outgoing message. ALT
PCB record names must be unique to prevent workspace errors
concerning ambiguous records or record items. The name of ALT PCB
records should be constructed to include the PCB name for readability
and identification of the PCB being accessed. The ALT PCB record
names should also include an identifier to easily differentiate ALT PCB
records from other record types. The ALT PCB record names should
start with a lowercase letter and be in camel case. For example:
thisIsMy[pcb name][record identifier]
Valid record identifiers are:
AltPCBRecord
APCBRecord
AltPCBRec
APCBRec
o Basic Record Names
 Basic Records are essentially working storage records. They have a
structure, but no properties. They are used for internal processing and
cannot access data storage. If unique to a specific EGL program, that
program name should be a part of the record name. If the record is
common to a project, the project name should be a part of the record
name. Basic record names must be unique to prevent workspace errors
concerning ambiguous records or record items. The Basic record name
should also include an identifier to easily differentiate Basic records
from other record types. The Basic record names should start with a
lowercase letter and be in camel case. For example:
miscStorageFields[optional program name][record identifier]
The valid record identifiers are:
BasicRecord
BasicRec
BasicRcd
BasRecord
BasRec
BasRcd
WsRecord
WSRec
WSRcd
20
Company Confidential
EGL Best Practices White Paper
o DB PCB Record Names
 DB_PCBRecords are used to describe the layout of a PCB that lets a
COBOL access a DL/I database. DB PCB record names must be unique
to prevent workspace errors concerning ambiguous records or record
items. The name of DB PCB records should be constructed to include
the DL/I database name for readability and identification of the database
being accessed. The DB PCB record names should also include an
identifier to easily differentiate DB PCB records from other record types.
The DB PCB record names should start with a lowercase letter and be in
camel case. For example:
thisIsMy[database name][record identifier]
Valid record identifiers are:
DBPCBRecord
DBPCBRec
o DLI Segment Record Names
 DLI Segment records are used to hold data to be read or written to a
DL/I database. DLI Segment record names must be unique to prevent
workspace errors concerning ambiguous records or record items. The
name of DLI Segment records should be constructed to include the DL/I
database name for readability and identification of the database being
accessed. The DLI Segment record names should also include an
identifier to easily differentiate DLI Segment records from other record
types. The DLI Segment record names should start with a lowercase
letter and be in camel case. For example:
thisIsMy[database name][record identifier]
Valid record identifiers are:
DLIRecord
DLIRec
DLISegmentRecord
DLISegmentRec
DLISegRecord
DLISegRec
21
Company Confidential
EGL Best Practices White Paper
o GSAM PCB Record Names
 GSAM_PCBRecords are used to describe the layout of a PCB that
determines a COBOL program’s access to a simple sequential dataset.
GSAM PCB record names must be unique to prevent workspace errors
concerning ambiguous records or record items. The name of GSAM
PCB records should be constructed to include the database name for
readability and identification of the datastore being accessed. The
GSAM PCB record names should also include an identifier to easily
differentiate GSAM PCB records from other record types. The GSAM
PCB record names should start with a lowercase letter and be in camel
case. For example:
thisIsMy[database name][record identifier]
Valid record identifiers are:
GSAMPCBRecord
GSAMPCBRec
GSAMRecord
GSAMRec
GRecord
GRec
o Indexed Record Names
 An indexed record lets you work with a file that is accessed by a key
value, which identifies the logical position of a record in the file.
Indexed record names must be unique to prevent workspace errors
concerning ambiguous records or record items. The name of Indexed
records should be constructed to include the file name for readability and
identification of the file being accessed. The Indexed record names
should also include an identifier to easily differentiate Indexed records
from other record types. The Indexed record names should start with a
lowercase letter and be in camel case. For example:
accountsPayable[record identifier]
The valid record identifiers are:
IndexedRecord
IndexedRec
IndexedRcd
IndexRecord
IndexRec
IndexRcd
IdxRecord
IdxRec
IdxRcd
22
Company Confidential
EGL Best Practices White Paper
o IO PCB Record Names
 IO_PCBRecords are used to describe the layout of a PCB that lets a
COBOL program communicate with a user through a terminal. IO PCB
record names must be unique to prevent workspace errors concerning
ambiguous records or record items. The name of IO PCB records should
be constructed to be descriptive of their function for readability and
identification. The IO PCB record names should also include an
identifier to easily differentiate IO PCB records from other record types.
The IO PCB record names should start with a lowercase letter and be in
camel case. For example:
thisIsMyTerminal[record identifier]
Valid record identifiers are:
IOPCBRecord
IOPCBRec
o MQ Record Names
 MQ records let you access an MQSeries message queue. MQ record
names must be unique to prevent workspace errors concerning
ambiguous records or record items. The name of MQ records should be
constructed to include the queue name for readability and identification
of the queue being accessed. The MQ record names should also include
an identifier to easily differentiate MQ records from other record types.
The MQ record names should start with a lower case letter and be in
camel case. For example:
myQueueName[record identifier]
The valid record identifiers are:
QueueRecord
QueueRec
QueueRcd
MQRecord
MQRec
MQRcd
23
Company Confidential
EGL Best Practices White Paper
o PSB Data Record Names
 PSBDataRecords are used to interact with the system variable
DLILib.psbData. PSBData record names must be unique to prevent
workspace errors concerning ambiguous records or record items. The
name of PSBData records should be constructed to include the PSB
name for readability and identification of the PSB being accessed. The
PSBData record names should also include an identifier to easily
differentiate PSBData records from other record types. The PSBData
record names should start with a lowercase letter and be in camel case.
For example:
thisIsMy[psb name][record identifier]
Valid record identifiers are:
PSBDataRecord
PSBDataRec
PSBDRecord
PSBDRec
o PSB Record Names
 PSB Records are used to describe the structure of the runtime PSB and
includes a series of PCB records. PSB record names must be unique to
prevent workspace errors concerning ambiguous records or record items.
The name of PSB records should be constructed to include the PSB name
for readability and identification of the PSB being accessed. The PSB
record names should also include an identifier to easily differentiate PSB
records from other record types. The PSB record names should start
with a lowercase letter and be in camel case. For example:
thisIsMy[psb name][record itdentifier]
Valid record identifiers are:
PSBRecord
PSBRec
24
Company Confidential
EGL Best Practices White Paper
o Relative Record Names
 A Relative record lets you work with a dataset whose records have the
following properties:


Are fixed length
Can be accessed by an integer that represents the sequential
position of the record in the file
Relative record names must be unique to prevent workspace errors
concerning ambiguous records or record items. The name of Relative
records should be constructed to include the file name for readability and
identification of the file being accessed. The Relative record names
should also include an identifier to easily differentiate Relative records
from other record types. The Relative record names should start with a
lowercase letter and be in camel case. For example:
accountsPayable[record identifier]
Valid record identifiers are:
RelativeRecord
RelativeRec
RelativeRcd
RelRecord
RelRec
RelRcd
o Serial Record Names
 Serial records let you access a sequentially accessed file or dataset.
Serial record names must be unique to prevent workspace errors
concerning ambiguous records or record items. The name of Serial
records should be constructed to include the file name for readability and
identification of the file being accessed. The Serial record names should
also include an identifier to easily differentiate Serial records from other
record types. The Serial record names should start with a lowercase
letter and be in camel case. For example:
accountsPayable[record identifier]
The valid record identifiers are:
SerialRecord
SerialRec
SerialRcd
SerRecord
SerRec
SerRcd
25
Company Confidential
EGL Best Practices White Paper
o SQL Record Names
 SQL Records let you access data stored in relational database tables.
SQL Record names must be unique to prevent workspace errors
concerning ambiguous records or record items. The name of SQL row
records should be constructed to include the table name, or names in the
case of a join record, for readability. The SQL Record names should
also include an identifier to easily differentiate SQL records from other
record types. The SQL Record names should start with a lowercase
letter and be in camel case. For example:
customerTable[record identifier]
The valid record identifiers are:
SQLRecord
SQLRec
SQLRcd
TableRecord
TableRec
TableRcd
TabRecord
TabRec
TabRcd
o VG UI Record Names
 VG UI Records allow VG Web Transaction programs to communicate
with a specific Web page. VG UI record names must be unique to
prevent workspace errors concerning ambiguous records or record items.
The name of VG UI records should be constructed to include the
program name for readability and identification of the Web Transaction
program being accessed. The VG UI record names should also include
an identifier to easily differentiate VGUI records from other record
types. The VG UI record names should start with a lowercase letter and
be in camel case. For example:
thisIsMy[program name][record itdentifier]
Valid record identifiers are:
VGUIRecord
VGUIRec
26
Company Confidential
EGL Best Practices White Paper
o Arrays
 Array names must be unique in the context to which they are defined,
whether they are global to a program, or project, or local to a specific
function. The array name should be descriptive of the contents of the
array and include an identifier to differentiate the array from other item
types. The array name should start with a lowercase letter and be in
camel case. For example:
nameAddress[type identifier]
The valid type identifiers are:
Array
List
27
Company Confidential
EGL Best Practices White Paper
o Primitives
 Items that are defined as primitives must be unique in the context to
which they are defined, whether they are global to a program, or project,
or local to a specific function. The item name should be descriptive of
the contents of the item and include an identifier to indicate what type of
primitive is being used. The item name should start with a lowercase
letter and be in camel case. For example:
updateReturnCode[type identifier]
The valid type identifiers are:
Bint
Bin
Blob
Char
Clob
Date
Dec
Dt
DBChar
Dec
Decimal
Float
Flt
Hex
Int
Interval
Inter
MBChar
Money
Mny
Num
Numc
Packf
Sint
SmallFloat
SmallFlt
SmFloat
SmFlt
SmallInt
SmInt
String
Str
Time
Tm
Unicode
Uc
28
Company Confidential
EGL Best Practices White Paper
 Using components across applications
o Packaging
o Calling
o Importing
 Generation Options and Build Descriptors.
o Normally, when an EGL member is saved in the EGL editor, the member is
validated and the Java code generated. One exception to this is for Library
Members. Upon saving a Library Member, an explicit generate must be
performed to generate the Java code. The generate can be performed by rightclicking on the member to be generated in the Project Navigator view and
selecting “Generate” from the context sensitive menu that appears.
When generation occurs, the Default Build Descriptor defined for the artifact(s)
being generated will be used as input to the generation process.
It is useful to maintain more than 1 Build Descriptor file. Usually you have at
least 2 Build Descriptors – one for building applications for the development
environment and a second Build Descriptor for building applications for the
target execution environment.
To keep developers from having to build their own Build Descriptors, create a
project that has nothing but Build Descriptors in it. This “master” Build
Descriptor project can contain the necessary Build Descriptors for all target
execution environments, database configurations and resource associations. If a
developer requires a change or addition to a build descriptor, those changes
should be made in the master copy of the Build Descriptor project and redistributed to all developers.
 Creating consistent code
o Using Templates
 Use HTML Page Templates (HTPL) as much as possible to give the
Faces JSP pages under development a common, consistent “look and
feel”. This also aids in developer productivity since a common look
doesn’t need to be created from scratch for each developer. Page design
can be a time consuming endeavor especially if the page contains
multiple frames.
29

When creating page templates, however, the number of artifacts on the
template should be kept to a minimum. Only place artifacts on the
template that will be used by all of the web pages under development,
since any artifact placed in the template will be propagated to all pages
using the template.

Page Templates are placed in the WebContenttheme folder of the EGL
Web project.
Company Confidential
EGL Best Practices White Paper
o Using code snippets
 Code snippets are small, scripted events that can be added to a tag in a
Faces JSP file. Snippets can be added from either the Snippets view or
the Quick Edit view. The advantage of adding Snippets from the Quick
Edit view is that the list of Quick Edit snippets changes based on the
events. The Quick Edit view only shows snippets that are relevant to the
current event.
o Content Assist
 Using Content Assist is a very good method of reducing the number of
keystrokes it takes to enter EGL code. Content Assist proposes
information that you can add to your source file. With just a keystroke
or two, you can complete the name of a part, variable or function, or can
place the outline of a part into your source file.
You also have the ability to create your own code templates for Content
Assist. This is helpful if you find regularly used code constructs that
aren’t currently provided by Content Assist.
o Faces JSP Design Considerations
 When placing artifacts on a JSP page, first drop an HTML table on the
form. HTML has no native alignment capabilities. To work around this
deficiency, use the cells in the HTML table to align the different controls
dropped on the page.
30

Try to avoid using the “Add controls to a page” method to get artifacts
on a Faces JSP page. It is more straightforward to complete the EGL
coding first and then drag the various variables and actions on to the
page. The main advantage of this is it removes the possibility of
dropping a control on to a page and then changing the names in the EGL
code. This situation causes test server run-time “Can’t find Bean” errors.

To separate the View from the Controller in the Model/View/Controller
development model, whenever possible, create a BasicRecord that is
dragged on to the Page Designer instead of dragging sqlRecords. It is
very rarely that the database record will exactly match the data that is
required on the page. It is more likely that the display data is a
combination of data gathered from various locations/calculations.

When possible, create programs, functions, services, etc. before creating
the pageHandlers. If the peripheral EGL artifacts are created first, then
Content Assist can be used more effectively when creating the necessary
Call statements in the pageHandlers.
Company Confidential
EGL Best Practices White Paper

PageHandlers are the “Controller” part of the Model/View/Controller
development model. So, to follow the rules of the M/V/C model,
pageHandlers should not contain business logic or data access logic.
PageHandlers should contain only routines that interact directly with the
JSF user interface.
o SQL Considerations
 Use SQL Retrieve to create SQL database records instead of handcoding the record. This will not only be much more productive in terms
of time, but will prevent from SQL table columns being incorrectly
coded.

For readability and to simplify future maintenance, limit the use of large,
complex SQL queries. Smaller, more modular queries are easier to
decipher and maintain by those unfamiliar with the program.

If it is necessary to create complex SQL queries, it can be beneficial to
“sample” the query in a command line tool. This way, the accuracy of
the proposed query can be tested in a standalone environment instead of
using the EGL debugger to determine if the query results are accurate.
This also applies when using dynamic SQL in EGL. Test the proposed
query outside of EGL first.
o DataTables
 In EGL, a dataTable is a structure with each top-level item defining a
column and an array of values that are consistent with those columns.
Each element of the array defines a row in the dataTable.
Some dataTables types are used for runtime validation. Specifically,
they are used to hold data for comparison against form input. A
dataTable can be defined for 3 types of validation:
 matchValidTable – The user’s input must match a value in the
first dataTable column.
 matchInvalidTable – The user’s input must be different from
any value in the first dataTable column.
 rangeChkTable – The user’s input must match a value that is
between the values in the first and second column of at least one
dataTable row.
Another type of dataTable is the msgTable. DataTables of this type are
used to hold runtime messages used by the EGL program.
The final type of dataTable is the basicTable. This table can be used to
contain static information a program might use. For example, a list of
valid state codes could be stored in a dataTable and read by the EGL
program running.
31
Company Confidential
EGL Best Practices White Paper
o General
 When creating new workspaces, create the workspaces under a parent
folder instead of creating them off of the root directory. This will keep
the files associated with a workspace together in one easily identified
location.

Use consistent source code formatting to improve readability of the EGL
code. Use the tab key to indent and align code. Don’t combine multiple
EGL statements on one source code line.

Always include comments in the code to document what is taking place
in the EGL source. This is especially necessary if the code is doing
something unique that may not be easily understood by developers
performing maintenance on the EGL code in the future.
e
 Using Data Items vs Primitives
o A dataItem part defines an area of memory that cannot be subdivided. It is a
standalone part, not like a structure field in a fixed structure such as a record.
The use of dataItems depends on how strict you want to be with a data
dictionary approach. DataItems can be used when a definition of an area in
storage needs to be shared between projects and that definition needs to be
consistent between projects. The dataItem would then be defined in a common
parts library in order to be available to all programs, pageHandlers and functions
that require it.
Primitives on the other hand can be defined as working storage fields and used
for basic records in a specific program. Primitives can be used in place of
dataItems if a strict adherence to a data dictionary approach is not used.
 Using Programs vs Libraries vs Services
o Programs are more like what a COBOL programmer is used to, in terms of one
entry point and one set of parameters. Programs can be invoked remotely (i.e.
on CICS or a different Java system) but functions in the programs cannot be
invoked directly.
Libraries contain functions that can be invoked directly without a parameter list,
as opposed to programs which, as stated before, only has one entry point.
Services can be invoked remotely like a program as well as be invoked directly,
like a library, or can be invoked as a true Web service.
Unlike a Service or a Program, libraries cannot be invoked remotely.
Ultimately, it is probably more a matter of style that determines which artifact
type to use. However, libraries and Services provide the most flexibility.
32
Company Confidential
EGL Best Practices White Paper
 Validation
o Data validation can be performed in several places such as libraries, page
handlers, on the client (javascript), declarative in JSF, declarative in EGL Data
Items. If the validation functions can be shared between multiple applications,
then the validations should be placed in EGL libraries to promote code reuse.
If you wish the validation to take place on the client (browser) side, then the
validations should be created in JavaScript in the JSF or placed in the JSF as
declaratives in the attributes of the JSP artifacts.
Lastly, some validations can be declared when an EGL data item is created.
This can be done, for example, for decimal numbers. When the decimal is
defined, a valid range can be defined as a part of the properties of the primitive.
 Error Handling
o It is very important that the EGL code is written to provide the maximum level
of error detection and exception handling. In order to provide a high-level of
exception handling, perform the following acts:
 Whenever performing any input/output processing, against either files,
queues or databases, ensure that the code performing the I/O is in a
Try/On Exception block. This will ensure that all soft I/O errors are
captured.

Set sysVar.handleHardIOErrors = 1. Setting this variable will allow the
program to catch and handle hard I/O errors that would normally
abnormally terminate program execution.
 Using multiple databases from EGL
o Workbench Properties
o Connecting at runtime
33
Company Confidential
EGL Best Practices White Paper
 Debugging
o Debugging your EGL code in the EGL debugger
 The EGL debugger can be very helpful in identifying execution errors
while still in the development environment. The debugger allows you to
step through the execution of the EGL code while interrogating the
values in records and variables during execution. You can also change
the values of fields and variables during the debug execution. This is
helpful in allowing you to test various pieces of logic, such as error
processing that would normally not be executed during a normal run of
an application.
For J2EE applications, the test server must be enabled to run the EGL
debugger. To do this, stop the test server if it is running and right-click
on the server entry in the Servers view. Select “Enable/disable EGL
debugging” from the context sensitive menu that appears. After enabling
EGL debugging, start the test server in debug mode. You can then
choose the option to “Debug on Server” as opposed to “Run on Server”.
For non-J2EE applications, there is no test server to worry about so all
one needs to do is execute the application in the EGL debugger. To do
this, right-click on the starting program in a run unit and select “Debug
EGL Program” from the context sensitive menu that appears.
o Tracing generated Java code
 There are instances when execution results are not what was expected,
but it is not possible to determine the problem when executing in the
EGL debugger. Runtime tracing can be enabled for EGL applications by
setting the value of the following runtime properties:
 vgj.trace.type
o Valid entries are:
-1 - Trace all
0 - Trace nothing
1 - General trace including function invocations and
call statements.
2 - System functions that handle math
4 - System functions that handle strings
16 - Data passed on a Call statement
32 - Linkage options used on a Call statement
128 – Jdbc I/O
256 – File I/O
512 – All properties except vgj.default.password
 vgj.trace.device.option
o Valid entries are:
1 - Write trace to System.out
0 - Write trace to System.err
2 - Write trace to file specified in
vgj.trace.device.spec. This is the default.
34
Company Confidential
EGL Best Practices White Paper

vgj.trace.device.spec
o Specifies the full path/filename of the trace output file.
Needed if vgj.trace.device.option is set to 2.
For J2EE applications, these properties are found in the Variables tab of
the web.xml file. The web.xml file can be found in the
WebContentWEB-INF folder of the Project Navigator view.
For non-J2EE applications, these runtime properties are found in the
rununit.properties file or, in the case of WebSphere Studio v5.1.2 users,
in the vgj.properties file. This file is produced by generating the EGL
code, provided the Build Descriptor setting for genProperties is set and
can be found in the Java ResourcesJavaSource folder of the Project
Navigator view.

Keyboard Shortcuts
o The following keyboard shortcuts are available in the EGL editor.
Key Combination
CTRL+/
CTRL+\
CTRL+A
CTRL+C
CTRL+F
CTRL+H
CTRL+K
CTRL+S
CTRL+V
CTRL+X
CTRL+G
CTRL+L
CTRL+Y
CTRL+Z
CTRL+Shift+A
CTRL+Shift+K
CTRL+Shift+N
CTRL+Shift+P
CTRL+Shift+R
CTRL+Shift+S
CTRL+Shift+V
CTRL+Shift+Z
CTRL+Space
F3
Tab
35
Function
Comment
Uncomment
Select all
Copy
Find
Search
Find next
Save
Paste
Cut
Generate
Go to a specific line
Redo
Undo
Add an explicit SQL statement to an EGL I/O statement that has
an implicit statement.
Find previous
Access the Open Part dialog
Construct an EGL prepare statement and the related get, execute
or open
Use the retrieve feature to create or overwrite items in an SQL
record part
Show the current file in Project Explorer
View and validate the SQL statement that is associated with an
EGL I/O statement and perform related actions
Use the Source Assistant
Get Content Assist
Open the file that contains the part whose name is highlighted
Indents text to the next tab stop
Company Confidential
EGL Best Practices White Paper

Page Design and Implementation
This section provides a basic understanding of the concepts and best practices involved
with implementing page design with EGL and JSF. It is not a ‘how to design web pages’.
It is a ‘how to optimize your page implementation by using JSF and EGL’.
o JSF Concepts – JSF is a development framework that provides a set of standard,
reusable GUI components. It is used for building web application interfaces. When
combined with EGL, you have a robust, powerful application development environment
that allows traditional programmers to write programs in a procedural language that is
easy for them to understand with the user interface targeted for the Web.
JSF follows the architecture shown in the following diagram:
At runtime, the Application Server contains both the View and Controller
components of the Model/View/Controller model. A third tier, which can either be
inside or outside of the Application Server contains the Model.
All JSF and EGL processing takes place on the server side. There are, however,
options for some rudimentary input validation taking place on the client side in the
page JSP. If errors are found in the JSP-defined validation, the request is not
submitted to the server and no JSF or EGL processing takes place.
36
Company Confidential
EGL Best Practices White Paper
o
The Page Handler
 An EGL pageHandler part controls a user’s runtime interaction with a Web page by
providing data and services to a JSF JSP. When you initially create a Faces JSP page,
an EGL pageHandler page is automatically create for you. The pageHandler is placed
in a package named “pageHandlers” under the EGLSource folder in the Project
Navigator. The pageHandler is named the same as the Faces JSP page with an
extension of .egl.
Optionally, the pageHandler EGL part can be manually created first. In this scenario,
the system will add the corresponding Faces JSP to the workspace if it doesn’t already
exist.
The pageHandler is the “Controller” part of the Model/View/Controller development
model. Since the purpose of the pageHandler is to simply provide controls that interact
directly with Faces JSP page, there should ideally be no business logic or data access
logic in the pageHandler.
o
The Page Data
 The Page Data view of the workbench shows the data areas and functions that are
available to the Faces JSP page. The artifacts that are shown in the Page Data view of
the workbench are those items that are defined in the EGL pageHandler. When an
artifact is added to the Faces JSP page, using drag-and-drop, that data area or function
defined in the pageHandler is associated with, or “bound” to, the control on the Faces
JSP page.
The preferred method of adding controls to a Faces JSP page is to drag and drop the
associated EGL pageHandler artifacts from the Page Data view rather than adding
controls from the Palette. When the controls are created from Page Data, there is no
chance of a control name not matching between the Faces JSP page and the EGL
pageHandler.
o
Rendering EGL Data with data aware JSF Control
o
Adding Business Logic to the page
 OnPageLoad
 In every pageHandler, there is a function, usually named onPageLoad that is
executed the first time the JSP renders the Web page.
Logic that needs to be performed before the page is initially displayed can be
executed from the onPageLoad function. Business logic and data access logic
should not be coded in the pageHandler itself. Rather, any additional logic
functions should be coded in Library members and called from the EGL
pageHandler.

Submit
 On a Faces JSF page, there is at least one button or link that submits the page
request. Upon executing the submit action, providing the JSP page passes all
of its validation rules, the pageHandler is invoked and the function that has
been bound to the submit control is executed.
At this point, the EGL function bound to the control can perform the necessary
logic to satisfy the request. Business logic and data access logic should not be
coded in the pageHandler itself. Rather, any additional logic functions should
be coded in Library members and called from the EGL pageHandler function.
37
Company Confidential
EGL Best Practices White Paper

Validation
 Upon selecting an input control on the Faces JSP page in Page Designer, you
can provide simple validations in the Validation tab of the Properties view.
Specify validation rules such as “Value is required”, minimum and maximum
values and input masks.
When the submit control is clicked during runtime, if there are any violations to
the validation rules defined, the pageHandler will not execute. Always be sure
to provide an error message field to ensure you see validation errors when they
occur.

Deployment
o Deployment is the act of packaging the EGL project and placing the runtime code on
the target execution environment. There are three types of EGL projects to deploy:
 nonWeb-based
NonWeb-based EGL applications are batch or text type applications that
need no resources for processing web pages.

Standalone Java
Typically, nonWeb-based EGL applications are deployed as standalone
Java JAR files. From the workbench, EGL projects are generated to Java
executables using the correct build descriptor for the desired target
execution environment. Prior to performing the final generate, any
rununit.properties, vgj.properties or programname.properties files should
be deleted. This allows the generation process to recreate the properties
files with the correct runtime properties for the target environment.
After the project has been generated, the project is exported to a JAR
file. The JAR file is then copied to the target platform and executed.
Before the EGL programs can be executed from the JAR file, the
necessary EGL runtime support files must be in place on the target
execution platform.

38
Application Client Projects
Another way to deploy a nonWeb-based EGL application is to deploy as
an Application Client. Application Client projects are developed in the
same way as standalone nonWeb-based EGL projects. The difference is
when the Application Client project is deployed, it is exported to an
Enterprise Archive (EAR) file and deployed to an application server.
Deploying to an application server allows the nonWeb-based EGL
application to use J2EE application server resources such as
CLASSPATH and JNDI information.
Company Confidential
EGL Best Practices White Paper

Web-based
Web-based EGL projects, as the name implies, are EGL projects that utilize
Faces JSPs and page handlers to interact with a Web browser. These
applications are deployed to an application server such as WebSphere
Application Server.
Web-based EGL projects are deployed as Enterprise Archive (EAR) files or
Web Archive (WAR) files. From the workbench, EGL Web projects are
generated using the correct build descriptor for the desired target execution
environment.
After the application code has been generated, the EAR or WAR file is then
deployed to WebSphere Application Server using the Administration
Console. The Administration Console places the EAR or WAR file in the
correct directory structure on the application server and enables you to start
and stop the application.
Before the EGL Web application can be executed, you must ensure that all
necessary database datasources, MQSeries queues, runtime properties, etc.
have been setup correctly on the application server. Without all of the
necessary definitions in place, your application will not be able to access
relational database, MQSeries message queues, etc.

39
COBOL Generation
 EGL projects that are targeted for execution on zSeries or iSeries utilize
a different approach than Java-based EGL applications. Upon
completion of application development, EGL programs are generated for
the zSeries or iSeries execution environment. COBOL code is generated
from the EGL code and sent to either the zSeries or iSeries for
preparation/compilation as a normal COBOL program. Again, there are
runtime files that must be in place before EGL applications can run on
either the zSeries or iSeries platforms.
Company Confidential
EGL Best Practices White Paper

Application Testing
We all know that testing should not be an afterthought. Also, a single testing cycle for a
large application can take longer than the amount of time that has been allocated. Given the
typical set of testing constraints, knowing how your application was implemented will help
you test your applications effectively. Following the best practice described above can
improve implementation productivity as well as testing productivity. This section provides
a set of examples where an increase in testing productivity and quality may be realized.
o When performing initial testing, it makes sense to use a small, carefully crafted set of
test data. Using small subsets of data allows you to spend less time executing tests
since there isn’t a large amount of test data to process. The test data needs to be
carefully crafted to ensure that the test data contains all necessary scenarios to
thoroughly test the EGL application. Test results are also easier to verify if the set of
test data is more concise.
o Utilize the EGL debugger to ensure that all logic trees in the EGL application have been
tested. This can be the only way to test some of the logic flow. This is especially true
in testing exception logic. It is not always possible to cause an exception condition so
exceptions can sometimes only be tested by simulating a problem during debug
execution.
o For runtime testing, automated testing tools can be used to execute test scenarios.
Testing tools make it very easy to re-run tests and compare test results between two
tests. Testing tools can also be used to stress test applications.
o You can also shorten your test/retest cycles by creating archive copies of input files and
databases. Having backup copies of your input data makes it easy to “reset” the data for
rerunning test scenarios by giving you a stable, reloadable set of input data. You can
easily reload input files to a consistent starting point in the event your input files are
changed or altered by other testing or other developers.
40
Company Confidential
EGL Best Practices White Paper
Part III –Conclusion
 Summary
This document has given you an overview of the EGL environment as well as provided
useful information in developing applications - from naming conventions to prototyping
and on through deployment.
EGL is a robust and powerful language. It opens the world of Web development to people
skilled in traditional programming techniques as well as providing capabilities for those
performing nonWeb-based development. All of this while maintaining a high-level of
abstraction from the underlying datastores and target execution platforms which lets
application developers focus on solving business requirements instead of concerning
themselves with many of the intricacies of the underlying architecture.

Next Steps
o Download the product for evaluation.
 You can evaluate EGL with your own evaluation copy. Go here to
download Rational Application Developer v6.
o Education
 There is one Web-based EGL offering:
 Using EGL Generation of COBOL for z/OS using IBM WebSphere
Studio Enterprise Developer.

There are two stand-up classes currently offered by IBM Education Services.
The are:
 Using Enterprise Generation Language in IBM WebSphere Studio
v5.1.2. Course code SW427.
 EGL for z/OS environment using WebSphere Studio Enterprise
Developer v5.1.2. Course code SW451.
o Where to find more information?
 There are various places to go for help on EGL. The help system in the
Rational Software Development Platform and, if using v5.1.2, the
WebSphere Studio tools, is an excellent place to go for information on using
EGL.
There is also an EGL Resource page on the IBM Web site that has many
EGL code examples as well as other resources for learning about and
migrating to EGL. Be sure to check out the Technical Samples. The Tech
Samples contain many real-world EGL coding examples.
41
Company Confidential
EGL Best Practices White Paper
o Choosing a pilot project.
 When choosing a pilot project for EGL development, it’s important to
choose a project that isn’t a high-priority, mission critical application. The
application should be chosen so as to give the new EGL developers the
opportunity to develop their skills in EGL development without placing
undue pressure on them to finish a project in a short, unalterable timeframe.
Batch applications can be a good place to start. Batch applications remove
the requirement for user interface design and development. When moving
into Web-based development, the first efforts should be the construction of
relatively simple Web pages. Wait until your developers are a bit more
experienced before developing pages that have all the “bells and whistles”.
42
Company Confidential