egl programmer's guidepublic.dhe.ibm.com/software/dw/rational/pdf/com_ibm_etools_egl_pg.pdf ·...
Post on 24-Sep-2020
12 Views
Preview:
TRANSCRIPT
Rational Business Developer
EGL Programmer’s Guide
Version 7 Release 01
���
Rational Business Developer
EGL Programmer’s Guide
Version 7 Release 01
���
Note
Before using this information and the product it supports, read the information in “Notices,” on page 331.
Contents
Introduction . . . . . . . . . . . . . 1
Using EGL with the Eclipse IDE . . . . . . . . 1
A typical EGL development workbench . . . . 2
Other windows EGL developers commonly use . . 4
Other views and editors EGL developers
commonly use . . . . . . . . . . . . . 5
How the workbench is organized . . . . . . 9
Other information on the workbench . . . . . 11
Enabling EGL capabilities . . . . . . . . . . 11
What’s new in EGL V7.0 . . . . . . . . . . 12
Language changes in EGL V7.0 . . . . . . . 13
Validation changes in EGL V7.0 . . . . . . 19
Changes to parts in EGL V7.0 . . . . . . . 21
Changes to system libraries and variables in EGL
V7.0 . . . . . . . . . . . . . . . . 24
Changes to build descriptor options in EGL V7.0 27
Changes to exception handling in EGL V7.0 . . 29
Changes to services in EGL V7.0 . . . . . . 29
User interface changes in EGL V7.0 . . . . . 30
Documentation changes in EGL V7.0 . . . . . 31
Migrating to the current version of EGL . . . . . 32
Setting EGL-to-EGL migration preferences . . . 34
Migrating EGL code to EGL V7.0 . . . . . . 36
Migrating EGL code to EGL V6.0 iFix 001 . . . 48
Features not supported in this version . . . . . 57
Contents of an EGL application . . . . 59
Introduction to EGL projects . . . . . . . . . 61
Creating an EGL project . . . . . . . . . 62
Creating an EGL Web project . . . . . . . 63
Creating an EGL plug-in project . . . . . . 65
Features and facets of EGL projects . . . . . 66
Sharing projects . . . . . . . . . . . . 67
The EGL build path . . . . . . . . . . 71
Source folders . . . . . . . . . . . . . 74
Creating source folders . . . . . . . . . 74
Introduction to EGL packages . . . . . . . . 74
Creating an EGL package . . . . . . . . . 76
Introduction to EGL files . . . . . . . . . . 76
Creating EGL source files . . . . . . . . . 77
Renaming a source file . . . . . . . . . 77
Moving a source file . . . . . . . . . . 79
Creating EGL build files . . . . . . . . . 79
Creating a deployment descriptor file . . . . . 80
Introduction to EGL parts . . . . . . . . . 81
Generatable parts and non-generatable parts . . 81
Introduction to data parts . . . . . . . . 82
Introduction to logic parts . . . . . . . . 90
Introduction to build parts . . . . . . . . 96
Renaming parts . . . . . . . . . . . . 97
Moving parts . . . . . . . . . . . . . 98
Properties . . . . . . . . . . . . . . . 99
Working with EGL code . . . . . . . 103
Common programming tasks . . . . . . . . 103
Turning lines of code into comment lines . . . 104
Calling Java . . . . . . . . . . . . . 104
Calling C functions with the call statement . . 107
Calling C functions through EGL libraries . . . 109
Encrypting passwords . . . . . . . . . 122
Handling errors . . . . . . . . . . . 123
Customizing runtime messages . . . . . . 127
The EGL editor . . . . . . . . . . . . . 130
Code assistant . . . . . . . . . . . . . 132
Code templates . . . . . . . . . . . . 133
Code snippets . . . . . . . . . . . . . 138
Inserting code snippets into EGL and JSP files 139
Using cheat sheets . . . . . . . . . . . . 140
Editing DataItem parts with the source assistant 141
Searching for EGL files and parts . . . . . . . 142
Searching for parts . . . . . . . . . . 143
Viewing lists of parts . . . . . . . . . . 144
Viewing part references . . . . . . . . . 145
Locating an EGL source file in the Project
Explorer view . . . . . . . . . . . . 146
Preferences . . . . . . . . . . . . . . 147
Setting general preferences . . . . . . . . 147
Setting preferences for the EGL editor . . . . 148
Setting preferences for folding in the EGL editor 149
Setting preferences for organizing import
statements in the EGL editor . . . . . . . 150
Setting preferences for source styles . . . . . 151
Setting generation preferences . . . . . . . 152
Setting preferences for EGL text . . . . . . 152
Accessing data with EGL code . . . . 155
Common data access tasks . . . . . . . . . 155
Reading and writing records . . . . . . . 156
Writing and reading a sequential file . . . . 158
Specifying database options at project creation 160
Working with SQL data . . . . . . . . . . 161
Best practices . . . . . . . . . . . . 161
Creating an SQL database connection . . . . 162
Supported SQL database managers . . . . . 166
Using an SQL database connection at run time 168
Editing or deleting an SQL database connection 169
Retrieving SQL table data . . . . . . . . 170
Creating a data access application . . . . . 173
Working with SQL statements . . . . . . . 175
Setting preferences for SQL database
connections . . . . . . . . . . . . . 181
Setting preferences for SQL retrieve . . . . . 181
Building EGL Web applications . . . 183
Elements of a Web application . . . . . . . . 183
Common tasks in Web applications . . . . . . 185
Creating a Web page . . . . . . . . . . 186
Binding JSF controls to EGL variables and
functions . . . . . . . . . . . . . . 187
© Copyright IBM Corp. 1996, 2007 iii
Navigating among Web pages with navigation
rules . . . . . . . . . . . . . . . 201
Forwarding data between Web pages . . . . 202
Executing commands when a page loads . . . 203
Retrieving the value of a clicked row in a data
table . . . . . . . . . . . . . . . 205
Setting the focus to a form field . . . . . . 206
Displaying error messages on Web pages . . . 206
Updating a row in a relational table . . . . . 210
Storing data in the user’s session . . . . . . 211
Testing browsers for a session variable . . . . 213
Localizing text in Web applications . . . . . 214
Updating portions of a Web page with AJAX
requests . . . . . . . . . . . . . . 219
Running a Web page on a server . . . . . . 235
Accessing the JSF component tree with the source
assistant . . . . . . . . . . . . . . . 236
Changing the target of a JSF link . . . . . . 239
Changing the style of a JSF control . . . . . 240
Changing the style class of a JSF control . . . 241
Setting event handlers for a JSF control . . . . 242
Setting the size of a JSF image . . . . . . . 243
Enabling or disabling JSF controls . . . . . 244
Setting JSF data table properties . . . . . . 245
Adding JSF component interface support to an
EGL Web project . . . . . . . . . . . . 246
Setting preferences for Web projects . . . . . . 246
Building and using service
applications in EGL . . . . . . . . . 249
Elements of a service application . . . . . . . 249
Types of service applications . . . . . . . . 252
Calling a local service . . . . . . . . . . 254
Calling an external service . . . . . . . . . 256
Adding service client binding information from
a WSDL file . . . . . . . . . . . . . 257
Adding service client binding information for
an EGL service . . . . . . . . . . . . 259
Creating and binding a variable to an external
service . . . . . . . . . . . . . . . 260
Exposing a service to other applications . . . . 263
Adding Web service deployment information to
the deployment descriptor . . . . . . . . 265
Creating and using a shared protocol . . . . . 266
Building EGL Console User Interface
applications . . . . . . . . . . . . 267
Elements of a Console UI application . . . . . 267
Creating a Console User Interface . . . . . . 269
Adding rich client widgets to a Console UI
program . . . . . . . . . . . . . . . 272
Adding a button widget . . . . . . . . . 274
Adding a check box widget . . . . . . . 276
Adding a combo box or radio button group
widget . . . . . . . . . . . . . . 278
Running Console UI applications . . . . . . . 280
Console UI modes . . . . . . . . . . . . 281
Creating reports with EGL . . . . . . 283
JasperReports engine . . . . . . . . . . . 283
EGL text report engine . . . . . . . . . . 283
Creating reports with JasperReports . . . . . . 283
Elements of an EGL report application . . . . 284
Creating the report design file . . . . . . . 285
Writing code to drive a report . . . . . . . 289
Creating an EGL report handler . . . . . . 292
Running a report . . . . . . . . . . . 296
Using report templates . . . . . . . . . 297
Creating subreports . . . . . . . . . . 298
Adding support for Jasper reports to a project 300
Creating EGL text reports . . . . . . . . . 301
Handler events for a text report . . . . . . 302
Writing code to print a text report . . . . . 303
Debugging EGL applications . . . . . 307
Stepping through an application in the EGL
debugger . . . . . . . . . . . . . . . 308
EGL debugger commands . . . . . . . . . 312
How build descriptor settings affect the EGL
debugger . . . . . . . . . . . . . . . 315
Using breakpoints in the EGL debugger . . . . 316
Viewing variables in the EGL debugger . . . . 317
Prerequisites . . . . . . . . . . . . . 317
Variables and breakpoints . . . . . . . . 318
Displaying and changing values . . . . . . 318
Buttons in the Variables view . . . . . . . 318
Starting the EGL debugger for EGL projects . . . 319
Creating a launch configuration in the EGL
debugger . . . . . . . . . . . . . . 320
Creating an EGL Listener launch configuration 321
Starting a non-J2EE application in the EGL
debugger . . . . . . . . . . . . . . 321
Invoking the EGL debugger from generated
code . . . . . . . . . . . . . . . 322
Debugging Web projects with the EGL debugger 323
Configuring a server for EGL Web debugging 323
Starting an EGL Web debugging session . . . 325
Debugging services with the EGL debugger . . . 326
Prerequisites . . . . . . . . . . . . . 326
Debugging a local service . . . . . . . . 326
Character encoding options for the EGL debugger 327
Setting preferences for the EGL debugger . . . . 328
General preferences . . . . . . . . . . 328
Debug behavior mapping . . . . . . . . 329
Appendix. Notices . . . . . . . . . 331
Programming interface information . . . . . . 333
Trademarks and service marks . . . . . . . 333
Index . . . . . . . . . . . . . . . 335
iv EGL Programmer’s Guide
Introduction
These topics explain the fundamentals of using EGL in the Eclipse IDE, as well as
changes to the EGL language and IDE in this version.
Related concepts
“Using EGL with the Eclipse IDE”The Eclipse IDE offers a graphical user interface (GUI) called the workbench, in
which users perform work by pointing and clicking objects on the screen as
well as by typing code. In this way, when you are working with EGL, you are
using the Eclipse workbench, so it is worth taking a minute to look at the tools
in the workbench.
“Enabling EGL capabilities” on page 11Capabilities keep the workbench menus from becoming cluttered by hiding
items you do not use. You can always perform these tasks, but to make them
appear in the menus, you must enable the capability for that area of
functionality.
“What’s new in EGL V7.0” on page 12
“Migrating to the current version of EGL” on page 32
“Features not supported in this version” on page 57EGL V7.0 temporarily removes support for some features included in previous
versions.
Using EGL with the Eclipse IDE
The Eclipse IDE offers a graphical user interface (GUI) called the workbench, in
which users perform work by pointing and clicking objects on the screen as well as
by typing code. In this way, when you are working with EGL, you are using the
Eclipse workbench, so it is worth taking a minute to look at the tools in the
workbench.
While developing EGL applications, you use the workbench to manage your files,
write your code, and test and deploy your application. The workbench includes
code editors similar to editors for other programming languages, but it also
includes a range of graphical tools for working with EGL code and the many other
types of code and files that the workbench understands.
Eclipse gives you the ability to change the set of tools that it offers and choose
which tools appear in the interface. Each different tool set is called a perspective,
and the windows within a perspective are called views and editors. You will learn
more about these concepts later in this topic.
© Copyright IBM Corp. 1996, 2007 1
A typical EGL development workbench
Menu bar
Functions in a GUI are typically listed in a menu bar at the top of the window.
In the picture above, the menu bar lists menus beginning with File, Edit, and
Navigate. The menus drop down when you click the menu item with the
mouse. The Eclipse menu bar contains global options for the workbench, such
as the location of the workspace, commands for importing and exporting files,
search commands, and help menus.
With the menu bar, you can also open and close views and perspectives. You
can click Window → Show View to open a view or Window → Open
Perspective to open a perspective.
Perspectives bar
The Perspectives bar lists the currently active perspectives. You can click the
name and icon of a perspective to switch to that perspective. In the picture
above, the Debug, EGL, and Web perspectives are active, and the EGL
perspective is open.
Toolbars
The workbench displays various toolbars below the menu bar depending on
the open perspective, views, and files. If you position the cursor over an icon,
hover help shows the function provided by that icon. Some icons also have a
drop-down list with additional options. For example, the tool bar for the EGL
2 EGL Programmer’s Guide
perspective contains icons that start the EGL wizards to create a new EGL
project, a new EGL package, or a new EGL source file. Some views and editors
also have their own toolbar.
The icons on these toolbars are shortcuts for commands found elsewhere in the
workbench, such as in the menu bar or on the popup menu that appears when
you right-click a file. You can customize the toolbars shown by clicking
Window → Customize Perspective and selecting or clearing check boxes on the
Commands tab.
EGL code editor
The EGL code editor looks and works like a standard text editor or code editor
for other languages, but it has additional features to help you edit EGL code.
The code editor highlights invalid syntax, provides an explanation for
problems in the code, and colors keywords and strings.
The EGL code editor also includes content assist, which attempts to complete
code that you have begun to type. To use content assist, type the first few
characters of a variable name, library name, or EGL keyword and press CTRL
+ Space. A content assist window opens, listing valid EGL code phrases that
begin with the code you have typed. Select a code phrase from the list by
highlighting it and pressing Enter or double-clicking it.
Project Explorer view
The Project Explorer view shows all of your files and projects. Within the
projects, this view shows your files in a hierarchical arrangement. Click a plus
sign to expand a package or folder and expose the files inside. Double-click a
file to open it in its default editor. Right-click a file, project, or folder to display
a context-sensitive menu of options. From this menu, you can delete or rename
files, among many other options. You can also click and drag files from place
to place in the view. You can group projects in this view by defining working
sets, or groups of projects or other elements. See ″Working sets″ in the product
help.
Outline view
The Outline view shows a hierarchical representation of the file you are
currently editing. For example, if the file contains a Program part and a Record
part, the Outline view shows the file’s package at the top of the hierarchy,
followed by any import statements in the file, and then the Program part and
Record part. Variables and functions in the Program part appear under the
Program part in the Outline view, and fields in the Record part appear as
nodes under the Record part. You can click any of the entries in the Outline
view to go to the matching location in the EGL source file.
Problems view
The Problems view shows syntax errors or warnings in your code or other
files. You can double-click on an error to show the location of the error in the
file.
Generation Results view
EGL updates the Generation Results view each time you generate parts. If any
of your EGL parts do not generate correctly, this window shows which parts
did not generate and why. This view also shows which parts generated
successfully.
In the previous image, the Generation Results view is ″stacked,″ or hidden behind
the Problems view. You can switch to a hidden view by clicking the tab with the
name of the view you want, which brings that view to the top of the stack. You
Introduction 3
can also double-click the name of a view to expand that view to fill the
workbench. Double-clicking the name again will return the view to its original
size.
Other windows EGL developers commonly use
Aside from the main workbench window, EGL developers will often need to use
other windows. Following are some examples:
EGL Preferences window
With the Preferences window, you can set global options for the workbench.
This illustration shows the EGL page of the Preferences window. To set EGL
preferences, click Window → Preferences and click EGL. See “Preferences” on
page 147 for links to information on the particular EGL preferences you can
set.
Search window
4 EGL Programmer’s Guide
In the Search window, not to be confused with the Search view, you can search
for EGL parts or for other information in your workspace. The search results
appear in the Search view. See “Searching for parts” on page 143 for details.
Properties window
Most types of projects and files have a Properties window, not to be confused
with the Properties view. The Properties window sets individual options for
the artifact. Access the Properties window for a project or file by right-clicking
it and then clicking Properties.
Other views and editors EGL developers commonly use
EGL build parts editor
The build parts editor is used for editing build parts, including build
descriptors.
Introduction 5
EGL Parts Reference view
The EGL Parts Reference view shows a hierarchical view of the parts
referenced in a generatable logic part. To open a part in the Parts Reference
view, right-click the file that contains the part in the Project Explorer view and
then click Open in Parts Reference. See “Viewing part references” on page 145
for details.
EGL Parts List view
6 EGL Programmer’s Guide
The EGL Parts List view shows a list of EGL parts that you can sort or filter
for reference purposes. See “Viewing lists of parts” on page 144 for details.
Page Designer Editor
Page Designer is a what-you-see-is-what-you-get (WYSIWYG) editor for Web
pages. Page Designer can work with EGL to create a Web interface for an EGL
application.
Properties view
The Properties view provides detailed information on a specific object that you
have selected in an editor. For example, if you have a Web page open in Page
Designer and you select a text output field on that Web page, the Properties
Introduction 7
view shows you information such as the style applied to the field, where its
content comes from, and its other characteristics.
Palette view
The Palette view works alongside WYSIWYG editors. The Palette lists objects
that you can drag into the editor, creating new objects in the open file.
Snippets view
The Snippets view works alongside code editors. The Snippets view holds
reusable pieces of code that you can drag into your code. You can also create
new snippets for code that you use often.
Console view
8 EGL Programmer’s Guide
The Console view shows logged messages that are related to running your
applications. For example, if you run an application and it causes an error, that
error is listed in the Console view.
Navigator view
The Navigator view is similar to the Project Explorer view in that both show
the projects and files in your workspace. However, the Navigator view is a
pure view of the folders and files in your workspace, without any formatting
or filtering done by EGL. As such, it shows every folder and file in the
workspace based on the actual location of those artifacts. The Project Explorer
reduces clutter by automatically hiding metadata files (such as the .eglproject
file) and directories that you do not normally need to access (such as the
EGLbin directory). Also, the Navigator view does not support refactoring EGL
parts and files, such as renaming or moving them, like the Project Explorer
view does.
How the workbench is organized
The workbench contains a large number of tools and options. For this reason, it
organizes the tools into a hierarchy of categories. From most general to most
specific, these groups are capabilities, perspectives, views, and editors.
Capabilities
Capabilities are the broadest category of functionality in the workbench.
Capabilities are organized by major functional areas, such as ″Web
developer″ or ″Tester.″
Capabilities can be enabled or disabled to display or hide functionality. For
example, if the Tester capability is disabled, perspectives and views related
to testing will not be available. You can manually enable a capability in the
Preferences window by clicking Window → Preferences → General →
Capabilities and then selecting the check boxes next to the capabilities you
want to enable. Alternately, when you try to create a file or open a
perspective that is associated with a disabled capability, the workbench
will prompt you to enable the associated capability.
The main capability that EGL developers use is the EGL Developer
capability. Enabling this capability makes EGL-related perspectives
Introduction 9
available, which in turn makes tools available for working with EGL code.
See “Enabling EGL capabilities” on page 11.
Perspectives
A perspective is a group of views and editors that are all shown on the
screen at once. For example, when you open the Web perspective by
clicking Window → Open Perspective → Other → Web, you see tools for
building Web sites. There are other perspectives for working with data
sources, debugging code, and testing.
The perspectives available to you depend on the capabilities enabled in
your workbench. For example, if the Tester capability is disabled, you will
not see the Test perspective as an option in Window → Open Perspective →
Other.
You can switch perspectives at any time without losing your work, and
you can have as many perspectives open as you want. Often, developers
switch between perspectives as they perform different tasks. To switch
between perspectives, open the perspectives you want with Window →
Open Perspective → Other or click a perspective’s icon in the Perspectives
bar, which is typically at the top right corner of the workbench.
You can also create customized perspectives that show only the tools you
want. To create a customized perspective, open an already existing
perspective and tailor it to your needs by repositioning its views and
editors and opening or closing views and editors. Then, click Window →
Save Perspective As and type a name.
Views When you open a perspective, the views associated with that perspective
are displayed in the workbench. Each view performs a specific purpose,
such as displaying certain information or giving access to a specific tool.
The purpose of each view varies widely, but in general, views give you
access to a specific area of your workspace. Some views, such as the
Project Explorer, Navigator, and Package Explorer views, show the files,
projects, and packages in your workspace, enabling you to open files or
reorganize projects. Other views, such as the Outline and Properties views,
give information about a file you are currently viewing in an editor.
Finally, some views, such as the Problems view and the Console view,
display information about the status of your projects.
Views are flexible; you can move them around the workbench, resize them,
minimize or maximize them, stack them on top of other views, or close
them. To close a view, click the X at the top of the view. To open a view,
either open a perspective that contains that view or click Window → Show
View and click the name of a view. You can have as many views open as
you want, but it is best to organize your views into one or more
perspectives.
Editors
Editors look like views, but editors are designed to change a particular
type of file. Some editors, like the EGL code editor, look and work just like
code editors for many other programming languages, although the EGL
code editor has additional features for working with EGL code.
Other editors are graphical, with drag-and-drop tools or
what-you-see-is-what-you-get (WYSIWYG) preview tools. For example,
with Page Designer you can edit a Web page by clicking and typing
directly in the Web page. You can also drag Web page elements onto the
page from views such as the Palette view.
10 EGL Programmer’s Guide
Still other editors are tabular and provide tables in which you enter values.
For example, the EGL build parts editor enables you to edit a build
descriptor part by entering the values for build descriptor options in a
table.
In general, when you double-click a file in a view that displays files, such
as the Project Explorer or Navigator, that file opens in its default editor.
You can also right-click the file, and then click Open With to see a list of
editors that can open that file, or you can click Open With → System
Editor to open the file outside of the workbench, in the default editor for
that type of file in the operating system.
Other information on the workbench
For more information on using the workbench effectively, see these sources:
v Help topics on the following subjects:
– Workbench
– Capabilities
– Perspectives
– Views
– Editorsv “Enabling EGL capabilities”
v “Setting general preferences” on page 147
v “Working with EGL code” on page 103
v The tutorial ″Understand the workbench environment″ in the tutorials gallery
(Help → Tutorials Gallery).
Enabling EGL capabilities
Capabilities keep the workbench menus from becoming cluttered by hiding items
you do not use. You can always perform these tasks, but to make them appear in
the menus, you must enable the capability for that area of functionality.
For EGL, capabilities hide the EGL-related views and the EGL perspective, items in
the context menus and menus for creating new files, and the code templates
available when you use content assist.
To enable EGL capabilities, follow these steps:
1. From the main menu, click Window → Preferences.
2. In the Preferences window, expand General in the tree and then click
Capabilities.
In the Capabilities list, the EGL Developer folder represents the EGL
capabilities. You may have other capabilities in the list.
3. To enable all EGL capabilities, select the check box next to EGL Developer.
4. To select a few EGL capabilities to enable, follow these steps:
a. Click Advanced. The Advanced window opens.
b. Expand EGL Developer.
c. Under EGL Developer, select the check boxes next to the capabilities that
you want to enable.
Each capability enables a different set of EGL functionality. The Core
Language capability is required for EGL functionality.
d. Click OK.
Introduction 11
5. Normally, the workbench warns you before you use functionality that belongs
to a disabled capability. If you clear the check box labeled Prompt when
enabling capabilities, the workbench will automatically enable any capabilities
that you try to use.
6. To save your changes, click Apply, then click OK.
Some capabilities have prerequisites. For this reason, enabling EGL capabilities
may automatically enable other capabilities that are required to develop and debug
EGL applications.
Related concepts
“Preferences” on page 147EGL preferences affect the way the workbench displays and works with EGL.
What’s new in EGL V7.0
Several new features have been added in this version:
v Language enhancements
v Expanded support for services, including iSeries™ COBOL and CICS® services
v Support for model-driven development, including the ability to transform UML
to EGL
v Addition of rich client widgets to EGL Console UI
v Improvements to the user interface
v Improvements to the documentation
v Improved performance, particularly for building projects, generating Java™ or
COBOL, and Java runtime.
v Libraries can now be generated for iSeries COBOL
v Support for AJAX requests (version 7.0.0.3)
Model-driven development
This version of EGL allows you to plan an application with a UML model and
then create starter EGL code from the UML model. Generally, model-driven
development with EGL follows these steps:
1. You plan your application with a UML model. EGL does not include
functionality for editing UML models graphically.
2. You associate the UML model with a transformation parameters model (TPM)
file. This file specifies which transformations will be used on the UML model
and how those transformations will be applied. The EGL Application
Transformation allows you to transform UML into EGL. Depending on what
products you have installed, you may have other transformations available, but
these transformations will not create EGL code.
3. Using the transformation parameters editor, you edit the parameters associated
with the EGL application transformation to describe what the resulting EGL
code will look like. Depending on what products you have installed, you may
have other transformations available, but these transformations will not create
EGL code.
4. You run the transformation to apply the transformation parameters to the UML
model and create EGL code.
For information on the transformation parameters editor and working with
transformations in general, see ″Generating source code from UML models″ in the
online help. For information on the EGL Application Transformation, see ″Model
12 EGL Programmer’s Guide
driven development of EGL code″ in the online help.
Console User Interface rich client widgets
In this release, EGL contains support for rich client widgets in Console UI. These
widgets allow you to add mouse support to your Console UI applications, as well
as graphical input fields like check boxes and buttons. Developing an application
with these widgets is similar to developing an ordinary Console UI application,
but you must run the application in RCP mode, rather than the standard mode for
Console UI applications. See “Adding rich client widgets to a Console UI
program” on page 272.
AJAX support
Beginning with version 7.0.0.3, EGL-controlled Web pages can issue AJAX requests,
allowing you to update a portion of a page without refreshing the entire page. To
create an AJAX request, you indicate an area on the page to be updated, specify a
user action to trigger the update, and add code to the page’s JSF Handler to
process the update. See “Updating portions of a Web page with AJAX requests” on
page 219.
The following topics deal with major changes in this version of EGL.
Related Concepts
“Language changes in EGL V7.0”This topic lists the changes to the EGL language in version 7.0.
“Validation changes in EGL V7.0” on page 19
“Changes to parts in EGL V7.0” on page 21This topic lists the EGL parts and describes their major changes in this version.
“Changes to system libraries and variables in EGL V7.0” on page 24
“Changes to build descriptor options in EGL V7.0” on page 27
“Changes to exception handling in EGL V7.0” on page 29This topic covers changes to the way EGL deals with exceptions in version 7.0.
“Changes to services in EGL V7.0” on page 29
“User interface changes in EGL V7.0” on page 30
“Documentation changes in EGL V7.0” on page 31
“Features not supported in this version” on page 57EGL V7.0 temporarily removes support for some features included in previous
versions. Related tasks
“Migrating to the current version of EGL” on page 32
Language changes in EGL V7.0
This topic lists the changes to the EGL language in version 7.0.
Major changes
Reference variables
EGL now uses the concept of reference variables, variables that do not hold a
value themselves but act as a reference to another value. For example,
arrays, Dictionaries, consoleForms, and the ANY, BLOB, and CLOB
primitives are reference types. See ″Reference variables″ in the EGL
Language Reference.
Introduction 13
Nullable types
The way EGL handles nullable variables, variables that can point to a null
or empty value, has changed.
v You can declare a nullable variable by appending a question mark ? to
the variable type specification. For example, the following code declares
a nullable integer variable:
myNullableVariable int?;
Variables declared to be nullable in this way contain null until you
assign a value to them.
v You can now set a nullable variable to null by assigning it the value
NULL, as in this example:
myVar int? = NULL;
Similarly, you can test to see whether a variable is null by comparing it
to the value NULL:
if (myVar == NULL)
...
end
Because you can now assign a null value and compare to a null value,
the following expressions are no longer used:
– SET myVar NULL
– if (myVar is NULL)
v NIL is no longer a valid literal to represent a null value. Use NULL
instead.
v The itemsNullable build descriptor option is no longer used. In its place
is the I4GLItemsNullable property, which can be put on programs,
libraries, handlers, and records for migration purposes. This property
places an implicit question mark on each primitive variable, constant,
and parameter in the part, making them all nullable.
v When a variable is made nullable with an explicit question mark, that
variable is initially null. When a variable is made nullable by
I4GLItemsNullable, the initial value of that variable depends on the
type of variable.
v The nullable modifier on function parameters is now sqlNullable.
v The isNullable property is now isSQLNullable.
v System functions have rules to deal with nullable variables. In most
cases, if you pass a null variable to a system function, the function will
return a null value. However, the behavior of each function differs with
respect to nullable parameters and return values. See the reference
information for the specific function for information on how it deals
with nullable variables.
v When concatenating string variables, a null value is treated as an empty
string.
For more information on nullable variables, see the topics ″Null values and
the nullable type″ and ″i4glItemsNullable″ in the EGL Language Reference.
14 EGL Programmer’s Guide
Statements
New operators
The new concatenation operator (::) concatenates two variables as though
those variables were strings. When used with text variables, it works like
the + operator:
myString1 string = "Hello ";
myString2 string = "everyone!";
SysLib.writeStderr(myString1 :: myString2);
SysLib.writeStderr(myString1 + myString2);
//writes "Hello everyone!" to the console twice
When used with numeric variables, the concatenation operator treats those
variables like strings:
myInt1, myInt2, myInt3 int;
myInt1 = 5;
myInt2 = 6;
myInt3 = myInt1 :: myInt2;
SysLib.writeStderr(myInt3);
//writes "56" to the console.
The as operator temporarily assigns, or casts, a value to a specified type.
The following example uses as to temporarily cast a variable of the ANY
primitive type to the INT primitive type:
myVar1 ANY = "5";
myVar2 int = 6;
myVar3 int = myVar2+myVar1 as int;
SysLib.writeStderr(myVar3);
//Writes "11" to the console.
Conversion enhancements
You can now assign a STRING directly to a DECIMAL, FLOAT, or INT.
This ability removes the need for functions such as
MathLib.stringAsDecimal().
Change in rounding behavior
In previous versions, when you assigned a variable to a target variable
with fewer decimal places, EGL truncated the source variable to fit into the
target variable. In EGL V7.0, these extra decimal places are rounded, not
truncated, when either of the following criteria is true:
v The truncateExtraDecimals build descriptor option is set to NO
v The type of the source variable is FLOAT or SMALLFLOAT, and the
type of the target variable is not FLOAT or SMALLFLOAT
If both of these criteria are false, EGL truncates the source variable to the
number of decimal places available in the target variable, as it did in
V6.0.1.1.
In previous versions, for the MathLib.round() system function, the second
argument (the power of 10) was optional. In EGL V7.0, the second
argument is required.
The migration tool uses the MathLib.assign() system function to replace
MathLib.round() in situations in which the power of 10 parameter was not
used.
Changes to syntax of call, transfer, and show
You can now specify the name of the target program or transaction in
these statements as a direct program reference, as a literal (in quotes), or as
Introduction 15
a variable. The statements also use braces to group their keyword
modifiers. In addition, the call statement now uses parentheses to group
arguments. For example:
call "xxx" (1, 2) { IsNoRefresh = yes, IsExternal = yes };
transfer to program "xxx" passing yyy { IsExternal = yes};
Variables
Scope of variables within functions
In previous versions of EGL, if you declared a variable within a function,
that variable was in scope for the entire function, even for statements that
preceded the variable declaration. Now, variables are in scope only for
statements that follow their declaration.
Format specifiers for INTERVAL variables
You must include a format specifier when creating an INTERVAL variable:
intval1 interval("yyyyMM");
Default representation for text literals
By default, text literals (such as "Hello!") are treated as of the type
STRING in the generated source. If you want EGL to interpret these as a
different type instead, set the new textLiteralDefaultIsString property to
NO. See ″textLiteralDefaultIsString″ is the EGL Language Reference.
ANY type is no longer limited to the type of its first assigned value
In previous versions of EGL, if you created a variable of the ANY type and
assigned a value to that variable, the ANY variable was permanently
limited to the type of that value. The ANY variable could store only values
compatible with that first value. In this version, the ANY variable can
accept any EGL type, regardless of what you have assigned to it
previously. You can use the as operator to cast an ANY variable
temporarily to another type, and you can use the isa operator to test what
type of data the ANY variable contains.
Web applications
Validating variables when their values change
With the onValueChangeFunction property, you can specify a function to
validate user input for a variable in a JSF Handler automatically when the
value of the variable changes. For example, the following code creates a
variable and specifies its validation function:
myInteger int {onValueChangeFunction = validateMyInt};
The function specified by onValueChangeFunction accepts a parameter of
the same type, which you use to test the value:
function validateMyInt(intToCheck int in)
if (intToCheck >= 500)
SysLib.setError("Number must be less than 500");
end
end
General changes
Some property values are no longer quoted strings
When assigning values to properties in set value blocks, EGL no longer
uses quotes around names of fields, variables, or parts. For example, the
following code is correct for version 6.0:
16 EGL Programmer’s Guide
Record CustomerRecord type SQLRecord {
keyItems = ["customerNumber"]}
customerNumber INT; //key field
customerName STRING;
end
The following code is correct for version 7.0:
Record CustomerRecord type SQLRecord {
keyItems = [customerNumber]}
customerNumber INT; //key field
customerName STRING;
end
File names, aliases, and other values continue to require quotes, as in the
following example:
Record XferLog type SerialRecord {fileName = "MYFILE1"}
10 entry CHAR(60);
end
The following properties have changed from a quoted string to an
unquoted reference to a variable:
v commandValueItem
v inputForm
v inputRecord
v inputUIRecord
v keyItem
v keyItems
v lengthItem
v msgField
v numElementsItem
v onPageLoadFunction, which is now split into the properties
onConstructionFunction, onPreRenderFunction, and
onPostRenderFunction
v parentRecord
v pcbParms
v psb
v psbParm
v redefines
v segmentRecord
v selectedIndexItem
v selectFromListItem
v validationByPassFunctions
v validatorDataTable
v validatorFunction
v valueRef
v viewRootVar
New reserved words
The following words are now reserved words in EGL:
v CONSTRUCTOR
v DELEGATE
Introduction 17
v ENUMERATION
v EXTERNALTYPE
v NOCURSOR
v NULL
v RUNUNIT
v SQLNULLABLE
v THROW
v WITHV60COMPAT
Importing from the default package is no longer allowed
In previous versions, you could define a part in the default package (that
is, a part in the root of an EGL source folder, with no named package
containing it) and import that part for use in a part in another package.
Now you can import parts in the default package only into other parts in
the default package.
Naming conflicts between functions and variables
Within a part, no function may have the same name as a variable.
Name resolution between fields and properties
You can use the ″at″ symbol (@) to distinguish between fields and
properties with the same name.
For example, assume an EGL Dictionary part, which a list of name-value
pairs. You use a set-value block to assign those name-value pairs; you can
use the same set-value block to assign values to properties of the
dictionary itself. The following is a declaration of a new Dictionary part:
myRef Dictionary {
displayName = "myNewDictionary"
};
Because of part resolution rules, EGL assumes that displayName =
"myNewDictionary" is a name-value pair in the new dictionary. If you want
to assign a value to the displayName property for the dictionary, you must
use an @ operator, as in the following example:
myRef Dictionary {
@displayName {"myNewDictionary"}
};
See ″EGL part resolution rules″ in the EGL Language Reference for more
information. Related Concepts
“What’s new in EGL V7.0” on page 12
“Validation changes in EGL V7.0” on page 19
“Changes to parts in EGL V7.0” on page 21This topic lists the EGL parts and describes their major changes in this version.
“Changes to system libraries and variables in EGL V7.0” on page 24
“Changes to build descriptor options in EGL V7.0” on page 27
“Changes to exception handling in EGL V7.0” on page 29This topic covers changes to the way EGL deals with exceptions in version 7.0.
“Changes to services in EGL V7.0” on page 29
“User interface changes in EGL V7.0” on page 30
“Documentation changes in EGL V7.0” on page 31
18 EGL Programmer’s Guide
“Features not supported in this version” on page 57EGL V7.0 temporarily removes support for some features included in previous
versions.
Validation changes in EGL V7.0
Some pieces of code that appeared to be valid in previous releases will be marked
as invalid in this version. In most cases, these validation changes do not reflect
language changes; instead, the EGL editor is identifying code that was accepted in
previous versions but did not run as expected in the generated code. Following are
updates to code validation that you may encounter in this version of EGL:
Variables and constants
isBoolean property on variables with no non-decimal places
You can apply the isBoolean property to a numeric variable with decimal
places, such as DECIMAL(3,2). However, the variable must have at least one
non-decimal place. For this reason, variable declarations such as myVar
decimal(2,2){isBoolean=yes} are invalid. Use a BOOLEAN primitive or a
numeric type with places to the left of the decimal.
Assigning a literal with too many decimal places for the target constant
Validation now recognizes an attempt to assign too many decimal places to
a constant, as in these examples:
const c1 decimal(5,3) = 1.2345; //validation error
const c2 decimal(5,3) = 123.456; //validation error
Statements
Size of arrays within an isa expression
You cannot specify a size for an array in an isa expression, as in this
example:
library myLibrary type basicLibrary
function func(parameterOne any)
if (parameterOne isa int[5]) //validation error
end
end
end
into clauses with ANY types
You cannot use into to put data into an ANY variable:
program myProgram
myRecord recordType;
myVariable any;
function main()
foreach(from myRecord into myVariable);// validation error
end
end
end
record recordType type SQLRecord
item1 int;
end
Operations with incompatible INTERVAL variables
Validation now recognizes an attempt to perform assignment or a
Introduction 19
mathematical operation between two INTERVAL variables with
incompatible formats, as in this example:
Program pgm
msInterval interval("yyyymm");
ssInterval interval("mmss");
function main()
msInterval = msInterval + ssInterval; //validation error
end
end
Parts
Service parts must have a function for every function prototype in the interfaces
it implements
When a Service part implements an Interface part, the Service part must
contain a function matching each function prototype in the Interface part.
The function names, parameter lists, and return values must match.
position property required on consoleForms that do not specify segments
property
If a Record part with the stereotype consoleForm does not specify the
position property, that Record part must specify the segments property.
JSF Handlers
Variables in JSF Handler parts with insufficient length to be displayed
Validation now recognizes variables in JSF Handlers that are not long
enough to fit the pattern specified in properties such as dateFormat and
timeFormat, as in this example:
handler myPage type JSFHandler
{view="myPage.jsp"}
myField decimal(1)
{dateFormat = "MM/dd/yyyy"}; //validation error
end
BLOB and HEX used as the value of selectFromListItem
Validation now recognizes an attempt to use BLOB and HEX variables as
the value of the selectFromListItem property in a JSF Handler.
selectFromListItem specifying a variable in another part
Validation now recognizes an attempt to use a variable in a library rather
than a variable in the same JSF Handler part as the value of the
selectFromListItem property.
Value of fillCharacter for DBCHAR and UNICODE variables
Validation now requires that the fillCharacter property is set to an empty
string on DBCHAR and UNICODE variables used in a JSF Handler
Type matching between variables in a JSF Handler and validation tables
Validation now ensures that the variables in a JSF Handler match the type
of the first column in their validation tables. Related Concepts
“What’s new in EGL V7.0” on page 12
“Language changes in EGL V7.0” on page 13This topic lists the changes to the EGL language in version 7.0.
“Changes to parts in EGL V7.0” on page 21This topic lists the EGL parts and describes their major changes in this version.
Related tasks
20 EGL Programmer’s Guide
“Migrating to the current version of EGL” on page 32
Changes to parts in EGL V7.0
This topic lists the EGL parts and describes their major changes in this version.
New primitive
Like Boolean types in other languages, the BOOLEAN EGL primitive accepts a
value of TRUE or FALSE. You can also use YES to represent TRUE and NO to
represent FALSE. The isBoolean property is still supported on other primitive
variables.
New parts
The following parts are new in this version:
ExternalType
An ExternalType part represents a mapping from EGL to another
language. This part replaces an Interface part with the stereotype
JavaObject in previous versions. For more information, see the following
topics:
v ″ExternalType part″ in the EGL Language Reference
v “Calling Java” on page 104
Delegate
This new type of part provides a model for a function. For more
information, see ″Delegate part″ in the EGL Language Reference
Changed parts
The following parts have changed in this version:
pageHandler
The pageHandler part is now a Handler part with the stereotype
JSFHandler. JSF Handlers perform all the same tasks as a pageHandler did
in previous versions, with some differences in properties:
v The onPageLoadFunction property, which designated a function to run
when the page loads, has been divided into the
onConstructionFunction, onPreRenderFunction, and
onPostRenderFunction functions. onConstructionFunction is the most
similar to onPageLoadFunction.
v The default value for a JSFHandler scope property is now session.
v The cancelOnPageTransition property determines whether the page
bean is removed from the session scope when the user’s browser loads a
new page. This property was added in version 6.0.1.1.
v You can apply the onValueChangeFunction property to a variable in a
JSF Handler to specify a function that validates the new value when
user input changes the value of the variable.
v You can apply the properties selectedRowItem and selectedValueItem
to variables within JSF Handlers. These properties behave in a way
similar to the properties selectFromListItem and selectType.
selectedRowItem indicates a variable that holds the index (or indexes)
for the row (or rows) the user selects from a screen display.
selectedValueItem holds the value or values from those rows instead of
the index or indexes.
Introduction 21
v If variable in a JSF Handler has the selectType property set to index,
that variable must be an INT type.
v If a variable in a JSF Handler has the selectFromListItem property, the
property’s value cannot be a record array or an array of primitive
variables within a record. Valid types are a data table column or an
array of primitive variables not within a record. To use a record array or
an array of primitive variables within a record as a list of selection
options, use the properties selectedRowItem or selectedValueItem
instead.
For more information, see the following topics:
v “Executing commands when a page loads” on page 203
v ″JSF Handler″ in the EGL Language Reference
v ″onPreRenderFunction″ in the EGL Language Reference
v ″onPostRenderFunction″ in the EGL Language Reference
v ″onConstructionFunction″ in the EGL Language Reference
v ″cancelOnPageTransition″ in the EGL Language Reference
v ″onValueChangeFunction″ in the EGL Language Reference
v ″selectType″ in the EGL Language Reference
v ″selectFromListItem″ in the EGL Language Reference
v ″selectedRowItem″ in the EGL Language Reference
v ″selectedValueItem″ in the EGL Language Reference
Service
The way EGL uses services has changed significantly in this version. See
“Changes to services in EGL V7.0” on page 29
The properties of the Service part have changed as follows:
v The @WSDL property is no longer used. Use @XML to interact with
WSDL files.
v The @XSD property is no longer used.
v The properties allowUnqualifiedItemReferences and
includeReferencedFunctions are now valid on Service parts.
For more information, see the following topics:
v “Changes to services in EGL V7.0” on page 29
v ″Service part″ in the EGL Language Reference
v ″EGL deployment descriptor″ in the EGL Generation Guide
v “Building and using service applications in EGL” on page 249
v ″@XML″ in the EGL Language Reference
v ″@bindService″″ in the EGL Language Reference
Library
The serviceBindingLibrary type of Library part is no longer used. The
runtimeBind property, which was used only on this type of Library part, is
no longer needed. See the information on services and the Service part, or
one of the following topics:
v ″Library part″ in the EGL Language Reference
v ″Service part″ in the EGL Language Reference
v “Building and using service applications in EGL” on page 249
22 EGL Programmer’s Guide
Interface
The Interface part no longer has stereotypes such as BasicInterface and
JavaObject. Instead of BasicInterface, use an Interface part with no
stereotype. Instead of JavaObject, use an ExternalType part. For more
information, see the following topics:
v ″Interface part″ in the EGL Language Reference
v ″ExternalType part″ in the EGL Language Reference
Program
Programs that are the target of a call statement must have a parameter list.
This parameter list can be empty, but the parentheses denoting the
parameter list are now required.
Record
Record parts have the new @SelectionList property, which specifies fields
in the record to use for the label and value when using the record in a JSF
selection list. For more information, see:
v ″@SelectionList″ in the EGL Language Reference
v “Binding a JSF single-select control to a variable” on page 194
Record parts have the new stereotype Exception, which is used to define a
custom exception. See “Changes to exception handling in EGL V7.0” on
page 29.
Record parts with the stereotype ConsoleForm
Record parts with the stereotype ConsoleForm are now considered
generatable parts. See “Generatable parts and non-generatable parts” on
page 81.
Record parts with the SQLRecord stereotype
The isNullable property for fields within SQLRecord parts is now the
isSQLNullable property. See ″isSQLNullable″ in the EGL Language
Reference.
Record parts with the RelativeRecord stereotype
The keyItem property for this type of Record part is now the
recordNumItem property. See ″recordNumItem″ in the EGL Language
Reference.
New properties
The following table lists new properties that can be used on multiple parts:
Table 1. New properties
Property Applicable parts
The v60ExceptionCompatibility property
specifies whether the logic part uses a form
of exception handling for compatibility with
a previous version. See
″v60ExceptionCompatibility″ in the EGL
Language Reference.
v Program
v Handler
v Library
v Service
The textLiteralDefaultIsString property tells
EGL how to deal with text literals to
promote compatibility with VisualAge®
Generator. See ″textLiteralDefaultIsString″ in
the EGL Language Reference.
v Program
v Handler
v Library
v Service
v Record
Introduction 23
Table 1. New properties (continued)
Property Applicable parts
The i4glItemsNullable property determines
whether a record emulates the behavior of
I4GL in creating variables as nullable by
default. It replaces the itemsNullable build
descriptor option. See ″i4glItemsNullable″ in
the EGL Language Reference.
v Program
v Handler
v Library
v Record
Related Concepts
“What’s new in EGL V7.0” on page 12
“Language changes in EGL V7.0” on page 13This topic lists the changes to the EGL language in version 7.0.
“Changes to services in EGL V7.0” on page 29
“Changes to exception handling in EGL V7.0” on page 29This topic covers changes to the way EGL deals with exceptions in version 7.0.
Related tasks
“Migrating to the current version of EGL” on page 32
Changes to system libraries and variables in EGL V7.0
Global changes
Most system functions have been updated to accept null values for parameters. In
general, if you pass a null value to a system function, it returns a null value.
However, each function behaves differently; see the help topic on the specific
function for information.
Some system functions and libraries have been temporarily removed from the
language because their areas of functionality are not present in this version. See
“Features not supported in this version” on page 57.
Removed system functions
The following system functions are no longer necessary because you can now
assign a string directly to a decimal, floating-point, or integer type:
v MathLib.stringAsDecimal
v MathLib.stringAsFloat
v MathLib.stringAsInt
New system libraries and variables
The new system library sqlLib contains some functions moved from sysLib and
consoleLib that deal with SQL data access.
Similarly, the SQL-related system variables in sysVar and VGVar have been moved
into the new sqlLib.sqlData and sysVar.sqlData system variables, which are both
structured records. sqlLib.sqlData contains information that is global to the entire
application, while sysVar.sqlData contains information that is local to the program.
See ″sysVar system variable (core fields)″ and ″sqlLib system variables″ in the EGL
Language Reference.
24 EGL Programmer’s Guide
New system functions
The following system functions and variables are new in this version:
j2eeLib.clearApplicationAttr
See ″clearApplicationAttr″ in the EGL Language Reference.
j2eeLib.clearEGLSessionAttrs
See ″clearEGLSessionAttrs″ in the EGL Language Reference.
j2eeLib.getApplicationAttr
See ″getApplicationAttr″ in the EGL Language Reference.
j2eeLib.setApplicationAttr
See ″setApplicationAttr″ in the EGL Language Reference.
MathLib.decimals
See ″decimals″ in the EGL Language Reference.
StrLib.booleanAsString
See ″booleanAsString″ in the EGL Language Reference.
StrLib.getTokenCount
See ″getTokenCount″ in the EGL Language Reference.
StrLib.indexOf
See ″indexOf″ in the EGL Language Reference.
StrLib.intAsUnicode
See ″intAsUnicode″ in the EGL Language Reference.
StrLib.unicodeAsInt
See ″unicodeAsInt″ in the EGL Language Reference.
SysLib.convertNumberToUnicodeNum
See ″convertNumberToUnicodeNum″ in the EGL Language Reference.
SysLib.convertUnicodeNumToNumber
See ″convertUnicodeNumToNumber″ in the EGL Language Reference.
SysLib.setErrorForComponentID
See ″setErrorForComponentID″ in the EGL Language Reference.
Changed system functions and variables
The following system functions have new names:
Table 2. Renamed system functions
Old name New name
ConsoleLib.constructQuery SqlLib.constructQuery
MathLib.compareNum VGLib.compareNum
MathLib.FloatingAssign MathLib.assign
MathLib.FloatingDifference VGLib.FloatingDifference
MathLib.FloatingMod VGLib.FloatingMod
MathLib.FloatingProduct VGLib.FloatingProduct
MathLib.FloatingQuotient VGLib.FloatingQuotient
MathLib.FloatingSum VGLib.FloatingSum
MathLib.maximum MathLib.max
MathLib.minimum MathLib.min
Introduction 25
Table 2. Renamed system functions (continued)
Old name New name
ServiceLib.getWebEndPoint ServiceLib.getWebServiceLocation
ServiceLib.setWebEndPoint ServiceLib.setWebServiceLocation
StrLib.characterAsInt StrLib.charAsInt
StrLib.compareStr VGLib.compareStr
StrLib.concatenate VGLib.concatenate
StrLib.concatenateWithSeparator VGLib.concatenateWithSeparator
StrLib.copyStr VGLib.copyStr
StrLib.findStr VGLib.findStr
StrLib.integerAsChar StrLib.intAsChar
StrLib.setSubStr VGLib.setSubStr
StrLib.strLen StrLib.byteLen
StrLib.textLen StrLib.characterLen
SysLib.beginDatabaseTransaction SqlLib.beginDatabaseTransaction
SysLib.connect SqlLib.connect
SysLib.defineDatabaseAlias SqlLib.defineDatabaseAlias
SysLib.disconnect SqlLib.disconnect
SysLib.disconnectAll SqlLib.disconnectAll
SysLib.loadTable SqlLib.loadTable
SysLib.queryCurrentDatabase SqlLib.queryCurrentDatabase
SysLib.setCurrentDatabase SqlLib.setCurrentDatabase
SysLib.startTransaction VGLib.startTransaction
SysLib.unloadTable SqlLib.unloadTable
The following system functions have changed significantly in this version:
MathLib.round
In previous versions this function had a required parameter (the number to
be rounded) and an optional parameter (the power of ten to which to
round the number). In this version, both parameters are required. See
″round()″ in the EGL Language Reference.
SysLib.convert
This direction argument of this function was formerly an ″L″ or ″R″ literal
value. In this version, the function cannot accept a literal; instead, it
requires an argument of ConvertDirection.Remote or
ConvertDirection.Local. See ″convert()″ in the EGL Language Reference.
SqlLib.Connect
This function was formerly SysLib.Connect, and its parameters have
changed:
v The fourth parameter, commitScope, is no longer used. The fifth, sixth,
and seventh parameters are now the fourth, fifth, and sixth parameters.
v When the isolationLevel parameter is not specified or is set to default,
the function uses the JDBC driver’s default isolation level, unless VAGen
compatibility mode is enabled.
26 EGL Programmer’s Guide
v The default value of the isolationLevel parameter default, not
serializableTransaction.
See ″connect()″ in the EGL Language Reference.
Change in casting syntax
In past versions, certain arguments in certain functions in JavaLib could
accept a casting operator in parentheses. Now, use the as keyword to cast a
variable, as in variable as "type". Related Concepts
“What’s new in EGL V7.0” on page 12
“Language changes in EGL V7.0” on page 13This topic lists the changes to the EGL language in version 7.0.
“Changes to build descriptor options in EGL V7.0”
Changes to build descriptor options in EGL V7.0
New build descriptor options
The following build descriptor options are new in this version:
currencyLocation
See ″currencyLocation″ in the EGL Generation Guide.
deploymentDescriptor
See ″deploymentDescriptor″ in the EGL Generation Guide.
includeLineNumbers
See ″includeLineNumbers″ in the EGL Generation Guide.
maxNumericDigits
See ″maxNumericDigits″ in the EGL Generation Guide.
separatorSymbol
See ″separatorSymbol″ in the EGL Generation Guide.
truncateExtraDecimals
See ″truncateExtraDecimals″ in the EGL Generation Guide.
Removed build descriptor options
The following build descriptor options have been removed:
v initIORecords
v initNonIOData
v itemsNullable
Instead of the itemsNullable build descriptor option, use the
I4GLItemsNullable property. See the explanation of nullable types in “Language
changes in EGL V7.0” on page 13.
v serviceRuntime
v webServiceEncodingStyle
The following build descriptor options have been temporarily removed because the
functionality they represent is not available in this version, as explained in
“Features not supported in this version” on page 57:
Options related to Java wrappers:
v enableJavaWrapperGen
Introduction 27
v wrapperPackageName
Options related to Text User Interface:
v fillWithNulls
v formServicePgmType
v genFormGroup
v genHelpFormGroup
v leftAlign
v oneFormItemCopybook
v printDestination
v restartTransactionID
v setFormItemFull
v validateOnlyIfModified
v workDBType
Options related to IMS™ and DL/I data access:
v errorDestination
v imsFastPath
v imsLogID
v mfsDevice
v mfsExtendedAttr
v mfsIgnore
v mfsUseTestLibrary
v restoreCurrentMsgOnError
v spaADF
v spaSize
v spaStatusBytePosition
v synchOnPgmTransfer
Options related to Web transactions:
v genVGUIRecords
v msgTablePrefix
Changed build descriptor options
The following build descriptor options have changed significantly:
targetNLS
DES (Swiss German) is no longer a valid value for this build descriptor
option. Use DEU instead.
tempDirectory
This build descriptor option is now used to specify the directory in which
temporary files are stored when you generate with the EGL SDK. Related Concepts
“What’s new in EGL V7.0” on page 12
“Language changes in EGL V7.0” on page 13This topic lists the changes to the EGL language in version 7.0.
“Changes to system libraries and variables in EGL V7.0” on page 24
28 EGL Programmer’s Guide
Changes to exception handling in EGL V7.0
This topic covers changes to the way EGL deals with exceptions in version 7.0.
Exception stereotype for Record parts
You can now define a Record with the type Exception, or use a number of
predefined Exception Records. The Exception stereotype is at the heart of a
new style of exception handling in EGL. Within a try block you can now
have multiple onException statements. Each onException statement must
include a declaration of an Exception record variable, as in the following
example:
try
get next mySerialRecord;
onException(myEx FileIOException)
myErrorHandler1(myEx);
onException(myEx AnyException)
myErrorHandler2(myEx);
end
The AnyException type is available to catch any exception not previously
specified.
When a function throws an exception that is not caught within the try
block or is not within a try block at all, control immediately returns to the
function that called it, if any, even if the exception occurs in a library
function. EGL passes the exception upward until an onException statement
catches it or the exception reaches the main function. If the main function
fails to catch the exception, the program ends immediately and writes the
message field of the exception to the log. When an exception occurs in a
called program, the calling program receives an InvocationException rather
than the original exception. Similarly, an exception in a service function
delivers a ServiceInvocationException to the calling program.
The Exception records contain various fields, depending on the exception
type. For a list of all system exception records and their fields, see ″EGL
Exception records″ in the EGL Language Reference.
For more information about error handling, including throwing your own
exceptions, see “Handling errors” on page 123.
v60ExceptionCompatibility property
This new property allows you to continue to use the EGL version 6 style of
exception handling for backward compatibility. For more information, see
“V6 exception compatibility” on page 126. Related Concepts
“What’s new in EGL V7.0” on page 12
“Language changes in EGL V7.0” on page 13This topic lists the changes to the EGL language in version 7.0.
Related tasks
“Migrating to the current version of EGL” on page 32
Changes to services in EGL V7.0
EGL’s service functionality has expanded significantly in this version. The way you
make a service available to other applications has changed, as well as the way in
which your EGL applications act as clients of other applications. Also, you can
now generate services and service clients to iSeries COBOL and CICS.
Introduction 29
Most importantly, the service binding library is no longer used. In its place is the
EGL deployment descriptor file, which defines both how your service client
application accesses external services and how your service application makes itself
available to other applications. The Service part itself is essentially the same, except
for some changes in properties; the difference is that to allow other applications to
use the service, you add Web service deployment information to the EGL
deployment descriptor file.
Similarly, to act as a client of a service (that is, to use the service in one of your
logic parts), you no longer call functions in the service binding library. Instead, you
create a variable to represent the service and then bind that variable to the actual
service using binding information in the EGL deployment descriptor file. In this
way, any logic part can now behave as a client.
Related tasks
“Elements of a service application” on page 249The major elements of an EGL service application are the service part, interface
part, and deployment descriptor file. In general, each of these files and parts
has a role in both service applications and client applications.
“Building and using service applications in EGL” on page 249Service applications, within service-oriented architecture, enable you to organize
your programs in a modular, compartmentalized manner.
User interface changes in EGL V7.0
Creating Web pages
The wizards used for creating different types of Web pages have been
consolidated into a single wizard. To create a Web page in an EGL Web
project, click File → New → Other → Web Page. In the New Web Page
window, be careful to select a WebContent folder in an EGL Web project
and to specify that you want a JSP file, either by selecting a JSP template
or adding the .jsp extension to the file name. See “Creating a Web page”
on page 186.
General workbench enhancements
Refactoring support is enhanced so you can move and rename parts
without having to make as many manual corrections. See “Moving parts”
on page 98 or “Renaming parts” on page 97.
EGL editor
The EGL editor now supports folding to temporarily hide sections of code,
and it has an ″Organize Imports″ option to order and simplify the import
statements in your code. The editor also provides context-sensitive help for
many EGL keywords if you highlight the keyword and press F1. See “The
EGL editor” on page 130, “Setting preferences for folding in the EGL
editor” on page 149, or “Setting preferences for organizing import
statements in the EGL editor” on page 150.
EGL debugger
When debugging an application, you can now jump to a specific line in the
code or run the application until a certain line in the code. See “EGL
debugger commands” on page 312. Also, you can set the debugger to use
either the generated source or the EGL source for a called program or
service. See “Setting preferences for the EGL debugger” on page 328.
Cheat sheets
EGL offers a set of cheat sheets to lead you through common tasks. See
“Using cheat sheets” on page 140.
30 EGL Programmer’s Guide
Generation options
You can now set which parts you want to generate automatically when
you save a file. See “Setting generation preferences” on page 152.
Transforming UML to EGL
You can design an application in UML and use the transformation
parameters editor to specify how that UML model should be transformed
into EGL source. See ″Generating source code from UML models″ in the
product Help.
Data Access Application wizard
The Parts and Pages wizard and Data Parts wizard have been combined
into the Data Access Application wizard, which offers more flexibility in
creating data parts, logic parts, and Web pages to use with a database
connection. See “Creating a data access application” on page 173.
Build parts editor
The build parts editor is enhanced to enable you to automatically set build
descriptor options based on an existing database connection in the
workbench. See ″Editing build descriptor options in the build descriptor
part″ in the EGL Generation Guide.
EGL deployment descriptor editor
EGL provides a graphical editor for working with the new EGL
deployment descriptor file. See “Changes to services in EGL V7.0” on page
29
Password encryption
EGL now encrypts your passwords in certain situations and provides a
utility for encrypting passwords manually. See “Encrypting passwords” on
page 122. Related Concepts
“What’s new in EGL V7.0” on page 12
“Language changes in EGL V7.0” on page 13This topic lists the changes to the EGL language in version 7.0.
Documentation changes in EGL V7.0
Reorganization of EGL documentation
The EGL documentation has been reorganized in this version into three
major sections:
v The EGL Language Reference covers the EGL language independently of
generation and of issues with using the Eclipse IDE.
v The EGL Generation Guide covers the generation process, including build
parts and build descriptor options.
v The EGL Programmer’s Guide covers the use of EGL with the Eclipse
workbench, as well as some common tasks in EGL and an introduction
to EGL artifacts and concepts.
The migration and server guides have not been reorganized:
v The IBM® EGL Server Guide for iSeries is available in the product
Information Center under ″EGL Server Guide for iSeries.″
v The IBM Rational® COBOL Runtime Guide for zSeries® is available in
the product Information Center under ″Rational COBOL Runtime Guide
for zSeries.″
Introduction 31
v TheIBM Informix® 4GL to EGL Conversion Utility User’s Guide is
available in the product Information Center under ″Migrating from IBM
Informix 4GL to EGL.″
Context-sensitive help
As in previous versions, you can press F1 in a wizard or window to show
a short piece of information on the wizard and links to related help topics.
In this version, you can also open context-sensitive help on EGL keywords
in the EGL editor, such as get, program, and for. To open context-sensitive
help on a keyword, highlight the entire keyword and no more in the EGL
editor and then press F1.
Samples and tutorials
EGL includes samples and tutorials for this new version in the samples
and tutorials galleries. See ″Tutorials and samples for EGL″ in the product
Help.
Index Along with its search functionality, the workbench help system now
provides index entries to help you access help topics based on an
alphabetical list of keywords. To open the index, first open the online help
system by clicking Help → Help Contents, and then click the Index button
at the bottom left of the window. Related Concepts
“What’s new in EGL V7.0” on page 12
“User interface changes in EGL V7.0” on page 30
“Language changes in EGL V7.0” on page 13This topic lists the changes to the EGL language in version 7.0.
“Validation changes in EGL V7.0” on page 19
“Changes to services in EGL V7.0” on page 29
“Changes to exception handling in EGL V7.0” on page 29This topic covers changes to the way EGL deals with exceptions in version 7.0.
“Changes to parts in EGL V7.0” on page 21This topic lists the EGL parts and describes their major changes in this version.
“Changes to system libraries and variables in EGL V7.0” on page 24
“Changes to build descriptor options in EGL V7.0” on page 27
“Features not supported in this version” on page 57EGL V7.0 temporarily removes support for some features included in previous
versions. Related tasks
“Migrating to the current version of EGL”
Migrating to the current version of EGL
EGL provides migration tools to move code from previous versions to the current
version. You can migrate entire projects at a time or select individual packages or
files to migrate, but you must migrate JSP files and their associated pageHandler
parts at the same time. The tool corrects syntax changes, updates invocations of
system libraries that have changed, corrects the names of properties that have
changed, and makes other updates as described in “Changes made by the V7.0
migration tool” on page 37.
Important: Do not use the migration tool on code that has already been updated
to EGL V7. Doing so can create errors in your code.
32 EGL Programmer’s Guide
Before you begin, take these steps to prepare for migration:
v Back up your code.
v Import all projects referenced by the project that you are migrating into your
workspace. The migration tool attempts to resolve references to parts in the
migrated code. You do not have to migrate the referenced projects at the same
time, but they must be present for the tool to work properly.
v All Eclipse Web projects, not just EGL Web projects, are updated automatically
to work in the new version of the workbench. This does not mean that your
EGL code is migrated automatically, just that your Web projects are updated to
the current standard.
You can determine whether your Web projects are being updated by watching
for the Project Migration window when you open and build a Web project from
a previous version in the V7.0 workspace. If you do not have automatic builds
enabled, build the project manually by clicking the project and then clicking
Project → Build Project.
v Determine the current version level of your code, because the steps for
migration are different depending on your current version. Migration paths are
provided for code at the following levels:
– Version 5.1.2, up to but not including version 6.0 with iFix 001
– Version 6.0 with iFix 001, up to but not including version 6.0.1
– Version 6.0.1, up to but not including version 7.0
Follow the steps below to migrate EGL code to the current version, using the
section that represents your code’s current version:
Version 5.1.2, up to but not including version 6.0 with iFix 001
1. Migrate the code to version 6.0 iFix 001 as explained in “Migrating EGL code to
EGL V6.0 iFix 001” on page 48.
2. Make the following changes to the code manually to migrate the code to
version 6.0.1:
v Make sure that none of your identifiers (such as variable or part names)
begins with the at symbol (@), which is now an operator.
v Change invocations of the following system functions, but only if the last
argument in the invocation is a numeric value, as evidenced by an error
message that indicates a problem with the argument’s primitive type.
Table 3. Manual changes to system functions
Old function New function
StrLib.compareStr VGLib.compareBytes
StrLib.CopyStr VGLib.copyBytes
StrLib.concatenate VGLib.concatenateBytes
3. Migrate the code from version 6.0.1 to version 7.0 as explained in “Migrating
EGL code to EGL V7.0” on page 36.
Version 6.0 with iFix 001, up to but not including version 6.0.1
1. Make the following changes to the code manually to migrate the code to
version 6.0.1:
v Make sure that none of your identifiers (such as variable or part names)
begins with the at symbol (@), which is now an operator.
Introduction 33
v Change invocations of the following system functions, but only if the last
argument in the invocation is a numeric value, as evidenced by an error
message that indicates a problem with the argument’s primitive type.
Table 4. Manual changes to system functions
Old function New function
StrLib.compareStr VGLib.compareBytes
StrLib.CopyStr VGLib.copyBytes
StrLib.concatenate VGLib.concatenateBytes
2. Migrate the code from version 6.0.1 to version 7.0 as explained in “Migrating
EGL code to EGL V7.0” on page 36.
Version 6.0.1, up to but not including version 7.0
1. Migrate the code from version 6.0.1 to version 7.0 as explained in “Migrating
EGL code to EGL V7.0” on page 36. Related concepts
“What’s new in EGL V7.0” on page 12
“Changes made by the V7.0 migration tool” on page 37
“Changes to exception handling in EGL V7.0” on page 29This topic covers changes to the way EGL deals with exceptions in version 7.0.
“Changes to services in EGL V7.0” on page 29
“Changes not made by the V7.0 migration tool” on page 46After migrating your code to V7.0, you might need to make manual changes.
Related tasks
“Setting EGL-to-EGL migration preferences”
“Migrating EGL code to EGL V6.0 iFix 001” on page 48
“Migrating EGL code to EGL V7.0” on page 36
Setting EGL-to-EGL migration preferences
Preferences for the EGL-to-EGL migration wizard control how EGL code from prior
versions is migrated to the current version. Some of these preferences are
meaningful for both the version 6 and version 7 migration, and others apply only
to one migration. Follow these steps to set EGL migration preferences:
1. Enable the EGL V7.0 migration capability:
a. Click Window → Preferences.
b. Expand General and click Capabilities.
c. Click Advanced.
d. In the Advanced window, expand EGL Developer and select the EGL V7.0
Migration check box.
e. Click OK.
f. Click OK again. 2. Click Window → Preferences.
3. Expand EGL and click Migration. This page shows the settings for the
migration tool.
4. Choose how to resolve a naming conflict with a new reserved word by
clicking a radio button:
34 EGL Programmer’s Guide
v Add suffix sets the migration tool to add a suffix to any words in the
source code that are now reserved words. In the text box by this radio
button, type the suffix you want the migration tool to add to the changed
word.
v Add prefix sets the migration tool to add a prefix to any words in the
source code that are now reserved words. In the text box by this radio
button, type the prefix you want the migration tool to add to the changed
word. 5. If your project has standalone functions, that is, functions that are not
contained by any other logic part, and those functions contain variables that
are now reference types (such as arrays), select the check box labeled Convert
assignment statements to move statements. See “Changes made by the V7.0
migration tool” on page 37 for more information on converting from
assignment statements to move statements for reference variables.
6. As explained in the section on nullable types in “Language changes in EGL
V7.0” on page 13, the itemsNullable build descriptor option has been
replaced with the I4GLItemsNullable property. The migration tool can add
this property to your logic parts automatically. Select the Add property
I4GLItemsNullable=yes if you want the migration tool to add this property.
7. The migration tool can set the new textLiteralDefaultIsString property to NO
for each part to preserve previous behavior in the way EGL treats text literals
(such as "Hello!"). See ″textLiteralDefaultIsString″ in the EGL Language
Reference.
8. The migration tool can delete the Java files from your projects so that the Java
files can be re-generated from the EGL source. Select Prompt, Always, or
Never. This change affects only the Java files in the same project as EGL code
that you are migrating. If you are generating the EGL code into a different
project, delete those Java files manually.
9. The migration tool can set the deploymentDescriptor build descriptor option
to the name of an EGL deployment descriptor file in the project. It can update
all build descriptor files, just the default build descriptors, or none at all.
Select a radio button under Project build descriptors to update with the
deployment descriptor name.
10. The migration tool can add Web service deployment information to the
project’s deployment descriptor file for each Service part it finds in the related
project. Select an option under Add a webservice element to the deployment
descriptor for every service.
11. The migration tool can remove Web service references from the J2EE
deployment descriptor because EGL now uses its own deployment descriptor
file for service references instead. If you want the migration tool to make this
change, select Remove Web Service references from the J2EE deployment
descriptor.
12. When migrating to V6.0, the migration tool adds level numbers to Record
parts that do not have level numbers. Set the default level number in the
Default level number for record structure field.
13. To add a qualifier to the values of properties that have a finite list of possible
values, select the Add qualifiers to enumeration property values check box.
If this box is checked, the migration tool will add the type of value to the
value name. This preference applies only to V6.0 migration.
14. Under Logging options, choose whether you want the tool to add a comment
to each file that it changes and whether you want the results of the migration
process saved to a log file.
15. When you are finished setting preferences, click OK to save your changes.
Introduction 35
Related concepts
“Changes made by the V7.0 migration tool” on page 37
“Changes to exception handling in EGL V7.0” on page 29This topic covers changes to the way EGL deals with exceptions in version 7.0.
“Changes to services in EGL V7.0” on page 29
“Language changes in EGL V7.0” on page 13This topic lists the changes to the EGL language in version 7.0.
Related tasks
“Migrating to the current version of EGL” on page 32
Migrating EGL code to EGL V7.0
Before migrating to EGL V7.0, ensure that you have followed the complete steps
for migration as explained in “Migrating to the current version of EGL” on page
32.
Follow these steps to run the migration tool to migrate code from EGL version
6.0.1 or later to version 7.0:
Note: Do not use the migration tool on code that has already been updated to
EGL V7.0. Doing so can create errors in your code.
1. Enable the EGL V7.0 migration capability:
a. Click Window → Preferences.
b. Expand General and click Capabilities.
c. Click Advanced.
d. In the Advanced window, expand EGL Developer and select the check box
labeled EGL V7.0 Migration.
e. Click OK.
f. Click OK again.2. Set the preferences for the migration process as described in “Setting
EGL-to-EGL migration preferences” on page 34.
3. In the Project Explorer view, select the EGL projects, packages, folders, or files
that you want to migrate. You can select any number of EGL resources to
migrate. To select more than one resource at once, press and hold CTRL while
clicking the resources.
4. Right-click on a selected resource and then click EGL V7.0 Migration →
Migrate.
5. Inspect your code for errors and for places that do not comply with EGL V7.0.
You might need to make manual changes to your code as explained in
“Changes not made by the V7.0 migration tool” on page 46, “Changes to
services in EGL V7.0” on page 29, and “Changes to exception handling in EGL
V7.0” on page 29.
6. Optionally, you can disable the V7.0 migration capability to avoid migrating the
same code twice.
To review the changes that the tool made to the source code, do as follows:
1. In the Project Explorer view, right-click an EGL source file that has been
migrated and then click Compare With → Local History.
2. Examine the differences between the file in the workspace and the previous
version.
36 EGL Programmer’s Guide
3. When you are finished reviewing the changes, click OK.
Related concepts
“Changes made by the V7.0 migration tool”
“Changes not made by the V7.0 migration tool” on page 46After migrating your code to V7.0, you might need to make manual changes.
Related tasks
“Migrating to the current version of EGL” on page 32
“Setting EGL-to-EGL migration preferences” on page 34
Changes made by the V7.0 migration tool
This topic lists the changes that the V7.0 migration tool makes. Some of these
changes can be controlled by the migration tool’s preferences. See “Setting
EGL-to-EGL migration preferences” on page 34 for more information.
General
Changes to projects
If you run the migration tool on an entire project and that project contains
a Service part or a Service Binding Library, the migration tool adds an EGL
Deployment Descriptor file to the project. See the section on changes to
services and service binding libraries later in this section.
If the preference to delete Java files is enabled, the migration tool deletes
the Java files from your projects so the Java files can be re-generated from
the EGL source. This change affects only the Java files that are in the same
project as the EGL code you are migrating. If you are generating the EGL
code into a different project, delete those Java files manually.
The migration tool updates project classpaths to reflect new names and
locations of JAR files, including removing JAR files that are no longer
used.
New reserved words
Depending on the preference settings, the migration tool adds a prefix or
suffix to existing names that conflict with new reserved words. See ″New
reserved words″ in “Language changes in EGL V7.0” on page 13.
Properties
Changes to existing properties
The migration tool changes the values of properties that are no longer
quoted strings. See the section ″Some property values are no longer quoted
strings″ in “Language changes in EGL V7.0” on page 13. This change
includes the pcbParms property, in which case the migration tool changes
empty strings ("") to NULL. The migration tool makes this change even
though this version of EGL does not support DL/I database access. See
“Features not supported in this version” on page 57.
The migration tool changes the keyItem property on records with the
stereotype relativeRecord to the recordNumItem property.
The migration tool changes the isNullable property to isSQLNullable.
The migration tool changes the value of the protect and outline property
on Text UI form fields to the ProtectKind and OutlineKind enumeration.
It puts the value of outline in brackets because this property is now an
array. The migration tool does not change the value of protect on fields in
a ConsoleForm record.
Introduction 37
Table 5. Changes to the protect and outline properties on Text UI form fields
Old property and value New property and value
protect = yes protect = ProtectKind.protect
protect = no protect = ProtectKind.noProtect
protect = skip protect = ProtectKind.skipProtect
outline = box outline = [OutlineKind.box]
outline = noOutline outline = [OutlineKind.noOutline]
The migration tool makes these changes even though this version of EGL
does not support Text UI. See “Features not supported in this version” on
page 57.
Exception compatibility
The migration tool sets v60ExceptionCompatibility to YES on the
following logic parts:
v Program
v Library
v Handler
v Service
Text literals
Depending on the preferences, the migration tool adds the code
textLiteralDefaultIsString = NO to the following parts to preserve
behavior from previous versions:
v Program
v Library
v Handler
v Service
v Records
Variables
Variable scope within code blocks
As explained in ″Scope of variables within functions″ in “Language
changes in EGL V7.0” on page 13, variables are now in scope only after
their declaration, not before. The migration tool moves all local variable
declarations to the beginning of the code block. If that variable was
initialized, the migration tool converts the initializer into an assignment
statement and leaves the assignment statement where the original location
of the variable declaration was. If the variable was already at the beginning
of the code block, the migration tool moves its initializer into an
assignment statement and puts that assignment statement at the end of the
variable declarations.
Default specifier for INTERVAL variables
The migration tool adds a default format specifier to INTERVAL variables
without a specified format:
Table 6. Changes to INTERVAL variable declaration
Old code Migrated code
intval1 interval; intval1 interval("yyyyMM");
38 EGL Programmer’s Guide
System functions and variables
General changes
v The migration tool changes uses of system functions and variables that
have changed names. See “Changes to system libraries and variables in
EGL V7.0” on page 24.
v The migration tool changes uses of the sysLib.convert() system function
to use the ConvertDirection enumeration, as in this example:
sysLib.convert(myOrderRec, ConvertDirection.Local, myConvTable);
Values of ″L″ and ″R″ are changed to ConvertDirection.Local and
ConvertDirection.Remote, respectively.
v The fourth parameter of the SqlLib.Connect (formerlySysLib.Connect)
system function, commitScope, is no longer needed, so the migration tool
removes it. Also, the tool specifies the isolationLevel argument with a
value of serializableTransaction and the disconnectOption argument
with a value of explicit if these arguments are not already specified.
Some examples of how the migration tool deals with invocations of
SqlLib.Connect follow:
Table 7. Changes to calls to SqlLib.Connect
Old code Migrated code
SysLib.connect( a, b, c ); SQLLib.connect( a, b, c,
explicit,
serializableTransaction );
SysLib.connect( a, b, c, d ); SQLLib.connect( a, b, c,
explicit,
serializableTransaction );
SysLib.connect( a, b, c, d, e ); SQLLib.connect( a, b, c, e,
serializableTransaction );
SysLib.connect( a, b, c, d, e, f ); SQLLib.connect( a, b, c, e, f );
SysLib.connect( a, b, c, d, e, f, g ); SQLLib.connect( a, b, c, e, f, g );
v To maintain compatibility with rounding rules in previous versions, uses
of MathLib.round() with only one argument are changed to use
MathLib.assign(). Uses of MathLib.round() with two arguments are not
changed.
Table 8. Changes to uses of MathLib.round()
Old code Migrated code
result = round(x); assign(x, result);
result = round(x, powerOfTen); No change.
Also to maintain compatibility with rounding rules in previous versions,
the migration tool wraps calls to functions in MathLib within
MathLib.assign(). Some examples follow:
Table 9. Changes to uses of functions in MathLib
Old code Migrated code
result = abs(x); assign(abs(x), result);
result = pow(x, y); assign(pow(x, y), result);
This change affects the following functions:
– MathLib.abs()
Introduction 39
– MathLib.acos()
– MathLib.asin()
– MathLib.atan()
– MathLib.atan2()
– MathLib.cos()
– MathLib.cosh()
– MathLib.exp()
– VGLib.floatingDifference()
– VGLib.floatingMod()
– VGLib.floatingProduct()
– VGLib.floatingQuotient()
– VGLib.floatingSum()
– MathLib.frexp()
– MathLib.ldexp()
– MathLib.log()
– MathLib.log10()
– MathLib.max()
– MathLib.min()
– MathLib.modf()
– MathLib.pow()
– MathLib.sin()
– MathLib.sinh()
– MathLib.sqrt()
– MathLib.tan()
– MathLib.tanh()
Casting with system library JavaLib
In previous versions, certain arguments in certain functions in JavaLib
could accept a casting operator in parentheses. The migration tool changes
this casting to use the syntax variable as "type", as in these examples:
Table 10. Changes to casts in JavaLib functions
Old code Migrated code
(byte)myVar myVar as "java:byte"
(objId)myVar myVar as "objId:java"
(null)"java.lang.Integer" null as "java.lang.Integer"
Unnecessary conversion functions
The migration tool corrects uses of removed conversion functions. If the
conversion function is used as part of a mathematical expression, the tool
adds a cast as necessary:
Table 11. Migrated conversion functions
Old code Migrated code
result = stringAsInt(x); result = x;
result = stringAsInt(x) + 5; result = x as Int + 5;
result = stringAsFloat(x); result = x;
result = stringAsFloat(x) + 5; result = x as Float + 5;
40 EGL Programmer’s Guide
Table 11. Migrated conversion functions (continued)
Old code Migrated code
result = stringAsDecimal(x); result = x;
result = stringAsDecimal(x) + 5; result = x as Decimal() + 5;
In the case of stringAsDecimal, the migration tool does not know what
length to give the resulting DECIMAL type, so you must manually enter a
length.
Reference types
Initializations for reference types
The migration tool adds an initial size to new arrays:
Table 12. Changes to array initializers
Old code Migrated code
newArray string[]; newArray string[0];
Also, the migration tool adds an initializer to reference variable
declarations without an initializer:
Table 13. Changes to console form initializers
Old code Migrated code
newForm consoleFormType; newForm consoleFormType{};
The migration tool initializes the following reference variables in this way:
v ArrayDictionary
v BLOB
v CLOB
v Record parts with the stereotype consoleForm
v Dictionary
In a function definition containing an array with the out modifier, the
migration tool adds a new statement at the first line of the function to
initialize the array. For example, assume the following function definition:
function doSomething (myParam int[] out)
...
end
The migration tool changes this function definition to the following:
function doSomething (myParam int[] out)
myParam = new int[];
...
end
The migration tool makes this change only for arrays and only if the arrays
have the out modifier.
Assignment statements for reference types
When one reference variable is assigned to another, the migration tool
changes the assignment statement to a move statement to keep the
behavior consistent with previous versions. The following example
assumes that the variables array1 and array2 are arrays or other reference
variables:
Introduction 41
Table 14. Changes to assignment statements for reference types
Old code Migrated code
array1 = array2; move array2 to array1;
The migration tool makes this change for the following types of variables:
v Array
v Dictionary
v ArrayDictionary
v Any
v Record parts with the stereotype ConsoleForm
For assignment statements in a standalone function part, that is, a function
that is not within a logic part, the migration tool attempts to change
assignment statements to move statements under the following conditions:
v If the migration tool can resolve both sides of an assignment statement
(that is, it can determine that the variables on both sides of the
assignment statement are created from a reference type), it changes the
assignment statement to a move statement as it does in any function.
v If the migration tool cannot resolve both sides of an assignment
statement, the associated migration preference takes effect. In this case, if
the migration preference is enabled, the tool changes the assignment
statement to a move statement as above. If the migration preference is
disabled, the tool makes no change to the assignment statement.
Nullable variables
Expressions with null values
The migration tool changes expressions with null values to the new
nullability rules explained in “Language changes in EGL V7.0” on page 13.
Table 15. Migration of expressions with null values
Old code Migrated code
set myVar NULL; myVar = NULL;
myVar is NULL myVar == NULL
nullable modifier
The migration tool changes uses of the nullable modifier on function
parameters to sqlNullable.
itemsNullable build descriptor option
Depending on the preferences, the migration tool adds the
I4GLItemsNullable property to the following parts to replace the
itemsNullable build descriptor option:
v Program
v Handler
v Library
v Record
Other statements
move statements
To preserve the default behavior of the move statement in previous
versions, the migration tool adds the byName option to move statements
between two record or form variables.
42 EGL Programmer’s Guide
For statements within a standalone function, the migration tool tries to
resolve the variables on both sides of the move statement before making a
change:
v If the migration tool can resolve both sides of a move statement (that is,
it can determine that the variables on both sides of the statement are
records or forms), it adds byName as it does in any function.
v If the migration tool cannot resolve both sides of the move statement, it
adds withV60Compat instead of byName to maintain compatibility with
the previous version.
The migration tool makes this change only if it can resolve both sides of
the assignment statement, or if the associated migration preference is
enabled. If it cannot resolve both sides of the assignment statement, and
the migration preference is disabled, the migration tool makes no change.
Changes to syntax of call, transfer, and show
The migration tool changes the uses of these three statements to comply
with their new syntax:
Table 16. Changes to call and transfer
Old code Migrated code
call xxx 1, 2
norefresh
externallyDefined;
call "xxx" (1, 2)
{IsNoRefresh = yes,
IsExternal = yes};
transfer to program xxx
passing yyy
externallyDefined;
transfer to program "xxx"
passing yyy
{IsExternal = yes};
The migration tool makes a similar change to show statements.
in array expression
The migration tool converts statements that use in with an array to use
from as well:
Table 17. Changes to in with an array
Old code Migrated code
if ( a in myArray[4] ) if ( a in myArray from 4 )
exit statement changes
In logic parts other than programs and standalone functions, the migration
tool changes the statement exit program to exit rununit. The tool makes
no change to exit statements within a program or standalone function.
Services
@WSDL and @XSD properties
The migration tool converts the @WSDL property to the @XML property
and removes the @XSD property. In the process, the tool converts the
elementName property field of the @WSDL property to the name property
field of the @XML property. The isLastParamReturnValue property field of
the @WSDL property is discarded.
Services and Service Binding Libraries
The migration tool removes the serviceBindingLibrary stereotype from
Library parts.
If the preference to add Web service elements to the deployment descriptor
is enabled, the migration tool creates an EGL deployment descriptor in the
Introduction 43
project’s EGLSource folder and converts @EGLBinding and @WebBinding
properties from the interfaces in the service binding libraries into service
client binding information in that deployment descriptor. The tool copies
the WSDL file specified in the @WebBinding property to the EGLSource
folder of the current project
If the preference to add the deployment descriptor to the project’s build
descriptors is enabled, the migration tool sets the deploymentDescriptor
build descriptor option to the name of the new deployment descriptor,
which by default has the same name as the project.
If the preference to remove Web service references from the J2EE
deployment descriptor is enabled, the migration tool removes these
references.
The tool updates ServiceLib.getWebEndPoint and
ServiceLib.setWebEndPoint to ServiceLib.getWebServiceLocation and
ServiceLib.setWebServiceLocation, respectively.
PageHandler parts
Conversion to JSFHandler parts
v The migration tool changes pageHandler parts to Handler parts with the
stereotype JSFHandler.
v The tool converts the pageHandler onPageLoadFunction property to the
JSF Handler onConstructionFunction property.
v The tool adds cancelOnPageTransition = YES to all pageHandler parts
that do not have this property defined.
v The tool changes links to pages with the extension .jsp to .faces in
forward to URL statements and action properties. In forward to URL
statements, the tool makes this change only if the target of the forward
to URL statement is a quoted string that ends with .jsp. In uses of the
action property, the tool makes this change only if the displayUse
property is set to hyperlink and the action property is a quoted string
that ends with .jsp. See “Running a Web page on a server” on page 235
for more information on file extensions of JSP files. Following are
examples of these changes:
Table 18. Changes to links in pageHandlers
Old code Migrated code
myLink string
{displayUse = hyperlink,
action="myPage.jsp"};
myLink string
{displayUse = hyperlink,
action="myPage.faces"};
forward to URL "myPage.jsp"; forward to URL "myPage.faces";
v The tool converts uses of value to initialization statements. If the
variable has both a value property and an initialization statement, the
migration tool uses the value of the value property, as in the following
examples:
Table 19. Changes to the value property in variables in PageHandler parts
Old code Migrated code
item1 string
{ value = "item1ValueProp" }
= "item1Initializer";
item1 string
{} = "item1ValueProp";
44 EGL Programmer’s Guide
Table 19. Changes to the value property in variables in PageHandler parts (continued)
Old code Migrated code
item2 string
{ value = "item3ValueProp" };
item2 string
{} = "item3ValueProp";
v In some cases, the migration tool aliases variables or handler names
containing an underscore character to _005f.
JSP files
The migration tool makes changes to JSP files associated with pageHandler
parts to update references to variables in the JSF Handler. The tool makes
these changes only if you migrate the pageHandler parts at the same time
as you migrate the JSP files. These changes are in addition to the changes
that happen when the migration tool migrates the pageHandler parts to
JSF Handlers.
v For JSF tags such as <h:selectOneMenu> and any <h:selectItems> or
<h:selectItem> tag inside those tags, the migration tool updates the
value attribute to remove the EGL prefix and any suffix, such as
AsBoolean. The tool saves the changes only if the resulting value
attribute correctly references a variable in the JSF Handler.
For example, assume this <h:selectOneMenu> tag:
<h:selectOneMenu styleClass="selectOneMenu" id="menu1"
value="#{myPage.EGLmyComboBoxValue}">
<f:selectItems value="#{myPage.EGLmyComboBoxChoicesAsBoolean}"/>
</h:selectOneMenu>
The migration tool converts this tag to the following:
<h:selectOneMenu styleClass="selectOneMenu" id="menu1"
value="#{myPage.myComboBoxValue}">
<f:selectItems value="#{myPage.myComboBoxChoices}"/>
</h:selectOneMenu>
The migration tool makes this change for the following tags:
– <h:selectManyCheckboxlist>
– <h:selectManyListbox>
– <h:selectManyMenu>
– <h:selectOneListbox>
– <h:selectOneMenu>
– <h:selectOneRadio>
It also makes the change for <f:selectItems> and <f:selectItem>
within these tags.
The migration tool removes the following suffixes:
– AsBoolean
– AsInteger
– AsIntegerArray
– AsReader
– AsSelectItemsList
– AsStream
In the case that the associated EGL variable is an array or data table
column and the properties selectFromListItem and selectType are set,
the migration tool makes additional changes to the value field:
Introduction 45
– If the selectType property is set to index, the migration tool adds the
suffix _exeIdx.toArray.
– If the selectType property is set to value, the migration tool adds the
suffix .toArray.v Similarly, the migration tool removes the EGL prefix and suffixes such as
AsBoolean from the value attribute of other tags on the page when the
value attribute is in the standard expression form for EGL variables in
the JSF Handler: #{beanName.variableName}. In this case, the tool also
adds a binding attribute with the following value:
#{beanName.variableName_Ref}
Where beanName is the name of the page bean (by default, the same
name as the JSF Handler) and variableName is the name of the variable
referred to in the value attribute.
v The migration tool updates any tags with actionListener attributes,
such as those on JSF command buttons. It changes
#{beanName.commandActionListener} to
#{beanName._commandActionListener}.
v For any other JSF attribute that contains an expression in the form
#{beanName.variableName}, the migration tool removes the EGL prefix
and any suffix such as AsBoolean or AsInteger from the list above.
Other parts
ConsoleForms
Because ConsoleForm parts are now generatable parts, the migration tool
checks each ConsoleForm to see if its name matches the name of its file. If
the file name does not match, and the file name is not already being used,
the tool creates a new file with the name of the ConsoleForm and moves
the ConsoleForm part into that new file, along with any necessary import
statements. If the file name is already being used, the migration tool makes
no change, and you will have to correct your ConsoleForm parts
accordingly.
Interface parts
The migration tool removes the BasicInterface stereotype from Interface
parts. It also converts all Interface parts with the JavaObject stereotype to
ExternalType parts. Related concepts
“Setting EGL-to-EGL migration preferences” on page 34
“Changes to build descriptor options in EGL V7.0” on page 27
“Language changes in EGL V7.0” on page 13This topic lists the changes to the EGL language in version 7.0.
Related tasks
“Migrating to the current version of EGL” on page 32
Changes not made by the V7.0 migration tool
After migrating your code to V7.0, you might need to make manual changes.
Project Builders
When importing a migrated project into a V7.0 workspace, the Generation
Results view might indicate that a part could not be generated due to a
missing default build descriptor even though you have set a default build
descriptor. To resolve this issue, update the builders for the project so that
46 EGL Programmer’s Guide
the EGL Advanced Builder is listed after the EGL Build Parts Model
Builder and the EGL Validation Builder.
Follow these steps to edit the build order in this way:
1. In the Project Explorer view, right-click the project and then click
Properties.
2. In the Properties window, click Builders.
3. On the Builders page, select the EGL Advanced Builder.
4. Using the Down arrow button, move the EGL Advanced Builder
under the EGL Build Parts Model Builder and the EGL Validation
Builder.
5. Click OK.
Property resolution
If you define a part with the same name as an EGL property, EGL may
resolve references to that name with the user-defined part, rather than the
EGL property.
Casts in removed conversion functions
If you migrated a stringAsDecimal function, the migration tool may add a
cast to the DECIMAL type as necessary to maintain the behavior of the old
code. In this case, you will need to manually add a length.
For example, assume the following old code:
myStringNumber string = "5";
myResult decimal(7,2);
myResult = stringAsDecimal(myStringNumber) + 5;
The tool migrates this code to the following:
myStringNumber string = "5";
myResult decimal(7,2);
myResult = myStringNumber as decimal() + 5;
You must add a length to the DECIMAL type, as in the following:
myStringNumber string = "5";
myResult decimal(7,2);
myResult = myStringNumber as decimal(7,2) + 5;
Naming conflicts between functions and variables
You cannot have a variable and a function within a logic part with the
same name. Rename the variable or the function.
Called programs without parameter lists
Programs that are the target of a call statement must have a parameter list.
This parameter list can be empty, but the parentheses denoting the
parameter list are now required.
Service migration with IBM WebSphere® Application Server development tools
The migration tool attempts to remove outdated service references from
metadata files in the projects you migrate. However, it cannot remove the
references if either of the following circumstances apply:
v You did not install the IBM WebSphere Application Server development
tools optional component, or your version did not include IBM
WebSphere Application Server and the related development tools
v You are generating Java code into a project on which you did not run
the migration tool
In either of these cases, you must remove outdated service references from
your metadata files manually:
Introduction 47
v For EGL Web projects, if you added service references to the Web
deployment descriptor file manually, delete any EGL-generated service
references from the file and retain any manually added references. If you
did not add any service references to the file manually, you must delete
the file. In most versions of J2EE, the Web deployment descriptor is
named web.xml and is located in the project’s WebContent/WEB-INF
folder. On J2EE 1.3, the file is named webservicesclient.xml and is
located in the same place.
v Similarly, remove any EGL-generated service references from the files
ibm-webservicesclient-ext.xmi and ibm-webservicesclient-bnd.xmi, also
found in WebContent/WEB-INF. If you added no references to these files
manually, you can delete the files, but you are not required to.
selectType property in JSF Handlers
If a variable in a JSF Handler has the selectType property set to index, that
variable must be an INT type.
selectFromListItem property
When a variable has the selectFromListItem property, the property’s value
cannot be a record array or an array of primitive variables within a record.
Valid types are a data table column or an array of primitive variables not
within a record. To use a record array or an array of primitive variables
within a record as a list of selection options, use the properties
selectedRowItem or selectedValueItem instead. Related concepts
“Changes made by the V7.0 migration tool” on page 37
“Validation changes in EGL V7.0” on page 19 Related tasks
“Migrating EGL code to EGL V7.0” on page 36
“Migrating to the current version of EGL” on page 32
“Setting EGL-to-EGL migration preferences” on page 34
Migrating EGL code to EGL V6.0 iFix 001
The EGL V6.0 migration tool converts EGL source from versions V5.1.2 and V6.0 to
comply with EGL V6.0 iFix001.
Important: Do not use the migration tool on code that has already been updated
to EGL V6.0 iFix001. Doing so can create errors in your code.
The migration tool can be used on an entire project, a single file, or a selection of
files. Running the tool on a package or folder converts all of the EGL source files
in that package or folder. For more information on the code that is changed by the
migration tool, see “Changes made by the V6.0 iFix 001 migration tool” on page
49.
To migrate EGL code to EGL V6.0 iFix001, do as follows:
1. Enable the EGL migration capability:
a. Click Window → Preferences.
b. Expand General and click Capabilities.
c. Click Advanced.
d. In the Advanced window, expand EGL Developer and select the EGL V6.0
Migration check box.
e. Click OK.
48 EGL Programmer’s Guide
f. Click OK again.2. Set the preferences for the migration tool. See “Setting EGL-to-EGL migration
preferences” on page 34.
3. In the Project Explorer view, select the EGL projects, packages, folders, or files
that you want to migrate. You can select any number of EGL resources to
migrate. To select more than one resource at once, hold CTRL while clicking the
resources.
4. Right-click a selected resource and then click EGL V6.0 Migration → Migrate.
5. Optionally, you can disable the V6.0 migration capability to avoid migrating the
same code twice.
The migration tool converts the selected EGL source files to comply with EGL V6.0
iFix001. To review the changes that the tool made to the source code, do as follows:
1. In the Project Explorer view, right-click an EGL source file that has been
migrated and then click Compare With → Local History.
2. Examine the differences between the file in the workspace and the previous
version.
3. When you are finished reviewing the changes, click OK.
Related concepts
“Changes made by the V6.0 iFix 001 migration tool” Related tasks
“Migrating to the current version of EGL” on page 32
“Setting EGL-to-EGL migration preferences” on page 34
Changes made by the V6.0 iFix 001 migration tool
The EGL V6.0 migration tool converts EGL source from V5.1.2 and V6.0 to comply
with EGL V6.0 iFix 001.
Important: Do not use the migration tool on code that has already been updated
to EGL V6.0 iFix 001. Doing so can create errors in your code.
The migration tool can add comments to each file it changes. It can also add
comments to the project’s log file. See “Setting EGL-to-EGL migration preferences”
on page 34.
The migration tool changes EGL code in these ways to comply with EGL V6.0 iFix
001 :
v The migration tool makes changes to the way properties are specified. For
information about the changes to properties, see “Changes to properties during
EGL V6.0 iFix 001 migration” on page 52.
v The migration tool searches for variables and part names that conflict with
reserved words. The migration tool changes those variable and part names by
adding a prefix or suffix as defined in the migration preferences. By default, the
tool adds the suffix _EGL to any name that is now a reserved word. The
migration tool does not rename objects of the CALL statement, and it does not
update references in EGL Build Part files. The following are examples of code
before and after using the migration tool.
Before migration:
Library Handler
boolean Bin(4);
End
After migration:
Introduction 49
Library Handler_EGL
boolean_EGL Bin(4);
End
v The migration tool replaces the single equals sign (=) with the double equals
sign (==) when the single sign is used as a comparison operator. It does not
change the single equals sign when it is used as an assignment operator.
Before migration:
Function test(param int)
a int;
If(param = 3)
a = 0;
End
End
After migration:
Function test(param int)
a int;
If(param == 3)
a = 0;
End
End
v The migration tool adds level numbers to records that do not have level
numbers.
Before migration:
Record MyRecord
item1 int;
item2 int;
End
After migration:
Record MyRecord
10 item1 int;
10 item2 int;
End
v The migration tool changes the declaration syntax of constants.
Before migration:
intConst 3;
After migration:
const intConst int = 3;
v The migration tool changes variables and function names that have been moved
to different libraries or renamed. This change affects variables and functions
from the sysLib and sysVar libraries.
Before migration:
SysLib.java();
clearRequestAttr();
After migration:
JavaLib.invoke();
J2EELib.clearRequestAttr();
A list of changed variables and function names from the sysLib and sysVar
libraries follows:
Table 20. Changed variable and function names from the sysLib and sysVar libraries
Before migration After migration
SysLib.dateValue DateTimeLib.dateValue()
SysLib.extendTimestampValue DateTimeLib.extend()
50 EGL Programmer’s Guide
Table 20. Changed variable and function names from the sysLib and sysVar
libraries (continued)
Before migration After migration
SysLib.formatDate StrLib.formatDate()
SysLib.formatTime StrLib.formatTime()
SysLib.formatTimestamp StrLib.formatTimestamp()
SysLib.intervalValue DateTimeLib.intervalValue()
SysLib.timeValue DateTimeLib.timeValue()
SysLib.timestampValue DateTimeLib.timestampValue()
SysLib.java JavaLib.invoke()
SysLib.javaGetField JavaLib.getField()
SysLib.javaIsNull JavaLib.isNull()
SysLib.javaIsObjID JavaLib.isObjID()
SysLib.javaRemove JavaLib.remove()
SysLib.javaRemoveAll JavaLib.removeAll()
SysLib.javaSetField JavaLib.setField()
SysLib.javaStore JavaLib.store()
SysLib.javaStoreCopy JavaLib.storeCopy()
SysLib.javaStoreField JavaLib.storeField()
SysLib.javaStoreNew JavaLib.storeNew()
SysLib.javaType JavaLib.qualifiedTypeName()
SysLib.clearRequestAttr J2EELib.clearRequestAttr()
SysLib.clearSessionAttr J2EELib.clearSessionAttr()
SysLib.getRequestAttr J2EELib.getRequestAttr()
SysLib.getSessionAttr J2EELib.getSessionAttr()
SysLib.setRequestAttr J2EELib.setRequestAttr()
SysLib.setSessionAttr J2EELib.setSessionAttr()
SysLib.displayMsgNum ConverseLib.displayMsgNum()
SysLib.clearScreen ConverseLib.clearScreen()
SysLib.fieldInputLength ConverseLib.fieldInputLength()
SysLib.pageEject ConverseLib.pageEject()
SysLib.validationFailed ConverseLib.validationFailed()
SysLib.getVAGSysType VGLib.getVAGSysType()
SysLib.connectionService VGLib.connectionService()
SysVar.systemGregorianDateFormat VGVar.systemGregorianDateFormat
SysVar.systemJulianDateFormat VGVar.systemJulianDateFormat
SysVar.currentDate VGVar.currentGregorianDate
SysVar.currentFormattedDate VGVar.currentFormattedGregorianDate
SysVar.currentFormattedJulianDate VGVar.currentFormattedJulianDate
SysVar.currentFormattedTime VGVar.currentFormattedTime
SysVar.currentJulianDate VGVar.currentJulianDate
SysVar.currentShortDate VGVar.currentShortGregorianDate
Introduction 51
Table 20. Changed variable and function names from the sysLib and sysVar
libraries (continued)
Before migration After migration
SysVar.currentShortJulianDate VGVar.currentShortJulianDate
SysVar.currentTime DateTimeLib.currentTime
SysVar.currentTimeStamp DateTimeLib.currentTimeStamp
SysVar.handleHardIOErrors VGVar.handleHardIOErrors
SysVar.handlesysLibErrors VGVar.handlesysLibraryErrors
SysVar.handleOverflow VGVar.handleOverflow
SysVar.mqConditionCode VGVar.mqConditionCode
SysVar.sqlerrd VGVar.sqlerrd
SysVar.sqlerrmc VGVar.sqlerrmc
SysVar.sqlIsolationLevel VGVar.sqlIsolationLevel
SysVar.sqlWarn VGVar.sqlWarn
SysVar.commitOnConverse ConverseVar.commitOnConverse
SysVar.eventKey ConverseVar.eventKey
SysVar.printerAssociation ConverseVar.printerAssociation
SysVar.segmentedMode ConverseVar.segmentedMode
SysVar.validationMsgNum ConverseVar.validationMsgNum
v The migration tool sets the HandleHardIOErrors property to NO for all migrated
libraries, programs, and pageHandlers for which that property is not specified.
Related tasks
“Migrating EGL code to EGL V6.0 iFix 001” on page 48 Related concepts
“Migrating to the current version of EGL” on page 32
“Setting EGL-to-EGL migration preferences” on page 34
“Changes to properties during EGL V6.0 iFix 001 migration”
Changes to properties during EGL V6.0 iFix 001 migration
The V6.0 migration tool makes significant changes to the way properties are
specified. A summary of these changes follows:
v The migration tool renames properties whose names have changed in EGL V6.0
iFix 001:
Table 21. Renamed properties
Before migration After migration
action actionFunction
boolean isBoolean
getOptions getOptionsRecord
msgDescriptor msgDescriptorRecord
onPageLoad onPageLoadFunction
openOptions openOptionsRecord
putOptions putOptionsRecord
queueDescriptor queueDescriptorRecord
52 EGL Programmer’s Guide
Table 21. Renamed properties (continued)
Before migration After migration
range validValues
rangeMsgKey validValuesMsgKey
selectFromList selectFromListItem
sqlVar sqlVariableLen
validator validatorFunction
validatorMsgKey validatorFunctionMsgKey
validatorTable validatorDataTable
validatorTableMsgKey validatorDataTableMsgKey
v The migration tool adds double quotes to property values that are used as string
literals.
Before migration:
{ alias = prog }
After migration:
{ alias = "prog" }
The following properties are affected:
– alias
– column
– currency
– displayName
– fileName
– fillCharacter
– help
– helpKey
– inputRequiredMsgKey
– minimumInputMsgKey
– msgResource
– msgTablePrefix
– pattern
– queueName
– rangeMsgKey
– tableNames
– title
– typeChkMsgKey
– validatorMsgKey
– validatorTableMsgKey
– value
– view
v The migration tool replaces parentheses with brackets when specifying array
literals as values for the following properties:
– formSize
– keyItems
– outline
Introduction 53
– pageSize
– position
– range
– screenSize
– screenSizes
– tableNames
– tableNameVariables
– validationBypassFunctions
– validationBypassKeys
v For properties that take array literals, the migration tool puts single element
array literals in brackets to specify that an array with only one element is still an
array. The migration tool uses double sets of brackets for properties that take
arrays of arrays.
Before migration:
{ keyItems = var, screenSizes = (24, 80), range = (1, 9) }
After migration:
{ keyItems = ["var"], screenSizes = [[24, 80]], range = [[1, 9]] }
v The migration tool uses the keyword this instead of a variable name when
overriding properties for a specific element in an array.
Before migration:
Form myForm type TextForm
fieldArray char(10)[5] { fieldArray[1] {color = red } };
end
After migration:
Form myForm type TextForm
fieldArray char(10)[5] { this[1] {color = red } };
end
v The migration tool changes references to parts, functions, and fields, adding
quotes and brackets where appropriate.
Before migration:
{ keyItems = (item1, item2) }
After migration:
{ keyItems = ["item1", "item2"] }
The following properties are affected by the migration tool in this way:
– action
– commandValueItem
– getOptions
– helpForm
– inputForm
– inputPageRecord
– inputRecord
– keyItem
– keyItems
– lengthItem
– msgDescriptorRecord
– msgField
– numElementsItem
54 EGL Programmer’s Guide
– onPageLoadFunction
– openOptionsRecord
– putOptionsRecord
– queueDescriptorRecord
– redefines
– selectFromListItem
– tableNameVariables
– validationBypassFunctions
– validatorFunction
– validatorDataTable
v The migration tool assigns a default value of yes to any boolean properties that
were specified but not assigned a value.
Before migration:
{ isReadOnly }
After migration:
{ isReadOnly = yes}
The following properties are affected by the migration tool in this way:
– addSpaceForSOSI
– allowUnqualifiedItemReferences
– boolean
– bypassValidation
– containerContextDependent
– currency
– cursor
– deleteAfterUse
– detectable
– fill
– helpGroup
– includeMsgInTransaction
– includeReferencedFunctions
– initialized
– inputRequired
– isDecimalDigit
– isHexDigit
– isNullable
– isReadOnly
– lowerCase
– masked
– modified
– needsSOSI
– newWindow
– numericSeparator
– openQueueExclusive
– pfKeyEquate
– resident
Introduction 55
– runValidatorFromProgram
– segmented
– shared
– sqlVar
– upperCase
– wordWrap
– zeroFormat
v The migration tool splits the currency property into two properties: currency
and currencySymbol. The following table gives some examples of how the
migration tool changes the currency property.
Table 22. Changes to the currency property
Before migration After migration
{ currency = yes } { currency = yes }
{ currency = no } { currency = no }
{ currency = "usd" } { currency = yes, currencySymbol = "usd"
}
v The migration tool changes the values of the dateFormat and timeFormat
properties to be case sensitive. For more information, see ″Date, time, and
timestamp format specifiers″ in the EGL Language Reference.
v If the Add qualifiers to enumeration property values check box is selected in
the preferences menu, the migration tool adds the name of the enumeration to
the value of the property.
Before migration:
color = red
outline = box
After migration:
color = ColorKind.red
outline = OutlineKind.box
This change affects the following properties:
– align
– color
– deviceType
– displayUse
– highlight
– indexOrientation
– intensity
– outline
– protect
– selectType
– sign
v The migration tool changes the values of the tableNames property to be an
array of arrays of strings. Each array of strings must have either one or two
elements. The first element is the table name, and the second element, if present,
is the table label. The following table gives some examples of how the migration
tool changes the tableNames property.
56 EGL Programmer’s Guide
Table 23. Changes to the tableNames property
Before migration After migration
{ tableNames = (table1, table2) } { tableNames = [["table1"], ["table2"]] }
{ tableNames = (table1 t1, table2) } { tableNames = [["table1", "t1"],
["table2"]] }
{ tableNames = (table1 t1, table2 t2) } { tableNames = [["table1", "t1"],
["table2", "t2"]] }
v The migration tool changes the way dates, times and timestamps are specified,
including changing the values of the dateFormat and timeFormat properties to
be case sensitive. Following are some examples:
Table 24. Changes to dates, times, and timestamps
Before migration After migration
dateFormat = "yy/mm/dd" dateFormat = "yy/MM/dd"
dateFormat = "YYYY/MM/DD" dateFormat = "yyyy/MM/dd"
dateFormat = "YYYY/DDD" dateFormat = "yyyy/DDD"
timeFormat = "hh:mm:ss" timeFormat = "HH:mm:ss"
v The migration tool changes the values of the defaultSelectCondition property to
be of type sqlCondition.
Before migration:
{ defaultSelectCondition =
#sql{
hostVar02 = 4
}
}
After migration:
{ defaultSelectCondition =
#sqlCondition{ // no space between #sqlCondition and the brace
hostVar02 = 4
}
}
v The migration tool replaces the NULL value of the fillCharacter to the empty
string value "".
Related tasks
“Migrating EGL code to EGL V6.0 iFix 001” on page 48
“Setting EGL-to-EGL migration preferences” on page 34
“Migrating to the current version of EGL” on page 32 Related concepts
“Changes made by the V6.0 iFix 001 migration tool” on page 49
Features not supported in this version
EGL V7.0 temporarily removes support for some features included in previous
versions.
The following areas of functionality are not supported in this version:
v Text User Interface, including FormGroups, the Form Editor, the system library
ConverseLib, and the ConverseVar system variable
Introduction 57
v DL/I, IMS, and GSAM data access, including the system library DLILib and the
DLIVar system variable
v WebSphere MQ data access
v Web transactions
v VisualAge Generator migration tool. Only the migration tool itself is
unsupported in this version; the VisualAge Generator compatibility mode is
supported, along with most VAGen compatibility options, the system library
VGLib, and the system variable VGVar.
v The statement exit stack
v Java wrapper generation, including the ejbCall type of the callLink element of
the linkage options part.
For a list of build descriptor options that are not supported in this version, see
″Removed build descriptor options″ in “Changes to build descriptor options in
EGL V7.0” on page 27.
Related concepts
“What’s new in EGL V7.0” on page 12
58 EGL Programmer’s Guide
Contents of an EGL application
This topic describes the artifacts found in a typical EGL application.
Projects
An EGL application contains one or more projects to hold and organize your code
in folders and files. A project is contained in a single physical folder in your
workspace, and that folder contains other folders, as described below.
You can have as many projects as you want, and those projects can be independent
or they can reference each other and use parts from each other’s packages. The
needs of your organization and design of the application that you are creating
determines your use of projects, packages, and files. There are no set guidelines for
how to use them. See “The EGL build path” on page 71 for information on
references between projects.
Folders
An EGL project can contain several folders. Some of these folders have default
names; for example, the EGL source files go in a folder named EGLSource by
default. The documentation often refers to these folders by their default name, but
be aware that they might have different names in your project.
Source code folder
EGL projects have at least one source code folder, named EGLSource by
default. The source folder contains all of the EGL source files, build files,
and deployment descriptor files for the project. EGL generates output code
only for files within a source code folder.
You can create packages within source folders or additional source code
folders to organize your files. See “Creating an EGL package” on page 76
or “Creating source folders” on page 74.
Generated code folder
When you are generating to Java, the EGL project has a folder to hold the
files that are created by the generation process. By default, the generated
code folder is named JavaSource. Do not edit the files in the generated
code folder, because they are overwritten each time you generate the
project.
For COBOL output, EGL puts the generated code into a directory outside
the workspace as specified by the genDirectory build descriptor option.
EGL then transfers the outputs to the target system based on the destHost
and other related build descriptor options.
EGLBin folder
The EGLBin folder is used to store .ir files, which are used by EGL in the
generation and debugging processes. Generally, you can ignore these files,
because EGL usually creates them automatically from your source code
and build files when the project is built.
By default, the workbench builds your projects automatically, prompting
EGL to create or update the .ir files. If you have turned off the automatic
© Copyright IBM Corp. 1996, 2007 59
builds, you can set a preference within EGL to build your projects when
necessary by clicking Window → Preferences → EGL → Generation and
selecting Build before generate.
However, if automatic builds and the EGL Build before generate
preference are both disabled, you must invoke a build manually before
generating or debugging. Otherwise, EGL will not have current .ir files
with which to generate your code; this situation might mean that the
generated output represents outdated source code, or that the generation
process will not have all the parts it needs to generate. To build a project,
select the project in the Project Explorer view and then click Project →
Build Project. To turn on automatic builds, click Project, and select Build
Automatically.
Web content folder
For EGL Web projects, the Web content folder contains the Web pages,
style sheet files, and other files that control how the Web project will
display in a browser. By default, the Web content folder is named
WebContent. See “Elements of a Web application” on page 183 for
information on the files specific to Web projects.
Packages
Packages are contained within source folders and group source files.
META-INF folder
For EGL plug-in projects, the META-INF folder contains the
MANIFEST.MF file.
Files
The two major types of EGL files are source files, files that contain EGL parts such
as programs, libraries, and records, and build files, files that contain EGL build
parts such as build descriptors. Generally, you will not have to spend much time
working with other types of files. The following is a list of the files most
commonly found in an EGL project:
Source files
Source files contain EGL logic parts and data parts, such as programs and
records. Source files always end in the extension .egl.
Build files
Build files contain EGL build parts, such as build descriptors. These files
have the extension .eglbld.
Deployment descriptors
EGL deployment descriptors, not to be confused with J2EE deployment
descriptors, contain information about deployment. These files have the
extension .egldd.
Web pages
EGL Web projects can contain one or more JSP Web pages controlled by
JSF Handler parts.
.eglpath
The EGL build path file is named .eglpath and is stored in the root of the
project. This file lists the locations that are searched for any part that is not
found in the current project, including the source folders in the current
project and any other projects on the build path of the current project.
60 EGL Programmer’s Guide
In the following example of an .eglpath file, EGLSource is a source folder
in the current project, and AnotherProject is a project in the EGL build
path:
<?xml version="1.0" encoding="UTF-8"?>
<eglpath>
<eglpathentry kind="src" path="EGLSource"/>
<eglpathentry kind="src" path="\AnotherProject"/>
</eglpath>
The source folders for AnotherProject are determined from the .eglpath file
in that project.
For more information, see “The EGL build path” on page 71.
.eglproject
This file contains basic information about the EGL project, such as where
its default build descriptors are located.
faces-config.xml
For EGL Web projects, EGL uses the JSF configuration file to determine
how to navigate from page to page. See “Elements of a Web application”
on page 183 for information on the JSF configuration file and for other files
related to EGL Web projects.
plugin.xml
For EGL plug-in projects, the plugin.xml file describes the extensions that
your project adds to the Eclipse framework. More specifically, this file
contains an entry for the EGL ″player″ that controls the runtime operations
of Console UI applications that are running in rich client platform (RCP)
mode. Also, when you generate a project, EGL adds a reference in the
plugin.xml file for each Console UI program in the project. This reference
is needed only when running a Console UI program in RCP mode. You
will rarely need to edit the reference.
MANIFEST.MF
The MANIFEST.MF file describes the requirements for the project to run as
an RCP application. This file is tied closely to the plugin.xml file.
Transformation parameter files
When creating EGL code from a UML model, you create a .TPM file that
specifies options for the transformation.
Other files
Your project might contain any number of other files that are not directly
related to EGL. For information about those types of files, use the search
function of the help system. Related tasks
“Creating an EGL project” on page 62This topic covers how to create an EGL project.
“Creating EGL source files” on page 77
Introduction to EGL projects
In the Eclipse workbench, a project is a group of related files. EGL adopts this
framework and keeps its source files in three types of EGL projects. These projects
differ mainly in the types of user interface they support:
Contents of an EGL application 61
EGL project
A standard EGL project is useful for batch applications or anything with a
simple user interface.
EGL Web project
EGL Web projects have all of the abilities of a standard EGL project, plus
the ability to create applications with Web interfaces. You cannot convert
any other type of project into an EGL Web project.
EGL plug-in project
EGL plug-in projects have all of the abilities of a standard EGL project plus
the ability to run Console UI programs in rich client platform (RCP) mode.
You can convert other types of EGL projects into an EGL plug-in project.
The project type is determined by selecting EGL, EGL Web, or EGL Plug-in when
you create a new project.
EGL projects can also have additional features and facets added to them to add
support for more granular pieces of functionality. See “Features and facets of EGL
projects” on page 66.
Depending on the target server for the project, EGL Web projects can be connected
to an Enterprise Application Resource (EAR) project. EAR projects contain
information for deployment in the J2EE application framework.
Related tasks
“Creating an EGL project”This topic covers how to create an EGL project.
“Creating an EGL Web project” on page 63This topic covers how to create an EGL Web project.
Creating an EGL project
This topic covers how to create an EGL project.
To create an EGL project:
1. From the menu bar, click File → New → Project. The New Project window
opens.
2. In the New Project window, expand EGL and click EGL Project. If you do not
see the type of project you want to create, select the Show All Wizards check
box.
3. Click Next.
4. Type a name for the project in the Project name field.
5. Accept the default location for the project in the Project location field or clear
the Use default check box and specify a new location.
6. Under Target Runtime Platform, select the language to which EGL will
generate your project: Java or COBOL.
7. Under Build Descriptor Options, choose where the default build descriptors
of the project will be located or created:
v Create new project build descriptors automatically means that EGL
provides build descriptors and writes them to a build file (extension
.eglbld) that has the same name as the project.
To specify some of the values in those build descriptors, click Options. To
change those values later, change the build file that is created for you.
For further details, see ″Specifying database options at project creation″.
62 EGL Programmer’s Guide
v Use build descriptor specified in EGL preference means that EGL points
to a build descriptor that you created and identified as an EGL preference.
v Select existing build descriptor enables you to specify a build descriptor
from those that are available in your workspace. 8. Under EGL Project Features Choices, select the check boxes for the additional
features to include in the project, if any. See “Features and facets of EGL
projects” on page 66 for more information.
9. When you have filled out the information on the first page, you can click
Finish to complete the process and create the project with the default options
or click Next to continue setting the remainder of the options. These
instructions continue with the remainder of the options.
10. On the Projects tab of the EGL Settings page, select any other projects in your
workspace to be added to the build path of the new project.
11. On the Order and Export tab of the EGL settings page, set the order for the
projects in the build path and select the check boxes for the projects that you
want to export along with the new project.
12. Click Finish. Related concepts
“Introduction to EGL projects” on page 61
“Contents of an EGL application” on page 59This topic describes the artifacts found in a typical EGL application.
Related tasks
“Creating an EGL Web project”This topic covers how to create an EGL Web project.
“Creating an EGL plug-in project” on page 65EGL plug-in projects are useful for Console UI applications that you want to
run in rich client platform (RCP) mode. You can create a new EGL plug-in
project or convert an existing EGL project or EGL Web project to an EGL
plug-in project.
“Specifying database options at project creation” on page 160
Creating an EGL Web project
This topic covers how to create an EGL Web project.
The steps for creating an EGL Web project are similar to those for creating an EGL
project, but include additional steps for the target server for the project. To set up a
new EGL Web project:
1. From the menu bar, click File → New → Project The New Project window
opens.
2. In the New Project window, expand EGL and click EGL Web Project. If you
do not see the type of project that you want to create, select the Show All
Wizards check box.
3. Click Next.
4. Type a name for the project in the Project name field.
5. Accept the default location for the project in the Project location field or clear
the Use default check box and specify a new location.
6. Under Build Descriptor Options, choose where the default build descriptors
of the project will be located or created:
Contents of an EGL application 63
v Create new project build descriptors automatically means that EGL
provides build descriptors and writes them to a build file (extension
.eglbld) that has the same name as the project.
To specify some of the values in those build descriptors, click Options. To
change those values later, change the build file that is created for you.
For further details, see ″Specifying database options at project creation″.
v Use build descriptor specified in EGL preference means that EGL points
to a build descriptor that you created and identified as an EGL preference.
v Select existing build descriptor enables you to specify a build descriptor
from those that are available in your workspace. 7. If you requested that a build descriptor be created automatically, you can
place a value in the JNDI name for SQL connection field. The effect is to
assign the name to which the default data source is bound in the JNDI
registry at debug or generation time. (An example value is java:comp/env/jdbc/MyDB.) Your selection assigns a value to the sqlJNDIName build
descriptor option. If the JNDI name for SQL connection field is already
populated, the value was obtained from a Workbench preference, as described
in ″Setting preferences for SQL database connections.″
8. Choose a runtime and an EAR project for the project, as applicable. These
fields are closely related. If your project is associated with an EAR project,
your new Web project must use the same runtime as the EAR project.
Conversely, your choice of runtimes affects your options for EAR projects,
since not all runtimes support EAR projects. Follow these guidelines:
v If you select the Add project to an EAR check box and choose an existing
EAR project in the EAR Project Name list, the Target Runtime field is
unavailable, because your project will use the EAR project’s target runtime.
v If you type a name for a new EAR project in the EAR Project Name list, the
new EAR and EGL Web projects will both use the runtime selected in the
Target Runtime field. By default, the name of the new EAR project is the
name of the EGL Web project with the suffix EAR.
v If you use the New button to create a new EAR project, the new EGL Web
project will use the same runtime as you specify for the new EAR project.
v If you select a target runtime that does not support EAR projects, the EAR
Project Name field is disabled.
v You are not required to select a runtime now, unless you add the project to
an EAR project with a defined runtime. However, you must choose a
runtime before you can run the project on a server or deploy the project. It
is best to choose a runtime now; you can change the target runtime later. 9. After you have filled out the information on the first page, you can click
Finish to complete the process and create the project with the default options,
or click Next to continue setting the remainder of the options. These
instructions continue with the remainder of the options.
10. On the Project Facets page, select any facets that you may want to add to your
project or select a preset facet configuration. See “Features and facets of EGL
projects” on page 66.
11. Click Next.
12. In the Context Root field, type a name for the root folder of the project when
the project is deployed to a Web server or accept the default, which the same
as the project name.
13. In the Content Directory field, type the name for the Web content folder. The
default name is WebContent.
64 EGL Programmer’s Guide
14. In the Java Source Directory field, type the name for the generated code
folder. The default name is src.
15. Click Finish. Related concepts
“Introduction to EGL projects” on page 61
“Contents of an EGL application” on page 59This topic describes the artifacts found in a typical EGL application.
Related tasks
“Creating an EGL project” on page 62This topic covers how to create an EGL project.
“Creating an EGL plug-in project”EGL plug-in projects are useful for Console UI applications that you want to
run in rich client platform (RCP) mode. You can create a new EGL plug-in
project or convert an existing EGL project or EGL Web project to an EGL
plug-in project.
“Adding JSF component interface support to an EGL Web project” on page 246
“Setting preferences for SQL database connections” on page 181
Creating an EGL plug-in project
EGL plug-in projects are useful for Console UI applications that you want to run in
rich client platform (RCP) mode. You can create a new EGL plug-in project or
convert an existing EGL project or EGL Web project to an EGL plug-in project.
Creating a new project
1. From the menu bar, click File → New → Project. The New Project window
opens.
2. In the New Project window, expand EGL, and click EGL Plug-in Project. If you
do not see EGL Plug-in Project, select the Show All Wizards check box.
3. Click Next.
4. Fill in the remainder of the options for your project, including the name and
the build descriptor options. The remainder of the options are the same as
those for an EGL project. See “Creating an EGL project” on page 62.
5. When you are finished, click Finish.
Converting a project
To convert an EGL project or an EGL Web project to an EGL plug-in project,
right-click the project in the Project Explorer view and then click Convert to EGL
Plug-in Project.
Related tasks
“Creating an EGL project” on page 62This topic covers how to create an EGL project.
“Creating an EGL Web project” on page 63This topic covers how to create an EGL Web project.
Related concepts
“Contents of an EGL application” on page 59This topic describes the artifacts found in a typical EGL application.
“Building EGL Console User Interface applications” on page 267Console User Interface, or Console UI, is a style of user interface similar to that
used on a UNIX-based program that interacts with a character-based terminal.
Contents of an EGL application 65
“Console UI modes” on page 281EGL supports three modes in which you can run Console UI applications:
Swing, Curses, and rich client platform (RCP). The three modes have different
abilities, but in general a Console UI application behaves the same way in each
mode.
Features and facets of EGL projects
EGL projects can have additional abilities, added through features and facets.
Features
EGL project features add support for a particular behavior or type of project. After
you add a feature to a project, you cannot remove it, although there is rarely any
reason to remove a feature. The features that a project can have depend on the
type of project; if you do not see a particular feature as an option for your project,
make sure you are using the correct type of EGL project.
You can specify features at project creation or add features to a project later. To add
features at project creation, see “Creating an EGL project” on page 62. To add a
feature to an existing project, follow these steps:
1. In the Project Explorer view, right-click the project and then click Properties.
The Properties window opens.
2. Click EGL Project Features. The check boxes under EGL Project Features
Choices are the features that you can apply to your project.
3. Select the check boxes next to the features that you want to add to your project.
If a check box is already selected, that feature has already been added to the
project and you cannot remove it.
4. Click OK.
You can also choose the features that are applied to your new EGL projects by
default:
1. Click Window → Preferences. The Preferences window opens.
2. Click EGL.
3. Under Default EGL Project Features Choices, select the features to you add to
each new project by default.
For more information about what the features do, see the individual topic that
explains how to add the feature to your project.
Facets
Facets define characteristics and requirements for projects in the J2EE framework.
Unlike EGL project features, which in this context are exclusive to EGL projects,
project facets can be applied to any project that behaves as a J2EE module, with
certain restrictions. Therefore, within EGL, you can add features only to EGL Web
projects and EGL Web projects that have been converted to EGL plug-in projects.
Like project features, you can add facets at project creation or add them to an
existing project. Follow these steps to add a facet to an existing project:
1. In the Project Explorer view, right-click the EGL Web project and then click
Properties. The Properties window opens.
2. Click Project Facets. The list shows the facets currently in the project.
3. ClickAdd/Remove Project Facets. The Project Facets window opens.
66 EGL Programmer’s Guide
4. In the Project Facets window, select the check boxes next to the facets tat you
want this project to have.
Only the facets that are valid for the project are listed:
v The list of runtimes selected for the project limits the facets shown in the list.
Only the facets that are compatible with all selected target runtimes are
shown.
v The currently selected facets and their version numbers limit the other facets
shown in the list. For example, if the project contains the Dynamic Web
Module facet, the EJB Module facet is not listed because these two facets
cannot be in the same project.
You can find out more about the requirements and limitations for each facet by
right-clicking the facet name and then clicking Show Constraints. You can also
choose a preset combination of facets from the Configurations list.
5. Choose a version number for the facet by clicking the current version number
and selecting the version number from the drop-down list.
6. To remove a facet, clear its check box. Not all facets can be removed.
7. If you want to limit the project so that it will be compatible with one or more
runtimes, click the Show Runtimes button and select the runtimes that you
want the project to be compatible with.
8. Click Finish.
9. Click OK.
You can also choose the facets that are applied to your new EGL Web projects by
default:
1. Click Window → Preferences. The Preferences window opens.
2. Click EGL.
3. Under Default EGL Web Project Facet Choices, select the facets that you want
to be added to each new EGL Web project by default.
Unlike project features, some facets can be removed from a project. Also unlike
project features, facets have version numbers, and facets can depend on the
presence or absence of other facets and specific version numbers of those facets.
Project features do not have version numbers.
Like project features, facets can depend on certain project types. For more
information on the EGL-specific facets, see the individual topic that explains how
to add the facet to your project.
Related tasks
“Adding JSF component interface support to an EGL Web project” on page 246
“Adding support for Jasper reports to a project” on page 300Before you can create reports with EGL, you must add support for Jasper
reports to your project and add a Java compiler to your system’s path variable.
Sharing projects
This topic explains the options for sharing projects between computers, as well as
some of the possible problems in doing so.
There are two main ways of transferring projects or files to another computer or
workspace:
v Storing them in a source repository and version control system, such as CVS or
Rational ClearCase®. This method provides the best results for development
Contents of an EGL application 67
code for many reasons, including the ability to synchronize changes, resolve
conflicts, and collaborate on code. See “Sharing projects in a repository” on page
71.
v Exporting an EGL project to the local file system. This method is appropriate
when you want to share a project a single time. See “Importing and exporting
projects” on page 69.
Files to share
Generally, share only the files that someone else needs to work with the project. Do
not share any files that can be generated from other files.
Share the following files, unless you have a reason not to do so:
v EGL source files
v EGL build files
v EGL deployment descriptors
v Non-derived metadata files in the project, such as .eglpath and .eglproject
files
v Files necessary for Web projects to run on a server, including faces-config.xml,
JSP files, web.xml, and files in the Enterprise Application Resource project, if you
have one
Do not share the following files in a repository unless you have a reason to do so:
v Derived files, including the .ir files found in the EGLBin folder
v Output files generated from EGL source files, such as .java files and .class files
Regardless of the type of project, do not share derived files. Derived files are
generated from source files and are not original data, so it is usually unnecessary
to share them. In the context of EGL Java generation, derived files include the Java
source files that are created during the generation process as well as the Java class
files created from those Java source files. EGL source files and build files are not
considered derived, but .ir files created from the source files are derived.
Including derived files increases the size of the artifacts that you share. Moreover,
including derived files might not be useful because they can be regenerated and
overwritten when the files are imported into another workspace. However, you
may want to share derived files if the person you are sharing the project with
cannot generate the derived files, or if you are trying to diagnose problems with
the derived files.
The workbench maintains a flag on each file to specify whether the file is derived
or not. For example, class files created from Java files and .ir files created from
EGL source files are automatically marked as derived. However, the workbench
does not mark Java source files as derived, even if they are generated from EGL
source files. In EGL, these Java source files are still considered derived because
they are created from EGL source files.
You can see whether a file is marked as derived by right-clicking the file in the
Project Explorer view or Navigator view, clicking Properties and moving to the
Info page. (You may want to use the Navigator view to examine derived files
because the Project Explorer view filters out some types of derived files, such as
EGL .ir files.) If the Derived check box on the file’s Properties window is selected,
the file is marked as derived. However, many sharing methods (including Project
68 EGL Programmer’s Guide
Interchange files and some types of repositories) do not retain the derived flag. If
you share a derived file and someone else checks out the file, that file will no
longer be marked as derived.
For more information on which files are considered derived and why you would
or would not want to include them, see ″Derived resources″ in the online help.
Possible errors
When sharing projects, dependencies and links within the projects can break as the
projects are moved to different locations. The following are some common tasks
that you might need to perform to correct errors that you encounter while sharing
projects:
v Correct project dependencies, if it has other projects in its build path.
v Make sure that the project can find imported parts in the new location, if any
source files use import statements to refer to other EGL parts.
v Verify that links between Web pages still work. Related concepts
“Introduction to EGL projects” on page 61 Related tasks
“Importing and exporting projects”The workbench includes several ways to import projects and files from your
local file system and export them to your local file system.
“Sharing projects in a repository” on page 71These general guidelines describe EGL files that you will most likely share in a
repository or source-control system. The guidelines also cover some common
problems you might encounter when sharing EGL projects.
Importing and exporting projects
The workbench includes several ways to import projects and files from your local
file system and export them to your local file system.
Importing and exporting with Project Interchange
Project Interchange files are archive files that contain one or more projects, making
them appropriate for sharing entire projects at once. Follow these steps to export
one or more of your projects as a Project Interchange file:
1. Click File → Export. The Export window opens.
2. Under Select an export destination, expand Other and click Project
Interchange.
3. Click Next.
4. On the Export Projects page, select the check boxes next to the projects that you
want to export in the Project Interchange file.
5. In the To zip file field, select the name and location for the exported file.
6. If you want to include derived files in the exported file, select the Include
derived files check box.
See “Sharing projects” on page 67 for information on derived files. Derived files
generated from source files and are not original data, so it is typically
unnecessary to include them when sharing projects.
7. Click Finish.
Contents of an EGL application 69
Follow these steps to import one or more of the projects in a Project Interchange
file:
1. Click File → Import. The Import window opens.
2. Under Select an import source, expand Other and click Project Interchange.
3. Click Next.
4. On the Import Projects page, select the projects you want to import.
5. Click Finish.
Importing and exporting individual files
With the workbench, you can also import and export individual files as separate
files or as a single archive file. Follow these steps to export individual files from
your workspace to your local file system:
1. Click File → Export.
2. In the Export window, expand General and choose a format for your output
files. These are some of the common formats:
v File System exports files to your local file system as individual files, the
same as they are within the workbench.
v Archive File compresses files into an archive file and saves that archive file
to your local files system.3. Click Next.
4. Select the files that you want to export and select a location for the exported
file or files.
5. Click Finish.
To import files into your workspace, you must first have a project to put the new
files in. Follow these steps to import individual files into your workspace from
your file system:
1. Click File → Import.
2. In the Import window, select the type of file you want to import. These are
some of the common formats:
v File System imports one or more files directly into a project in your
workspace.
v Archive File extracts one or more files from an archive file and imports those
files into the workspace.3. Click Next.
4. Select the location of the files that you want to import and the folder in your
workspace into which you want to import the files.
5. Click Finish. Related concepts
“Introduction to EGL projects” on page 61
“Sharing projects” on page 67This topic explains the options for sharing projects between computers, as well
as some of the possible problems in doing so. Related tasks
“Sharing projects in a repository” on page 71These general guidelines describe EGL files that you will most likely share in a
repository or source-control system. The guidelines also cover some common
problems you might encounter when sharing EGL projects.
70 EGL Programmer’s Guide
Sharing projects in a repository
These general guidelines describe EGL files that you will most likely share in a
repository or source-control system. The guidelines also cover some common
problems you might encounter when sharing EGL projects.
The way that you share your projects in a repository or source-control system
depends on the type of repository or source-control system. In general, share
source files and build files but not derived files, files that are created from other
files. This way, the files in the repository are limited to only those necessary for the
application. (If you edit a file directly, it is probably not derived.) For a discussion
of derived files in the context of EGL, see “Sharing projects” on page 67.
Also, when you share projects in a repository, be aware of these possible problems:
v If derived files are checked into a repository, they often lose their derived flags.
In this case, files that you normally wouldn’t check into a repository may appear
to need to be stored in a repository.
v Checking files into a repository can break connections between files. For
example, if you check a UML model and a TPM file into a repository and then
check them back out again, the workbench might not know that the two are
associated.
v When sharing projects in a repository, the projects are subject to the same
potential errors as described in “Sharing projects” on page 67. Related concepts
“Introduction to EGL projects” on page 61
“Sharing projects” on page 67This topic explains the options for sharing projects between computers, as well
as some of the possible problems in doing so. Related tasks
“Importing and exporting projects” on page 69The workbench includes several ways to import projects and files from your
local file system and export them to your local file system.
The EGL build path
EGL projects contain a build path, which lists other EGL projects that you want to
use in the current project.
For example, suppose project A contains a Record part and you want to create a
variable based on that Record part in project B. You could copy the source file
from project A into project B, but that would mean duplicating the file. Instead,
you can add project A to the build path of project B. Then, you can use the Record
part in project B as though the definition were in project B. Scoping rules still
apply, however, so you might need to import the part to bring it into scope.
A project build path includes the following items:
v A list of EGL source folders in the current project
v The location of the generated output folder, which is meaningful only for Java
generation
v Zero to many projects to include in the build path
Adding other projects to the build path is useful only while you are coding; for
example, the EGL build path enables content assist to find other parts and insert
correct import statements. The EGL build path also provides a way for validation
to flag unknown parts and functions. If you are generating to Java, to allow your
Contents of an EGL application 71
project to use parts in another project at run time, you must make that project
available at run time. See “Editing the build path” on page 73.
The order of the items in the build path is significant because EGL searches for
parts based on the order of the folders and projects in the build path. See ″Name
resolution in an expression″ in the EGL Language Reference. For this reason, the
source folders of the current project are usually the first items in the build path.
You can also choose to export a project or source folder in your build path. In this
case, the exported project or source folder is available to all projects that refer to
the current project. For example, take the following project build paths:
v Project C
C, D, Y
v Project D
D, E, Z
If, in the build path for project D, you choose to export project E but not project Z,
the effective build path for project C is as follows:
C, D, E, Y
In this case, project D can use project Z, because Z is in D’s build path. However,
project C cannot use project Z because Z, is not exported along with project D.
Project C can use project E, because project E is exported along with project D.
When working with multiple EGL projects, you should be careful not to create
packages with identical names in two different projects. Also, you must be careful
to avoid circular references, that is, build paths that make an infinite loop.
To add or remove projects in the build path, or to set exporting for a project on the
build path, see “Editing the build path” on page 73.
In general, the build path information is stored in the .eglpath file in the root of
the project. However, if you generate output code using the EGL SDK, the build
path is determined through the command-line argument eglpath, which is a list of
operating-system directories that are searched when the EGL SDK attempts to
resolve a part reference. The eglpath argument behaves much like the .eglpath file
except that you cannot export source folders with the eglpath argument as you can
with the .eglpath file. See the EGL Generation Guide for more information on
generating in the SDK.
Related tasks
“Editing the build path” on page 73
Building projects
To build EGL output for Java programs, complete the following steps:
1. Generate Java source code into a project or directory: If you generate code into
a project (for best results) and if your Eclipse preferences are set to build
automatically on resource modification, the workbench prepares the output. If
you generate into a directory, distributed build function of the generator
prepares the output.
2. Prepare the generated output. This step is done automatically unless you set
the buildPlan or prep build descriptor options to no.
Details for generating source code are located in the EGL Generation Guide.
Related tasks
72 EGL Programmer’s Guide
“Editing the build path”
Editing the build path
See “The EGL build path” on page 71 for information on the build path.
To include projects in the EGL build path, follow these steps:
1. In the Project Explorer view, right-click a project that you want to link to other
projects and then click Properties. The Properties window opens.
2. Select the EGL Build Path properties page.
3. A list of all other projects in your workspace is displayed in the Projects tab.
Click the check box beside each project that you want to add to the project’s
build path.
4. To put the projects in a different order or to export any of them, click the Order
and Export tab and do as follows:
v To change the position of a project in the build-path order, select the project
and click the Up and Down buttons.
v To export a project, select the related check box. To handle all the projects at
once, click the Select All or Deselect All button.5. Click OK.
If you are generating to Java and want to use parts in a referenced project at run
time, you must make the referenced project available at run time. You can either
add that project to the Java build path of the current project, or you can add the
referenced project to your project as a JAR file.
To add a project to the Java build path of your project:
1. In the Project Explorer view, right-click a project that you want to link to other
projects and then click Properties. The Properties window opens.
2. Select the Java Build Path properties page.
3. On the Java Build Path page, click Projects tab.
4. Click Add,
5. Select the check boxes next to the projects that you want to add and then click
OK.
6. Click OK again.
Follow these steps to add a referenced project as a JAR file:
1. Right-click the project that you want to use in your project and then click
Export.
2. In the Export window, expand Java and click JAR file.
3. Click Next.
4. Under Select the resources to export, select the check box next to the project
that you want to export.
5. In the JAR file field, set the location for the JAR file.
6. Click Finish.
7. Right-click the project in which you want to use the referenced project and
then click Properties.
8. In the Properties window, click Java Build Path.
9. Go to the Libraries tab.
10. Click Add external JARs.
11. Select the JAR file that you exported and click Open.
Contents of an EGL application 73
12. Click OK. Related concepts
“The EGL build path” on page 71EGL projects contain a build path, which lists other EGL projects that you want
to use in the current project.
Source folders
EGL source folders contain EGL packages and files. By default, each new EGL
project has a source folder named EGLSource. You can add and remove source
folders as necessary to organize your code at high levels, but generally, EGL
projects have only one source folder and the packages within that source folder
provide the organization. You can create EGL packages only within an EGL source
folder, and EGL generates output code only for files within a source folder.
Related concepts
“Contents of an EGL application” on page 59This topic describes the artifacts found in a typical EGL application.
Related tasks
“Creating source folders”
“Creating EGL source files” on page 77
Creating source folders
After you create a project in the workbench, you can create one or more folders
within that project to contain your EGL files.
To create a folder for grouping EGL files, complete these steps:
1. From the main menu, click File → New → EGL Source Folder. The New Source
Folder window opens.
2. In the Project name field, specify the project to contain the new source folder.
3. Specify a name for the folder in the Folder name field.
4. Click Finish. Related concepts
“Contents of an EGL application” on page 59This topic describes the artifacts found in a typical EGL application.
“Source folders” Related tasks
“Creating an EGL project” on page 62This topic covers how to create an EGL project.
“Creating EGL source files” on page 77
Introduction to EGL packages
Packages work like folders: they organize source files and prevent naming
conflicts.
Technically speaking, a package is a named collection of related parts, but it can be
easier to think of a package in the same way as a folder or directory on your local
system.
74 EGL Programmer’s Guide
Packages prevent name conflicts by separating files into different contexts. Two
parts with the same name cannot be defined in the same package, but two
different packages can each have a part with the same name. Likewise, you should
prevent conflicts between packages by not creating packages with the same name,
even if those packages are in different projects or source folders.
The parts in an EGL source file all belong to the same package. The package
statement in the file, if any, specifies the name of that package. If you do not
specify a package statement, the parts are stored in the root of the source folder
and are considered to be in the default package. Because files in the default package
cannot be shared by parts in other packages or projects, it is best to specify a
package statement.
Package names are case sensitive.
Working with packages
When you want a part to reference another part that is in the same package, you
do not need to specify the location of the second part. The following example
shows two parts in the same package: a Record part and a Program part that uses
the record part:
package com.companyb.firstpackage;
program testProgram type BasicProgram
function main()
myVariable myRecordPart;
end
end
Record myRecordPart type BasicRecord
field1 int;
field2 string;
end
When you want a part to reference another part that is in a different package,
specify the complete location of the part within its package. For example, the
following Program part uses the Record part from the previous example:
package com.companyb.secondpackage;
program testProgram2 type BasicProgram
function main()
myVariable2 com.companyb.firstpackage.myRecordPart;
end
end
As shorthand, you can use the import statement to tell EGL that you want to use
the part in the source file. If you import a part in this way, you can use the part as
though it were in the current package, without specifying the complete location of
the part within its package each time you use it. Sometimes, importing a part in
this way is called ″bringing the part into scope.″
For example, the following Program part again uses the Record part defined
earlier, but this time it imports the part first:
package com.companyb.thirdpackage;
import com.companyb.firstpackage.myRecordPart;
program testProgram3 type BasicProgram
Contents of an EGL application 75
function main()
myVariable3 myRecordPart;
end
end
Note that the import statement uses the package path to the part and the part
name, not the source file name.
For more information on import, see ″Import and use statements″ in the EGL
Language Reference.
Related concepts
“Contents of an EGL application” on page 59This topic describes the artifacts found in a typical EGL application.
Creating an EGL package
An EGL package is a named collection of related source parts. To create an EGL
package, do the following:
1. Identify a project or folder to contain the package. You must create a project or
folder if you do not already have one.
2. In the workbench, click File → New → EGL Package.
3. Select the project or folder that will contain the EGL package. The Source
folder field might be pre-populated depending on the current selection in the
Project Explorer.
4. In the Package name field, type the name of the EGL package.
5. Click the Finish button.
Related concepts
“Introduction to EGL projects” on page 61 Related tasks
“Creating an EGL Web project” on page 63This topic covers how to create an EGL Web project.
“Creating an EGL project” on page 62This topic covers how to create an EGL project.
Introduction to EGL files
The two most common types of files in an EGL project are source files and build
files. EGL also uses deployment descriptors in service applications and service
client applications.
Source files
Source files contain EGL source code in units called logic parts and data parts. You
can have any number of logic parts and data parts in any one source file, except
that you can have only one generatable part in a source file. See “Introduction to
EGL parts” on page 81.
Source files have an extension of .egl and are written in EGL source format.
Build files
Build files contain information EGL uses to generate and deploy applications.
Build files are written in Extensible Markup Language (XML) and have the
76 EGL Programmer’s Guide
extension .eglbld. This type of file contains build parts such as build descriptor
parts, linkage options parts, and resource associations parts.
Whenever possible, use the build parts editor provided in the workbench to work
with build parts and build files. However, it is possible to edit a build file with a
text editor or XML editor.
Deployment descriptors
Deployment descriptors contain information that describes how EGL services will
be made available to other applications and how EGL applications will find
services provided by other applications. Deployment descriptor files have an
extension of .egldd and open in the deployment descriptor editor.
Related reference
“Contents of an EGL application” on page 59This topic describes the artifacts found in a typical EGL application.
Creating EGL source files
To create an EGL source file, complete these steps:
1. Identify a project or package to contain the file. If you do not already have a
project or package, you must create one.
2. From the main menu, click File → New → EGL Source File.
3. In the Source folder field of the New EGL Part window, select the location for
the new source file. The new file must be within an EGL source folder in an
EGL project.
4. In the Package field, select the package that will contain the EGL source file or
type the name of a new package.
5. Type the name of the EGL source file in the EGL source file name field.
6. Click Finish to create the file. An extension (.egl) is automatically appended to
the end of the file name. The EGL source file is displayed in the Project
Explorer view and automatically opens in the default EGL editor. Related concepts
“Introduction to EGL projects” on page 61
“Introduction to EGL parts” on page 81Parts are the building blocks of EGL applications.
Related tasks
“Creating an EGL project” on page 62This topic covers how to create an EGL project.
Renaming a source file
You can use the refactoring function of the workbench to rename source files and
correct references to those files.
With refactoring, you can rename EGL source files or JSP files that are controlled
by a JSF Handler.
1. In one of the following places, select the file you want to rename:
v Right-click the file in the Project Explorer view
v For files that contain a generatable part, right-click the generatable part in
the Outline view, Parts List view, or Parts Reference view
v For files that contain a generatable part, place the cursor on the generatable
part’s name in the EGL editor and right-click
Contents of an EGL application 77
2. From the context menu, click Refactor → Rename. The Rename Part window
opens.
3. In the Rename Part window, type a new name for the file, following EGL
naming conventions.
4. You can click Preview for a list of the changes EGL will make if you proceed.
5. If you clear the Update references check box, EGL will not search other files
for references to change. In most instances, select this check box.
6. Click OK.
Renaming a file makes the following changes:
v EGL changes the name of the file to the new name
v For files that contain a generatable part, EGL changes the name of the part to
match the new file name
v For files that contain a generatable part, EGL searches the build path for
references to that part and changes the references to match the new name of the
part. For example, if you rename a file that contains a called program, EGL
changes the code that calls that program to use the new name.
v For files that contain a JSF Handler, EGL links the JSP file to the new file and
changes any references in the JSP to the JSF Handler to use the new name, but it
does not change the name of the JSP file.
v For files that contain a JSF Handler, EGL updates references to the file in the
faces configuration file.
v For JSP files that are controlled by a JSF Handler, EGL updates the view
property of the JSF Handler to refer to the new JSP file.
You might still need to check for other changes caused by refactoring. For example,
EGL does not change labels used with the forward statement. Suppose that you
have a line of code that passes control to a JSF Handler like this:
forward to "myWebPage";
In this case, if you renamed myWebPage, EGL does not change this forward
statement to reflect the new label for the page. You must search for changes and
update the files manually.
Related concepts
“Generatable parts and non-generatable parts” on page 81EGL parts can be generatable or non-generatable.
“Introduction to EGL files” on page 76
“Introduction to EGL parts” on page 81Parts are the building blocks of EGL applications.
Related tasks
“Moving a source file” on page 79You can use the refactoring function of the workbench to move source files and
correct references to those files.
“Renaming parts” on page 97You can use the refactoring function of the workbench to rename parts and
correct references to those parts.
“Moving parts” on page 98You can use the refactoring function of the workbench to move parts between
source files and correct references to those parts.
78 EGL Programmer’s Guide
Moving a source file
You can use the refactoring function of the workbench to move source files and
correct references to those files.
With refactoring, you can move EGL source files to a new location in an EGL
package in your workspace.
1. In the Project Explorer view, right-click the file and then click Refactor → Move.
The Move window opens.
2. In the Move window, select a destination for the file. You can create a new
package for the file with the Create Package button.
3. You can click Preview for a list of the changes that EGL will make if you
proceed.
4. If you clear the Update references to the moved elements check box, EGL will
not search other files for references to change. In most instances, select this
check box.
5. Click OK.
Moving a file makes the following changes:
v EGL moves the file to the new location
v EGL updates the package statement in the file
v EGL searches the build path for references to parts in the file and updates
references and import statements as necessary
v For files containing a JSF Handler, EGL links the JSP file to the new file and
changes any references in the JSP to the JSF Handler to use the new name, but it
does not change the name of the JSP file.
v For files containing a JSF Handler, EGL updates references to the file in the faces
configuration file.
You might still need to check for other changes that refactoring causes.
Related concepts
“Introduction to EGL files” on page 76 Related tasks
“Renaming a source file” on page 77You can use the refactoring function of the workbench to rename source files
and correct references to those files.
“Renaming parts” on page 97You can use the refactoring function of the workbench to rename parts and
correct references to those parts.
“Moving parts” on page 98You can use the refactoring function of the workbench to move parts between
source files and correct references to those parts.
Creating EGL build files
To create an EGL build file, complete these steps:
1. Identify a project or folder to contain the file. If you do not already have a
project or folder, you must create one.
2. From the main menu, click File → New → EGL Build File.
3. From the Select Container window, type the project or folder that will contain
the EGL build file in the Enter or select the parent folder field or use the
directory tree to select the location.
Contents of an EGL application 79
4. Click Advanced to link the file to an existing file in the file system. Type the
name of the file to be linked in the text box or click Browse to locate the file.
Click Variables to work with the variables in the file that you specify.
5. Type the name of the build file in the File name field.
6. Optionally, you can click Next to select EGL parts to populate the file.
7. Click Finish to create the file without populating it with an EGL part. An
extension (.eglbld) is automatically appended to the end of the file name. The
EGL build file is displayed in the Project Explorer view and automatically
opens in the default EGL editor. Related concepts
“Introduction to EGL projects” on page 61
“Introduction to EGL parts” on page 81Parts are the building blocks of EGL applications.
Creating a deployment descriptor file
The EGL deployment descriptor file describes how EGL service applications are
linked to clients, and how EGL service clients are linked to the service applications
they use.
The EGL deployment descriptor is distinct from J2EE deployment descriptors.
You can have as many deployment descriptors in your EGL project as you want,
but only one can be selected as the main deployment descriptor in the
deploymentDescriptor build descriptor option. That main deployment descriptor
can include entries from other deployment descriptor files, linking the main
deployment descriptor to the other deployment descriptors without directly
copying their information. Alternately, you can copy the information from one
deployment descriptor directly into another deployment descriptor.
Follow these steps to create a new EGL deployment descriptor file:
1. Click File → New → Other. The New window opens.
2. In the New window, expand EGL and click Deployment Descriptor.
3. Click Next.
4. In the Source folder field, select an EGL source folder in an EGL project. You
can add a deployment descriptor only to EGL projects.
5. Type a name for the file in the EGL deployment descriptor file name field.
6. Click Finish.
The new deployment descriptor file is created and opens in the editor. The next
step is to configure your project to use the new deployment descriptor. There are
several ways to configure your project in this way:
v If this is the only deployment descriptor in your project, set the
deploymentDescriptor build descriptor option to the name of the deployment
descriptor file, omitting the .egldd extension.
v You can include entries from one deployment descriptor in another.
v You can copy the entries from one deployment descriptor into another. Related concepts
“Building and using service applications in EGL” on page 249Service applications, within service-oriented architecture, enable you to organize
your programs in a modular, compartmentalized manner. Related tasks
80 EGL Programmer’s Guide
“Calling an external service” on page 256You can use services that are supplied by external applications in your EGL
logic parts. Using an external service in this way is acting as a client of a
service, or sometimes consuming or invoking a service.
“Exposing a service to other applications” on page 263Your EGL application can act as a service by exposing its functions to other
applications.
Introduction to EGL parts
Parts are the building blocks of EGL applications.
EGL includes these basic kinds of parts:
Logic parts
Logic parts define a sequence of instructions. Logic parts contain one or
more functions, which are the basic unit of logic. Logic parts include
Program parts and Library parts, which are general-use parts, as well as
Service parts, ExternalType parts, and Handler parts, which have more
specialized uses.
Data parts
Data parts define a structure that stores data. Data parts form the basis for
a variable that you can use in a logic part. Data parts can hold one piece of
data, as in a primitive or DataItem, or they can hold many pieces of data,
as in a Record part. See “Introduction to data parts” on page 82.
User interface parts
User interface parts define the information presented to a user or the logic
required when interacting with a user. Some user interface parts are
defined with a stereotype of a Record part, as is the case with
ConsoleForms, which specify the information that you want to appear on
the user interface. Others are defined with a stereotype of a Handler part,
as is the case with JSFHandlers and ReportHandlers.
Build parts
Build parts control the generation process and set how the application will
behave at run time. The most commonly used kind of build part is the
build descriptor part, which contains a list of build descriptor options to
define how the EGL code will be generated to the output language. Other
build parts control how the application will work with other applications
and resources at run time.
Deployment descriptors
Deployment descriptors contain information that describes how EGL
services will be made available to other applications and how EGL
applications will find services provided by other applications. Related concepts
“Contents of an EGL application” on page 59This topic describes the artifacts found in a typical EGL application.
Generatable parts and non-generatable parts
EGL parts can be generatable or non-generatable.
Generatable parts are the parts on which you can begin the generation process. For
example, you cannot start the generation process on a DataItem part or a Record
part with the BasicRecord stereotype. Instead, you must start the generation
Contents of an EGL application 81
process on a generatable part such as a Program part; in the process, any
non-generatable parts used in that Program part, such as Records and DataItems,
are generated as well.
The following parts are generatable:
v Program parts
v Library parts of all stereotypes
v Handler parts of all stereotypes
v Service parts
v DataTable parts
v Record parts with the stereotype ConsoleForm
v EGL deployment descriptors
Generatable parts have these characteristics:
v A source file can contain zero or one generatable parts. Any number of
non-generatable parts can be included in the same source file as the generatable
part.
v The generatable part must have the same name as the source file, minus the
source file’s .egl extension. The case of the names must match. EGL deployment
descriptors are considered generatable even though they do not have a part
name separate from the file name. Related concepts
“Introduction to EGL parts” on page 81Parts are the building blocks of EGL applications.
Introduction to data parts
Data parts define a structure that stores one or more pieces of data. Data parts
form the basis for a variable that you can use in a logic part.
These are the three most common types of data part:
Primitives
EGL supplies simple data types similar to those found in most other
programming languages, such as numbers, dates, characters, and large
objects. Primitives form the basis for more complex data types. Here are
two examples of variables created from primitives:
myInteger int;
myString char(50);
You can find a complete list of primitives in ″Primitive data types″ in the
EGL Language Reference. See “Commonly used primitives” on page 83 for
the primitives you are most likely to work with.
DataItems
A dataItem part is a customized primitive. To create a dataItem, choose
one primitive and add properties that adjust the behavior of the part. The
properties that a dataItem can accept depend on its primitive type and the
context in which it is used. Here are a few examples of dataItem parts:
DataItem myZipCodeItem int
{validValues = [00000,99999]} end
DataItem myAddressItem char(50)
{upperCase = YES} end
82 EGL Programmer’s Guide
In this case, the first dataItem is built from an integer primitive, but is
limited with the validValues property to include only the integers between
0 and 99999. The second dataItem is built from the character primitive with
50 characters, and it is set to convert any user input into its value to upper
case.
When you create a variable in a logic part, you can use a dataItem part as
the variable type instead of the primitive. The following example creates a
variable from a dataItem part in the previous example:
zipVar myZipCodeItem;
The following variable is equivalent to the previous one:
zipVar int {validValues = [00000,99999]};
In this way, a dataItem part is simply an alias for a primitive type that has
specific property settings.
Records
Record parts are structured collections of other data parts, such as
primitives, dataItems, or other records. These other data parts within the
record part are referred to as its fields. Generally, a record part represents a
table in a database, with one field for each column in the table:
Record myCustomerRecord type BasicRecord
customerNumber int;
customerFirstName string;
customerLastName string;
customerBalance float;
end
This record has four fields: one integer, two strings, and one floating-point
number. These fields could just as easily be dataItems or other records.
Strictly speaking, the data part itself doesn’t store data; a variable created from that
data part stores the data. In this way, you can think of a data part as a pattern for
a variable. You can declare a variable simply by naming the variable and then
specifying the data part that you want to use:
myVariable1 int;
myVariable2 myDataItemPart;
myVariable3 myRecordPart;
These are only the most common types of data part. For the others, see “Other
data parts” on page 87.
Related concepts
“Contents of an EGL application” on page 59This topic describes the artifacts found in a typical EGL application.
“Other data parts” on page 87These data parts are not used as often as the others.
“Commonly used primitives”This topic lists and describes the primitives that you are most likely to use.
“Introduction to Record parts” on page 85Record parts are collections of other data parts. The data parts within the
Record part are referred to as fields. A Record part can contain any number of
fields, and the fields can include primitives, dataItems, and other records.
Commonly used primitives
This topic lists and describes the primitives that you are most likely to use.
Contents of an EGL application 83
Not all primitives are listed here; for the complete list, see ″Primitive data types″ in
the EGL Language Reference.
Primitive numeric types: The following numeric primitives are the most often
used:
INT
This is a basic four-byte integer, the workhorse of internal calculations, used
also for key numbers, stock quantities, or anywhere else that a whole number
is appropriate. The range of values you can put in an INT is -2,147,483,648 to
+2,147,483,647.
DECIMAL
Use decimals for any numbers that need a decimal point—currency amounts,
for example, or employee hours (if you allow fractions). When you declare a
variable of this type, specify the length (in digits, not bytes) and the number of
decimal places. If you know that a variable will never need to hold a value as
large as ten million dollars, you could declare it as follows:
mySalary DECIMAL(9,2) = 30000.00;
FLOAT
Variables of this type are 8 bytes in length (or double-precision, as opposed to
single-precision floating point numbers, which are only 4 bytes long). A
FLOAT variable stores a number that uses exponents, so it can hold extremely
large numbers in those 8 bytes. Very high numbers are the only values that
you typically store in FLOAT variables. You can assign the value through
ordinary decimal notation, or, because values of FLOAT variables can get so
large, through exponential notation, where e indicates a power of ten:
speedOfLight FLOAT = 299800000;
speedOfLight FLOAT = 2.998e8;
Here 2.998e8 means 2.998 x 108.
Primitive character types: The most common character primitives are STRING
and CHAR.
STRING
A STRING variable holds a group of characters such as a name or an address.
EGL automatically makes all strings Unicode, which means that each character
is two bytes long and can handle any international language that the Unicode
standard can render. STRING variables, by default, are variable in length. The
length of a STRING at any given moment is the length of the data that it
holds, and that length can change at run time. For some uses you might want
to limit the size of the STRING variable. To limit the length of the STRING
variable, specify a maximum number of characters (not bytes) at declaration
time, as in the following example:
myUSState STRING(2) = "TX";
Note that when you assign a STRING value, you place it inside double quotes.
CHAR
A CHAR primitive is also available, mostly to provide compatibility with older
programs and data. A variable declared as CHAR(4) would hold four bytes of
character data.
Primitive date and time types: To store dates and times, you typically use the
following types:
84 EGL Programmer’s Guide
DATE
A DATE variable stores month, day, and year in Gregorian format, using eight
bytes.
TIME
A TIME variable stores hours, minutes, and seconds in six bytes.
TIMESTAMP
A TIMESTAMP variable holds both date and time, and has a maximum of 20
digits.
For variables based on any of these date and time types, you can specify formats
for input and output. See ″Date, time, and timestamp format specifiers″ in the EGL
Language Reference for more information.
Primitive large object types: Large object types store unformatted data. EGL
simply passes them through without changing them—generally capturing them
and storing them in a database, or retrieving them from a database and
transferring them off to a program that can display them. The two types of
large-object primitives follow:
BLOB
BLOB is short for binary large object. BLOB variables are most commonly used
to store visual data, such as JPGs and movies. For example, a Web site that
sells movies might store short previews as BLOBs in a database, and serve
them to customers on request.
CLOB
Similarly, CLOB is a large object that contains character data. For example, a
company might use a database to archive emails as CLOBs. Related concepts
“Introduction to data parts” on page 82Data parts define a structure that stores one or more pieces of data. Data parts
form the basis for a variable that you can use in a logic part.
“Contents of an EGL application” on page 59This topic describes the artifacts found in a typical EGL application.
Introduction to Record parts
Record parts are collections of other data parts. The data parts within the Record
part are referred to as fields. A Record part can contain any number of fields, and
the fields can include primitives, dataItems, and other records.
At the simplest level, a Record part is a group of other data parts. In this example,
three different primitives are grouped into a single Record part:
Record primitiveRec type BasicRecord
integerField int;
stringField string;
charField char(30);
end
Creating a variable based on this Record part is similar to creating a variable based
on a DataItem part or primitive:
myRecVar primitiveRec;
The record variable itself does not contain a value, but the fields within the record
do contain values. After you have a variable based on a Record part, you can
access the fields within the record as though they were individual variables:
Contents of an EGL application 85
myRecVar.integerField = 6;
myRecVar.stringField = "Hello";
myRecVar.charField = "Character field";
However, the record still behaves as a single unit, so you can pass it to functions
as a single parameter, for example:
myFunction(myRecVar);
Record stereotypes
Like most other parts, Record parts can be specialized for specific purposes with a
stereotype. You set the stereotype for a Record part with the type keyword, as in
this example of a Record part with the stereotype BasicRecord:
Record myCustomerRecord type BasicRecord
customerNumber int;
customerFirstName string;
customerLastName string;
customerBalance float;
end
The BasicRecord stereotype denotes a general-purpose Record part. You can use
this stereotype any time that you want to group one or more variables together for
simplicity.
Because Record parts are most often used to represent records or other groups of
related data in a data source, the other stereotypes that you can apply make the
Record parts specialized for use with a particular kind of data source. For example,
the SQLRecord stereotype makes the Record part specialized for use with a SQL
database. When creating a Record part of this type, use properties to link the
record and its fields to the database table and its columns:
Record myCustomerRecordSQL type SQLRecord
{ tableNames = [["Customer"]], keyItems = [customerNumber] }
customerNumber int {column = "CustomerID"};
customerFirstName string {column = "FirstName"};
customerLastName string {column = "LastName"};
end
In this case, the record is linked to a database table named Customer that has
columns named CustomerID, FirstName, and LastName. When you link a record to a
database table like this, EGL can use this information to access the database based
on your interactions with the record. In simple terms, you can use the record as
though it were the row in the database.
For example, the following code uses the Record part defined in the previous
example to retrieve a specific row from the database:
myRecordVar myCustomerRecordSQL;
myRecordVar.customerNumber = 5;
get myRecordVar;
SysLib.writeStderr("Name: " +
myRecordVar.customerFirstName + " " +
myRecordVar.customerLastName);
Other stereotypes that can be added to Record parts include indexedRecord,
serialRecord and relativeRecord, which are used for accessing different types of
files.
Structured records
86 EGL Programmer’s Guide
Record parts can be structured to provide more detail about the layout and
organization of their fields. In a structured record, each field is assigned a level
number, an arbitrary number that indicates that field’s relationship to other fields.
The fields in unstructured records do not have level numbers, so each field is
considered to be at the same level. Structured records can also behave this way,
with each field at the same level number:
record structRec1 type BasicRecord
10 field1 int;
10 field2 int;
10 field3 int;
end
Varying the level numbers creates substructures within the record:
Record CustomerRecord type BasicRecord
10 phoneNumber CHAR(10);
20 areaCode CHAR(3);
20 localNumber CHAR(7);
end
In this case, the fields areaCode and localNumber are subfields of the field
phoneNumber. You can access the phoneNumber field to get the entire value of the
field, or you can access the areaCode or localNumber fields to get a portion of the
value held in the phoneNumber field.
Structured records are limited to fields with fixed length. See ″Records″ in the EGL
Language Reference for more information on the limitations and uses of structured
records.
Related concepts
“Introduction to data parts” on page 82Data parts define a structure that stores one or more pieces of data. Data parts
form the basis for a variable that you can use in a logic part.
Other data parts
These data parts are not used as often as the others.
DataTable
A DataTable part provides a collection of data in tabular form that you can
make available throughout an application. Unlike other data parts, you
declare each DataTable part in its own EGL source file because DataTables
are generatable parts. For more information, see ″DataTable″ in the EGL
Language Reference.
Dictionary
A dictionary is like a record in that it contains fields to which you can
assign values. Unlike a record, it is not associated with a database and you
can add new fields (also called name/value pairs) while your program is
running. As with a record, you create a dictionary type variable to reserve
storage. The amount of storage the dictionary uses will change depending
on the information that you put in it. For more information, see
″Dictionary″ in the EGL Language Reference.
ArrayDictionary
A variable that is based on an ArrayDictionary part enables you to access a
series of arrays by retrieving the same-numbered element of every array. A
set of elements that is retrieved in this way is itself a dictionary, with each
array name treated as a key that is paired with the value in the array
element.
Contents of an EGL application 87
Related concepts
“Introduction to data parts” on page 82Data parts define a structure that stores one or more pieces of data. Data parts
form the basis for a variable that you can use in a logic part.
“Arrays of data parts”Like many other programming languages, EGL can group variables of the same
type into arrays. This topic covers the basics of using arrays in EGL.
Arrays of data parts
Like many other programming languages, EGL can group variables of the same
type into arrays. This topic covers the basics of using arrays in EGL.
An array is an ordered series of variables of the same type. For example, you can
define an array of integer variables:
myInts int[] = [1,2,3,4,5];
In this case, the array is a series of five integer variables. In EGL, arrays begin
numbering with the number one, so this array has elements numbered one
through five.
You can access each of the integers in the array as though they were individual
variables by specifying the index number of the integer in brackets:
myInts[1] = 5+5;
myInts[2] = 16;
myInts[3] = myInts[1] + myInts[2];
You can also assign values to the array more than one at a time using one of these
two methods:
v You can use a set-value block:
myStrings string[2];
myStrings {"Hello", "Goodbye"};
Note that this syntax uses braces ({) and no equals sign (=). This is not an
assignment statement but a method of assigning values to the array as though
the elements were its properties. This method offers better performance at run
time than the other method, which entails an array literal to the array.
Also, this method works only when the array has sufficient elements to accept
the new values in braces; EGL does not automatically add more elements. For
this reason, you must specify a starting length for the array or otherwise add
elements to it before you can assign values to elements with a set-value block.
v You can assign an array literal to the array:
myBigInts bigint[];
myBigInts = [10,40];
This method is a little slower than the set-value method because the generated
code must create two arrays: one for the variable and one for the literal.
You can also use either of these two methods to assign values to the array when
you create it:
myStringsInit string[] {"Hello", "Goodbye"};
myBigIntsInit bigint[] = [10, 40];
If you want to assign properties to the array as well as specifying starting values
in the set-value block, put the property name-value pairs after the starting values:
myDecimals decimal(10,2)[3] {55.43, 22.12, 4.34, CurrencySymbol = "$"};
88 EGL Programmer’s Guide
If you are using the array literal method of specifying starting values, you can set
properties with the set-value block as usual:
myBools boolean[3]{MaxSize = 5} = [true, false, true];
If you specify a number of elements in the array when you create it, that array is
initialized to contain that number of elements. Each element has the default value
for its type:
fiveInts int[5];
SysLib.writeStderr(fiveInts[1]); //Writes "0"
It’s good coding practice to specify a starting length for the array when you create
it so that EGL can initialize it. You can always add or remove elements later with
array functions such as appendElement and removeElement.
However, if you do not specify a starting length for the array, it starts as null, so
there is nothing in the array to be accessed:
nullArray int[];
nullArray[2] = 5; //NullValueException!
nullArray.appendElement(5); //NullValueException!
nullArray {1,2,3}; //NullValueException!
Instead, you must begin by initializing the array with an array literal:
nullArray2 int[];
nullArray2 = [1,2,3];
nullArray2.appendElement(4);
Alternatively, you can use a set-value block to initialize a null array:
emptyArray int[]{};
emptyArray.appendElement(5);
In the previous example, the set-value block is empty. You cannot use a set-value
block to assign more elements to an array than currently exist in the array. This
array has zero elements, so you must use a set-value block with zero values.
You can increase the length of an array by assigning a longer array literal to it. In
this case, you overwrite the shorter array with a new, longer array. The following
example assigns an array literal with 5 elements to replace an array with only two
elements:
smallIntArray int[2];
smallIntArray = [1,2,3,4,5];
However, you cannot use a set-value block to assign more elements to the array
than currently exist in the array:
smallStrArray string[2];
smallStrArray {"ab", "cd", "ef", "gh"};
//IndexOutOfBoundsException! Array has only 2 elements!
For more details on arrays, see ″Arrays″ in the EGL Language Reference.
Related concepts
“Introduction to data parts” on page 82Data parts define a structure that stores one or more pieces of data. Data parts
form the basis for a variable that you can use in a logic part.
Contents of an EGL application 89
Introduction to logic parts
Logic parts define a sequence of instructions. Most logic parts contain one or more
functions, which are the basic unit of logic.
A function can receive parameters, execute EGL statements, and return a value to
the function that called it. Following is a simple example of a function:
Function addIntegers(int1 int in, int2 int in) returns (int)
sum int = int1 + int2;
return (sum);
end
For more details, see ″Functions″ in the EGL Language Reference.
A function is not technically a logic part, although it is possible for a function to
exist outside of a logic part and thus behave like a logic part. See ″Standalone
function part″ in the EGL Language Reference.
Program
A program is the simplest kind of logic part. A program in EGL behaves
similarly to programs in many other programming languages. An EGL
program must contain a function named main, which is the function that is
invoked when the program runs. The program can contain any number of
other functions. The following example shows a simple program part:
package programs;
program multiplicationTable type BasicProgram
stopNumber int = 7;
function main()
SysLib.writeStderr("Printing multiplication table through "
:: stopNumber);
i, j int;
for (i from 1 to stopNumber by 1)
for (j from 1 to stopNumber by 1)
printProduct(i, j);
end
end
SysLib.writeStderr("Finished.");
end
function printProduct(int1 int in, int2 int in)
SysLib.writeStderr(int1 :: "x" :: int2 ::
"=" :: int1*int2);
end
end
Library
A library part is a collection of functions and variables that are made
available locally to other logic parts. Functions in a library part can be
invoked in any order, while the main function in a program always runs
first. The following example shows a simple library part:
package libraries;
library myMathLibrary type BasicLibrary
function addIntegers(int1 int in, int2 int in)
returns (int)
return (int1+int2);
90 EGL Programmer’s Guide
end
function subtractIntegers(int1 int in, int2 int in)
returns (int)
return (int1-int2);
end
end
Handler
A Handler part is specialized to control a particular kind of user interface.
BasicHandler
BasicHandler parts are the simplest kind of Handler. Generally,
you will use a Handler that is specialized for a type of interface.
JSFHandler
JSF Handler parts control Web pages. See “Elements of a Web
application” on page 183.
JasperReport
Jasper Report Handler parts control reports that are created by
EGL within the Jasper Reports framework. See “Elements of an
EGL report application” on page 284.
Service
Like a library part, a service part is a collection of functions, but unlike a
library part, the service part is designed to enable applications outside the
current run unit to use the functions. See “Elements of a service
application” on page 249 for more information and examples.
Interface
An interface part is different from most logic parts because instead of
containing functions or any executable code, it contains function
prototypes. Instead of defining actual logic, as the other types of logic part
do, an interface part merely describes another logic part, usually a service
part. In EGL, you can use interfaces to plan services or to represent
services that your application will use. See “Elements of a service
application” on page 249 for more information and examples.
ExternalType
With an ExternalType part, you can create variables in EGL that refer to
elements in another language. Generally, ExternalType parts are used to
represent Java objects. An ExternalType part contains function prototypes
that allow you to invoke the logic in the Java object. Also, an ExternalType
part can contain variables that represent public variables in the Java object.
See “Calling Java” on page 104 for an example. Related concepts
“Contents of an EGL application” on page 59This topic describes the artifacts found in a typical EGL application.
Creating a program part
An EGL program part is the main logical unit that is used to generate a COBOL or
Java program. For more information, see ″Program part″ in the EGL Language
Reference
A program part is automatically added to an EGL source file and named
appropriately when you create the file in the workbench. Source file specifications
allow only one program part per file, and require a program name that matches
the file name.
Contents of an EGL application 91
To create a program file with a program part, do as follows:
1. Identify a project or package to contain the file. If you do not already have a
project or package, you must create one.
2. In the workbench, click File → New → Other. The New window opens.
3. In the New window, expand EGL and double-click Program.
4. Select the project or folder that will contain the EGL file; then select a package.
5. In the EGL source file name field, type the name of the EGL file, for example
myEGLprg. Because the program name will be identical to the file name,
choose a file name that adheres to EGL part name conventions.
6. If you want to be able to call the program from another logic part, select the
Create as called program check box. See ″Program part″ in the EGL Language
Reference for more information on called programs.
7. Click Finish.
Related concepts
“Introduction to logic parts” on page 90Logic parts define a sequence of instructions. Most logic parts contain one or
more functions, which are the basic unit of logic.
Creating a library part
To create an EGL source file that contains a library part, do as follows:
1. Identify a project or package to contain the file. If you do not already have a
project or package, you must create one.
2. In the workbench, click File → New → Other. The New window opens.
3. In the New window, expand EGL and then click Library.
4. Click Next. The New EGL Library wizard opens.
5. In the Source folder field, select a source folder to hold the new file.
6. In the Package field, select a package to hold the new file.
7. In the EGL source file name field, type a name for the new file.
Because the name of the new library will be identical to the name of the file,
type a name that adheres to EGL part name conventions.
8. Under EGL Library Type, select the type of library. Most often, you will choose
Basic. For information about the differences between the types of EGL libraries,
see ″Library part″ in the EGL Language Reference.
9. Click Finish.
Related concepts
“Introduction to logic parts” on page 90Logic parts define a sequence of instructions. Most logic parts contain one or
more functions, which are the basic unit of logic.
Creating a service part
To create an EGL source file that contains an EGL service part, do as follows:
1. Identify a project or package to contain the file. If you do not already have a
project or package, you must create one.
2. In the workbench, click File → New → Other. The New window opens.
3. In the New window, expand EGL and double-click Service.
4. In the Source folder field, select a source folder to hold the new file.
5. In the Package field, select a package to hold the new file.
6. In the EGL source file name field, type a name for the new file.
92 EGL Programmer’s Guide
Because the name of the new service will be identical to the name of the file,
type a name that adheres to EGL part name conventions.
7. If you want the new service part to implement any EGL interface parts, follow
these steps:
a. Click Add. The Implemented Interfaces Selection window opens.
b. In the Choose interfaces field, type a search string.
v A question mark (?) represents any one character
v An asterisk (*) represents a series of any characters
The interface parts that match the search string are listed under Matching
parts.
c. Click the interface part that you want the service part to implement.
d. Click Add.
e. When you are finished choosing interface parts, click OK.
The interface parts that you chose are listed in the Implements Interfaces field.
You can remove an interface part by clicking it and then clicking Remove.
8. New service parts can include functions that call an EGL called program. If you
want the new service part to have functions that call an EGL called program,
follow these steps:
a. Click Show Advanced.
b. Click the Add button next to Basic Called Programs. The Basic Called
Program Selection window opens.
c. In the Choose Programs field, type a search string.
v A question mark (?) represents any one character
v An asterisk (*) represents a series of any characters
The programs that match the search string are listed under Matching parts.
d. Click the program name.
e. Click Add.
f. When you are finished choosing programs, click OK.
The programs you chose are listed in the Basic Called Programs field. You can
remove a program by clicking it and then clicking Remove. For each of the
programs in this field, the new service part will have a function that calls the
program.
9. Click Finish.
Related concepts
“Building and using service applications in EGL” on page 249Service applications, within service-oriented architecture, enable you to organize
your programs in a modular, compartmentalized manner. Related tasks
“Creating a service to call a program”If you have a called program in your project, you can create a Service part to
call that program.
Creating a service to call a program
If you have a called program in your project, you can create a Service part to call
that program.
You might want to create a service in this way to act as a wrapper for the called
program. In this context, a wrapper refers to a logic part that has no meaningful
logic in itself but exists only to provide other applications access to another logic
part.
Contents of an EGL application 93
1. In the Project Explorer view, right-click a file containing an EGL called program
part and then click EGL Services → Create Program Call Function. The New
EGL Service Part window opens.
2. Enter the location and file name information for the Service part as in “Creating
a service part” on page 92.
If you type the name of an existing Service part and then select the Update
existing files check box, EGL adds a function to the existing Service part that
calls the called program. If you type a name for a new Service part, EGL
creates the new part and adds a function that calls the called program.
3. Click Finish.
Related concepts
“Building and using service applications in EGL” on page 249Service applications, within service-oriented architecture, enable you to organize
your programs in a modular, compartmentalized manner.
“Creating a service part” on page 92
Creating an Interface part
Use an Interface part in any of the following situations:
v A systems architect can use interfaces to help design your organization’s
services.
You can create an interface that describes the functionality that you want to have
coded in an EGL service. After the interface is complete, you or others can code
the service that implements the interface. That service must contain a function
that matches every prototype in the interface. The interface can be thought of as
a contract that the service fulfills.
This use of interfaces provides the following benefits:
– It helps people in your organization to think clearly about what operations
are needed in a service before service development begins.
– It allows developers to begin coding client applications while the service code
is under development.
A service can implement multiple interfaces, and multiple services can
implement the same interface.
v Interfaces give developers access to your organization’s services while
shielding them from knowledge of the implementation.
The runtime effect of declaring a variable based on an Interface part is the same
as the effect of declaring a variable based on the related Service part; but use of
the interface lets you avoid disclosing the logic inside the service. Keeping the
logic away from others might be appropriate for competitive reasons (you might
want to hide the source code from developers outside of your organization) or
to reduce complexity (you might want developers, whether in or out of your
organization, to focus on the functionality that the service provides rather than
on the details of the implementation).
v Interfaces let you access a Web service regardless of the language or location
of the service implementation.
Access of a Web service created outside of your organization requires that you
have the service-specific Web Service Description Language (WSDL) definition,
which details how to access the service.
You use the WSDL definition as input to create an external service using the
service module editor. The editor creates a service-specific Interface part through
which you can access the service in your code.
To create an EGL source file that contains an EGL interface part, do as follows:
94 EGL Programmer’s Guide
1. Identify a project or package to contain the file. If you do not already have a
project or package, you must create one.
2. In the workbench, click File → New → Interface. The New EGL Interface Part
wizard opens.
3. In the Source folder field, select a source folder to hold the new file.
4. In the Package field, select a package to hold the new file.
5. In the EGL source file name field, type a name for the new file.
6. Click Finish.
You can also create an interface part based on the functions in a service part. See
“Creating an interface part from a service part.”
Related concepts
“Building and using service applications in EGL” on page 249Service applications, within service-oriented architecture, enable you to organize
your programs in a modular, compartmentalized manner. Related tasks
“Creating an interface part from a service part”You can use a service part as a model for an interface part. The resulting
interface part has a function prototype for each function in the service that is
not identified as private.
Creating an interface part from a service part
You can use a service part as a model for an interface part. The resulting interface
part has a function prototype for each function in the service that is not identified
as private.
1. In the Project Explorer view, right-click an EGL source file that includes an EGL
Service part and then click EGL Services → Extract EGL Interface. The New
EGL Interface Part window opens.
2. In the Source folder field, select a source folder to hold the new file.
3. In the Package field, select a package to hold the new file.
4. In the EGL source file name field, type a name for the new file that will
contain the new Interface part. By convention, files that contain interface parts
begin with a capital letter I.
5. In the Functions field, select the functions that you want to include in the new
Interface part. Only the functions not marked as private are shown in this list.
You can use the Select All and Deselect All buttons to select or deselect the
functions.
6. If you want to overwrite an EGL source file, select the Overwrite existing files
check box.
7. Click Finish. Related concepts
“Building and using service applications in EGL” on page 249Service applications, within service-oriented architecture, enable you to organize
your programs in a modular, compartmentalized manner. Related tasks
“Creating an Interface part” on page 94
Creating a WSDL file from a service part
You can create a sample WSDL file as a point of reference to a service part.
Contents of an EGL application 95
This method is provided mainly for compatibility and to preview the WSDL file
that will be created when you deploy your service. If you want to expose a Web
service to other applications through a WSDL file, add Web service binding
information to an EGL deployment descriptor file and then generate the project to
create a WSDL file. See “Exposing a service to other applications” on page 263.
1. In the Project Explorer view, right-click the file that contains the Service part
and then click EGL Services → Generate WSDL File. The Create WSDL file
window opens.
2. Fill out the Project Source, Folder, and WSDL file name fields with the
location and name of the new WSDL file.
3. Under Advanced, provide the deployment information to be added to the
WSDL file.
4. Click Finish.
The new WSDL file is created in the location that you specified. This file is not
updated automatically, so if the service information changes, you must recreate or
edit the WSDL file.
Related tasks
“Exposing a service to other applications” on page 263Your EGL application can act as a service by exposing its functions to other
applications.
“Adding Web service deployment information to the deployment descriptor”
on page 265After you have coded a service part that you want to expose as a Web service,
you must add information to the deployment descriptor that tells EGL to
generate the necessary Web service wrapper.
Introduction to build parts
Build parts control the generation process and set how an application will behave
at run time. The kinds of build part you need vary depending on the target
platform of your application and the type of application that you have created.
Build descriptor part
A build descriptor part controls the generation process and indicates what
other control parts are read during that process. Build descriptor parts
contain build descriptor options, which are covered in the EGL Generation
Guide. The information in this part is used at generation time, test time,
and run time.
Linkage options part
A linkage options part gives details on how a generated program calls or
transfers to and from other programs. The part also gives details on how a
generated COBOL program accesses files on remote CICS regions. The
information in this part is used at generation time, test time, and run time.
Resource associations part
A resource associations part relates an EGL record with the information
that is needed to access a file on a particular target platform; the
information in this part is used at generation time, test time, and run time.
Bind control part
A bind control part (which applies only when the target platform is z/OS®)
describes how to access a DB2® database from one or more programs. The
information in this part is used at generation time and preparation time.
96 EGL Programmer’s Guide
Link edit part
A link edit part (which applies only when the target platform is z/OS)
describes how to form a load module from two or more programs. The
information in this part is used at generation time and preparation time.
Deployment descriptors
EGL deployment descriptors are not build parts, but they fit into the
category of files involved in generation and deployment. Deployment
descriptors contain information that describes either how a service part
from your application is exposed to other applications or how an external
service will be used in your application. For more information, see ″EGL
deployment descriptor file″ in the EGL Generation Guide.
More information on build parts is available in the EGL Generation Guide.
Related concepts
“Introduction to EGL parts” on page 81Parts are the building blocks of EGL applications.
Renaming parts
You can use the refactoring function of the workbench to rename parts and correct
references to those parts.
1. In one of the following places, select the part that you want to rename:
v Place the cursor on the part name in the EGL editor and right-click.
v Right-click the part in the Outline view, Parts List view, or Parts Reference
view.
v For generatable parts, right-click the file that contains the part in the Project
Explorer view2. In the popup menu, click Refactor → Rename. The Rename window opens.
3. In the Rename window, type a new name for the part, following EGL naming
conventions.
4. You can click Preview for a list of the changes that EGL will make if you
proceed.
5. If you clear the Update references check box, EGL will not search other files
for references to change. Generally, select this check box.
6. Click OK.
Renaming a part makes the following changes happen:
v EGL changes the name of the part to the new name
v EGL searches the build path for references to that part and changes the
references to match the new name of the part. For example, if you rename a
record part, EGL changes variable declarations to the new name of the record
v For generatable parts, EGL changes the name of the file to match the new part
name
v For JSF Handlers, EGL links the JSP file to the new part’s file, but it does not
change the name of the JSP file.
v For JSF Handlers, EGL updates references to the part’s file in the faces
configuration file.
You cannot rename functions in this way.
Related concepts
Contents of an EGL application 97
“Introduction to EGL parts” on page 81Parts are the building blocks of EGL applications.
“Generatable parts and non-generatable parts” on page 81EGL parts can be generatable or non-generatable.
Related tasks
“Renaming a source file” on page 77You can use the refactoring function of the workbench to rename source files
and correct references to those files.
“Moving a source file” on page 79You can use the refactoring function of the workbench to move source files and
correct references to those files.
“Moving parts”You can use the refactoring function of the workbench to move parts between
source files and correct references to those parts.
Moving parts
You can use the refactoring function of the workbench to move parts between
source files and correct references to those parts.
1. In one of the following places, select the part that you want to move:
v Place the cursor on the part name in the EGL editor and right-click
v Right-click the part in the Outline view, Parts List view, or Parts Reference
view
v For generatable parts, right-click the file containing the part in the Project
Explorer view2. In the popup menu, click Refactor → Move. The Textual Move window opens.
3. In the Textual Move window, select a new source file for the part. You can click
Create EGL file to create a new file to put the part into. If you are moving a
generatable part, the target source file must have the same name as the part.
4. You can click Preview for a list of the changes that EGL will make if you
proceed.
5. If you clear the Update references to the moved elements check box, EGL will
not search other files for references to change. Generally, select this check box.
6. Click OK.
Moving a part makes the following changes:
v EGL moves the part into the target source file
v EGL searches the build path for references to that part and changes the
references to match the new location of the part. For example, if you move a
record part, EGL changes variable declarations and any import statement to the
new location of the record
v For JSF Handlers, EGL links the JSP file to the new part’s file, but it does not
change the name of the JSP file.
v For JSF Handlers, EGL updates references to the part’s file in the faces
configuration file. Related concepts
“Introduction to EGL parts” on page 81Parts are the building blocks of EGL applications.
“Generatable parts and non-generatable parts” on page 81EGL parts can be generatable or non-generatable.
Related tasks
98 EGL Programmer’s Guide
“Renaming a source file” on page 77You can use the refactoring function of the workbench to rename source files
and correct references to those files.
“Renaming parts” on page 97You can use the refactoring function of the workbench to rename parts and
correct references to those parts.
“Moving a source file” on page 79You can use the refactoring function of the workbench to move source files and
correct references to those files.
Properties
Properties set specific options for parts. In general, you specify the properties when
you create the part and then the properties are static. In certain circumstances,
however, it is possible to change a property dynamically.
The available properties are different for each part and for each stereotype, so
when creating a part, check to see what properties are appropriate. Some parts
have required properties, but most properties are optional.
The most common type of property is a simple property, a name-value pair that sets
an option for the part. Most parts can accept one or more simple properties by
listing the name of the property and the value for the property within braces ( { } )
at the beginning of the part definition. If you specify more than one property for
the part, separate the name-value pairs with commas:
DataItem cost money(10,2)
{Currency = yes,
CurrencySymbol = "$"}
end
The code block that begins with the opening brace and ends with the closing brace
(that is, the list of properties and their values) is referred to as a set-value block.
Properties are useful only in specific situations. For example, DataItem parts can
include properties that apply only to specific types of user interfaces. As in the
previous example, you can specify the properties currency and currencySymbol on
any DataItem part to indicate that the DataItem represents a currency value and to
specify the monetary symbol used in displaying the value. From the topic
″currencySymbol″ in the EGL Language Reference, you can see that this property has
an effect when used on a Web page, but not in a Console User Interface
application.
Property values
You must provide a valid value for each property. Some properties accept string
literals, some accept a ″yes″ or ″no″ value, some accept values from lists of options
called enumerations, and others accept array literals. In most cases, you cannot use
a variable or constant as the value of a property. In other words, you cannot use a
boolean variable or a string variable set to ″yes″ or ″no″ for the value of the
currency property; you must specify a literal, unquoted ″yes″ or ″no″ value.
However, a few properties require that you supply the name of a variable or part
as a value. In this case, the property is not using the value of the variable or part;
it is referring to the variable or part itself. For example, the JSF Handler part
Contents of an EGL application 99
accepts the onPreRenderFunction property. This property specifies a function
within the handler that runs automatically each time the handler runs. In this case,
you might write the handler as follows:
handler myPage type JSFHandler
{onPreRenderFunction = refreshFunction}
function refreshFunction()
end
end
In this example, the onPreRenderFunction is set to the name of the function
refreshFunction. The handler must have a function with this name or EGL will
throw a validation error.
Some properties are provided for compatibility with previous versions or migrated
code and are unnecessary for new EGL applications. To know which properties are
provided for new code and which are used for compatibility, see the EGL Language
Reference topic that covers a particular part and its properties.
Inheriting and overriding properties
When you create a part based on another part, the new part inherits the properties
of the old part:
DataItem myRedVar int {color = red} end
Record myRedRecord type BasicRecord
myField myRedVar;
end
In this case, the field myField behaves as though you had specified the color
property on it.
However, properties do not transfer between most variables, as in this example:
myRedInt int {color = red};
myBlueInt int {color = blue};
myBlueInt = myRedInt;
In this case, myBlueInt still has the color property set to blue.
Reference variables are an exception to property transfers. See ″Properties″ in the
EGL Language Reference.
You can explicitly override properties, as in the following example:
DataItem myRedVar int {color = red} end
Record myBlueRecord type BasicRecord
myField myRedVar {color = blue};
end
In this case, the field myField overrides the red value with the blue value.
In this way, it is legal but not recommended to define a property twice for one part
or variable. The last property specification sets the value, as in this example:
myBlueVar int {color = red, color = blue};
In this case, the variable’s color property is set to blue because the second
definition overrides the first.
100 EGL Programmer’s Guide
Related concepts
“Introduction to EGL parts” on page 81Parts are the building blocks of EGL applications.
Contents of an EGL application 101
102 EGL Programmer’s Guide
Working with EGL code
The EGL source editor provides a number of tools that you use to create EGL files.
Related concepts
“The EGL editor” on page 130The EGL code editor looks and works like a standard text editor or code editor
for other languages, but it has additional features to help you edit EGL code.
The code editor highlights invalid syntax, provides an explanation for problems
in the code, colors keywords, strings, and comments, and helps you write EGL
code.
“Code assistant” on page 132
“Code templates” on page 133
“Code snippets” on page 138Snippets are code objects that are reusable programming objects. Snippets can
be a piece of code or a complete programming task. In addition to the default
snippets provided in the workbench, you can create your own snippets. Related tasks
“Enabling and disabling code templates” on page 134
“Creating code templates” on page 134
“Using cheat sheets” on page 140Cheat sheets can assist you with common tasks in the Workbench. They
provide step-by-step instructions within a workbench view and can perform
some of the steps in the task automatically.
“Editing DataItem parts with the source assistant” on page 141
Common programming tasks
These topics contain information on how to complete several common
programming tasks in EGL.
Related tasks
“Turning lines of code into comment lines” on page 104As in most languages, in EGL you can add comments in your code. EGL
ignores any text that is commented.
“Calling Java” on page 104There are several ways to call Java code when you are generating Java from
EGL. This topic covers a few of the most common ways, including using the
system functions in the JavaLib system library such as javaLib.invoke(), and
declaring an ExternalType part.
“Encrypting passwords” on page 122You can encrypt passwords with an EGL command-line utility. Password
encryption is supported only for Java programs and the debugger, not for
COBOL programs.
“Handling errors” on page 123With EGL, you can decide how your program behaves in case of errors.
“Customizing runtime messages” on page 127
© Copyright IBM Corp. 1996, 2007 103
Turning lines of code into comment lines
As in most languages, in EGL you can add comments in your code. EGL ignores
any text that is commented.
You can comment a single line of code at once, or you can create a block of
commented lines.
v To comment a single line or a portion of a line, use two virgules or slashes (//):
myInt int; //This is an integer variable
//The following function is for error checking
function validateData (inputRecord myRecord inOut)
end
v To comment a block of lines, begin the comment with /* and end the comment
with */:
/*
This function is commented.
function myPlannedFunction()
end
*/
To comment lines, you can type the comment characters yourself, or you can tell
the EGL editor which lines to comment. Follow these steps to comment lines of
code in the EGL editor:
1. In the EGL editor, highlight one or more lines of code.
2. Right-click the highlighted lines and then click Comment. Comment indicators
(//) are placed at the beginning of each line in the selected range.
Use the same procedures to uncomment lines, but select Uncomment from the
context menu.
Related concepts
“The EGL editor” on page 130The EGL code editor looks and works like a standard text editor or code editor
for other languages, but it has additional features to help you edit EGL code.
The code editor highlights invalid syntax, provides an explanation for problems
in the code, colors keywords, strings, and comments, and helps you write EGL
code. Related tasks
“Creating EGL source files” on page 77
Calling Java
There are several ways to call Java code when you are generating Java from EGL.
This topic covers a few of the most common ways, including using the system
functions in the JavaLib system library such as javaLib.invoke(), and declaring an
ExternalType part.
Prerequisites
v An EGL project generated to Java, not to COBOL
v An EGL program or other logic part
Calling a Java class once
If you need to use a method in a Java class only once, you can use the
javaLib.invoke system function.
104 EGL Programmer’s Guide
This example calls the method random. This method belongs to the class
java.lang.Math and returns a random number between 0 and 1. In this case, the
class resembles an EGL library and the method works like a function in this
library.
The only methods you can call in this way are the methods defined as static.
″Static″ is a Java term that has no parallel in EGL; in this context, it means that the
method is ready to be called at any time and needs no initialization before use.
1. In an EGL function within a logic part, declare any variables that you might
need to pass or that you might need to accept a return value:
myNumber float;
2. Use the javaLib.invoke() system function to call the method, passing the name
of the class and the method to call as parameters:
myNumber = javaLib.invoke("java.lang.Math", "random");
3. Then, you can use the results of the call:
sysLib.writeStderr(strLib.formatNumber(myNumber));
To pass a parameter to the method, use the argument parameter of
javaLib.invoke().
Calling a Java class multiple times
If you plan to use methods in a Java class several times, or if the method that you
want to call is not defined as static, you should create an ExternalType part, as in
″Creating an ExternalType part to represent a class″ that follows. However, for
compatibility with migrated programs, and with a little less EGL code, you can use
other functions in javaLib to initialize and use a class multiple times, even its
non-static methods.
The following example uses a different class that returns random numbers. The
method nextInt in the class java.util.Random provides an alternate way to return
a random integer. Because the method is not defined as static, you cannot use
javaLib.invoke() to call nextInt without any preparation:
//Error! The method nextInt() is not static.
myInt int = javaLib.invoke("java.util.Random", "nextInt");
Instead, you must first initialize the class and give it an identifier in EGL using
javaLib.storeNew(). Note the use of the casting operator, AS, to convert Java types
to EGL:
javaLib.storeNew("myRandomGenerator" AS "objId:java", "java.util.Random");
Then you can use the class repeatedly through javaLib.invoke:
myInt int = javaLib.invoke("myRandomGenerator" AS "objId:java", "nextInt");
In these examples, the string myRandomGenerator is an identifier that represents the
class. Each time you use the class, you tell EGL that this identifier refers not to an
EGL part or a string literal but a Java class with the code AS "objId:java". For
more information, see ″as operator″ in the EGL Language Reference. For more details
on calling Java classes and methods, see ″Java access functions″ in the EGL
Language Reference.
Working with EGL code 105
Creating an ExternalType part to represent a class
If you plan to use the class often, or if the method that you want to use is not
defined as static, you can define an EGL ExternalType part, an EGL part that
represents a Java class directly. After you have defined the ExternalType part, you
can create variables based on it and use those variables just like you would use the
names of EGL libraries.
This example uses the class java.util.Random. This class has a non-static method
named nextInt which returns a random integer. Again, for the purposes of EGL
programming, imagine that the class is a library and the methods are functions.
1. In an EGL source file, begin defining the ExternalType part by giving it the
name of the Java class you want to use.
ExternalType Random type JavaObject
{packageName = "java.util",
javaName = "Random"}
//prototypes go here
end
Note that the name of the Java class is divided into two properties:
v packageName is the name of the package that holds the class. Java packages
and EGL packages work in much the same way.
v javaName is the name of the Java class itself. You can name the ExternalType
part with the same name as the class if you want to.2. Within the ExternalType part, create function prototypes that represent the
methods in the class that you want to use:
ExternalType Random type JavaObject
{packageName = "java.util",
javaName = "Random"}
function nextInt() returns(int);
end
Again, function prototypes in Java are similar to function prototypes in EGL,
such as those in an Interface part. They list the function or method name, its
arguments, and its return value, but have no internal logic. Here, a prototype
links a function in the ExternalType part to a method in the Java class.
Also, you must be careful to match Java types to compatible EGL types and
vice versa. Tables that associate EGL parts and Java parts are available in
″Mapping EGL primitives to Java″ in the EGL Language Reference.
3. The ExternalType part also requires a constructor. In EGL terms, a constructor is
a function that runs when a new variable that is based on the part is created.
Constructors are not commonly used in EGL; for more information about them,
see ″new operator″ in the EGL Language Reference.
ExternalType Random type JavaObject
{packageName = "java.util",
javaName = "Random"}
function nextInt() returns(int);
constructor();
end
4. To create a variable based on an ExternalType part, you must first call its
constructor with the new keyword and the name of the part:
myRandomGenerator Random = new Random();
The code new Random() is actually a function call to the constructor() function
prototype in the part definition, which in turn refers to the constructor of the
Java class.
106 EGL Programmer’s Guide
5. Use the functions in ExternalType just like you were using an EGL library:
myInt int = myRandomGenerator.nextInt();
sysLib.writeStderr(strLib.formatNumber(myInt));
Here is an example of a complete program that uses an ExternalType part as
explained above:
/*
Writes a random integer to the console
using an ExternalType part
*/
program ExternalTypeTest type BasicProgram
function main()
myRandomGenerator Random = new Random();
myInt int = myRandomGenerator.nextInt();
SysLib.writeStderr(StrLib.formatNumber(myInt));
end
end
externalType Random type JavaObject
{packageName = "java.util",
javaName = "Random"}
constructor();
function nextInt() returns(int);
end
For more details on the ExternalType part, see ″ExternalType part″ in the EGL
Language Reference.
Related tasks
“Common programming tasks” on page 103These topics contain information on how to complete several common
programming tasks in EGL.
Calling C functions with the call statement
EGL programs can invoke C functions with the call statement. Follow these steps
to invoke a C function from EGL:
1. Identify the C function to call. This function must return an integer value; zero
indicates success and any other value prompts EGL to throw an
InvocationException from the statement that invoked the C function.
2. Link to the C function and the DLL containing that function using a callLink
element with type set to remoteCall, as explained in the EGL Generation Guide.
3. Call the function using the following syntax:
call functionName (parameters);
Use the pgmName property of the callLink element as functionName, and any
parameters to pass to the function as parameters. To map EGL data types to C
data types for use in these parameters, see “Mapping EGL data types to C.” Related reference
“Mapping EGL data types to C”
Mapping EGL data types to C
The following table matches EGL primitive types to C primitive types for use in
calling C functions with the call statement, as explained in “Calling C functions
with the call statement.”
Working with EGL code 107
Table 25. EGL primitives and C primitives
EGL primitive C type
INT int (signed 4-byte integer)
SMALLINT short (signed 2-byte integer)
BIGINT long long (signed 8-byte integer)
NUM COBOL zoned format. For ASCII, the sign
bits are x30 for a positive number and x70
for a negative number. For EBCDIC, the sign
bits are xF0 for a positive number and xD0
for a negative number
NUMC COBOL zoned format. For ASCII, the sign
bits are x30 for a positive number and x70
for a negative number. For EBCDIC, the sign
bits are xC0 for a positive number and xD0
for a negative number
DECIMAL, MONEY COBOL packed format. The sign bits are xC
for a positive number and xD for a negative
number.
PACF COBOL packed format. The sign bits are xF
for a positive number and xD for a negative
number.
FLOAT double
SMALLFLOAT float
BOOLEAN char, with 1 representing true and 0
representing false
HEX unsigned char
CHAR char
MBCHAR, DBCHAR char; use mbstowcs from stdlib.h to convert
to wchar_t
UNICODE, STRING char, with data in the UTF-16 encoding, two
bytes per character. Use mbstowcs from
stdlib.h to convert to wchar_t. On Windows®
and Linux®, the data is in little-endian order;
on other systems, the data is in big-endian
order.
DATE char, in yyyMMdd format, with digits stored
as ″0″ through ″9″
TIME char, in HHmmss format, with digits stored
as ″0″ through ″9″
TIMESTAMP char, with digits stored as ″0″ through ″9″
INTERVAL char, starting with ″+″ or ″-″ followed by the
digits of the value as ″0″ through ″9″
The values of the text types (CHAR, MBCHAR, DBCHAR, UNICODE, STRING),
data and time types (DATE, TIME, TIMESTAMP, and INTERVAL), and HEX do not
end with a null byte. You can use StrLib.setNullTerminator to convert trailing
blanks to null, or StrLib.setBlankTerminator to convert trailing nulls to blanks.
For arrays, the data passed to the C function is as follows, in this order:
1. An INT value representing the current length of the array
108 EGL Programmer’s Guide
2. An INT value representing the maximum size of the array
3. The following data for each element in the array:
a. If the element is a STRING or a record, an INT value representing the
length of the element’s data
b. The data of the element
c. If the element is nullable, a SHORT representing the element’s nullability. If
the element is nullable and has a null value, the value of the SHORT is -1.
d. If the element is nullable, a SHORT as a filler value. EGL ignores this value.
For non-structured records, the data passed to the C function is as follows, in this
order:
1. An INT value, representing the number of fields
2. The following data for each field in the record:
a. An INT value representing the length of the field’s data
b. The field’s data
c. If the field is nullable, a SHORT representing the field’s nullability. If the
field is nullable and has a null value, the value of the SHORT is -1.
d. If the element is nullable, a SHORT as a filler value. EGL ignores this value.
For structured records, EGL passes the data of the lowest-level fields. You could
define a C struct with the same structure as the record.
Related reference
“Calling C functions with the call statement” on page 107
Calling C functions through EGL libraries
EGL programs can invoke C functions through Library parts with the stereotype
nativeLibrary.
Follow these steps to prepare to invoke a C function from EGL:
1. Identify the C functions to use in your EGL program and make sure they
return an INT value of zero it they succeed.
2. Download the EGL runtimes and extract the stack library and application object
file to your computer:
a. Download the EGL runtime file as explained in ″Installing the EGL runtime
code for Java″ in the EGL Generation Guide.
b. Unzip the file to a temporary directory and find the following files:
For the platform-specific stack libraries:
v AIX®: EGLRuntimes/Aix/bin/libstack.so
v Linux: EGLRuntimes/Linux/bin/libstack.so
v Win32:
EGLRuntimes/Win32/bin/stack.dll
EGLRuntimes/Win32/bin/stack.lib
For the platform-specific application object files:
v AIX: EGLRuntimes/Aix/bin/application.o
v Linux: EGLRuntimes/Linux/bin/application.o
v Win32: EGLRuntimes/Win32/bin/application.obj3. Compile all C code into one shared library and link it with the appropriate
platform-specific stack library.
Working with EGL code 109
Your C code receives values from EGL using pop external functions and returns
values to EGL using return external functions.
To compile all C code into a shared library:
a. Using standard methods, compile all of your C code into one shared library
and link it with the appropriate platform-specific EGL stack library.
b. In the following platform-specific examples, file1.c and file2.c are C files
containing functions invoked from EGL:
On AIX (the ld command must be on a single line):
cc -c -Iincl_dir file1.c file2.c
ld -G -b32 -bexpall -bnoentry
-brtl file1.o file2.o -Lstack_lib_dir
-lstack -o lib1_name -lc
On Linux (the gcc command must be on a single line):
cc -c -Iincl_dir file1.c file2.c
gcc -shared file1.o file2.o -Lstack_lib_dir
-lstack -o lib1_name
On Windows (the link command must be on a single line):
cl /c -Iincl_dir file1.c file2.c
link /DLL file1.obj file2.obj
/LIBPATH:stack_lib_dir
/DEFAULTLIB:stack.lib /OUT:lib1_name
incl_dir
The directory location for the header files.
stack_lib_dir
The directory location for the stack library.
lib1_name
The name of the output library.
Note: If your C code is using any of the IBM Informix ESQL/C library
functions (BIGINT, DECIMAL, DATE, INTERVAL, DATETIME), then the
ESQL/C library must also be linked.
4. Create a function table.
The function table is a C source file which includes the names of all C
functions to be invoked from the EGL program. In the following function table
example, c_fun1 and c_fun2 are names of the C functions. All of the functions
identified in the code must have been exported from the C shared library
created in a previous step.
#include <stdio.h>
struct func_table {
char *fun_name;
int (*fptr)(int);
};
extern int c_fun1(int);
extern int c_fun2(int);
/* Similar prototypes for other functions */
struct func_table ftab[] =
{
"c_fun1", c_fun1,
"c_fun2", c_fun2,
/* Similarly for other functions */
"", NULL
};
110 EGL Programmer’s Guide
Create a function table based on the example above, and populate the function
table with the appropriate C functions. Indicate the end of the function table
with "", NULL.
5. Compile the function table and the appropriate platform-specific application
object file into a shared library, and link this shared library with the shared
library created in Step 2 and the stack library.
The application object file is the interface between the EGL code and the C
code.
The following two artifacts must be compiled into one shared library and
linked with the stack library and the library created in Step 2 above:
v function table
v application object file
Compile the new shared library using the following example, where ftable.c is
the name of the function table and mylib is the name of the C shared library
created in Step 2 and lib_dir is the directory location for mylib. Specify
lib2_name by using the dllName property or the vgj.defaultI4GLNativeLibrary
Java runtime property.
On AIX (the ld command must be on a single line):
cc -c ftable.c
ld -G -b32 -bexpall -bnoentry
-brtl ftable.o application.o
-Lstack_lib_dir -lstack -Llib_dir
-lmylib -o lib2_name -lc
On Linux (the gcc command must be on a single line):
cc -c ftable.c
gcc -shared ftable.o application.o
-Lstack_lib_dir -lstack -Llib_dir
-lmylib -o lib2_name
On Windows (the link command must be on a single line):
cl /c ftable.c
link /DLL ftable.obj application.obj
/LIBPATH:stack_lib_dir
/DEFAULTLIB:stack.lib
/LIBPATH:lib_dir
/DEFAULTLIB:mylib.lib /OUT:lib2_name
Link the three libraries together.
With your C shared library, function table, and stack library linked, you are now
ready to invoke the C functions from your EGL code. For information on how to
invoke a C function in EGL, see Invoking a C function from an EGL program.
Related reference
“BIGINT functions for C” on page 113
“Mapping EGL data types to C” on page 107
“DATE functions for C” on page 114
“DATETIME and INTERVAL functions for C” on page 115
“DECIMAL functions for C” on page 116
“Invoking a C function from an EGL program” on page 112
“Return functions for C” on page 120
“Stack functions for C” on page 117
Working with EGL code 111
Invoking a C function from an EGL program
You can invoke (or call) a C function from an EGL program through a Library part
with the stereotype nativeLibrary. Prior to following the instructions below, you
must compile and link your C code as identified in “Calling C functions through
EGL libraries” on page 109.
To invoke a C function from an EGL program:
1. Using the function invocation statement, specify the following:
v The name of the C function
v Any arguments to pass to the C function
v Any variables to return to the EGL program2. Create an EGL Library part with the stereotype nativeLibrary containing the
function definition.
3. With the USE statement, specify the EGL native library in the calling module.
For example, the following function invocation statement calls the C function
sendmsg( )
sendmsg(chartype, 4, msg_status, return_code);
It passes two arguments (chartype and 4, respectively) to the function and expects
two arguments to be passed back (msg_status and return_code, respectively). This
is made clear by defining the function in a native library as follows:
Library I4GLFunctions type nativeLibrary
{callingConvention = I4GL, dllName = "mydll"}
Function sendmsg(chartype char(10) in, i int in,
msg_status int out, return_code int out)
end
end
The arguments passed are specified using the ″in″ parameter and the arguments to
be returned are specified using the ″out″ parameter.
callingConvention
specifies that the arguments will be passed between functions and the calling
code using the argument stack mechanism.
dllName
specifies the C shared library in which this function exists.
Note: The C shared library name can also be specified using the
vgj.defaultI4GLNativeLibrary system property. If both dllName and the system
property have been specified, the dllName will be used.
The C function receives an integer argument that specifies how many values were
pushed on the argument stack (in this case, two arguments). This is the number of
values to be popped off the stack in the C function. The function also needs to
return values for the msg_status and return_code arguments before passing control
back to the EGL program.
The C function should not assume it has been passed the correct number of
stacked values. The C function should test its integer argument to see how many
EGL arguments were stacked for it.
This example shows a C function that requires exactly one argument:
112 EGL Programmer’s Guide
int nxt_bus_day(int nargs);
{
int theDate;
if (nargs != 1)
{
fprintf(stderr,
"nxt_bus_day: wrong number of parms (%d)\n",
nargs );
ibm_lib4gl_returnDate(0L);
return(1);
}
ibm_lib4gl_popDate(&theDate);
switch(rdayofweek(theDate))
{
case 5: /* change friday -> monday */
++theDate;
case 6: /* saturday -> monday*/
++theDate;
default: /* (sun..thur) go to next day */
++theDate;
}
ibm_lib4gl_returnDate(theDate); /* stack result */
return(1) /* return count of stacked */
}
The function returns the date of the next business day after a given date. Because
the function must receive exactly one argument, the function checks for the
number of arguments passed. If the function receives a different number of
arguments, it terminates the program (with an identifying message).
Related reference
“BIGINT functions for C”
“Mapping EGL data types to C” on page 107
“DATE functions for C” on page 114
“DATETIME and INTERVAL functions for C” on page 115
“DECIMAL functions for C” on page 116
“Stack functions for C” on page 117
“Return functions for C” on page 120
“Calling C functions through EGL libraries” on page 109
BIGINT functions for C
Note: The following BIGINT functionality is available only to users of IBM
Informix ESQL/C. To use these functions, ESQL/C users will need to
manually link their C code to the ESQL/C libraries.
The BIGINT data type is a machine-independent method for representing numbers
in the range of -263-1 to 263-1. ESQL/C provides routines that facilitate the
conversion from the BIGINT data type to other data types in the C language.
The BIGINT data type is internally represented with the ifx_int8_t structure.
Information about the structure can be found in the header file int8.h, which is
included in the ESQL/C product. Include this file in all C source files that use any
of the BIGINT functions.
All operations on int8 type numbers must be performed using the following
ESQL/C library functions for the int8 data type. Any other operations,
modifications, or analyses can produce unpredictable results. The ESQL/C library
provides the following functions that allow you to manipulate int8 numbers and
Working with EGL code 113
convert int8 type numbers to and from other data types.
Function Name Description
ifx_int8add( ) Adds two BIGINT type values
ifx_int8cmp( ) Compares two BIGINT type numbers
ifx_int8copy( ) Copies an ifx_int8_t structure
ifx_int8cvasc( ) Converts a C char type value to a BIGINT type number
ifx_int8cvdbl( ) Converts a C double type number to a BIGINT type number
ifx_int8cvdec( ) Converts a decimal type value into a BIGINT type value
ifx_int8cvflt( ) Converts a C float type value into a BIGINT type value
ifx_int8cvint( ) Converts a C int type number into a BIGINT type number
ifx_int8cvlong( ) Converts a C long (int on 64 bit machine) type value to a
BIGINT type value
ifx_int8cvlong_long( ) Converts a C long long type (8-byte value, long long in 32 bit
and long in 64 bit) value into a BIGINT type value
ifx_int8div( ) Divides two BIGINT numbers
ifx_int8mul( ) Multiples two BIGINT numbers
ifx_int8sub( ) Subtracts two BIGINT numbers
ifx_int8toasc( ) Converts a BIGINT type value to a C char type value
ifx_int8todbl( ) Converts a BIGINT type value to a C double type value
ifx_int8todec( ) Converts a BIGINT type number into a decimal type number
ifx_int8toflt( ) Converts a BIGINT type number into a C float type number
ifx_int8toint( ) Converts a BIGINT type value to a C int type value
ifx_int8tolong( ) Converts a BIGINT type value to a C long (int on 64 bit
machine) type value
ifx_int8tolong_long( ) Converts a C long long (long on 64 bit machine) type to a
BIGINT type value
For more information about the individual functions, see the following: IBM
Informix ESQL/C Programmer’s Manual.
Related reference
“DATE functions for C”
“DATETIME and INTERVAL functions for C” on page 115
“DECIMAL functions for C” on page 116
“Invoking a C function from an EGL program” on page 112
DATE functions for C
Note: The following DATE functionality is available only to users of IBM Informix
ESQL/C. To use these functions, ESQL/C users will need to manually link
their C code to the ESQL/C libraries.
The following date-manipulation functions are in the ESQL/C library. They convert
dates between a string format and the internal DATE format.
Function Name Description
rdatestr( ) Converts an internal DATE to a character string format
114 EGL Programmer’s Guide
Function Name Description
rdayofweek( ) Returns the day of the week of a date in internal format
rdefmtdate( ) Converts a specified string format to an internal DATE
rfmtdate( ) Converts an internal DATE to a specified string format
rjulmdy( ) Returns month, day, and year from a specified DATE
rleapyear( ) Determines whether the specified year is a leap year
rmdyjul( ) Returns an internal DATE from month, day, and year
rstrdate( ) Converts a character string format to an internal DATE
rtoday( ) Returns a system date as an internal DATE
For more information about the individual functions, see the following: IBM
Informix ESQL/C Programmer’s Manual.
Related reference
“BIGINT functions for C” on page 113
“DATETIME and INTERVAL functions for C”
“DECIMAL functions for C” on page 116
“Invoking a C function from an EGL program” on page 112
DATETIME and INTERVAL functions for C
Note: The following DATETIME and INTERVAL functionality is available only to
users of IBM Informix ESQL/C. To use these functions, ESQL/C users will
need to manually link their C code to the ESQL/C libraries.
The DATETIME and INTERVAL data types are internally represented with the
dtime_t and intrvl_t structures, respectively. Information about these structures can
be found in the header file datetime.h, which is included in the ESQL/C product.
Include this file in all C source files that use any of the DATETIME and INTERVAL
functions.
You must use the following ESQL/C library functions for the datetime and
interval data types to perform all operations on those types of values.
Function Name Description
dtaddinv( ) Adds an interval value to a datetime value
dtcurrent( ) Gets the current date and time
dtcvasc( ) Converts an ANSI-compliant character string to a
datetime value
dtcvfmtasc( ) Converts a character string with a specified format to a
datetime value
dtextend( ) Changes the qualifier of a datetime value
dtsub( ) Subtracts one datetime value from another
dsubinv() Subtracts an interval value from a datetime value
dttoasc( ) Converts a datetime value to an ANSI-compliant
character string
dttofmtasc( ) Converts a datetime value to a character string with a
specified format
Working with EGL code 115
Function Name Description
incvasc( ) Converts an ANSI-compliant character string to an
interval value
incvfmtasc( ) Converts a character string with a specified format to
an interval value
intoasc( ) Converts an interval value to an ANSI-compliant
character string
intofmtasc( ) Converts an interval value to a character string with a
specified format
invdivdbl( ) Divides an interval value by a numeric value
invdivinv( ) Divides an interval value by another interval value
invextend( ) Extends an interval value to a different interval
qualifier
invmuldbl( ) Multiples an interval value by a numeric value
For more information about the individual functions, see the following: IBM
Informix ESQL/C Programmer’s Manual.
Related reference
“BIGINT functions for C” on page 113
“DATE functions for C” on page 114
“DECIMAL functions for C”
“Invoking a C function from an EGL program” on page 112
DECIMAL functions for C
Note: The following DECIMAL functionality is available only to users of IBM
Informix ESQL/C. To use these functions, ESQL/C users will need to
manually link their C code to the ESQL/C libraries.
The data type DECIMAL is a machine-independent method for representing
numbers of up to 32 significant digits, with or without a decimal point, and with
exponents in the range -128 to +126. ESQL/C provides routines that facilitate the
conversion of DECIMAL-type numbers to and from every data type allowed in the
C language. DECIMAL-type numbers consist of an exponent and a mantissa (or
fractional part) in base 100. In normalized form, the first digit of the mantissa must
be greater than zero.
The DECIMAL date type is internally represented with the dec_t structure. The
decimal structure and the type definition dec_t can be found in the header file
decimal.h, which is included in the ESQL/C product. Include this file in all C
source files that use any of the decimal functions.
All operations on decimal type numbers must be performed using the following
ESQL/C library functions for the decimal data type. Any other operations,
modifications or analyses can produce unpredictable results.
Function Name Description
deccvasc( ) Converts C int1 type to DECIMAL type
dectoasc( ) Converts DECIMAL type to C int1 type
deccvint( ) Converts C int type to DECIMAL type
116 EGL Programmer’s Guide
Function Name Description
dectoint( ) Converts DECIMAL type to C int type
deccvlong( ) Converts C int4 type to DECIMAL type
dectolong( ) Converts DECIMAL type to C int4 type
deccvflt( ) Converts C float type to DECIMAL type
dectoflt( ) Converts DECIMAL type to C float type
deccvdbl( ) Converts C double type to DECMAL type
dectodbl( ) Converts DECIMAL type to C double type
decadd( ) Adds two DECIMAL numbers
decsub( ) Subtracts two DECIMAL numbers
decmul( ) Multiplies two DECIMAL numbers
decdiv( ) Divides two DECIMAL numbers
deccmp( ) Compares two DECIMAL numbers
deccopy( ) Copies a DECIMAL number
dececvt( ) Converts DECIMAL value to ASCII string
decfcvt( ) Converts DECIMAL value to ASCII string
For more information about the individual functions, see the following: IBM
Informix ESQL/C Programmer’s Manual.
Related reference
“BIGINT functions for C” on page 113
“DATE functions for C” on page 114
“DATETIME and INTERVAL functions for C” on page 115
“Invoking a C function from an EGL program” on page 112
Stack functions for C
To call a C function, EGL uses an argument stack, a mechanism that passes
arguments between the functions and the calling code. The EGL calling function
pushes its arguments onto the stack and the called C function pops them off of the
stack to use the values. The called function pushes its return values onto the stack
and the caller pops them off to retrieve the values. The pop and return external
functions are provided with the argument stack library. The pop external functions
are described below according to the data type of the value that each pops from
the argument stack. The return external functions are described in Return functions
for C.
Note: The pop functions were originally used with IBM Informix 4GL (I4GL);
hence the inclusion of ″4gl″ in the function names.
Library functions for returning values
You can call the following library functions from a C function to pop number
values from the argument stack:
v extern void ibm_lib4gl_popMInt(int *iv)
v extern void ibm_lib4gl_popInt2(short *siv)
v extern void ibm_lib4gl_popInt4(int *liv)
v extern void ibm_lib4gl_popFloat(float *fv)
Working with EGL code 117
v extern void ibm_lib4gl_popDouble(double *dfv)
v extern void ibm_lib4gl_popDecimal(dec_t *decv)
v extern void ibm_lib4gl_popInt8(ifx_int8_t *bi)
The following table and similar tables below map the return function names
between I4GL pre-Version 7.31 and Version 7.31 and later:
Pre-Version 7.31 name Version 7.31 and later name
popint ibm_lib4gl_popMInt
popshort ibm_lib4gl_popInt2
poplong ibm_lib4gl_popInt4
popflo ibm_lib4gl_popFloat
popdub ibm_lib4gl_popDouble
popdec ibm_lib4gl_popDecimal
Each of these functions, like all library functions for popping values, performs the
following actions:
1. Removes one value from the argument stack.
2. Converts its data type if necessary. If the value on the stack cannot be
converted to the specified type, an error occurs.
3. Copies the value to the designated variable.
The structure types dec_t and ifx_int8_t are used to represent DECIMAL and
BIGINT data in a C program. For more information about the dec_t and ifx_int8_t
structure types and library functions for manipulating and printing DECIMAL and
BIGINT variables, see the IBM Informix ESQL/C Programmer’s Manual.
Library Functions for Popping Character Strings
You can call the following library functions to pop character values:
v extern void ibm_lib4gl_popQuotedStr(char *qv, int len)
v extern void ibm_lib4gl_popString(char *qv, int len)
v extern void ibm_lib4gl_popVarChar(char *qv, int len)
Pre-Version 7.31 name Version 7.31 and later name
popquote ibm_lib4gl_popQuotedStr
popstring ibm_lib4gl_popString
popvchar ibm_lib4gl_popVarChar
Both ibm_lib4gl_popQuotedStr( ) and ibm_lib4gl_popVarChar( ) copy exactly len
bytes into the string buffer *qv. Here ibm_lib4gl_popQuotedStr( ) pads with
spaces as necessary, but ibm_lib4gl_popVarChar( ) does not pad to the full length.
The final byte copied to the buffer is a null byte to terminate the string, so the
maximum string data length is len-1. If the stacked argument is longer than len-1,
its trailing bytes are lost.
The len argument sets the maximum size of the receiving string buffer. Using
ibm_lib4gl_popQuotedStr( ), you receive exactly len bytes (including trailing
blank spaces and the null), even if the value on the stack is an empty string. To
118 EGL Programmer’s Guide
find the true data length of a string retrieved by ibm_lib4gl_popQuotedStr( ), you
must trim trailing spaces from the popped value.
Note: The functions ibm_lib4gl_popString( ) and ibm_lib4gl_popQuotedStr( ) are
identical, except that ibm_lib4gl_popString( ) automatically trims any
trailing blanks.
Library Functions for Popping Time Values
You can call the following library functions to pop DATE, INTERVAL, and
DATETIME (TIMESTAMP) values:
v extern void ibm_lib4gl_popDate(int *datv)
v extern void ibm_lib4gl_popInterval(intrvl_t *iv, int qual)
You can call the following library function to pop TIMESTAMP values:
v extern void ibm_lib4gl_popDateTime(dtime_t *dtv, int qual)
Pre-Version 7.31 name Version 7.31 and later name
popdate ibm_lib4gl_popDate
popdtime ibm_lib4gl_popDateTime
popinv ibm_lib4gl_popInterval
The structure types dtime_t and intrvl_t are used to represent DATETIME and
INTERVAL data in a C program. The qual argument receives the binary
representation of the DATETIME or INTERVAL qualifier. For more information
about the dtime_t and intrvl_t structure types and library functions for
manipulating and printing DATE, DATETIME, and INTERVAL variables, see the
IBM Informix ESQL/C Programmer’s Manual.
Library Functions for Popping BYTE or TEXT Values
You can call the following function to pop a BYTE or TEXT argument:
v extern void ibm_lib4gl_popBlobLocator(loc_t **blob)
Pre-Version 7.31 name Version 7.31 and later name
poplocator ibm_lib4gl_popBlobLocator
The structure type loc_t defines a BYTE or TEXT value, and is discussed in the
IBM Informix ESQL/C Programmer’s Manual.
Any BYTE or TEXT argument must be popped as BYTE or TEXT because EGL
provides no automatic data type conversion.
Related reference
“BIGINT functions for C” on page 113
“Mapping EGL data types to C” on page 107
“Calling C functions through EGL libraries” on page 109
“DATE functions for C” on page 114
“DATETIME and INTERVAL functions for C” on page 115
“DECIMAL functions for C” on page 116
“Invoking a C function from an EGL program” on page 112
“Return functions for C” on page 120
Working with EGL code 119
Return functions for C
To call a C function, EGL uses an argument stack, a mechanism that passes
arguments between the functions and the calling code. The EGL calling function
pushes its arguments onto the stack and the called C function pops them off of the
stack to use the values. The called function pushes its return values onto the stack
and the caller pops them off to retrieve the values. The pop and return external
functions are provided with the argument stack library. The return external
functions are described below; the pop external functions used are described in
Stack functions for C.
The external return functions copy their arguments to storage allocated outside the
calling function. This storage is released when the returned value is popped. This
situation makes it possible to return values from local variables of the function.
Note: The return functions were originally used with IBM Informix 4GL (I4GL);
hence the inclusion of ″4gl″ in the function names.
Library functions for returning values
The following library functions are available to return values:
v extern void ibm_lib4gl_returnMInt(int iv)
v extern void ibm_lib4gl_returnInt2(short siv)
v extern void ibm_lib4gl_returnInt4(int lv)
v extern void ibm_lib4gl_returnFloat(float *fv)
v extern void ibm_lib4gl_returnDouble(double *dfv)
v extern void ibm_lib4gl_returnDecimal(dec_t *decv)
v extern void ibm_lib4gl_returnQuotedStr(char *str0)
v extern void ibm_lib4gl_returnString(char *str0)
v extern void ibm_lib4gl_returnVarChar(char *vc)
v extern void ibm_lib4gl_returnDate(int date)
v extern void ibm_lib4gl_returnDateTime(dtime_t *dtv)
v extern void ibm_lib4gl_returnInterval(intrvl_t *inv)
v extern void ibm_lib4gl_returnInt8(ifx_int8_t *bi)
The following table maps the return function names between I4GL pre-Version 7.31
and Version 7.31 and later:
Pre-Version 7.31 name Version 7.31 and later name
retint ibm_lib4gl_returnMInt
retshort ibm_lib4gl_returnInt2
retlong ibm_lib4gl_returnInt4
retflo ibm_lib4gl_returnFloat
retdub ibm_lib4gl_returnDouble
retdec ibm_lib4gl_returnDecimal
retquote ibm_lib4gl_returnQuotedStr
retstring ibm_lib4gl_returnString
retvchar ibm_lib4gl_returnVarChar
retdate ibm_lib4gl_returnDate
retdtime ibm_lib4gl_returnDateTime
120 EGL Programmer’s Guide
Pre-Version 7.31 name Version 7.31 and later name
retinv ibm_lib4gl_returnInterval
The argument of ibm_lib4gl_returnQuotedStr( ) is a null-terminated string. The
ibm_lib4gl_returnString( ) function is included only for symmetry; it internally
calls ibm_lib4gl_returnQuotedStr( ).
The C function can return data in whatever form is convenient. If conversion is
possible, EGL converts the data type as required when popping the value. If data
type conversion is not possible, an error occurs.
C functions called from EGL must always exit with the statement return(n), where
n is the number of return values pushed onto the stack. A function that returns
nothing must exit with return(0).
Related reference
“BIGINT functions for C” on page 113
“Mapping EGL data types to C” on page 107
“Invoking a C function from an EGL program” on page 112
“Calling C functions through EGL libraries” on page 109
“DATE functions for C” on page 114
“DATETIME and INTERVAL functions for C” on page 115
“DECIMAL functions for C” on page 116
“Stack functions for C” on page 117
C data types and EGL primitive types
The following table shows the mapping between C data types, I4GL data types,
and EGL primitive types for use in a Library part with the stereotype
nativeLibrary.
C data types Equivalent I4GL data
type
Equivalent EGL primitive type
char CHAR or CHARACTER UNICODE(1)
char NCHAR UNICODE(size)
char NVARCHAR STRING
char VARCHAR STRING
int INT or INTEGER INT
short SMALLINT SMALLINT
ifx_int8_t BIGINT BIGINT
dec_t DEC or DECIMAL(p,s,)
or NUMERIC(p)
DECIMAL(p)
dec_t MONEY MONEY
double FLOAT FLOAT
float SMALLFLOAT SMALLFLOAT
loc_t TEXT CLOB
loc_t BYTE BLOB
int DATE DATE
dtime_t DATETIME TIMESTAMP
Working with EGL code 121
C data types Equivalent I4GL data
type
Equivalent EGL primitive type
intvl_t INTERVAL INTERVAL
Related reference
“Invoking a C function from an EGL program” on page 112
Encrypting passwords
You can encrypt passwords with an EGL command-line utility. Password
encryption is supported only for Java programs and the debugger, not for COBOL
programs.
When EGL generates output files, it automatically encrypts passwords in property
files and literals that are passed to system functions. For example, here is a call to
the sqlLib.connect system function:
sqlLib.connect(myDatabase, myUserid, "myPassword");
Because the password parameter is specified as a string literal, it is automatically
encrypted in the generated code.
However, if you hard-code your password in a place other than the function call,
EGL does not encrypt the password:
myPasswordVariable string = "myPassword";
sqlLib.connect(myDatabase, myUserid, myPasswordVariable);
In this case, the password is not encrypted and is displayed in the generated
source.
You can manually encrypt your password by running the command-line utility and
using the returned encrypted value in your code:
myPasswordVariable string = "crypto:abcdef12345";
sqlLib.connect(myDatabase, myUserid, myPasswordVariable);
Following are some places where you might need to manually encrypt hard-coded
passwords:
v Variables in which you store passwords
v CallLink element properties, such as ctgKeyStorePassword
v Calls to system functions, such as sqlLib.connect, sysLib.setRemoteUser, or
VGLib.connectionService in which you do not pass the password as a literal in
the function call
When an EGL system function receives a password with the crypto: prefix, it
decrypts the password automatically. For this reason, you must encrypt any
passwords beginning with the characters crypto:; otherwise, EGL will attempt to
decrypt the non-encrypted password.
Follow these steps to encrypt a password:
1. Add your Java executable to the system’s path:
a. Obtain and install a Java SDK if you do not already have one. IBM offers a
Java SDK for download at the following Web site: http://www.ibm.com/developerworks/java/jdk/.
b. In your system’s PATH environment variable, add the location of the Java
SDK. See your operating system’s documentation for instructions.
122 EGL Programmer’s Guide
2. Open a command prompt.
3. Navigate to the following location:
<shared_resources>/plugins/
com.ibm.etools.egl.java.runtime_<version_number>
Use your own installation’s shared resources directory for the
<shared_resources> and your current version number for <version_number>.
4. Type the following command to invoke the program:
java -classpath fda7.jar com.ibm.javart.security.PasswordEncrypter
The program displays the prompt Enter text to encrypt:.
5. Type your password and press Enter. The program returns an encrypted string
beginning with the prefix crypto:.
6. Copy the entire returned string, including the crypto: prefix, into places in
which you would ordinarily hard-code your password.
7. Save the changed files and regenerate the project.
Related tasks
“Common programming tasks” on page 103These topics contain information on how to complete several common
programming tasks in EGL.
Handling errors
With EGL, you can decide how your program behaves in case of errors.
Handling errors means anticipating the kinds of problems that might occur in your
program and providing a code path for each of them. If you decide not to handle
errors, all but the most trivial (see ″I/O errors″ later in this topic) will cause your
program to terminate.
Error handling in EGL grows out of the concept of the exception, which is a
stereotype that applies to a record. EGL has a number of predefined exceptions
(see ″EGL Exception records″ in the appendix to the EGL Language Reference), or
you can define your own. Each exception record contains at least these fields:
messageID
A STRING that contains the EGL message for the exception. For example,
if you try to use an uninitialized array, EGL sets the messageID in the
NullValueException record to EGL0106E.
message
A STRING that contains a brief explanation of the problem. For example,
the message that goes with messageID EGL0106E is ″A null reference was
used.″
The exception record can contain additional fields where appropriate. For example,
the IndexOutOfBoundsException has an additional field for indexValue, which
contains the value of the array index that EGL could not process.
The try block
The EGL try keyword introduces a block of code in which you can catch and
handle exceptions. If an exception occurs inside a try block, EGL looks for an
onException statement within the try block that matches the exception type. Each
onException statement includes the declaration of an exception variable. This is a
record variable similar to variables that you declare elsewhere in EGL; the
declaration looks something like the following:
Working with EGL code 123
onException(myEx NullValueException)
This means that if EGL throws a NullValueException inside this try block, you can
access fields in that exception record. For example, you can find the EGL message
ID in myEx.msgID, as in the following example:
try
intArray[10] = 0; // this may not be initialized
onException(myEx NullValueException)
writeStdErr(myEx);
myErrorHandler(myEx);
end
The myErrorHandler() function could, for example, take care of initializing the
array and perform the assignment again.
A special type of exception, AnyException, is available to catch any exception and
is comparable to the ANY primitive type. You declare a record variable for
AnyException, and if EGL throws an exception, your variable takes on the type of
the actual exception record. Consider the following example:
try
get next mySerialRecord
onException(myEx AnyException)
myErrorHandler(myEx);
end
If you had a specific code path that you wanted to follow if EGL throws a
FileIOException, you could add a special check for that as follows:
try
get next mySerialRecord
onException(myEx FileIOException)
myErrorHandler1(myEx);
onException(myEx AnyException)
myErrorHandler2(myEx);
end
Here, myErrorHandler2() deals with any exception other than a FileIOException.
If EGL throws an exception but no onException block catches the exception, the
function ends immediately and control returns to the function that called the
function that threw the error. In this way, EGL passes the exception upward until a
function catches the exception with an onException block or the exception reaches
the main function. If the main function fails to catch the exception, the program
ends immediately and writes the message field of the exception to the log. When
an exception occurs in a called program, the calling program receives an
InvocationException rather than the original exception. Similarly, an exception in a
service function delivers a ServiceInvocationException to the calling program.
In other words, a function can catch exceptions thrown in functions it calls, as in
this example:
function FuncOne(myRec serialRecordType)
try
FuncTwo(myRec);
onException(myEx AnyException)
myErrorHandler2(myEx);
end
end
function FuncTwo(myRec serialRecordType)
get next myRec;
end
124 EGL Programmer’s Guide
Exceptions do not pass from function to function like this in V6 exception
compatibility mode, explained below.
Hard and soft I/O errors
When you are reading or writing to a file, EGL makes a distinction between hard
and soft I/O errors. The following errors are considered soft, that is, not likely to
cause a loss of data:
Table 26. Soft I/O errors
Error Meaning
duplicate For an indexed or relative record, this error indicates
a second record has the same key.
endOfFile For a serial, indexed, or relative record, this error
indicates an attempt to read past the end of the file.
noRecordFound For any record type, the error indicates an attempt to
read a record that could not be found.
Other errors, such as an invalid file format or a full file, are considered hard errors.
A hard I/O error on an indexed, relative, or serial file throws a FileIOException. A
hard I/O error on an SQL database throws an SQLException.
Soft I/O errors associate the error value with record, but do not cause an exception
to be thrown. To test for this situation, use the is or not operator. You do not have
to place the I/O statement in question inside a try block to use these operators.
However, unless you put the I/O statement inside a try block, you cannot check at
the same time for hard I/O errors:
while(TRUE) // endless loop
try
get next mySerialRecord;
if(mySerialRecord is endOfFile)
exit while;
end
onException(myEx AnyException)
myErrorHandler(myEx);
end
end
throwNrfEofExceptions property
By default, the throwNrfEofExceptions program property is set to NO, which
means that the program continues after the soft I/O errors noRecordFound and
endOfFile, even if the error occurs outside of a try block, as in the following
example:
get myCustomer;
if(myCustomer is noRecordFound)
add myCustomer;
end
However, you may prefer to have EGL throw an exception when one of these
errors occurs. You can do so by setting the throwNrfEofExceptions program
property to YES. In that case, EGL throws one of the following exceptions:
v If you are performing file I/O, EGL throws a RuntimeException.
v If you are performing SQL I/O, EGL throws an SQLException.
Working with EGL code 125
You must catch this error in a try block, or the program will terminate. Using the
previous example, if no record is found for the get statement, the program
terminates. However, either of the following techniques enables you to handle the
exception:
v Continue after the soft error:
try
get myCustomer;
end
if (myCustomer is noRecordFound)
add myCustomer;
end
v Catch the exception, which is the preferred technique:
try
get myCustomer;
onException (myEx FileIOException)
if (myCustomer is noRecordFound)
add myCustomer;
else
myErrorHandler(myEx);
end
end
Throwing your own exceptions
Using an EGL throw statement, you can throw any of the predefined system
exceptions. As in exception handling, you must declare a variable based on the
record:
nullEx NullValueException{};
...
throw nullEx;
In addition to the exceptions that the system defines, you can create your own
exception records. As with other records, you must define a Record part first, and
then declare a variable based on it.
Record CustomerException type Exception
customerNumber INT;
end
...
throw new customerException {
customerNumber = custNum,
message = "Illegal customer number" };
Custom exceptions records like this one automatically include the messageID and
message fields, just like the system exception records.
V6 exception compatibility
For compatibility with earlier versions, you can still use the error handling
methods from version 6 of EGL.
You specify V6 exception mode on a program-by-program basis when you set the
program’s v60ExceptionCompatibility property to YES. However, for best results
use the same setting for all of your programs.
V6 exceptions are typically handled through a try block. The difference is that V6
exceptions allow only a single onException statement, and do not specify an
exception type. The behavior is thus the same as if the onException statement had
an implied AnyException modifier:
126 EGL Programmer’s Guide
try
posNum = abs(myVar);
onException
if(sysVar.errorCode = "00000008") // invalid input
myErrorHandler1();
if(sysVar.errorCode = "00000012") // cannot assign value
myErrorHandler2();
else
myErrorHandler3();
end
Instead of being based on exception records, V6 exception compatibility relies on
the sysVar.errorCode system variable. If you are running in V6 exception mode,
sysVar.errorCode is set in the following cases:
v At the completion of a call statement
v After a call to a service
v After a file I/O statement such as get or replace
v After invoking many of the EGL system functions
In addition, for SQL I/O errors, V6 exception compatibility relies on the system
variables in sysVar.sqlData.
You do not need a try block to access sysVar.errorCode in V6 exception mode if
you have the vgVar.handleSysLibraryErrors system variable (for functions in
system libraries) or vgVar.handleHardIOErrors (for file and SQL I/O) set to 1:
vgVar.handleSysLibraryErrors = 1;
posNum = abs(myVar);
if(sysVar.errorCode == "00000008") // invalid input
myErrorHandler1();
else
if(sysVar.errorCode == "00000012") // cannot assign
myErrorHandler2();
else
exit program (-1);
end
end
If, however, vgVar.handleSysLibraryErrors is set to 0 (the default) and you do not
use a try block to catch exceptions, any exception will cause the program to
terminate.
For more information, see ″Exception Handling″ in the EGL Language Reference.
Related tasks
“Common programming tasks” on page 103These topics contain information on how to complete several common
programming tasks in EGL.
Customizing runtime messages
When an error occurs at Java run time, an EGL system message is displayed by
default. You can specify a customized message for each of those system messages
or for a subset of messages.
The customized messages are stored in a properties file that you identify in the
vgj.messages.file Java runtime property. This property is set with the
userMessageFile build descriptor option. For more information about the format of
a Java properties file, see ″Program properties file″ in the EGL Generation Guide.
Working with EGL code 127
When a message is required, EGL first searches the properties file specified in
vgj.messages.file. EGL compares the message ID of the required message to the
IDs of the messages in the properties file. If EGL finds a message in the properties
file with a matching ID, it uses that message. If there is no message in the
properties file with a matching ID, EGL uses the default system message. You can
also use the sysLib.getMessage system function to return a message from the
properties file specified in vgj.messages.file.
In many cases, a system message includes placeholders for the message inserts that
EGL retrieves at run time. For example, if your code submits an invalid date mask
to a system function, the message has two placeholders; one (placeholder 0) for the
date mask itself, the other (placeholder 1) for the name of the system function. In
properties-file format, the entry for the default message is as follows:
EGL0049E = Overflow when assigning {0} to {1}.
You can change the wording of the message to include all or some of the
placeholders in any order, but you cannot add placeholders. Valid examples are as
follows:
EGL0049E = Tried to assign {0} to {1} and failed.
EGL0049E = {1} = {0} : Overflow on assignment.
The program terminates if the file that is identified in the vgj.messages.file
property cannot be opened.
Other details are available in Java language documentation:
v For details on how messages are processed and on what content is valid, see the
documentation for the Java class java.text.MessageFormat.
v For details on handling characters that cannot be directly represented in the ISO
8859-1 character encoding (which is always used in properties files), see the
documentation for the Java class java.util.Properties.
Creating a customized message file
You can create a properties file that contains customized messages that are shown
when errors occur at Java run time. These messages replace the default system
messages.
1. To create a properties file for the customized messages:
a. In the Project Explorer view, right-click the JavaSource folder of your EGL
project.
b. Click New → Other.
c. In the New window, expand General and click File.
d. Click Next.
e. In the Enter or select the parent folder field, ensure that your project’s
JavaSource folder is selected.
f. In the File name field, type a name for the properties file, ending in
.properties. An example of a valid file name is messages.properties.
g. Click Finish. The new file is created and opens in the editor.2. To add customized messages to the messages file.
a. Find the message ID of the system message you want to replace, or create a
new message ID if you are adding a new message.
b. Add a line to the messages file in the following format:
messageID = customMessage
128 EGL Programmer’s Guide
messageID
The ID of the system message.
customMessage
The custom message to display in place of the system message,
including any placeholders in the message.For example, the following properties file line replaces the system message
ID EGL0049E, which by default is Overflow when assigning {0} to {1}.:
EGL0049E = Tried to assign {0} to {1} and failed.
In this example, the code strings {0} and {1} are placeholders for message
inserts that EGL retrieves at run time. These placeholders are optional in
your customized message.
c. When you are finished adding messages, save and close the messages file.3. Set the genProperties build descriptor option to GLOBAL or PROGRAM and then,
using one of the following methods, specify the messages file:
v Set the userMessageFile build descriptor option to specify name of the
messages file without the .properties extension. For example, if the
messages file is named messages.properties, set the userMessageFile build
descriptor option to messages.
The userMessageFile build descriptor option sets the vgj.messages.file Java
runtime property, the runtime property that specifies the message file. This
method applies to any type of EGL project.
v Set the vgj.messages.file Java runtime property in the J2EE deployment
descriptor (not the EGL deployment descriptor) to specify the name of the
messages file. This method applies only to projects used within the J2EE
framework. To set the vgj.messages.file runtime property in the J2EE
deployment descriptor, follow these steps:
a. In the Project Explorer view, double-click the project’s J2EE deployment
descriptor. The deployment descriptor opens in the deployment
descriptor editor.
b. Click the Variables tab.
c. Under Environment Variables, click Add. The Add Environment Entry
window opens.
d. In the Name field, type vgj.messages.file.
e. In the Type field, select String.
f. In the Value field, type the name of the messages file without the
.properties extension. For example, if the messages file is named
messages.properties, type messages.
g. Click Finish.v Set the vgj.messages.file property in the file rununit.properties to specify the
name of the messages file. This method applies only to projects used within
the J2EE framework. To set the vgj.messages.file runtime property in the file
rununit.properties, follow these steps:
a. Open the file rununit.properties in the folder JavaSource. This file is
created the first time that you generate a file with the genProperties
property set to GLOBAL. If you generate with genProperties set to PROGRAM,
the properties file is named pgmNameOrAlias.properties and is located in
the Java package of the generated program.
b. In the properties file, add the following code:
vgj.messages.file = messageFileName
Working with EGL code 129
c. Replace messageFileName with the name of the name of the messages file
without the .properties extension. For example, if the messages file is
named messages.properties, type vgj.messages.file = messages.
d. Save and close the properties file.4. If you want to localize messages into other languages, create additional
properties files for those languages:
a. Create new properties files for each language you want to provide, adding a
locale suffix to the new files to represent their language. For example, if
your original properties file was named messages.properties, a file with
messages in German might be named messages_de.properties. For more
information on locales, see “Locales for resource bundles” on page 218.
b. In each new file, repeat the message IDs that you used in the first
properties file.
c. In the new files, translate the text of the message, without changing the
message ID.
d. Set the application to use the specified language by either generating with
the targetNLS build descriptor option to the name of the language or by
setting the language with the sysLib.setLocale() system function.5. Generate any EGL file in the project. Related tasks
“Localizing text in Web applications” on page 214
The EGL editor
The EGL code editor looks and works like a standard text editor or code editor for
other languages, but it has additional features to help you edit EGL code. The code
editor highlights invalid syntax, provides an explanation for problems in the code,
colors keywords, strings, and comments, and helps you write EGL code.
The basics
You can open an EGL source file in the EGL editor either by double-clicking it in
the Project Explorer view or by right-clicking it and then clicking Open with →
EGL Editor.
The editor uses many of the same editing functions as the other text and code
editors in the workbench:
v Cut, copy, and paste code with commands in the Edit menu.
v Save the current file by pressing CTRL+S, clicking the Save button on the
toolbar, or clicking File → Save.
v Generate the current file by pressing CTRL+G or right-clicking the file in the
Project Explorer view and then clicking Generate.
v Undo your most recent change by pressing CTRL+Z or by clicking Edit → Undo.
v Switch between open files, by clicking the tabs at the top of the editor.
v Locate the file in a different view by clicking Navigate → Show In and then click
Project Explorer, Outline, or Navigator.
v To indent or outdent code, select one or more lines, right-click, and then click
Shift Right or Shift Left.
v To comment or uncomment one or more lines of code, select one or more lines,
right-click, and then click Comment or Uncomment.
130 EGL Programmer’s Guide
Some functions of the editor require that you select one or more lines of code
(sometimes referred to as a block of code). You can select code in any of these ways
v Click and drag the mouse over one or more lines of code.
v Double-click a single word to select that word.
v Put the cursor at the beginning of a code block, hold the Shift key, and use the
arrow keys to move the cursor to the end of the block. Also, you can
double-click at the beginning or end of a code block to select the entire code
block.
v Press Ctrl+A to select the entire file.
You can control how EGL code is displayed in the editor. See “Setting preferences
for EGL text” on page 152.
Writing code faster
The main tool that the EGL editor provides to speed up code development time is
code assist. Code assist searches for valid keywords, variables, or part names that
begin with the first few characters that you type and the matching code. To
activate code assistance, press CTRL+Space and choose a keyword, variable, part,
or function from the list of options. You can also type the first few characters of a
keyword, part, or variable to filter the list. See “Code assistant” on page 132.
Code assist can also insert larger code templates into your code, such as a
framework for a part. See “Code templates” on page 133.
The editor also includes wizards that can generate EGL code into the file you are
editing. For example, the DataItem part source assistant can help you set the
properties for a DataItem part. See “Editing DataItem parts with the source
assistant” on page 141.
Getting help
The editor provides dynamic help for most EGL keywords. To activate dynamic
help, highlight an EGL keyword, such as package, and press F1. Additionally, the
F1 key provides dynamic help when you are in most EGL-related wizards and
windows.
Organizing code
The EGL editor can help organize your import statements. To organize import
statements, right-click in the editor and then click Organize Imports. The editor
changes your import statements in the following ways:
v The editor arranges the import statements in the order specified in the Organize
Imports preference page. See “Setting preferences for organizing import
statements in the EGL editor” on page 150.
v The editor removes any unused import statements.
v The editor combines multiple import statements to the same package into a
single import statement with a wildcard character, based on the settings in the
preference page.
v The editor attempts to add import statements for any parts that are used in the
file but are not in scope.
With the editor, you can also ″fold″ code. Folding a block of code hides that code
temporarily, so that you can see only the parts of the source file that you want to
Working with EGL code 131
see. To fold a block of code, click the minus icon on the left side of the editor; the
code collapses temporarily. You can also fold arbitrary lines of code by selecting
them, right-clicking, and then clicking Fold Text. Click the icon again to restore the
code. Folding does not change the behavior of your code in any way.
Depending on the folding preference settings, certain blocks of code may be folded
automatically when you open a source file in the editor. See “Setting preferences
for folding in the EGL editor” on page 149.
Related tasks
“Working with EGL code” on page 103
Code assistant
The EGL code assistant is a tool that you can use to complete programming
statements without having to type the entire statement. It provides a way to
quickly insert an EGL keyword, function, variable, property, or code template.
When you initiate the code assistant, it presents all of the available keywords that
are legal at that position, which may be a long list. However, you can control the
amount of information that is displayed when you initiate the code assistant. You
can filter the displayed information by entering the beginning characters of the
function that you want to insert and then initiate the code assistant. For example, if
you are looking for program, type pr and press Ctrl+Space. The displayed list will
contain those commands, templates, and code statements that begin with pr. You
can narrow the list more by increasing the number of characters that you type for
the search argument (for example, type progr).
To use the code assistant, do the following steps:
1. Within an EGL source file, press Ctrl + Space. The code assistant displays a list
of EGL keywords and code templates legal at your current position.
To reduce the number of items in the list, type at least one character of the
keyword or template you are searching for before or after activating the code
assistant.
2. Select the desired code from the list by doing one of the following:
v Use the arrow keys to select an option and press Enter.
v Click on an option in the list.3. The code is inserted into the current location of the cursor. You can then
modify the inserted code.
4. If you inserted a code template with variables rather than a single keyword,
those variables are highlighted in the inserted code temporarily. Press the Tab
key to move to a highlighted variable.
The code assistant is context-sensitive. For example, if you are in a set-value block
for a program, the code assistant offers only properties that are valid for programs.
You can use the code assistant to add additional properties as follows:
1. Type a comma (,) after the last property-value pair.
2. Position the cursor after the comma and press Ctrl+Space to initiate the code
assistant. The resulting list shows properties that are both valid for the program
and not yet included in the program.
3. Select the desired code as described above. Related concepts
“Code templates” on page 133
132 EGL Programmer’s Guide
“Code snippets” on page 138Snippets are code objects that are reusable programming objects. Snippets can
be a piece of code or a complete programming task. In addition to the default
snippets provided in the workbench, you can create your own snippets.
Code templates
A code template is an outline of code that can be reused. Typically, templates are
used for functions that are routine, such as retrieving data from a data source. To
use a template, that template must be enabled in the code template preferences.
You can create, edit, remove, import, or export a template by using the Preferences
window. If you have modified the list of default templates, you can restore the list
to its default value. You can also restore a removed template if you have not exited
from the workbench since it was removed.
To see the templates, you must type a prefix and then press Ctrl+Space. All
templates whose name begins with that prefix are included in the code assist list,
provided the on-screen cursor is in a position where the code produced by the
template is syntactically allowed. The templates are always at the bottom of the list
for code assist. For example, if the cursor is position in a place where a function is
permitted, and you type w, the webservice_function templates are listed in code
assist. If you select one of the templates, the w is replaced by the code from the
template.
Content and naming considerations for code templates
The that name you give your code templates is significant because that name is the
keyword that represents the code template, not the first word of the code in the
template itself. For example, assume you have created a code template named
″myFunction″ that consists of an EGL function, beginning with the keyword
function. When you want to insert this template, you must begin by typing letters
from the name, such as my or myFunc, not f or fun. Templates are displayed in code
assist only when you have typed at least one character to filter the list of options.
Also, if you begin the code template with an EGL keyword such as function, the
template will be available only when the cursor is in a place where that keyword is
valid. In this case, the function template would be an option only if the cursor is in
a place where a function would be valid. If the beginning of the template is not an
EGL keyword, the template can be inserted anywhere.
Related concepts
“Code assistant” on page 132
“Code snippets” on page 138Snippets are code objects that are reusable programming objects. Snippets can
be a piece of code or a complete programming task. In addition to the default
snippets provided in the workbench, you can create your own snippets. Related tasks
“Enabling and disabling code templates” on page 134
“Creating code templates” on page 134
“Editing code templates” on page 135
“Removing code templates” on page 137
“Importing code templates” on page 136
“Exporting code templates” on page 136
“Restoring default code templates” on page 138
Working with EGL code 133
Enabling and disabling code templates
To limit the list of code templates that is offered to you in the editor, you can
enable or disable specific templates.
To enable code templates in the EGL editor, follow these steps:
1. From the main menu, click Window → Preferences.
2. From the navigation tree, expand EGL → Editor and then click Templates. A list
of templates is displayed.
3. From the Preferences window, select the check box to the left of a template
name that you want to be available in the EGL editor. Similarly, to make a
template unavailable, clear the related check box.
4. To save your changes, click Apply.
5. Click OK to close the window.
To disable code templates in the EGL editor, follow these steps:
1. From the main menu, click Window → Preferences.
2. From the navigation tree, expand EGL → Editor and then click Templates. A list
of templates is displayed.
3. From the Preferences window, clear the check box to the left of the template
names that you do not want to show in the EGL editor.
4. To save your changes, click Apply.
5. Click OK to close the window. Related concepts
“Code templates” on page 133 Related tasks
“Creating code templates”
“Importing code templates” on page 136
“Exporting code templates” on page 136
“Removing code templates” on page 137
“Restoring default code templates” on page 138
Creating code templates
You can create your own code template. After the template is created it is shown in
the list of templates.
To create a new code template, follow these steps:
1. From the main menu, click Window → Preferences.
2. From the navigation tree, expand EGL → Editor and then click Templates.
3. From the Preferences window, click New.
4. In the New Template window, specify both a name and a description to
uniquely identify the template. When you want to use the new template, you
will type all or the beginning of the name and then activate code assist. For
more information on naming considerations, see “Code templates” on page 133.
5. In the Pattern field, type the template itself:
v Type any text that you want to display.
v To place an existing variable at the current cursor position, click Insert
Variable, then double-click a variable. When you insert the template in the
EGL editor, each of those variables resolves to the appropriate value.
134 EGL Programmer’s Guide
v To create a custom variable, type a dollar sign ($) followed by a left brace ({),
a string, and a right brace (}), as in this example:
${variable}
You might find it easier to insert an existing variable and change the name
for your own use.
When you insert a custom template in the EGL editor, each variable is
highlighted to indicate that a value is required.
v You can select an area of functionality for the template from the Context list,
but user-defined templates are not filtered by capability like the default
templates are. For user-defined templates, this value is for informational
purposes only.6. Click OK to create the template.
7. To save your changes, click Apply.
8. Click OK to close the window.
Related concepts
“Code assistant” on page 132
“Code templates” on page 133
“Code snippets” on page 138Snippets are code objects that are reusable programming objects. Snippets can
be a piece of code or a complete programming task. In addition to the default
snippets provided in the workbench, you can create your own snippets. Related tasks
“Enabling and disabling code templates” on page 134
“Importing code templates” on page 136
“Exporting code templates” on page 136
“Removing code templates” on page 137
“Restoring default code templates” on page 138
Editing code templates
You can modify existing code templates to fit your specific coding needs.
To edit an existing code template, follow these steps:
1. From the main menu, click Window → Preferences.
2. From the navigation tree, expand EGL → Editor and then click Templates. A list
of templates is displayed.
3. Click the desired template from the table and click Edit.
4. Change the desired fields in the Edit Template dialog box. Click OK when you
are finished.
5. To save your changes, click Apply.
6. Click OK to close the window.
If the code template you edited is one of the templates provided with the product,
you can revert to the original template as follows:
1. From the main menu, click Window → Preferences.
2. From the navigation tree, expand EGL → Editor and then click Templates. A list
of templates is displayed.
3. Click the desired template from the table and then click Revert to Default.
4. To save your changes, click Apply.
5. Click OK to close the window.
Working with EGL code 135
Related concepts
“Code assistant” on page 132
“Code templates” on page 133
“Code snippets” on page 138Snippets are code objects that are reusable programming objects. Snippets can
be a piece of code or a complete programming task. In addition to the default
snippets provided in the workbench, you can create your own snippets. Related tasks
“Enabling and disabling code templates” on page 134
“Creating code templates” on page 134
“Importing code templates”
“Exporting code templates”
“Removing code templates” on page 137
“Restoring default code templates” on page 138
Exporting code templates
You can export code templates to a file system.
To export code templates, follow these steps:
1. From the main menu, click Window → Preferences.
2. From the navigation tree, expand EGL → Editor and then click Templates. A list
of templates is displayed.
Note: As in other applications on Windows 2000/NT/XP, you can click an
entry to select it; can use Ctrl-click to select or deselect an entry without
affecting other selections; and can use Shift-click to select a set of entries
that are contiguous to the entry you last clicked.
3. Select the desired templates from the table and click Export.
4. Select the location to save the template file in the Exporting Templates window.
You can browse the various locations to locate the place that you want to save
the templates.
5. Click Save to save the templates in the specified location.
Related concepts
“Code assistant” on page 132
“Code templates” on page 133
“Code snippets” on page 138Snippets are code objects that are reusable programming objects. Snippets can
be a piece of code or a complete programming task. In addition to the default
snippets provided in the workbench, you can create your own snippets. Related tasks
“Enabling and disabling code templates” on page 134
“Creating code templates” on page 134
“Importing code templates”
“Removing code templates” on page 137
“Restoring default code templates” on page 138
Importing code templates
You can import code templates from a file system. To import code templates,
follow these steps:
1. From the main menu, click Window → Preferences.
136 EGL Programmer’s Guide
2. From the navigation tree, expand EGL → Editor and then click Templates. A list
of templates is displayed.
3. Click Import.
4. Select the location of the template file to be imported in the Importing
Templates window. You can browse the various locations to locate the template
file that you want to import.
5. Select the template file to be imported and click Open.
6. The templates are added to the existing templates.
Related concepts
“Code assistant” on page 132
“Code templates” on page 133
“Code snippets” on page 138Snippets are code objects that are reusable programming objects. Snippets can
be a piece of code or a complete programming task. In addition to the default
snippets provided in the workbench, you can create your own snippets. Related tasks
“Enabling and disabling code templates” on page 134
“Creating code templates” on page 134
“Exporting code templates” on page 136
“Removing code templates”
“Restoring default code templates” on page 138
Removing code templates
You can remove code templates from the list of available templates. You can restore
the templates if you have not exited the workbench. After you exit the workbench,
the removed templates cannot be restored.
To remove an existing code template, follow these steps:
1. From the main menu, click Window → Preferences.
2. From the navigation tree, expand EGL → Editor and then click Templates. A list
of templates is displayed.
Note: As in other applications on Windows 2000/NT/XP, you can click an
entry to select it; can use Ctrl-click to select or deselect an entry without
affecting other selections; and can use Shift-click to select a set of entries
that are contiguous to the entry you last clicked.
3. In the table, click the templates that you want to remove, and then click
Remove.
4. To save your changes, click Apply.
5. Click OK to close the window.
Related concepts
“Code assistant” on page 132
“Code templates” on page 133
“Code snippets” on page 138Snippets are code objects that are reusable programming objects. Snippets can
be a piece of code or a complete programming task. In addition to the default
snippets provided in the workbench, you can create your own snippets. Related tasks
“Enabling and disabling code templates” on page 134
“Creating code templates” on page 134
Working with EGL code 137
“Importing code templates” on page 136
“Exporting code templates” on page 136
“Restoring default code templates”
Restoring default code templates
You can reset the code template list to the original list of templates when the
workbench was installed. When restoring the list of code templates any
modifications or templates you created will be removed.
Alternately, you can restore a single code template to the default shipped with the
product. See “Editing code templates” on page 135.
To restore the default code templates, follow these steps:
1. From the main menu, click Window → Preferences.
2. From the navigation tree, expand EGL → Editor and then click Templates. A list
of templates is displayed.
3. To return to the template list that was in effect at installation time, click Restore
Defaults.
4. To save your changes, click Apply.
5. Click OK to close the window.
Related concepts
“Code assistant” on page 132
“Code templates” on page 133
“Code snippets”Snippets are code objects that are reusable programming objects. Snippets can
be a piece of code or a complete programming task. In addition to the default
snippets provided in the workbench, you can create your own snippets. Related tasks
“Enabling and disabling code templates” on page 134
“Creating code templates” on page 134
“Importing code templates” on page 136
“Exporting code templates” on page 136
“Removing code templates” on page 137
“Restoring default code templates”
Code snippets
Snippets are code objects that are reusable programming objects. Snippets can be a
piece of code or a complete programming task. In addition to the default snippets
provided in the workbench, you can create your own snippets.
The Snippets view provides access to the snippets available for use. The Snippets
view contains several pieces of EGL code, as well as code for many other
technologies. The following table lists the snippets that are available in EGL.
Table 27. Snippets available in EGL
Snippet name Description
Set cursor focus (JSP) A JavaScript™ function that sets the cursor
focus to a specified form field on a Web
page. See “Setting the focus to a form field”
on page 206.
138 EGL Programmer’s Guide
Table 27. Snippets available in EGL (continued)
Snippet name Description
Auto redirect (JSP) A JavaScript function that tests for the
presence of a session variable. If the session
variable is not present, it forwards the
browser to a different page. See “Testing
browsers for a session variable” on page 213.
Get clicked row value An EGL function that retrieves the
hyperlinked value of a clicked row in a data
table. See “Retrieving the value of a clicked
row in a data table” on page 205.
database update An EGL function that updates a single row
of a relational table when passed a record
from a JSF Handler. See “Updating a row in
a relational table” on page 210.
Related concepts
“Code assistant” on page 132
“Code templates” on page 133 Related concepts
Related tasks
“Inserting code snippets into EGL and JSP files”
“Setting the focus to a form field” on page 206The Set cursor focus snippet in the EGL drawer of the Snippets view is a
JavaScript function that sets the cursor focus to a specified form field on a Web
page. It must be placed within a <script> tag in a JSP page.
“Testing browsers for a session variable” on page 213The Auto redirect snippet in the JSP drawer of the Snippets view tests for the
presence of a session variable. If the session variable is not present, the
customized code forwards control to a different Web page.
“Retrieving the value of a clicked row in a data table” on page 205The getClickedRowValue snippet in the EGL drawer of the Snippets view is a
function that retrieves the hyperlinked value of a clicked row in a data table.
“Updating a row in a relational table” on page 210The database update snippet in the EGL drawer of the Snippets view is a
function that updates a single row of a relational table when passed a record
from a JSF Handler. This snippet is intended to be placed in an EGL library.
Inserting code snippets into EGL and JSP files
To insert an EGL code snippet into your code, follow these steps:
1. Open the file to which you want to add a snippet.
2. Open the Snippets view.
a. Click Window → Show View → Other.
b. Expand General and click Snippets.
c. Click OK.3. In the Snippets view, expand the EGL drawer. This drawer contains the
available EGL code snippets.
4. Use one of these methods to insert a snippet into the file:
Working with EGL code 139
v Double-click a snippet to insert that snippet at the current cursor position.
You may see a window describing the variables in the snippet. If so, enter
values for these variables and then click Insert.
v Click and drag a snippet into the source code. This method works only when
putting a snippet on a JSP file.
If you selected a snippet that contains variables, you will be prompted to enter
the variables.
Note: If the cursor turns into a circle with a strike through it, indicating that
the snippet can not be inserted at that point, you may be trying to insert
the snippet into the wrong place. Check the snippet’s details to find out
where it should be inserted in the code.
5. Change the predefined names of functions, variables, and data parts in the
snippet as appropriate to your code. Most snippets include comments that
explain what names need to be changed.
Related concepts
“Code snippets” on page 138Snippets are code objects that are reusable programming objects. Snippets can
be a piece of code or a complete programming task. In addition to the default
snippets provided in the workbench, you can create your own snippets. Related tasks
“Code assistant” on page 132
“Setting the focus to a form field” on page 206The Set cursor focus snippet in the EGL drawer of the Snippets view is a
JavaScript function that sets the cursor focus to a specified form field on a Web
page. It must be placed within a <script> tag in a JSP page.
“Testing browsers for a session variable” on page 213The Auto redirect snippet in the JSP drawer of the Snippets view tests for the
presence of a session variable. If the session variable is not present, the
customized code forwards control to a different Web page.
“Retrieving the value of a clicked row in a data table” on page 205The getClickedRowValue snippet in the EGL drawer of the Snippets view is a
function that retrieves the hyperlinked value of a clicked row in a data table.
“Updating a row in a relational table” on page 210The database update snippet in the EGL drawer of the Snippets view is a
function that updates a single row of a relational table when passed a record
from a JSF Handler. This snippet is intended to be placed in an EGL library.
Using cheat sheets
Cheat sheets can assist you with common tasks in the Workbench. They provide
step-by-step instructions within a workbench view and can perform some of the
steps in the task automatically.
Follow these instructions to open and use a cheat sheet:
1. Click Help → Cheat Sheets. The Cheat Sheet Selection window opens.
2. Expand EGL and select an EGL cheat sheet.
3. Click OK. The cheat sheet opens in a workbench view.
4. Click Click to Begin to start through the cheat sheet.
5. Follow the steps in the cheat sheet.
140 EGL Programmer’s Guide
As the steps in the cheat sheet expand, they provide the information necessary
to perform each step. Depending on the step, you might need to perform the
step manually or there might be other options available as follows:
v In some cases, the cheat sheet can perform the step or a portion of the step
for you. If this option is available, you can click the Click to Perform link.
For example, the cheat sheet might be able to open a wizard for you, but you
must fill out the wizard to complete the step.
v In some cases, the cheat sheet provides an option to skip a step. If this
option is available and you have already met the criteria, you can click on
the Click to Skip link. For example, if you already have an EGL Web project,
then you can skip the step of creating an EGL Web project.6. As you complete each step, click the Click to Complete link. The next step in
the cheat sheet expands automatically.
EGL offers the following cheat sheets:
Create an EGL Hello World Web application
Creates a simple Web application with EGL.
Create an EGL data access Web application from a database connection
If you already have a connection to a database, you can use this cheat
sheet to connect to the database and create a simple Web application based
on the database schema. This cheat sheet is similar to the method
described in “Creating a data access application” on page 173.
Create an EGL data access Web application from a UML model
If you have a UML model that describes a database, you can use this cheat
sheet to create a transformation parameters file and run the EGL data
access transformation to create an application based on the UML model.
Create a Web service
Creates a simple Web service using EGL.
Create a Web service client
If you have a WSDL file that describes a Web service, you can use this
cheat sheet to create an EGL application that acts as a client for that
service. Related concepts
“Working with EGL code” on page 103
Editing DataItem parts with the source assistant
Like most parts, DataItem parts can have one or more properties assigned to them.
The source assistant helps you assign the correct properties and values for the
DataItem by displaying only the valid properties for DataItem parts and by
validating the values that you enter for the properties.
To modify DataItem properties, follow these steps:
1. Open an EGL source file.
2. Select the DataItem that you want to edit. The cursor must be on the DataItem.
3. Open the source assistant by using one of these methods:
v Press Ctrl + Shift + Z.
v Right-click the DataItem and then click Source Assistant.4. In the EGL Source Assistant window, type the name of the DataItem in the
Name field and select the type from the Type field.
Working with EGL code 141
5. If the type of DataItem requires a length or a number of decimal places, specify
these values in the Length and Decimals fields. These fields are not available if
the DataItem does not require a length or number of decimal place values.
6. Specify values for the properties of the DataItem. You can switch between
different pages of properties by clicking the tabs below the Type field.
7. When you are finished editing the values, click Validate.
The source assistant validates the values you enter and lists any errors at the
bottom of the window. Correct any errors that are listed in the window and
click Validate again.
8. When there are no more validation errors listed, click OK. The source assistant
closes and updates the DataItem properties to match the properties that you
specified.
9. Save the EGL source file. Related concepts
“Introduction to data parts” on page 82Data parts define a structure that stores one or more pieces of data. Data parts
form the basis for a variable that you can use in a logic part.
Searching for EGL files and parts
The workbench provides several options for searching for and viewing EGL files
and parts.
File Search view
With the File Search view, you can perform a textual search of the entire
workspace or a subset of your files and projects. You type a string and
specify the search scope, and the workbench searches the files for a textual
match. This method of searching is not customized for EGL use; you can
use it for all types of files.
EGL Search view
With the Search view, you can search for EGL parts or references to those
parts. Click Search → EGL from the menu bar and type in a search string.
See “Searching for parts” on page 143.
Parts List view
The Parts List view displays a table of EGL parts with details about their
location and type. To use the Parts List view, select one or more EGL files
in the Project Explorer view, right-click the files, and then click Open in
Parts List. See “Viewing lists of parts” on page 144.
Parts Reference view
The Parts Reference view displays all the parts that are referenced by a
single generatable logic part, such as a program. To open the Parts
Reference view, right-click a file containing a generatable logic part in the
Project Explorer view and then click Open in Parts Reference. See
“Viewing part references” on page 145.
Project Explorer view
If you have a file open in the EGL editor and you want to locate that file
in the Project Explorer view, right-click the open file in the editor and then
click Show In → Project Explorer. See “Locating an EGL source file in the
Project Explorer view” on page 146. Related tasks
“Searching for parts” on page 143You can search for parts among the EGL projects in your workspace.
142 EGL Programmer’s Guide
“Viewing lists of parts” on page 144You can choose one or more EGL parts and group those parts in a list to filter
or sort them.
“Viewing part references” on page 145The EGL Parts Reference view shows a hierarchical view of the parts that are
referenced in a generatable logic part, such as functions, parameters, and the
types used to create variables.
“Locating an EGL source file in the Project Explorer view” on page 146
Searching for parts
You can search for parts among the EGL projects in your workspace.
This search returns part definitions and references; it does not search your project
for a text match to a string. For a textual search of your project, click Search → File.
To search for a list of available parts, follow these steps:
1. From the main menu, click Search → EGL. The Search window opens to the
EGL Search tab.
If you do not see Search → EGL, click Search → Search and switch to the EGL
Search tab.
2. Type the criteria for the search in the Search string field. You can use the
following wildcard symbols in your search:
v A question mark (?) represents any one character
v An asterisk (*) represents a series of any characters of any length
For example, type my?Part to locate parts named ″my1Part″ and ″my2Part″, but
not ″my10Part″. Type my*Part to locate parts named ″my1Part″, ″my2Part″, and
″my10Part″. Click the Case sensitive check box for a case-sensitive search.
3. In the Search For section, select the type of part you are searching for, or select
Any element to expand your search to all part types.
4. In the Limit To section, select the option to limit your search to part
declarations, part references, or any occurrence of the search string.
5. In the Scope section, select where to search:
Workspace
Searches the current workspace.
Selected resources
Searches the resources currently selected in the Project Explorer view or
other view.
Enclosing projects
Searches the project or projects that contain the files selected in the
Project Explorer view or other view.
Working set
Searches a set of projects, called a working set. Click Choose to select the
working sets to search.6. Click Search. The results are displayed in the Search view.
7. If you double-click a file in the Search view, the file opens in the EGL editor,
and the matching part is highlighted. If there is more than one match in the
file, the first match is highlighted.
Arrows in the left margin of the editor indicate the locations of each matching
part. Related concepts
Working with EGL code 143
“Contents of an EGL application” on page 59This topic describes the artifacts found in a typical EGL application.
“Introduction to EGL parts” on page 81Parts are the building blocks of EGL applications.
Related tasks
“Viewing lists of parts”You can choose one or more EGL parts and group those parts in a list to filter
or sort them.
“Viewing part references” on page 145The EGL Parts Reference view shows a hierarchical view of the parts that are
referenced in a generatable logic part, such as functions, parameters, and the
types used to create variables.
“Locating an EGL source file in the Project Explorer view” on page 146
Viewing lists of parts
You can choose one or more EGL parts and group those parts in a list to filter or
sort them.
To populate the EGL Parts List view with parts, do one of the following:
v In the Project Explorer view, select one or more EGL resources, such as files,
projects, or packages. Then, right-click the selected resources and click Open in
Parts List.
v In the EGL Parts Reference view, select one or more EGL parts. Then, right-click
the selected parts and click Open in Parts List. This method can be useful for
viewing all the parts that are referenced by another part.
After the EGL Parts List view is open and populated with parts, you can do the
following tasks with the list of parts:
v Double-click a part to open it in the EGL editor.
v Click a column header to sort the list by the part name, type, project, package,
or filename.
v Click the Refresh button at the top right of the view to refresh the information
in the view.
v Open the History list at the top right of the view to return to a list of parts you
have viewed in the EGL Parts List view previously.
v Filter the list of parts with the Filters list at the top right of the view.
v Go to the part in the Project Explorer view by right-clicking it and then clicking
Show in Project Explorer.
v Generate a generatable part by right-clicking it and then clicking Generate or
Generate With Wizard.
v Debug a program by right-clicking it and then clicking Debug EGL Program.
v Open a part in the EGL Parts Reference view by right-clicking a program,
library, handler, or service and then clicking Open in Parts Reference. See
“Viewing part references” on page 145.
v Search for related EGL code by right-clicking on the part, clicking References or
Declarations, and then choosing a scope for the search.
Filtering lists of parts
While viewing a list of parts in the EGL Parts List view, you can filter the list to
include only certain parts:
144 EGL Programmer’s Guide
1. Populate the EGL Parts List view with EGL parts.
2. From the list at the top right corner of the EGL Parts List view, click Filters.
The EGL Parts List Filter window opens.
3. In the EGL Parts List Filter window, set the criteria for the filter:
v To filter by project, folder, package, or file, select or deselect the resources
under Part Resources.
v To filter by type of part, select or deselect the types of parts under Part Type.
v To filter by part name, enter a part name in the Part name filter field. A
question mark (?) represents any one character and an asterisk (*) represents
a series of any characters.4. When you are finished setting the filter in the EGL Parts List Filter window,
click OK. Only the parts that match the filter criteria are shown in the EGL
Parts List view. Related concepts
“Introduction to EGL parts” on page 81Parts are the building blocks of EGL applications.
Related tasks
“Searching for parts” on page 143You can search for parts among the EGL projects in your workspace.
“Locating an EGL source file in the Project Explorer view” on page 146
“Viewing part references”The EGL Parts Reference view shows a hierarchical view of the parts that are
referenced in a generatable logic part, such as functions, parameters, and the
types used to create variables.
Viewing part references
The EGL Parts Reference view shows a hierarchical view of the parts that are
referenced in a generatable logic part, such as functions, parameters, and the types
used to create variables.
To open a generatable logic part in the EGL Parts Reference view, right-click the
file that contains the part in the Project Explorer view and then click Open in Parts
Reference. After the part opens in the view, you can expand its hierarchy to see
the parts that are referenced. Alternatively, you can right-click the part in the
Outline view or the EGL Parts List view and then click Open in Parts Reference.
In the EGL Parts Reference view, you can perform several tasks on a part or its
referenced parts:
v Open a part in the EGL editor by double-clicking the part.
v Search for related EGL code by right-clicking on the part, clicking References or
Declarations, and then choosing a scope for the search.
You can also search for parts or text strings among the parts in the view:
1. Right-click the EGL Parts Reference view and then click Find in tree.
The EGL Parts Reference Find window opens.
2. Type a search string into the Search string field.
v A question mark (?) represents any one character
v An asterisk (*) represents a series of any characters
Working with EGL code 145
For example, type my?Part to locate parts named ″my1Part″ and ″my2Part″, but
not ″my10Part″. Type my*Part to locate parts named ″my1Part″, ″my2Part″, and
″my10Part″.
3. Choose a search type. Part search searches for EGL parts and Text search
searches for text within the part.
4. Select the options for the search.
v If you selected Part search, you can select a type of part to search for by
clicking a radio button under Search For.
v Under Direction, choose to search Forward or Backward from the currently
selected part.
v To make a text search case-sensitive, select the Case sensitive check box.
v To continue searching from the other end if the search reaches the bottom or
the top of the tree, select the Wrap search check box.
v To search for only a complete part name or text string, select the Whole
word check box.5. When you are finished setting the criteria for the search, click Find. The first
result of the search is highlighted in the EGL Parts Reference view.
6. To move to the next result, click Find.
7. When you are finished, click Close. Related concepts
“Introduction to EGL parts” on page 81Parts are the building blocks of EGL applications.
Related tasks
“Searching for parts” on page 143You can search for parts among the EGL projects in your workspace.
“Viewing lists of parts” on page 144You can choose one or more EGL parts and group those parts in a list to filter
or sort them. Related reference
“The EGL editor” on page 130The EGL code editor looks and works like a standard text editor or code editor
for other languages, but it has additional features to help you edit EGL code.
The code editor highlights invalid syntax, provides an explanation for problems
in the code, colors keywords, strings, and comments, and helps you write EGL
code.
Locating an EGL source file in the Project Explorer view
If you are editing an EGL source file, you can quickly locate the file in the Project
Explorer view, Outline view, or Navigator view.
To locate an EGL source file in one of these views, right-click the open file in the
EGL editor and then click Show in → ProjectExplorer. You can also click Show in →
Outline or Show in → Navigator to display where the file is in one of those views.
This menu option does the following tasks:
v Opens the specified view, if it is not already open
v Expands the tree nodes needed to locate the source file
v Highlights the source file Related tasks
“Creating EGL source files” on page 77
146 EGL Programmer’s Guide
Related reference
“The EGL editor” on page 130The EGL code editor looks and works like a standard text editor or code editor
for other languages, but it has additional features to help you edit EGL code.
The code editor highlights invalid syntax, provides an explanation for problems
in the code, colors keywords, strings, and comments, and helps you write EGL
code.
Preferences
EGL preferences affect the way the workbench displays and works with EGL.
Related tasks
“Enabling EGL capabilities” on page 11Capabilities keep the workbench menus from becoming cluttered by hiding
items you do not use. You can always perform these tasks, but to make them
appear in the menus, you must enable the capability for that area of
functionality.
“Enabling and disabling code templates” on page 134
“Setting general preferences”
“Setting preferences for the EGL debugger” on page 328This topic tells you how to change your preferences for the EGL debugger.
“Setting preferences for the EGL editor” on page 148
“Setting EGL-to-EGL migration preferences” on page 34
“Setting generation preferences” on page 152
“Setting preferences for source styles” on page 151
“Setting preferences for Web projects” on page 246These preferences control defaults for EGL Web projects and JSF Handler parts.
“Setting preferences for SQL retrieve” on page 181
“Creating an SQL database connection” on page 162The New Connection wizard creates an SQL database connection that you can
use either at design time or at run time.
“Setting preferences for EGL text” on page 152
Setting general preferences
Set the basic EGL preferences as follows:
1. From the main menu, click Window → Preferences.
2. In the Preferences window, click EGL in the tree.
3. In the EGL Base section, select whether VisualAge Generator compatibility is
needed in your environment. Ensure that the VisualAge Generator
compatibility check box is selected if your environment requires compatibility.
4. In the Encoding field, select the character-encoding set that will be used when
you create new EGL build (.eglbld) files. The setting has no effect on existing
build files. The default value is UTF-8.
5. Select features to be enabled by default for a new EGL project in the Default
EGL Project Features Choices.
6. Select facets to be enabled by default for a new EGL Web project in the Default
EGL Web Project Facet Choices section.
7. Click Apply to save the changes and remain in the Preferences window. Click
OK to save the changes and exit the window. Related concepts
Working with EGL code 147
“Features and facets of EGL projects” on page 66EGL projects can have additional abilities, added through features and facets.
“Preferences” on page 147EGL preferences affect the way the workbench displays and works with EGL.
Related tasks
“Enabling EGL capabilities” on page 11Capabilities keep the workbench menus from becoming cluttered by hiding
items you do not use. You can always perform these tasks, but to make them
appear in the menus, you must enable the capability for that area of
functionality.
“Setting preferences for the EGL debugger” on page 328This topic tells you how to change your preferences for the EGL debugger.
“Setting preferences for the EGL editor”
“Setting preferences for source styles” on page 151
“Setting preferences for EGL text” on page 152
Setting preferences for the EGL editor
To specify the EGL editor preferences, follow these steps:
1. From the main menu, click Window → Preferences.
2. From the navigation tree, expand EGL and click Editor.
3. In the Preferences window, you can set the following EGL editor settings:
Show line numbers
Displays the line numbers in the EGL file.
Annotate errors in text
Underlines errors in the source code with a red line. Errors are shown
after saving the file.
Annotate errors in overview ruler
Shows a red error indicator in the right margin of the editor (overview
ruler) whenever an error is found in the source code. Errors are shown
after saving the file.
When the check box next to the setting is clear, the setting is turned off. Click
the check box to turn the setting on.
4. Click Apply to save the changes and remain in the Preferences window. Click
OK to save the changes and exit the window.
There are other pages with additional options for the EGL editor under the EGL
page in the navigation tree. To set these options, see the following topics:
v “Setting preferences for folding in the EGL editor” on page 149
v “Setting preferences for organizing import statements in the EGL editor” on
page 150
v “Setting preferences for source styles” on page 151
v “Enabling and disabling code templates” on page 134 Related concepts
“Preferences” on page 147EGL preferences affect the way the workbench displays and works with EGL.
Related tasks
“Enabling EGL capabilities” on page 11Capabilities keep the workbench menus from becoming cluttered by hiding
148 EGL Programmer’s Guide
items you do not use. You can always perform these tasks, but to make them
appear in the menus, you must enable the capability for that area of
functionality.
“Setting general preferences” on page 147
“Setting preferences for the EGL debugger” on page 328This topic tells you how to change your preferences for the EGL debugger.
“Setting preferences for folding in the EGL editor”Folding enables you to collapse blocks of code in the EGL editor to hide them.
“Setting preferences for organizing import statements in the EGL editor” on
page 150EGL can automatically organize the import statements in your code.
“Setting preferences for the EGL editor” on page 148
“Setting preferences for source styles” on page 151
“Setting preferences for EGL text” on page 152 Related reference
“Code assistant” on page 132
“Code templates” on page 133
Setting preferences for folding in the EGL editor
Folding enables you to collapse blocks of code in the EGL editor to hide them.
Folding has no effect on EGL source code or generated source; it is only a tool to
view the active parts of your source code while hiding parts that you are not
currently working with.
To set folding preferences:
1. From the main menu, click Window → Preferences.
2. In the Preferences window, expand EGL → Editor and click Folding.
3. On the Folding page of the Preferences window, select the Enable folding
check box to enable the EGL editor to collapse sections of your code.
4. Under Initially fold these elements, select the check boxes next to the sections
of EGL code that you want the editor to fold automatically when you open a
file.
5. In the Number of property block lines needed to enable folding field, enter
the minimum number of lines in a block of properties that you want to be able
to fold. If you select the Properties Block check box, EGL will automatically
fold blocks of properties of the given size or larger.
6. Click Apply to save the changes and remain in the Preferences window. Click
OK to save the changes and exit the window. Related concepts
“Preferences” on page 147EGL preferences affect the way the workbench displays and works with EGL.
Related tasks
“Enabling EGL capabilities” on page 11Capabilities keep the workbench menus from becoming cluttered by hiding
items you do not use. You can always perform these tasks, but to make them
appear in the menus, you must enable the capability for that area of
functionality.
“Setting preferences for the EGL editor” on page 148
Working with EGL code 149
“Setting preferences for organizing import statements in the EGL editor”EGL can automatically organize the import statements in your code.
Setting preferences for organizing import statements in the
EGL editor
EGL can automatically organize the import statements in your code.
Organizing import statements involves reordering and grouping the statements by
the package name. Also, EGL removes unnecessary import statements from your
code.
Follow these steps to set preferences for organizing the import statements in your
code:
1. From the main menu, click Window → Preferences.
2. In the Preferences window, expand EGL → Editor and click Organize Imports.
3. On the Organize Imports page of the Preferences window, set the order for
import statements in the list of package names:
v To add a new package or prefix to the list, click New and type the new
name. You can use the asterisk character as a wild card at the end of the
package name.
v To reorder the packages and prefixes, click a package or prefix in the list to
select it and then click Up or Down.4. In the Number of imports needed field, enter the minimum number of
individual import statements in the same package to simplify into an import
statement with a wild card character.
For example, your file might have the following similar import statements:
import com.mypackage.myPart1;
import com.mypackage.myPart2;
import com.mypackage.myPart3;
If you set the Number of imports needed field to 3, the editor will simplify
these import statements into the following single import statement:
import com.mypackage.*;
5. Click Apply to save the changes and remain in the Preferences window. Click
OK to save the changes and exit the window.
To organize your import statements, open a source file in the editor, right-click the
file, and then click Organize Imports. Alternatively, you can organize the import
statements for every file in a project or package by right-clicking the project or
package in the Project Explorer view and then clicking Organize Imports.
Related concepts
“Preferences” on page 147EGL preferences affect the way the workbench displays and works with EGL.
Related tasks
“Enabling EGL capabilities” on page 11Capabilities keep the workbench menus from becoming cluttered by hiding
items you do not use. You can always perform these tasks, but to make them
appear in the menus, you must enable the capability for that area of
functionality.
“Setting preferences for the EGL editor” on page 148
150 EGL Programmer’s Guide
“Setting preferences for folding in the EGL editor” on page 149Folding enables you to collapse blocks of code in the EGL editor to hide them.
Setting preferences for source styles
You can change how EGL code is displayed in the EGL editor:
1. From the main menu, click Window → Preferences.
2. From the navigation tree, expand EGL → Editor and click Source Styles.
3. The Source Styles page of the Preferences window shows the following EGL
style preferences:
Background color
Select one of the following options to define the background color in
the EGL source file:
System Default
Use the colors currently defined as part of the system
configuration.
Custom
Click the radio button to select a color from the color palette.
The color palette is displayed when clicking the button next to
the Custom label. After you have selected a color, click OK to
save your choice. The color is shown in the Preview field.
Element
Select the color for each element of source data in your file. You can
also make the data bold. To set a color, follow these steps:
a. Select the type of text in the Element list.
b. Click the box next to the Color label. A color palette is displayed.
c. Select the desired color and click OK.
d. Click the check box for the Bold field to bold the text.
Repeat the steps for each type of text. The results are shown in the
Preview box.4. Click Apply to save the changes and remain in the Preference window. Click
OK to save the changes and exit the window. Related concepts
“Preferences” on page 147EGL preferences affect the way the workbench displays and works with EGL.
Related tasks
“Enabling EGL capabilities” on page 11Capabilities keep the workbench menus from becoming cluttered by hiding
items you do not use. You can always perform these tasks, but to make them
appear in the menus, you must enable the capability for that area of
functionality.
“Setting general preferences” on page 147
“Setting preferences for the EGL debugger” on page 328This topic tells you how to change your preferences for the EGL debugger.
“Setting preferences for the EGL editor” on page 148
“Setting preferences for EGL text” on page 152
Working with EGL code 151
Setting generation preferences
To specify preferences for EGL generation, follow these steps:
1. From the main menu, click Window → Preferences.
2. From the navigation tree, expand EGL and click Generation.
3. In the Generation window, you can set the following preferences:
Build before generate
If you select this check box, EGL builds the project automatically prior
to generation if it has not been built since the last change. This
preference takes effect only when the workbench is not set to build the
project automatically.
Auto generate
If you select the check box next to a type of part, EGL will generate
that part automatically each time you save a file that contains that type
of part. Clearing these check boxes improves workbench performance
because you will not have to wait for EGL to generate the parts each
time you save. However, if you clear the check boxes, you must
remember to generate the appropriate files manually before running
your application.
Generation Destination User Information
If you are generating code to a computer other than this one, type the
user ID and password for the computer on which the generated code is
saved. These fields behave like default values for the destUserID and
destPassword build descriptor options. The values of these build
descriptor options take precedence over the settings in the Preferences
window.4. Click Apply to save the changes and remain in the Preference window. Click
OK to save the changes and exit the window. Related concepts
“Preferences” on page 147EGL preferences affect the way the workbench displays and works with EGL.
Setting preferences for EGL text
To change how text is displayed in the EGL editor, follow these steps:
1. From the main menu, click Window → Preferences.
2. In the navigation tree, expand General → Appearance and then click Colors
and Fonts.
3. In the Colors and Fonts window, expand EGL in the tree and then click EGL
Editor Text Font.
4. Click Change.
5. In the Font window you can specify one or more of the following settings:
v Type or select a font style in the Font field.
v Type or select a font style in the Font style field.
v Type or select a font size in the Size field.
v Type or select a color in the Color field.
v Select the Strikeout check box if you want a line to run through the middle
of the text.
v Select the Underline check box if you want a line under the text.
152 EGL Programmer’s Guide
You can see a preview of your selections in the Sample section. When you are
finished making your selections, click OK.
6. To use the default operating system font, click the Use System Font button.
7. To use the default workbench font, click the Reset button.
8. To set the font for all editors (not just the EGL editor) to the default workbench
font, click the Restore Defaults button.
9. Click Apply to save the changes and remain in the Preference window. Click
OK to save the changes and exit the window. Related tasks
“Setting preferences for the EGL editor” on page 148
“Setting preferences for source styles” on page 151
Working with EGL code 153
154 EGL Programmer’s Guide
Accessing data with EGL code
If your program is going to store any of the information that it works with, it
needs to use a file. If you plan to work with large amounts of information,
typically you use a database or other type of data source for storage and retrieval.
Commercial software (such as IBM DB2) helps you manage the information that
you store in the database
The most common type of database is the relational database. In very simple terms,
the information in a relational database resides in tables that can refer to each
other. A relational database management system (RDBMS) keeps track of the tables
and relationships. You use a special language, called SQL, to communicate with the
database manager. Some popular types of RDBMS include IBM DB2, Microsoft®
SQL Server, Oracle, and the open-source MySQL.
In the mainframe world, it is still common to see hierarchical databases. A
hierarchical database contains a tree-like structure, where segments (equivalent to
tables) can have a parent segment (only one each) and multiple child segments.
IMS is an example of a hierarchical database manager, which you can talk to
through the DL/I language.
Another option is to use a lower level data structure that is provided by your
operating system. Using this type of data source enables you to manage more of
the details of data storage and retrieval yourself. IBM MVS™ systems use a file
access method called VSAM (Virtual Storage Access Method) that enables you to
write directly to several different types of file, including plain sequential access
files and indexed files (which keep track of data by means of a key).
The EGL strategy is to provide a few basic commands (like get, which fetches
information and puts it into a record) that focus on business logic rather than
implementation details. For an overview of how this works, see “Reading and
writing records” on page 156.
Related tasks
“Reading and writing records” on page 156
“Creating a data access application” on page 173EGL can create a simple data access application based on a database to which
you are connected. The resulting application contains data parts, logic parts and
(optionally) Web pages that are based on one or more database tables.
“Viewing implicit SQL statements” on page 179
Common data access tasks
EGL helps you perform common data processing tasks such as reading and writing
to files, while protecting you from the implementation details.
The goal of information processing is to transform data (raw facts and figures) into
information (data that means something and increases knowledge). Common
processes include:
© Copyright IBM Corp. 1996, 2007 155
Retrieval
EGL uses the get statement (and its variants) to read data from files,
databases, and message queues. For more details, see “Reading and
writing records.”
Processing
What you do with the data you receive—whether retrieved from storage or
input through a user interface (UI)—depends on your business processes.
For example, you might be receiving orders from a Web site, generating
picking tickets for your warehouse, and making adjustments to inventory
and customer balances.
Storage
EGL uses the add and replace statements to modify existing data in
storage. For more details, see “Reading and writing records.”
Reporting and analysis
EGL can present reports that include everything from checks and invoices
to general ledgers and Web statistics. EGL uses the JasperReports
open-source reporting package to provide this functionality. For more
details, see “Creating reports with EGL” on page 283. Related concepts
“Creating reports with EGL” on page 283EGL offers different ways to create reports, using external engines to generate
the report contents. Related tasks
“Reading and writing records”
Reading and writing records
The acronym CRUD refers to the basic I/O functions that you typically perform on
records within a file. The following table shows the CRUD functions and the EGL
keywords that provide those functions:
Table 28. CRUD functions in EGL
CRUD function EGL keyword
Create add
Read get
Update replace
Delete delete
Furthermore, EGL tailors the way it executes each of these functions based on the
particular type of file with which you are working. For example, if you write a get
next statement for a SQL database, EGL generates a series of SQL statements to
locate and retrieve the appropriate row from an SQL result set. The same EGL
statement generated for a sequential file would simply read the next record in the
file.
EGL accomplishes these tasks by means of stereotyping. In everyday use, a
stereotype is a common pattern that you can use to characterize an individual. In
much the same way, when you apply a stereotype to a record, you tell EGL how it
should perform I/O functions that involve that record. For more on stereotypes,
see “Introduction to Record parts” on page 85 and topics that focus on the specific
stereotypes in the EGL Language Reference.
156 EGL Programmer’s Guide
The I/O processing cycle
Assuming that you have an existing database (typically created by a database
administrator), regular processing generally involves the create, read, update, and
delete (CRUD) functions. More specific examples are presented in the topics that
deal with specific data access technologies. The following general scenario is
possible only because EGL is so efficient at shielding you from implementation
details.
Start by defining a Record, which you must do outside of a generatable part:
package com.companyb.customer
Record CustomerRecord type Stereotype
customerNumber INT;
customerName STRING;
customerBalance MONEY;
end
The details of the record, and its properties, will vary depending on how you plan
to use it.
Next, within the body of your program, declare a variable based on this Record
part:
myCustomer CustomerRecord;
To find an existing customer record, you will need a unique piece of information
about the record. Typically this means some kind of ID number, often used as a key
to the file. A key is a piece of data used to index a file, so you don’t have to look
at every record to find the one that you want. Assume that you have separately
written a function called getCustomer() that asks the user for a customer number
and returns that number:
myCustomer.customerNumber = getCustomer();
To read the information that matches the requested number, simply code the
following:
get myCustomer forUpdate;
EGL generates the appropriate code to read the data from the file or database and
then places the information in your record variable. The forUpdate keyword tells
EGL to place a hold on the data so you have the option to replace or delete it.
You can then offer the information to your user with the option to change it.
Assume that you have separately written a function called showCustomer() that
returns a –1 if the user wants to delete the record, 0 if the record is unchanged,
and 1 if the user made any changes to the record:
case (showCustomer(myCustomer))
when (-1)
delete myCustomer;
when (1)
replace myCustomer;
end
If you handle errors (see “Handling errors” on page 123), you can do a bit more
with the number that getCustomer() returns. Assume that you have separately
written a function called getReply() that returns TRUE or FALSE depending on
whether the user answers Y or N to the specified question:
Accessing data with EGL code 157
set myCustomer empty; // all fields blank or 0
myCustomer.customerNumber = getCustomer(); // sets cust #
try
get myCustomer forUpdate;
onException (ex AnyException) // couldn’t get the record
if(myCustomer is noRecordFound) // because customer # not on file
if(getReply("Do you wish to add this customer? (y/n)") == TRUE)
showCustomer(myCustomer); // let user fill in remaining fields
add myCustomer;
end
else
myErrorHandler(ex);
end
With these few lines of code you have the heart of a customer file service program
that you can use with an SQL database or your own VSAM indexed file. The only
difference in your program between VSAM and SQL is the stereotype you apply to
the CustomerRecord definition.
Related concepts
“Introduction to Record parts” on page 85Record parts are collections of other data parts. The data parts within the
Record part are referred to as fields. A Record part can contain any number of
fields, and the fields can include primitives, dataItems, and other records. Related tasks
“Handling errors” on page 123With EGL, you can decide how your program behaves in case of errors.
Writing and reading a sequential file
Sequential files or data sets store records in a specific sequence. Writing and
reading records in a sequential file is similar to writing and reading records in any
other type of data source, except that the process of connecting to the file is
different.
Prerequisites
v An EGL project
Setting up a resource association
To connect to a sequential file, you must first define a resource associations part
that points to that file. The file itself can be a data set as well as a file on your
system, but this example uses a local file.
1. Open the project’s build descriptor.
2. Add a resource associations part to the build descriptor and open that part in
the build parts editor. See ″Adding a resource associations part to an EGL build
file.″
3. In the new resource associations part, add a new association to the location
where the sequential file will go:
a. In the resource associations part, click the Add Association button. A new
entry is displayed under Association elements.
b. In the File Name field of the new entry, type a mnemonic for the sequential
file that conforms to EGL naming requirements, such as myFile. This field is
not the name of the actual file on disk; this field corresponds to the value of
the fileName property of serial record parts that use this file.
158 EGL Programmer’s Guide
c. Set the System field to the type of system you are using, such as win for
Windows or linux for Linux.
d. Set the File type field to seqws to represent a sequential record.
e. Set the systemName field to the fully qualified location of the file. For
example, in a Windows operating system, systemName should be set to
something like this:
C:\myFolder\myFile.dat
If you point to a file that does not exist, EGL will create the file when you
write to it.
The resource associations part looks like this, with your own values in the
fields:
f. Save and close the resource associations part.4. Set the value of the resourceAssociations build descriptor option to the name
of the resource associations part.
5. Define a serialRecord part to represent the records that will be stored in the
sequential file. For example:
record mySerialRecord type serialRecord
10 myInteger int;
10 myChar char(50);
end
6. Finally, set the fileName serial record property to the value of the File Name
field in the resource association part entry:
record mySerialRecord type serialRecord
{fileName = "myFile"}
10 myInteger int;
10 myChar char(50);
end
Now you can use the record part in your code to access the sequential file.
For more information on resource associations parts, see the EGL Generation Guide.
Writing to the file
Writing to a sequential file is similar to writing to any other data source.
1. Open an EGL program or other logic part.
2. Make sure that your serial record part is in scope and is associated with the
sequential file as in ″Setting up a resource association″ above. You might need
to use an import statement to bring it into scope:
import myProject.myData.mySerialRecord;
3. In an EGL program, declare a variable that is based on your serial record:
variableRecord mySerialRecord;
4. Add data to the fields in the new variable:
variableRecord.myInteger = 45;
variableRecord.myChar = "Hello!";
Accessing data with EGL code 159
5. Use an appropriate EGL data access statement, such as add to write the record
to the file:
add variableRecord;
6. Save, generate, and run the program. The new record is written to the end of
the sequential file.
Reading from the file
Reading data from a sequential file is similar to reading from any other data
source, except that you must pay attention to the order of the records in a
sequential file.
In general, use the get next statement instead of the get statement when you deal
with serial records. In this context, get next begins with the first record in the
sequential file and reads the records in order.
1. Open an EGL program or other logic part.
2. Make sure that your serial record part is in scope and is associated with the
sequential file as described in ″Setting up a resource association″ above. You
might need to use an import statement to bring it into scope:
import myProject.myData.mySerialRecord;
3. In an EGL logic part, declare a variable that is based on your serial record:
variableRecord mySerialRecord;
4. Retrieve a record from the sequential file using the variable:
get next variableRecord;
5. Use the data from the sequential file:
sysLib.writeStderr(variableRecord.myChar);
6. Save, generate, and run the program. The program reads the sequential file and
displays the data from the record in the console:
Hello!
Specifying database options at project creation
This topic tells you how to specify SQL database options at project creation.
1. Create a database connection as explained in ″The New Connection Wizard″
in “Creating an SQL database connection” on page 162.
2. Open the New EGL Project window:
a. Click File → New → Other.
b. Expand EGL and click EGL Project.
c. Click Next. 3. Give the project a name.
4. Under Target Runtime Platform, click Java or COBOL.
5. Under Build Descriptor Options, click Create new project build descriptor(s)
automatically.
6. Click Options.
7. In the Project Build Options window, clear the Use Default SQL Connection
check box.
8. Select the connection you created earlier from the Connection list.
9. Click OK to close the Project Build Options window.
10. Click Finish
Related tasks
160 EGL Programmer’s Guide
“Creating an EGL project” on page 62This topic covers how to create an EGL project.
Working with SQL data
SQL (pronounced as three separate letters) refers to a language that is designed to
communicate with the software that controls a relational database.
A relational database maintains information in interconnected tables. SQL
databases are the workhorses of the computer world.
EGL provides two options in dealing with SQL data. If you are doing fairly
common and straightforward tasks, you can simply use EGL statements to perform
all your I/O operations (see “Reading and writing records” on page 156). In this
case EGL creates all the actual SQL statements for you. In the second option, you
can use a #sql directive to include your own SQL statements in your EGL code.
With EGL, you can even combine the two styles. You can access the SQL
statements that EGL generates from your EGL code and modify them (see
“Viewing implicit SQL statements” on page 179).
Topics in this section will show you how to connect EGL to your SQL database
(see “Creating an SQL database connection” on page 162), as well as shortcuts for
creating SQL records (see “Retrieving SQL table data” on page 170) and complete
SQL applications (see “Creating a data access application” on page 173).
Best practices
The following table shows where to use each of the EGL SQL techniques:
Table 29. Best practices for EGL SQL
SQL objective EGL approach
Simple SQL data manipulation (SELECT,
UPDATE, INSERT, DELETE). Primary key
controls WHERE and ORDER BY.
Use EGL keywords (get, replace, add,
delete) and let EGL generate implicit SQL.
Simple SQL data manipulation with reusable
custom WHERE clause.
Place the custom WHERE clause in the
defaultSelectCondition property.
SQL SELECT statements with custom
WHERE clause.
Use explicit SQL through the #sql directive.
SQL table JOIN statement. Use the Retrieve SQL feature in the
workbench, then create use the
defaultSelectCondition property to correctly
join the tables on primary and foreign keys,
as in the following example:
defaultSelectCondition = #sqlCondition{
customer.customer_ID =
orders.customer_ID }
Derived data in SELECT command (such as
MAX() or AVG())
Use explicit SQL through the #sql directive,
placing the derived fields inside the braces.
Create a custom SQLRecord, where the
column property for the individual fields
specifies the derived or computed
expression.
Accessing data with EGL code 161
Table 29. Best practices for EGL SQL (continued)
SQL objective EGL approach
Complex or custom SQL UPDATE, INSERT,
or DELETE statement.
Use EGL replace, add, or delete statements
with explicit SQL (#sql directive).
Use explicit SQL through the execute #sql
statement.
SQL statements other than simple data
manipulation (such as CREATE TABLE).
Use explicit SQL through the execute #sql
statement.
Dynamic SQL (prepared SQL statement). Use explicit SQL through the execute #sql
statement.
Stored procedure. Use explicit SQL such as the following:
open result_set with #sql{
CALL stored_proc ( :host_var) }
Processing of individual rows of the result
set from a SQL SELECT statement.
Use the EGL open command to open the
result set, then initiate a loop with one of
the following statements:
v forEach (from result_set)
v while (sqlLib.sqlData.sqlcode == 0)
Programmatic paging for online searches. Use the Data Access Application wizard.
Addition of data to SQL table. Use the Table Editor in the workbench Data
Perspective.
SQL statement validation In the EGL editor, select Validate SQL from
the context menu.
Run interactive SQL using the SQL Editor in
the workbench Data Perspective.
Related tasks
“Creating an SQL database connection”The New Connection wizard creates an SQL database connection that you can
use either at design time or at run time.
“Reading and writing records” on page 156
“Retrieving SQL table data” on page 170
“Creating a data access application” on page 173EGL can create a simple data access application based on a database to which
you are connected. The resulting application contains data parts, logic parts and
(optionally) Web pages that are based on one or more database tables.
“Viewing implicit SQL statements” on page 179
Creating an SQL database connection
The New Connection wizard creates an SQL database connection that you can use
either at design time or at run time.
EGL offers two other ways to create an SQL connection:
v The sqlLib.connect() system function, to activate a connection at run time; see
″connect()″ in the EGL Language Reference.
v The vgLib.connectionService() system function, for programs migrated from
VisualAge Generator or EGL version 5; see ″connectionService()″ in the EGL
Language Reference.
162 EGL Programmer’s Guide
Even if you plan to use either of these functions, it is still recommended that you
have a default connection in place.
Prerequisites
You must have a database set up and running. The database must be one of the
products that EGL supports. See “Supported SQL database managers” on page 166
for more information.
Opening the New Connection wizard
In EGL, you can access the New Connection wizard from many of the places
where an SQL connection is required. Here are two easy ways to open it:
v From the workbench menu, select Window → Preferences → EGL → SQL
Database Connections. To the right of the list labeled Connection, click the
button labeled New.
v Open the Data perspective (Window → Open Perspective → Other → Data). The
Database Explorer view is available in this perspective, by default in the lower
left corner of the workbench. Right-click Connections and pick New Connection
from the menu.
Note: The Data perspective is not filtered for EGL, and includes information for
other products. Thus if you run the New Connection wizard from the
Data perspective, you might see databases listed (such as Generic JDBC or
Sybase) that EGL does not support. Use the table in ″Supported database
managers″ to determine the database managers that you can use with
EGL.
The information the wizard needs might vary with the type of database that you
use. When you choose from the Select a database manager: list, the wizard fills in
as many default values as it can. For the list of supported databases and the
information that each requires, see “Supported SQL database managers” on page
166.
When you have given the wizard enough information, the Test Connection button
becomes available. Click this button to verify your connection information. If you
get an error message, you might need to work with your database administrator to
resolve the problem.
If the test is successful, you have everything you need to use the EGL features that
require a design-time connection, such as “Creating a data access application” on
page 173 or “Retrieving SQL table data” on page 170. You are not, however,
automatically set up to have an SQL connection at run time. To specify that
connection, see “Using an SQL database connection at run time” on page 168.
Creating the new connection
Once you have opened the New Connection wizard as explained above, you can
start filling in the information:
1. Under Select a database manager, select the type of database you are
connecting to. You should do this step first because the remainder of the fields
on the page depend on this choice.
2. Once you have selected the database type, fill in the remainder of the fields on
the page. Which fields you need to fill in depends on which database you are
connecting to. See ″Fields in the New Connection wizard″ below for
information on the individual fields.
3. When you have filled out the fields in the wizard, you can click Test
Connection to make sure that the connection is working.
Accessing data with EGL code 163
4. Click Next.
5. On the Filter page, you can select schemas from the database to be included or
ignored in the connection.
By default, the New Connection wizard will retrieve information for each
schema in the database and each table in each of those schemas. Retrieving this
information can take time on large databases. The EGL Data Access Application
wizard requires this connection information to produce parts from the database,
but the other areas of EGL design-time access functionality, such as the SQL
retrieve functionality described in “Retrieving SQL table data” on page 170, do
not require this information. For this reason, you can save time by filtering out
schemas or tables that you do not want to use with the Data Access
Application wizard, or by filtering out all of the schemas and tables if you do
not want to use this connection with the Data Access Application wizard at all.
6. If you do not want to filter schemas out of the connection, click Finish.
7. If you want to filter schemas out of the connection, follow these additional
steps:
a. Clear the Disable filter check box.
b. Click the Selection radio button. The schemas in the database are listed
below.
c. In the list under Selection, select Include selected items or Exclude
selected items, depending on whether you want to select the schemas to
include or the schemas to exclude from the connection.
d. Select or clear the check boxes next to the schemas in the list. You must
select at least one schema.
Schemas that you filter out of the connection will not be available if you use
this connection with the Data Access Application wizard.
e. Click Finish.
Alternately, you can select the Expression radio button and enter a search
string to indicate which tables should be included.
Fields in the New Connection wizard
The New Connection wizard fills in the following fields automatically:
JDBC driver
This is the EGL name for the driver that is used to talk to the database
manager, such as ″IBM DB2 Universal.″
JDBC driver class
This is the name of the Java class that contains the driver:
v For IBM DB2 Universal Driver, the driver class is
com.ibm.db2.jcc.DB2Driver
v For IBM DB2 APP DRIVER for Windows, the driver class is
COM.ibm.db2.jdbc.app.DB2Driver
v For the Oracle JDBC thin client-side driver, the driver class is
oracle.jdbc.driver.OracleDriver
v For the Informix JDBC NET driver, the driver class is
com.informix.jdbc.IfxDriver
v For the DataDirect SequeLink JDBC Driver for SQL Server, the driver
class is com.ddtek.jdbc.sqlserver.SQLServerDriver
v For the Microsoft JDBC Driver for SQL Server 2005, the driver class is
com.microsoft.jdbc.sqlserver.SQLServerDriver; for SQL Server 2000,
the driver class is com.microsoft.sqlserver.jdbc.SQLServerDriver
164 EGL Programmer’s Guide
v For Derby, the driver class is org.apache.derby.jdbc.EmbeddedDriver
v For Cloudscape™, the driver class is com.ibm.db2j.jdbc.DB2jDriver
v For other driver classes, refer to the documentation for the driver
Connection URL
This is the address that EGL uses to contact the database, such as
″jdbc:db2://localhost:50000/SAMPLE:retrieveMessagesFromServerOnGetMessage=true;″ This URL
contains a hostname, port number, and attributes.
You can override the default values in these fields by choosing Other for your
JDBC driver and specifying the appropriate JDBC driver class.
The wizard will complete as many of the other fields as it can, but might require
you to fill in some or all of the following:
Connection Name
You will not need to complete this field if you check the Use default
naming convention option, which typically uses the name of your
database.
SID The ID of the server where your database is located.
Host The host name of your database server.
Port number
The port number that you connect to on the host.
Server The address of your database server.
Database
The name of the specific database to which you want to connect.
Class location
The fully qualified location of the *.jar or *.zip file that contains the driver
class:
v For IBM DB2 Universal Driver, type the fully qualified filenames to the
db2jcc.jar and db2jcc_license_cu.jar files
v For IBM DB2 APP DRIVER for Windows, type the fully qualified
filename to the db2java.zip file; for example, d:\sqllib\java\db2java.zip
v For the Oracle THIN JDBC DRIVER, type the fully qualified pathname
to the ojdbc14.jar file; for example, d:\Ora81\jdbc\lib\ojdbc14.jar or, if
you require Oracle trace, ojdbc14_g.jar
v For the Informix JDBC NET driver, type the fully qualified filename to
the ifxjdbc.jar file
v For the DataDirect SequeLink JDBC Driver for SQL Server, type the fully
qualified filenames to the base.jar, util.jar, and sqlserver.jar files
v For the Microsoft JDBC Driver for SQL Server, type the fully qualified
filenames to the msbase.jar, msutil.jar, and mssqlserver.jar files
v For Derby, type the fully qualified filename to the derby.jar file
v For Cloudscape, type the fully qualified filename to the db2j.jar file
v For other driver classes, refer to the documentation for the driver
User ID
If your database is password protected, you can store the user ID here.
Note that the Tomcat server ignores the userID and password that you
provide here and uses the values from its server configuration.
Accessing data with EGL code 165
Password
If your database is password protected, you can store the password here.
Note that the Tomcat server ignores the userID and password that you
provide here and uses the values from its server configuration. Related tasks
“Creating a data access application” on page 173EGL can create a simple data access application based on a database to which
you are connected. The resulting application contains data parts, logic parts and
(optionally) Web pages that are based on one or more database tables.
“Retrieving SQL table data” on page 170
“Using an SQL database connection at run time” on page 168To use an SQL connection at run time, you must point to the connection from
your project’s build descriptor.
“Editing or deleting an SQL database connection” on page 169 Related reference
“Supported SQL database managers”The following table provides a list of the SQL databases that EGL supports.
Supported SQL database managers
The following table provides a list of the SQL databases that EGL supports.
To create a connection, the New Connection wizard requests some or all of the
information in the right column. This information is provided so that you can
obtain the right information from a database administrator, if necessary. For more
information about these connection fields, see “Fields in the New Connection
wizard” on page 164.
Table 30. Supported databases
Database
Manager Versions Setup Information
Cloudscape 5.1 v JDBC driver
v JDBC driver class
v Class location
v Connection URL
v User ID
v Password
DB2 UDB V8.1, V8.2, V9.1 v JDBC driver
v Host
v Port number
v JDBC driver class
v Class location
v Connection URL
v User ID
v Password
166 EGL Programmer’s Guide
Table 30. Supported databases (continued)
Database
Manager Versions Setup Information
DB2 UDB
iSeries
V5R2, V5R3, V5R4 v JDBC driver
v JDBC driver class
v Class location
v Connection URL
v User ID
v Password
DB2 UDB
zSeries
V7, V8 (Compatibility
Mode or
New-Function Mode)
v JDBC driver
v Host
v Port number
v JDBC driver class
v Class location
v Connection URL
v User ID
v Password
Derby 10.0, 10.1 v JDBC driver
v Database location
v JDBC driver class
v Class location
v Connection URL
v User ID
v Password
Informix 9.2, 9.3, 9.4, 10.0 v JDBC driver
v Database
v Host
v Port number
v Server
v JDBC driver class
v Class location
v Connection URL
v User ID
v Password
Oracle 8, 9, 10 v JDBC driver
v SID
v Host
v Port number
v JDBC driver class
v Class location
v Connection URL
v Catalog
v User ID
v Password
Accessing data with EGL code 167
Table 30. Supported databases (continued)
Database
Manager Versions Setup Information
SQL Server 2000, 2005 v JDBC driver
v Host
v Port number
v JDBC driver class
v Class location
v Connection URL
v User ID
v Password
Related tasks
“Creating a data access application” on page 173EGL can create a simple data access application based on a database to which
you are connected. The resulting application contains data parts, logic parts and
(optionally) Web pages that are based on one or more database tables.
“Creating an SQL database connection” on page 162The New Connection wizard creates an SQL database connection that you can
use either at design time or at run time.
Using an SQL database connection at run time
To use an SQL connection at run time, you must point to the connection from your
project’s build descriptor.
Prerequisites
You will need a working SQL connection. For instructions on setting up this
connection, see “Creating an SQL database connection” on page 162.
Editing your build descriptor
1. Double-click the build descriptor for your project. Typically, the build
descriptor file is located in the top level of the EGLSource directory of your
project and is named project.eglbld. The build descriptor will open in the editor
window.
2. On the upper right side of the window, find the list box Load DB options
using Connection:. Pick the connection name that you want to use. If you have
not already created this connection, see “Creating an SQL database connection”
on page 162.
When you select a connection, the build parts editor updates the following
build descriptor options to match the connection:
v dbms
v sqlDB
v sqlID
v sqlJDBCDriverClass
v sqlPassword
v sqlValidationConnectionURL
3. Save the build descriptor and close the window.
4. If you have existing EGL programs that perform SQL I/O, remember to rebuild
them using the Project → Clean top-level menu option in the workbench.
168 EGL Programmer’s Guide
Error conditions
EGL uses a different process to connect with the database at run time than it does
at design time. These differences might result in errors when you try to run your
code:
v EGL might not be able to find the Java class containing the driver for your
database manager, even though you specified a Class location in the New
Connection wizard. To correct this error, make sure the driver is on the classpath
for your project:
1. Right-click on your project name in the Project Explorer view and click
Properties from the context menu.
2. Select Java Build Path from the left pane of the Properties window.
3. Click the Libraries tab on the Java Build Path page.
4. If the correct class location is not displayed, click Add External JARs and
add the class and location. You can copy this information from your
Connection; see “Editing or deleting an SQL database connection”
. Related tasks
“Creating an SQL database connection” on page 162The New Connection wizard creates an SQL database connection that you can
use either at design time or at run time.
“Editing or deleting an SQL database connection”
Editing or deleting an SQL database connection
Prerequisites
v An existing database connection
Editing an existing connection
To edit an existing database connection, do as follows:
1. Click Window → Open → Perspective → Other. At the Select Perspective dialog,
select the Show all check box and double-click Data.
2. In the Database Explorer view, right-click the database connection, then select
Edit Connection. Step through the pages of the database connection wizard
and change information as appropriate. For help, press F1. For a list of the
required fields for each database type, see “Supported SQL database managers”
on page 166.
3. To complete the edit, click Finish.
Alternately, you can edit an existing connection from the EGL preferences:
1. Click Window → Preferences.
2. Expand EGL and click SQL Database Connections.
3. Select the connection from the Connection list.
4. Click Edit.
5. Change information in the connection as appropriate.
6. When you are finished editing the connection, click Finish and then click OK
to close the Preferences window.
Deleting an existing connection
To delete an existing database connection, do as follows:
1. Select Window > Open Perspective > Other. In the Select Perspective dialog
box, select the Show all check box and double-click Data.
Accessing data with EGL code 169
2. In the Database Explorer view, right-click the database connection, and then
click Delete. Related reference
“Creating an SQL database connection” on page 162The New Connection wizard creates an SQL database connection that you can
use either at design time or at run time.
“Supported SQL database managers” on page 166The following table provides a list of the SQL databases that EGL supports.
Retrieving SQL table data
With EGL, you can create SQL record fields from the definition of an SQL table,
view, or join.
To create SQL record fields from the definition of an SQL table:
1. Ensure that you have set SQL preferences as appropriate. For details, see
“Setting preferences for SQL retrieve” on page 181.
2. Set the default database connection, which is the connection that EGL will use
to retrieve the table data:
a. Click Window → Preferences.
b. Expand EGL and click SQL Database Connections.
c. Select your database connection from the Connection list or create a new
database connection. The connection selected in the Connection list is the
default database connection.3. Decide where to do the task:
v In an EGL source file, as you develop each SQL record; or
v In the Outline view, as may be easier when you already have SQL records.4. If you are working in the EGL source file, proceed in this way. If you are
working in the Outline view, skip to the next step.
a. If you do not have the SQL record, create it:
1) Type R, press Ctrl+Space, and in the content-assist list, select one of the
SQL table entries (usually SQL record with table names).
2) Type the name of the SQL record, press Tab, and then type a table name,
or a comma-delimited list of tables, or the alias of a view.You also can create an SQL record by typing the minimal content, as
appropriate if the name of the record is the same as the name of the table,
as in this example:
Record myTable type sqlRecord
end
b. Right-click anywhere in the record.
c. In the menu, click SQL record > Retrieve SQL.5. If you are working in the Outline view, right click the entry for the SQL record
and, in the context menu, click Retrieve SQL.
Note: You cannot retrieve an SQL view that is defined with the DB2 condition
WITH CHECK OPTIONS.
After you create record fields, you may want to gain a productivity benefit by
creating the equivalent DataItem parts for the fields in the record:
1. Open the record in the EGL editor and then open the Outline view. The Outline
view shows a hierarchical view of the parts and other EGL code on the page.
170 EGL Programmer’s Guide
2. In the Outline view, right-click the field and then click Create DataItem Part.
EGL creates a dataItem part based on the field in the record and uses that
dataItem as the field type.
Compatibility of SQL data types and EGL primitive types
An EGL host variable (see “Host variables” on page 176) and the corresponding
SQL table column are compatible in any of the following situations:
v The SQL column is any form of character data, and the EGL host variable is of
the type CHAR with a length less than or equal to the length of the SQL
column.
v The SQL column is any form of DBCHAR data, and the EGL host variable is of
the type DBCHAR with a length less than or equal to the length of the SQL
column.
v The SQL column is any form of number and the EGL host variable is of one of
these types:
– BIN(4,0)/SMALLINT
– BIN(9,0)/INT
– BIN(18,0)/BIGINT
– DECIMAL, with a maximum length of 18 digits, including decimal places.
The number of digits for a DECIMAL variable should be the same for the
EGL host variable and for the column.v The SQL column is of any data type, the EGL host variable is of type HEX, and
the column and host variable contain the same number of bytes. No data
conversion occurs during data transfer.
EGL host variables of type HEX support access to any SQL column of a data
type that does not correspond to an EGL primitive type.
If character data is read from an SQL table column into a shorter host variable,
content is truncated on the right. To test for truncation, use the reserved word
trunc in an EGL if statement.
Default mapping
EGL uses a default mapping when it creates records with the Retrieve SQL feature.
The following table shows the default mapping.
Table 31. EGL variable characteristics
SQL data type EGL variable characteristics
Primitive type Digits/characters Number of bytes
BIGINT BIGINT n/a 8
BIT SMALLINT n/a 2
BLOB BLOB n/a n/a
BOOLEAN BOOLEAN n/a 1
CHAR CHAR 1–32767 1–32767
CLOB CLOB n/a n/a
DATE DATE n/a 8
DECIMAL DECIMAL 1-18 1–10
DOUBLE FLOAT n/a 8
FLOAT FLOAT n/a 8
GRAPHIC DBCHAR 1–16383 2–32766
Accessing data with EGL code 171
Table 31. EGL variable characteristics (continued)
SQL data type EGL variable characteristics
Primitive type Digits/characters Number of bytes
INTEGER INT n/a 4
LONG VARBINARY HEX 65534 32767
LONG VARCHAR CHAR >4000 >4000
LONG VARGRAPHIC DBCHAR >2000 >4000
NUMERIC DECIMAL 1-18 1–10
REAL SMALLFLOAT n/a 4
SMALLINT SMALLINT n/a 2
TIME TIME n/a 6
TIMESTAMP TIMESTAMP n/a 14
VARBINARY HEX 2–65534 1–32767
VARCHAR CHAR ≤4000 ≤4000
VARGRAPHIC DBCHAR ≤2000 ≤4000
The definition of an SQL table column of the type VARCHAR or VARGRAPHIC
includes a maximum length, and the retrieve command uses that maximum to
assign a length to the EGL host variable. The definition of an SQL table column of
the type LONG VARCHAR or VARGRAPHIC, however, does not include a
maximum length, and the retrieve command uses the SQL-data-type maximum to
assign a length.
Compatibility
Table 32. Compatibility considerations for SQL data
Platform Issue
Java generation If numeric data is read from an SQL table column into a
shorter host variable, EGL treats the situation as it would an
overflow on an assignment statement.
COBOL generation If numeric data is read from an SQL table column into a
shorter host variable, leading zeros are truncated on the left. If
the number still does not fit into the host variable, fractional
parts of the number (in decimal) are deleted on the right, with
no indication of error. If the number still does not fit, a
negative SQL code is returned to indicate an overflow
condition.
Related concepts
“Accessing data with EGL code” on page 155
“Working with SQL data” on page 161SQL (pronounced as three separate letters) refers to a language that is designed
to communicate with the software that controls a relational database. Related tasks
“Creating a data access application” on page 173EGL can create a simple data access application based on a database to which
you are connected. The resulting application contains data parts, logic parts and
(optionally) Web pages that are based on one or more database tables.
“Setting preferences for SQL database connections” on page 181
172 EGL Programmer’s Guide
“Setting preferences for SQL retrieve” on page 181
Creating a data access application
EGL can create a simple data access application based on a database to which you
are connected. The resulting application contains data parts, logic parts and
(optionally) Web pages that are based on one or more database tables.
Prerequisites
Before you begin, connect to an SQL database. See “Creating an SQL database
connection” on page 162.
Files created for the application
For each table that you select, the EGL Data Access Application wizard creates the
following parts. You can choose to put these parts into a new project or into one or
more existing projects.
v Data parts based on the table:
– An SQLRecord part that represents the table
– DataItem parts that represents the columns in the tablev Data access functions that perform operations on the database, such as adding,
retrieving, and deleting records. You can choose to put these data access
functions in libraries or in services.
Also, you have the option of creating a Web interface for the data access
application. If you choose to create a Web interface, the wizard creates these
additional files and parts:
v A set of JSF handler parts that you later generate into a set of parts that run
under JavaServer Faces
v A set of JSP files that provide the following Web pages:
– A selection condition page, which accepts selection criteria from the user
– A list page, which displays multiple rows, based on the user’s criteria
– A create detail page, which enables the user to display or insert one row
– A detail page, which enables the user to display, update, or delete one row
Projects in the application
Before you begin creating the application, make two decisions about where the
new files and parts will go:
v You can put all the new files and parts into one project, or you can put the files
and parts into different projects, based on the kind of file and part. Data parts,
logic parts, and JSF handler parts (with the associated Web pages) can all go into
separate projects.
v You can put files and parts into a new project or into an existing project. If you
choose to put parts into different projects, some can go into an existing project
and others can go into a new project.
Creating the application
1. Click File → New → Other.
2. In the New window, expand EGL and click EGL Data Access Application.
3. Click Next.
Accessing data with EGL code 173
4. In the Project Name field, either select an existing EGL project or type the
name of a new project. Later, you will be able to fine-tune where the new data
parts, logic parts, and Web pages will go, but at least one kind of part will go
into the project you specify here.
5. In the Database Connection list, select a database connection. You can create a
new one by clicking the New button. For more information, see “Creating an
SQL database connection” on page 162.
After you have selected a database connection, the tables in the database
schema are listed in the Table Name list.
6. In the Table Name list, select the check box next to the tables that you want
to include in the data access application.
7. If you want to create a Web interface for the application, including JSF
handler parts and Web pages, select the Generate to EGL Web project check
box. If you clear this check box, your application will contain logic parts and
data parts that enable you to access the database, but no JSF handler parts or
Web pages.
8. Click Next.
The Define the Fields page has a tab for each table that you selected on the
previous page. On this page, you select the key fields for each table and
which fields you want to be able to search.
9. Select the key fields for each table in the Choose key fields list. If the table
already had a key field in the database, that field is selected as a key already.
You cannot remove a key field that is defined in the database.
10. If you are creating a Web interface, select the search fields for each table in the
Choose search UI fields list. The wizard creates a search page for each table
you selected, and that search page will have an input field for each field that
you select here.
11. Click Next.
If you are creating a Web interface, you will see the Configure the Fields page.
Otherwise, the wizard skips ahead to the Define Generation options page.
As in previous steps, the Configure the Fields page also has a tab for each
table that you selected. On this page, you select how the Web pages will
display the data.
12. Set the display name for each field in the Modify field display name list. The
value in the Display As column will be that field’s label wherever it appears
on a Web page. In EGL terms, this value becomes the value of the
displayName data item property.
13. Select the fields to show on the search results page by selecting check boxes in
the Choose summary fields list.
14. Click Next.
The Define project creation options page has options for the new projects and
packages.
15. In the Default package name field, type the name of the root package that
will contain the new EGL parts. The default value is the name of the database
connection.
16. Under Data access method, select whether you want to create library parts or
service parts to hold the new data access functions.
17. If you want to put all of the new files and parts into one project, clear the
Create multiple projects check box. All of the new files and parts will be
created in the project that you entered in the Project Name field on a previous
page. Then, click Finish.
174 EGL Programmer’s Guide
18. If you want to put the new files and parts into different projects, select the
Create multiple projects check box and then click Next. Specify additional
options about the projects on the next page.
The Define alternate project locations page enables you to select separate
projects to hold the new data parts, logic parts, and Web interface files and
parts, with the following restrictions:
v At least one of the projects must be the same as the project you entered in
the Project Name field on a previous page.
v You cannot put all of the files and parts in the same project. If you want to
put all of the files in the same project, go back one page and clear the
Create multiple projects check box.19. For each kind of file or part, choose a project.
v In the Data Project Name field, select a project to hold the new data parts.
v In the Data Access Project Name field, select a project to hold the new
logic parts (services or libraries, depending on your choices on the previous
page).
v In the UI Project Name field, select a project to hold the new Web pages
and JSF handler parts.20. For each project, select the EGL Web Project field if you want the respective
project to be an EGL Web project.
21. Click Next.
22. The final page of the wizard shows a summary of your choices so far. You can
click Finish and complete the process or go back to previous pages and
change your selections.
23. After the projects and files are created, you might need to add the projects to
the EGL and Java build paths of other projects. See “The EGL build path” on
page 71. Related tasks
“Creating an SQL database connection” on page 162The New Connection wizard creates an SQL database connection that you can
use either at design time or at run time.
Working with SQL statements
With EGL you can deal with explicit SQL code in your EGL program.
You can do some reasonably sophisticated database manipulation in EGL without
writing a word of SQL. Experienced SQL programmers, however, might want the
level of control that writing in SQL gives them. EGL accommodates those
programmers through the #sql directive.
The #sql directive
The EGL keyword #sql introduces a section of explicit SQL code, delimited by
braces, as in the following example:
get myCustomer with #sql{
select C_NUMBER, C_NAME, C_ADDR1, C_ADDR2, C_ADDR3, C_BALANCE
from ADMINISTRATOR.CUSTOMER L1
where C_NUMBER = :myCustomer.customerNumber };
You may modify this code to fine tune your SELECT statement. For more
information, see “Viewing implicit SQL statements” on page 179. You can also use
the #sql directive to call a stored procedure (see “Calling a stored procedure” on
page 176).
Accessing data with EGL code 175
Host variables
You might have noticed in the preceding example that the variable
myCustomer.customerNumber has a colon in front of it. This tells EGL to look for the
variable name within the EGL program, not the SQL table. Such variables are
called host variables, because EGL is the programming language that is hosting SQL;
SQL cannot run as an independent language.
Related tasks
“Executing a prepared statement” on page 177The prepare keyword constructs an SQL statement from a string. Then, you can
run that prepared statement with another data-access statement.
“Calling a stored procedure”You can call an SQL stored procedure with the open or execute statements and
the #sql directive.
“Viewing implicit SQL statements” on page 179
Calling a stored procedure
You can call an SQL stored procedure with the open or execute statements and the
#sql directive.
A stored procedure is a set of instructions for a database, like a function in EGL.
Stored procedures differ from prepared statements because the stored procedure is
kept permanently in the database itself, while a prepared statement is local to your
program or logic part and is cached by the database only temporarily. Also, a
stored procedure can consist of many SQL statements, while a prepared statement
can consist of only one SQL statement. Fundamentally, however, you can execute
the same instructions with a stored procedure as you can with a prepared
statement.
Prerequisites
v An EGL project and program or other logic part
v An SQL database with a stored procedure
Using execute to call a stored procedure
The execute keyword is appropriate for calling stored procedures that do not
return a result set. You can also use execute to call stored procedures that return
one or more result sets, but in that case any result sets are ignored.
To call a stored procedure with execute, use the #sql directive and specify the
name of the stored procedure in the explicit SQL:
execute #sql{
CALL MYSTOREDPROCEDURE
};
If the stored procedure accepts parameters, pass EGL variables as host variables
(see “Host variables”):
myParameter int = 5;
execute #sql{
CALL MYSTOREDPROCEDURE(:myParameter)
};
176 EGL Programmer’s Guide
Using open to call a stored procedure
You can use the open keyword to call only stored procedures that return exactly
one result set. To call a stored procedure that does not return a result set or that
returns more than one result set, use execute.
To call a stored procedure with open, use the #sql directive and specify the name
of the stored procedure in the explicit SQL:
open myResultSet with #sql{
CALL GETCUSTOMERS
};
Then you can access the result set through the myResultSet identifier, as in the
following example, which assumes a SQLRecord part named myCustomers:
myCustomers myCustomers;
get next from myResultSet into myCustomers;
If the stored procedure accepts parameters, pass EGL variables as host variables:
myParameter int = 5;
open myResultSet with #sql{
CALL GETCUSTOMERS(:myParameter)
};
Limitations
The following limitations apply to using stored procedures in EGL:
v You can call stored procedures with open only if the stored procedure returns
exactly one result set.
v You cannot use open to call a stored procedure on COBOL or on an Oracle
DBMS.
v You cannot use open to call a stored procedure on an Informix DBMS if the
stored procedure has any OUT or INOUT parameters.
v You cannot call a stored procedure on a Microsoft SQL Server DBMS if the
stored procedure contains any OUT parameters. Related tasks
“Executing a prepared statement”The prepare keyword constructs an SQL statement from a string. Then, you can
run that prepared statement with another data-access statement.
“Viewing implicit SQL statements” on page 179
Executing a prepared statement
The prepare keyword constructs an SQL statement from a string. Then, you can
run that prepared statement with another data-access statement.
Using prepared statements instead of explicit SQL code can improve performance
for data access operations that you use repeatedly. When you create a prepared
statement, the database performs much of the processing necessary for the
statement ahead of time. Then, the database has to perform less processing when
you execute the prepared statement. Whether you use a prepared statement or
explicit SQL depends on how many times you use the data access operation.
Fundamentally, executing a prepared statement is no different from executing any
explicit SQL code. The following two functions are equivalent:
Accessing data with EGL code 177
function executeExplicitSQL()
myCustomers myCustomers[0];
get myCustomers with #sql{
SELECT CUSTOMER_ID, LAST_NAME
FROM MYSCHEMA.MYTABLE
};
end
function executePreparedStatement()
myCustomers myCustomers[0];
prepare myStatement from
"SELECT CUSTOMER_ID, LAST_NAME FROM MYSCHEMA.MYTABLE";
get myCustomers with myStatement;
end
The previous examples used the get statement to execute the prepared statement,
but you can also use execute or open. In each case, the prepared statement must
be appropriate for the data access statement. In other words, if you can execute the
string as explicit SQL, you can also prepare and execute the string as a prepared
statement. You can use prepare for standard SQL statements such as SELECT, for
dynamic SQL statements that include variables, and for calls to stored procedures.
Preparing and executing the statement
To prepare the statement, first create a string variable to hold the statement. Like
any string, you can assign a value to the variable directly or assemble the value
from multiple strings or variables:
myString string = "SELECT ";
myString += "CUSTOMER_ID, LAST_NAME ";
myString += "FROM MYSCHEMA.MYTABLE";
Then, use prepare to create the prepared statement from the variable, assigning the
statement to a new identifier:
prepare myStatement from myString;
Also, you can add a for clause to specify the SQLRecord to use with the prepared
statement:
myCustomer myCustomers;
prepare myStatement2 from myString for myCustomer;
Finally, execute the statement and put the results into a variable:
myCustomerArray myCustomers[];
get myCustomerArray with myStatement2;
Using variables in the prepared statement
Prepared statements are especially useful when you want to insert variables into
the statement. Variables in prepared statements are even more powerful than host
variables in normal explicit SQL code, because you can do more than just insert an
EGL variable value; you can change which variable the dynamic statement uses.
When creating a prepared statement, you use a question mark (?) to represent
variables. The question mark acts as a placeholder into which you can insert a
value later with the using clause:
myCustomerID int = 5;
myCustomerArray myCustomers[];
myHostVarString string = "SELECT CUSTOMER_ID, LAST_NAME";
myHostVarString += " FROM MYSCHEMA.MYTABLE";
178 EGL Programmer’s Guide
myHostVarString += " WHERE CUSTOMER_ID = ?";
prepare myStatement from myHostVarString;
get myCustomerArray with myHostVarString using myCustomerID;
In this case, you can change the using myCustomerID clause to use different
variables in different situations.
Creating a detailed prepared statement
EGL also provides a tool that creates a prepare statement and the related execute,
get, or open statement.
1. Within a function in your logic part, right-click a blank line and then click Add
SQL Prepare Statement. The Add SQL Prepare Statement window opens.
2. In the Prepared statement identifier field, type a name to identify the EGL
prepare statement. For rules, see ″Naming conventions″ in the EGL Language
Reference.
3. In the SQL record variable name field, select a record variable from the list or
type a name for a new variable and then select an SQL record part using the
Browse button. You must eventually define an SQL record variable with that
name in the EGL source code.
4. In the Execution statement type field, select execute,get, or open.
5. If you selected open in the Execution statement type field, type an identifier
for the result set in the Result set identifier field.
6. Click OK. EGL creates the prepare statement and related data access statement.
Related concepts
“Working with SQL statements” on page 175With EGL you can deal with explicit SQL code in your EGL program.
Related tasks
“Calling a stored procedure” on page 176You can call an SQL stored procedure with the open or execute statements and
the #sql directive.
Viewing implicit SQL statements
EGL creates implicit SQL statements whenever you use an EGL data-access
statement (such as add or get) that specifies an SQL record variable as its target.
This feature enables you to write functions that access a relational database even if
you do not know any SQL at all. It also enables you to generate default SQL code
that you can customize.
EGL can also display a default SELECT statement based on an SQL Record
definition.
The default SELECT statement: Right-click within the first line of an SQL Record
definition and select SQL Record. A second menu offers you the following choices:
Retrieve SQL
If you are in the process of defining the record, this option asks EGL to
construct the record definition for you, based on fields in the database
table. See “Retrieving SQL table data” on page 170.
View Default Select
This option pops up a window that contains the SQL SELECT statement
that returns all information in the current record. You can copy the
contents of this window by highlighting it and pressing Ctrl+C.
Accessing data with EGL code 179
Validate Default Select
This option compares the information in the SELECT statement to the
structure of the referenced SQL database and makes sure that such a query
would work correctly.
Implicit SQL statements: The opposite of an implicit SQL statement is an
embedded SQL statement. Here you include explicit SQL code as part of an EGL I/O
statement that is introduced by a #sql directive. For details of the #sql syntax, see
″#sql directive″ in the EGL Language Reference.
To deal with the transformation of implicit SQL code to embedded SQL code,
right-click anywhere in an EGL I/O statement that references a record variable
based on a Record part with the SQLRecord stereotype. Choose SQL Statement
from the menu. The examples in this section all use the following Record part:
record CustomerRecord type SQLRecord
{tableNames = [["ADMINISTRATOR.CUSTOMER", "L1"]],
keyItems = [customerNumber]}
customerNumber STRING {column="C_NUMBER", maxLen=6};
customerName STRING {column="C_NAME", isSqlNullable=yes, maxLen=25};
customerAddr1 STRING {column="C_ADDR1", isSqlNullable=yes, maxLen=25};
customerAddr2 STRING {column="C_ADDR2", isSqlNullable=yes, maxLen=25};
customerAddr3 STRING {column="C_ADDR3", isSqlNullable=yes, maxLen=25};
customerBalance MONEY {column="C_BALANCE", isSqlNullable=yes};
end
The following options are available from the SQL Statement menu:
Add This option converts implicit SQL code to embedded SQL code and adds it
to your program. The Add option converts the simple I/O statement get
myCustomer to the following:
get myCustomer with #sql{
select
C_NUMBER, C_NAME, C_ADDR1, C_ADDR2, C_ADDR3, C_BALANCE
from ADMINISTRATOR.CUSTOMER L1
where
C_NUMBER = :myCustomer.customerNumber
};
Add with Into
This option functions the same as Add, but includes an EGL into clause for
the field names in the EGL record variable. This is useful if you want to
update only some of the fields; you can remove the field names you do not
want to update from the into and select clauses:
get myCustomer
into myCustomer.customerNumber, myCustomer.customerName,
myCustomer.customerAddr1, myCustomer.customerAddr2,
myCustomer.customerAddr3, myCustomer.customerBalance with
#sql{
select
C_NUMBER, C_NAME, C_ADDR1, C_ADDR2, C_ADDR3, C_BALANCE
from ADMINISTRATOR.CUSTOMER L1
where
C_NUMBER = :myCustomer.customerNumber
};
View This option displays the implicit SQL code without adding to the code.
You can, however, highlight the code in the pop-up display and copy it by
pressing Ctrl+C. From the View dialog you also have the option to Add,
Add with Into, Reset, and Validate the SQL statement.
180 EGL Programmer’s Guide
Validate
This option checks to see whether the implicit SQL code is well-formed
and will work correctly.
Remove
This option removes the embedded SQL code and returns you to your
original I/O statement.
Reset If you have edited the embedded code that EGL added to your program,
this will undo all of your edits and restore the original embedded code. Related concepts
“Accessing data with EGL code” on page 155 Related tasks
“Preferences” on page 147EGL preferences affect the way the workbench displays and works with EGL.
“Retrieving SQL table data” on page 170
Setting preferences for SQL database connections
In the workbench, you can create declaration-time and debug-time database
connections. See “Creating an SQL database connection” on page 162 to create a
new connection in these preferences, or follow these steps to set up or edit the
connections:
1. Click Window → Preferences.
2. When a list of preferences is displayed, expand EGL, then click SQL Database
Connections.
3. The currently selected connection in the Connection list is the default database
for EGL in the workbench. You can switch between database connections, edit
or delete the connections, and test the connections from this window.
You can clear or apply preference settings:
v To restore default values, click Restore Defaults.
v To apply preference settings without exiting the preferences dialog, click Apply.
v If you are finished setting preferences, click OK. Related tasks
“Creating an EGL Web project” on page 63This topic covers how to create an EGL Web project.
“Preferences” on page 147EGL preferences affect the way the workbench displays and works with EGL.
Setting preferences for SQL retrieve
At EGL declaration time, you can use the SQL retrieve feature to create an SQL
record from the columns of an SQL table.
To set preferences for the SQL retrieve feature, do as follows:
1. Click Window → Preferences, expand EGL and then click SQL
2. Specify rules for creating each structure field that the SQL retrieve feature
creates:
a. To specify the EGL type to use when creating a structure field from an SQL
character data type, click one of the following radio buttons:
v Use EGL type string (the default) maps SQL char data types to EGL
string data types.
Accessing data with EGL code 181
v Use EGL type limited-length string maps SQL char data types to EGL
limited-length string data types.
v Use EGL type char maps SQL char data types to EGL char data types.
v Use EGL type mbChar maps SQL char data types to EGL mbChar data
types.
v Use EGL type Unicode maps SQL char data types to EGL Unicode data
types.b. To specify the EGL type to use when creating a structure field from an SQL
national character data type, click one of the following radio buttons:
v Use EGL type dbChar (the default) maps the SQL type to EGL dbChar
data types.
v Use EGL type Unicode maps the SQL type to EGL Unicode data types.
v Use EGL type string maps the SQL type to EGL string data types.
v Use EGL type limited-length string maps the SQL type to EGL
limited-length string data types.c. To specify the case of the structure field name, click one of the following
radio buttons:
v Do not change case (the default) means that the case of the structure field
name is the same as the case of the related table column name.
v Change to lower case means that the structure field name is a lower-case
version of the table column name.
v Change to lower case and capitalize first letter after underscore also
means that the structure field name is a lower-case version of the table
column name, except that a letter in the structure field name is rendered
in uppercase if, in the table column name, the letter immediately follows
an underscore.d. To specify how the underscores in the table column name are reflected in
the structure field name, click one of the following radio buttons:
v Do not change underscores (the default) means that underscores in the
table column name are included in the structure field name.
v Remove underscores means that underscores in the table column name
are not included in the structure field name.3. If you want new SQL records to be compatible with COBOL programs (that is,
to have fixed records with level numbers for structure items, and to use CHAR
instead of STRING primitive types), select the Add level numbers to record
definition check box.
4. If you want new SQL records to have the key field property set, select the
Retrieve primary key information from the system catalog check box.
5. If you want to be prompted for a database password if you did not supply one
for the connection on the SQL Database Connections page, select the Prompt
for SQL user ID and password when needed check box.
6. Click Apply to save the changes and remain in the Preferences window. Click
OK to save the changes and exit the window. Related concepts
“Accessing data with EGL code” on page 155 Related tasks
“Retrieving SQL table data” on page 170
“Preferences” on page 147EGL preferences affect the way the workbench displays and works with EGL.
“Setting preferences for SQL database connections” on page 181
182 EGL Programmer’s Guide
Building EGL Web applications
In an EGL Web application, EGL logic parts control Web pages, enabling you to
put data on Web pages, get data from user input on Web pages, and forward users
from page to page.
Related concepts
“Elements of a Web application”The main elements of an EGL Web application are the Web pages themselves
and JSF Handlers, which are logic parts that control the Web pages.
“Binding JSF controls to EGL variables and functions” on page 187When you have a JSP file and an associated JSF Handler part, you can begin
developing the Web page’s behavior. This means binding, or connecting,
elements on the Web page to variables and functions in the JSF Handler.
Elements of a Web application
The main elements of an EGL Web application are the Web pages themselves and
JSF Handlers, which are logic parts that control the Web pages.
JSF Handler part
A JSF Handler part, also called a JSF Handler, is a logic part that is customized to
control a Web page at run time. In prior versions of EGL, JSF Handlers were
PageHandler parts and referred to generally as page handlers.
Like other types of logic part, JSF Handler parts can contain any number of
user-defined functions. You might use functions in a JSF Handler to validate or
change the data that a user types into a Web page, to assign values to fields in a
Web page, to respond to a user’s actions on the page, or to forward the user or
data to a different page. However, it is best to keep JSF Handlers as simple as
possible and to use libraries or services for complicated business logic, because
functions in a JSFHandler part behave as though they are private and are not
available to other EGL logic parts or other JSF Handlers.
JSF Handler parts also contain specialized functions that run automatically at
certain points in the life of a Web page. For more information, see “Executing
commands when a page loads” on page 203.
You can also make variables and functions that are defined in the JSF Handler
available to the Web page. In this case, you bind the variable to an input or output
component on the page, or bind the function to a command button. When a
variable is bound to a component on the page and the user changes the value in
the component, the value of the variable changes to match, and if the logic in the
JSF Handler changes the value of the variable, the value on the page changes to
match. Likewise, if a user clicks a button bound to a function in the JSF Handler,
that function is called.
Generally, there is a one-to-one relationship between JSF Handlers and Web pages.
See ″JSF handler″ in the EGL Language Reference for more information about JSF
Handler parts.
© Copyright IBM Corp. 1996, 2007 183
Java Server Pages (JSP) files
The Java Server Pages (JSP) files in an EGL Web project are the files that most
resemble the Web pages that a user will actually see in the browser. In Web terms,
these files create the view portion of a Web application. JSP files contain all the text,
tables, and other elements that are commonly seen on Web pages, plus dynamic
areas that can change at run time based on the logic in the JSF Handler. For these
dynamic areas, EGL Web applications use JavaServer Faces (JSF), a technology that
includes reusable user interface components, such as command buttons, links,
input fields, and output fields. In EGL Web applications, you add JSF components
to your JSP files and refer to those JSF components in your JSF Handler code.
JSF configuration file
The JavaServer Faces (JSF) configuration file contains information for your pages
and for the JSF components on those pages. In general you will not need to edit
the JSF configuration file yourself, but you should be aware of the information
stored in the file and how it affects your EGL pages. For example, the JSF
configuration file contains navigation rules, or navigation aliases for your pages.
EGL uses these aliases with the forward statement to allow your JSF Handlers to
forward the user from one page to another. See “Navigating among Web pages
with navigation rules” on page 201.
By default, the JSF configuration file is named faces-config.xml and is located in
the WebContent/WEB_INF folder.
Web deployment descriptor
The Web deployment descriptor, not to be confused with the EGL deployment
descriptor, provides deployment information
The Web deployment descriptor is visible in your EGL Web project in two places:
v As the web.xml file, located in the project’s WebContent/WEB_INF folder by
default.
v As the Deployment Descriptor file at the root of your project, visible only in the
Project Explorer view.
These references point to the same file.
Web Site Navigation
By default, all Web projects in the workbench, including EGL Web projects, contain
a Web Site Navigation file. This file is labeled Web Site Navigation in the Project
Explorer view and named .website-config in the Navigator view. The Web Site
Navigation file allows you to plan your Web application with a map of the pages
and the relationships between them. For more information, see ″Designing Web
sites″ in the online help.
Web diagrams
By default, all Web projects in the workbench, including EGL Web projects, contain
a Web diagram. EGL does not support Web diagrams. Use the Web Site Navigation
file instead.
184 EGL Programmer’s Guide
Other Web resources
Like other Web projects, an EGL Web application can contain files that are used to
control the runtime appearance and behavior of Web pages, including images,
Cascading Style Sheet (CSS) files, and JavaScript files. For more information on
using style sheet files and using JavaScript, see the topics ″Defining styles″ and
″Adding code to Web pages″ in the online help.
Common tasks in Web applications
This section covers some common tasks that you might want to perform when
working with EGL Web applications.
Related tasks
“Creating a Web page” on page 186When you create a Web page in an EGL Web project, EGL creates a JSF Handler
part to go along with the page.
“Binding JSF controls to EGL variables and functions” on page 187When you have a JSP file and an associated JSF Handler part, you can begin
developing the Web page’s behavior. This means binding, or connecting,
elements on the Web page to variables and functions in the JSF Handler.
“Navigating among Web pages with navigation rules” on page 201A JSF Handler can control the navigation on a Web site, forwarding the user
from one page to another and passing data between pages. EGL works closely
with JavaServer Faces (JSF) navigation functionality to control page navigation
in this way.
“Forwarding data between Web pages” on page 202You can use the forward statement to pass data from one Web page to another
when you transfer control.
“Executing commands when a page loads” on page 203A JSF Handler can include functions that run automatically when the page
loads.
“Retrieving the value of a clicked row in a data table” on page 205The getClickedRowValue snippet in the EGL drawer of the Snippets view is a
function that retrieves the hyperlinked value of a clicked row in a data table.
“Setting the focus to a form field” on page 206The Set cursor focus snippet in the EGL drawer of the Snippets view is a
JavaScript function that sets the cursor focus to a specified form field on a Web
page. It must be placed within a <script> tag in a JSP page.
“Updating a row in a relational table” on page 210The database update snippet in the EGL drawer of the Snippets view is a
function that updates a single row of a relational table when passed a record
from a JSF Handler. This snippet is intended to be placed in an EGL library.
“Storing data in the user’s session” on page 211
“Testing browsers for a session variable” on page 213The Auto redirect snippet in the JSP drawer of the Snippets view tests for the
presence of a session variable. If the session variable is not present, the
customized code forwards control to a different Web page.
“Localizing text in Web applications” on page 214
“Creating a resource bundle” on page 217
“Locales for resource bundles” on page 218
Building EGL Web applications 185
“Running a Web page on a server” on page 235When you are working with a Web page in EGL, you can run the page on a
server to see how it will look when deployed.
“Accessing the JSF component tree with the source assistant” on page 236
Creating a Web page
When you create a Web page in an EGL Web project, EGL creates a JSF Handler
part to go along with the page.
Prerequisites
v An EGL Web project
Additionally, it is best if you choose a target server for your project before creating
Web pages. If your project does not have a target server, support for Faces
components will not work at run time, and you might see a warning reminding
you to choose a target server. See Specifying target servers for J2EE projects.
Creating a page along with a JSF Handler part
When you create a Web page to be used with EGL, be sure to select the correct
type of Web page:
1. Click File → New → Other. The New window opens.
2. Expand Web and click Web page (not JSP).
3. Click Next.
4. In the File Name field, type the name for the new Web page. The
accompanying JSF Handler will have the same name with an .egl extension.
5. In the Folder field, select the location for the new Web page. The location must
be in the WebContent folder of an EGL Web project. The accompanying JSF
Handler will be put into the project’s jsfhandlers package unless you specified
a different package in the workbench preferences.
6. Optionally, select a template that is compatible with JSP files in the Template
box. If you don’t select a template, the new Web page will be an empty JSP file
with no template.
v For a blank Web page, click Basic Templates → JSP.
v For a Web page with placeholders for graphics and navigation elements that
are linked to a page template, expand Sample Templates and select a
template.
v To use a template that is already in your project, click My Templates and
choose the template from the Preview box.
If you select a template other than the basic JSP template, the template files are
added to your project, and you can create more pages from the same template.
Then, when you change an area in the template, the matching area in each Web
page changes as well.
If you have selected a template that is not compatible with JSP files, a warning
will appear at the top of the page. Some templates default to file types other
than JSP, so by typing the .jsp extension into the File Name field, you
constrain yourself to templates compatible with JSP files.
7. Click Finish.
The new Web page and its JSF Handler part are created in your Web project.
Additionally, EGL creates a navigation rule in the JSF configuration file that
enables you to forward users to this page.
186 EGL Programmer’s Guide
Creating a page from an existing JSF Handler part
An alternate way to create an EGL-controlled Web page is to create a JSF Handler
part separately, and then let EGL create a default JSP file for you based on the
information in the JSF Handler.
1. Click File → New → Other.
2. Expand EGL and click JSF Handler.
3. Click Next.
4. Set the location and file name of the new Handler part.
5. Click Finish.
6. In the new JSF Handler, create variables to represent the data that you want to
use on the page.
7. On each variable that you want to display on the page, set the displayUse
property to input for an input field and output for a read-only output field. For
example, an integer field that you want to be displayed as an editable input
field on the page might look like this:
myInputVar string {displayUse = input};
For other options for the displayUse property, see ″displayUse″ in the EGL
Language Reference.
8. Set the view property of the JSF Handler to the name of the page you want to
create, including the .jsp extension. For example, if your JSF Handler is named
myPage, you might set the Handler’s properties as follows:
Handler myPage type JSFHandler
{view = "myPage.jsp"}
...
end
9. Save and generate the JSF Handler. EGL generates a default JSP that is based
on the Handler.
You can regenerate the JSP file at any time by deleting the JSP file and generating
the JSF Handler.
Related tasks
“Setting preferences for Web projects” on page 246These preferences control defaults for EGL Web projects and JSF Handler parts.
Binding JSF controls to EGL variables and functions
When you have a JSP file and an associated JSF Handler part, you can begin
developing the Web page’s behavior. This means binding, or connecting, elements
on the Web page to variables and functions in the JSF Handler.
The specific steps involved depend on the complexity of the Web page and of the
related EGL parts:
v You can bind a button on the page to a function in the JSF Handler so that when
the user clicks the button, the associated function in the JSF Handler runs. See
“Binding a JSF button to a function” on page 188.
v You can bind input and output controls on the Web page to variables in the JSF
Handler so that when the value changes on the page, the value of the associated
variable changes to match and when the value of the variable changes in the JSF
Handler, that value displayed on the page changes. See “Binding a control on a
Web page to a variable” on page 190.
Building EGL Web applications 187
v You can bind variables in the JSF Handler to a JSF single-select control, such as a
combo box or list box. See “Binding a JSF single-select control to a variable” on
page 194.
v You can bind an array of records to a data table on the page and return an array
of integers indicating which items the user has selected. See “Returning the
indexes of selected rows in a data table” on page 197.
v You can bind the inputs, outputs, and functions from a service to controls on the
page. These steps are essentially the same as binding ordinary input, output,
and command button controls to EGL variables and functions, but EGL provides
shortcuts for dealing with services on a Web page in this way. See “Binding JSF
controls to services” on page 200.
Although EGL is not case-sensitive, JSF is. EGL names referenced in the JSP file
must have the same case as the EGL variable or function declaration. For this
reason, you should avoid changing the case of variable or function names in a JSF
Handler after binding them to a JSF control. You can always repeat the binding
process to create a new, correct reference in the JSP file.
Related tasks
“Binding a JSF button to a function”When you bind a JSF button to a function in the JSF Handler, the function runs
when the user clicks the button.
“Binding a control on a Web page to a variable” on page 190You can bind a variable in the JSF Handler to an input or output control on the
Web page. When a variable is bound to a control on the page and the user
changes the value in the control, the value of the variable changes to match,
and if the logic in the JSF Handler changes the value of the variable, the value
on the page changes to match.
“Binding a JSF single-select control to a variable” on page 194Binding a JSF single-select control, such as a combo box or group of radio
buttons, to an EGL variable is more complicated than binding an input or
output control because you must use two EGL variables: one for the options in
the control and one for the selected value.
“Returning the indexes of selected rows in a data table” on page 197
“Binding JSF controls to services” on page 200Binding functions and variables from a service to controls on a Web page is no
different from binding any other type of functions and variables, but EGL
provides shortcuts for working with service controls in this way.
Binding a JSF button to a function
When you bind a JSF button to a function in the JSF Handler, the function runs
when the user clicks the button.
The easiest way to accept a command from a Web page is to write the function
first and then bind it to the button:
1. Create a Web page in an EGL Web project.
2. In the page’s JSF Handler, create a function. At this point, you only need the
basics of the function to do the binding; you can code the logic for the function
later.
3. Save the JSF Handler.
4. Open the associated JSP file.
5. From the Enhanced Faces Components drawer of the Palette view, drag a
Button - Command onto the page.
188 EGL Programmer’s Guide
6. In the Page Data view, expand JSF Handler. The functions and variables in the
JSF Handler are listed here.
7. From the Page Data view, drag the function directly onto the button that you
added to the page.
The function is bound to the button.
Alternatively, you can code the function from the Quick Edit view while working
on the Web page:
1. Open the JSP file.
2. From the Enhanced Faces Components drawer of the Palette view, drag a
Button - Command onto the page.
3. Right-click the button and then click Edit Events. The Quick Edit view opens.
Typically, this view is for JavaScript code, but you can use it to write functions
in the JSF Handler as well.
4. In the Quick Edit view, click Command at the left side of the view.
5. Click on the right area of the Quick Edit view to set focus there. The view
shows a new EGL function that is actually in the JSF Handler.
6. Type your EGL statements in the new function. You must at least add a
comment in the function in the Quick Edit view. If you do not change the code
in the function, the editor assumes that the function is not needed and removes
it.
Limitations
Command elements on the page can be bound only to functions in the JSF
Handler, not functions in other logic parts such as libraries. Also, you can bind
only functions with no parameters. If the function needs input to run, create a
variable in the JSF Handler and bind it to an input control on the page. Then, you
can use that variable as a parameter in a function invocation.
Also, see “Binding a control on a Web page to a variable” on page 190 for a
limitation having to do with the location of buttons and controls within a <form>
tag.
Related concepts
“Building EGL Web applications” on page 183In an EGL Web application, EGL logic parts control Web pages, enabling you to
put data on Web pages, get data from user input on Web pages, and forward
users from page to page. Related tasks
“Binding JSF controls to EGL variables and functions” on page 187When you have a JSP file and an associated JSF Handler part, you can begin
developing the Web page’s behavior. This means binding, or connecting,
elements on the Web page to variables and functions in the JSF Handler.
“Binding a control on a Web page to a variable” on page 190You can bind a variable in the JSF Handler to an input or output control on the
Web page. When a variable is bound to a control on the page and the user
changes the value in the control, the value of the variable changes to match,
and if the logic in the JSF Handler changes the value of the variable, the value
on the page changes to match.
“Binding a JSF single-select control to a variable” on page 194Binding a JSF single-select control, such as a combo box or group of radio
buttons, to an EGL variable is more complicated than binding an input or
Building EGL Web applications 189
output control because you must use two EGL variables: one for the options in
the control and one for the selected value.
“Returning the indexes of selected rows in a data table” on page 197
“Binding JSF controls to services” on page 200Binding functions and variables from a service to controls on a Web page is no
different from binding any other type of functions and variables, but EGL
provides shortcuts for working with service controls in this way.
Binding a control on a Web page to a variable
You can bind a variable in the JSF Handler to an input or output control on the
Web page. When a variable is bound to a control on the page and the user changes
the value in the control, the value of the variable changes to match, and if the logic
in the JSF Handler changes the value of the variable, the value on the page
changes to match.
There are several ways to bind Web page controls to EGL variables:
v Create the controls automatically from existing EGL variables.
v Create the controls yourself and explicitly bind variables to those controls.
v Create both the controls and the variables at the same time.
Creating JSF controls automatically from EGL variables
With this method, you create variables in the JSF Handler and then allow EGL to
create appropriate representations on the page.
1. Open the JSF Handler that is associated with the Web page. If you are looking
at the JSP file in the editor, you can open its JSF Handler by right-clicking the
page and then clicking Edit page code.
2. In the JSF Handler, define one or more EGL primitives, data items, or record
variables, and save the file. To be used on the Web page, the variables must be
directly within the JSF Handler part and not within any function in the part.
3. Open the JSP file.
4. In the Page Data view, expand JSF Handler. The variables that are defined in
the JSF Handler are listed here.
5. Drag the variable from the Page Data view directly onto the Web page.
Depending on the type of variable that you drag, the Insert Control or Insert
List Control window opens.
6. Click a radio button under Create controls for:
v If you want read-only output controls, select Displaying an existing record.
v If you want editable input controls, select Updating an existing record or
Creating a new record. In this context, the two options are equivalent.
This wizard treats all EGL variables as if they were records.
7. If you selected a record variable or more than one variable, select the check
boxes next to the controls or variables that you want to display. You can also
choose a type of control to represent the controls or variables from the Control
type column.
8. Click Finish.
The controls are added to the page, and they are automatically bound to the
variables that you dragged onto the page. You can check to see which variable a
JSF control is bound to by clicking the control to select it and then opening the
Properties view. The Value field tells you which variable the selected control is
bound to.
190 EGL Programmer’s Guide
Creating JSF controls and binding them manually
You can create your own controls and bind them manually to EGL variables. This
method is useful if you want to design the look of your page first and then add
data.
1. Open the JSF Handler associated with the Web page. If you are looking at the
JSP file in the editor, you can open its JSF Handler by right-clicking the page
and then clicking Edit page code.
2. In the JSF Handler, define one or more EGL primitive, data item, or record
variables and save the file. To be used on the Web page, the variables must be
directly within the JSF Handler part and not within any function in the part.
3. Open the JSP file.
4. From the Palette view, expand the Enhanced Faces Components drawer and
drag a control onto the Web page.
If you want the control to be read-only, use an output control, such as an
Output text control. If you want to make the control editable for input and
output, use an Input control. For records, use a Data Table control and create a
column in the data table for each field in the record.
5. In the Page Data view, expand JSF Handler. The variables defined in the JSF
Handler are listed here.
6. Drag the variable from the Page Data view directly onto the control on the Web
page, making sure to use appropriate controls for the EGL variable types. For
example, single primitive variables or data items can be bound to single input
or output controls. Arrays and records need to be bound to columns within a
data table.
Creating controls and variables at the same time
You can create controls and variables that are bound together at the same time
with the New Variable item in the EGL drawer of the Palette view.
1. In the Palette view, expand the EGL drawer.
2. Drag a New Variable onto the page. The Create a New EGL Data Variable
window opens.
3. Under Type Selection, select whether you want a primitive, data item, or
record variable. The rest of the options on the page differ depending on the
type of variable you choose.
4. Select the type of variable. For data items and records, choose a part from
your project. For primitive variables, choose a primitive type and specify a
dimension if appropriate.
5. Name the variable in the Enter the name of the field field.
6. If you want the variable to be an array, select the Array check box and specify
a starting length in the Size field.
7. Select Add controls to display the EGL element on the page.
8. Click OK. Depending on the type of variable, the Insert Control or Insert List
Control window opens.
9. Click a radio button under Create controls for:
v If you want read-only output controls, select Displaying an existing record.
v If you want editable input controls, select Updating an existing record or
Creating a new record. In this context, the two options are equivalent.
This wizard treats all EGL variables as though they were records.
Building EGL Web applications 191
10. If you selected a record variable with more than one field, select the check
boxes next to the fields that you want to display. You can also choose a type
of control to represent the fields or variables from the Control type column.
11. Click Finish.
Limitations
Binding controls to variables has limitations because of the way Web pages behave.
One major limitation is that the JSF Handler receives only the changed variables
from the form that is submitted on the Web page.
For example, assume the following JSF Handler with two variables and one
function:
handler formTestPage type JSFHandler
{view = "formTestPage.jsp"}
stringOne string;
stringTwo string;
function doSomething()
SysLib.writeStderr("stringOne = " + stringOne);
SysLib.writeStderr("stringTwo = " + stringTwo);
end
end
If you bind the function to a button and the variables to two input controls, you
can type values into the controls, press the button, and see the values that you
typed written to the console.
This example assumes that you have placed the button and controls in the same
HTML form. The code of the body of the Web page might look like this:
<body>
<hx:scriptCollector id="scriptCollector1"
preRender="#{formTestPage._preRender}"
postRender="#{formTestPage._postRender}">
<h:form id="form1" styleClass="form">
<h:inputText id="text1" styleClass="inputText"
value="#{formTestPage.stringOne}"
binding="#{formTestPage.stringOne_Ref}"></h:inputText>
<br>
<h:inputText id="text2" styleClass="inputText"
value="#{formTestPage.stringTwo}"
binding="#{formTestPage.stringTwo_Ref}"></h:inputText>
<br>
<hx:commandExButton id="buttonDoSomething1"
styleClass="commandExButton" type="submit" value="doSomething"
action="#{formTestPage.doSomething}"
actionListener="#{formTestPage._commandActionListener}">
</hx:commandExButton>
</h:form>
</hx:scriptCollector>
</body>
Note that the <h:form> tag surrounds both the button (represented on the page as
a commandExButton tag) and the two input controls (represented on the page as
192 EGL Programmer’s Guide
inputText tags). This way, when you click the button, both input controls are made
available to the JSF Handler; that is, the values typed into the input controls are
assigned to the variables in the handler.
However, if you put the controls on the page far apart, they might not be within
the same form tag:
<body>
<hx:scriptCollector id="scriptCollector1"
preRender="#{formTestPage._preRender}"
postRender="#{formTestPage._postRender}">
<h:inputText id="text1" styleClass="inputText"
value="#{formTestPage.stringOne}"
binding="#{formTestPage.stringOne_Ref}"></h:inputText>
<br>
<h:form id="form1" styleClass="form">
<h:inputText id="text2" styleClass="inputText"
value="#{formTestPage.stringTwo}"
binding="#{formTestPage.stringTwo_Ref}"></h:inputText>
<br>
<hx:commandExButton id="buttonDoSomething1"
styleClass="commandExButton" type="submit" value="doSomething"
action="#{formTestPage.doSomething}"
actionListener="#{formTestPage._commandActionListener}">
</hx:commandExButton>
</h:form>
</hx:scriptCollector>
</body>
In this case, the first input control is outside the form, but the second input control
and the button are within the form. When you click the button now, the JSF
Handler receives only the second control, and the variable bound to the first
control is not changed.
Related concepts
“Building EGL Web applications” on page 183In an EGL Web application, EGL logic parts control Web pages, enabling you to
put data on Web pages, get data from user input on Web pages, and forward
users from page to page. Related tasks
“Binding JSF controls to EGL variables and functions” on page 187When you have a JSP file and an associated JSF Handler part, you can begin
developing the Web page’s behavior. This means binding, or connecting,
elements on the Web page to variables and functions in the JSF Handler.
“Binding a JSF button to a function” on page 188When you bind a JSF button to a function in the JSF Handler, the function runs
when the user clicks the button.
“Binding a JSF single-select control to a variable” on page 194Binding a JSF single-select control, such as a combo box or group of radio
buttons, to an EGL variable is more complicated than binding an input or
output control because you must use two EGL variables: one for the options in
the control and one for the selected value.
“Returning the indexes of selected rows in a data table” on page 197
“Binding JSF controls to services” on page 200Binding functions and variables from a service to controls on a Web page is no
Building EGL Web applications 193
different from binding any other type of functions and variables, but EGL
provides shortcuts for working with service controls in this way.
Binding a JSF single-select control to a variable
Binding a JSF single-select control, such as a combo box or group of radio buttons,
to an EGL variable is more complicated than binding an input or output control
because you must use two EGL variables: one for the options in the control and
one for the selected value.
In general, you need to create an array that represents the options in the control, as
well as a single variable to hold the value of the selected option. The simplest way
to do this is by defining an array of strings and populating the array with the
options for the control. See ″Using an array of STRING as the selection options.″
Alternatively, you can use an array of records as the options for the control by
specifying fields in the record as the option that is displayed in the control and as
the value for the selection. See ″Using an array of records as the selection options.″
Using an array of STRING as the selection options
1. In a JSF Handler, create an array of strings to hold the options for the
single-select control:
selectionOptions string[4];
2. Assign values to the array. You can assign values dynamically or simply assign
literal values to the array:
selectionOptions string[4]
{"First choice", "Second choice",
"Third choice", "Fourth choice"};
3. Create a string variable to hold the selected option:
selectedChoice string;
4. Indicate that the single variable receives the option selected from the list of
options by adding the SelectedValueItem property to the list of options:
selectionOptions string[4]
{"First choice", "Second choice",
"Third choice", "Fourth choice",
SelectedValueItem = selectedChoice};
5. Save and generate the JSF Handler.
6. On the page that is associated with the JSF Handler, drag the variable that
represents the list of options (in this case, selectionOptions) from the Page
Data view onto the page. The Insert List Control window opens.
7. In the Insert List Control window, click Displaying an existing record.
8. Under Control Type, select the type of single-select JSF control to put on the
page.
You can choose from Combobox (also called a list box or drop-down box), List
Box - single select, or Radio Button Group. In each case, the options will be
added dynamically depending on the number of elements in the list of options
at run time.
9. Click Finish. The control is added to your page and it is automatically bound
to the variables in the JSF Handler.
You can check which variables the JSF control is bound to by clicking the control
to select it and then opening the Properties view. In the Properties view, the Value
field represents the variable that will receive the value of the selected option, and
the table of variables at the right side of the view lists the variable or variables that
are used to provide the options for the control.
194 EGL Programmer’s Guide
This is a complete example of a JSF Handler that uses a single-select control in this
way:
handler singleSelect type JSFHandler
{view = "singleSelect.jsp"}
selectionOptions string[4]
{"First choice","Second choice",
"Third choice","Fourth choice",
SelectedValueItem = selectedChoice};
selectedChoice string;
outputMessage string;
function getChoice()
outputMessage = "You chose: "
+ selectedChoice;
end
end
This example assumes that you have dragged the selectionOptions variable onto
the page and created a combo box, list box, or radio button group based on this
variable. You will also need to bind the outputMessage variable to an output
control and the getChoice function to a button on the page. When you click the
button, the output control displays the text of the option you selected in the JSF
single-select control.
Using an array of records as the selection options
The method of using an array of strings as the selection options is simple, but it
might not be the most convenient method. You might need to retrieve the options
from an array of records, or you might need to use one value for the option and
pass a different value to the selection result variable. In this case, use the
@SelectionList record property to indicate which fields in the record should be
used for the option and which should be used for the value of the selection.
To use an array of records as the selection options:
1. In a Record part, use @SelectionList to specify which field in the record
should be the selection option (the labelItem) and which field should be the
value of the option (the valueItem:
record optionsRec type BasicRecord
{@SelectionList {labelItem = displayOption,
valueItem = optionValue}}
displayOption string;
optionValue string;
end
The record can contain other fields, but you must select two of these fields to
be the label and the value.
2. In the JSF Handler, create an array that is based on this Record part:
selectionOptions optionsRec[3];
3. Assign values to the array. You can assign values dynamically or simply
assign literal values to the array. You might want to use the
onPreRenderFunction to set values for this array:
function onPreRender()
selectionOptions[1].displayOption = "Option one";
selectionOptions[1].optionValue = "first option";
selectionOptions[2].displayOption = "Option two";
Building EGL Web applications 195
selectionOptions[2].optionValue = "second option";
selectionOptions[3].displayOption = "Option three";
selectionOptions[3].optionValue = "third option";
end
4. Create a single variable to receive the selected option:
selectedChoice string;
The type of this variable must match the type of the field marked as
valueItem in the Record part.
5. Indicate that the single variable will receive the option that is selected from
the list of options by adding the SelectedValueItem property to the list of
options:
selectionOptions optionsRec[3]
{selectedValueItem = selectedChoice};
6. Save and generate the JSF Handler.
7. On the page that is associated with the JSF Handler, drag the variable that
represents the list of selection options (in this case, selectionOptions from the
Page Data view onto the page. The Insert List Control window opens.
8. In the Insert List Control window, click Displaying an existing record.
9. Under Control Type, select the type of single-select JSF control to put on the
page.
You can choose from Combobox (also called a list or drop-down box), List
Box - single select, or Radio Button Group. In each case, the options will be
added dynamically depending on the number of elements in the list of
selection options at run time.
10. Click Finish. The control is added to your page and it is automatically bound
to the variables in the JSF Handler.
You can check which variables the JSF control is bound to by clicking the control
to select it and then opening the Properties view. In the Properties view, the Value
field represents the variable that will receive the value of the selected option, and
the table of variables at the right side of the view lists the variable or variables that
are used to provide the options for the control.
This is a complete example of a JSF Handler that uses a single-select control in this
way:
handler singleSelect type JSFHandler
{view = "singleSelect.jsp",
onPreRenderFunction = onPreRender}
selectionOptions optionsRec[3]
{selectedValueItem = selectedChoice};
selectedChoice string;
outputMessage string;
function onPreRender()
selectionOptions[1].displayOption = "Option one";
selectionOptions[1].optionValue = "first option";
selectionOptions[2].displayOption = "Option two";
selectionOptions[2].optionValue = "second option";
selectionOptions[3].displayOption = "Option three";
selectionOptions[3].optionValue = "third option";
end
function getChoice()
outputMessage = "You chose: "
196 EGL Programmer’s Guide
+ selectedChoice;
end
end
record optionsRec type BasicRecord
{@SelectionList {labelItem = displayOption,
valueItem = optionValue}}
displayOption string;
optionValue string;
end
This example assumes that you have dragged the selectionOptions variable onto
the page and created a combo box, list box, or radio button group that is based on
this variable. You also need to bind the outputMessage variable to an output
control and the getChoice function to a button on the page. When you click the
button, the output control displays the text of the option that you selected in the
JSF single-select control.
Related concepts
“Building EGL Web applications” on page 183In an EGL Web application, EGL logic parts control Web pages, enabling you to
put data on Web pages, get data from user input on Web pages, and forward
users from page to page. Related tasks
“Binding JSF controls to EGL variables and functions” on page 187When you have a JSP file and an associated JSF Handler part, you can begin
developing the Web page’s behavior. This means binding, or connecting,
elements on the Web page to variables and functions in the JSF Handler.
“Binding a JSF button to a function” on page 188When you bind a JSF button to a function in the JSF Handler, the function runs
when the user clicks the button.
“Binding a control on a Web page to a variable” on page 190You can bind a variable in the JSF Handler to an input or output control on the
Web page. When a variable is bound to a control on the page and the user
changes the value in the control, the value of the variable changes to match,
and if the logic in the JSF Handler changes the value of the variable, the value
on the page changes to match.
“Returning the indexes of selected rows in a data table”
“Binding JSF controls to services” on page 200Binding functions and variables from a service to controls on a Web page is no
different from binding any other type of functions and variables, but EGL
provides shortcuts for working with service controls in this way. Related reference
Returning the indexes of selected rows in a data table
JSF provides the ability to include a ″selection column″ of check boxes in a data
table. With this column of check boxes, you can select one or more rows in the
table to perform a particular action on. For example, you might select several rows
for deletion.
You can set a specific arrangement of properties on an array of records to indicate
that the array should be displayed on a Web page with a selection column. Then
the user can select one or more of the check boxes. EGL indicates which rows were
selected by returning an array of integers that represent the indexes of the selected
rows. For example, if the check boxes for the first, third, and fourth rows in the
Building EGL Web applications 197
data table are selected, EGL sets the array of integers to [1,3,4]. EGL
automatically converts 0-based JSF arrays to 1-based EGL arrays.
In this way, to be able to select multiple rows in a JSF data table, you need two
arrays:
v An array of records that will be the data in the table
v An array of integers to hold the indexes of the selected records
This task has the following prerequisites:
v An EGL Web project with at least one Web page
v A Record part that you want to show on the Web page
Follow these steps to set up a data table with a multiple selection column. This
example displays a list of customers and their total purchases and enables you to
select one or more rows to add together:
1. In the JSF Handler for an EGL-controlled Web page, create an array of records
to represent the table of data you want shown on the page:
purchaseList customerPurchase[3];
This example uses the following sample Record part:
record customerPurchase type BasicRecord
custName string;
totalPurchases decimal(10,2);
end
2. Retrieve data to populate this array with the data that you want the user to
select on the page. The example later in this topic will assign literal values to
the array, but you can retrieve the data from a database or populate the array
in any other way. You might want to put this retrieval logic in the function
specified in the onPreRenderFunction property of the JSF Handler.
3. Create the array of integers that will hold the indexes of the selected records:
allSelectedRows int[0];
4. For the record variable, set the selectedRowItem property to the name of the
array that will hold the indexes of the selected records:
purchaseList customerPurchase[3]
{selectedRowItem = allSelectedRows};
5. On the Web page, drag the array of records from the Page Data view onto the
page. The Insert List Control window opens.
6. In the Insert List Control, select a radio button under Create controls for. If
you want read-only output controls, select Displaying an existing record. If
you want editable input controls, select Updating an existing record.
7. Click Finish. The records are displayed on the page as a JSF data table.
This table includes a small, unlabeled column that contains check box elements.
If you click the check box control to select it and go to the Properties view, you
can see that this check box is bound not to any fields in the record variable but
to the integer array that you defined to hold the indexes of the selected rows.
Now the integer array will hold the row numbers of the rows that are selected on
the Web page. You can define a function to process the selected records when a
user clicks a button on the page, for example:
For example, this JSF Handler uses a selection column in this way:
handler multiSelectPage type JSFHandler
{onPreRenderFunction = onPreRender,
view = "multiSelectPage.jsp"}
198 EGL Programmer’s Guide
//Array of customer records and their purchase amount
purchaseList customerPurchase[3]
{selectedRowItem = allSelectedRows};
//indexes of the selected rows
allSelectedRows int[0];
//Sum of selected purchases
purchaseSum decimal(10,2);
function onPreRender()
//initialize the array of customers
purchaseList[1].custName = "Company A";
purchaseList[1].totalPurchases = "500.23";
purchaseList[2].custName = "Company B";
purchaseList[2].totalPurchases = "232.55";
purchaseList[3].custName = "Company C";
purchaseList[3].totalPurchases = "499.12";
end
function sumRows()
purchaseSum = 0;
counter int = 0;
customerIndexToAdd int;
for (counter from 1 to allSelectedRows.getSize() by 1)
customerIndexToAdd = allSelectedRows[counter];
purchaseSum += purchaseList[customerIndexToAdd].totalPurchases;
end
end
end
record customerPurchase type BasicRecord
custName string;
totalPurchases decimal(10,2);
end
This example assumes that you have dragged the purchaseList array onto the
page to make a JSF data table and that you have bound the sumRows function and
purchaseSum variable to a command button and output control on the Web page,
respectively.
Related concepts
“Building EGL Web applications” on page 183In an EGL Web application, EGL logic parts control Web pages, enabling you to
put data on Web pages, get data from user input on Web pages, and forward
users from page to page. Related tasks
“Binding JSF controls to EGL variables and functions” on page 187When you have a JSP file and an associated JSF Handler part, you can begin
developing the Web page’s behavior. This means binding, or connecting,
elements on the Web page to variables and functions in the JSF Handler.
“Binding a JSF button to a function” on page 188When you bind a JSF button to a function in the JSF Handler, the function runs
when the user clicks the button.
“Binding a control on a Web page to a variable” on page 190You can bind a variable in the JSF Handler to an input or output control on the
Web page. When a variable is bound to a control on the page and the user
changes the value in the control, the value of the variable changes to match,
and if the logic in the JSF Handler changes the value of the variable, the value
on the page changes to match.
Building EGL Web applications 199
“Binding a JSF single-select control to a variable” on page 194Binding a JSF single-select control, such as a combo box or group of radio
buttons, to an EGL variable is more complicated than binding an input or
output control because you must use two EGL variables: one for the options in
the control and one for the selected value.
“Binding JSF controls to services”Binding functions and variables from a service to controls on a Web page is no
different from binding any other type of functions and variables, but EGL
provides shortcuts for working with service controls in this way. Related reference
Binding JSF controls to services
Binding functions and variables from a service to controls on a Web page is no
different from binding any other type of functions and variables, but EGL provides
shortcuts for working with service controls in this way.
This task has the following prerequisites:
v An EGL Web project and Web page.
v A service client binding. See “Adding service client binding information from a
WSDL file” on page 257 or “Adding service client binding information for an
EGL service” on page 259.
To bind functions and variables from a service to fields on a Web page:
1. Open the Web page in the editor.
2. From the EGL drawer of the Palette view, drag a Service onto the page. The
Add Service window opens, listing all the services for which you have
defined client bindings.
3. In the Add Service window, select the service that you want to use in the
Select a service list. The Select a function list shows the functions that are
available in this service.
4. Under Select a function, select the function that you want to use. You can
select more than one function by pressing and holding Ctrl and clicking the
functions.
5. Click Finish. The Page Data view now shows the service in its Services folder,
and variables and functions are added to the JSF Handler.
From this point you can add controls and buttons to the page just as in
“Binding a control on a Web page to a variable” on page 190 and “Binding a
JSF button to a function” on page 188, but the entry for the service in the
Services folder enables you to create all the controls that are needed for the
service at once.
6. From the Services folder of the Page Data view, drag the service onto the
page. The Insert Service window opens.
7. In the Function list, select a function to use on the page.
8. Under Fields to display, set the options for the input controls.
9. Click Next.
10. On the Results Form page, set the options for the output controls.
11. Click Finish.
The controls for input and output and buttons to invoke the function are added to
the page and bound to the corresponding variables and functions in the JSF
Handler.
Related concepts
200 EGL Programmer’s Guide
“Building EGL Web applications” on page 183In an EGL Web application, EGL logic parts control Web pages, enabling you to
put data on Web pages, get data from user input on Web pages, and forward
users from page to page. Related tasks
“Binding JSF controls to EGL variables and functions” on page 187When you have a JSP file and an associated JSF Handler part, you can begin
developing the Web page’s behavior. This means binding, or connecting,
elements on the Web page to variables and functions in the JSF Handler.
“Binding a JSF button to a function” on page 188When you bind a JSF button to a function in the JSF Handler, the function runs
when the user clicks the button.
“Binding a control on a Web page to a variable” on page 190You can bind a variable in the JSF Handler to an input or output control on the
Web page. When a variable is bound to a control on the page and the user
changes the value in the control, the value of the variable changes to match,
and if the logic in the JSF Handler changes the value of the variable, the value
on the page changes to match.
“Binding a JSF single-select control to a variable” on page 194Binding a JSF single-select control, such as a combo box or group of radio
buttons, to an EGL variable is more complicated than binding an input or
output control because you must use two EGL variables: one for the options in
the control and one for the selected value.
“Returning the indexes of selected rows in a data table” on page 197 Related reference
Navigating among Web pages with navigation rules
A JSF Handler can control the navigation on a Web site, forwarding the user from
one page to another and passing data between pages. EGL works closely with
JavaServer Faces (JSF) navigation functionality to control page navigation in this
way.
You can forward the user from one page to another at any time, but you must
know the name of the JSF navigation rule that points to the target page. By default,
the name of the navigation rule that points to a page is the same as the name of
the JSF Handler that manages that page.
For example, a page named myPage.jsp might have a JSF Handler named myPage
in a file named myPage.egl. By default, the navigation rule for this page is myPage.
When you know the navigation rule of the target page, you can use the EGL
forward statement to send the user’s Web browser to that target page. In this case,
to forward to the page myPage.jsp, use the following code:
forward to "myPage";
To find the navigation rule that points to a page, look in the faces-config.xml file,
which is in the WebContent/WEB-INF folder of your EGL Web project. This file lists
the rules and the pages to which those rules lead. The previous example used a
navigation rule that looks like this:
<navigation-case>
<from-outcome>myPage</from-outcome>
<to-view-id>/myPage.jsp</to-view-id>
</navigation-case>
Building EGL Web applications 201
To avoid introducing errors into the JSF configuration, you should either use the
default rules or create new rules instead of modifying the default rules. More
information on navigation rules is available in the JSF help topics.
You can also use forward to send the user to another Web page by specifying the
complete URL of the page:
forward to URL "http://www.ibm.com";
When forwarding to another page controlled by an EGL JSF Handler, be sure to
use the correct extension of .faces or .jsp, as explained in “Running a Web page
on a server” on page 235.
Related reference
“Forwarding data between Web pages”You can use the forward statement to pass data from one Web page to another
when you transfer control.
Forwarding data between Web pages
You can use the forward statement to pass data from one Web page to another
when you transfer control.
See “Navigating among Web pages with navigation rules” on page 201 for
information on forwarding to a different Web page.
Follow these steps to pass data between two Web pages:
1. In the page that will receive the data, set the functions defined in the JSF
Handler properties onConstructionFunction, onPreRenderFunction, and
onPostRenderFunction to receive the parameters, just like any other function
would receive parameters.
For example, the following JSF Handler is set to receive an integer and a
character parameter:
handler myPage type JSFHandler
{onPreRenderFunction = onPreRender,
view = "myPage.jsp"}
function onPreRender(myIntVariable int, myCharVariable char(100))
end
end
If you define more than one of these JSF Handler properties, the specified
functions must have matching parameters because all functions receive the
passed data. However, you can leave the parameters out of the functions if you
do not plan to use the passed data in that function.
2. In the page that forwards the data, use a forward statement and include the
data in the same order as the functions that will accept it:
myInteger int = 5;
myChar char(100) = "Hello";
forward myInteger, myChar to "myPage";
The variables must be separated by commas, and their types must be
compatible with the types defined in the functions of the target page. Related reference
“Navigating among Web pages with navigation rules” on page 201A JSF Handler can control the navigation on a Web site, forwarding the user
202 EGL Programmer’s Guide
from one page to another and passing data between pages. EGL works closely
with JavaServer Faces (JSF) navigation functionality to control page navigation
in this way.
“Executing commands when a page loads”A JSF Handler can include functions that run automatically when the page
loads.
Executing commands when a page loads
A JSF Handler can include functions that run automatically when the page loads.
The JSF Handler properties onPreRenderFunction, onPostRenderFunction, and
onConstructionFunction allow you to specify functions that run at different points
in the page’s life cycle.
When these functions run depends on the value of the scope property of the page.
When the user visits an EGL-controlled Web page for the first time, EGL loads the
JSF Handler, which is represented at run time by a page bean. If the scope of the
page is set to session (the default), the bean remains active during the user’s
session, even if the user browses away from the page. If the user returns to the
page, the bean is still available. If the scope of the page is set to request, the bean
does not remain active when the user browses away from the page. In this case,
any data stored in the bean is lost, and the bean must be loaded again if the user
returns to the page.
v The function that is specified in the onConstructionFunction property runs
when the page bean is loaded. Therefore, for pages set to session scope, this
function runs only the first time that the user visits the page. For pages set to
request scope, this function runs each time the user visits the page, because the
bean is recreated each time, except when the page is redisplayed due to a JSF
validation error.
However, if the cancelOnPageTransition property of the JSF Handler is set to
yes, the page bean is removed from the session when the user moves to another
page, even if the scope property is set to session. In this case, the
onConstructionFunction runs again when the user returns to the page because
the page bean must be reloaded.
This function is useful for one-time initialization tasks. You should not use
onConstructionFunction to retrieve session variables or other data that may
change and need to be loaded again when the page is refreshed. Use
onPreRenderFunction instead. See ″onConstructionFunction″ in the EGL
Language Reference for more detail on this property.
v The function that is specified in the onPreRenderFunction property is not
affected by the scope of the page. This function runs each time the server begins
rendering the page, whether the bean was in the user’s session or not. In this
way, the onPreRenderFunction runs the first time the page bean is loaded,
whenever the user refreshes the page, whenever another page directs the user to
this page, and whenever the page is redisplayed due to a JSF validation error.
v The function that is specified in the onPostRenderFunction property is similar
to the onPreRenderFunction, but it runs every time the server finishes rendering
the page. This function runs the first time the page bean is loaded, whenever the
user refreshes the page, whenever another page directs the user to this page, and
whenever the page is redisplayed due to a JSF validation error.
If you specify more than one of these properties, be aware of the following:
Building EGL Web applications 203
v The function that is specified in the onConstructionFunction property runs
before the function that is specified in the onPreRenderFunction property if
both are defined.
v If the functions accept parameters, the parameters must match. Alternatively,
you can define parameters in one function but not in another.
v You can specify the same function for more than one of these properties, but
this means that the function might run more than once.
The following example of a JSF Handler illustrates the use of two of these
functions:
1. In an EGL Web project, create a new Web page named loadTest.jsp.
2. Open the JSF Handler of the new page by right-clicking the open page in the
editor and then clicking Edit Page Code.
3. Change the code in the JSF Handler to match this example:
package jsfhandlers;
handler loadTest type JSFHandler
{onConstructionFunction = onConstruction,
onPreRenderFunction = onPreRender,
scope = session,
view = "loadTest.jsp"}
numberOfLoads int;
messageString string;
function onConstruction()
numberOfLoads = 0;
end
function onPreRender(incomingNumber int)
numberOfLoads = incomingNumber + 1;
messageString = "You have viewed this page "
+ numberOfLoads + " times.";
end
function forwardBack()
forward numberOfLoads to "loadTest";
end
end
4. Save the JSF Handler and close it.
5. On the loadTest.jsp page, add an Output field from the Enhanced Faces
Components drawer of the Palette view.
6. Next to the output field, add a Button - Command from the Enhanced Faces
Components drawer of the Palette view.
7. From the Page Data view, drag messageString directly onto the output field.
Now the variable in the JSF Handler is bound to the output field on the page.
8. From the Page Data view, drag forwardBack() directly onto the command
button. Now the button is bound to the function in the JSF Handler.
9. Save the page and generate the project.
10. Run the page on a server.
The first time that you run this page, it displays ″You have viewed this page 1
times.″ In this case, the function specified in the onConstructionFunction property
runs first and sets the numberOfLoads variable to zero. Then, the function specified
in the onPreRenderFunction property runs, sets the variable to 1, and sets the
message string variable to ″You have viewed this page 1 times.″ Each subsequent
204 EGL Programmer’s Guide
time you reload the page, the variable will increase by one, demonstrating that the
onPreRenderFunction function is running each time, but the
onConstructionFunction function is not.
If you try the example with scope set to request, the variable will never exceed 1
because the onConstructionFunction function sets the variable to zero each time
you refresh the page. Remember to save your changes to the JSF Handler, generate,
and republish the project to the server.
For more information, see the topics dedicated to these properties.
Retrieving the value of a clicked row in a data table
The getClickedRowValue snippet in the EGL drawer of the Snippets view is a
function that retrieves the hyperlinked value of a clicked row in a data table.
This snippet must be placed in an EGL JSF Handler part. This snippet has the
following prerequisites:
1. The JSP page has a data table.
2. The names of the JSP identifiers have not been changed from the default.
3. The page is defined as request in scope in faces-config.xml, not session.
To insert and configure this snippet, follow these directions:
1. In a JSF Handler, define a character or string variable to receive the clicked
value.
2. Place the cursor on a blank line in the JSF Handler where it is legal to add a
function. (This snippet includes an entire EGL function.)
3. In the EGL drawer of the Snippets view, double-click the Get clicked row
value snippet. The Insert Template window opens. For more information, see
Inserting EGL code snippets.
4. In the Insert Template window, type the name of the variable as the value of
the receivingVar variable.
5. Click Insert.
6. From the Enhanced Faces Components drawer in the Palette view, add a
command hyperlink to a field in the data table.
7. For the target of the command hyperlink, specify the name of the JSP page. The
hyperlink links to its own page.
8. Add a parameter to the hyperlink and give that parameter the same name as
the variable in the JSF Handler that receives the clicked value.
9. On the All tab of the Properties view, set the action property to the getVal()
function.
The code that is inserted by this snippet follows:
function getVal()
javaLib.store((objId)"context",
"javax.faces.context.FacesContext",
"getCurrentInstance");
javaLib.store((objId)"root",
(objId)"context", "getViewRoot");
javaLib.store((objId)"parm",
(objId)"root",
"findComponent",
"form1:table1:param1");
recVar = javaLib.invoke((objId)"parm",
"getValue");
end
Building EGL Web applications 205
Related concepts
“Code snippets” on page 138Snippets are code objects that are reusable programming objects. Snippets can
be a piece of code or a complete programming task. In addition to the default
snippets provided in the workbench, you can create your own snippets. Related tasks
“Inserting code snippets into EGL and JSP files” on page 139
Setting the focus to a form field
The Set cursor focus snippet in the EGL drawer of the Snippets view is a
JavaScript function that sets the cursor focus to a specified form field on a Web
page. It must be placed within a <script> tag in a JSP page.
To insert and configure this snippet:
1. Add a <script> tag within the <head> tag of the JSP file as in this example:
<script type="text/javascript">
<!-- snippet code goes here -->
</script>
2. From the EGL drawer of the Snippets view, drag the Set cursor focus snippet
to a blank line within the <script> tag you just added. For more information,
see Inserting code snippets into EGL and JSP files. This snippet goes into the code
of the JSP file, not the code of the JSF Handler part.
3. In the snippet code, replace both instances of [n] with the number of the form
field which will receive focus. The form fields are numbered beginning with
zero. For example, use [3] to set focus to the fourth field on the page.
4. In the snippet code, replace both instances of form1 to the value of the ID
attribute of the form to which you want to set focus.
5. In the <body> tag of the JSP page, add the attribute onload="setFocus();" as in
the following example:
<body onload="setfocus();">
6. Save the file.
The code inserted by this snippet is as follows:
function setFocus() {
document.getElementById(’form1’).elements[n].select();
document.getElementById(’form1’).elements[n].focus();
}
Related concepts
“Code snippets” on page 138Snippets are code objects that are reusable programming objects. Snippets can
be a piece of code or a complete programming task. In addition to the default
snippets provided in the workbench, you can create your own snippets. Related tasks
“Inserting code snippets into EGL and JSP files” on page 139
Displaying error messages on Web pages
JSF Web pages can include error messages to provide feedback, usually to notify
the user of a problem on the page. With the sysLib.setError and
sysLib.setErrorForComponentID system functions, you can set the value of these
error message components from the page’s JSF Handler.
206 EGL Programmer’s Guide
JSF pages use two types of error message components:
v The display error component displays a message that relates to a specific input
component on the page. For this reason, this type of component must specify the
ID of an input component on the page. The display error component is
represented by an <h:message> JSF tag, and the ID of the input component for
which it provides feedback is specified in its for attribute.
v The display errors component can behave in one of two ways:
– It combines all of the error messages from the display error components on
the page and adds any error messages not associated with a specific
component.
– It displays only the error messages not associated with a specific component.
A JSF Handler can set the value of error message components in these ways:
v The sysLib.setError system function sets the message of a display error
component, given the name of a variable that is bound to an input component
on the page. In other words, you pass the name of an EGL variable in the JSF
Handler to the function, and JSF finds the display error component that is
associated with an input component on the page, which in turn to that specified
EGL variable.
v The sysLib.setErrorForComponentID function sets the message of a display
error component, given the ID of an input component on the page. JSF shows
the error message in the display error component associated with the specified
input component.
Follow these steps to display an error message on a Web page with EGL:
1. As described in “Creating a resource bundle” on page 217, create a resource
bundle to hold the error messages. In short, you will create a file named in
the following format:
prefix_locale.properties
prefix
The prefix of the resource bundle file name is arbitrary, but the prefix
must be the same for each resource bundle in the application.
locale
The locale of the resource bundle, such as en_US. The locale identifies the
language of the strings in the bundle and, optionally, more specific
information about the specialization of the language, such as the dialect,
variety, or geographic location. For more information on locales, see
“Locales for resource bundles” on page 218.
For example, a resource bundle that contains English as it is spoken in the
United States might be named resourceBundle_en_US.properties.
Then, add messages to the file in the format keyname=messageText, such as
this:
error01=The specified value is too short.
Optionally, you can include inserts in the message. Inserts are represented by
an integer in braces and will be replaced with a value you specify when you
display the error message. Error messages can contain several inserts per
message, numbered such as {0}, {1}, and {2}.
With one insert, the error message in the resource bundle might look like this:
error02=The specified value is shorter than five characters: {0}
Building EGL Web applications 207
2. On a Web page in an EGL Web project, create an input component, such as an
input text component. You can use JSF display errors only with input
components.
3. Bind the input component to a variable in the JSF Handler associated with the
page.
4. Optionally, set the ID of the component to a meaningful mnemonic by clicking
the component to select it and typing the ID in the Id field of the Properties
view.
5. From the Palette view, drag a Display Error component onto the page. You
should put the display error component near the input component so it will
be clear which component is associated with the error message.
6. Click the display error component to select it.
7. In the Properties view, under Display error message for the component, set
the Id field to the ID of the input component.
At this point, the code of the Web page shows that the error message is
associated with the input component. In the following example, note that the
for attribute of the display error component is set to the value of the input
component’s id attribute:
<h:inputText id="inputComponent"
styleClass="inputText"
value="#{errorMessageTest.inputString}"
binding="#{errorMessageTest.inputString_Ref}">
</h:inputText>
<h:message id="message1"
styleClass="message"
for="inputComponent">
</h:message>
8. Save the page.
9. In the JSF Handler associated with the page, set the msgResource JSF Handler
property to the prefix of the resource bundle (that is, the file name excluding
the extension and the locale code):
handler errorMessageTest type JSFHandler
{view = "errorMessageTest.jsp",
msgResource = "resourceBundle"}
In this case, the resource bundle is named resourceBundle_en_US.properties
and so the msgResource property is set to resourceBundle.
10. Use the sysLib.setError or sysLib.setErrorForComponentID system function
to set the error message, using one of the following methods:
v If you want to use a string specified in the JSF Handler as the text of the
error message, pass these three parameters in order:
a. The unquoted name of the EGL variable in the JSF Handler. For a field
within a record, specify the record name, a period, and the field name,
as in myRecord.myField.
b. An empty string. You pass an empty string as the second parameter
because this parameter is used as the key of a message in an external
error message file.
c. The text of the error message as a string.
Following is an example of this method:
SysLib.setError(inputString, "",
"This is the text of the error message.");
208 EGL Programmer’s Guide
v If you want to use an error message in a resource bundle with zero or one
inserts, pass these three parameters in order:
a. The unquoted name of the EGL variable in the JSF Handler. For a field
within a record, specify the record name, a period, and the field name,
as in myRecord.myField.
b. The quoted key of the message in the resource bundle.
c. If the message expects an insert, the value to be used in that insert. This
parameter must be compatible with the STRING type.
For example, if you want to issue an error related to the variable
inputString, using an error message with the key error02 and the same
variable as an insert value, you would use this EGL code:
SysLib.setError(inputString, "error02", inputString);
This example assumes a resource bundle with a message definition similar
to this example:
error02=The specified value is shorter than five characters: {0}
v If you want to use an error message in a resource bundle with two or more
inserts, you must use sysLib.getMessage in coordination with
sysLib.setError, because sysLib.setError supports error messages with only
zero or one insert:
a. Set the userMessageFile build descriptor option to the prefix of the
resource bundle file name, the same value as you set in the
msgResource JSF Handler property.
b. Use sysLib.getMessage to put the inserts into the message and create a
string containing the complete message:
errorMessageString string =
sysLib.getMessage("error03", [inputString, "five"]);
c. Pass the error message string to sysLib.setError:
SysLib.setError(inputString, "", errorMessageString);
This example assumes an error message in the resource bundle with two
inserts, as in this example:
error03=The string {0} is too short.
It must be at least {1} characters long.
v In most cases, you will use sysLib.setError to set the error message, since it
is usually more convenient to use the EGL variable name as the reference
point for the error message. However, if you know the ID of the input
component with which you want to associate the error message, you can
use sysLib.setErrorForComponentID in a way similar to sysLib.setError,
except that sysLib.setErrorForComponentID takes the quoted identifier of
the input component, consisting of the ID of the form on the page, a colon,
and the ID of the input component, rather than the name of the EGL
variable:
SysLib.setErrorForComponentId("form1:inputComponent",
"error01", inputString);
This example assumes an input component on the page with the ID
inputComponent and a display error component associated with it. It also
assumes a message in the resource bundle with a key error01, similar to
the previous examples.
Building EGL Web applications 209
v If you want to display the error message on the display errors component,
rather than a display error component associated with a specific input
component, pass the error message to sysLib.setError without specifying a
variable name:
SysLib.setError("The string is too short.");
For example, the following JSF Handler tests a value typed into an input
component on a Web page to see if the value is long enough. If the value is too
short, the JSF Handler displays an error message.
handler errorMessageTest type JSFHandler
{view = "errorMessageTest2.jsp",
msgResource = "resourceBundle"}
inputString string;
function validateString()
if (StrLib.characterLen(inputString) < 5)
SysLib.setError(inputString, "error02", inputString);
end
end
end
This example assumes that the inputString variable is bound to an input
component on the associated Web page which is associated with an error message
component, as explained above. Also, it assumes a resource bundle named
resourceBundle_locale.properties, where locale is the locale code of the language
you are using. The example uses a message in that resource bundle file similar to
the following:
error02=The specified value is shorter than five characters: {0}
JSF can also set the values of error message components as part of user input
validation.
Updating a row in a relational table
The database update snippet in the EGL drawer of the Snippets view is a function
that updates a single row of a relational table when passed a record from a JSF
Handler. This snippet is intended to be placed in an EGL library.
To insert and configure this snippet:
1. In the EGL editor, place the cursor where you want the snippet to go. Because
this snippet is a complete EGL function, the cursor must be placed where a
function is legal.
2. In the EGL drawer of the Snippets view, double-click the database update
snippet. The Insert Template window opens.
3. In the Insert Template window, set the value of TableName to the name of the
table you are updating.
4. Set the value of KeyColumn to the primary key column of the table.
5. Click Insert.
6. Save the file.
This snippet inserts the following code:
Function updateRec(EGL_RecordNameNew EGL_RecordName)
//Function name - call this function passing
//the EGL_RecordName Record as a parameter
EGL_RecordNameOld EGL_RecordName; //A copy of the Record,
210 EGL Programmer’s Guide
//used to lock the table row, and obtain the existing row values
//prior to update
try
EGL_RecordNameOld.Table_Key_column_ID
= EGL_RecordNameNew.Table_Key_column_ID;
get EGL_RecordNameOld forUpdate; //Get the existing row.
//Note that if you had custom processing to do,
//you would insert after this call
move EGL_RecordNameNew to EGL_RecordNameOld byName;
//Move the updated values to the copy-row
replace EGL_RecordNameOld; //And replace the row in the database.
sysLib.commit(); //Commit your changes to the Database
onException (ex AnyException) //If the update fails...
sysLib.rollback(); //cancel all database updates
//(assuming this is permitted by your database)
// and call a custom error handling routine or something
end
end
Related concepts
“Code snippets” on page 138Snippets are code objects that are reusable programming objects. Snippets can
be a piece of code or a complete programming task. In addition to the default
snippets provided in the workbench, you can create your own snippets. Related tasks
“Inserting code snippets into EGL and JSP files” on page 139
Storing data in the user’s session
Web applications are considered stateless because they do not automatically save
information about a user’s interaction with the application. If the application needs
to remember details about the user’s actions, it must explicitly store that
information somewhere.
Web applications often store these details in the user’s session object, an area of
memory on the server that stores temporary information about one user’s
transactions and interaction with the Web application. The data in the session
object is not as stable as data stored in a database because the session object is lost
if the session ends. Still, putting data in the session object is useful in the short
term if done efficiently.
When a user visits an EGL-controlled Web page, the server loads the page’s JSF
Handler, represented at run time as a page bean, stores that bean in the session
object as a session variable, and uses that bean to provide the logic for the page. If
the scope property of the JSF Handler is set to session and its
cancelOnPageTransition property is set to no, the bean remains in the session
object until the session ends or the bean times out. In this way, variables in the
Handler can retain their values during the session, even if the user moves to
another page.
However, page beans can take up large amounts of memory. A much more efficient
way to use the session object (and, in turn, server resources) is to store the user’s
information in your own smaller session variables and then remove the beans from
the session object by setting the scope of the JSF Handlers to request or
cancelOnPageTransition to yes. In this way, you retain only the data the
application needs, not all the variables in its Handlers.
Building EGL Web applications 211
Setting and retrieving session variables
To set a session variable, pass a string identifier and an EGL variable to the session
object:
myVar string = "Hello";
J2EELib.setSessionAttr("mySessionVar", myVar);
To retrieve the value later, use the J2EELib.getSessionAttr system function with
the same identifier and a new variable:
myVarFromSession string;
J2EELib.getSessionAttr("mySessionVar", myVarFromSession);
A more complete example of two JSF Handlers that set and retrieve a session
variable follows. The first Handler sets the session variable:
package jsfhandlers;
handler sessionPageOne type JSFHandler
{scope = request,
view = "sessionPageOne.jsp"}
userRecord sessionRecord;
function storeAndForward()
J2EELib.setSessionAttr("mySessionRecord",
userRecord);
forward to "sessionPageTwo";
end
end
record sessionRecord type BasicRecord
userName string;
idNumber int;
end
This example assumes a Web page named sessionPageOne.jsp with two input
fields bound to the fields in the record, along with a command button bound to
the storeAndForward function. When the user clicks the button bound to the
storeAndForward function, the record is added to the user’s session variable, and
the user is forwarded to another page, represented by the following JSF Handler:
package jsfhandlers;
handler sessionPageTwo type JSFHandler
{view = "sessionPageTwo.jsp",
onPreRenderFunction = onPreRender}
submittedRecord sessionRecord;
function onPreRender()
J2EELib.getSessionAttr("mySessionRecord",
submittedRecord);
end
end
Like the previous Handler, this example assumes that you have bound the fields in
the record to output variables on the sessionPageTwo.jsp page. This Handler
retrieves the data from the session variable and assigns it to a variable for
temporary use within the JSF Handler.
212 EGL Programmer’s Guide
Clearing session variables
You can remove a single session variable from the session object by passing the
string identifier of the variable to the J2EELib.clearSessionAttr function:
J2EELib.clearSessionAttr("mySessionRecord");
Also, you can remove all EGL-controlled session variables from the user’s session
object with the J2EELib.clearEGLSessionAttrs function.
For more information on session-related functions, see ″EGL library j2eeLib″ in the
EGL Language Reference.
Testing browsers for a session variable
The Auto redirect snippet in the JSP drawer of the Snippets view tests for the
presence of a session variable. If the session variable is not present, the customized
code forwards control to a different Web page.
The snippet must be placed within the <head> tag of a JSP page after the
<pageEncoding> tag.
To insert and configure this snippet:
1. From the EGL drawer of the Snippets view, drag the Auto redirect snippet to a
blank line in the JSP file within the <head> tag of the page. This snippet goes
into the code of the JSP file, not the code of the JSF Handler part. For more
information, see Inserting code snippets into EGL and JSP files. The Insert
Template window opens.
2. In the Insert Template window, set the SessionAttribute variable to the name
of the session variable that is being tested. The default value is UserID. See
“Storing data in the user’s session” on page 211.
3. Set the ApplicationName variable to the name of your project or application.
The default value is EGLWeb.
4. Set the PageName variable to the name of the page that the browser will be
redirected to if the session variable is absent. The default value is Login.jsp.
5. When you have customized the values in the Insert Template window, click
Insert.
6. Save the file.
The code inserted by this snippet is as follows:
<%
if ((session.getAttribute("userID") == null ))
{
String redirectURL =
"http://localhost:9080/EGLWeb/faces/Login.jsp";
response.sendRedirect(redirectURL);
}
%>
Related concepts
“Code snippets” on page 138Snippets are code objects that are reusable programming objects. Snippets can
be a piece of code or a complete programming task. In addition to the default
snippets provided in the workbench, you can create your own snippets. Related tasks
“Inserting code snippets into EGL and JSP files” on page 139
“Storing data in the user’s session” on page 211
Building EGL Web applications 213
Localizing text in Web applications
You can localize your Web application so that the Web pages will display in
different languages. To localize a Web application, you must create a resource bundle
for each language that you want to support. These resource bundles contain strings
to be presented on the Web pages at run time. Each resource bundle is specific to a
human language, so that when you switch to a different resource bundle, the
strings on the Web pages switch to a different language.
You can use translatable strings as the text on Web pages. The sections below cover
some different uses of these strings on web pages. Also, you can use translatable
strings as the error messages for Web pages; see “Displaying error messages on
Web pages” on page 206.
Using translatable strings as output fields
To use a translatable string as the value of a JSF field, such as an output field, you
cannot assign the key of the translatable string to an EGL variable bound to the
field. To use a translatable string as the value of a JSF field, you cannot bind that
field to an EGL variable at all. Instead, you must bind the field to the translatable
string directly, as in these steps:
1. On a JSP file in your EGL Web project, drag onto the page a JSF output
component, such as an output field, from the Enhanced Faces Components
drawer of the Palette view .
2. Click the field to select it.
3. In the Properties view, find the Value field. This field shows the text for the
component.
4. Next to the Value field, click the Select Page Data Object button. The Select
Page Data Object window opens. Typically, you select a variable from your
JSF Handler from this window, but in this case you will use a string from a
resource bundle instead.
5. Go to the String Resource tab.
6. Click Add Properties File.
7. In the Choose/Create Properties File window, select the resource bundle file
that you want to use on the Existing File tab, or go to the New File tab to
create a new resource bundle. In either case, adhere to the naming and
placement conventions explained in “Creating a resource bundle” on page
217.
8. After you have selected or created a resource bundle file, enter a mnemonic to
represent the file in the File identifier field. By default, this mnemonic is
labels, but if you change it, it must match the mnemonic set in the EGL Page
Designer preferences as explained in “Setting preferences for Web projects” on
page 246.
9. Click OK to close the Choose/Create Properties File window. The table on the
String Resource tab shows the strings from the file. You can use the strings
that are already there or add new strings with the Add Resource button.
10. Select the string that you want to use on the field and click OK. The field
shows the key of the translatable string. When you run the page, the server
will use the string as the value of the field.
Using translatable strings in EGL properties
You can also use translatable strings as the values of certain EGL properties, most
notably DisplayName:
214 EGL Programmer’s Guide
1. In the jsfhandlers package of your project’s JavaSource folder, create a
resource bundle to hold the strings that you want to use in the application. See
“Creating a resource bundle” on page 217. For example, if you are using
American English, you might create a resource bundle named
myBundle_en_US.properties.
2. In the resource bundle, add keys and string values for the text that you want to
use on the Web pages, as in this example:
myString01=Hello there!
myString02=Welcome to my Web page.
3. Set your workbench preferences to use a default mnemonic to represent the
resource bundle:
a. Click Window → Preferences.
b. In the Preferences window, expand EGL and click Page Designer.
c. In the Loadbundle variable field, type a mnemonic for the translatable
strings. By default, this mnemonic is labels, but if you change it, it must
match the mnemonic that is used in the File identifier field in the
Choose/Create Properties File window as explained earlier.
d. Click OK.4. In the JSF Handler for the Web page, set the DisplayName or Help properties
of a variable to the key that represents the text that you want to use on the
Web page:
myFieldString string {DisplayUse = button,
DisplayName = "%myString01",
Action = "DoSomething"};
Note the percent sign (%) in the value of DisplayName. This symbol indicates
that the value comes from the given key in the resource bundle.
5. On the JSP that is associated with the JSF Handler, drag the variable onto the
page. For example, if you drag the variable in the previous example onto a
page, the code created in the JSP is as follows:
<hx:commandExButton id="buttonMyFieldString1"
styleClass="commandExButton" type="submit"
value="#{labels.myString01}"
actionListener="#{testResourceBundle._commandActionListener}"
action="DoSomething"></hx:commandExButton>
Note that the value of the button is not the name of the variable or the value of
the variable, but a string from the resource bundle, composed of the mnemonic
that you entered in the preferences plus the key that you used in the JSF
Handler.
An alternate method for using the translatable strings on the page is to define a
JSF Handler part without an associated page and then allow EGL to create the
page based on the variables in the Handler. See ″Creating a page from an
existing JSF Handler part″ in “Creating a Web page” on page 186. If you use
this method, you can also use a translatable string for the title property of the
JSF Handler, and when EGL creates the page, that string will appear
prominently at the top of the page.
6. In the code of the JSP, add the following line of code, directly below the code
<f:view>:
<f:loadBundle basename="myBundle" var="labels"/>
7. Set the values of the basename and var attributes to the prefix of your resource
bundle and the mnemonic, respectively. This example assumes that your
resource bundles are named myBundle_locale.properties and that you used
the default mnemonic labels.
Building EGL Web applications 215
This code specifies that the translatable strings represented on the page as
labels.keyname are found in the resource bundle files named with the prefix
myBundle. The basename attribute of this tag specifies the prefix of the resource
bundle file name, and the var attribute specifies the start of the translatable
string used in the code.
Using translatable strings for different languages at run time
To use translatable strings for different languages at run time:
1. Create one resource bundle for each language that your application supports.
The file name of each resource bundle in the application must have the same
prefix. If the name of your first resource bundle is myBundle_en_US.properties,
the names of the other resource bundles must begin with myBundle.
2. In the Project Explorer view, double-click the file faces-config.xml to open it.
This file is found in the folder WebContent/WEB-INF.
3. Within the <application> tag of the faces-config.xml file, add a
<locale-config> tag:
<faces-config>
<application>
<locale-config>
</locale-config>
...
</application
</faces-config>
4. Within the <locale-config> tag, add a <default-locale> tag that contains the
locale of the default resource bundle. For example, if you want your application
to appear in German if the user does not specify a locale or specifies a locale
that you application does not support, add the following code within the
<locale-config> tag:
<default-locale>de</default-locale>
It is good practice to specify a default locale, but it is not required.
5. Following the <default-locale> tag, add a <supported-locale> tag for each
locale that your application supports. For example, if your application supports
American English, add the following code within the <locale-config> tag:
<supported-locale>en_US</supported-locale>
Following is an example from an application that supports several locales:
<faces-config>
<application>
<locale-config>
<default-locale>de</default-locale>
<supported-locale>en_US</supported-locale>
<supported-locale>es</supported-locale>
<supported-locale>de</supported-locale>
<supported-locale>fr_FR</supported-locale>
<supported-locale>it_IT</supported-locale>
<supported-locale>pt_br</supported-locale>
</locale-config>
...
</application>
</faces-config>
If you define a default locale, you must also define that locale as a supported
locale.
Note: Each locale that is defined in this file must have a matching resource
bundle defined for that locale.
216 EGL Programmer’s Guide
6. Save and close the file.
7. Test your application with your Web browser set to different languages to see
the different strings. Related concepts
“Locales for resource bundles” on page 218 Related tasks
“Customizing runtime messages” on page 127
“Creating a resource bundle”
Creating a resource bundle
A resource bundle contains a series of strings to be presented at run time. With
resource bundles, you can localize your applications by including a different
resource bundle for each language that you want to support.
Each resource bundle must define a string for each key that is used in the
application. If a Web page lists a key and the resource bundle for the current user’s
language does not define a string for that key, a fatal error will be generated.
To create a resource bundle:
1. In the Project Explorer view, right-click the folder in which you want to create
the resource bundle. This folder must be within the JavaSource folder of an
EGL Web project.
2. From the menu, click New → Other. The New window opens.
3. In the New window, expand General and click File.
4. Click Next.
5. In the File name field, type a name for the new resource bundle. The file name
of the resource bundle must be in this format:
prefix_locale.properties
prefix
The prefix of the resource bundle file name is arbitrary, but the prefix must
be the same for each resource bundle in the application.
locale
The locale of the resource bundle, such as en_US. The locale identifies the
language of the strings in the bundle and, optionally, more specific
information about the specialization of the language, such as the dialect,
variety, or geographic location. For more information on locales, see
“Locales for resource bundles” on page 218.
For example, a resource bundle that contains English as it is spoken in the
United States might be named resourceBundle_en_US.properties.
6. Click Finish.
The new file is created in the folder that you right-clicked, and the new file
opens in the editor.
7. Add strings to the new resource bundle in the following format:
keyname=stringtext
keyname
The key name of the string. This key is placed in the Web pages to indicate
which text from the resource bundle to insert. For example, a key named
WelcomeText might indicate introductory text to be shown at the top of a
page.
Building EGL Web applications 217
stringtext
The text that is associated with the key.8. Save and close the file.
You can create as many resource bundles for your application as you want, but
each resource bundle must have a different locale and the same prefix.
Related concepts
“Locales for resource bundles” Related tasks
“Customizing runtime messages” on page 127
“Localizing text in Web applications” on page 214
Locales for resource bundles
Each resource bundle has a different locale. The locale indicates the specific human
language of the strings in the resource bundle. The locale is indicated by the end of
the file name, before the .properties extension.
Locales consist of one to three identifiers. Each additional identifier after the first
identifier enables you to indicate a more specific language by specifying the
dialect, variety, or geographic location of the language. The identifiers are
separated with an underscore character.
The simplest locales indicate a human language with a single identifier. This
identifier is the language code of the language that is used in the resource bundle.
For example, the language code en indicates English, and es indicates Spanish. An
English resource bundle might be named resourceBundle_en.properties. The
language code is part of the Java specification.
A more complex locale includes a language code followed by a country code. The
country code indicates a country where the dialect of the language is spoken. For
example, the country code US indicates the United States, and GB indicates Great
Britain. In this way, an American English resource bundle might be named
resourceBundle_en_US.properties, while a British English resource bundle might
be named resourceBundle_en_GB.properties. The country code is part of the Java
specification.
The most complex locale includes a language code, followed by a country code,
followed by a variant code. The variant code defines a more specific dialect or
variety of the language in the resource bundle. For example, you could use the
variant codes A and B to distinguish between two different varieties of Norwegian
spoken in Norway. These two resource bundles might be named
resourceBundle_no_NO_A.properties and resourceBundle_no_NO_B.properties.
Alternately, you could define a standard type of Norwegian as the locale no_NO and
define a variant as no_NO_B. The variant code is not part of the Java specification.
If the user requests a locale that exactly matches a locale in the application, the
resource bundle that represents that locale is the source of the strings that are used
in the application. If the user requests a locale that is more specific than any of the
locales in the application, the application uses a resource bundle with a more
general locale. For example, if the user requests the locale no_NO_B, but the only
available Norwegian locale is no_NO, the locale no_NO is used.
It is good programming practice to include a default resource bundle. The default
resource bundle is used if the user requests no locale or a locale that is more
general than any supported by the application. The default resource bundle has no
218 EGL Programmer’s Guide
locale. If no default resource bundle is specified, or if no locale can be loaded for
the Web page, the page uses the string values that are specified on the page at
definition time.
Related tasks
“Creating a resource bundle” on page 217
“Customizing runtime messages” on page 127
“Localizing text in Web applications” on page 214
Updating portions of a Web page with AJAX requests
Asynchronous JavaScript and XML (AJAX) is a development technique that you
can use to create Web pages that relay information to and from a server only for
the portions of pages that users edit, while still displaying the rest of the page.
This technique can make Web applications faster and more efficient than if an
entire page had to reload after each user action. You can set up an EGL-controlled
JSP file to call the JSF Handler’s onPreRenderFunction and provide a limited
update to the page.
Setting up a JSP file and a JSF Handler to use AJAX requests involves these general
steps:
1. Create the page and JSF Handler.
2. Design the page and populate the page with JSF controls that are bound to
variables and functions in the JSF Handler.
3. Indicate the area of the page that you want to change as a result of the AJAX
request. No other part of the page will be affected.
4. On the page, indicate the user event that will trigger the AJAX request, such as
selecting or moving away from a particular text control.
5. Define the request to send from the page to the JSF Handler, including the type
of request (refresh, submit, or external) and any parameters to include with the
request.
6. Write code in the JSF Handler to process the request.
The following is the life cycle of a typical AJAX page in EGL:
1. The servlet renders the complete page, running the functions indicated by the
onConstructionFunction, onPreRenderFunction, and onPostRenderFunction
JSF Handler properties, as applicable.
2. The servlet sends the page to the browser.
3. The user begins to fill out the input fields on the page.
4. The user triggers the AJAX request.
5. The browser sends the request to the servlet, including the parameters specified
in the request.
6. The servlet calls the function in the JSF Handler indicated by the
onPreRenderFunction property, providing this function with the parameters in
the request.
7. The onPreRenderFunction function runs, updating controls in the area on the
page specified by the AJAX request.
8. The servlet renders the portion of the page specified by the AJAX request and
updates this portion of the page in the browser.
9. The cycle of AJAX requests continues until the user goes to another page, either
by clicking a link or by triggering a forward statement in the JSF Handler.
There are three types of AJAX requests available to Web pages in EGL:
Building EGL Web applications 219
Refresh
This type of request prompts the servlet to update the values of the
controls in a specified area of the page; however, it does not provide
information on the state of the page to the JSF Handler. In other words, if
the user changes the value of input controls on the page, the JSF Handler
is not aware of the changes; the variables in the JSF Handler are not
updated to match the page controls to which the variables are bound. This
limitation reduces the amount of data sent in the request, making the
request more modular and efficient.
If the JSF Handler needs information from the page to complete the refresh
request, you can add one or more parameters to the request. The JSF
Handler receives these parameters along with the request, but as before,
the variables in the JSF Handler are not updated to the new values of the
controls to which the variables are bound. For more information, see
“Updating a page with a refresh request” on page 223.
Submit
This type of request prompts the servlet to update the values of the
controls in a specified area of the page, as well as to update the values of
the variables in the JSF Handler. Unlike what happens in the refresh
request, the submit request causes all of the variables in the JSF Handler to
be set to the current values of the components to which the variables are
bound. Therefore, it is not necessary to pass parameters with a Submit
request, because all of the variables are updated to match the current state
of the page. For more information, see “Updating a page with a submit
request” on page 226.
External
This type of request prompts the servlet to update the content in a
specified area of the page with content from a different page. For more
information, see “Updating a page with a portion of another page” on
page 229.
The J2EELib.getQueryParameter() system function retrieves the parameters from
the AJAX request, if there are any. You can also use this function to detect whether
the onPreRenderFunction function has been called as the result of an AJAX refresh
or submit request by checking the value of the parameter $$ajaxmode. Any value
other than NULL indicates that the function has been called as the result of an
AJAX refresh or submit request:
if (J2EELib.getQueryParmeter("$$ajaxmode") == null)
//Not the result of an AJAX refresh or submit request
//May be the result of an AJAX external request or
else
//The result of an AJAX request.
end
Example
This example uses an AJAX refresh request to perform simple mathematical
operations like a calculator. The page shows two input controls and a combo box
with mathematical operations. The AJAX request, triggered by the combo box,
passes the selected operation and the two input controls to the
onPreRenderFunction of the JSF Handler, which performs the mathematical
operation and updates an output control showing the answer.
The page might look like this example:
220 EGL Programmer’s Guide
The following is the code of the JSP file:
<html>
<head>
<title>calculatorPage</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="GENERATOR" content="Rational Business Developer">
<link rel="stylesheet" type="text/css" href="theme/stylesheet.css"
title="Style">
</head>
<f:view>
<body>
<hx:scriptCollector id="scriptCollector1"
preRender="#{calculatorPage._preRender}"
postRender="#{calculatorPage._postRender}">
<h:form id="form1" styleClass="form">
<TABLE>
<TBODY>
<tr>
<td align="left">Field1:</td>
<td style="width:5px"></td>
<td>
<h:inputText id="input1" value="#{calculatorPage.field1}"
binding="#{calculatorPage.field1_Ref}" styleClass="inputText">
</h:inputText>
</td>
</tr>
<tr>
<td align="left">Field2:</td>
<td style="width:5px"></td>
<td>
<h:inputText id="input2" value="#{calculatorPage.field2}"
binding="#{calculatorPage.field2_Ref}" styleClass="inputText">
</h:inputText>
</td>
</tr>
<tr>
<td align="left">Operation:</td>
<td style="width:5px"></td>
<td>
<h:selectOneMenu id="operationComboBox"
styleClass="selectOneMenu" value="#{calculatorPage.operation}">
Building EGL Web applications 221
<f:selectItem itemValue="add" itemLabel="add" />
<f:selectItem itemValue="subtract" itemLabel="subtract" />
<f:selectItem itemValue="multiply" itemLabel="multiply" />
<f:selectItem itemValue="divide" itemLabel="divide" />
</h:selectOneMenu>
<hx:behavior event="onblur"
target="operationComboBox" behaviorAction="get"
targetAction="updatablePanel"></hx:behavior></td>
</tr>
<tr>
<td align="left">Output:</td>
<td style="width:5px"></td>
<td>
<h:panelGroup id="updatablePanel" styleClass="panelGroup">
<h:outputText id="output" value="#{calculatorPage.output}"
binding="#{calculatorPage.output_Ref}" styleClass="outputText">
</h:outputText>
</h:panelGroup>
<hx:ajaxRefreshRequest id="ajaxRefreshRequest1"
target="updatablePanel" params="input1;input2;operationComboBox">
</hx:ajaxRefreshRequest>
</td>
</tr>
</TBODY>
</TABLE>
</h:form>
</hx:scriptCollector>
</body>
</f:view>
</html>
The following is the code of the JSF Handler that goes with this page:
package jsfhandlers;
handler calculatorPage type JSFHandler
{onPreRenderFunction = onPreRender,
view = "calculatorPage.jsp"}
field1 float;
field2 float;
operation string;
output string;
function onPreRender()
if (J2EELib.getQueryParameter("$$ajaxmode") == null)
output = "Enter values and an operation.";
else
calculateAnswer();
end
end
function calculateAnswer()
param1 float = J2EELib.getQueryParameter("input1");
param2 float = J2EELib.getQueryParameter("input2");
case (J2EELib.getQueryParameter("operationComboBox"))
when ("add")
output = param1 + param2;
when ("subtract")
output = param1 - param2;
when ("multiply")
output = param1 * param2;
when ("divide")
222 EGL Programmer’s Guide
output = param1 / param2;
end
end
end
Related tasks
“Updating a page with a refresh request”
“Updating a page with a submit request” on page 226
“Updating a page with a portion of another page” on page 229
Updating a page with a refresh request
The refresh type of AJAX request prompts the servlet to update the values of the
controls in a specified area of the page. However, the refresh request does not
update the variables in the JSF Handler to match the controls on the page. In this
way, this type of request is intended to be modular and efficient.
With this type of request, you specify an area of the page to be updated, an event
to trigger the request, and optionally any parameters to be passed along with the
request. Then, you configure the JSF Handler’s onPreRenderFunction to update
the specified part of the page.
Follow these steps to add an AJAX refresh request to a Web page. The following
steps assume that you have a JSF Handler with variables bound to controls on a
Web page:
1. On the Web page, indicate the area of the page that you want to update with
the AJAX request by creating a JSF panel control on the page.
AJAX requests in EGL can update only the parts of the page within a JSF panel
control. JSF panel controls serve mainly as containers and organizers for other
JSF controls. The Panel - Group Box control, found in the Enhanced Faces
Components drawer of the Palette view, is a good control to use because it is
only a container and is not visible on the page.
2. Set the ID attribute of the panel control to a value that is unique on the page.
You will need to specify this ID in the AJAX request.
3. Place the JSF controls that you want to update inside the panel control and
make sure that the controls are bound to EGL variables.
The code of the panel control might look like the following example. In this
case, only a single output control is within the panel.
<h:panelGrid id="updatablePanel" styleclass="panelGrid">
<h:outputText id="textToUpdate" value="#{myPage.message}"
binding="#{myPage.message_Ref}" styleClass="outputText" />
</h:panelGrid>
4. Set the ID attributes of any controls on the page that you want to pass as
parameters in the request. These controls do not need to be within the panel
control, but their ID attributes must be unique on the page, and they must be
input controls.
5. Specify the user event that will trigger the AJAX request.
Do this by adding a JSF behavior to an input control on the page and then
choosing an event to trigger the request. The control containing the behavior
does not need to be within the panel control, but only input controls can
trigger requests.
For example, you can make the AJAX request occur when the user moves the
focus into a particular control. In this case, you use the onFocus event. To
Building EGL Web applications 223
perform the request when the user moves focus away from a particular control,
you use the onBlur event. Other commonly used events include onClick,
onMouseOver, and onSelect.
a. On the Web page, select the input control that you want to use as the
trigger.
b. With the control selected, open the Quick Edit view.
c. In the Quick Edit view, select the event, such as onBlur, from the left side of
the view.
d. Select the Use pre-defined behavior check box.
e. In the Action list, select Invoke Ajax behavior on the specified tag.
f. In the Target list, select the ID of the panel you want to update.
Now the behavior to trigger the AJAX request is attached to the control. For
example, if you attach a behavior to an input text control and set it to use the
onBlur event, the code on the page might look like this:
<h:inputText id="nameText" value="#{myPage.name}"
binding="#{myPage.name_Ref}" styleClass="inputText" >
<hx:behavior event="onblur" id="behavior1"
behaviorAction="get" targetAction="updatablePanel">
</hx:behavior>
</h:inputText>
The behavior might look like this example:
6. Create the request by specifying the panel to update and the parameters for the
request:
a. On the Web page, select the panel control.
b. With the panel selected, open the Properties view.
c. On the properties view, go to the Ajax tab under the type of panel control.
d. On the Ajax tab, select the Allow Ajax updates check box.
e. Click Refresh as the type of request.
f. Under the types of requests, click the button labeled Click to edit Ajax
request properties.
g. In the Target list, select the ID attribute of the panel you want to update.
224 EGL Programmer’s Guide
h. Add parameters to the request by clicking one of the Add Parameter
buttons:
The parameters in the table labeled Parameter values sent from the
browser refer to the value of input controls on the page. For example, if
you want to pass the current value of an input control on the page as a
parameter, add that input control’s ID here.
The parameters in the table labeled Parameter values calculated on the
server refer either to literal values you type here or to the value of variables
in the JSF Handler.
For example, if you choose to pass the value of an input control on the page,
the new request might look like this:
<hx:ajaxRefreshRequest id="ajaxRefreshRequest1"
target="updatablePanel" params="nameText">
</hx:ajaxRefreshRequest>
In the editor, the AJAX request might look like this example:
7. In the JSF Handler for the page, configure the onPreRenderFunction to accept
the request.
Because the onPreRenderFunction runs when the page first loads as well as on
every AJAX request, you might want to detect which case has caused the
function to run. You can do this by testing for the value of the parameter
$$ajaxmode. When the function runs as the result of a normal page loading
operation, this parameter is null; when the function runs as the result of an
AJAX request, the parameter will contain a value.
function onPreRender()
if (J2EELib.getQueryParameter("$$ajaxmode") == NULL)
//The page is loading for the first time.
//Perform page loading operations here.
else
//The page is loading as the result of an AJAX request.
//Perform AJAX updating operations here.
end
end
Building EGL Web applications 225
8. Once you have determined that the onPreRenderFunction has been invoked as
the result of an AJAX request, you can update the controls on the page by
setting the values of the variables bound to those controls. You can update only
the controls within the panel in the request.
You can retrieve the parameters passed with the request by using the
J2EELib.getQueryParameter() system function. For example, if you passed the
value of a text control with the ID nameText, you can retrieve the value of that
parameter with the following code:
outputText = "Hello "::J2EELib.GetQueryParameter("nameText")::"!";
For an example of an AJAX refresh request, see “Updating portions of a Web page
with AJAX requests” on page 219.
Related tasks
“Updating portions of a Web page with AJAX requests” on page 219Asynchronous JavaScript and XML (AJAX) is a development technique that you
can use to create Web pages that relay information to and from a server only
for the portions of pages that users edit, while still displaying the rest of the
page. This technique can make Web applications faster and more efficient than
if an entire page had to reload after each user action. You can set up an
EGL-controlled JSP file to call the JSF Handler’s onPreRenderFunction and
provide a limited update to the page.
“Updating a page with a submit request”
“Updating a page with a portion of another page” on page 229
Updating a page with a submit request
The submit type of AJAX request works in a way that is similar to the action that
occurs when a user clicks a button on an EGL-controlled Web page: control passes
to the JSF Handler and all the variables in the JSF Handler are updated to match
the values of the JSF controls. Unlike a refresh request, there is no need to pass
parameters because all of the variables in the JSF Handler are updated with the
current values of the control. However, like a refresh request, only the controls
within a JSF panel control are updated.
With this type of request, you specify an area of the page to be updated and an
event to trigger the request. Then, you configure the JSF Handler’s
onPreRenderFunction to update the specified part of the page.
Follow these steps to add an AJAX submit request to a Web page. The following
steps assume that you have a JSF Handler with variables bound to controls on a
Web page:
1. On the Web page, indicate the area of the page that you want to update with
the AJAX request by creating a JSF panel control on the page.
AJAX requests in EGL can update only the parts of the page within a JSF panel
control. JSF panel controls serve mainly as containers and organizers for other
JSF controls. The Panel - Group Box control, found in the Enhanced Faces
Components drawer of the Palette view, is a good control to use because it is
only a container and is not visible on the page.
2. Set the ID attribute of the panel control to a value that is unique on the page.
You will need to specify this ID in the AJAX request.
3. Place the JSF controls that you want to update inside the panel control and
make sure that the controls are bound to EGL variables.
The code of the panel control might look like the following example. In this
case, only a single output control is within the panel.
226 EGL Programmer’s Guide
<h:panelGrid id="updatablePanel" styleclass="panelGrid">
<h:outputText id="textToUpdate" value="#{myPage.message}"
binding="#{myPage.message_Ref}" styleClass="outputText" />
</h:panelGrid>
4. Specify the user event that will trigger the AJAX request.
Do this by adding a JSF behavior to an input control on the page and then
choosing an event to trigger the request. The control containing the behavior
does not need to be within the panel control, but only input controls can
trigger requests.
For example, you can make the AJAX request occur when the user moves the
focus into a particular control. In this case, you use the onFocus event. To
perform the request when the user moves focus away from a particular control,
you use the onBlur event. Other commonly used events include onClick,
onMouseOver, and onSelect.
a. On the Web page, select the input control that you want to use as the
trigger.
b. With the control selected, open the Quick Edit view.
c. In the Quick Edit view, select the event, such as onBlur, from the left side of
the view.
d. Select the Use pre-defined behavior check box.
e. In the Action list, select Invoke Ajax behavior on the specified tag.
f. In the Target list, select the ID of the panel you want to update.
Now the behavior to trigger the AJAX request is attached to the control. For
example, if you attach a behavior to an input text control and set it to use the
onBlur event, the code on the page might look like this:
<h:inputText id="nameText" value="#{myPage.name}"
binding="#{myPage.name_Ref}" styleClass="inputText" >
<hx:behavior event="onblur" id="behavior1"
behaviorAction="get" targetAction="updatablePanel">
</hx:behavior>
</h:inputText>
The behavior might look like this example:
5. Create the request by specifying the panel to update:
a. On the Web page, select the panel control.
Building EGL Web applications 227
b. With the panel selected, open the Properties view.
c. On the Properties view, go to the Ajax tab under the type of panel control.
d. On the Ajax tab, select the Allow Ajax updates check box.
e. Click Submit as the type of request.
The Properties view looks like this example:
f. Under the types of requests in the Properties view, click the button labeled
Click to edit Ajax request properties.
g. In the Target list, select the ID attribute of the panel you want to update.
For example, the new request might look like this:
<hx:ajaxRefreshSubmit id="ajaxRefreshSubmit1"
target="updatablePanel">
</hx:ajaxRefreshSubmit>
6. In the JSF Handler for the page, configure the onPreRenderFunction to accept
the request.
Because the onPreRenderFunction runs when the page first loads as well as on
every AJAX request, you might want to detect which case has caused the
function to run. You can do this by testing for the value of the parameter
$$ajaxmode. When the function runs as the result of a normal page loading
operation, this parameter is null; when the function runs as the result of an
AJAX request, the parameter will contain a value.
function onPreRender()
if (J2EELib.getQueryParameter("$$ajaxmode") == NULL)
//The page is loading for the first time.
//Perform page loading operations here.
else
//The page is loading as the result of an AJAX request.
228 EGL Programmer’s Guide
//Perform AJAX updating operations here.
end
end
7. Once you have determined that the onPreRenderFunction has been called as
the result of an AJAX request, you can update the controls on the page by
setting the values of the variables bound to those controls. You can update only
the controls within the panel in the request. Related tasks
“Updating portions of a Web page with AJAX requests” on page 219Asynchronous JavaScript and XML (AJAX) is a development technique that you
can use to create Web pages that relay information to and from a server only
for the portions of pages that users edit, while still displaying the rest of the
page. This technique can make Web applications faster and more efficient than
if an entire page had to reload after each user action. You can set up an
EGL-controlled JSP file to call the JSF Handler’s onPreRenderFunction and
provide a limited update to the page.
“Updating a page with a refresh request” on page 223
“Updating a page with a portion of another page”
Updating a page with a portion of another page
The external type of AJAX request prompts the servlet to replace a specified area of
one page with a specified area of a second page. Like the refresh type of request,
you can pass parameters to the second page. The onPreRenderFunction function
can receive these parameters with the J2EELib.getQueryParameter system
function.
With this type of request, you specify an area of the first page to be updated, an
event to trigger the request, and optionally any parameters to be passed along with
the request. Unlike the other types of request, the external AJAX request goes to
another page, so the request must specify the page to send the request to and the
control from that page to use in place of the first page.
Using this type of AJAX request involves creating two pages:
v A source page from which the content will be taken
v A target page into which the content will be placed
Follow these steps to add an AJAX external request to a Web page:
1. Create a source page to hold the content that you want to use on another page:
a. Create a JSP file and JSF Handler as you would ordinarily create an
EGL-controlled Web page.
b. On this page, add a panel control and give it an ID unique on the page.
c. Add the content into the panel control. The request will instruct the servlet
to take the content from this panel and use it on another page.
d. In the JSF Handler for the page, configure the onPreRenderFunction to
accept the request.
Because the onPreRenderFunction runs when the page first loads as well as
on every AJAX request, you might want to detect which case has caused the
function to run. You can do this by testing for the value of the parameter
$$ajaxmode. When the function runs as the result of a normal page loading
operation, this parameter is null; when the function runs as the result of an
AJAX request, the parameter will contain a value.
Building EGL Web applications 229
function onPreRender()
if (J2EELib.getQueryParameter("$$ajaxmode") == NULL)
//The page is loading for the first time.
//Perform page loading operations here.
else
//The page is loading as the result of an AJAX request.
//Perform AJAX updating operations here.
end
end
e. Once you have determined that the onPreRenderFunction has been
invoked as the result of an AJAX request, you can update the controls on
the page by setting the values of the variables bound to those controls. You
can update only the controls within the panel in the request.
You can retrieve the parameters passed with the request by using the
J2EELib.getQueryParameter() system function. For example, if you passed
the value of a text control with the ID nameText, you can retrieve the value
of that parameter with the following code:
outputText = "Hello "::J2EELib.GetQueryParameter("nameText")::"!";
2. Create the target page into which the content will be placed:
a. Create a JSP file and JSF Handler as you would ordinarily create an
EGL-controlled Web page.
b. On this page, add a panel control and give it an ID unique on the page. The
contents of this panel will be replaced with the panel on the source page.
c. Optionally, add JSF controls to the panel. The panel can be blank or
populated with controls when the AJAX request replaces it with the panel
on the source page.3. Specify the user event that will trigger the AJAX request.
Do this by adding a JSF behavior to an input control on the page and then
choosing an event to trigger the request. The control containing the behavior
does not need to be within the panel control, but only input controls can
trigger requests.
For example, you can make the AJAX request occur when the user moves the
focus into a particular control. In this case, you use the onFocus event. To
perform the request when the user moves focus away from a particular control,
you use the onBlur event. Other commonly used events include onClick,
onMouseOver, and onSelect.
a. On the Web page, select the input control that you want to use as the
trigger.
b. With the control selected, open the Quick Edit view.
c. In the Quick Edit view, select the event, such as onBlur, from the left side of
the view.
d. Select the Use pre-defined behavior check box.
e. In the Action list, select Invoke Ajax behavior on the specified tag.
f. In the Target list, select the ID of the panel you want to update.
Now the behavior to trigger the AJAX request is attached to the control. For
example, if you attach a behavior to an input text control and set it to use the
onBlur event, the code on the page might look like this:
230 EGL Programmer’s Guide
<h:inputText id="nameText" value="#{myPage.name}"
binding="#{myPage.name_Ref}" styleClass="inputText" >
<hx:behavior event="onblur" id="behavior1"
behaviorAction="get" targetAction="updatablePanel">
</hx:behavior>
</h:inputText>
The behavior might look like this example:
4. Create the request by specifying the panel to update and the parameters for the
request:
a. On the target page, select the panel control.
b. With the panel selected, open the Properties view.
c. On the properties view, go to the Ajax tab under the type of panel control.
d. On the Ajax tab, select the Allow Ajax updates check box.
e. Click External as the type of request.
f. Under the types of requests, click the button labeled Click to edit Ajax
request properties.
g. In the Target list, select the ID attribute of the panel on the target page you
want to update.
h. In the URL field, enter the relative path to the source page. Be sure to use
the correct extension of .faces or .jsp for the target page, as explained in
“Running a Web page on a server” on page 235.
i. In the Source field, enter the ID of the panel control on the source page. The
contents of this panel will replace the contents of the panel on the target
page.
If you leave this field blank, the request will retrieve the entire source page
(that is, everything within the <body> tag), not just the panel control.
j. Add parameters to the request by clicking one of the Add Parameter
buttons:
The parameters in the table labeled Parameter values sent from the browser
refer to the value of input controls on the target page. For example, if you
want to pass the current value of an input control on the page as a
parameter, add that input control’s ID here.
Building EGL Web applications 231
The parameters in the table labeled Parameter values calculated on the
server refer either to literal values you type here or to the value of variables
in the source page’s JSF Handler.
For example, if you choose to pass the value of an input control on the page,
the new request might look like this:
<hx:ajaxExternalRequest id="ajaxExternalRequest1"
target="sourcePanel" params="nameText"
href="sourcePage.faces" soure="replacePanel">
</hx:ajaxExternalRequest>
Now when the request is triggered on the target page, the servlet will pass the
AJAX external request to the source page, along with any parameters. The servlet
invokes the onPreRenderFunction function on the source page and when that
function has finished, it removes the panel from the source page and inserts it into
the target page.
Example
The following example shows two pages that work together with an AJAX external
request as explained in this topic. The target page includes a group of check boxes
that allow the user to select a value. The AJAX request passes this value to the
source page, which renders a replacement panel based on the value of the
message.
The page and its request look like this example:
The following is the code of the target page, named targetPage.jsp:
<html>
<head>
<title>targetPage</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="GENERATOR" content="Rational Business Developer">
<link rel="stylesheet" type="text/css" href="theme/stylesheet.css"
title="Style">
</head>
<f:view>
<body>
<hx:scriptCollector id="scriptCollector1">
232 EGL Programmer’s Guide
<h:form id="form1" styleClass="form">
<h:panelGroup id="targetPanel" styleClass="panelGroup">
<h:outputText id="promptMessage" styleClass="outputText"
value="What is your favorite type of friut?">
</h:outputText>
<h:selectOneRadio disabledClass="selectOneRadio_Disabled"
enabledClass="selectOneRadio_Enabled" id="fruitName"
styleClass="selectOneRadio">
<f:selectItem itemValue="bananas" itemLabel="bananas" />
<f:selectItem itemValue="apples" itemLabel="apples" />
<f:selectItem itemValue="grapes" itemLabel="grapes" />
</h:selectOneRadio>
<hx:behavior event="onchange" target="fruitName"
behaviorAction="get" targetAction="targetPanel">
</hx:behavior>
</h:panelGroup>
<hx:ajaxExternalRequest id="ajaxExternalRequest1"
target="targetPanel" href="sourcePage.faces"
source="sourcePanel" params="fruitName">
</hx:ajaxExternalRequest>
</h:form>
</hx:scriptCollector>
</body>
</f:view>
</html>
The following are some technical details about the target page:
v The tag <h:panelGroup> is the JSF panel control that will be updated. It has the
ID attribute targetPanel.
v The tag <h:outputText> is a JSF output text control that displays a static
message as a prompt.
v The tag <h:selectOneRadio> is a JSF check box group control that offers three
options. This check box group has the ID attribute fruitName, which will be the
parameter passed along with the request.
v The tag <hx:behavior> specifies the event that triggers the AJAX request. The
behavior’s attributes point to the ID of the panel control and the radio button
group. In this case, the event is onchange, which means that the AJAX request is
triggered when the selection in the radio button group changes.
v The tag <hx:ajaxExternalRequest> defines the AJAX request itself. This tag’s
target attribute points to the panel control, indicating that this request will run
when the panel’s event is triggered. The other attributes of the request point to
the location of the source page, the ID of the panel to retrieve from the source
page, and the parameter to pass with the request. In this case, the request
includes the selection in the check box group as a parameter.
The following is the JSF Handler that would go with this page, named
targetPage.egl:
package jsfhandlers;
handler targetPage type JSFHandler
{view = "targetPage.jsp"}
end
Building EGL Web applications 233
No special code is required in the JSF Handler for the target page. Because this
example uses an external request, the request goes to the source page, so that
page’s JSF Handler will process the request.
Following is the code of the source page, named sourcePage.jsp:
<html>
<head>
<title>sourcePage</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="GENERATOR" content="Rational Business Developer">
<link rel="stylesheet" type="text/css" href="theme/stylesheet.css"
title="Style">
</head>
<f:view>
<body>
<hx:scriptCollector id="scriptCollector1"
preRender="#{sourcePage._preRender}" postRender="#{sourcePage._postRender}">
<h:panelGroup id="sourcePanel" styleClass="panelGroup">
<h:outputText id="text1" styleClass="outputText"
value="#{sourcePage.message}" binding="#{sourcePage.message_Ref}">
</h:outputText>
</h:panelGroup>
</hx:scriptCollector>
</body>
</f:view>
</html>
This page contains a panel control that will be used to replace the panel on the
target page. In this case, the panel contains a single output field that is bound to a
variable in the page’s JSF Handler. The page looks like this:
Following is the JSF Handler that would go with this page, named sourcePage.egl:
package jsfhandlers;
handler sourcePage type JSFHandler
234 EGL Programmer’s Guide
{onPreRenderFunction = onPreRender,
view = "sourcePage.jsp"}
message string = "No value set";
function onPreRender()
if (J2EELib.getQueryParameter("fruitName") != null)
case (J2EELib.getQueryParameter("fruitName"))
when ("bananas")
message = "Bananas are a yellow tropical fruit.";
when ("grapes")
message = "Grapes grow on vines and can be made into wine.";
when ("apples")
message = "Apples grow on trees in many parts of the world";
end
end
end
end
This JSF Handler’s onPreRenderFunction function first detects whether the
function has been called as the result of an AJAX request. If so, the JSF Handler
updates the text control on the page to show a message based on the value of the
parameter passed along with the request. The request then uses the contents of the
panel on the source page to replace the contents of the panel on the target page.
Related tasks
“Updating portions of a Web page with AJAX requests” on page 219Asynchronous JavaScript and XML (AJAX) is a development technique that you
can use to create Web pages that relay information to and from a server only
for the portions of pages that users edit, while still displaying the rest of the
page. This technique can make Web applications faster and more efficient than
if an entire page had to reload after each user action. You can set up an
EGL-controlled JSP file to call the JSF Handler’s onPreRenderFunction and
provide a limited update to the page.
“Updating a page with a submit request” on page 226
“Updating a page with a refresh request” on page 223
Running a Web page on a server
When you are working with a Web page in EGL, you can run the page on a server
to see how it will look when deployed.
This task has the following prerequisites:
v An EGL Web project with at least one Web page.
v A server defined in the workbench.
To run a Web page on a server in the workbench:
1. Save any unsaved files and generate the project. Note that in past versions of
EGL, JSF Handlers were generated automatically when you saved the file, but
now you can choose whether to generate Handlers automatically or not. See
“Setting generation preferences” on page 152.
2. If the server is already running, publish the new versions of your files to the
server by right-clicking the server in the Servers view and then clicking
Publish.
If the server is not already running, publishing will happen automatically when
you run the page. Depending on the server and its settings, it might publish
automatically when you save changes to the Web project; in this case, wait until
the server’s status is listed as Synchronized.
Building EGL Web applications 235
3. In the Project Explorer view, right-click the JSP file (not the EGL source file
with the JSF Handler) and then click Run As → Run on Server. If you have not
yet defined a default server for the project, the Run On Server window opens.
4. In the Run On Server window, select a server to use.
5. If you want to use this server each time your run a page, select the Set server
as project default check box.
6. Click Finish. The server starts, if necessary, and the page opens in the internal
Web browser of the workbench. As long as the server is running, you can copy
the URL from the internal Web browser and paste it into the address field of
any external Web browser on your system to view the page in a different
browser.
The URL of the Web page is set by the JavaServer Faces (JSF), which controls the
run-time display of the JSP files. For example, if you run a Web page named
myPage.jsp in a project named myProject, the internal Web browser might open to
the following URL:
http://hostname:portnumber/myProject/faces/myPage.jsp
You may also see this URL:
http://hostname:portnumber/myProject/myPage.faces
In each case, hostname refers to the name of your local server, such as localhost,
and portnumber refers to the port of that server. Note that in the first case, JSF adds
the /faces prefix to the URL. In the other case, it adds the .faces extension to the
file name, replacing the actual .jsp extension. These URLs are equivalent and refer
to the same JSP file and JSF Handler part.
However, conflicts between these two different URLs can cause links to break
when you test Web pages in the workbench. If the page opens as
myProject/myPage.faces, relative links to a page named myProject/myOtherPage.jsp will not work because JSF sets the location for the target page as
myProject/myOtherPage.faces and myProject/faces/myOtherPage.jsp. In this case,
you must either change the link to myProject/faces/myOtherPage.jsp or
myProject/myOtherPage.faces, or open the original page as myProject/faces/myPage.jsp.
Accessing the JSF component tree with the source assistant
You can use EGL code to call Java functions that are recognized by JavaServer
Faces (JSF) controls. In this way, you can change the appearance and behavior of
these controls from a JSF Handler. The following example includes EGL code to
access a JSF control:
package jsfhandlers;
import com.ibm.egl.jsf.*;
handler myPage type JSFHandler
{view = "myPage.jsp",
viewRootVar = myViewRoot}
myViewRoot UIViewRoot;
myInputVar string = "Hello";
function changeColor()
myInputField HtmlInputText;
myInputField = viewRoot.findComponent("form1:text1");
236 EGL Programmer’s Guide
myInputField.setStyle("color : red");
end
end
This example assumes an input control on the JSP named text1 that is bound to
the myInputVar variable and a command button on the JSP that is bound to the
changeColor function.
To access a JSF control from a JSF Handler:
1. Make sure that your EGL Web project has support for the JSF component
interface. See “Adding JSF component interface support to an EGL Web
project” on page 246.
2. Create a Web page and add one or more JSF controls to it.
3. Optionally, you might want to change the ID attribute of the JSF controls so
they will be easier to identify. You can change the ID attribute by selecting the
control and typing a meaningful mnemonic that is unique within the page in
the ID field in the Properties view.
4. In the JSF Handler of the page, add the following code. If you create the Faces
JSP file after you add support for the JSF component interface to the project,
this code is added to the JSF Handler’s file automatically.
v Add the following import statement:
import com.ibm.egl.jsf.*
The packages that are imported by this statement contain a group of
ExternalType parts which provide access to Java code in the JSF controls. You
do not need to edit these parts.
v Within the JSF Handler of the page, declare a variable of the type
UIViewRoot, as in this example:
myViewRoot UIViewRoot;
v Specify the name of the UIViewRoot variable in the viewRootVar JSF
Handler property:
handler myPage type JSFHandler
{view = "myPage.jsp",
viewRootVar = myViewRoot}
5. On a blank line inside a function in the JSF Handler, press Ctrl+Shift+Z. The
EGL Source Assistant window opens, displaying the JSF controls on the page.
6. In the EGL Source Assistant window, select the JSF control you want to access.
You can use the IDs or control types to find the control you want, or you can
hover the mouse over the controls to see their attributes.
7. Click OK.
The EGL source assistant adds two lines of EGL code to the JSF Handler:
v The first line of code defines an EGL variable of the ExternalType part that
matches the JSF control that you selected. In the previous example, a variable
of the type HtmlInputText is defined to access a JSF input text control, using
this code:
myInputField HtmlInputText;
v The second line of code associates that variable with the JSF control. In the
above example, the variable is associated with a JSF input text control named
text1, which is located within a form named form1, using this code:
myInputField = myViewRoot.findComponent("form1:text1");
Building EGL Web applications 237
8. Use the variable to change the JSF control. For example, the following code
uses the setStyle function to change the text in an input control to the color
red:
myInputField.setStyle("color : red");
When this code runs, the style of the input control is changed. In this example,
the HTML code displayed by the browser looks like this:
<input id="form1:text1" type="text" name="form1:text1" style="color : red" />
The related topics in this section give some other examples of operations that
you can perform on JSF controls in this way. To see the full list of operations
you can call on a given control, refer to the functions of the ExternalType parts
in the com.ibm.egl.jsf package.
Following are some notes about accessing JSF controls with EGL code:
v For the complete list of JSF functions that are accessible in EGL, open the file
FacesHtmlComponent.egl in the package com.ibm.egl.jsf. This file is added to
your project when you add support for the JSF component interface. The
functions are briefly explained in comments to this file. For more detailed
information, see the documentation for Faces controls.
v When passing a parameter to one of these functions, be sure to pass the correct
data type. Because many of the parameters passed to these functions are
inserted into HTML attributes, they must be passed as EGL string variables,
even if the name of the function suggests that the parameter is a numerical or
boolean value.
For example, the setWidth function sets the width of a control in pixels, or in a
percentage of its original size if the percent (%) symbol is appended. Because
this parameter is a measurement, it might seem to take a numeric data type as a
parameter. However, this function must receive a string. To set the width of a
control to 300 pixels, you must pass a string variable with the value ″300″.
v Because many of the functions set or return information from HTML attributes,
you should be aware of the HTML attributes that are connected to the functions
that you are using. You might change an HTML attribute that is needed for the
page to work correctly. For example, if you change the style class of a control as
in Changing the style class of a JSF control, that new style class of the control must
be available to the page in a CSS file or style tag, or else the control might not
display properly. Be sure to test any changes that you make to Web pages. The
comments in the FacesHtmlComponent.egl file note the functions that change
HTML attributes directly.
v In most cases, the changes that you make to the JSF controls are not cumulative.
For example, if you set a control’s text to red with the code
myComponent.setStyle("color: red"); and then set the same control’s text to
bold with the code myComponent.setStyle("font-weight: bold");, the text will
be bold but not red, because the change to bold overwrites the change to red.
To add several changes to a JSF control, retrieve the current state of the control
and append the new data, paying attention to how the list of changes is
delimited. For example, use the following code to change a control’s text to bold
and red, without overwriting any previous changes to that control’s style:
myStyleString string;
myStyleString = myComponent.getStyle() + "; color: red; font-weight: bold";
myComponent.setStyle(myStyleString);
v You cannot access JSF controls in this way in the onConstructionFunction,
onPreRenderFunction, or onPostRenderFunction functions in the Handler.
There are many different changes that you can make to JSF controls. See the
related tasks for some examples.
238 EGL Programmer’s Guide
Related tasks
“Changing the target of a JSF link”
“Changing the style of a JSF control” on page 240
“Changing the style class of a JSF control” on page 241
“Setting event handlers for a JSF control” on page 242
“Setting the size of a JSF image” on page 243
“Enabling or disabling JSF controls” on page 244
“Setting JSF data table properties” on page 245
Changing the target of a JSF link
You can change the target attribute of a JavaServer Faces (JSF) link from a JSF
Handler. For example, you can set the target attribute of a link to _blank to make
that link open in a new browser window.
This task has the following prerequisites:
v Your EGL Web project must have support for the JSF component interface. See
“Adding JSF component interface support to an EGL Web project” on page 246.
v The JSF Handler that is associated with the Web page must have the following
import statement:
import com.ibm.egl.jsf.*
v You must declare a variable of the type UIViewRoot within the JSF Handler.
v You must specify the name of the of the UIViewRoot variable in the
viewRootVar JSF Handler property.
For more information on these prerequisites, see “Accessing the JSF component
tree with the source assistant” on page 236.
To change the target attribute of a JSF link from a JSF Handler:
1. On a blank line inside a function in the JSF Handler, press Ctrl+Shift+Z. The
EGL Source Assistant window opens, displaying the JSF controls on the page.
2. In the EGL Source Assistant window, select the JSF control that you want to
access.
3. Click OK.
The EGL source assistant adds two lines of EGL code to the JSF Handler. The
first line defines an EGL variable of the type that matches the JSF link that you
selected. The second line associates that variable with the JSF link. For example,
the code might look like this:
linkEx1 HtmlOutputLink;
linkEx1 = myViewRoot.findComponent("form1:linkEx1");
4. Using the EGL variable that is created by the source assistant, change the target
of the link with the setTarget() function. For example, to make the link open
in a new window, add this code:
linkEx1.setTarget("_blank");
Related tasks
“Adding JSF component interface support to an EGL Web project” on page 246
“Changing the style class of a JSF control” on page 241
“Changing the style of a JSF control” on page 240
“Enabling or disabling JSF controls” on page 244
“Setting the size of a JSF image” on page 243
“Setting event handlers for a JSF control” on page 242
Building EGL Web applications 239
“Setting JSF data table properties” on page 245
Changing the style of a JSF control
You can change the appearance of a JavaServer Faces (JSF) control with EGL code,
such as changing the text color. To make a larger change in the control’s
appearance by changing its style class, see Changing the style class of a JSF control.
This task has the following prerequisites:
v Your EGL Web project must have support for the JSF component interface. See
“Adding JSF component interface support to an EGL Web project” on page 246.
v The JSF Handler that is associated with the Web page must have the following
import statement:
import com.ibm.egl.jsf.*
v You must declare a variable of the type UIViewRoot within the JSF Handler.
v You must specify the name of the of the UIViewRoot variable in the
viewRootVar JSF Handler property.
For more information on these prerequisites, see “Accessing the JSF component
tree with the source assistant” on page 236.
Follow these steps to change the style of a JSF control from an EGL JSF Handler:
1. On a blank line inside a function in the JSF Handler, press Ctrl+Shift+Z. The
EGL Source Assistant window opens, displaying the JSF controls on the page.
2. In the EGL Source Assistant window, select the JSF control that you want to
access.
3. Click OK.
The EGL source assistant adds two lines of EGL code to the JSF Handler. The
first line defines an EGL variable of the type that matches the JSF control that
you selected. The second line associates that variable with the JSF control. For
example, the code to access a JSF input text control might look like this:
text1 HtmlInputText;
text1 = myViewRoot.findComponent("form1:text1");
4. Using the EGL variable that the source assistant created, change the style of the
JSF control with the setStyle function. For example, to change the text in a text
control to red, add this code:
text1.setStyle("color : red");
When this code runs, the style attribute of the input control is changed. In this
example, the HTML code displayed by the browser looks like this:
<input id="form1:text1" type="text" name="form1:text1" style="color : red" />
The new style attribute overwrites any previous style attribute. To make more
than one change to the style of a control, separate changes with semicolons (;).
For example, to change the color to red and the size to 20 points, use this code:
text1.setStyle("color : red; font-size: 20pt");
Some examples of other changes you can make to the style of a control follow. Not
all styles are compatible with all JSF controls.
text1.setStyle("font-size : 20pt");
Sets the size of the font in the control to 20 points.
text1.setStyle("text-align: center");
Centers the text within the control.
240 EGL Programmer’s Guide
text1.setStyle("border-style : solid; border-color : red");
Adds a red border composed of a solid line around the control.
text1.setStyle("font-weight : bold");
Makes the text within the control bold.
text1.setStyle("height : 50px");
Makes the control 50 pixels tall. Related tasks
“Adding JSF component interface support to an EGL Web project” on page 246
“Accessing the JSF component tree with the source assistant” on page 236
“Changing the style class of a JSF control”
“Changing the target of a JSF link” on page 239
“Enabling or disabling JSF controls” on page 244
“Setting the size of a JSF image” on page 243
“Setting event handlers for a JSF control” on page 242
“Setting JSF data table properties” on page 245
Changing the style class of a JSF control
Like many elements on a Web page, JSF controls can be assigned a style class with
the class attribute. A style class, not to be confused with a Java class, is a group of
zero to many commands that describes the appearance of an element on a Web
page. Style classes are defined with the Cascading Style Sheets language, a
language that can control many different aspects of the appearance of a Web page.
You can change the style class of a JSF control on a Faces JSP file from one class to
another. To make smaller changes to a JSF control’s style, such as changing the text
color, see “Changing the style of a JSF control” on page 240.
This task has the following prerequisites:
v Your EGL Web project must have support for the JSF component interface. See
“Adding JSF component interface support to an EGL Web project” on page 246.
v The JSF Handler that is associated with the Web page must have the following
import statement:
import com.ibm.egl.jsf.*
v You must declare a variable of the type UIViewRoot within the JSF Handler.
v You must specify the name of the of the UIViewRoot variable in the
viewRootVar JSF Handler property.
For more information on these prerequisites, see “Accessing the JSF component
tree with the source assistant” on page 236.
To change the style class of a JSF control from an EGL JSF Handler:
1. On a blank line inside a function in the Handler, press Ctrl+Shift+Z. The EGL
Source Assistant window opens, displaying the JSF controls on the page.
2. In the EGL Source Assistant window, select the JSF control you want to access.
3. Click OK.
The EGL source assistant adds two lines of EGL code to the JSF Handler. The
first line defines an EGL variable of the type that matches the JSF control that
you selected. The second line associates that variable with the JSF control. For
example, the code to access a JSF input text control might look like this:
text1 HtmlInputText;
text1 = myViewRoot.findComponent("form1:text1");
Building EGL Web applications 241
4. Using the EGL variable that the source assistant created, set the style class of
the JSF control with the setStyleClass function. For example, to set a text
control to a style class named errorField, add this code:
text1.setStyleClass("errorField");
When this code runs, the style class of the input control is changed. In this
example, the HTML code displayed by the browser looks like this:
<input id="form1:text1" type="text" name="form1:text1" class="errorField" />
Related tasks
“Adding JSF component interface support to an EGL Web project” on page 246
“Accessing the JSF component tree with the source assistant” on page 236
“Changing the style of a JSF control” on page 240
“Changing the target of a JSF link” on page 239
“Enabling or disabling JSF controls” on page 244
“Setting the size of a JSF image” on page 243
“Setting event handlers for a JSF control”
“Setting JSF data table properties” on page 245
Setting event handlers for a JSF control
You can assign a JavaScript function to a JavaServer Faces (JSF) control to serve as
an event handler, or you can remove an event handler from a control. In this
context, an event handler is a JavaScript function that is called when a specific event
happens on the page. For example, you can assign a function to a text input
control using the onClick event handler. When the control is clicked in the
browser, the function defined as the onClick event handler runs.
The JavaScript function that is used as an event handler must be available to the
page, either in a <script> tag on the page itself or in a script file that is linked to
the page. You cannot use an EGL function as an event handler for a JSF control.
This task has the following prerequisites:
v Your EGL Web project must have support for the JSF component interface. See
“Adding JSF component interface support to an EGL Web project” on page 246.
v The JSF Handler that is associated with the Web page must have the following
import statement:
import com.ibm.egl.jsf.*
v You must declare a variable of the type UIViewRoot within the JSF Handler.
v You must specify the name of the of the UIViewRoot variable in the
viewRootVar JSF Handler property.
For more information on these prerequisites, see “Accessing the JSF component
tree with the source assistant” on page 236.
Follow these steps to assign or remove an event handler from a JSF control:
1. On a blank line inside a function in the JSF Handler, press Ctrl+Shift+Z. The
EGL Source Assistant window opens, displaying the JSF controls on the page.
2. In the EGL Source Assistant window, select the JSF image control that you want
to access.
3. Click OK.
The EGL source assistant adds two lines of EGL code to the JSF Handler. The
first line defines an EGL variable of the type that matches the JSF control that
242 EGL Programmer’s Guide
you selected. The second line associates that variable with the JSF control. For
example, the code to access a JSF input text control might look like this:
text1 HtmlInputText;
text1 = myViewRoot.findComponent("form1:text1");
4. Using the EGL variable that the source assistant created, assign or remove the
event handlers. For example, to assign the JavaScript function myFunction() as
the onClick event handler for the text control, add this code:
text1.setOnclick("myFunction");
To remove an event handler from a JSF control, assign it a blank string as an
event handler:
text1.setOnclick("");
Related tasks
“Adding JSF component interface support to an EGL Web project” on page 246
“Accessing the JSF component tree with the source assistant” on page 236
“Changing the style class of a JSF control” on page 241
“Changing the style of a JSF control” on page 240
“Changing the target of a JSF link” on page 239
“Enabling or disabling JSF controls” on page 244
“Setting the size of a JSF image”
“Setting JSF data table properties” on page 245
Setting the size of a JSF image
You can change the size of a JavaServer Faces (JSF) image on a Faces JSP page with
EGL code. You must use a Faces image control; an EGL JSF Handler cannot
directly change ordinary HTML image tags.
This task has the following prerequisites:
v Your EGL Web project must have support for the JSF component interface. See
“Adding JSF component interface support to an EGL Web project” on page 246.
v The JSF Handler that is associated with the Web page must have the following
import statement:
import com.ibm.egl.jsf.*
v You must declare a variable of the type UIViewRoot within the JSF Handler.
v You must specify the name of the of the UIViewRoot variable in the
viewRootVar JSF Handler property.
For more information on these prerequisites, see “Accessing the JSF component
tree with the source assistant” on page 236.
Follow these steps to change the size of a JSF image control with an EGL JSF
Handler:
1. On a blank line inside a function in the JSF Handler, press Ctrl+Shift+Z. The
EGL Source Assistant window opens, displaying the JSF controls on the page.
2. In the EGL Source Assistant window, select the JSF image control that you want
to access.
3. Click OK.
The EGL source assistant adds two lines of EGL code to the JSF Handler. The
first line defines an EGL variable of the type that matches the JSF control that
you selected. The second line associates that variable with the JSF control. For
example, the code to access a JSF image control might look like this:
Building EGL Web applications 243
imageEx1 HtmlGraphicImageEx;
imageEx1 = myViewRoot.findComponent("imageEx1");
4. Using the EGL variable that the source assistant created, change the size of the
JSF image control with the setHeight and setWidth functions, passing each
function a string or literal that specifies the measurement in pixels. For
example, to make the image 300 pixels wide and 200 pixels tall, add this code:
imageEx1.setWidth("300");
imageEx1.setHeight("300");
Related tasks
“Adding JSF component interface support to an EGL Web project” on page 246
“Accessing the JSF component tree with the source assistant” on page 236
“Changing the style class of a JSF control” on page 241
“Changing the style of a JSF control” on page 240
“Changing the target of a JSF link” on page 239
“Enabling or disabling JSF controls”
“Setting event handlers for a JSF control” on page 242
“Setting JSF data table properties” on page 245
Enabling or disabling JSF controls
You can enable or disable JSF input controls and command buttons with EGL code.
A disabled control cannot be edited or changed on the Web page.
This task has the following prerequisites:
v Your EGL Web project must have support for the JSF component interface. See
“Adding JSF component interface support to an EGL Web project” on page 246.
v The JSF Handler that is associated with the Web page must have the following
import statement:
import com.ibm.egl.jsf.*
v You must declare a variable of the type UIViewRoot within the JSF Handler.
v You must specify the name of the of the UIViewRoot variable in the
viewRootVar JSF Handler property.
For more information on these prerequisites, see “Accessing the JSF component
tree with the source assistant” on page 236.
To enable or disable a JSF control with an EGL JSF Handler:
1. On a blank line inside a function in the JSF Handler, press Ctrl+Shift+Z. The
EGL Source Assistant window opens, displaying the JSF controls on the page.
2. In the EGL Source Assistant window, select the JSF control that you want to
access.
3. Click OK.
The EGL source assistant adds two lines of EGL code to the JSF Handler. The
first line defines an EGL variable of the type that matches the JSF control that
you selected. The second line associates that variable with the JSF control. For
example, the code to access a JSF input text control might look like this:
text1 HtmlInputText;
text1 = myViewRoot.findComponent("form1:text1");
4. Using the EGL variable that the source assistant created, enable or disable the
JSF control with the setDisabled function. For example, to enable a text control,
add this code:
text1.setDisabled(no);
244 EGL Programmer’s Guide
To disable the text control, add this code:
text1.setDisabled(yes);
Related tasks
“Adding JSF component interface support to an EGL Web project” on page 246
“Accessing the JSF component tree with the source assistant” on page 236
“Changing the style class of a JSF control” on page 241
“Changing the style of a JSF control” on page 240
“Changing the target of a JSF link” on page 239
“Setting the size of a JSF image” on page 243
“Setting event handlers for a JSF control” on page 242
“Setting JSF data table properties”
Setting JSF data table properties
You can change some of the properties of a JavaServer Faces (JSF) data table on a
Faces JSP page with EGL code.
This task has the following prerequisites:
v Your EGL Web project must have support for the JSF component interface. See
“Adding JSF component interface support to an EGL Web project” on page 246.
v The JSF Handler that is associated with the Web page must have the following
import statement:
import com.ibm.egl.jsf.*
v You must declare a variable of the type UIViewRoot within the JSF Handler.
v You must specify the name of the of the UIViewRoot variable in the
viewRootVar JSF Handler property.
For more information on these prerequisites, see “Accessing the JSF component
tree with the source assistant” on page 236.
To change the properties of a JSF data table control:
1. On a blank line inside a function in the JSF Handler, press Ctrl+Shift+Z. The
EGL Source Assistant window opens, displaying the JSF controls on the page.
2. In the EGL Source Assistant window, select the JSF data table control that you
want to access.
3. Click OK.
The EGL source assistant adds two lines of EGL code to the JSF Handler. The
first line defines an EGL variable of the type that matches the JSF control that
you selected. The second line associates that variable with the JSF control. For
example, the code to access a JSF input text control might look like this:
table1 HtmlDataTable;
table1 = viewRoot.findComponent("table1");
4. Using the EGL variable that the source assistant created, change the properties
of the data table. For example, to change the rowClasses property of the table
to the style class MyRowClass1, add this code:
table1.setRowClasses("MyRowClass1");
To make the rows of the data table alternate between the two style classes
MyRowClass1 and MyRowClass2, add this code:
table1.setRowClasses("MyRowClass1, MyRowClass2");
Related tasks
“Adding JSF component interface support to an EGL Web project” on page 246
Building EGL Web applications 245
“Accessing the JSF component tree with the source assistant” on page 236
“Changing the style class of a JSF control” on page 241
“Changing the style of a JSF control” on page 240
“Changing the target of a JSF link” on page 239
“Enabling or disabling JSF controls” on page 244
“Setting the size of a JSF image” on page 243
“Setting event handlers for a JSF control” on page 242
Adding JSF component interface support to an EGL Web project
Before you can access JavaServer Faces (JSF) components in a Faces JSP file from
EGL code, your EGL Web project must contain the packages that enable you to
access the JSF component tree. You can add these packages when you create an
EGL Web project, or you can add them to an existing EGL Web project by
following these steps:
1. In the Project Explorer view, right-click the EGL Web project and then click
Properties.
2. In the Properties window, click Project Facets.
3. Click Add/Remove Project Facets.
4. Select the EGL support with JSF Component Interfaces check box. If this
check box is already selected, the project already has support for the JSF
component interface.
5. Click Finish.
6. Click OK.
Adding support for the JSF component interface adds a package named
com.ibm.egl.jsf to your project. As explained in “Accessing the JSF component
tree with the source assistant” on page 236, this package contains ExternalType
parts that you can use to access JSF components on the page.
You cannot remove support for the JSF component interface from a project.
Related tasks
“Creating an EGL Web project” on page 63This topic covers how to create an EGL Web project.
“Accessing the JSF component tree with the source assistant” on page 236
Setting preferences for Web projects
These preferences control defaults for EGL Web projects and JSF Handler parts.
To specify preferences for Web projects and JSF Handler parts, follow these steps:
1. From the main menu, click Window → Preferences.
2. From the navigation tree, expand EGL and click Page Designer.
3. In the JSFHandler Package field, specify the location of JSF Handler parts in
your EGL Web projects.
4. In the Loadbundle variable field, set the name of the variable to use to
represent resource bundles in your pages. The default value is labels, but you
can change this value as explained in “Localizing text in Web applications” on
page 214.
5. Set preferences for refactoring EGL Web projects and JSF Handler parts in the
check boxes at the bottom of the page. These check boxes tell EGL to delete the
246 EGL Programmer’s Guide
JSP file that is associated with a JSF Handler if you delete the JSF Handler, and
vice versa. You can also delete the generated output when you delete a JSF
Handler.
6. Click Apply to save the changes and remain in the Preferences window. Click
OK to save the changes and exit the window. Related concepts
“Preferences” on page 147EGL preferences affect the way the workbench displays and works with EGL.
Building EGL Web applications 247
248 EGL Programmer’s Guide
Building and using service applications in EGL
Service applications, within service-oriented architecture, enable you to organize your
programs in a modular, compartmentalized manner.
EGL provides the ability to create service applications and to use services that are
provided by other applications. For an overview of the different ways service
applications can behave, see “Types of service applications” on page 252.
For an overview of the parts and files involved in a service application, see
“Elements of a service application.”
If you want to access a service in your EGL application, see “Calling an external
service” on page 256. If you want to create a service for other applications to use,
see “Exposing a service to other applications” on page 263.
Related concepts
“Elements of a service application”The major elements of an EGL service application are the service part, interface
part, and deployment descriptor file. In general, each of these files and parts
has a role in both service applications and client applications.
“Types of service applications” on page 252In EGL, you have the option of generating your service parts as EGL services or
as Web services. Likewise, your clients can access EGL services or Web services. Related tasks
“Calling an external service” on page 256You can use services that are supplied by external applications in your EGL
logic parts. Using an external service in this way is acting as a client of a
service, or sometimes consuming or invoking a service.
“Exposing a service to other applications” on page 263Your EGL application can act as a service by exposing its functions to other
applications.
“Adding service client binding information from a WSDL file” on page 257Service client binding information tells EGL how to connect to a service at run
time. This topic covers adding binding information to connect to a Web service.
“Adding service client binding information for an EGL service” on page 259Service client binding information tells EGL how to connect to a service at run
time. This topic covers adding binding information to connect to an EGL
service.
Elements of a service application
The major elements of an EGL service application are the service part, interface
part, and deployment descriptor file. In general, each of these files and parts has a
role in both service applications and client applications.
Service part
The service part is a logic part that is customized to be able to expose functions to
other applications. In EGL terms, a service works much like a library:
© Copyright IBM Corp. 1996, 2007 249
v Services are groups of functions. Fundamentally, the functions in a service are no
different than those in a library: they receive parameters, return parameters,
perform logic, and access data.
v Services can encapsulate functions that you want to reuse in other parts of your
application.
v Services can have private functions, functions that can be called only by other
functions in the same service.
v Services are generatable parts. You can have only one service part in a file, and
that file can contain no other generatable parts.
However, services differ from libraries because services are intended to be
modular, stateless ways to expose functions to a client, or an application that can
be outside the EGL application. Unlike libraries, services have the following
characteristics:
v Services can expose their functions to a wide range of applications, not just EGL
applications. EGL services can use standards like the Web Services Definition
Language to expose their functions in a way that many other types of
applications can understand and use.
v Services are stateless, meaning that they do not remember interactions with a
client or change after an interaction with a client. Each time a service is used, it
is as though that service is being used for the first time. In other words, the
global memory of a service is re-initialized every time it is used, while a library
can remember changes in its global memory as long as its run unit is running.
v Client applications can call the functions in a service but they cannot reference
its variables.
This is a example of a simple service part:
Service calculatorService
function addIntegers(intOne int in, intTwo int in)
returns (int)
return (intOne + intTwo);
end
function subtractIntegers(intOne int in, intTwo int in)
returns (int)
return (intOne - intTwo);
end
end
Interface part
An interface part contains function prototypes, or summaries of functions. In this
case, the prototypes summarize functions in a service part. A function prototype
lists the function or method name, its arguments, and its return value, but no
internal logic. See ″Function prototypes″ in the EGL Language Reference for more
information on prototypes.
An interface part is designed to be implemented by one or more service parts. When
a service part implements an interface part, that service part must define each
function that is prototyped in the interface part. Also, the function definitions in
the service part must match the prototypes, using the same name, parameters, and
return value.
250 EGL Programmer’s Guide
Interface parts are rarely required, but they can be helpful in the service
development process:
v The interface enables you to plan the service ahead of time, and EGL warns you
if the service deviates from the interface.
v Interfaces provide a concise summary of a service, explaining what the service
can do without providing all of the details of implementing the service.
v Interfaces can be useful in accessing a service remotely.
v Interfaces can serve as requirements for development or compliance.
This is an example of a simple interface part:
interface calculatorInterface
function addIntegers(intOne int in, intTwo int in)
returns (int);
function subtractIntegers(intOne int in, intTwo int in)
returns (int);
end
To make a service implement an interface, add the implements keyword after the
service name, followed by the interface name. Separate additional interfaces with
commas. Like any type of part, the interface part must be in scope for the service
part to implement it.
import interfaces.calculatorInterface;
Service calculatorService implements calculatorInterface
function addIntegers(intOne int in, intTwo int in)
returns (int)
return (intOne + intTwo);
end
function subtractIntegers(intOne int in, intTwo int in)
returns (int)
return (intOne - intTwo);
end
end
Deployment descriptor file
The EGL deployment descriptor file (not to be confused with J2EE deployment
descriptor files) contains information that describes either how a service part from
your application is exposed to other applications or how an external service will be
used in your application. Therefore, there are two major items in the deployment
descriptor file:
v Service client bindings represent services from other applications that you want to
use in your application’s logic parts. The service client binding information often
includes a WSDL file that describes the external service and the name of an EGL
part in your project that will represent the service within your application.
v Web services deployment information lists service parts in your application that
you want to expose to other applications. The information in the deployment
descriptor includes details about how the service will be deployed and made
available to other applications.
The EGL deployment descriptor is distinct from J2EE deployment descriptors.
Building and using service applications in EGL 251
Web Services Description Language (WSDL) file
Web Services Description Language (WSDL) files are a standard way of
communicating information about Web services. You might encounter WSDL files
in your EGL applications in two areas:
v When acting as a client of a service, you can create parts and binding
information directly from the WSDL file of the particular service. See “Adding
service client binding information from a WSDL file” on page 257 for more
information.
v When you generate a service part as a Web service, EGL creates a WSDL file that
other services can use to call your service. In this case, treat the WSDL file as
you treat any generated output, because it will be overwritten each time you
generate the deployment descriptor file.
For more information on Web Services Description Language (WSDL), see Web
Services Description Language (WSDL).
Related concepts
“Types of service applications”In EGL, you have the option of generating your service parts as EGL services or
as Web services. Likewise, your clients can access EGL services or Web services.
“Building and using service applications in EGL” on page 249Service applications, within service-oriented architecture, enable you to organize
your programs in a modular, compartmentalized manner. Related tasks
“Adding service client binding information from a WSDL file” on page 257Service client binding information tells EGL how to connect to a service at run
time. This topic covers adding binding information to connect to a Web service.
“Adding service client binding information for an EGL service” on page 259Service client binding information tells EGL how to connect to a service at run
time. This topic covers adding binding information to connect to an EGL
service.
Types of service applications
In EGL, you have the option of generating your service parts as EGL services or as
Web services. Likewise, your clients can access EGL services or Web services.
Services and clients
EGL provides the ability to create services, applications that provide logic to other
applications, and clients, applications that use services. Because both of these types
of applications fall under the broader term ″service applications,″ the terminology
and the layout of the applications can be confusing. For example, a service part
can behave both as a service (by providing logic to other applications) and as a
client (by using other services). A brief description of services and clients in EGL
terms follows.
EGL service applications depend on the service part, a logic part similar to a
library but designed to be deployed as a service. A service application can contain
many other parts, but only the service parts can be exposed to other applications.
After you have written the service parts, you expose them to clients by adding
Web service deployment information to the EGL deployment descriptor file. For
details, see “Exposing a service to other applications” on page 263.
252 EGL Programmer’s Guide
A client application is any application that uses the functions provided by a
service. In EGL, any logic part, including a service part, can behave as a client. In
general, you begin by adding service client binding information in the deployment
descriptor that enables EGL to find the service at run time. Also, you must provide
information about the service itself and what functionality it offers, from which
EGL creates parts that represent the service at design time. Then, you use those
parts in your logic parts to access the service. For details, see “Calling an external
service” on page 256.
Types of connections between services and clients
EGL provides two basic ways of connecting services to clients:
v An EGL service connection is the simplest way of connecting an EGL client to an
EGL service.
In this case, you create a service part in the service application and deploy the
application. Then, you create a logic part in the client application and add client
binding information that enables the logic part to access the service part. In this
case, the service application is referred to as an EGL service. Only EGL
applications can access EGL services.
v If either the client or the service is not an EGL application, you must use a Web
service connection.
In this case, you create a service part and then add Web service deployment
information to the project’s deployment descriptor file. The Web service
deployment information tells EGL to add a Web service layer to the service part,
making the service a Web service.
The Web service layer gives non-EGL applications access to the service part. EGL
applications can still create an EGL service connection, bypassing the Web
service layer to access the service part.
The following diagram illustrates how EGL services and Web services can interact
with each other. EGL clients can access the EGL service application directly or
through the Web service layer, while non-EGL applications must access the service
through the Web service layer.
Related concepts
“Building and using service applications in EGL” on page 249Service applications, within service-oriented architecture, enable you to organize
your programs in a modular, compartmentalized manner.
Building and using service applications in EGL 253
“Elements of a service application” on page 249The major elements of an EGL service application are the service part, interface
part, and deployment descriptor file. In general, each of these files and parts
has a role in both service applications and client applications.
“Building and using service applications in EGL” on page 249Service applications, within service-oriented architecture, enable you to organize
your programs in a modular, compartmentalized manner. Related tasks
“Calling an external service” on page 256You can use services that are supplied by external applications in your EGL
logic parts. Using an external service in this way is acting as a client of a
service, or sometimes consuming or invoking a service.
“Exposing a service to other applications” on page 263Your EGL application can act as a service by exposing its functions to other
applications.
Calling a local service
You can call an EGL service that is local to your application without exposing that
service as a Web service.
In this context, a local service is an EGL service part either in your project or in a
project that is in your project’s build path. To access an EGL service outside your
build path, or to access a non-EGL service, see “Calling an external service” on
page 256.
Calling a local EGL service involves these general steps:
1. Create a service part to act as the service.
2. Add client binding information to the deployment descriptor.
3. Create a program or other logic part to act as the client.
4. In the client program, create a variable based on the service part and bind that
variable to the service.
5. Use the variable to access the service.1. Create a service part with the functions that you want to expose to your client.
A simple example of a service part follows:
service CalculatorService
function addIntegers(intOne int in, intTwo int in)
returns (int)
return (intOne + intTwo);
end
function subtractIntegers(intOne int in, intTwo int in)
returns (int)
return (intOne - intTwo);
end
end
2. Save and generate the service part.
3. Create client binding information in the deployment descriptor file. The client
binding information tells EGL where to find the service part at run time.
a. Open the client project’s deployment descriptor file. If the project does not
have a deployment descriptor file, create a new one and add it as the value
254 EGL Programmer’s Guide
of the deploymentDescriptor build descriptor option. For more information,
see “Creating a deployment descriptor file” on page 80.
b. On the Service Client Bindings page of the deployment descriptor editor,
under the heading Service Client Bindings, click Add. The Add a Service
Binding window opens.
c. In the Add a Service Binding window, click EGL Binding and then click
Next.
d. Next to the EGL Binding Name field, click Browse.
e. In the EGL Interface Selection window, select the service part that you want
to access and click OK.
The Service Name field is populated with the fully qualified name of the
service part, and the EGL Binding Name field is populated with the default
name for the client binding. You can change the name if you want to. In
this case, the default name is be the same as the service part, or
CalculatorService.
f. Under Choose protocol type, click Local.
g. Click Finish.
h. Save, close, and generate the deployment descriptor.
Now the deployment descriptor has service client binding information that
points to the local service.
4. Create a program or other logic part to act as the client. The program part that
acts as the client must either be in the same project as the service part, or the
service part must be in the client’s build path.
5. In the client program, create a variable based on the service part. The service
part must be in scope.
import services.CalculatorService;
program localClientProgram type BasicProgram
localEGLService CalculatorService;
function main()
end
end
6. Apply the @BindService complex property to the variable and set the
bindingKey property field to the name of the client binding. In the previous
examples, this binding was named CalculatorService.
import services.CalculatorService;
program localClientProgram type BasicProgram
localEGLService CalculatorService
{@BindService{bindingKey = "CalculatorService"}};
function main()
end
end
7. After you have created a variable that represents a service and bound that
service to the service part using the client binding information, you can use the
service through the variable:
import services.CalculatorService;
program localClientProgram type BasicProgram
Building and using service applications in EGL 255
localEGLService CalculatorService
{@BindService{bindingKey = "CalculatorService"}};
function main()
SysLib.writeStderr("Calling local EGL service: ");
outputString string;
outputString = "5+5=";
outputString += localEGLService.addIntegers(5,5);
SysLib.writeStderr(outputString);
end
end
8. Save, generate, and run the program.
Related tasks
“Building and using service applications in EGL” on page 249Service applications, within service-oriented architecture, enable you to organize
your programs in a modular, compartmentalized manner.
“Creating an Interface part” on page 94
“Creating a service part” on page 92
“Creating a deployment descriptor file” on page 80The EGL deployment descriptor file describes how EGL service applications are
linked to clients, and how EGL service clients are linked to the service
applications they use.
Calling an external service
You can use services that are supplied by external applications in your EGL logic
parts. Using an external service in this way is acting as a client of a service, or
sometimes consuming or invoking a service.
Fundamentally, calling a service is equivalent to calling a function in an EGL
library: you specify the name of the function in the service, pass any required
arguments, and receive any return variable. However, there are several additional
steps that you need to perform to make sure that EGL can find and use the
external service at run time.
Calling an external service has the following general steps:
1. In your deployment descriptor file, you create service client binding
information that tells EGL where to find the service at run time. There are two
main ways of creating these bindings:
v If you have a Web Services Description Language (WSDL) file from a Web
service, you can select that WSDL file and EGL will create the binding
information for you. See “Adding service client binding information from a
WSDL file” on page 257.
v If you are using an EGL service directly, enter the location of that service and
fill in the information for the connection, such as its protocol and location.
See “Adding service client binding information for an EGL service” on page
259 for more information.2. You also need an interface part or service part that represents the external
service at design time:
v If you created the binding information from a WSDL file, EGL can create an
interface part automatically from the information in the WSDL file. See
“Adding service client binding information from a WSDL file” on page 257
for more information.
256 EGL Programmer’s Guide
v If you are using an EGL service, you can copy an interface part or service
part from the other application.
v Alternatively, you can create your own interface part. In this case, it is up to
you to ensure that the function prototypes in the interface part accurately
represent the real functions in the service.3. In a logic part, you create a variable that is based on the interface part or
service part, bind that variable to the service using the binding information,
and then use the service through the variable. See “Creating and binding a
variable to an external service” on page 260 for more information. Related tasks
“Building and using service applications in EGL” on page 249Service applications, within service-oriented architecture, enable you to organize
your programs in a modular, compartmentalized manner.
“Adding service client binding information from a WSDL file”Service client binding information tells EGL how to connect to a service at run
time. This topic covers adding binding information to connect to a Web service.
“Adding service client binding information for an EGL service” on page 259Service client binding information tells EGL how to connect to a service at run
time. This topic covers adding binding information to connect to an EGL
service.
“Calling a local service” on page 254You can call an EGL service that is local to your application without exposing
that service as a Web service.
“Creating and binding a variable to an external service” on page 260After you have created binding information for an external service, you can use
the service in an EGL logic part with a variable that represents the service.
Adding service client binding information from a WSDL file
Service client binding information tells EGL how to connect to a service at run
time. This topic covers adding binding information to connect to a Web service.
To add binding information for an EGL service, see “Adding service client binding
information for an EGL service” on page 259.
Prerequisites
v An EGL project or EGL Web project
v An EGL deployment descriptor
v A Web Services Description Language (WSDL) file that describes the service you
want to use, located somewhere in your workspace.
Adding the service client binding information
1. Open the EGL deployment descriptor in the deployment descriptor editor.
2. On the Service Client Bindings tab, under the Service Client Bindings
heading, click Add.
3. In the Add a Service Binding window, click Web Binding and then click Next.
4. Next to the WSDL File field, click Browse. You can select the Choose WSDL
file from workspace and copy it to the current project if the WSDL file is not
in your EGL project.
5. In the Folder Selection window, select the WSDL file and click OK.
Building and using service applications in EGL 257
6. You can accept the default value for the Web Binding Name or type in a
different name. This name will be the value of the bindingKey property field
when you use the service in your logic parts.
7. Under Interface Options, click Generate EGL Interface from WSDL file. This
is the preferred method for creating an interface part to represent the service
at design time.
However, you can also create your own interface part and select it under Use
existing EGL interface. In this case, it is up to you to ensure that the function
prototypes in the interface part accurately represent the real functions in the
service.
8. Click Next.
9. On the New EGL Interface page, select the interfaces that you want to use
from the WSDL file.
10. Click Next.
11. On the next page, each interface has a tab on which each function in the
selected interfaces is listed. You can select or clear the check box for any of the
functions to choose which functions will be in the new interface part.
12. Set the location and name for the new interface part in the Source folder,
Package, and EGL source file name fields.
13. Click Finish.
Now you can create variables based on the interface part and use these variables to
access the service. See “Creating and binding a variable to an external service” on
page 260.
Shortcut
You can add client binding information directly from a WSDL file in your project
with the following shortcut:
1. In the Project Explorer view, right-click the WSDL file and then click Create
EGL Interfaces and Web Client Binding.
2. On the New EGL Interface page, select the interfaces you want to use from
the WSDL file.
3. Click Next.
4. On the next page, each interface has a tab on which each function in the
selected interfaces is listed. You can select or clear the check box for any of the
functions to choose which functions will be in the new interface part.
5. Set the location and name for the new interface part in the Source folder,
Package, and EGL source file name fields.
6. Click Next.
7. In the EGL deployment descriptor file name field, select the name of the
deployment descriptor file to add information to.
8. If you want to update information already in a deployment descriptor file,
select the Update all existing bindings check box.
9. In the table of ports, select the ports that you want to generate into interfaces.
You can change the binding name, which is the label for the Web service
deployment listing in the deployment descriptor file.
10. Click Finish. Related tasks
258 EGL Programmer’s Guide
“Creating a deployment descriptor file” on page 80The EGL deployment descriptor file describes how EGL service applications are
linked to clients, and how EGL service clients are linked to the service
applications they use.
“Adding service client binding information for an EGL service”Service client binding information tells EGL how to connect to a service at run
time. This topic covers adding binding information to connect to an EGL
service.
“Creating and binding a variable to an external service” on page 260After you have created binding information for an external service, you can use
the service in an EGL logic part with a variable that represents the service.
Adding service client binding information for an EGL service
Service client binding information tells EGL how to connect to a service at run
time. This topic covers adding binding information to connect to an EGL service.
To add binding information for a Web service, see “Adding service client binding
information from a WSDL file” on page 257.
Prerequisites
v An EGL project
v An EGL deployment descriptor
v An interface part or service part that represents the external service at design
time:
– If the EGL service part that you want to use is either in your project or in a
project in your project’s build path, you can use that part directly as a local
service. See “Calling a local service” on page 254 for more information.
– You can copy a service part or interface part from another EGL project to use
in your project.
– If you do not have access to the other project, you can create an interface part
with functions that match the functions in the service. In this case, it is up to
you to ensure that the function prototypes in the interface part accurately
represent the real functions in the service.
Adding the service client binding information
To add the service client binding information:
1. Open the deployment descriptor in the deployment descriptor editor.
2. On the Service Client Bindings tab, under the Service Client Bindings
heading, click Add.
3. In the Add a Service Binding window, click EGL Binding and then click Next.
4. On the Add an EGL Binding page, click the Browse button, which is next to
the EGL Binding Name field.
5. In the EGL Interface Selection window, select the interface part or service part
that you will use to represent the service and click OK.
6. You can accept the default value for the EGL Binding Name or type a different
name. This name will be the value of the bindingKey property field when you
use the service in your logic parts.
7. Choose a protocol type for the client binding:
v If you have already defined a shared protocol for the service, click Choose
from protocols and select the shared protocol from the list.
Building and using service applications in EGL 259
v Choose LOCAL for a service in the same project or within your project’s
build path.
v Otherwise, choose a specific protocol type such as CICSJ2C or TCPIP and
then fill in the information for the binding in the Attributes list.8. Click Finish. The new client binding is listed in the Service Bindings list. You
can update the binding information later by selecting the client binding and
editing the information under EGl Service Binding.
Now you can use the binding in your code as explained in “Creating and binding
a variable to an external service.”
Alternately, if you have the service part in your workspace already, you can create
the binding information directly from that service part. Right-click the part and
then click EGL Services → Create EGL Service Client Binding. Then, choose a
deployment descriptor file and fill in the protocol and attribute information for the
binding as in the steps above.
Related tasks
“Building and using service applications in EGL” on page 249Service applications, within service-oriented architecture, enable you to organize
your programs in a modular, compartmentalized manner.
“Creating a deployment descriptor file” on page 80The EGL deployment descriptor file describes how EGL service applications are
linked to clients, and how EGL service clients are linked to the service
applications they use.
“Adding service client binding information from a WSDL file” on page 257Service client binding information tells EGL how to connect to a service at run
time. This topic covers adding binding information to connect to a Web service.
“Calling a local service” on page 254You can call an EGL service that is local to your application without exposing
that service as a Web service.
“Creating and binding a variable to an external service”After you have created binding information for an external service, you can use
the service in an EGL logic part with a variable that represents the service.
Creating and binding a variable to an external service
After you have created binding information for an external service, you can use the
service in an EGL logic part with a variable that represents the service.
The topic “Elements of a service application” on page 249 lists a few similarities
and differences between EGL services and libraries. In short, a service behaves
much like a library in that they are both a group of functions that are available for
use by other logic parts. However, calling a service requires more preparation than
calling a library.
When you call a function within a library, you type the name of the library, a
period, and the name of the function, followed by any arguments the function
expects:
myInt int = MathLib.abs(-5);
A call to a function within a service looks the same because the call uses similar
syntax:
mySum int = Calculator.addIntegers(1, 2);
260 EGL Programmer’s Guide
However, the call to a service is different because the code is not calling the service
directly (as the example above called MathLib.abs() directly), but instead is using
a variable that represents that service. In the previous example, Calculator is a
variable that is created from a service part or interface part and then linked, or
bound, to the service itself. The binding information in the deployment descriptor
file tells EGL how bind that variable to the service at run time.
Prerequisites
v An EGL project
v Client binding information for a Web service or an EGL service. See “Adding
service client binding information from a WSDL file” on page 257 or “Adding
service client binding information for an EGL service” on page 259 for more
information.
v An interface part or service part bound to the external service. See “Calling an
external service” on page 256.
v Any EGL logic part, such as a program, library, service, or handler for more
information.
Binding a variable explicitly
To bind a variable to an external service, create a variable from an interface or
service part and then set the property field bindingKey to the name attribute of
the service binding information entry in the deployment descriptor file.
For example, assume that you created the following entry in the deployment
descriptor file while working through the topic “Adding service client binding
information from a WSDL file” on page 257:
<webBinding interface="interfaces.StockQuote"
name="quoteBinding"/>
This entry is named quoteBinding and refers to an interface part or service part in
the interfaces package named StockQuote.
You can use the service that this entry represents by creating a variable that is
based on the part listed in the entry and specifying the name of the entry in the
bindingKey property field:
myQuoteGenerator stockQuote {@BindService{bindingKey = "quoteBinding"}};
Then you can call the functions in the service through the variable:
myStockPrice float = myQuoteGenerator.getQuote("IBM");
If you do not specify a value in the bindingKey property field, EGL assumes that
the name of the entry in the deployment descriptor matches the name of the
interface part or service part. For example, assume the following entry in the
deployment descriptor file:
<webBinding interface="interfaces.CalculatorService"
name="CalculatorService"/>
In this case, you can omit the bindingKey property field, but the @BindService
complex property is still required:
myCalculator CalculatorService {@BindService};
mySum int = myCalculator.addIntegers(1, 1);
Building and using service applications in EGL 261
Binding a variable dynamically
Dynamic binding enables you to choose a service at run time, or to change the
service to which a variable is bound. To bind a variable dynamically, use functions
in the EGL library ServiceLib instead of the @BindService property.
Suppose that you have created entries in the deployment descriptor file for two
slightly different service implementations:
<webBinding interface="interfaces.SpeechTranslator"
name="TranslateSpanish" port="SpanishPort"/>
<webBinding interface="interfaces.SpeechTranslator"
name="TranslateGerman" port="GermanPort"/>
You could create and bind two variables, one for each of these entries. An alternate
way is to create one variable based on the interface part that the entries share, and
then use the ServiceLib.bindService() system function to bind the variable to the
service that you want to use.
1. Create a variable that is based on the interface or service part in the
deployment descriptor entry:
myTranslator SpeechTranslator;
2. Use the bindService() function to bind the variable to the service
implementation:
myTranslator = ServiceLib.bindService("TranslateSpanish");
In this case, the myTranslator variable is now bound to the entry in the
deployment descriptor file named TranslateSpanish.
3. Use the variable to access the service:
mySpanishString string = myTranslator.translate
("This sentence is in Spanish");
4. Later, you can use bindService() again to bind the service to a different
implementation:
myTranslator = ServiceLib.bindService("TranslateGerman");
5. At this point, you can use the variable to access the alternate implementation of
the service:
myGermanString string = myTranslator.translate
("This sentence is in German");
Related tasks
“Adding service client binding information for an EGL service” on page 259Service client binding information tells EGL how to connect to a service at run
time. This topic covers adding binding information to connect to an EGL
service.
“Adding service client binding information from a WSDL file” on page 257Service client binding information tells EGL how to connect to a service at run
time. This topic covers adding binding information to connect to a Web service.
“Calling an external service” on page 256You can use services that are supplied by external applications in your EGL
logic parts. Using an external service in this way is acting as a client of a
service, or sometimes consuming or invoking a service.
262 EGL Programmer’s Guide
Exposing a service to other applications
Your EGL application can act as a service by exposing its functions to other
applications.
Creating an EGL service has these general steps:
1. Optionally, define one or more interface parts. Interface parts contain function
prototypes, which list the function’s name, its parameters, and its return value,
but have no internal logic.
2. Code one or more EGL service parts and any other parts they may need.
3. Add binding information for the service in the EGL deployment descriptor file.
4. Distribute the binding information for your service so other applications can
connect to your service
Creating an interface (optional)
To create an interface:
1. Create an EGL interface part. You can put the interface part in the same
package as your service or in another package; the scoping rules for interfaces
are the same as for any other part. See “Creating an Interface part” on page 94.
2. In the interface part, write function prototypes that describe the functions your
service performs, including the name of the function, its parameters and their
types, and its return value, if any:
package interfaces;
interface calculatorInterface
function addIntegers(intOne int in, intTwo int in)
returns (int);
function subtractIntegers(intOne int in, intTwo int in)
returns (int);
end
Provide prototypes in the interface only for the functions that you intend to
expose to other applications. These functions are referred to as public. The
service can contain functions that are not described in the interface, and those
additional functions can optionally be defined as private. Only the service itself
can access its private functions, but any logic part or application can access the
public functions of the service. Functions in a service are public by default.
Coding a service part
You code a service part in much the same way as a library part.
1. Create an EGL service part. See “Creating a service part” on page 92.
2. If you want the service part to use an interface, add an implements clause to
the service part:
package services;
service calculatorService implements interfaces.calculatorInterface
//Add functions here.
end
Building and using service applications in EGL 263
Alternately, you can select an interface to implement when you create the
service. In this case, EGL creates stub functions for the functions that are
defined in the interface.
When a service implements an interface, that service must define each function
that is listed in the interface, and the input and output parameters of those
functions must match those of the prototypes in the interface. EGL produces an
error if any function in a service does not match the prototype of the same
name in the interface, as well as if any function prototype in the interface is not
defined in the service. Also, a service can implement more than one interface.
In that case, the service must define each function that is prototyped in each
interface.
3. Write the code for the functions in the service, including any functions defined
in the interface and any private functions your services may need:
package services;
service calculatorService implements interfaces.calculatorInterface
function addIntegers(intOne int in, intTwo int in)
returns (int)
return(intOne + intTwo);
end
function subtractIntegers(intOne int in, intTwo int in)
returns (int)
return(intOne - intTwo);
end
private function getAbsoluteValueInteger(intOne int in)
returns(int)
return(MathLib.abs(intOne));
end
end
Adding Web service deployment information
Now, EGL client applications can access your service part directly as described in
“Adding service client binding information for an EGL service” on page 259.
However, for non-EGL client applications to access the service, you must expose
your service as a Web service, which involves adding Web service deployment
information to the deployment descriptor file. See “Adding Web service
deployment information to the deployment descriptor” on page 265.
Distribute the binding information
After you have coded and deployed your service application, you must distribute
its information so client applications can use the service. For an EGL client
application to access your service, you need only distribute the binding
information that the client needs to complete the steps in “Adding service client
binding information for an EGL service” on page 259. For a non-EGL client
application to access the service, or for an EGL client application to access the
service through a Web service connection, you must distribute the WSDL file that
is created when you generate the project.
Related tasks
“Creating an Interface part” on page 94
“Creating a service part” on page 92
264 EGL Programmer’s Guide
“Creating a deployment descriptor file” on page 80The EGL deployment descriptor file describes how EGL service applications are
linked to clients, and how EGL service clients are linked to the service
applications they use.
Adding Web service deployment information to the
deployment descriptor
After you have coded a service part that you want to expose as a Web service, you
must add information to the deployment descriptor that tells EGL to generate the
necessary Web service wrapper.
Prerequisites
v An EGL project
v A Service part
v An EGL deployment descriptor file
Adding the deployment information
1. Open the EGL deployment descriptor file and go to the Web Service
Deployment tab.
2. Click Add.
3. In the Add Web Services window, select the service parts to be exposed as a
Web service by moving them from the EGL service parts found list to the EGL
service parts to be generated as Web services list.
4. Click Finish. Each service part that you chose is listed on the Web Services
Deployment page.
5. Select a service part in the list and provide the basic information for the service
in the other fields in the table:
v Select the Generate check box if you want EGL to re-generate the Web
service wrapper each time you generate the project. You might want to avoid
generating the Web service wrapper if you are not changing the service part
because generating a Web service wrapper can be time consuming.
v In the Style field, select document-wrapped.6. Provide deployment information for each service under Generate Web Service.
7. Save and generate the deployment descriptor file. Related concepts
“Elements of a service application” on page 249The major elements of an EGL service application are the service part, interface
part, and deployment descriptor file. In general, each of these files and parts
has a role in both service applications and client applications.
“Building and using service applications in EGL” on page 249Service applications, within service-oriented architecture, enable you to organize
your programs in a modular, compartmentalized manner. Related tasks
“Exposing a service to other applications” on page 263Your EGL application can act as a service by exposing its functions to other
applications.
Building and using service applications in EGL 265
Creating and using a shared protocol
Shared protocols are reusable definitions of a service connection that you can apply
to one or more of the entries in an EGL deployment descriptor file.
To create and use a shared protocol:
1. Open the EGL deployment descriptor file for your project. If your project does
not have a deployment descriptor file, see “Creating a deployment descriptor
file” on page 80.
2. On the Service Client Bindings page of the deployment descriptor editor,
expand the Sharable Protocols section.
3. Under Sharable Protocols, click Add. The Add Protocol window opens.
4. In the Protocol Name, enter a mnemonic for the new protocol.
5. Under Choose protocol type, select a type of protocol. Use Local for services in
the same project, TCPIP for EGL services, Java400 for Web services on iSeries,
or a CICS protocol for Web services on CICS.
6. Under Attributes, set the options for the protocol. These options differ for each
type of protocol.
7. Click Finish. The new protocol is listed under Sharable Protocols, and you can
use that protocol when you create a new service client binding or Web service
binding.
Related tasks
“Calling an external service” on page 256You can use services that are supplied by external applications in your EGL
logic parts. Using an external service in this way is acting as a client of a
service, or sometimes consuming or invoking a service.
“Adding service client binding information from a WSDL file” on page 257Service client binding information tells EGL how to connect to a service at run
time. This topic covers adding binding information to connect to a Web service.
“Adding service client binding information for an EGL service” on page 259Service client binding information tells EGL how to connect to a service at run
time. This topic covers adding binding information to connect to an EGL
service.
266 EGL Programmer’s Guide
Building EGL Console User Interface applications
Console User Interface, or Console UI, is a style of user interface similar to that
used on a UNIX-based program that interacts with a character-based terminal.
As the term character-based suggests, a console user interface shows only text on the
screen, no graphics or buttons, and it responds only to the keyboard, not the
mouse. However, with EGL, you to enhance your Console UI programs with
mouse functionality and rich client widgets by running your applications in rich
client platform (RCP) mode. See “Console UI modes” on page 281.
Related concepts
“Elements of a Console UI application”A Console UI application can use several different types of EGL parts to supply
data and several different types of EGL variables to create the interface.
“Console UI modes” on page 281EGL supports three modes in which you can run Console UI applications:
Swing, Curses, and rich client platform (RCP). The three modes have different
abilities, but in general a Console UI application behaves the same way in each
mode. Related tasks
“Creating a Console User Interface” on page 269Console UI relies on the openUI statement to define which forms and fields are
shown on the interface, which variables those forms and fields are bound to,
and which actions happen when the user performs tasks in the interface.
“Adding rich client widgets to a Console UI program” on page 272When running in rich client platform (RCP) mode, you can use additional
Console UI components called widgets to add additional functionality.
“Running Console UI applications” on page 280The process for running a Console UI application differs slightly depending on
the mode you are running in.
Elements of a Console UI application
A Console UI application can use several different types of EGL parts to supply
data and several different types of EGL variables to create the interface.
Like many types of applications with user interfaces, EGL Console UI applications
separate the interface from the logic used to create that interface. An ordinary EGL
program provides the logic for the application, while several different types of
parts can represent the interface itself.
Console UI forms and fields
A ConsoleForm part is a record of fields to be shown on the user interface. The
fields in this type of record do not store data or have a data type such as INT like
the fields in other types of records. Instead, the fields in a ConsoleForm define the
location and label of the fields that are shown on the screen. As a group, these
fields are sometimes referred to as a form. The Console UI program links the fields
on the screen with other EGL variables.
© Copyright IBM Corp. 1996, 2007 267
A field in a console UI record can be as simple as a name, a length in characters,
and a position on the screen. For example, here is a simple Console UI record that
defines a form:
Record CustomerConsoleRecord type consoleForm
{formSize = [10,40],name = "Customer Record"}
* consoleField {position = [1,4],
value = "Welcome to my console."};
ID consoleField {fieldLen = 5, position = [3,4],
name="customer_id"};
Fname consoleField {fieldLen = 20, position = [4,4],
name="first_name"};
Lname consoleField {fieldLen = 20, position = [5,4],
name="last_name"};
PhoneNum consoleField {fieldLen = 20, position = [6,4],
name="phone"};
end
Of the five fields in this form, one is a constant string of text; it cannot change at
run time. This field is named with an asterisk (*) and serves as header or
explanatory text, in this case ″Welcome to my console.″ The other fields are
variable; a Console UI program can use them to display data or accept input.
Menu and MenuItem parts
In Console UI, a menu is a set of options from which the user is expected to
choose one. When showing a menu on the interface, you define a menu part and
then define the options as an array of menuItem parts in the menuItems menu
property. For example, the following menu defines three options from which the
user can choose:
new Menu {labelText = "Choose an option: ",
menuItems = [
new MenuItem{name = "One", labelText = "Option One"},
new MenuItem{name = "Two", labelText = "Option Two"},
new MenuItem{name = "Three", labelText = "Option Three"}
]}
See “Creating a Console User Interface” on page 269 for an example of how to
respond when the user selects one of the options.
ArrayDictionary part
An ArrayDictionary is a type of EGL part that is often used to represent data in
Console UI. Unlike an array of records, in which you define one record part that
represents a row and then create an array of those rows, in an ArrayDictionary,
you define arrays of consoleFields that represent the columns. Defining data by the
columns can be useful in Console UI because ArrayDictionaries scroll automatically
in the limited space on a Console UI window.
Console UI program
The Console UI program is an ordinary EGL program that creates and controls the
interface. In general, it creates a Window variable, uses functions in the EGL
library ConsoleLib to display that window, and then populates that window with
parts that represent the interface, such as ConsoleForm parts. Here is a simple
example of a Console UI program that uses the sample ConsoleForm part
described above:
program CreateAConsole type BasicProgram
function main()
268 EGL Programmer’s Guide
// Step 1: Create a variable for the form.
myConsoleUIRecord CustomerConsoleRecord;
// Step 2: Create a window, but don’t open it yet.
myWindow window {name="My Window", position=[1,1]};
// Step 3: Create variables for the form fields.
customer_id int;
first_name, last_name, phone char(30);
// Step 4: Open the window and open the form inside the window.
consoleLib.openWindowWithForm(myWindow,myConsoleUIRecord);
// Step 5: Link the variables to the fields in the form.
openUI myConsoleUIRecord
bind customer_id, first_name, last_name, phone
end
end
end
For more information on using Console UI programs, see “Creating a Console User
Interface.”
The EGL Plug-in project
With EGL, you can run your Console UI projects in a variety of modes. If you
want to run your Console UI application in rich client application (RCP) mode,
you need to convert your project to an EGL plug-in project.
For more information about the modes you can run your Console UI application
in, see “Console UI modes” on page 281. For more information on EGL plug-in
projects, see “Creating an EGL plug-in project” on page 65.
Related tasks
“Creating a Console User Interface”Console UI relies on the openUI statement to define which forms and fields are
shown on the interface, which variables those forms and fields are bound to,
and which actions happen when the user performs tasks in the interface.
“Adding rich client widgets to a Console UI program” on page 272When running in rich client platform (RCP) mode, you can use additional
Console UI components called widgets to add additional functionality.
“Running Console UI applications” on page 280The process for running a Console UI application differs slightly depending on
the mode you are running in.
Creating a Console User Interface
Console UI relies on the openUI statement to define which forms and fields are
shown on the interface, which variables those forms and fields are bound to, and
which actions happen when the user performs tasks in the interface.
Opening and populating a window
The simplest way to create a Console UI is to create a window variable that
represents a user interface window and use a function such as
consoleLib.displayForm() to open the form in the window.
program basicConsole type BasicProgram
function main()
Building EGL Console User Interface applications 269
myWindow Window {name = "My Window",
position = [1,1]};
myConsoleRec CustomerConsoleRecord{name = "myForm"};
ConsoleLib.openWindow(myWindow);
ConsoleLib.displayForm(myConsoleRec);
end
end
Record CustomerConsoleRecord type consoleForm
{formSize = [10,40],name = "Customer Record"}
* consoleField {position = [1,4],
value = "Welcome to my console."};
ID consoleField {fieldLen = 5, position = [3,4],
name="customer_id"};
Fname consoleField {fieldLen = 20, position = [4,4],
name="first_name"};
Lname consoleField {fieldLen = 20, position = [5,4],
name="last_name"};
PhoneNum consoleField {fieldLen = 20, position = [6,4],
name="phone"};
end
However, this interface is not very useful because it does not enable the user to
interact with the form or window at all. Because this form does not enable any
interaction, the window closes as soon as it opens. You need to bind EGL variables
to the fields with the openUI statement to make the fields on the interface
meaningful and keep the window open while the user works with the interface.
Binding data to the fields in the window
Like many other types of applications with user interfaces, Console UI applications
separate the interface from the data being managed by the interface. When you
create a Console UI in EGL, you create the interface with parts like consoleForms
and then use the openUI statement to connect, or bind, those parts to variables in
your program. Then, when the person using the interface changes a value in the
consoleForm, the value of the variable changes to match. Conversely, when your
code changes the value of the variable, the value in the form changes to match.
The following example expands on the previous example to bind four variables to
the four editable fields in the consoleForm:
program basicConsole type BasicProgram
function main()
myWindow Window {name = "My Window", position = [1,1]};
myConsoleRec CustomerConsoleRecord{name = "myForm"};
ConsoleLib.openWindow(myWindow);
ConsoleLib.displayForm(myConsoleRec);
customer_id int;
first_name, last_name, phone char(30);
openUI myConsoleRec
bind customer_id, first_name, last_name, phone
end
end
end
270 EGL Programmer’s Guide
Record CustomerConsoleRecord type consoleForm
{formSize = [10,40],name = "Customer Record"}
* consoleField {position = [1,4],
value = "Welcome to my console."};
ID consoleField {fieldLen = 5, position = [3,4],
name="customer_id"};
Fname consoleField {fieldLen = 20, position = [4,4],
name="first_name"};
Lname consoleField {fieldLen = 20, position = [5,4],
name="last_name"};
PhoneNum consoleField {fieldLen = 20, position = [6,4],
name="phone"};
end
Now when you run this program, the window stays open so the user can tab
through the fields and type values. The line of code that begins openUI
myConsoleRec bind customer_id... specifies that the fields in the myConsoleRec are
bound to the variables listed in the bind clause.
Responding to events in the window
For your Console UI to react to actions that the user performs in the form, you
must define event handlers that tell EGL what to do in response to the action. An
event handler contains EGL statements like a function, but it begins with a
description of an event, such as a key being pressed or a value being typed in a
field. When the user presses a key or types a value in a field, the event handler
that is associated with that action is called.
The following example adds an event handler to the previous example. This event
handler is called when the user types a value in the customer_id field and moves
the cursor out of the field:
program basicConsole type BasicProgram
function main()
myWindow Window {name = "My Window", position = [1,1]};
myConsoleRec CustomerConsoleRecord{name = "myForm"};
ConsoleLib.openWindow(myWindow);
ConsoleLib.displayForm(myConsoleRec);
customer_id int;
first_name, last_name, phone char(30);
openUI myConsoleRec
bind customer_id, first_name, last_name, phone
onEvent(AFTER_FIELD:"customer_id")
if (customer_id == 3)
first_name = "John";
end
end
end
end
Record CustomerConsoleRecord type consoleForm
{formSize = [10,40],name = "Customer Record"}
* consoleField {position = [1,4],
value = "Welcome to my console."};
ID consoleField {fieldLen = 5, position = [3,4],
Building EGL Console User Interface applications 271
name="customer_id"};
Fname consoleField {fieldLen = 20, position = [4,4],
name="first_name"};
Lname consoleField {fieldLen = 20, position = [5,4],
name="last_name"};
PhoneNum consoleField {fieldLen = 20, position = [6,4],
name="phone"};
end
To respond when a user chooses an option in a menu, use the MENU_ACTION
event handler:
program menuTest type BasicProgram
function main()
openUI
new Menu {labelText = "Choose an option",
menuItems = [
new MenuItem{name = "One",labelText = "Option One"},
new MenuItem{name = "Two",labelText = "Option Two"},
new MenuItem{name = "Exit",labelText = "Exit"}
]}
onEvent(MENU_ACTION:("Exit"))
exit openUI;
onEvent(MENU_ACTION:("One"))
consolelib.displayAtLine("You chose option One", 5);
onEvent(MENU_ACTION:("Two"))
consolelib.displayAtLine("You chose option Two", 5);
end
end
end
In this example, the window provides a feedback message when the user selects
one of the first two options and closes when the user selects the ″Exit″ menu
option.
For other kinds of event handlers, see ″openUI″ in the EGL Language Reference.
Related tasks
“Adding rich client widgets to a Console UI program”When running in rich client platform (RCP) mode, you can use additional
Console UI components called widgets to add additional functionality.
“Running Console UI applications” on page 280The process for running a Console UI application differs slightly depending on
the mode you are running in.
Adding rich client widgets to a Console UI program
When running in rich client platform (RCP) mode, you can use additional Console
UI components called widgets to add additional functionality.
Rich client widgets enable a Console UI interface to behave less like a
character-based interface and more like a graphical user interface. EGL supports
the following rich client widgets:
v buttons
v check boxes
v radio button groups
v combo boxes (also called list boxes or drop-down boxes)
272 EGL Programmer’s Guide
In general, using a rich client widget in your Console UI program involves these
steps:
1. Create the widget as a field in a console form and specify the properties for the
field.
2. In the Console UI program, create a variable to represent the state of the
widget:
v For check boxes, create a BOOLEAN variable.
v For combo boxes or radio button groups, create an INT variable.
v For buttons, no variable is needed.3. With the bind clause of the openUI statement, bind the variable to the widget.
This step is not required for button widgets because the button widgets do not
need a variable.
4. Create an event handler for the widget:
v For check boxes, use the ConsoleCheckbox.STATE_CHANGED event.
v For combo boxes, use the ConsoleCombo.SELECTION_CHANGED event.
v For radio button groups, use the
ConsoleRadiogroup.SELECTION_CHANGED event.
v For buttons, use the ConsoleButton.PUSHED event.
See the following topics:
v “Adding a button widget” on page 274
v “Adding a check box widget” on page 276
v “Adding a combo box or radio button group widget” on page 278
These widgets are supported only when running in RCP mode. See “Console UI
modes” on page 281.
Related concepts
“Elements of a Console UI application” on page 267A Console UI application can use several different types of EGL parts to supply
data and several different types of EGL variables to create the interface.
“Console UI modes” on page 281EGL supports three modes in which you can run Console UI applications:
Swing, Curses, and rich client platform (RCP). The three modes have different
abilities, but in general a Console UI application behaves the same way in each
mode. Related tasks
“Creating a Console User Interface” on page 269Console UI relies on the openUI statement to define which forms and fields are
shown on the interface, which variables those forms and fields are bound to,
and which actions happen when the user performs tasks in the interface.
“Running Console UI applications” on page 280The process for running a Console UI application differs slightly depending on
the mode you are running in.
“Adding a combo box or radio button group widget” on page 278The combo box and radio button group are similar because they both require
the user to select a single option from a group of options.
“Adding a check box widget” on page 276Unlike the button widget, the check box widget has a state; it is either checked
or not checked. Therefore, you must bind a boolean variable to the check box,
just like you would bind a text variable to a text field in a console form. When
Building EGL Console User Interface applications 273
the user selects the check box, the variable is set to TRUE, and when the user
clears the check box, the variable is set to FALSE.
“Adding a button widget”The button widget is the simplest rich client widget because it does not need to
maintain a state like the others. You only need to create the button and specify
an event handler to run when the button is clicked.
Adding a button widget
The button widget is the simplest rich client widget because it does not need to
maintain a state like the others. You only need to create the button and specify an
event handler to run when the button is clicked.
1. In a console form, create the button by using the consoleButton predefined
part. This part represents the button widget.
Record buttonForm type ConsoleForm {formSize=[12,40]}
myButton consoleButton
{name = "simpleButton",
text = "Click here",
bounds=[4,4,1,15]};
end
2. At minimum, specify the following properties for the button:
name A mnemonic that you will use later to link the button to an event
handler
text The label for the button
bounds
An array of four integers that represent the row, column, height, and
width of the button, respectively3. Within an openUI statement, specify an event handler for the button’s
PUSHED event:
onEvent(ConsoleButton.PUSHED : "simpleButton")
SysLib.writeStderr("You pushed the button.");
A complete example of a Console UI program that uses a button in this way
follows.
In the file programs/simpleButton.egl:
package programs;
import forms.buttonForm
program simpleButton type BasicProgram
textValue string;
counter int=0;
function main()
myWindow WINDOW {name="myWindow",
position = [1,1]};
openWindow(myWindow);
myForm buttonForm {};
displayForm(myForm);
keepGoing boolean = true;
while (keepGoing == true)
openUI { bindingByName=no }
myForm
bind textValue
OnEvent(ConsoleButton.PUSHED : "simpleButton")
274 EGL Programmer’s Guide
counter+=1;
textValue = "You have clicked the button "
+counter+" times.";
SysLib.writeStderr(textValue);
onEvent(ConsoleButton.PUSHED : "exitButton")
keepGoing = false;
end
end
end
end
In the file forms/buttonForm.egl:
package forms;
record buttonForm type ConsoleForm { formsize=[12,40] }
introText consoleField
{name="introText",
position = [1,1],
fieldLen = 20};
myButton consoleButton
{name = "simpleButton",
text = "Click here",
bounds=[4,4,1,15]};
exitButton consoleButton
{name = "exitButton",
text = "Click to exit",
bounds=[6,4,1,15]};
end
Related concepts
“Elements of a Console UI application” on page 267A Console UI application can use several different types of EGL parts to supply
data and several different types of EGL variables to create the interface.
“Console UI modes” on page 281EGL supports three modes in which you can run Console UI applications:
Swing, Curses, and rich client platform (RCP). The three modes have different
abilities, but in general a Console UI application behaves the same way in each
mode. Related tasks
“Creating a Console User Interface” on page 269Console UI relies on the openUI statement to define which forms and fields are
shown on the interface, which variables those forms and fields are bound to,
and which actions happen when the user performs tasks in the interface.
“Running Console UI applications” on page 280The process for running a Console UI application differs slightly depending on
the mode you are running in.
“Adding rich client widgets to a Console UI program” on page 272When running in rich client platform (RCP) mode, you can use additional
Console UI components called widgets to add additional functionality.
“Adding a combo box or radio button group widget” on page 278The combo box and radio button group are similar because they both require
the user to select a single option from a group of options.
“Adding a check box widget” on page 276Unlike the button widget, the check box widget has a state; it is either checked
or not checked. Therefore, you must bind a boolean variable to the check box,
just like you would bind a text variable to a text field in a console form. When
the user selects the check box, the variable is set to TRUE, and when the user
clears the check box, the variable is set to FALSE.
Building EGL Console User Interface applications 275
Adding a check box widget
Unlike the button widget, the check box widget has a state; it is either checked or
not checked. Therefore, you must bind a boolean variable to the check box, just
like you would bind a text variable to a text field in a console form. When the user
selects the check box, the variable is set to TRUE, and when the user clears the
check box, the variable is set to FALSE.
1. In a console form, create the check box by using the consoleCheckbox
predefined part.
Record checkForm type ConsoleForm {formSize=[12,40]}
myCheck consoleCheckbox
{name = "simpleCheck",
text = "Click here",
bounds=[4,4,1,15]};
end
2. At minimum, specify the following properties for the check box:
name A mnemonic that you will use later to link the check box to an event
handler
text The label for the check box
bounds
An array of four integers that represent the row, column, height, and
width of the check box, respectively3. Create a boolean variable to represent the state of the check box:
checkState boolean = false;
4. With an openUI statement, open the form and bind the variable to the check
box:
myForm checkForm {};
openUI myForm
bind checkState
//event handlers go here
end
5. Within the openUI statement, specify an event handler for the check box’s
STATE_CHANGED event:
onEvent(ConsoleCheckbox.STATE_CHANGED : "simpleCheck")
if (checkState == true)
SysLib.writeStderr("Checked");
else
SysLib.writeStderr("Cleared");
end
A complete example of a Console UI program that uses a check box in this way
follows:
In the file programs/simpleCheckbox.egl:
package programs;
import forms.checkForm;
program simpleCheckbox type BasicProgram
function main()
myWindow WINDOW {name="myWindow", position = [1,1]};
openWindow(myWindow);
myForm checkForm {};
displayForm(myForm);
276 EGL Programmer’s Guide
textValue string = "Text.";
keepGoing boolean = true;
myCheckVar boolean = false;
while (keepGoing == true)
openUI myForm
bind textValue, myCheckVar
onEvent(ConsoleButton.PUSHED : "exitButton")
keepGoing = false;
onEvent(ConsoleCheckbox.STATE_CHANGED : "simpleCheck")
if (myCheckVar == true)
textValue = "Checked";
else
textValue = "Cleared";
end
end
end
end
end
In the file forms/checkForm.egl:
package forms;
record checkForm type ConsoleForm { formsize=[12,40] }
introText consoleField
{name="introText",
position = [1,1],
fieldLen = 20};
myCheck consoleCheckbox
{name="simpleCheck",
text="Checkbox",
bounds=[3,5,1,15]};
exitButton consoleButton
{name = "exitButton",
text = "Click to exit",
bounds=[6,4,1,15]};
end
Related concepts
“Elements of a Console UI application” on page 267A Console UI application can use several different types of EGL parts to supply
data and several different types of EGL variables to create the interface.
“Console UI modes” on page 281EGL supports three modes in which you can run Console UI applications:
Swing, Curses, and rich client platform (RCP). The three modes have different
abilities, but in general a Console UI application behaves the same way in each
mode. Related tasks
“Creating a Console User Interface” on page 269Console UI relies on the openUI statement to define which forms and fields are
shown on the interface, which variables those forms and fields are bound to,
and which actions happen when the user performs tasks in the interface.
“Running Console UI applications” on page 280The process for running a Console UI application differs slightly depending on
the mode you are running in.
“Adding rich client widgets to a Console UI program” on page 272When running in rich client platform (RCP) mode, you can use additional
Console UI components called widgets to add additional functionality.
Building EGL Console User Interface applications 277
“Adding a combo box or radio button group widget”The combo box and radio button group are similar because they both require
the user to select a single option from a group of options.
“Adding a button widget” on page 274The button widget is the simplest rich client widget because it does not need to
maintain a state like the others. You only need to create the button and specify
an event handler to run when the button is clicked.
Adding a combo box or radio button group widget
The combo box and radio button group are similar because they both require the
user to select a single option from a group of options.
Like the check box widget, these two widgets must be bound to a variable that
represents their states. However, instead of a boolean variable, the combo box and
radio button group must be bound to an INT variable to represent the index of the
currently selected option.
1. In a console form, create the widget using the predefined parts:
Record radioComboForm type ConsoleForm { formsize=[12,40] }
myRadio consoleRadiogroup
{name = "radio", bounds = [3,1,3,15]};
myCombo consoleCombo
{name = "combo", bounds = [8,1,1,15]};
end
2. At minimum, specify the following fields for the widget:
name A mnemonic that you will use later to link the widget to an event
handler
bounds
An array of four integers that represent the row, column, height, and
width of the widget, respectively3. Create an integer variable to represent the state of the widget:
radioValue, comboValue int = 2;
4. Between creating the form variable and displaying the form in a window,
define the options in the widget with an array of string variables or literals:
myWindow WINDOW {name="myWindow", position = [1,1]};
openWindow(myWindow);
myForm radioComboForm {};
myForm.myCombo.items =
["Option One", "Option Two", "Option Three"];
myForm.myRadio.items =
["Option Four", "Option Five", "Option Six"];
displayForm(myForm);
5. With an openUI statement, open the form and bind the variables to the
widgets:
openUI myForm
bind radioValue, comboValue
//event handlers go here
end
6. Within the openUI statement, specify an event handler for the widget’s
SELECTION_CHANGED event:
onEvent (ConsoleRadioGroup.SELECTION_CHANGED : "radio")
SysLib.writeStderr("Radio selected: "+radioValue);
onEvent (ConsoleCombo.SELECTION_CHANGED : "combo")
SysLib.writeStderr("Combo selected: "+comboValue);
278 EGL Programmer’s Guide
A complete example of a Console UI program that uses a combo box widget and
radio button group widget in this way follows:
In the file programs/simpleRadioCombo.egl:
package programs;
import forms.radioComboForm;
program simpleRadioCombo type BasicProgram
radioValue, comboValue int = 2;
radioString, comboString string = "";
function main()
myWindow WINDOW
{name="myWindow", position = [1,1]};
openWindow(myWindow);
myForm radioComboForm {};
myForm.myCombo.items =
["Option One", "Option Two", "Option Three"];
myForm.myRadio.items =
["Option Four", "Option Five", "Option Six"];
displayForm(myForm);
keepGoing boolean = true;
while (keepGoing == true)
openUI { bindingByName=no }
myForm
bind radioString, radioValue, comboString, comboValue
onEvent (ConsoleRadiogroup.SELECTION_CHANGED : "radio")
radioString = "Radio selected: "+radioValue;
onEvent (ConsoleCombo.SELECTION_CHANGED : "combo")
comboString = "Combo selected: "+comboValue;
onEvent(ConsoleButton.PUSHED : "exitButton")
keepGoing = false;
end
end
end
end
In the file forms/radioComboForm.egl:
package forms;
record radioComboForm type ConsoleForm { formsize=[12,40] }
radioText consoleField
{name="radioText",
position = [1,1],
fieldLen = 20};
myRadio consoleRadiogroup
{name = "radio",
bounds = [3,1,3,15]};
comboText consoleField
{name="comboText",
position = [7,1],
fieldLen = 20};
myCombo consoleCombo
{name = "combo",
bounds = [8,1,1,15]};
exitButton consoleButton
{name = "exitButton",
text = "Click to exit",
bounds=[10,4,1,15]};
end
Building EGL Console User Interface applications 279
Related concepts
“Elements of a Console UI application” on page 267A Console UI application can use several different types of EGL parts to supply
data and several different types of EGL variables to create the interface.
“Console UI modes” on page 281EGL supports three modes in which you can run Console UI applications:
Swing, Curses, and rich client platform (RCP). The three modes have different
abilities, but in general a Console UI application behaves the same way in each
mode. Related tasks
“Creating a Console User Interface” on page 269Console UI relies on the openUI statement to define which forms and fields are
shown on the interface, which variables those forms and fields are bound to,
and which actions happen when the user performs tasks in the interface.
“Running Console UI applications”The process for running a Console UI application differs slightly depending on
the mode you are running in.
“Adding rich client widgets to a Console UI program” on page 272When running in rich client platform (RCP) mode, you can use additional
Console UI components called widgets to add additional functionality.
“Adding a check box widget” on page 276Unlike the button widget, the check box widget has a state; it is either checked
or not checked. Therefore, you must bind a boolean variable to the check box,
just like you would bind a text variable to a text field in a console form. When
the user selects the check box, the variable is set to TRUE, and when the user
clears the check box, the variable is set to FALSE.
“Adding a button widget” on page 274The button widget is the simplest rich client widget because it does not need to
maintain a state like the others. You only need to create the button and specify
an event handler to run when the button is clicked.
Running Console UI applications
The process for running a Console UI application differs slightly depending on the
mode you are running in.
For information on the different modes available for Console UI applications, see
“Console UI modes” on page 281.
Running in Swing or Curses mode
Running in Swing or Curses mode is no different from running any EGL
application generated to Java:
1. Save all changed files and generate the project.
2. In your EGL project, expand the JavaSource folder and find the Java program
to which your program part was generated. The Java file has the same name as
your program part, but with a .java extension.
3. Right-click the program file and then click Run As → Java Application.
280 EGL Programmer’s Guide
Running in RCP mode
To run a Console UI program in rich client platform (RCP) mode, the Console UI
program must be in an EGL plug-in project. See “Creating an EGL plug-in project”
on page 65.
Running a Console UI program in RCP mode is different from running other types
of EGL programs because you run the application from the EGL file, not the Java
file:
1. Save all changed files and generate the project.
2. In your EGL project, right-click the file that contains the Console UI program
part and then click Run As RCP. The program opens in a new window. In this
window, you can use the enhanced GUI features of the workbench, including
using the mouse to select fields, and copying and pasting text between fields. Related concepts
“Building EGL Console User Interface applications” on page 267Console User Interface, or Console UI, is a style of user interface similar to that
used on a UNIX-based program that interacts with a character-based terminal.
“Console UI modes”EGL supports three modes in which you can run Console UI applications:
Swing, Curses, and rich client platform (RCP). The three modes have different
abilities, but in general a Console UI application behaves the same way in each
mode.
Console UI modes
EGL supports three modes in which you can run Console UI applications: Swing,
Curses, and rich client platform (RCP). The three modes have different abilities,
but in general a Console UI application behaves the same way in each mode.
Swing mode
Swing mode is the default mode for Console UI applications. If you write a
Console UI program, generate it, and run the generated Java source without
making any other changes, the resulting program runs in Swing mode. A Console
UI application running in Swing mode uses Java Swing libraries to simulate a
UNIX® interface like that of Curses mode.
Curses mode
Curses mode is similar to Swing mode, but Curses mode is intended for users who
use telnet to access a UNIX system or who use a terminal device.
To use Curses mode you must add the EGL Curses library to your project and then
run the application in the same way as you would run it in Swing mode. Follow
these steps to install the EGL Curses library:
1. Locate the appropriate EGL Support Web site.
2. Download the EGLRuntimesV70.zip file to a directory of your choice.
3. Unzip EGLRuntimesV70.zip to identify the following files:
v AIX: EGLRuntimes/Aix/bin/libCursesCanvas6.so
v Linux: EGLRuntimes/Linux/bin/libCursesCanvas6.so
4. Insert the appropriate EGL curses library in the Library Path environment
variable.
Building EGL Console User Interface applications 281
AIX: Set the ’LIBPATH’ Library Path environment variable by using the
following bourne-shell:
"LIBPATH=$INSTDIR/aix; export LIBPATH"
Linux: Set the ’LD_LIBRARY_PATH’ Library Path environment variable by
using the following bourne-shell:
"LD_LIBRARY_PATH=$INSTDIR/aix; export LD_LIBRARY_PATH"
After you have added the EGL Curses library to your project, Curses mode
becomes the default mode for running Console UI applications. If you run the
generated Java output from a Console UI program, that program runs in Curses
mode.
RCP mode
Rich client platform (RCP) mode is similar to Swing mode, except that in RCP
mode, EGL applications use SWT libraries instead of Swing libraries. The resulting
application has graphical user interface fields (like fields in a Web page form or in
a wizard in the Eclipse workbench) in place of the character-based fields. Also,
RCP applications have mouse functionality and enhanced keyboard functionality,
enabling you to copy and paste text between fields. Finally, RCP mode supports
enhanced UI components, or widgets, that the other modes do not, such as
drop-down boxes, check boxes, and clickable buttons.
The other modes do not support these widgets, which means that you can run an
application designed for another mode in RCP mode, but you can generally not
run an application designed for RCP mode in another mode.
A Console UI program behaves similarly in RCP mode as in Swing or Curses
mode. The main difference is that you can use the mouse and enhanced keyboard
features of the workbench in a RCP program. However, because these features are
now enabled, the user might be able to make the program behave differently in
RCP mode:
v Because the mouse is enabled in RCP mode, the user can skip between fields in
any order, where in the other modes the user must move between fields in a
specific order.
v Because copying and pasting text is enabled in RCP mode, keyboard
combinations like Ctrl+X might behave differently in RCP mode.
Formatting masks are not supported in RCP mode.
Related concepts
“Building EGL Console User Interface applications” on page 267Console User Interface, or Console UI, is a style of user interface similar to that
used on a UNIX-based program that interacts with a character-based terminal. Related tasks
“Running Console UI applications” on page 280The process for running a Console UI application differs slightly depending on
the mode you are running in.
282 EGL Programmer’s Guide
Creating reports with EGL
EGL offers different ways to create reports, using external engines to generate the
report contents.
You can use any of the following methods to create a report:
v The JasperReports engine creates reports in formats including PDF, HTML,
comma-separated, and plain text.
v The EGL text report engine creates plain text reports.
Each engine has its particular advantages and drawbacks, as detailed in the
following sections. One common drawback is that these reports run on Java only.
You must create custom report programs for COBOL.
JasperReports engine
The JasperReport engine allows the greatest complexity. You use a design file to
dictate the layout, which can be quite complex. You can nest as many subreports as
you want to any depth, passing information to the subreport from the report or
subreport that calls it. The addition of an EGL JasperReports handler means you
can create dynamic reports that respond to events that occur as the report is
generated, such as reaching maximum values on subtotals, or changing between
various commission structures. Output options include PDF, HTML, XML, plain
text, and comma separated values (CSV) for use with Excel.
With greater flexibility comes increased effort required in using the product.
Mastering the design file is difficult enough that third-party applications are
available to help you. These applications, including JasperReports, are third-party
products, not affiliated with IBM.
If all you need is a simple text report, JasperReports may be a more powerful tool
than you need, like using a jet plane for a short trip down the street.
EGL text report engine
The EGL text report engine draws on EGL parts such as the generic Handler,
Delegate, and ExternalType. It is particularly useful for the migration of reports
from I4GL. You can use the Handler part to respond to a limited list of specific
events during the output of report data. Your data source can be anything you can
read from in EGL. It should take far less time to create a simple report design with
this engine than with JasperReports or BIRT.
As the name implies, the only available output format for the EGL text report
engine is a plain text file (though you may also direct output to stdout).
Creating reports with JasperReports
EGL uses the JasperReports framework to create reports in several formats,
including PDF, HTML, comma-separated values, and plain text.
To create and export a report using the JasperReports framework in EGL, follow
these general steps:
© Copyright IBM Corp. 1996, 2007 283
1. Create and compile a JasperReports report design file. See “Creating the report
design file” on page 285.
2. Write a report driver program. See “Writing code to drive a report” on page
289.
3. Optionally, create a report handler with additional functions that are called by
the report design file. See “Creating an EGL report handler” on page 292.
4. Generate the project and run the report driver program. See “Running a report”
on page 296
EGL does not require that you perform these tasks in a particular order, but you
must be aware of dependencies between the files. For example, if your report
design file calls functions in the report handler, you must write and generate the
report handler first and then compile the report design file. EGL compiles the
report design file each time you save a change to the report design file, or you can
direct EGL to compile the report design file by clicking Project → Clean → Clean all
projects.
EGL does not automatically refresh exported reports. If you change the report
design or if the data used in the report changes, you must run the report driver
program again.
Related tasks
“Creating the report design file” on page 285The report design file specifies the layout and appearance of the report. Unless
you import a working design file (with the extension .jasper), you will need to
create or modify a report design file.
“Writing code to drive a report” on page 289A report-driver program is an ordinary EGL program that runs a report using a
.jasper file that is compiled from a report design file.
“Creating an EGL report handler” on page 292
“Running a report” on page 296
Elements of an EGL report application
The main elements of a JasperReport application in EGL are a program to run the
report and a report design file to control the layout of the report. Additionally, a
report handler can give you greater control over the data put into the report.
Report design file
The report design file is an XML file with a .jrxml extension that describes how the
report will look and where the data will be displayed. You can code the XML file
yourself or use a third-party tool. The workbench does not provide a graphical
way to create report design files.
When you have finished writing the report design file, EGL compiles it into a
.jasper file, which your report driver program uses to create the report. For more
information on the report design file and an example, see “Creating the report
design file” on page 285.
Report driver program
Generally, an EGL program does the work of populating the report with data and
exporting its output. The report driver program performs the following tasks:
v Creates a Report variable to represent the report
284 EGL Programmer’s Guide
v Populates that report variable with a report design file and information about
where the completed report will go
v Creates a ReportData variable to represent the data in the report
v Connects to a data source, retrieves data for the report, and puts that data into
the ReportData variable
v Calls functions in the EGL library ReportLib to run and export the report
For an example of a report driver program, see “Writing code to drive a report” on
page 289.
Report handler
The report handler is an EGL logic part that provides additional functions to be
executed when the report runs. You can define a function in the report handler and
then call that function from a specific place in the report design file. Also, the
report automatically calls functions in the report handler at certain points during
the report-creation process. For example, the report calls functions in the report
handler before the report runs, after it runs and at the beginning and end of each
page.
The report handler is optional. You can manipulate much of the data and the
appearance of the report from the report driver program and the report design file,
but you might want to use a report handler if you need to respond to events in the
report.
Related concepts
“Creating reports with EGL” on page 283EGL offers different ways to create reports, using external engines to generate
the report contents. Related tasks
“Creating the report design file”The report design file specifies the layout and appearance of the report. Unless
you import a working design file (with the extension .jasper), you will need to
create or modify a report design file.
“Writing code to drive a report” on page 289A report-driver program is an ordinary EGL program that runs a report using a
.jasper file that is compiled from a report design file.
“Creating an EGL report handler” on page 292
“Running a report” on page 296
Creating the report design file
The report design file specifies the layout and appearance of the report. Unless you
import a working design file (with the extension .jasper), you will need to create or
modify a report design file.
For more detailed information than you will find in this topic, see the following
Web site:
http://jasperforge.org
You can use a file with the .xml extension for your source, although this can slow
your compilation. JasperReports works best with the .jrxml extension.
To add a design document to a package, follow these steps:
Creating reports with EGL 285
1. Create a design document in one of the following ways:
v Use a third-party JasperReports design tool (like JasperAssistant or iReport).
Make sure the file you create has a .jrxml extension.
v Use a text editor to write JasperReports XML source information into a new
text file and save the file as a .jrxml file.2. Place the XML design document in the same EGL package as your report
driver file and optional EGL report handler.
3. Customize the XML source file to use one of the following data sources:
v When you have a fairly simple, straightforward database query, create a
report of the type DataSource.databaseConnection. Include your SQL query
in the XML design file source. The EGL report driver passes your connection
information to JasperReports.
v When you need to perform complex database operations, or need to build
your SQL statement dynamically, create a report of the type
DataSource.sqlStatement. The EGL report driver includes your SQL query
and passes the result set to JasperReports.
v When your data comes from somewhere other than a database, create a
report of the type DataSource.reportData. The EGL report driver passes
complete report data to JasperReports; no connection information is
necessary.4. Compile the source file.
An example of a report design file follows:
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE jasperReport PUBLIC
"//JasperReports//DTD Report Design//EN"
"http://jasperreports.sourceforge.net/dtds/jasperreport.dtd">
<jasperReport name="simpleReport">
<field name="CUSTOMER_ID" class="java.lang.String" />
<field name="FIRST_NAME" class="java.lang.String" />
<field name="LAST_NAME" class="java.lang.String" />
<field name="PHONE" class="java.lang.String" />
<pageHeader>
<band height="30">
<staticText>
<reportElement x="0" y="0" width="70" height="24" />
<text>
<![CDATA[Customer ID: ]]>
</text>
</staticText>
<staticText>
<reportElement x="140" y="0" width="70" height="24" />
<text>
<![CDATA[First name: ]]>
</text>
</staticText>
<staticText>
<reportElement x="280" y="0" width="70" height="24" />
<text>
<![CDATA[Last name: ]]>
</text>
</staticText>
<staticText>
<reportElement x="420" y="0" width="70" height="24" />
<text>
<![CDATA[Phone: ]]>
286 EGL Programmer’s Guide
</text>
</staticText>
</band>
</pageHeader>
<detail>
<band height="30">
<textField>
<reportElement x="0" y="0" width="70" height="24" />
<textFieldExpression>
<![CDATA[$F{CUSTOMER_ID}]]>
</textFieldExpression>
</textField>
<textField>
<reportElement x="140" y="0" width="70" height="24" />
<textFieldExpression>
<![CDATA[$F{FIRST_NAME}]]>
</textFieldExpression>
</textField>
<textField>
<reportElement x="280" y="0" width="70" height="24" />
<textFieldExpression>
<![CDATA[$F{LAST_NAME}]]>
</textFieldExpression>
</textField>
<textField>
<reportElement x="420" y="0" width="70" height="24" />
<textFieldExpression>
<![CDATA[$F{PHONE}]]>
</textFieldExpression>
</textField>
</band>
</detail>
</jasperReport>
This example report design file prints four columns of information: an ID number,
a first name, a last name, and a phone number. The <pageHeader> section prints
column headers, and the <detail> section prints rows of data based on the data
provided by the report driver program.
The following sections offer specifics for the different types of XML source files.
This information covers very simple cases; for more complex examples see either
the JasperReports Web site mentioned earlier or the documentation for your design
tool (if you decide to use one).
EGL source files of the type DataSource.databaseConnection
Include connection information in your EGL source file and include your SQL
query in the XML design file source. Here is the syntax for a very simple case:
<queryString><![CDATA[SELECT * FROM Table_Name]]></queryString>
Table_Name
Name of a table from your database
Define the specific fields (tied to columns in the SQL result set) you want to use:
<field name="Field_Name" class="java.lang.class_type"></field>
Field_Name
A column name in the result set from the query in your design file. The field
Creating reports with EGL 287
names must conform to Java variable name conventions. You can use aliases
for column names within your SQL statement to handle duplicate names,
illegal characters (such as ″.″), or other conflicts.
Class_Type
A java.lang class, such as Integer or String, that identifies the type of data to
which Field_Name refers
Place the fields on the report with a TextFieldExpression tag:
<textFieldExpression class="java.lang.class_type">
<![CDATA[$F{Field_Name}]]>
</textFieldExpression>
EGL source files of the type DataSource.sqlStatement
Place your SQL statement in the EGL report driver file. You can either specify your
connection explicitly in your report driver or use the default connection in your
build descriptor. In the XML design file, define the specific fields that you want to
print on the report. The field names refer to column names in your SQL
statement’s result set:
<field name="Field_Name" class="java.lang.class_type"></field>
Field_Name
A column name in the result set that was created by the query in your EGL
report driver. The field names must conform to Java variable name
conventions. You can alias the column names within your SQL statement if
necessary.
Class_Type
A java.lang class such as Integer or String, identifying the type of data to
which Field_Name refers
Place the fields on the report with a TextFieldExpression tag:
<textFieldExpression class="java.lang.class_type">
<![CDATA[$F{Field_Name}]]>
</textFieldExpression>
EGL source files of the type DataSource.reportData
In this instance, you do not use a database, so you do not need a connection or
SQL statement, either in your XML source or in the EGL report driver. Instead
define the specific fields that you want to use from the records that you create in
the EGL report driver:
<field name="Field_Name" class="java.lang.class_type"></field>
Field_Name
The name of a field exactly as you specify it in your EGL source file
Class_Type
A java.lang class such as Integer or String, identifying the type of data to
which Field_Name refers
Place the fields on the report with a TextFieldExpression tag:
<textFieldExpression class="java.lang.class_type">
<![CDATA[$F{Field_Name}]]>
</textFieldExpression>
Compiling the XML design file source
EGL automatically compiles any .jrxml file that it finds in the package directory in
the EGL source folder, provided that these conditions are true:
v The .jrxml file has changed
288 EGL Programmer’s Guide
v The .jrxml file is free of errors
v The javac compiler is in your execution path
EGL places the compiled .jasper file in the JavaSource\package_name directory that
is parallel to EGLSource\package_name. When you successfully generate your EGL
report driver, the product places a linked copy of the .jasper file in the parallel
bin\package_name directory. You can manually create and copy the .jasper file by
selecting Project → Build All or Project → Clean.
If you are creating an XML design document and a report handler simultaneously,
see EGL report creation process overview for guidelines. For an example that shows
how an XML design document gets a report data record from the report handler,
see Creating an EGL report handler.
Related concepts
“Creating reports with EGL” on page 283EGL offers different ways to create reports, using external engines to generate
the report contents. Related tasks
“Creating an EGL report handler” on page 292
“Writing code to drive a report”A report-driver program is an ordinary EGL program that runs a report using a
.jasper file that is compiled from a report design file.
Writing code to drive a report
A report-driver program is an ordinary EGL program that runs a report using a
.jasper file that is compiled from a report design file.
The following example shows a report driver program that uses data from a
specified database connection:
program reportDriverProgram type BasicProgram
function main()
SQLLib.defineDatabaseAlias("customer",
"jdbc:derby:C:\\databases\\CustomerDatabase");
SQLLib.connect("customer", "admin", "admin");
myReport Report = new Report();
myReportData ReportData = new ReportData();
myReport.reportDesignFile =
"C:\\Workspace\\MyProject\\bin\\reportModel.jasper";
myReport.reportDestinationFile = "C:\\temp.jrprint";
myReport.reportExportFile = "C:\\MyReport.pdf";
myReportData.connectionName = "customer";
myReportData.sqlStatement =
"select * from EGL.CUSTOMER order by CUSTOMER_ID desc";
myReport.reportData = myReportData;
reportLib.fillReport(myReport, DataSource.sqlStatement);
reportLib.exportReport(myReport, ExportFormat.pdf);
end
end
Because the backslash character (\) is used in escape sequences, you must use a
double backslash in path names.
Creating reports with EGL 289
The following table explains the code in the previous example:
Code Explanation
SQLLib.defineDatabaseAlias("customer",
"jdbc:derby:C:\\databases
\\CustomerDatabase");
SQLLib.connect("customer",
"admin", "admin");
Connects to a database and defines an alias
for the database using functions in the EGL
library SQLLib
myReport Report = new Report(); Creates a new report variable to represent
the report
myReportData ReportData =
new ReportData();
Creates a new report data variable to
represent the data in the report
myReport.reportDesignFile =
location;
Sets the location of the .jasper file that is
compiled from the report design file
myReport.reportDestinationFile =
location;
Sets the location of a temporary file that is
used while processing the report
myReport.reportExportFile =
location;
Sets the location of the exported report
myReportData.connectionName =
"customer";
Sets the database connection that the report
uses, in terms of the database alias defined
earlier
myReportData.sqlStatement =
SQL statement;
Sets the database access statement that
provides the data for the report
myReport.reportData = myReportData; Associates the report variable with the
report data variable
reportLib.fillReport(myReport,
DataSource.sqlStatement);
Fills the report with data
reportLib.exportReport(myReport,
ExportFormat.pdf);
Runs and exports the report
Populating a report from a customized record
The following code snippet shows how you might fill a report using your own
internal record as the data source. First, define a record like the following example,
somewhere outside the program:
Record myRecord type BasicRecord
author String;
description String;
title String;
end
Next, write the function to fill and drive the report:
//Variable declarations
myReport Report = new Report();
myReportData ReportData = new ReportData();
recArray myRecord[];
recArrayElement myRecord;
//Function containing the report driving code
function makeReport()
//Initialize report file locations
myReport.reportDesignFile =
"c:\\workspace\\report_project\\" ::
"bin\\report_package\\myReport.jasper";
myReport.reportDestinationFile =
290 EGL Programmer’s Guide
"c:\\temp\\myReport.jrprint";
//Get the report data
populateReportData();
myReport.reportData = myReportData;
//Fill the report with data
reportLib.fillReport(myReport, DataSource.reportData);
//Export the report in HTML format
myReport.reportExportFile = "c:\\temp\\myReport.html";
reportLib.exportReport(myReport, ExportFormat.html);
end
function populateReportData()
recArrayElement.author="Jane Austen";
recArrayElement.title="Northanger Abbey";
recArrayElement.description = "British Novel";
recArray.appendElement(recArrayElement);
recArrayElement.author = "Jane Austen";
recArrayElement.title="Emma";
recArrayElement.description = "British Novel";
recArray.appendElement(recArrayElement);
recArrayElement.author = "Charles Dickens";
recArrayElement.title="Our Mutual Friend";
recArrayElement.description = "British Novel";
recArray.appendElement(recArrayElement);
recArrayElement.author = "Gustave Flaubert";
recArrayElement.title="Madame Bovary";
recArrayElement.description = "French Novel";
recArray.appendElement(recArrayElement);
recArrayElement.author = "M. Lermontov";
recArrayElement.title="Hero of Our Time";
recArrayElement.description = "Russian Novel";
recArray.appendElement(recArrayElement);
end
Choosing an export format
JasperReports saves filled report data as an intermediate destination file (extension
.jrprint), from which it can create multiple export files. You can export filled
reports as PDF, HTML, XML, CSV (comma-separated values that spreadsheet
programs can read), and plain text output. To export the report, use the
reportLib.exportReport() function in the EGL report-driver program with the
report variable and a parameter that indicates the format of the report.
The reportLib.exportReport() function recognizes the following parameters:
v ExportFormat.html
v ExportFormat.pdf
v ExportFormat.text
v ExportFormat.xml
v ExportFormat.csv
For example, the following code causes JasperReports to export a report as a PDF
file:
myReport.ReportExportFile = "c:\\temp\\my_report.pdf";
reportLib.exportReport(myReport, ExportFormat.pdf);
Creating reports with EGL 291
Important: JasperReports does not automatically refresh exported reports. If you
change the report design or if data changes, you must refill and re-export the
report.
Related concepts
“Creating reports with EGL” on page 283EGL offers different ways to create reports, using external engines to generate
the report contents. Related tasks
“Creating an EGL report handler”
“Creating the report design file” on page 285The report design file specifies the layout and appearance of the report. Unless
you import a working design file (with the extension .jasper), you will need to
create or modify a report design file.
“Using report templates” on page 297
Creating an EGL report handler
An EGL report handler provides blocks of code that the JasperReports engine can
access at run time. Predefined function names tie some of these code blocks to
events that occur when JasperReports fills a report. Such events might include the
beginning or end of a page, the beginning or end of a line item, or the beginning
or end of the report itself. You can call other, custom functions directly from the
XML design file source.
To create an EGL report handler, do as follows:
1. Identify a project or folder to contain the file. If you do not already have a
project or folder, you must create one.
2. In the workbench, click File → New → Other.
3. In the New window, expand EGL.
4. Click Report Handler.
5. Click Next.
6. Select the project or folder that will contain the EGL source file and then select
a package.
7. In the EGL Source File Name field, type the name of the report handler source
file. Because the report handler name will be identical to the file name, choose
a file name that adheres to EGL part name conventions (for example,
myReportHandler).
8. Click Finish.
The New EGL Report Handler wizard will give you a list of function names that
correspond to report fill events. For example, JasperReports will invoke
″beforePageInit()″ before entering a page. You must create the code for these
functions.
Alternatively, you can add this template information to an existing file by
following these steps:
1. Create a new EGL source file.
2. Type handler and then press Ctrl+space.
The remainder of this topic contains code examples that show the following items:
v The outline of a generic report handler
v How to get report parameters in a report-handler
292 EGL Programmer’s Guide
v How to get and set report variables
v How to get field values
v How to add a report data record
v How to pass report data to an XML design document
v How to invoke a custom report handler function from the XML design
document
These few examples cannot address all the complexities possible in a report
handler. For more detail, see the JasperReports documentation.
Report handler template
This is the template code that by the New EGL Report Handler wizard creates:
handler handlerName type jasperReport
// Use Declarations
use usePartReference;
// Constant Declarations)
const constantName constantType = literal;
// Data Declarations
identifierName declarationType;
// Pre-defined Jasper callback functions
function beforeReportInit()
end
function afterReportInit()
end
function beforePageInit()
end
function afterPageInit()
end
function beforeColumnInit()
end
function afterColumnInit()
end
function beforeGroupInit(stringVariable string)
end
function afterGroupInit(stringVariable string)
end
function beforeDetailEval()
end
function afterDetailEval()
end
end
Getting report parameters
Reports can contain three types of items: parameters (set in the XML file and do
not change), variables (changeable by the XML file or the report handler) and
fields (keyed to names in the data source). The following code snippet shows how
to get report parameters in a report handler:
Creating reports with EGL 293
handler my_report_handler type jasperReport
// Data Declarations
report_title String;
// Jasper callback function
function beforeReportInit()
report_title = getReportParameter("ReportTitle");
end
end
Getting and setting report variables
The following code snippet shows how to get and set report variables in a report
handler:
handler my_report_handler type jasperReport
// Data Declarations
item_count int;
// Jasper callback function
function beforeDetailEval()
item_count = getReportVariableValue("itemCount");
end
function afterDetailEval()
setReportVariableValue("itemCount", (item_count + 1));
end
end
You must match variable types in the report handler with those in your XML
source file.
Getting report field values
The following example code snippet shows how to get report field values in a
report handler:
handler my_report_handler type jasperReport
// Data Declarations
employee_first_name String;
// Jasper callback function
function beforeColumnInit()
employee_first_name = getFieldValue("fName");
end
end
Saving report data in the report handler
The following example code shows how to save a customer record under the name
″saveCustomer″ for later access:
handler my_report_handler type jasperReport
// Data Declarations
customer_array customerRecordType[];
c customerRecordType;
// Jasper callback function
function beforeReportInit()
customer ReportData;
//create the ReportData object for the Customer subreport
c.customer_num = getFieldValue("c_customer_num");
c.fname = getFieldValue("c_fname");
294 EGL Programmer’s Guide
c.lname = getFieldValue("c_lname");
c.company = getFieldValue("c_company");
c.address1 = getFieldValue("c_address1");
c.address2 = getFieldValue("c_address2");
c.city = getFieldValue("c_city");
c.state = getFieldValue("c_state");
c.zipcode = getFieldValue("c_zipcode");
c.phone = getFieldValue("c_phone");
customer_array.appendElement(c);
customer.data = customer_array;
addReportData(customer, "saveCustomer");
end
end
Retrieving report data in the XML file
After report data is saved in the report handler, you can retrieve it in the XML
source file and pass it to a subreport:
<jasperReport name="MasterReport" ... scriptletClass="subreports.my_report_handler">
...
<subreport>
<dataSourceExpression>
<![CDATA[(JRDataSource)(((subreports.SubReportHandler)
$P{REPORT_SCRIPTLET}).getReportData( new String("saveCustomer")))]]>;
</dataSourceExpression>
<subreportExpression class="java.lang.String">
<![CDATA["C:/RAD/workspaces/customer_subreport.jasper"]]>;
</subreportExpression>
</subreport>
...
</jasperReport>
Invoking a function from the XML design document
This report handler has one simple function: to print ″Hello, World!″
handler my_report_handler type jasperReport
function hello () returns (String)
return("Hello, world!");
end
end
Invoke it from the XML design document with this code:
<jasperReport name="MasterReport" ... scriptletClass="my_package.my_report_handler">
...
<summary>
<band height="40">
<textField>
<reportElement positionType="Float" x="0" y="20" width="500" height="15"/>
<textElement textAlignment="Center">
<font reportFont="Arial_Bold" size="10"/>
</textElement>
<textFieldExpression class="java.lang.String">
<![CDATA[((my_package.my_report_handler)$P{REPORT_SCRIPTLET}).hello()]]>
</textFieldExpression>
</textField>
</band>
</summary>
...
</jasperReport>
The phrase ″Hello, world!″ will print at the end of the report.
Creating reports with EGL 295
Related concepts
“Creating reports with EGL” on page 283EGL offers different ways to create reports, using external engines to generate
the report contents. Related tasks
“Creating EGL source files” on page 77
“Using report templates” on page 297
Running a report
To run a report, you must have the following files in the specified locations:
v An EGL project with a build descriptor file.
v A compiled report design file (extension jasper) somewhere on your system.
Specify the location of the report design file in the report driver program. For
more information, see “Creating the report design file” on page 285.
v A report driver program (extension .egl) in the EGLSource folder of the project.
See “Writing code to drive a report” on page 289.
v Optionally, you can have a report handler (extension .egl) in the EGLSource
folder of the project.
v If your report driver program accesses a database, you might need to tell EGL
where to find the appropriate Java Database Connectivity (JDBC) driver. You
might need to add an external Java Archive (JAR) file to your project properties.
To create and fill a report for an EGL project, follow these steps:
1. Build the EGL project by clicking Project → Build or Project → Clean. EGL
automatically generates Java code from any EGL source files that have changed
since the last build and compiles any changed design document source files.
2. Run the Java program that contains the generated report driver program. One
way to do this in the Package Explorer view is to navigate to and right-click
the .java file that contains the code. Then select Run As → Java Application
from the menu.
When you create a report, the JasperReports engine first creates an intermediate
destination file (extension .jrprint), from which it can create multiple export files in
different formats (.pdf, .html, .xml, .txt, or .csv). You specify locations for all of
these files in the report driver.
Related concepts
“Creating reports with EGL” on page 283EGL offers different ways to create reports, using external engines to generate
the report contents.
“Elements of an EGL report application” on page 284The main elements of a JasperReport application in EGL are a program to run
the report and a report design file to control the layout of the report.
Additionally, a report handler can give you greater control over the data put
into the report. Related tasks
“Creating an EGL report handler” on page 292
“Creating the report design file” on page 285The report design file specifies the layout and appearance of the report. Unless
you import a working design file (with the extension .jasper), you will need to
create or modify a report design file.
296 EGL Programmer’s Guide
“Writing code to drive a report” on page 289A report-driver program is an ordinary EGL program that runs a report using a
.jasper file that is compiled from a report design file.
Using report templates
EGL provides code that you can add to your program with a few keystrokes. That
code can provide most of the statements that you need to fill and export a report
through JasperReports or can give you a template for writing a report handler.
To fill and export a report through JasperReports, choose any of these data sources
for the report:
v Database connection
v Custom report data
v Result object from a specified SQL query
To add a report handler template to your source file, follow these steps:
1. Open a new file in your text editor.
2. Type handler, then press Ctrl+space
3. The editor will replace the word ″handler″ with template code. Work through
the code and add statements for the functions that you want to use. For more
information, including code examples, see Creating an EGL report handler.
To add JasperReport code to your source file, follow these steps:
1. Move your cursor to a new line within the main() section of your program.
2. Type jas, then press Ctrl+space
3. The editor provides a menu with options for database, custom, or SQL data;
select the appropriate template.
4. The editor will replace the letters ″jas″ with code; use the Tab key to move to
the fields that you need to change.
You can edit the templates themselves by following these steps:
1. Click Window → Preferences.
2. When a list of preferences is displayed, expand EGL.
3. Expand Editor and select Templates.
4. Scroll through the list of templates and select a template. For example, select
handler to display the report handler template.
5. Click Edit.
6. Change the template to meet your needs.
7. Click Apply and then click OK to save your changes. Related concepts
“Creating reports with EGL” on page 283EGL offers different ways to create reports, using external engines to generate
the report contents. Related tasks
“Creating an EGL report handler” on page 292
“Writing code to drive a report” on page 289A report-driver program is an ordinary EGL program that runs a report using a
.jasper file that is compiled from a report design file.
Creating reports with EGL 297
Creating subreports
In the simplest case, with the subreport capability of JasperReports you can to
print associated data for each line item in a report—from the same table, from
another table in the same database, or from another data source altogether. More
complex cases are beyond the scope of this topic; refer to JasperReports
documentation for such information.
In complex cases you might need a report handler to provide data for the
subreport; see Creating an EGL report handler. In some simple cases, you can add a
subreport in two simple steps:
1. Add subreport code to the design file for the main report.
2. Create one or more design files for the subreport or subreports.
Here is an elementary example of how you can create a subreport and add it to
your report. Given a report that prints all the customers from the table
CUSTOMER, you can add a subreport that shows all invoices for each customer,
drawn from the table ORDERS.
1. This is a section of code from the main report design file. This code was
originally written to print one line for each customer in the table CUSTOMER.
Add the code shown in bold in the following example:
<queryString><![CDATA[SELECT * FROM ADMINISTRATOR.CUSTOMER]]></queryString>
<field name="CUST_NO" class="java.lang.Integer">
</field>
<field name="CUST_NAME" class="java.lang.String">
</field>
<detail>
<band height="100">
<subreport>
<reportElement positionType="Float" mode="Opaque" x="0" y="31"
width="709" height="12" isRemoveLineWhenBlank="true"/>
<subreportParameter name="CURRENT_CUST">
<subreportParameterExpression>
<![CDATA[$F{CUST_NO}]]>
</subreportParameterExpression>
</subreportParameter>
<connectionExpression>
<![CDATA[$P{REPORT_CONNECTION}]]>
</connectionExpression>
<subreportExpression class="java.lang.String">
<![CDATA[new String("C:\\workspace\\report_project\\bin
\\report_package\\my_subreport.jasper")]]>
</subreportExpression>
</subreport>
<textField>
<reportElement positionType="Float" x="57" y="11"
width="304" height="20"/>
<textElement/>
<textFieldExpression class="java.lang.String">
<![CDATA[$F{CUST_NO} + " " + $F{CUST_NAME}]]>
</textFieldExpression>
</textField>
</band>
</detail>
The <subreport> tag gives JasperReports the information it needs to run the
subreport:
v Positioning information (the same parameter that you will find in the main
report)
298 EGL Programmer’s Guide
v Parameters that you want to pass to the subreport (in this case, the number
of the current customer, which you will need in the SQL SELECT statement
in the subreport)
v Connection information, because the report driver for this report specifies a
data source of DataSource.databaseConnection
v The location of a compiled report design file for the subreport (in this case,
my_subreport.jasper)2. The subreport design file is not different in kind from any other .jasper design
file. Include the following essential code in that file:
<parameter name="CURRENT_CUST" class="java.lang.Integer"/>
<queryString><![CDATA[SELECT * FROM ADMINISTRATOR.ORDERS
WHERE CUST_NO = $P{CURRENT_CUST}]]></queryString>
<field name="CUST_NO" class="java.lang.Integer">
</field>
<field name="INVOICE_NO" class="java.lang.Integer">
</field>
<field name="ORDER_TOTAL" class="java.lang.Float">
</field>
<detail>
<band height="100">
<textField>
<reportElement positionType="Float" x="50" y="10" width="300" height="20"/>
<textElement/>
<textFieldExpression class="java.lang.String">
<![CDATA["Invoice # " + $F{INVOICE_NO} + " total: " +
$F{ORDER_TOTAL}]]>
</textFieldExpression>
</textField>
</band>
</detail>
Even though you passed the parameter CURRENT_CUST to the subreport, you
must tell the report what type the parameter is, using the class= attribute of the
<parameter> tag. Next comes the query string (JasperReports is very particular
about the order of the tags within the file). Here you reference the value of
CURRENT_CUST as $P{CURRENT_CUST}. The field names refer to column
names in the ORDERS table, which you can then reference inside the
<textFieldExpression> tag.
These are the only changes that you need to make to add a subreport; you do not
need to change any code in the EGL report driver program. If you want to include
other sources of data or complex calculations, however, you must create a report
handler (see Creating an EGL report handler).
You can create nested subreports. For example, you might call up line items for
each invoice from a third table. This would involve adding the information within
a <subreport> tag to the subreport file my_subreport.jasper, and creating a separate
design file for the nested subreport (you might call it my_invoice_subreport.jasper).
There is no limit to the depth to which you can nest subreports.
Related Tasks
“Creating an EGL report handler” on page 292
“Creating the report design file” on page 285The report design file specifies the layout and appearance of the report. Unless
you import a working design file (with the extension .jasper), you will need to
create or modify a report design file.
Creating reports with EGL 299
Adding support for Jasper reports to a project
Before you can create reports with EGL, you must add support for Jasper reports
to your project and add a Java compiler to your system’s path variable.
Adding Jasper report support adds JAR files to your project that enable EGL to
compile report design files. You only need to do this once for each project that uses
Jasper reports, and there is no need to remove support from a project.
You can add support for Jasper reports only to EGL projects, not to EGL Web
projects.
1. In the Project Explorer view, right-click your EGL project and then click
Properties. The Properties window opens.
2. In the Properties window, click EGL Project Features.
3. Under EGL Project Features at the right side of the window, select the EGL
with Jasper report support check box. If this check box is already selected,
leave it selected.
4. Click OK.
Alternately, you can enable Jasper report support in a new project. Select the EGL
with Jasper report support check box in the New EGL Project. Selecting this check
box has the same effect as selecting the check box in the Properties window.
Adding the Java compiler to the PATH environment variable
To compile a report design file, EGL needs a Java compiler in your system’s PATH
environment variable.
Use a Java compiler with the same version as the version of Java you are using to
generate EGL. Follow these steps to tell what level of Java you are using:
1. Right-click an EGL project and then click Properties.
2. In the Properties window, click Java Compiler.
This page shows settings for the project’s Java compiler. By default, the Enable
project specific settings check box is cleared and the rest of the fields on the
page are disabled.
3. If the Enable project specific settings check box is selected, the version of Java
that you are using in this project is shown in the Compiler compliance level
field.
4. If the Enable project specific settings check box is cleared, click Configure
Workspace Settings. The Preferences window opens to the Compiler page, and
the version of Java you are using for all your projects is shown in the Compiler
compliance level field.
Follow these steps to add the Java compiler to your system:
1. Obtain and install a Java SDK if you do not already have one. IBM offers a Java
SDK for download at the following Web site: http://www.ibm.com/developerworks/java/jdk/.
2. In your system’s PATH environment variable, add the location of the Java SDK.
See your operating system documentation for instructions.
Adding support for PDF reports
If you want to export reports in Portable Document Format (PDF), follow these
additional steps after adding support for Jasper reports:
300 EGL Programmer’s Guide
1. Download the file iText-1.3.jar from the following Web site:http://prdownloads.sourceforge.net/itext.
2. In the Project Explorer view, right-click your project and then click Properties.
3. In the Properties window, click Java Build Path.
4. On the Libraries tab, click Add External JARs.
5. In the JAR Selection window, select the iText-1.3.jar file that you just
downloaded and click Open.
Now the iText-1.3.jar file is listed under JARs and class folders on the build
path.
6. Click OK.
Setting the export location for reports in RCP mode
If you are creating reports in a Console UI application that is running in rich client
platform (RCP) mode, you must set the osgi.user.area system property to the
location where you want to store reports. Otherwise, reports will be created in the
product installation directory.
1. Click Run → Run. The Run window opens.
2. From the list of runtime configurations, expand Eclipse Application and then
click the run configuration for the program.
3. On the Arguments tab of the run configuration, add the following code:
-user "<location>"
In place of <location>, use the directory to which you want to generate the
reports.
4. Click Apply to save changes to the run configuration. Related concepts
“Creating reports with EGL” on page 283EGL offers different ways to create reports, using external engines to generate
the report contents.
“Elements of an EGL report application” on page 284The main elements of a JasperReport application in EGL are a program to run
the report and a report design file to control the layout of the report.
Additionally, a report handler can give you greater control over the data put
into the report. Related tasks
“Creating the report design file” on page 285The report design file specifies the layout and appearance of the report. Unless
you import a working design file (with the extension .jasper), you will need to
create or modify a report design file.
“Writing code to drive a report” on page 289A report-driver program is an ordinary EGL program that runs a report using a
.jasper file that is compiled from a report design file.
“Creating an EGL report handler” on page 292
“Running a report” on page 296
Creating EGL text reports
EGL offers its own report engine (an external Java class) that produces a simple
text report. This engine is particularly useful for migrating reports from Informix
4GL.
Creating reports with EGL 301
The following steps provide a broad overview of the process of creating an EGL
text report:
1. Create a basic Handler part. This program performs the following actions:
v It declares a report variable that has access to the functions and variables of
the report engine (the Java class). The declaration can optionally change
default format values such as margins, headers, and so on. For more
information on the specific values you can set when creating the variable, see
″Creating a TextReport variable″ in the EGL Language Reference.
v It defines functions that are tied to specific events during report generation.
See “Handler events for a text report.”
v It passes control to the report engine, which calls the handler functions as
appropriate.2. Create a report generator program. This program performs the following
actions:
v It declares a variable that is based on the basic Handler part.
v It passes control to the handler program.
For a sample text report program and handler, see “Writing code to print a text
report” on page 303.
The text report engine includes functions for most of the tasks that you perform in
the handler, including functions to start and finish the report, to print lines, text, or
white space, to manage headers and footers, and more. For a complete list of these
functions, see ″Text report functions″ in the EGL Language Reference.
For more information on converting existing I4GL reports to EGL, refer to the IBM
Informix 4GL to EGL Conversion Utility User’s Guide.
Related concepts
“Creating reports with EGL” on page 283EGL offers different ways to create reports, using external engines to generate
the report contents.
“Handler events for a text report”The TextReport external type defines the events that a basic text report handler
can react to.
“Writing code to print a text report” on page 303This topic provides a sample text report program and handler.
Handler events for a text report
The TextReport external type defines the events that a basic text report handler can
react to.
Each event is a variable that you reference through the text report variable. You
can code a function for any of these events. The text report engine calls the
corresponding function whenever the event occurs. Use a simple EGL assignment
statement in the handler to associate a function with an event, as in the following
example:
myReport.onFirstPageHeaderListener = printHeader1;
If you assign a function name to one of these event variables, you must create a
matching function in the handler. The matching functions must have a single
argument, a TextReportEvent type variable.
302 EGL Programmer’s Guide
For a complete list of event variables, see ″Text report variables″ in the EGL
Language Reference. For a sample text report program and handler, see “Writing
code to print a text report.”
Related concepts
“Creating reports with EGL” on page 283EGL offers different ways to create reports, using external engines to generate
the report contents.
“Writing code to print a text report”This topic provides a sample text report program and handler.
Writing code to print a text report
This topic provides a sample text report program and handler.
Prerequisites
v An EGL project
v A database and a working connection to that database
Synopsis
The program prints a list of all customers in the SQL database and their current
balances.
The following events take place in the course of the program:
1. The report generator program creates variables that are based on
CustomerRecord and textReportHandler.
2. The report generator calls the start() function from the handler.
3. The handler start() function creates a variable that is based on the
TextReport ExternalType, and specifies functions for two events: onEveryRow
and onLastRow. The function then passes control of the report to the text
report engine by means of the myReport.startReport() function.
4. The myReport.startReport() function does not change any report formatting,
so the report engine returns control to the handler, which returns control to
the report generator.
5. The report generator creates a result set using the EGL open statement. This
result set contains all customers from the current database.
6. The report generator loops through the result set. For each customer, it sends
the handler output() function a customer name and balance.
7. The handler stores the customer name and balance in a record that is
accessible to all functions in the handler and updates the running balance
total.
8. The handler then passes control to the report engine using the
outputToReport() function.
9. After performing certain housekeeping tasks, the report engine calls the
onEveryRow() function in the handler.
10. The onEveryRow() function in the handler sends the customer name in the
current print position, moves to the 40th column of the page, prints the
customer balance, and sends a carriage return and form feed to the report file.
11. Control passes back to the report generator, which seeks the next customer
record to process. When it has processed all customers, the generator calls the
finish() function in the handler.
12. The finish() function in the handler passes control to the report engine
through the finishReport() function.
Creating reports with EGL 303
13. The report engine finds a function for the last-row event and calls
onLastRow() from the handler.
14. The onLastRow() function in the handler prints the running total that the
handler has been updating.
15. The report engine closes the report file, and control passes back to the handler,
and finally to the generator, which terminates the run unit.
The customer record
The program uses the following record to access the SQL database of customers:
record CustomerRecord type SQLRecord
{tableNames = [["ADMINISTRATOR.CUSTOMER", "L1"]],
keyItems = [customerNumber]}
customerNumber STRING {column="C_NUMBER", maxLen=6};
customerName STRING {column="C_NAME", isSqlNullable=yes, maxLen=25};
customerAddr1 STRING {column="C_ADDR1", isSqlNullable=yes, maxLen=25};
customerAddr2 STRING {column="C_ADDR2", isSqlNullable=yes, maxLen=25};
customerAddr3 STRING {column="C_ADDR3", isSqlNullable=yes, maxLen=25};
customerBalance MONEY {column="C_BALANCE", isSqlNullable=yes};
end
The report generator
Execution begins with the report generator.
package com.companyb.customer;
program reportGenerator type BasicProgram
myCustomer CustomerRecord;
myHandler textReportHandler{};
function main()
myHandler.start(); // passes control to handler
// get customer list from database
open myResults scroll for myCustomer;
forEach (from myResults) // loop through results
myHandler.output(myCustomer.customerName, myCustomer.customerBalance);
end // forEach
myHandler.finish(); // close report
end
end
The generic handler
Both the report generator and the report engine call functions from the handler.
package com.companyb.customer;
record reportRecord type BasicRecord
customerName STRING;
customerBalance MONEY;
end
handler textReportHandler type BasicHandler
myReport TextReport{}; // creates instance
currentReportRecord reportRecord;
runningTotal MONEY = 0;
function start()
myReport.onEveryRowListener = onEveryRow;
myReport.onLastRowListener = onLastRow;
// accept defaults on everything but destination file
myReport.startReport("D:/temp/customerReport.txt",
304 EGL Programmer’s Guide
null,null,null,null,null,null);
end
function output(cName STRING in, cBal MONEY in)
// this information comes from the forEach loop in the main program
currentReportRecord.customerName = cName;
currentReportRecord.customerBalance = cBal;
runningTotal = runningTotal + cBal;
// pass control to the report engine
// onEveryRow is called
myReport.outputToReport();
end
function finish()
// pass control to the report engine again
// onLastRow is called
myReport.finishReport();
end
function onEveryRow(myEvent TextReportEvent)
myReport.printText(currentReportRecord.customerName);
myReport.column(40);
myReport.printText(currentReportRecord.customerBalance);
myReport.println();
end
function onLastRow(myEvent TextReportEvent)
myReport.println(); // skip a line
myReport.printText("All customers:");
myReport.column(40);
myReport.printText(runningTotal);
end
end
Related reference
“Creating EGL text reports” on page 301EGL offers its own report engine (an external Java class) that produces a simple
text report. This engine is particularly useful for migrating reports from
Informix 4GL.
Creating reports with EGL 305
306 EGL Programmer’s Guide
Debugging EGL applications
Debugging is the process of monitoring the execution of a program to pinpoint the
causes of errors. With the EGL debugger, you can set breakpoints (places for
execution to pause), examine or change variables, and move through the program
one step at a time. You can debug two types of code:
v A JSF Handler part
v Other types of code
At its simplest, debugging an EGL program involves the following:
v Checking the preference Window → Preferences → EGL → Debug → Stop at first
line of a program
v Opening an EGL source program in the editor
v Changing to the Debug perspective (Window → Open Perspective → Other →
Debug)
v Right-clicking the program name in the Outline view and choosing Debug EGL
Program
v Clicking the Step Into button to move through the program
More sophisticated debugging involves launch configurations, breakpoints,
database connections, setting variable values, and other concepts. For an overview,
see “Stepping through an application in the EGL debugger” on page 308.
Debugging a JSF Handler part
To debug JSF Handler parts, as well as programs that are used in a J2EE context,
you can use the local WebSphere Application Server test environment in debug
mode. If you are debugging code that runs under J2EE in a Web application, you
must use a server test environment. If you are debugging programs that run in a
batch application under J2EE, you can use the server test environment, but it is not
required.
Debugging other types of code
To debug other programs (such as batch programs that do not run under J2EE, or
TextUI programs), use a launch configuration that is outside of the WebSphere
Application Server test environment. In this case, you can start the debug session
with a few keystrokes.
If you are working on a batch program that you intend to deploy in a J2EE
context, you can use the launch configuration to debug the program in a non-J2EE
context. Although the setup is straightforward, you need to adjust some values:
1. Set the value of the J2EE build descriptor option to NO when you use the
launch configuration.
2. Adjust Java property values to conform to differences in accessing a relational
database:
v For J2EE, specify a string like jdbc/MyDB, which is the name to which a data
source is bound in the JNDI registry. You can specify that string in these
ways:
– By setting the sqlJNDIName build descriptor option; or
© Copyright IBM Corp. 1996, 2007 307
– By placing a value in the EGL SQL Database Connections preference page,
in the Connection JNDI Name field; for details, see “Setting preferences
for SQL database connections” on page 181.v For non-J2EE, specify a connection URL like jdbc:db2:MyDB. You can specify
that string in these ways:
– By setting the sqlDB build descriptor option; or
– By placing a value in EGL SQL Database Connections preference page, in
the field Connection URL. For details, see “Setting preferences for SQL
database connections” on page 181.
For information on EGL debugger commands, see “EGL debugger commands” on
page 312. For more information on how build descriptor settings affect the EGL
debugger, see “How build descriptor settings affect the EGL debugger” on page
315.
Related concepts
“Character encoding options for the EGL debugger” on page 327
“EGL debugger commands” on page 312 Related tasks
“Setting preferences for SQL database connections” on page 181
“Setting preferences for the EGL debugger” on page 328This topic tells you how to change your preferences for the EGL debugger.
“Stepping through an application in the EGL debugger”This topic offers guidance on the basic steps of debugging a program in the
EGL debugger.
“Creating a launch configuration in the EGL debugger” on page 320
Stepping through an application in the EGL debugger
This topic offers guidance on the basic steps of debugging a program in the EGL
debugger.
Strategies for debugging an application are beyond the scope of this
documentation, but in general the heart of the debugging process is identifying the
source of a problem in the code. For example, if your program ends abnormally,
you can use the debugger to step through the code and find the point at which the
program fails. If the program gives unexpected output, you can use the debugger
to track the values of variables and find the point at which the output deviates
from the expected.
The debugger always starts debugging from a program part. If you want to debug
another logic part, such as a library, you must step into the other logic part from a
program. In some cases you might benefit from writing a simple program with no
other function than to call the logic part that you want to debug.
Prerequisites
v An EGL project
v An EGL program to debug
The following example provides a program with a simple error that you can use to
test the debugger:
program myDebugTestPgm type BasicProgram
function main()
308 EGL Programmer’s Guide
//Provide some initial values for the array of items.
customerItems items[3];
customerItems[1].itemNumber=1;
customerItems[2].itemNumber=2;
customerItems[3].itemNumber=3;
customerItems[1].itemCost=12.50;
customerItems[2].itemCost=200;
customerItems[3].itemCost=49.95;
customerItems[1].itemQuantity=30;
customerItems[2].itemQuantity=10;
customerItems[3].itemQuantity=60;
counter int;
orderTotal float=0;
//Calculate the total cost of the items.
//Use the discountPrice function to get the discounted cost of each item.
for (counter from 1 to customerItems.getSize() by 1)
orderTotal += discountPrice(customerItems[counter].itemCost,
customerItems[counter].itemQuantity);
end // for loop
//Write the output to the console.
SysLib.writeStderr("The total cost for the order is $" + orderTotal);
end // main
//Return a total price for a group of items
//based on the item price and a quantity discount.
function discountPrice(itemCost float in, itemQuantity int in) returns(float)
discountRate float=0;
quantCost float=0;
//Determine the discount for each quantity.
//Discount 20% for more than 50 items.
//Discount 5% for more than 20 items.
case
when (itemQuantity > 50)
discountRate = 1/5;
when (itemQuantity > 20 && itemQuantity <= 50)
discountRate = 1/20;
otherwise
//bug - division by zero
discountRate = 1/0;
end
//Multiply the cost of the item, the number of items,
//and the discounted price.
quantCost = itemCost*itemQuantity*(1-discountRate);
quantCost = MathLib.round(quantCost, -2);
return (quantCost);
end // function discountPrice
end // program
record items type BasicRecord
itemNumber int;
itemCost float;
itemQuantity int;
end
If you generate this program and run it, EGL will return an error pointing to the
discountPrice function and the expression 1/0. In this case, the error is easy to
see, but in other cases you might not be able to find the error so easily. Your first
step in identifying the source of the error might be to run the program in the
Debugging EGL applications 309
debugger with breakpoints to find where the program fails.
Adding breakpoints
You can mark one or more lines of code as breakpoints. When the debugger
encounters a breakpoint, it pauses before running the associated line of code. You
then have the option of checking the current values of program variables before
telling the debugger how to proceed. Breakpoints do not affect the generated
source in any way; they are meaningful only during the debugging process.
To add a breakpoint, double-click the gray margin to the left of the code in the
EGL editor. In the previous example, you might want to add breakpoints
throughout the discountPrice function because the error tells you that this
function is where the error occurred. Breakpoints are marked with blue circles in
this gray area:
You can add a breakpoint at most lines of EGL code that conduct logic, including
the following examples:
v An assignment statement, such as:
myString = "Hello";
v A variable declaration that includes an assignment, such as:
myInt int = 5;
v A call to a system function or other EGL function, such as:
SysLib.writeStderr("Hello");
v A loop or comparison statement, such as:
if (myInt == 5)
However, you cannot add breakpoints at the following lines of code:
v A variable declaration that does not include an assignment.
v An end statement.
v A line of code that begins with function, or that begins with program, package,
or any other line that declares a logic part. However, you can set a preference to
310 EGL Programmer’s Guide
have the debugger treat the first line of each program as though it contained a
breakpoint. See “Setting preferences for the EGL debugger” on page 328.
v Any line within a data part.
v A blank line or a line that consists only of a comment.
For more instructions on using breakpoints, see “Using breakpoints in the EGL
debugger” on page 316.
You can debug a program without using breakpoints. If you check the preference
Window → Preferences → EGL → Debug → Stop at first line of a program, it has the
same effect as setting a breakpoint at the first executable line inside the main()
function of the program. From this point you can step through or around
succeeding lines of code, that is, execute a single line and pause. For more on the
step commands, see “EGL debugger commands” on page 312.
Running a program in the EGL debugger
After you have added breakpoints to your program, or set the Stop at first line
option (see ″Adding breakpoints″ earlier in this topic), you can run it in the
debugger.
The debugger requires a launch configuration to describe how it will run the
application. There are two ways to create a launch configuration:
v Have the debugger to create a launch configuration automatically when you
start debugging.
v Create a launch configuration manually. See “Creating a launch configuration in
the EGL debugger” on page 320 for more information.
For most programs, you can use the automatically created launch configuration.
1. In the Project Explorer view, right-click the EGL source program that you want
to debug and then click Debug EGL Program. The debugger performs the
following tasks:
v If no launch configuration exists for the program, the debugger creates a
default launch configuration. You can view this configuration by clicking
Run → Debug.
v Depending on your workbench preferences, the debugger might switch to
the Debug perspective automatically or prompt you to do so. You can switch
perspectives manually by clicking Window → Open Perspective → Other →
Debug.
v The debugger begins running the program.2. After the debugger has started running the program, it continues until it
encounters a breakpoint, or, if you have set the preference for it, finds the first
line of executable code. At this point, the debugger pauses and displays the
following information:
v The EGL editor highlights the line about to be executed.
v The Variables view shows the value of all the variables in the current logic
part, including the value of system variables. You can use this view to track
the value of a variable through the program. You can also change the value
of a variable while the debugger is paused at a breakpoint.
v The Debug view lists the threads running within the current run unit. In
simple terms, this view shows which program or logic part is currently
running. Use this view to resume or stop the debugging process.
Debugging EGL applications 311
v The Breakpoints view lists the breakpoints in the program. From this view,
you can disable a breakpoint temporarily by clearing its check box.3. When you want the debugger to continue, click the Resume button at the top
of the Debug view. The debugger continues to the next breakpoint. You can
also use one of the Step buttons to see the program execute the next line and
pause again.
In the example program, you can run the program from breakpoint to
breakpoint until the debugger reaches the line discountRate = 1/0;, at which
point the debugger returns the same error that you see in the console when
running the program.
4. When you are finished debugging, click the Terminate button at the top of the
Debug view to stop the debugger or allow the program to finish running. Related concepts
“Debugging EGL applications” on page 307
“EGL debugger commands” Related tasks
“Setting preferences for the EGL debugger” on page 328This topic tells you how to change your preferences for the EGL debugger.
“Creating a launch configuration in the EGL debugger” on page 320
“Starting a non-J2EE application in the EGL debugger” on page 321
“Using breakpoints in the EGL debugger” on page 316This topic shows you how to use breakpoints in debugging your programs. You
can manage breakpoints inside or outside of an EGL debugging session.
“Viewing variables in the EGL debugger” on page 317This topic shows you how to view variables in your program while your are
debugging your programs.
EGL debugger commands
You can use the following commands to interact with the EGL debugger:
Add breakpoint
Identifies a line at which processing pauses. When code execution pauses,
you can examine variable values, as well as the status of files and screens.
Breakpoints are carried from one debugging session to the next, unless you
remove the breakpoint. You cannot set a breakpoint at a blank line or at a
comment line.
Disable breakpoint
Inactivates a breakpoint, but does not remove it.
Enable breakpoint
Activates a breakpoint that was previously disabled.
Remove breakpoint
Clears the breakpoint so that processing no longer automatically pauses at
the line.
Remove all breakpoints
Clears every breakpoint.
Run Runs the code until the next breakpoint, or until the run unit ends. In any
case, the debugger stops at the first statement in the main function.
312 EGL Programmer’s Guide
Run to line
Runs all statements up to, but not including, the statement on a specified
line.
Jump to line
Right-clicking the gray border to the left of a line of code and then clicking
this option repositions the debugger at that line. You can jump only to a
line in a function that is part of the currently active stack; that is, the
function that you are in currently or a function that has called the current
function.
Step into
Runs the next EGL statement and pauses.
The following list indicates what happens if you issue the command step
into for a particular statement type:
call Stops at the first statement of a called program if the called
program runs in the EGL debugger. Stops at the next statement in
the current program if the called program runs outside of the EGL
debugger.
The EGL debugger searches for the receiving program in every
project in the workbench.
converse
Waits for user input. That input causes processing to stop at the
next running statement, which might be in a validator function.
forward
If the code forwards to a JSF Handler, the debugger waits for user
input, and then stops at the next running statement, which might
be in a validator function. If the code forwards to a program, the
debugger stops at the first statement in that program.
function invocation
Stops at the first statement in the function.
show, transfer
Stops at the first statement of the program that receives control in a
transfer. The target program is EGL source code that runs in the
EGL debugger, but is not generated by EGL.
After either a show statement or a transfer to transaction
statement, the behavior of the EGL debugger depends on the
debugger mode:
v In Java mode, the EGL debugger switches to the build descriptor
for the new program or, (if no such build descriptor is in use,
prompts the user for a new build descriptor. The new program
can have a different set of properties from the program that ran
previously.
v In COBOL mode, the build descriptor for the previous program
remains in use, and the new program cannot have a different set
of properties.
The EGL debugger searches for the receiving program in every
project in the workbench.
Step over
Runs the next EGL statement and pauses, but does not stop within
functions that are invoked from the current function.
Debugging EGL applications 313
The following list indicates what happens if you issue the command step
over for a particular statement type:
converse
Waits for user input and then skips any validation function (unless
a breakpoint is in effect). Stops at the statement that follows the
converse statement.
forward
If the code forwards to a JSF Handler, the debugger waits for user
input and stops at the next running statement, but not in a
validator function, unless a breakpoint is in effect.
If the code forwards to a program, the debugger stops at the first
statement in that program.
show, transfer
Stops at the first statement of the program that receives control.
The target program is EGL source code that runs in the EGL
debugger, but is not generated by EGL.
After either a show statement or a transfer to transaction
statement, the behavior of the EGL debugger depends on the
debugger mode:
v In Java mode, the EGL debugger switches to the build descriptor
for the new program or, if no such build descriptor is in use,
prompts the user for a new build descriptor. The new program
can have a different set of properties from the program that ran
previously.
v In COBOL mode, the build descriptor for the previous program
remains in use, and the new program cannot have a different set
of properties.
The EGL debugger searches for the receiving program in every
project in the workbench.
Step return
Runs the statements needed to return to an invoking program or function,
then pauses at the statement that receives control in that program or
function.
The step return command in a validator function is an exception. In that
case, the behavior is identical to that of a step into command, which
primarily means that the EGL debugger runs the next statement and
pauses.
The EGL debugger ignores the following EGL system functions:
v sysLib.audit()
v sysLib.purge()
v sysLib.startTransaction()
You can add a breakpoint at these statements, for example, but a step into
command merely continues to the subsequent statement, with no other effect.
Finally, if you issue the command step into or step over for a statement that is the
last one running in the function (and if that statement is not return, exit program,
or exit stack), processing pauses in the function itself so that you can review
variables that are local to the function. To continue the debug session in this case,
issue another command.
314 EGL Programmer’s Guide
Related concepts
“Debugging EGL applications” on page 307 Related tasks
“Creating a launch configuration in the EGL debugger” on page 320
“Stepping through an application in the EGL debugger” on page 308This topic offers guidance on the basic steps of debugging a program in the
EGL debugger.
“Using breakpoints in the EGL debugger” on page 316This topic shows you how to use breakpoints in debugging your programs. You
can manage breakpoints inside or outside of an EGL debugging session.
How build descriptor settings affect the EGL debugger
A build descriptor helps to determine some aspects of the debugging environment.
For example, the system build descriptor option determines which mode the EGL
debugger will run in. The debugger has two modes, Java and COBOL; if you set
the system type to DEBUG, then the mode is set to Java automatically. The mode
controls how the debugger acts in situations where the EGL runtime behavior
differs for Java and COBOL output.
The EGL debugger selects the build descriptor in accordance with the following
rules:
v If you specified a debug build descriptor for your program or JSF Handler, the
EGL debugger uses that build descriptor. For details on how to establish the
debug build descriptor, see ″Setting the default build descriptors″ in the EGL
Generation Guide.
v If you did not specify a debug build descriptor, the EGL debugger prompts you
to select from a list of your build descriptors.
v If the build descriptor you specified lacks any required database-connection
information, the EGL debugger gets the connection information by reviewing
your preferences. For details on how to set those preferences, see “Setting
preferences for SQL database connections” on page 181.
If you are debugging a program that you intend for use in a text or batch
application in a Java environment, and if that program issues a transfer statement
that switches control to a program that you also intend for use in a different run
unit in a Java environment, the EGL debugger uses a build descriptor that is
assigned to the receiving program. The choice of build descriptor is based on the
rules described earlier.
If you are debugging a program that is called by another program, the EGL
debugger uses the build descriptor that is assigned to the called program. The
choice of build descriptor is based on the rules that are described earlier, except
that if you do not specify a build descriptor, the debugger does not prompt you for
a build descriptor when the called program is invoked; instead, the build
descriptor for the calling program remains in use.
Note: You must use a different build descriptor for the caller and the called
program if one of those programs (but not both) uses VisualAge Generator
compatibility. The generation-time status of VisualAge compatibility is
determined by the value of the vagCompatibility build descriptor option.
Debugging EGL applications 315
A build descriptor or resource association part that you use for debugging code
might be different from the one that you use for generating code. For example, if
you intend to access a VSAM file from a program that is written for a COBOL
environment, you are likely to reference a resource association part in the build
descriptor. The resource association part must refer to the runtime target system
(for example, zOS) and must refer to a file type (for example, vsamrs) that is
appropriate for the target system. The debug situation differs from the generation
situation as follows:
v At generation time, the resource association part indicates the system name of
the file that is used in the target environment.
v At debug time, the system name must reflect another naming convention, as
appropriate when you access a remote VSAM file from an EGL-generated Java
program on Windows 2000, NT, or XP; for details on that naming convention,
see your VSAM support documents.
System type used at debug time
In addition to the system build descriptor option, a value for system type can be
set in sysVar.systemType. Also, a second value is available in
vgLib.getVAGSysType if you requested development-time compatibility with
VisualAge Generator).
The value in sysVar.systemType is the same as the value of the system build
descriptor option, except that the value is DEBUG in either of two cases:
v You select the preference Set systemType to DEBUG, as mentioned in “Setting
preferences for the EGL debugger” on page 328; or
v You specified NONE as the build descriptor to use during the debugging
session, regardless of the value of that preference.
The vgLib.getVAGSysType system function returns the VisualAge Generator
equivalent of the value in sysVar.systemType. For details, For details, see the table
in ″vgLib.getVAGSysType″ in the EGL Language Reference.
Related concepts
“Debugging EGL applications” on page 307 Related tasks
“Setting preferences for SQL database connections” on page 181
“Setting preferences for the EGL debugger” on page 328This topic tells you how to change your preferences for the EGL debugger.
“Creating a launch configuration in the EGL debugger” on page 320
Using breakpoints in the EGL debugger
This topic shows you how to use breakpoints in debugging your programs. You
can manage breakpoints inside or outside of an EGL debugging session.
Prerequisites
v An EGL project
v An EGL program or other logic part that needs debugging
Breakpoints are used to pause the execution of a program in the debugger. You can
manage breakpoints inside or outside of an EGL debugging session. Keep the
following in mind when working with breakpoints:
316 EGL Programmer’s Guide
v A blue marker in the left margin of the Source view indicates that a breakpoint
is set and enabled.
v A white marker in the left margin of the Source view indicates that a breakpoint
is set but disabled.
v The absence of a marker in the left margin indicates that a breakpoint is not set.
Adding or removing a breakpoint
To add or remove a single breakpoint in an EGL source file you can do either of
the following:
v Position the cursor at the breakpoint line in the left margin of the Source view
and double-click.
v Position the cursor at the breakpoint line in the left margin of the Source view
and right-click. A menu opens. Click either Add or Remove (The Remove option
is only there if a breakpoint is already set).
Disabling or enabling a breakpoint
To disable or enable a single breakpoint in an EGL source file, follow these steps:
1. In the Breakpoint view, right-click on the breakpoint. A menu opens.
2. Click either Enable or Disable.
Remove all breakpoints
To remove all breakpoints from an EGL source file, follow these steps:
1. Right-click any breakpoint that is displayed in the Breakpoints view. A menu
opens.
2. Click Remove All.
Related concepts
“Debugging EGL applications” on page 307 Related tasks
“Creating a launch configuration in the EGL debugger” on page 320
“Starting a non-J2EE application in the EGL debugger” on page 321
“Stepping through an application in the EGL debugger” on page 308This topic offers guidance on the basic steps of debugging a program in the
EGL debugger.
“Viewing variables in the EGL debugger”This topic shows you how to view variables in your program while your are
debugging your programs.
Viewing variables in the EGL debugger
This topic shows you how to view variables in your program while your are
debugging your programs.
Prerequisites
v An EGL project
v An EGL program or other logic part that needs debugging
Debugging EGL applications 317
Variables and breakpoints
When you are debugging a program, you will probably have the debugger stop or
pause at certain points in your program (see “Using breakpoints in the EGL
debugger” on page 316 for more information on using breakpoints to make the
debugger pause while debugging your program). Whenever a program is paused,
you can view the current values of the variables in the program.
Displaying and changing values
You typically use the Variable view to monitor the changing values of your
variables. To display their values, do one of the following:
v Click the Options button at the top of the view (the triangle), and then click
Layout and either Horizontal View or Vertical View. Also on the Options menu,
choose Detail pane. The Variables view will split into two panes, one showing
the current value of the variable.
v Click the Options button at the top of the view (the triangle), then click Layout →
Show Columns. If you do not see the Value column, choose Layout → Show
Columns → Value.
To change a value, right-click the value and choose the appropriate option from the
popup menu. The wording of the option varies depending on the context.
For more information, see ″Buttons in the Variables view″ in this topic.
Buttons in the Variables view
In the Variables view, expand the parts in the navigator to see the variables that
are associated with them. The Variables view provides the following buttons:
Show Type Names
This toggle displays or hides the types on which the variables are based.
This button is not available if you chose to show columns. In that case, you
can request a column that shows the variable type.
Show Logical Structure
Collapse All
This hides all the variable names and shows only the parts in the current
program.
[Options]
Click this downward pointing triangle icon to display a list of further
options:
Layout
The following layout options are available for the Variables view:
Vertical View Orientation
The detail pane is displayed below the variables.
Horizontal View Orientation
The detail pane is displayed to the right of the variables.
Variables View Only
This option closes the detail pane.
Show Columns
This option reformats the view in table form
318 EGL Programmer’s Guide
Select Columns
This option is only available if you select Show Columns.
The following columns are available:
Name The name of the variable.
Declared Type
The original type of the variable.
Value The current value of the variable. Click this cell to
enter a new value for the variable, or right-click
and choose Change Value to display a window
where you can change the value.
Actual Type
The actual type will differ from the declared type
only when the variable was originally ANY type
and took on another type through assignment.
Show All Jython Variables
This option does not apply to EGL.
Detail pane
This option opens a separate pane in the Variables view to display
the details of a highlighted variable. You can type a value for the
variable in this pane, highlight that value, right-click, and select
Assign Value to assign the value to the variable. Related concepts
“Debugging EGL applications” on page 307 Related tasks
“Creating a launch configuration in the EGL debugger” on page 320
“Starting a non-J2EE application in the EGL debugger” on page 321
“Configuring a server for EGL Web debugging” on page 323
“Using breakpoints in the EGL debugger” on page 316This topic shows you how to use breakpoints in debugging your programs. You
can manage breakpoints inside or outside of an EGL debugging session.
Starting the EGL debugger for EGL projects
Start the debugging process by creating a launch configuration.
To start the debugging process there must be a launch configuration. You can
create a launch configuration yourself, but the EGL debugger will create one
automatically if you do not create one.
To start the EGL debugger and have it create a launch configuration for you, see
“Starting a non-J2EE application in the EGL debugger” on page 321. To create a
launch configuration yourself, see “Creating a launch configuration in the EGL
debugger” on page 320. If you are debugging an EGL application that is called
from an EGL-generated Java application or Java wrapper, you must create a special
kind of launch configuration called an EGL Listener launch configuration. To create
one, see “Creating an EGL Listener launch configuration” on page 321.
Related tasks
“Starting a non-J2EE application in the EGL debugger” on page 321
“Creating a launch configuration in the EGL debugger” on page 320
“Creating an EGL Listener launch configuration” on page 321
Debugging EGL applications 319
Creating a launch configuration in the EGL debugger
To start debugging an EGL text program or non-J2EE basic program in an EGL
debugging session, a launch configuration is required. You can create a launch
configuration yourself, or you can have the EGL application create one for you
automatically (see “Starting a non-J2EE application in the EGL debugger” on page
321).
To start a program using a launch configuration that you create yourself, follow
these steps:
1. Click Run → Debug. The Debug window opens.
2. In the left pane of the Debug window, click EGL Program.
3. Click the New launch configuration at the top of that same pane. A new
launch configuration is displayed below the EGL Program heading. The
Launch tab is initially displayed.
4. In the Name field, type a name for the launch configuration. By default, the
launch configuration has the same name as the program, unless a
configuration already exists for this program.
5. In the Project field of the Load tab, type the name of your project.
6. In the EGL program source file field, select the program that you want to
debug.
7. If you are debugging a called program that takes arguments, click the
Arguments tab. List the arguments for the program, in order, as you would in
a call statement.
8. If you need to use a different JRE than the default for this project, click the
JRE tab and complete the information there.
9. If you need additional Java classes to run the program, specify the paths for
those classes on the Classpath tab.
10. Add any needed source files on the Source tab.
11. To set environment variables for the duration of the debug session only, type
the names and values on the Environment tab.
12. Click Apply to save the launch configuration settings.
13. Click Debug to launch the program in the EGL debugger.
Note: If you have not yet clicked Apply to save the launch configuration settings,
clicking Revert will remove all changes that you have made.
Related concepts
“Debugging EGL applications” on page 307 Related tasks
“Starting a non-J2EE application in the EGL debugger” on page 321
“Stepping through an application in the EGL debugger” on page 308This topic offers guidance on the basic steps of debugging a program in the
EGL debugger.
“Using breakpoints in the EGL debugger” on page 316This topic shows you how to use breakpoints in debugging your programs. You
can manage breakpoints inside or outside of an EGL debugging session.
“Viewing variables in the EGL debugger” on page 317This topic shows you how to view variables in your program while your are
debugging your programs.
320 EGL Programmer’s Guide
Creating an EGL Listener launch configuration
To debug a non-J2EE EGL application called from an EGL-generated Java
application or wrapper, an EGL Listener launch configuration is required. To create
an EGL Listener launch configuration, do as follows:
1. Click the arrow next to the Debug button on the toolbar, then click Debug, or
select Debug from the Run menu.
2. The Debug dialog box is displayed.
3. Click EGL Listener in the Configurations list, then click the New launch
configuration button.
4. The Listener launch configuration is named New_configuration. If you want to
change the name of the launch configuration, type the new name in the Name
field.
5. If you do not type a port number, the port defaults to 8346; otherwise, type a
port number. Each EGL Listener requires its own port.
6. If you are debugging a called program that takes arguments, click the
Arguments tab. List the arguments for the program, in order, as you would in
a call statement.
7. If you need to use a different JRE than the default for this project, click the
JRE tab and complete the information there.
8. If you need additional Java classes to run the program, specify the paths for
those classes on the Classpath tab.
9. Add any needed source files on the Source tab.
10. To set environment variables for the duration of the debug session only, type
the names and values on the Environment tab.
11. Click Apply to save the Listener launch configuration.
12. Click Debug to launch the EGL Listener. Related concepts
“Debugging EGL applications” on page 307 Related tasks
“Creating a launch configuration in the EGL debugger” on page 320
“Starting a non-J2EE application in the EGL debugger”
“Stepping through an application in the EGL debugger” on page 308This topic offers guidance on the basic steps of debugging a program in the
EGL debugger.
“Viewing variables in the EGL debugger” on page 317This topic shows you how to view variables in your program while your are
debugging your programs.
“Using breakpoints in the EGL debugger” on page 316This topic shows you how to use breakpoints in debugging your programs. You
can manage breakpoints inside or outside of an EGL debugging session.
Starting a non-J2EE application in the EGL debugger
To start debugging an EGL text program or non-J2EE basic program in an EGL
debugging session, a launch configuration is required. A launch configuration
specifies the location of a program on disk and specifies how the program must be
launched. You can let the EGL application create the launch configuration (implicit
creation), or you can create one yourself (see “Creating a launch configuration in
the EGL debugger” on page 320).
Debugging EGL applications 321
To launch a program using an implicitly created launch configuration, do as
follows:
1. In the Project Explorer view, right-click the EGL source file that you want to
launch. Alternatively, if the EGL source file is open in the EGL editor, you can
right-click the program in the Outline view. A menu opens.
2. Click Debug EGL Program. A launch configuration is created, and the program
is launched in the EGL debugger.
To view the implicitly created launch configuration, do as follows:
1. Click the arrow next to the Debug button on the toolbar. A context menu
displays.
2. Click Debug. The Debug dialog displays. The name of the launch configuration
is displayed in the Name field. Implicitly created launch configurations are
named according to the project and source file names.
Note: You can also display the Debug dialog by clicking Run → Debug.
Related concepts
“Debugging EGL applications” on page 307 Related tasks
“Creating a launch configuration in the EGL debugger” on page 320
“Stepping through an application in the EGL debugger” on page 308This topic offers guidance on the basic steps of debugging a program in the
EGL debugger.
“Using breakpoints in the EGL debugger” on page 316This topic shows you how to use breakpoints in debugging your programs. You
can manage breakpoints inside or outside of an EGL debugging session.
“Viewing variables in the EGL debugger” on page 317This topic shows you how to view variables in your program while your are
debugging your programs.
Invoking the EGL debugger from generated code
You can invoke the EGL debugger from an EGL-generated Java program or
wrapper, so you can use the EGL debugger when you work on a partly deployed
application. The program needs a call statement that you then associate with the
callLink element of a linkage options part. Similarly, you must associate the
wrapper with a callLink element. In either case, the element must specify the
remoteComType property as DEBUG.
Programs running in J2EE
To invoke the EGL debugger from an EGL-generated program or wrapper that
runs in J2EE, follow these steps:
1. Make sure you have added a linkage options part to your build file. For
instructions on how to do this, see ″Adding a linkage options part to an EGL
build file″ in the EGL Generation Guide.
2. Edit the callLink element to include the remoteComType property. To edit the
callLink element, see ″Editing the callLink element of a linkage options part″ in
the EGL Generation Guide. For details on setting the remoteComType property,
see ″remoteComType in callLink element″ in the EGL Generation Guide.
3. Make sure that the program to be debugged is running in the same server as
its caller.
322 EGL Programmer’s Guide
4. Add the EGL debugger JAR files to the server. Make sure the server is running
in debug mode.
5. Run the program in the debugger.
Programs not running in J2EE
Different rules apply when the called program to be debugged does not run in
J2EE. When this is the case, the caller of the program might be running anywhere,
including on a remote system. Follow these steps:
1. Start a listener program. Start a listener by using an EGL Listener launch
configuration that has only one configurable setting, a port number. The default
port number is 8346.
2. If multiple EGL Listeners are running at the same time, you must specify a
different port for each EGL Listener. You might also need to specify a different
port if port 8346 is being used by another application or if a firewall prevents
use of that port. To specify a different port number, see “Creating an EGL
Listener launch configuration” on page 321. Related tasks
“Creating an EGL Listener launch configuration” on page 321
Debugging Web projects with the EGL debugger
Use the EGL debugger to debug Web projects.
Before you can debug an EGL Web application, you must configure the server for
debugging. This needs to be done only once; see “Configuring a server for EGL
Web debugging.” This process will restart the server in Debug mode. To begin
debugging, see “Starting an EGL Web debugging session” on page 325.
Related concepts
“Debugging EGL applications” on page 307 Related tasks
“Configuring a server for EGL Web debugging”
“Starting an EGL Web debugging session” on page 325
Configuring a server for EGL Web debugging
Before you can debug EGL Web applications, you must configure the server for
EGL debugging. You need to do this configuration step only once per server. If you
use Tomcat, make sure that you request EGL debugging support at the time you
define the new server to EGL.
EGL Debug is the default debugging mode. If you want to debug generated Java
code rather than the EGL JSF handler, see ″Debugging Java code″ later in this
topic.
To configure a server for EGL debugging, do as follows:
1. In the Debug perspective, find or open the Server view (Window → Show View
→ Other → Server → Servers). The Status column of the display says
″Debugging″ when the server is running in EGL debug mode.
2. If Status column does not report ″Debugging,″ and the server is not running,
right click the server name and choose Debug from the context menu. If the
server is running, right-click the server name and click Restart → Debug.
Debugging EGL applications 323
3. To take the server out of EGL debug mode, right-click the server name and
choose Restart → Start.
Debugging Java code
EGL assumes that you want the server to debug EGL JSF Handler parts. If you
want to debug generated Java code instead, you must set the egl.jsfhandler.debug
system property to FALSE. Do this by passing the property as a VM argument to
the server. Methods for doing this depend on which server you are running.
On Apache Tomcat, edit the VM arguments section of the launch configuration
(Run → Debug), as in the following figure:
Restart the server for the property to take effect.
For IBM WebSphere Application Server, version 6.1, the process is more
complicated. Right-click the server name in the Server view and choose Run
administrative console. In the left menu pane of the Integrated Solutions Console,
expand Servers, and click Application servers. The console displays a list of
servers; click yours. On the Configuration tab of the next page, the last group of
options is headed Additional Properties. Under this heading, click Debugging
Service. On the Debugging Service page, add the following (with a space
afterwards) to the beginning of the string in JVM debug arguments:
-Degl.jsfhandler.debug=false
That area of the console looks like the following figure:
324 EGL Programmer’s Guide
Click Apply to save your changes. The console will ask you if you want to Save or
Review your changes; click Save. Restart the server for the property to take effect.
Related concepts
“Debugging EGL applications” on page 307 Related tasks
“Starting an EGL Web debugging session”
“Stepping through an application in the EGL debugger” on page 308This topic offers guidance on the basic steps of debugging a program in the
EGL debugger.
Starting an EGL Web debugging session
Before you follow the instructions in this topic, you must have generated each JSF
Handler that you want to debug at least once, as explained in “Debugging Web
projects with the EGL debugger” on page 323, and you must have started your
server in Debug mode (see “Configuring a server for EGL Web debugging” on
page 323).
To start debugging an EGL Web application, follow these steps:
1. In the Project Explorer for the EGL perspective, expand the
WebContent/WEB-INF folder for your project. Right-click the JSP file that you
Debugging EGL applications 325
want to run and then select Debug As → Debug on Server from the context
menu. EGL will change to the Debug perspective, deploy the application to the
server, and start the application.
2. Begin debugging the application. For an overview of this process, see “Stepping
through an application in the EGL debugger” on page 308.
3. As you find bugs and correct your EGL code, make sure that the debugger
picks up the changes and continues debugging with the updated code. The
easiest way to make the debugger use the updated code is to generate the parts
that you have changed, but you can also restart the server or restart the project
on the server.
Related concepts
“Debugging EGL applications” on page 307 Related tasks
“Configuring a server for EGL Web debugging” on page 323
“Stepping through an application in the EGL debugger” on page 308This topic offers guidance on the basic steps of debugging a program in the
EGL debugger.
Debugging services with the EGL debugger
You can debug your local EGL services similarly to the way that you debug other
programs.
Prerequisites
You will need an EGL Service part. Service binding information is not needed for
debugging, but you do not need to remove any existing binding information. You
will, however, need to add binding information for a client to test this service. The
instructions that follow will lead you through creating that information.
Debugging a local service
The simplest way to debug a service is to call it from a program in the same
project as the service. You can then pass test values to the service and inspect the
results.
Perform the following steps:
1. Create a new EGL source program.
2. In the program, declare a service variable that is based on the Service part that
you want to test.
3. Create a service client binding in the deployment descriptor as an EGL service
(not a Web service) with a ″local″ protocol. See “Calling a local service” on
page 254 for instructions.
4. Using the service client binding, bind the variable to the service with
{@BindService{bindingKey = "ServiceClientBindingName"}}.
5. In the main() function of the program, make at least one call to the service
using that variable. The easiest way is to hard code the input values in the
service call and write the output values to the console, as in the following
example:
program addTestProgram type BasicProgram
myAddingMachine additionService
{@BindService {bindingKey = "additionService"}};
function main()
326 EGL Programmer’s Guide
sumint int;
sumint = myAddingMachine.addInts(5, 12);
SysLib.writeStdOut("result = " + sumint);
end
end
6. Set a breakpoint at the service call. See “Using breakpoints in the EGL
debugger” on page 316.
7. Set breakpoints in the service, as you would in any logic part.
8. Debug your new EGL source program. At the breakpoint before the service call,
step into the service code. The debugger pauses at the breakpoints in the
service just as in any other logic part. Related concepts
“Debugging EGL applications” on page 307 Related tasks
“Calling a local service” on page 254You can call an EGL service that is local to your application without exposing
that service as a Web service.
“Using breakpoints in the EGL debugger” on page 316This topic shows you how to use breakpoints in debugging your programs. You
can manage breakpoints inside or outside of an EGL debugging session.
“Stepping through an application in the EGL debugger” on page 308This topic offers guidance on the basic steps of debugging a program in the
EGL debugger.
Character encoding options for the EGL debugger
With the EGL debugger, you can specify the type of character encoding to use
while debugging. Character encoding controls how the debugger represents
character and numeric data internally, how it compares character data, and how it
passes parameters to remote programs, files, and databases. To change these
options, see Setting preferences for the EGL debugger.
The EGL debugger supports two different types of character encoding: the default
encoding on your local system and Extended Binary Coded Decimal Interchange
Code (EBCDIC). The default character encoding for the EGL debugger is the same
as your local system’s default encoding.
v When the default character encoding is selected, the debugger represents CHAR,
DBCHAR, MBCHAR, DATE, TIME, INTERVAL, NUM, and NUMC variables in
the default format, typically ASCII. Comparisons between character variables use
the ASCII collating sequence. Data must be converted to host format when
calling remote programs and when accessing remote files and databases.
If you choose this setting and do not specify a conversion table, the debugger
chooses an appropriate conversion table when you call a remote program or
access a remote file or database. For more information on conversion tables, see
″callConversionTable″ in the EGL Language Reference.
v When EBCDIC character encoding is used, the debugger represents CHAR,
DBCHAR, MBCHAR, DATE, TIME, and INTERVAL variables with EBCDIC
encoding. NUM and NUMC variables are represented in host numeric format.
Comparisons between character variables use the EBCDIC collating sequence.
Data does not need to be converted to host format when calling remote
programs or when accessing remote files and databases, but data is converted to
the appropriate Java or ASCII format when making SQL calls or calls to local
C++ routines. EBCDIC encoding is available in several languages.
Debugging EGL applications 327
If you choose EBCDIC character encoding and do not specify a conversion table,
the debugger does not use a conversion table when you call a remote program
or access a remote file or database. The program name, library name, and any
passed parameters are encoded according to EBCDIC character encoding.
If your Java Runtime Environment does not support the selected character
encoding, you will see a warning message when the debugger starts. If you choose
to continue debugging, the debugger will return to the default encoding type.
You can not change character encoding during a debugging session. You must
restart the debugger for a change in character encoding to take effect.
Related concepts
“Debugging EGL applications” on page 307 Related tasks
“Setting preferences for the EGL debugger”This topic tells you how to change your preferences for the EGL debugger.
Setting preferences for the EGL debugger
This topic tells you how to change your preferences for the EGL debugger.
There are two pages of preferences for the EGL debugger. The first contains
general preferences, and the second contains a list of programs that you want to
debug in the generated code (Java or COBOL) version (see ″Debug behavior
mapping″ in this topic).
General preferences
To set general preferences for the EGL debugger, follow these steps:
1. From the main menu, click Window → Preferences.
2. In the Preferences window, expand EGL in the tree and then click Debug.
This opens the EGL debugger preferences.
3. If you want the debugger to treat a program declaration like a breakpoint,
check Stop at first line of a program.
4. If you want to require that a user ID and password be specified for remote
calls to an SQL database while debugging, click the box next to Prompt for
SQL user ID and password when needed. This user ID and password are
separate from those that are used to access an SQL database.
5. Click the check box for Set systemType to DEBUG to set the systemType
build descriptor option to DEBUG.
6. Type the initial values for sysVar.terminalID, sysVar.sessionID, and
sysVar.userID. If you do not specify values, each defaults to your user ID on
Windows 2000, NT, XP, and Linux.
7. In the Remote User and Remote Password fields, type the user ID and
password to be used for remote calls while debugging.
The user ID and password that are used for remote calls while debugging are
separate from the user ID and password that are used to access a SQL
database.
8. Type the port number for the EGL debugger in the EGL Debugger Port value
field. The default is 8345.
328 EGL Programmer’s Guide
9. Select the type of character encoding to use when processing data during a
debugging session in the Character encoding field. The default is the local
system’s file encoding. For more information, see “Character encoding options
for the EGL debugger” on page 327.
10. To specify external Java classes for use when the debugger runs, modify the
class path. You might need extra classes, for example, to support MQSeries®,
JDBC drivers, or Java access functions.
The class path additions are not visible to the WebSphere Application Server
test environment, but you can add to that environment’s classpath by working
on the Environment tab of the server configuration.
Use the buttons to the right of the Class Path Order section.
v To add a project, JAR file, directory, or variable, click the appropriate
button: Add Project, Add JARs, Add Directory, or Add Variable.
v To remove an entry, select it and click Remove.
v To move an entry in a list of two or more entries, select the entry and click
Move Up or Move Down.11. To restore the default settings, click Restore Defaults.
12. To save your changes, click Apply or, if you are finished setting preferences,
click OK.
Debug behavior mapping
When you debug a program that calls another program or a service, the debugger
can execute either the EGL source code or the generated code for the called
program or service. By default, the debugger uses the EGL source code. To use the
generated code, add an entry to the ″Debug behavior mapping″ table.
Add entries as follows:
1. From the main menu, click Window → Preferences.
2. In the Preferences window, expand EGL in the tree, expand Debug, and click
Debug Behavior Mapping.
3. For calls to programs, click the Called Programs tab. For each row of the table,
specify the following fields:
Bypass source
Select this checkbox if you want the debugger to attempt to use the
generated source rather than the EGL source.
Call target
The name of the program that is called from the program that you are
debugging. You can use an asterisk (*) at the end of the target as a
wildcard.
Part mapping field
The fully qualified name of the program or service that you want the
debugger to run when the program in Call target is called. Do not use
an asterisk in this field.4. For calls to services, click the Service References tab. For each row of the table,
specify the following fields:
Bypass source
Select this checkbox if you want the debugger to attempt to use the
generated source rather than the EGL source.
Debugging EGL applications 329
Service binding key
The name of the binding key in the deployment descriptor for the
service that you are calling.
Part mapping field
The fully qualified name of the service that you want the debugger to
run when the service in Service binding key is called. Do not use an
asterisk in this field.
SQL database access
To determine the user ID and password to use for accessing an SQL database, the
EGL debugger considers the following sources in order:
1. The build descriptor used at debug time; specifically, the sqlID and
sqlPassword build descriptor options.
2. The SQL preferences page, as described in “Setting preferences for SQL
database connections” on page 181; at that page, you can also specify other
connection information.
3. An interactive dialog that is displayed at connection time. This dialog is
displayed when you select the check box Prompt for SQL user ID and
password when needed.
The user ID and password that are used to access an SQL database are separate
from the user ID and password that are used to make remote calls while
debugging. To set the user ID and password for remote calls while debugging, see
the earlier instructions for setting preferences in the debugger.
EGL debugger port
The EGL debugger uses a port to establish communication with the Eclipse
workbench. The default port number is 8345. If another application is using that
port or if that port is blocked by a firewall, set a different value as described in the
earlier instructions for setting preferences in the EGL debugger.
If a value other than 8345 is specified as the EGL debugger port and if an EGL
program will be debugged on the J2EE server, you must edit the server
configuration:
1. Go to the Environment tab, System Properties section.
2. Click Add.
3. In the Name field, type com.ibm.debug.egl.port.
4. In the Value field, type the port number. Related concepts
“Preferences” on page 147EGL preferences affect the way the workbench displays and works with EGL.
“Debugging EGL applications” on page 307
“Character encoding options for the EGL debugger” on page 327 Related tasks
“Setting preferences for SQL database connections” on page 181
330 EGL Programmer’s Guide
Appendix. Notices
Note to U.S. Government Users Restricted Rights - Use, duplication or disclosure
restricted by GSA ADP Schedule Contract with IBM Corp.
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in
other countries. Consult your local IBM representative for information on the
products and services currently available in your area. Any reference to an IBM
product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product,
program, or service that does not infringe any IBM intellectual property right may
be used instead. However, it is the user’s responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not give you
any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:
IBM World Trade Asia Corporation
Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106-0032, Japan
The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or
implied warranties in certain transactions, therefore, this statement may not apply
to you.
This information could include technical inaccuracies or typographical errors.
Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the publication. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.
Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those Web
sites. The materials at those Web sites are not part of the materials for this IBM
product and use of those Web sites is at your own risk.
© Copyright IBM Corp. 1996, 2007 331
IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact:
IBM Corporation
Lab Director
IBM Canada Ltd. Laboratory
8200 Warden Avenue
Markham, Ontario, Canada L6G 1C7
Such information may be available, subject to appropriate terms and conditions,
including in some cases, payment of a fee.
The licensed program described in this information and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement, or any equivalent agreement
between us.
Any performance data contained herein was determined in a controlled
environment. Therefore, the results obtained in other operating environments may
vary significantly. Some measurements may have been made on development-level
systems and there is no guarantee that these measurements will be the same on
generally available systems. Furthermore, some measurements may have been
estimated through extrapolation. Actual results may vary. Users of this document
should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of
those products, their published announcements or other publicly available sources.
IBM has not tested those products and cannot confirm the accuracy of
performance, compatibility or any other claims related to non-IBM products.
Questions on the capabilities of non-IBM products should be addressed to the
suppliers of those products.
All statements regarding IBM’s future direction or intent are subject to change or
withdrawal without notice, and represent goals and objectives only.
All IBM prices shown are IBM’s suggested retail prices, are current and are subject
to change without notice. Dealer prices may vary.
This information is for planning purposes only. The information herein is subject to
change before the products described become available.
This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include the
names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which
illustrate programming techniques on various operating platforms. You may copy,
modify, and distribute these sample programs in any form without payment to
332 EGL Programmer’s Guide
IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating
platform for which the sample programs are written. These examples have not
been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or
imply reliability, serviceability, or function of these programs. You may copy,
modify, and distribute these sample programs in any form without payment to
IBM for the purposes of developing, using, marketing, or distributing application
programs conforming to IBM’s application programming interfaces.
Each copy or any portion of these sample programs or any derivative work, must
include a copyright notice as follows:
© (your company name) (year). Portions of this code are derived from IBM Corp.
Sample Programs. © Copyright IBM Corp. 2000, 2004. All rights reserved.
If you are viewing this information softcopy, the photographs and color
illustrations may not appear.
Programming interface information
Programming interface information is intended to help you create application
software using this program.
General-use programming interfaces allow you to write application software that
obtain the services of this program’s tools.
However, this information may also contain diagnosis, modification, and tuning
information. Diagnosis, modification and tuning information is provided to help
you debug your application software.
Warning: Do not use this diagnosis, modification, and tuning information as a
programming interface because it is subject to change.
Trademarks and service marks
The following terms are trademarks of International Business Machines
Corporation in the United States, other countries, or both:
v AIX
v CICS
v CICS/ESA®
v ClearCase
v DB2
v IBM
v IMS
v Informix
v iSeries
v MQSeries
v MVS
v OS/400®
v RACF®
v Rational
v VisualAge
v WebSphere
v z/OS
Appendix. Notices 333
Intel® is a trademark of Intel Corporation in the United States, other countries, or
both.
Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the
United States, other countries, or both.
Linux is a trademark of Linus Torvalds in the United States, other countries, or
both.
Microsoft, Windows, and Windows NT® are trademarks of Microsoft Corporation
in the United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other
countries.
Other company, product or service names, may be trademarks or service marks of
others.
334 EGL Programmer’s Guide
Index
Aadd EGL keyword
records 156
AJAX requestsEGL Web pages 219
external requests 229
refresh requests 223
submit requests 226
applicationsdebugging in EGL 307
EGL artifacts 59
EGL cheat sheets 140
EGL Console UI 267, 280
EGL deployment descriptor files 80
argument stackC functions 117
ArrayDictionary EGL data part 87
arraysEGL data parts 88
BBIGINT data type
C functions 113
binding functionsEGL shortcuts 200
bindingsJSF controls to EGL elements 187
JSPs 183
variables to services 260
breakpointsEGL debugger 316
build control partdescription 96
build descriptor optionsEGL version 7.0 changes 27
build descriptor partdescription
description 96
build descriptorsEGL debugger 315
runtime SQL database
connections 168
build filesdescription 76
EGL 79
build partsoverview 96
build pathsediting in EGL 73
overview 71
build projectsJava source code 72
button widgetsEGL Console UI elements 274
CC
mapping data to EGL 107
C data typesEGL primitive types compared 121
C functionsinvoking 112
using with EGL 109
C functions in EGLBIGINT 113
DATE 114
DATETIME 115
DECIMAL 116
INTERVAL 115
pop functions 117
return functions 120
callsJava from EGL 104
cancelOnPageTransition EGL
property 203
capabilitiesenabling for EGL 11
character encodingEGL debugger options 327
character typesEGL primitives 84
cheat sheetsopening in EGL 140
check boxesEGL Console UI elements 276
user input in EGL 197
clientsEGL binding 259
code assistantEGL overview 132
code generationEGL
data access 155
debugging 322
JSF data table properties 245
JSF image sizes 243
JSF input functions 244
source code editor 103
SQL statements 161
code snippetsinserting 139
overview 138
retrieving row values 205
setting focus 206
testing for session variables 213
updating table rows 210
code templatescreating 134
disabling 134
editing 135
enabling 134
exporting 136
importing 136
naming considerations 133
overview 133
removing 137
restoring defaults 138
combination boxesEGL Consule UI elements 278
commandsEGL debugger 312
commentsEGL source code
code lines 104
Console UIbuilding EGL applications 267
creating 269
EGL elements 267
elementsbutton widgets 274
check boxes 276
user input 278
modesrunning EGL applications 281
rich client widgets 272
running EGL applications 280
create functionadd EGL keyword 156
curses modeoverview 281
Ddata
forwarding between Web pages 202
data accessEGL code 155
data access applicationscreating with EGL 173
data partsEGL arrays 88
EGL miscellaneous 87
EGL overview 82
EGL version 7.0 21
data processing tasksoverview 155
data table check boxesselecting rows in EGL 197
data tablesretrieving row values 205
data typesmapping EGL to C 107
database connectionspreferences 181
SQLchanging 169
creating 162
runtime connections 168
database optionsEGL specifications 160
databasescreating EGL data access
applications 173
EGL SQL support 166
DataItem partsediting 141
dataItems EGL data parts 82
DataTable EGL data part 87
DATE data typeC functions 114
© Copyright IBM Corp. 1996, 2007 335
date typesEGL primitives 84
DATETIME data typeC functions 115
debuggerbreakpoints in EGL 316
build descriptors 315
character encoding options in
EGL 327
creating a launch configuration 320
creating a Listener launch
configuration 321
EGL commands 312
EGL overview 307
EGL preferences 328
EGL Web projects 323
invoking from EGL generated
code 322
preparing servers 323
starting a Web session 325
starting EGL programs 321
starting in EGL 319
stepping through programs 308
viewing variables in EGL 317
debuggingservices 326
DECIMAL data typeC functions 116
delete EGL keywordbasic I/O functions 156
delete functiondelete EGL keyword 156
deployment descriptor filesadding information 265
EGL applications 80, 96
EGL Web projects 183
shared protocols 266
design document for reportsJasperReports 285
development workbenchoverview 1
Dictionary EGL data part 87
documentationEGL version 7 31
Eeditors
EGLcode assistant 132
overview 130
locating source files 146
preferencesfolding 149
imports 150
setting 148
EGL migrationcurrent version 32
EGL version 6.0 iFix 001migration 48
migration tool changes 49
property changes 52
EGL version 7.0build descriptor option changes 27
documentation 31
exception handling 29
interface updates 30
EGL version 7.0 (continued)language changes 13
manual changes 46
manual changes after migration 46
migration 34, 36
migration tool 37
new features 12
parts 21
services 29
unsupported features 57
validation changes 19
eglpath EGL build path 71
elementsEGL Console UI applications 267
encryptionpasswords in EGL 122
event handlersJSF controls 242
exceptionshandling
EGL version 7.0 29
overview 123
exporting filesEclipse workbench 69
exporting projectsProject Interchange 69
external servicescalling 256
exposing 263
providing access 263
ExternalType EGL logic partdescription 90
Ffacets
EGL projects 66
featuresEGL projects 66
File Search viewEGL 142
filesbuild
overview 76
creatingEGL source files 77
creating source 77
EGLsearches 142
source code editor 103
EGL application artifacts 59
sequential files in EGL 158
sharing in EGL 67
folderscreating source folders in EGL 74
EGL application artifacts 59
foldingpreferences 149
form fieldssetting focus 206
FormGroup EGL data part 87
functionsbinding JSF buttons in EGL 188
EGLbinding JSF controls 187
commands when pages load 203
functions (continued)EGL (continued)
version 7.0 unsupported
features 57
EGL projects 66
Ggeneratable parts
EGLdescription 81
generationeglpath 71
preferences 152
generation processcontrolling 96
get EGL keywordhandling records 156
Hhandler parts
creating 292
Handler partscreating Web pages in EGL 186
handlers EGL logic partsoverview 90
II/O functions
EGL records 156
I4GL data typesEGL primitive types compared 121
import organizationEGL editor 150
importing filesEclipse workbench 69
importing projectsProject Interchange 69
interface EGL logic partdescription 90
Interface partcreating 94
creating from service 95
INTERVAL data typeC functions 115
JJasper reports
adding support to projects 300
application elements in EGL 284
JasperReportsXML design document 285
JavaEGL calls 104
JavaScript functionsJSF control event handlers 242
JavaServer Faces (JSF)binding buttons to EGL
functions 188
binding controls to EGL
elements 187
336 EGL Programmer’s Guide
JavaServer Faces (JSF) (continued)binding single-select controls to EGL
variables 194
changing image sizes with EGL
code 243
component interface support 246
controlsaccessing in EGL 236
binding to services in EGL 200
EGL variables 190
event handlers 242
style changes with EGL code 240
creating Web pages 186
data tablescheck boxes in EGL 197
properties in EGL code 245
EGL Web pageselements 183
navigation function 201
handler part propertiesWeb page data 202
Handler partschanging style classes in EGL 241
EGL preferences 246
input functions in EGL code 244
link target changes in EGL 239
JavaServer Pages (JSP)EGL Web applications 183
JSP pageschanging JSF image size with EGL
code 243
Llanguage changes
EGL version 7.0 13
large object typesEGL primitives 84
launch configurationsexplicit 320
Listener 321
viewing implicitly created
configurations 321
library EGL logic partdescription 90
Library partcreating 92
link edit partdescription 96
linkage options partdescription 96
List viewEGL parts 144
local servicescalling 254
localizationresource bundles 217
Web applications 214
logic partsEGL overview 90
EGL version 7.0 21
Interfacecreating 94
creating from service 95
JSF HandlerEGL preferences 246
logic parts (continued)Library
creating 92
Servicecreating 92
creating from called program 93
creating WSDL from 96
Mmanual changes
EGL version 7.0 46
menusenabling capabilities in EGL 11
migratingEGL current version 32
migrating EGL codeversion 6.0 iFix 001 48
version 7.0 36
manual changes after
migration 46
migrationpreferences
EGL-to-EGL 34
migration toolEGL version 7.0 37
migration tool changesEGL version 6.0 iFix001 49
move statementsEGL version 7.0 migration 37
moving partsEGL 98
Nnavigation rules
EGL Web pages 201
numeric typesEGL primitives 84
OonConstructionFunction EGL
function 203
onPostRenderFunction EGL function 203
onPreRenderFunction EGL function 203
Ppackages
creating 76
overview 74
Page Designerbindings 183
support 183
page lifecylesEGL functions 203
pagescommands when pages load 203
partsEGL
Record parts 85
searches 142
version 7.0 21
parts (continued)generatable in EGL
description 81
introduction 81
propertiesintroduction 99
references 145
renaming in EGL 97
searching for 143
viewing lists in EGL 144
Parts List viewEGL 142
Parts Reference viewEGL
generatable logic parts 145
searches 142
passwordsencryption in EGL 122
pop functionsC 117
preferencesEGL
debugger 328
setting 147
Web applications 246
EGL editorfolding 149
import organization 150
overview 148
generation 152
overview 147
source styles 151
SQL database connections 181
SQL retrieve 181
textEGL overview 152
primitive typesC data types compared 121
mapping EGL to C 107
primitivesEGL data parts 82
EGL data types 84
procedurescalling in EGL 176
program EGL logic partdescription 90
program partscreating 91
programming taskscompleting in EGL 103
programsEGL debugger 308
starting in the EGL debugger 321
Project Explorer viewEGL 142
Project Interchangeproject sharing 69
projectsadding Jasper reports support 300
converting to EGL plug-in 65
creatingEGL plug-in 65
EGL Web 63
overview 62
debugging in EGL 319
EGL application artifacts 59
EGL database options 160
Index 337
projects (continued)EGL facets 66
EGL features 66
EGL functions 66
linking in the EGL build path 73
new EGL projects 147
overview 61
sharing in EGLoverview 67
repositories 71
propertieschanges in EGL version 6.0 iFix 001
migration 52
changing JSF data tables with EGL
code 245
EGLcancelOnPageTransition 203
introduction 99
JSF Handler for data transfer 202
Rradio button group widget
EGL Consule UI 278
read functionget EGL keyword 156
record arraysbinding JSF controls to EGL
variables 194
Record EGL part 85
Record stereotypeEGL parts 85
recordsEGL data parts 82
EGL read/write functions 156
refactoringEGL source files 77
moving EGL parts 98
moving EGL source files 79
renaming EGL parts 97
renaming partsEGL 97
replace EGL keyword 156
report design filescompiling in EGL 284
report driver programfunctions in EGL 284
report handlercreating 292
subreports 298
report handler EGL logic part 284
reportscode for invoking reports 289
creating with EGL 283
exported file formats 289
exporting 289
running 296
templates for 297
writing report-driver code 289
repositoriessharing EGL projects 71
resource associationssetting up in EGL 158
resource associations partdescription 96
resource bundlescreating 217
resource bundles (continued)locales 218
overview 214
retrievaldata processing tasks 155
retrieve featureSQL 170
retrieve preferencesSQL 181
return functionsC 120
Rich Client Platform (RCP) modeEGL overview 281
rich client widgesEGL Console UI 272
runtime messagescustomizing EGL system
messages 127
SSearch view
EGL 142
searchesEGL items 142
sequential filesEGL projects 158
serversEGL Web page previews 235
preparing for debugging 323
service EGL logic partdescription 90
service partscreating 92
creating from called programs 93
creating WSDL 96
servicesbinding from WSDL files 257
binding JSF controls in EGL 200
callingexternal 256
local 254
debugging 326
EGL client binding information 259
EGL code 260
EGL version 7.0 29
elements 249
exposing 263
overview 249
providing access 263
shared protocols 266
types 252
session objectsEGL Web pages 211
session variablesdetecting 213
EGL Web pages 211
setCursorFocuscode snippets 206
shared protocolscreating 266
snippetsinserting 139
overview 138
retrieving row values 205
setting focus 206
testing for session variables 213
snippets (continued)updating table rows 210
source assistantJSF controls in EGL 236
overview 141
source codebuilding projects 72
comments 104
source controlsharing EGL projects 71
source filescode assistant 132
comments 104
creating 77
description 76
locating in the Project Explorer
view 146
moving in EGL 79
renaming in EGL 77
source folderscreating in EGL 74
source stylepreferences 151
SQLconnection preferences 181
database connectionschanging 169
creating 162
runtime connections 168
EGL supported database
managers 166
explicit 175
retrieve feature 170
retrieve preferences 181
SELECT statementsvalidating 179
statementsworking with 175
stored procedures in EGL 176
working with data in EGL 161
SQLRecord partsin prepare statements 177
stereotypesEGL Record 85
storagedata processing tasks 155
STRING arraysbinding JSF controls to EGL
variables 194
style classeschanging from EGL JSF
Handlers 241
styleschanging JSF controls with EGL
code 240
subreportscreating 298
Swing modeoverview 281
system functionsEGL version 7.0 24
EGL version 7.0 migration 37
system librariesEGL version 7.0 24
system messagesEGL runtime customization 127
338 EGL Programmer’s Guide
system variablesEGL version 7.0 24
EGL version 7.0 migration 37
Ttemplates
creating in EGL 134
disabling in EGL 134
editing in EGL 135
EGL naming considerations 133
EGL overview 133
enabling in EGL 134
exporting from EGL 136
importing in EGL 136
removing in EGL 137
restoring defaults in EGL 138
textlocalizing 214
preferencessetting in EGL 152
time typesEGL primitives 84
trademarks 333
UUNIX screen options
EGL Console UI 281
UNIX usersEGL Console UI screen options 281
update functionreplace EGL keyword 156
user interfaceEGL version 7 updates 30
user interface (UI) partsJSF Handler
EGL preferences 246
user interfacesEGL console 269
user sessionsdata storage for EGL Web pages 211
Vvalidation
changes in EGL version 7.0 19
validation changesEGL version 7.0 19
variablesbinding JSF controls to EGL
elements 187
binding JSF controls to EGL
variables 194
binding to services 260
EGLarrays 88
binding to Web page controls 190
viewing in the EGL debugger 317
VisualAge Generatorcompatibility preferences 147
WWeb applications
debugging in EGL 319
EGL debugger 323
EGL elements 183
EGL preferences 246
EGL tasks 185
Page Designer 183
Web diagramsEGL Web projects 183
Web page controlsbinding to EGL variables 190
Web pagesAJAX requests 219
external requests 229
refresh requests 223
submit requests 226
creating in EGL 186
EGL commands when pages
load 203
forwarding data 202
navigation rules in EGL 201
previewing EGL pages 235
session data storage with EGL 211
Web projectsEGL elements 183
JSF component interface support 246
JSF link targets in EGL 239
Web servicesbinding
EGL services 259
WSDL 257
building 249
callingexternal 256
local 254
deployment information 265
EGL code 260
elements 249
exposing 263
providing access 263
shared protocols 266
types 252
workbenchoverview 1
WSDLbiding 257
WSDL filescreating 96
XXML report design document
creating 285
Index 339
340 EGL Programmer’s Guide
����
Printed in USA
top related