EGL Programmer's Guidepublic.dhe.ibm.com/software/dw/rational/pdf/com_ibm_etools_egl_pg.pdf · Rational Business Developer EGL Programmer’s Guide Version 7 Release 01. Rational

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


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


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


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.


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


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


versions. Related tasks


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.


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:


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


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









“Documentation changes in EGL V7.0” on page 31



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


“Language changes in EGL V7.0” on page 13This topic lists the changes to the EGL language in version 7.0.


Related tasks



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


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


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


v Program

v Handler

v Library

v Record

Related Concepts





Related tasks


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.


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.


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



“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





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)


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



Related tasks


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.


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



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











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.


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


EGL code to EGL V7.0” on page 36.

Version 6.0.1, up to but not including version 7.0


EGL code to EGL V7.0” on page 36. Related concepts


“Changes made by the V7.0 migration tool” on page 37



“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:


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





Related tasks


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:



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.


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


“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");


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


SysLib.connect( a, b, c ); SQLLib.connect( a, b, c,

explicit,

serializableTransaction );

SysLib.connect( a, b, c, d ); SQLLib.connect( a, b, c,

explicit,


SysLib.connect( a, b, c, d, e ); SQLLib.connect( a, b, c, e,


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()


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


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


(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


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;


Table 11. Migrated conversion functions (continued)


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


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


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


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


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.


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


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


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


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


item1 string

{ value = "item1ValueProp" }

= "item1Initializer";

item1 string

{} = "item1ValueProp";


Table 19. Changes to the value property in variables in PageHandler parts (continued)


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




Related tasks


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


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:



myResult = myStringNumber as decimal() + 5;

You must add a length to the DECIMAL type, as in the following:



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


“Validation changes in EGL V7.0” on page 19 Related tasks

“Migrating EGL code to EGL V7.0” on page 36



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.


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:



c. Click Advanced.

d. In the Advanced window, expand EGL Developer and select the EGL V6.0

Migration check box.

e. Click OK.


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



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.


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()


Table 20. Changed variable and function names from the sysLib and sysVar

libraries (continued)


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)


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



“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


action actionFunction

boolean isBoolean

getOptions getOptionsRecord

msgDescriptor msgDescriptorRecord

onPageLoad onPageLoadFunction

openOptions openOptionsRecord

putOptions putOptionsRecord

queueDescriptor queueDescriptorRecord


Table 21. Renamed properties (continued)


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


– 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


{ 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.


Table 23. Changes to the tableNames property


{ 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


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


“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



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


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.


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″.


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:


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


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.


14. In the Java Source Directory field, type the name for the generated code

folder. The default name is src.




Related tasks


“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



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” 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.


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 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


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


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


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.


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.



“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




Sharing projects in a repository

These general guidelines describe EGL files that you will most likely share in a



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


“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


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


“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.


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


Related tasks

“Creating source folders”


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.



“Source folders” Related tasks



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.


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


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


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



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


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 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


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 parts” on page 81Parts are the building blocks of EGL applications.

Related tasks


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


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


Related tasks

“Moving a source file” on page 79You can use the refactoring function of the workbench to move source files and


“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.


Moving a source file

You can use the refactoring function of the workbench to move source files and


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.



“Moving parts” on page 98You can use the refactoring function of the workbench to move parts between


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.


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



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


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.

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 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


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


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 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


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


“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.


Not all primitives are listed here; for the complete list, see ″Primitive data types″ in


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:


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



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:


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


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



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.


Related concepts



“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 = "$"};


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 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);


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


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.


To create a program file with a program part, do as follows:



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:




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:




3. In the New window, expand EGL and double-click Service.





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.



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



“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.


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



“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:




2. In the workbench, click File → New → Interface. The New EGL Interface Part

wizard opens.




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



“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.



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.




“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.


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


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.


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.


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


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.


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




Related tasks





“Moving parts”You can use the refactoring function of the workbench to move parts between


Moving parts

You can use the refactoring function of the workbench to move parts between


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.


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



Related tasks








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


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:


{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.


Related concepts




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


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


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





code. Related tasks


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.


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:




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.





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.


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



constructor();


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


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.”


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


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.


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

};


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


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:


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”







“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


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”




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.


rdatestr( ) Converts an internal DATE to a character string format


http://www-306.ibm.com/software/data/informix/pubs/library/



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



Related reference


“DATETIME and INTERVAL functions for C”



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.


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





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



Related reference



“DECIMAL functions for C”


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.


deccvasc( ) Converts C int1 type to DECIMAL type

dectoasc( ) Converts DECIMAL type to C int1 type

deccvint( ) Converts C int type to DECIMAL type





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



Related reference





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)




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)


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


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)


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)


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











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:


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



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









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


C data types Equivalent I4GL data

type

Equivalent EGL primitive type

intvl_t INTERVAL INTERVAL

Related reference


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.


http://www.ibm.com/developerworks/java/jdk/


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



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:


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



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)




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);



end

end

function FuncTwo(myRec serialRecordType)

get next myRec;

end


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



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.


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


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:


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



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.


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


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


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.


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


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





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







“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


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:


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:




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.


5. Click OK to close the window. Related concepts

“Code templates” on page 133 Related tasks

“Creating code templates”





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:


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.


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.



Related concepts











Editing code templates

You can modify existing code templates to fit your specific coding needs.

To edit an existing code template, follow these steps:




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.



If the code template you edited is one of the templates provided with the product,

you can revert to the original template as follows:




3. Click the desired template from the table and then click Revert to Default.




Related concepts








“Importing code templates”

“Exporting code templates”



Exporting code templates

You can export code templates to a file system.

To export code templates, follow these steps:




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








“Importing code templates”



Importing code templates

You can import code templates from a file system. To import code templates,

follow these steps:





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









“Removing code templates”


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:




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.



Related concepts











“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:




3. To return to the template list that was in effect at installation time, click Restore

Defaults.



Related concepts



“Code snippets”Snippets are code objects that are reusable programming objects. Snippets can








“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.


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 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:


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
















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.


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.


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



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.


“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 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




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




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:


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


Related tasks



“Viewing part references”The EGL Parts Reference view shows a hierarchical view of the parts that are



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.




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


Related tasks


“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





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



Related reference





code.

Preferences

EGL preferences affect the way the workbench displays and works with EGL.

Related tasks




functionality.


“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 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:


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


“Features and facets of EGL projects” on page 66EGL projects can have additional abilities, added through features and facets.


Related tasks




functionality.


“Setting preferences for the EGL editor”



Setting preferences for the EGL editor

To specify the EGL editor preferences, follow these steps:


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.


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


Related tasks





functionality.

“Setting general preferences” on page 147


“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 EGL text” on page 152 Related reference



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:


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.




Related tasks




functionality.



“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:


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;



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.*;


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


Related tasks




functionality.



“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:


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



Related tasks




functionality.

“Setting general preferences” on page 147





Setting generation preferences

To specify preferences for EGL generation, follow these steps:


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



Setting preferences for EGL text

To change how text is displayed in the EGL editor, follow these steps:


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.


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





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:


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.


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;


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.


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!";


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



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.


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


“Reading and writing records” on page 156

“Retrieving SQL table data” on page 170





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.


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.


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


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.


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





“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


Table 30. Supported databases (continued)

Database


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


Table 30. Supported databases (continued)

Database


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






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.


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



“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.


2. In the Database Explorer view, right-click the database connection, and then

click Delete. Related reference



“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:


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.


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


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






“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


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.


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.


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



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).


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.


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)

};


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



Executing a prepared statement

The prepare keyword constructs an SQL statement from a string. Then, you can


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:


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";


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.


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"]],


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};



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


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


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.


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



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:


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



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.


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.



“Accessing data with EGL code” on page 155 Related tasks





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.


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.


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.




“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.









“Storing data in the user’s session” on page 211





“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.


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.


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


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.


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 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.


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.


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.


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.


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>


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


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>


preRender="#{formTestPage._preRender}"

postRender="#{formTestPage._postRender}">


value="#{formTestPage.stringOne}"

binding="#{formTestPage.stringOne_Ref}"></h:inputText>

<br>



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>


</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







“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











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:


{"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.


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"}


{"First choice","Second choice",

"Third choice","Fourth choice",

SelectedValueItem = selectedChoice};


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";


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:


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};


outputMessage string;


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: "


+ 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














“Returning the indexes of selected rows in a data table”



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


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"}


//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);


//initialize the array of customers

purchaseList[1].custName = "Company A";

purchaseList[1].totalPurchases = "500.23";

purchaseList[2].custName = "Company B";


purchaseList[3].custName = "Company C";


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



















“Binding JSF controls to services”Binding functions and variables from a service to controls on a Web page is no


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.


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



















“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>


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


Forwarding data between Web pages

You can use the forward statement to pass data from one Web page to another


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:



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


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:


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


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


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


Related concepts




“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



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">



</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





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.


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}


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.");


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:


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.


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:


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.


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,


//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





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.


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:


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:


handler sessionPageTwo type JSFHandler

{view = "sessionPageTwo.jsp",

onPreRenderFunction = onPreRender}

submittedRecord sessionRecord;


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.


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.


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





“Storing data in the user’s session” on page 211


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:


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:


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.


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.


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


“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.


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



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


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



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:


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:


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>


preRender="#{calculatorPage._preRender}"

postRender="#{calculatorPage._postRender}">


<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>

<h:inputText id="input2" value="#{calculatorPage.field2}"

binding="#{calculatorPage.field2_Ref}" styleClass="inputText">

</h:inputText>

</td>

</tr>

<tr>

<td align="left">Operation:</td>


<td>

<h:selectOneMenu id="operationComboBox"

styleClass="selectOneMenu" value="#{calculatorPage.operation}">


<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>

<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>


</body>

</f:view>

</html>

The following is the code of the JSF Handler that goes with this page:


handler calculatorPage type JSFHandler


view = "calculatorPage.jsp"}

field1 float;

field2 float;

operation string;

output string;


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")


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


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.


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.


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


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.


<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.




trigger requests.







trigger.



the view.











</hx:behavior>

</h:inputText>


5. Create the request by specifying the panel to update:

a. On the Web page, select the panel control.



c. On the Properties view, go to the Ajax tab under the type of panel control.


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









else




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 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










else



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.




trigger requests.







trigger.



the view.












</hx:behavior>

</h:inputText>


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.


c. On the properties view, go to the Ajax tab under the type of panel control.


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.


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>




title="Style">

</head>

<f:view>

<body>

<hx:scriptCollector id="scriptCollector1">



<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>


</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:


handler targetPage type JSFHandler

{view = "targetPage.jsp"}

end


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>




title="Style">

</head>

<f:view>

<body>


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>


</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:


handler sourcePage type JSFHandler



view = "sourcePage.jsp"}

message string = "No value set";


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 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.


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.


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:


import com.ibm.egl.jsf.*;


{view = "myPage.jsp",

viewRootVar = myViewRoot}

myViewRoot UIViewRoot;

myInputVar string = "Hello";

function changeColor()

myInputField HtmlInputText;

myInputField = viewRoot.findComponent("form1:text1");


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:


{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");


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.


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.


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:


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:



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









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.





import statement:







Follow these steps to change the style of a JSF control from an EGL JSF Handler:




access.

3. Click OK.


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.


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



“Changing the style class of a JSF control”

“Changing the target of a JSF link” on page 239





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.





import statement:







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.








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







“Setting event handlers for a JSF control”


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.





import statement:







Follow these steps to assign or remove an event handler from a JSF control:



2. In the EGL Source Assistant window, select the JSF image control that you want

to access.

3. Click OK.








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







“Setting the size of a JSF image”


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.





import statement:







Follow these steps to change the size of a JSF image control with an EGL JSF

Handler:



2. In the EGL Source Assistant window, select the JSF image control that you want

to access.

3. Click OK.




example, the code to access a JSF image control might look like this:


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






“Enabling or disabling JSF controls”



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.





import statement:







To enable or disable a JSF control with an EGL JSF Handler:




access.

3. Click OK.







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);


To disable the text control, add this code:

text1.setDisabled(yes);

Related tasks








“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.





import statement:







To change the properties of a JSF data table control:



2. In the EGL Source Assistant window, select the JSF data table control that you

want to access.

3. Click OK.





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

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



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:


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


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.






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



“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





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:


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.


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


returns (int);


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


returns (int)


end


returns (int)


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.







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.


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













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


returns (int)


end


returns (int)


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


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.



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:




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





“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.


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



“Adding service client binding information from a WSDL file”Service client binding information tells EGL how to connect to a service at run




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


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.


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





“Adding service client binding information for an EGL service”Service client binding information tells EGL how to connect to a service at run


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


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.


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










“Creating and binding a variable to an external service”After you have created binding information for an external service, you can use


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);


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);


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



service.







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


returns (int);


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


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


returns (int)

return(intOne + intTwo);

end


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







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







applications.


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








service.


Building EGL Console User Interface applications

Console User Interface, or Console UI, is a style of user interface similar to that


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.




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


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.


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()


// 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







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








name="first_name"};


name="last_name"};


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:


function main()

myWindow Window {name = "My Window", position = [1,1]};




customer_id int;


openUI myConsoleRec


end

end

end









name="first_name"};


name="last_name"};


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:


function main()

myWindow Window {name = "My Window", position = [1,1]};




customer_id int;


openUI myConsoleRec


onEvent(AFTER_FIELD:"customer_id")

if (customer_id == 3)

first_name = "John";

end

end

end

end









name="first_name"};


name="last_name"};


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




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)


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





mode. Related tasks






“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.

“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")


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",


bounds=[4,4,1,15]};

exitButton consoleButton

{name = "exitButton",

text = "Click to exit",

bounds=[6,4,1,15]};

end

Related concepts






mode. Related tasks








“Adding a combo box or radio button group widget” on page 278The combo box and radio button group are similar because they both require








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",


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


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]};


myForm checkForm {};



textValue string = "Text.";


myCheckVar boolean = false;


openUI myForm

bind textValue, myCheckVar


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]};




bounds=[6,4,1,15]};

end

Related concepts






mode. Related tasks









“Adding a combo box or radio button group widget”The combo box and radio button group are similar because they both require


“Adding a button widget” on page 274The button widget is the simplest rich client widget because it does not need to



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


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]};


myForm radioComboForm {};

myForm.myCombo.items =

["Option One", "Option Two", "Option Three"];

myForm.myRadio.items =

["Option Four", "Option Five", "Option Six"];


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);


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]};


myForm radioComboForm {};

myForm.myCombo.items =

["Option One", "Option Two", "Option Three"];

myForm.myRadio.items =

["Option Four", "Option Five", "Option Six"];




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;


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]};




bounds=[10,4,1,15]};

end


Related concepts






mode. Related tasks




“Running Console UI applications”The process for running a Console UI application differs slightly depending on









“Adding a button widget” on page 274The button widget is the simplest rich client widget because it does not need to



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.


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



“Console UI modes”EGL supports three modes in which you can run Console UI applications:



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.


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


used on a UNIX-based program that interacts with a character-based terminal. Related tasks




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:


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


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 the report design file”The report design file specifies the layout and appearance of the report. Unless







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

http://jasperforge.org

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>


<text>

<![CDATA[First name: ]]>

</text>

</staticText>

<staticText>


<text>

<![CDATA[Last name: ]]>

</text>

</staticText>

<staticText>


<text>

<![CDATA[Phone: ]]>


</text>

</staticText>

</band>

</pageHeader>

<detail>

<band height="30">

<textField>


<textFieldExpression>

<![CDATA[$F{CUSTOMER_ID}]]>

</textFieldExpression>

</textField>

<textField>



<![CDATA[$F{FIRST_NAME}]]>


</textField>

<textField>



<![CDATA[$F{LAST_NAME}]]>


</textField>

<textField>



<![CDATA[$F{PHONE}]]>


</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


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}]]>


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

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






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

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






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


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




“Writing code to drive a report”A report-driver program is an ordinary EGL program that runs a report using a


Writing code to drive a report

A report-driver program is an ordinary EGL program that runs a report using a


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.


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


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


"c:\\workspace\\report_project\\" ::

"bin\\report_package\\myReport.jasper";

myReport.reportDestinationFile =


"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.author = "Charles Dickens";

recArrayElement.title="Our Mutual Friend";



recArrayElement.author = "Gustave Flaubert";

recArrayElement.title="Madame Bovary";

recArrayElement.description = "French Novel";


recArrayElement.author = "M. Lermontov";

recArrayElement.title="Hero of Our Time";

recArrayElement.description = "Russian Novel";


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);


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 an EGL report handler”




“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


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:


handler my_report_handler type jasperReport


report_title String;

// Jasper callback function


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:



item_count int;


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:



employee_first_name String;


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:



customer_array customerRecordType[];

c customerRecordType;



customer ReportData;

//create the ReportData object for the Customer subreport

c.customer_num = getFieldValue("c_customer_num");

c.fname = getFieldValue("c_fname");


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!″


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()]]>


</textField>

</band>

</summary>

...

</jasperReport>

The phrase ″Hello, world!″ will print at the end of the report.


Related concepts




“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


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








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:


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 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/>


<![CDATA[$F{CUST_NO} + " " + $F{CUST_NAME}]]>


</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)


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/>


<![CDATA["Invoice # " + $F{INVOICE_NO} + " total: " +

$F{ORDER_TOTAL}]]>


</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






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:




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



“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 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.


http://prdownloads.sourceforge.net/itext

http://prdownloads.sourceforge.net/itext

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



“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.


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



“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.


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"]],


customerNumber STRING {column="C_NUMBER", maxLen=6};

customerName STRING {column="C_NAME", 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


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",


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.



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


– 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



“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()


//Provide some initial values for the array of items.

customerItems items[3];

customerItems[1].itemNumber=1;



customerItems[1].itemCost=12.50;

customerItems[2].itemCost=200;

customerItems[3].itemCost=49.95;

customerItems[1].itemQuantity=30;



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


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.


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



“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.


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.



Step over

Runs the next EGL statement and pauses, but does not stop within

functions that are invoked from the current function.


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.



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.


Related concepts

“Debugging EGL applications” on page 307 Related tasks


“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.



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.


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





Using breakpoints in the EGL debugger

This topic shows you how to use breakpoints in debugging your programs. You


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:


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





EGL debugger.

“Viewing variables in the EGL debugger”This topic shows you how to view variables in your program while your are


Viewing variables in the EGL debugger

This topic shows you how to view variables in your program while your are


Prerequisites

v An EGL project

v An EGL program or other logic part that needs debugging


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


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




“Configuring a server for EGL Web debugging” on page 323



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



“Creating an EGL Listener launch configuration” on page 321


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




EGL debugger.






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



“Starting a non-J2EE application in the EGL debugger”


EGL debugger.





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).


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




EGL debugger.





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.


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


“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.


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:


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


“Starting an EGL Web debugging session”


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


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


“Configuring a server for EGL Web debugging” on page 323


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()


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







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.


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


“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:


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.


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:


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.


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


“Debugging EGL applications” on page 307

“Character encoding options for the EGL debugger” on page 327 Related tasks



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.


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


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.


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


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


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


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 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



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


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



types 252

workbenchoverview 1

WSDLbiding 257

WSDL filescreating 96

XXML report design document

creating 285

Index 339


��

Printed in USA

Documents

EGL Programmer's Guidepublic.dhe.ibm.com/software/dw/rational/pdf/com_ibm_etools_egl_pg.pdf · Rational Business Developer EGL Programmer’s Guide Version 7 Release 01. Rational