Com.ibm.Etools.egl.Pg.pdf

May 12, 2018 | Author: Anand Singh | Category: Java Server Faces, Icon (Computing), Menu (Computing), Integrated Development Environment, Sql
Share
Report this link


Comments



Description

Rational Business DeveloperEGL Programmer’s Guide V ersion 7 Release 5.1 Rational Business Developer EGL Programmer’s Guide V ersion 7 Release 5.1 Note Before using this information and the product it supports, read the information in “Notices,” on page 609. This edition applies to version 7.1 of Rational Business Developer and to all subsequent releases and modifications until otherwise indicated in new editions. © Copyright International Business Machines Corporation 1996, 2008. US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. 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.5 . . . . . . . . . . 12 What’s new in EGL V7.1 . . . . . . . . . . 13 Language changes in EGL V7.1 . . . . . . . 14 Changes to parts in EGL V7.1 . . . . . . . 14 Changes to system libraries and variables in EGL V7.1 . . . . . . . . . . . . . . . . 15 Changes to build descriptor options in EGL V7.1 16 User interface changes in EGL V7.1 . . . . . 17 What’s new in EGL V7.0 . . . . . . . . . . 18 Language changes in EGL V7.0 . . . . . . . 19 Validation changes in EGL V7.0 . . . . . . 24 Validation changes in EGL V7.0 . . . . . . 26 Changes to parts in EGL V7.0 . . . . . . . 28 Changes to system libraries and variables in EGL V7.0 . . . . . . . . . . . . . . . . 32 Changes to build descriptor options in EGL V7.0 35 Changes to exception handling in EGL V7.0 . . 36 Changes to services in EGL V7.0 . . . . . . 36 User interface changes in EGL V7.0 . . . . . 37 Migrating from a previous version of EGL . . . . 38 Setting EGL-to-EGL migration preferences . . . 42 Migrating EGL code to EGL V7.0 . . . . . . 43 Migrating EGL code to EGL V6.0 iFix 001 . . . 56 Introduction to data parts Introduction to logic parts Introduction to build parts Renaming parts . . . Moving parts . . . . Properties . . . . . . Import and use statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 105 120 120 121 122 124 Working with EGL code . . . . . . . 127 Common programming tasks . . . . . . . . Turning lines of code into comment lines . . . Calling Java . . . . . . . . . . . . . Calling C functions with the call statement . . Calling C functions through EGL libraries . . . Working with substrings . . . . . . . . Encrypting passwords . . . . . . . . . Handling errors . . . . . . . . . . . Customizing runtime messages . . . . . . The EGL editor . . . . . . . . . . . . . Content assist . . . . . . . . . . . . . Code templates. . . . . . . . . . . . Code snippets . . . . . . . . . . . . . Inserting code snippets into EGL and JSP files Using cheat sheets. . . . . . . . . . . . Editing DataItem parts with the source assistant Searching for EGL files and parts . . . . . . . Searching for parts . . . . . . . . . . Viewing lists of parts . . . . . . . . . . Viewing part references . . . . . . . . . Locating an EGL source file in the Project Explorer view . . . . . . . . . . . . Preferences . . . . . . . . . . . . . . Setting general preferences . . . . . . . . Setting build descriptor preferences . . . . . Setting preferences for the EGL editor . . . . Setting the fonts used in the EGL editor . . . Setting preferences for folding in the EGL editor Setting preferences for formatting in the EGL editor . . . . . . . . . . . . . . . Setting preferences for organizing import statements in the EGL editor . . . . . . . Setting preferences for source styles . . . . . Setting generation preferences . . . . . . . Setting preferences for EGL text . . . . . . 127 128 128 131 133 146 146 148 152 155 157 158 164 165 166 167 168 168 169 171 172 172 173 174 175 176 176 177 178 179 180 180 Contents of an EGL application . . . . 67 Introduction to EGL projects . . . . . Creating an EGL project . . . . . Creating an EGL Web project . . . Creating an EGL plug-in project . . Renaming an EGL project. . . . . Features and facets of EGL projects . Sharing projects . . . . . . . . The EGL build path . . . . . . Source folders . . . . . . . . . Creating source folders . . . . . Introduction to EGL packages . . . . Creating an EGL package . . . . . Introduction to EGL files . . . . . . Creating EGL source files . . . . . Renaming a source file . . . . . Moving a source file . . . . . . Deleting a source file . . . . . . Creating EGL build files . . . . . Creating a deployment descriptor . . Introduction to EGL parts . . . . . Generatable parts and non-generatable © Copyright IBM Corp. 1996, 2008 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . parts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 71 73 74 75 76 79 83 86 87 87 89 89 90 91 92 93 94 94 95 96 Accessing data with EGL code . . . . 183 Common data access tasks . . . . . Reading and writing records . . . Writing and reading to files . . . Specifying database options at project Accessing an LDAP-compliant server Working with SQL data . . . . . . Best practices . . . . . . . . Result-set processing . . . . . . SQL records and their uses . . . . . . . . . . . . . creation . . . . . . . . . . . . . . . . 183 . 184 . 186 189 . 190 . 190 . 191 . 192 . 193 iii Compatibility . . . . . . . . . . . . Creating an SQL database connection . . . . Supported SQL database managers . . . . . Using an SQL database connection at run time Editing or deleting an SQL database connection Retrieving SQL table data . . . . . . . . Creating a data access application . . . . . Working with SQL statements . . . . . . . Setting preferences for SQL database connections . . . . . . . . . . . . . Setting preferences for SQL retrieve . . . . . Working with DL/I data . . . . . . . . . Example DL/I database . . . . . . . . . DL/I examples . . . . . . . . . . . . Working with MQ message queues . . . . . . Defining messages in EGL . . . . . . . . Defining resource associations for message queues . . . . . . . . . . . . . . Reading from and writing to message queues Using direct MQ API calls . . . . . . . . Using linkage options for MQ run-time library selection . . . . . . . . . . . . . . Working with iSeries objects . . . . . . . . Working with bidirectional data . . . . . . . Creating a bidirectional runtime file . . . . . Creating a bidirectional conversion table . . . 196 197 200 202 205 205 208 211 219 220 221 223 227 235 236 237 238 240 242 244 245 247 249 Transfer of control across programs 251 252 252 253 253 254 256 259 259 261 261 262 263 265 265 267 268 268 268 269 270 271 271 Reference information for special parameters on call or transfer statement . . . . . . . . . Format of a text or print form passed on a call Format of the dliLib.psbData structure . . . . Format of a PCBRecord . . . . . . . . . Calling programs in CICS environments . . . . Format of call statement parameters for CICS Calls from an EGL program to an EGL program Calls from an EGL program to a non-EGL program . . . . . . . . . . . . . . Calls from a non-EGL program to an EGL program . . . . . . . . . . . . . . Transferring control in CICS environments . . . Transfer to program . . . . . . . . . . Transfer to transaction . . . . . . . . . Transfer using show . . . . . . . . . . Using asynchronous tasks . . . . . . . . Calling programs in IMS and z/OS batch environments . . . . . . . . . . . . . Calls from an EGL program to an EGL program Calls from an EGL program to a non-EGL program . . . . . . . . . . . . . . Calls from a non-EGL program to an EGL program . . . . . . . . . . . . . . Calling a CICS program from an EGL z/OS batch program . . . . . . . . . . . . Transferring control in IMS BMP and z/OS batch environments . . . . . . . . . . . . . Transfer from an EGL program to an EGL program using transfer to program . . . . . Transfer from an EGL program to an EGL program using transfer to transaction . . . . Transfer to a non-EGL program using either transfer to program or transfer to transaction. Transfer from a non-EGL program to an EGL program using OS XCTL . . . . . . . Reference information for transfers . . . . Transferring control in the IMS/VS environment Transferring between conversational programs Transferring between nonconversational programs . . . . . . . . . . . . . Interfacing through serial files in IMS . . . Reference information for IMS/VS transfers . Transferring to and from IMSADF II programs . IMSADF II conversational processing . . . Transferring with conversational programs in ADF mode . . . . . . . . . . . . Transferring control in the iSeries COBOL environment. . . . . . . . . . . . . Transferring control in the iSeries RPG environment. . . . . . . . . . . . . Calling to and from Java programs . . . . . EGL-generated Java program to EGL-generated Java program . . . . . . . . . . . Non-EGL Java program to EGL program . . EGL-generated Java program to non-EGL Java program . . . . . . . . . . . . . EGL-generated Java program to DLL . . . EGL-generated Java program to .EXE or .BAT file . . . . . . . . . . . . . . . Calling an IMS program from EGL-generated Java code . . . . . . . . . . . . . . 271 . 272 . 272 275 276 . . . . . 281 284 286 293 294 . 295 . 299 . 300 . 300 . 300 . 300 . 301 . 301 . 301 . 301 Developing EGL programs for the VSE environment. . . . . . . . . . 305 Developing EGL programs for the IMS environment . . . . . . . . . . . . 307 Generating for the MPP region . . . . . . . Text UI programs . . . . . . . . . . . Basic programs . . . . . . . . . . . . Generating for the MPP IMS FastPath region . . . Generating for the IMS BMP region . . . . . . Effect of build descriptor options . . . . . . . EGL support for runtime PSBs and PCBs . . . . Requirements for the PSB record part . . . . Interacting with terminals in IMS. . . . . . . Defining forms for IMS programs . . . . . . Estimating the size of MFS blocks for a formGroup . . . . . . . . . . . . . Using serial and print files in IMS . . . . . . Using serial files as GSAM files . . . . . . Using serial files as message queues . . . . . Defining records to use with message queues Checking the results of serial file I/O statements Using print files as message queues . . . . . Example IMS program code . . . . . . . . Example of output to a serial file associated with a message queue . . . . . . . . . Example of IMS batch processing. . . . . . Mutliple users and message queues . . . . . 307 307 308 308 309 310 310 313 315 317 318 319 319 320 321 321 322 322 322 324 324 iv EGL Programmer’s Guide Overview of EGL Rich UI . . . . . . 327 Starting to work with EGL Rich UI . . . . . . Understanding how browsers handle a Rich UI application . . . . . . . . . . . . . . Introduction to the EGL Rich UI editor . . . . . Opening the EGL Rich UI editor . . . . . . Creating a Web interface in the Rich UI editor Running a Web application in the EGL Rich UI editor . . . . . . . . . . . . . . . Setting preferences for Rich UI . . . . . . . Setting preferences for Rich UI appearance . . Setting preferences for Rich UI bidirectional text Setting preferences for Rich UI deployment . . Securing a Rich UI application . . . . . . . Overview of Rich UI security . . . . . . . Resources to secure . . . . . . . . . . JSF versus Rich UI applications . . . . . . Using Web container-managed (JEE) authentication . . . . . . . . . . . . Using application-managed (custom) authentication . . . . . . . . . . . . Authentication summary . . . . . . . . Authorization . . . . . . . . . . . . JEE security example . . . . . . . . . . Sample login and error pages for JEE form-based authentication . . . . . . . . Preventing client-side security threats . . . . Overview of SSL . . . . . . . . . . . IBM Rational AppScan . . . . . . . . . 329 334 337 339 340 344 345 347 349 351 352 352 355 357 357 362 367 368 369 374 376 377 386 Inter-Portlet Communication . . . J2EELib . . . . . . . . . . Creating a Web Page . . . . . . Adding a Portlet to the Application . Adding Support for Additional Portlet . . . . . . . . . . . . Modes . . . . . . . . . . 470 471 471 472 473 Overview of service-oriented architecture (SOA) . . . . . . . . . 475 Elements of a service-oriented application . . . . Types of services . . . . . . . . . . . . Calling a local service . . . . . . . . . . Calling a remote service . . . . . . . . . . Adding service client binding information for an EGL service . . . . . . . . . . . . . . Adding service client binding information from a WSDL file . . . . . . . . . . . . . . Creating a service-access variable and binding it to a service . . . . . . . . . . . . . . . Exposing a service to other applications . . . . Adding Web service deployment information to the deployment descriptor . . . . . . . . Creating and using a shared protocol . . . . . Setting preferences for service generation . . . . 478 481 483 485 487 489 491 493 496 497 498 Building EGL Text User Interface applications . . . . . . . . . . . . 499 Example . . . . . . . . . . . . . . . Elements of a text user interface application . . . Building EGL Text User Interface applications with the Text Form editor . . . . . . . . . . . Creating a simple text or print form . . . . . Creating a constant field. . . . . . . . . Creating a variable field . . . . . . . . . Creating a form from a template . . . . . . Filtering the editor . . . . . . . . . . Display options for the EGL Text Form editor Setting preferences for the Text Form editor . . Setting bidirectional text preferences for the Text Form editor . . . . . . . . . . . . . Setting preferences for the Text Form editor palette entries . . . . . . . . . . . . 499 500 500 502 502 503 505 509 510 510 511 512 Building EGL JSF Web applications Elements of a JSF Web application . . . . . Common tasks in Web applications . . . . . Creating a Web page . . . . . . . . . Localizing text in Web applications . . . . Updating portions of a Web page with AJAX requests . . . . . . . . . . . . . Running a Web page on a server . . . . . Using the i5/OS integrated Web application server . . . . . . . . . . . . . . Using JEE container-managed security . . . . Accessing the JSF component tree with the source assistant . . . . . . . . . . . . . . Changing the target of a JSF link . . . . . Changing the style of a JSF control . . . . Changing the style class of a JSF control . . Setting event handlers for a JSF control. . . Setting the size of a JSF image. . . . . . Enabling or disabling JSF controls . . . . Setting JSF data table properties . . . . . Adding JSF component interface support to an EGL Web project . . . . . . . . . . . Setting preferences for Web projects . . . . . 389 . . . . 389 391 392 426 . 432 . 448 . 449 . 452 . . . . . . . . 454 457 458 459 460 461 462 463 Building EGL Console User Interface applications . . . . . . . . . . . . 513 Elements of a Console UI application . . . Creating a Console User Interface . . . . Adding rich client widgets to a Console UI program . . . . . . . . . . . . . Adding a button widget . . . . . . . Adding a check box widget . . . . . Adding a single-selection widget . . . . Running Console UI applications . . . . . Console UI modes . . . . . . . . . . . . . . . . . . . 513 . 516 . . . . . . 519 520 522 524 528 529 . 464 . 465 Building EGL portlet applications. . . 467 Portlet overview . . . . . . Prerequisites. . . . . . . . Elements of a Portlet Application . JSF Handler part . . . . . Managing Portlet Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467 468 468 468 469 Creating reports with EGL . . . . . . 531 JasperReports engine . . . . . . BIRT engine . . . . . . . . . EGL text report engine . . . . . Creating reports with JasperReports . . . . . . . . . . . . . . . . . . . . . 531 531 531 532 Contents v Elements of an EGL JasperReport application Creating the JasperReport design file . . . Writing code to drive a report of type JasperReport. . . . . . . . . . . . Creating an EGL JasperReport handler . . . Running a report of type JasperReport . . . Using JasperReport templates . . . . . . Creating JasperReport subreports . . . . . Adding support for Jasper reports to a project Creating reports with BIRT . . . . . . . . Adding support for BIRT reports to a project Creating an EGL BIRT handler . . . . . Creating EGL text reports . . . . . . . . Handler events for a text report . . . . . Writing code to print a text report . . . . 533 . 534 . . . . . . . . . . 538 541 545 546 547 549 551 553 555 556 557 558 Working with Web transaction applications in EGL. . . . . . . . . 561 Customizing JSP files . . . . . . . . . . Adding Web transaction support to an EGL Web project. . . . . . . . . . . . . . . Web transaction configuration files . . . . . Running VGWebTransaction programs . . . . Using VGUIRecord properties . . . . . . . Other controls . . . . . . . . . . . Using JavaServer pages with Web transactions . Transferring control between JSF Handlers and Web transactions . . . . . . . . . . . UI record bean API . . . . . . . . . . . 561 . . . . . . 562 563 564 564 566 567 . 569 . 570 Debugging EGL applications . . . . . 573 Stepping through an application in the EGL debugger . . . . . . . . . . . . . Debugging an EGL batch program . . . . EGL debugger commands . . . . . . . How build descriptor settings affect the EGL debugger . . . . . . . . . . . . . . . . . . 575 . 579 . 580 . 583 Using breakpoints in the EGL debugger . . . . Viewing variables in the EGL debugger . . . . Prerequisites. . . . . . . . . . . . . Variables and breakpoints . . . . . . . . Displaying and changing values . . . . . . Buttons in the Variables view . . . . . . . Making code updates while debugging an application . . . . . . . . . . . . . . Starting the EGL debugger for EGL projects . . . Creating a launch configuration in the EGL debugger . . . . . . . . . . . . . . Creating an EGL Listener launch configuration Starting a non-JEE application in the EGL debugger . . . . . . . . . . . . . . Invoking the EGL debugger from generated Java code . . . . . . . . . . . . . . Debugging Web projects with the EGL debugger Configuring a server for EGL Web debugging Starting an EGL Web debugging session . . . Debugging services with the EGL debugger . . . Prerequisites. . . . . . . . . . . . . Debugging a local service . . . . . . . . Debugging IMS and DL/I applications . . . . . Prerequisites. . . . . . . . . . . . . Host configuration . . . . . . . . . . Local workspace configuration . . . . . . Starting the DLI Debug Server on the z/OS host Character encoding options for the EGL debugger Setting preferences for the EGL debugger . . . . General preferences . . . . . . . . . . Debug behavior mapping . . . . . . . . 584 585 585 585 585 586 587 588 588 589 590 591 592 592 594 595 595 595 596 596 597 599 601 603 604 605 606 Appendix. Notices . . . . . . . . . 609 Programming interface information . Trademarks and service marks. . . . . . . . . . . . 611 . 611 Index . . . . . . . . . . . . . . . 613 vi 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 11 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. “What’s new in EGL V7.1” on page 13 “What’s new in EGL V7.0” on page 18 “Migrating from a previous version of EGL” on page 38 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, 2008 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 editor The EGL 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 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. EGL Rich UI editor The EGL Rich UI editor includes the functionality of the EGL editor, as well as a Design surface and Preview view for fast development of client-side Web applications. For details, see Overview of EGL Rich UI and Introduction to the EGL Rich UI editor. 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. 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. Introduction 3 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 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 172 for links to information on the particular EGL preferences you can set. Search window 4 EGL Programmer’s Guide not to be confused with the Properties view. Introduction 5 . The Properties window sets individual options for the artifact.In the Search window. not to be confused with the Search view. See “Searching for parts” on page 168 for details. The search results appear in the Search view. Other views and editors EGL developers commonly use EGL build parts editor The build parts editor is used for editing build parts. Properties window Most types of projects and files have a Properties window. including build descriptors. you can search for EGL parts or for other information in your workspace. Access the Properties window for a project or file by right-clicking it and then clicking Properties. To open a part in the Parts Reference view.EGL Parts Reference view The EGL Parts Reference view shows a hierarchical view of the parts referenced in a generatable logic part. EGL Parts List view 6 EGL Programmer’s Guide . 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 171 for details. Page Designer Editor Page Designer is a what-you-see-is-what-you-get (WYSIWYG) editor for Web pages. the Properties Introduction 7 . Properties view The Properties view provides detailed information on a specific object that you have selected in an editor. if you have a Web page open in Page Designer and you select a text output field on that Web page. Page Designer can work with EGL to create a Web interface for an EGL application. See “Viewing lists of parts” on page 169 for details.The EGL Parts List view shows a list of EGL parts that you can sort or filter for reference purposes. For example. You can also create new snippets for code that you use often. The Palette lists objects that you can drag into the editor. creating new objects in the open file.view shows you information such as the style applied to the field. Palette view The Palette view works alongside WYSIWYG editors. The Snippets view holds reusable pieces of code that you can drag into your code. Console view 8 EGL Programmer’s Guide . where its content comes from. Snippets view The Snippets view works alongside code editors. and its other characteristics. like the Project Explorer view does. For example.The Console view shows logged messages that are related to running your applications. Capabilities Capabilities are the broadest category of functionality in the workbench. Alternately. Enabling this capability makes EGL-related perspectives Introduction 9 .″ Capabilities can be enabled or disabled to display or hide functionality. The main capability that EGL developers use is the EGL Developer capability. it organizes the tools into a hierarchy of categories. the workbench will prompt you to enable the associated capability. Navigator view The Navigator view is similar to the Project Explorer view in that both show the projects and files in your workspace. it shows every folder and file in the workspace based on the actual location of those artifacts. such as renaming or moving them. Capabilities are organized by major functional areas. The Project Explorer reduces clutter by automatically hiding metadata files (such as the . From most general to most specific. For this reason. these groups are capabilities. the Navigator view is a pure view of the folders and files in your workspace. such as ″Web developer″ or ″Tester. 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. For example. How the workbench is organized The workbench contains a large number of tools and options. when you try to create a file or open a perspective that is associated with a disabled capability. without any formatting or filtering done by EGL. and editors. As such. views.eglproject file) and directories that you do not normally need to access (such as the EGLbin directory). if the Tester capability is disabled. perspectives and views related to testing will not be available. the Navigator view does not support refactoring EGL parts and files. that error is listed in the Console view. perspectives. However. Also. if you run an application and it causes an error. Navigator. the views associated with that perspective are displayed in the workbench. if the Tester capability is disabled. resize them. which is typically at the top right corner of the workbench. For example. minimize or maximize them. The purpose of each view varies widely. Other editors are graphical. and testing. and you can have as many perspectives open as you want. with Page Designer you can edit a Web page by clicking and typing directly in the Web page. although the EGL code editor has additional features for working with EGL code. and packages in your workspace. 10 EGL Programmer’s Guide . You can also drag Web page elements onto the page from views such as the Palette view. such as displaying certain information or giving access to a specific tool. See “Enabling EGL capabilities” on page 11. For example. For example. The perspectives available to you depend on the capabilities enabled in your workbench. display information about the status of your projects. To open a view. when you open the Web perspective by clicking Window → Open Perspective → Other → Web. Other views. You can also create customized perspectives that show only the tools you want. views give you access to a specific area of your workspace. Often. you can move them around the workbench. either open a perspective that contains that view or click Window → Show View and click the name of a view. Perspectives A perspective is a group of views and editors that are all shown on the screen at once. you see tools for building Web sites. projects. such as the Problems view and the Console view. Views are flexible. Finally. Some editors. which in turn makes tools available for working with EGL code. enabling you to open files or reorganize projects. You can have as many views open as you want. Editors Editors look like views. Some views. open the perspectives you want with Window → Open Perspective → Other or click a perspective’s icon in the Perspectives bar. show the files. To switch between perspectives. debugging code. with drag-and-drop tools or what-you-see-is-what-you-get (WYSIWYG) preview tools. but in general. and Package Explorer views. look and work just like code editors for many other programming languages. stack them on top of other views. Views When you open a perspective. To create a customized perspective. but it is best to organize your views into one or more perspectives. Each view performs a specific purpose. like the EGL code editor. some views. such as the Outline and Properties views. give information about a file you are currently viewing in an editor. 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. There are other perspectives for working with data sources. click the X at the top of the view. or close them. Then. such as the Project Explorer. click Window → Save Perspective As and type a name. To close a view.available. but editors are designed to change a particular type of file. developers switch between perspectives as they perform different tasks. open an already existing perspective and tailor it to your needs by repositioning its views and editors and opening or closing views and editors. expand General in the tree and then click Capabilities. Under EGL Developer. and then click Open With to see a list of editors that can open that file. such as the Project Explorer or Navigator. You may have other capabilities in the list. Expand EGL Developer. you must enable the capability for that area of functionality. follow these steps: 1. In the Capabilities list. For example. You can also right-click the file.Still other editors are tabular and provide tables in which you enter values. the EGL Developer folder represents the EGL capabilities. Click Advanced. the EGL build parts editor enables you to edit a build descriptor part by entering the values for build descriptor options in a table. when you double-click a file in a view that displays files. You can always perform these tasks. Each capability enables a different set of EGL functionality. 4. click Window → Preferences. select the check boxes next to the capabilities that you want to enable. c. 2. To enable all EGL capabilities. capabilities hide the EGL-related views and the EGL perspective. To enable EGL capabilities. but to make them appear in the menus. in the default editor for that type of file in the operating system. or you can click Open With → System Editor to open the file outside of the workbench. To select a few EGL capabilities to enable. 3. The EGL Core Language capability is required for EGL functionality. For EGL. In the Preferences window. Enabling EGL capabilities Capabilities keep the workbench menus from becoming cluttered by hiding items you do not use. b. From the main menu. In general. items in the pop-up menus and menus for creating new files. The Advanced window opens. select the check box next to EGL Developer. Other information on the workbench For more information on using the workbench effectively. that file opens in its default editor. and the code templates available when you use content assist. follow these steps: a. see these sources: v Help topics on the following subjects: – Workbench – Capabilities – Perspectives – Views v v v v – Editors “Enabling EGL capabilities” “Setting general preferences” on page 173 “Working with EGL code” on page 127 “Overview of EGL Rich UI” on page 327 v “Introduction to the EGL Rich UI editor” on page 337 v The tutorial Understand the workbench environment. Introduction 11 . Rational Business Developer no longer supports WebSphere Application Server Version 5. 6. enabling EGL capabilities may automatically enable other capabilities that are required to develop and debug EGL applications.1. instead of RMODE 24. Because Rich UI supports Safari. Firefox versions 2 and 3. Rich UI applications work on the iPhone. Some capabilities have prerequisites. Click OK. What’s new in EGL V7. 5. which is converted automatically into JavaScript™. Additional support for IBM® CICS® channels and containers EGL generated programs for CICS can be called with channels and containers. Runtime improvements for COBOL programs The runtime now runs in AMODE 31/RMODE ANY mode. Related concepts “Preferences” on page 172 EGL preferences affect the way the workbench displays and works with EGL. To save your changes.0 v Apache Tomcat Version 6 v IBM WebSphere® Portal Server Version 6. click Apply. Update of supported platforms Rational® Business Developer now supports the following products: v IBM WebSphere® Application Server Version 7. Batch applications can now use remote CICSEXCI calls to communicate with CICS. Normally. the workbench will automatically enable any capabilities that you try to use.0 applications. You can use the EGL Rich UI interface to write an EGL Rich UI application.5 Rich UI leads the list of new features for this release of EGL. EGL Rich UI applications can invoke remote services and interact with public Web sites. and Safari versions 2 and 3. This mode uses more above-the-line memory to create a transaction throughput. For this reason. Rich UI applications Rich UI is a new technology for writing Web 2. the workbench warns you before you use functionality that belongs to a disabled capability. Rich UI supports Internet Explorer versions 6 through 8.d. 12 EGL Programmer’s Guide . then click OK. If you clear the check box labeled Prompt when enabling capabilities. VSE support You can purchase an extension that enables the generation of EGL as COBOL source that can be compiled and deployed to z/VSE™. so there is no migration program to move from V7 to V7. BIRT reports EGL can now generate reports with BIRT. IMS™.1 Return of features that were unsupported in V7. However. you must make the following changes in your code by hand: v Add the @ operator to all printFloatingArea and screenFloatingArea properties.Related information “What’s new in EGL V7.1” Related concepts What’s new in EGL V7. including FormGroups. if you use forms and you migrated to V7.1” on page 16. and the ConverseVar system variable v DL/I. v Place all of the @screenFloatingArea complex properties for a form inside the new screenFloatingAreas property.1” on page 15. J2EE security New functions in J2EELib allow you to secure a JSF application through container-manages security. Introduction 13 . EGL assumes that EGL V6 users with forms did not migrate to V7.1. see Form part. see “Changes to build descriptor options in EGL V7. see “Changes to system libraries and variables in EGL V7.0 are returned in this version: v Text User Interface. and GSAM data access.0 The following areas of functionality that were removed in V7. including the system library DLILib and the DLIVar system variable v WebSphere MQ data access v Web transactions v VisualAge® Generator migration tool v The statement exit stack v Java™ wrapper generation. including the ejbCall type of the callLink element of the linkage options part Build descriptor options related to these areas of functionality are returned. See “Using JEE container-managed security” on page 452. System libraries and variables related to these areas of functionality are returned. the Text Form editor. v Place all of the @printFloatingArea complex properties for a form inside the new printFloatingAreas property. the system library ConverseLib. For more information. See “Creating reports with BIRT” on page 551. Limits removed for SQL table labels SQL table labels formerly were limited to four characters. EGL no longer limits the length of SQL table labels. the restrictions have changed: v The label must be in the current block. DLIException stereotype The new DLIException exception record is for handling errors in DL/I data access applications. HEX(4).CUSTOMER". in a block that fully contains the current block. New operators The bitwise xor (xor) operator performs a bitwise exclusive or operation on two operands of type HEX(2).1 This topic lists the changes to the EGL language in version 7. This record can have additional properties that it could not have in previous versions: 14 EGL Programmer’s Guide . HEX(8). v The label cannot be with the scope of an OpenUI statement. Related concepts “Language changes in EGL V7. “User interface changes in EGL V7. The following Record part stereotypes are new in this version: CSVRecord stereotype The new CSVRecord stereotype is for Record parts that hold information with fields delimited by a character such as a comma. The VGUIRecord stereotype is available in this version. INT.1 This topic lists the major changes to EGL parts in this version. See Sample: EGL LDAP access. In earlier versions. Changes to parts in EGL V7. or SMALLINT. as in the following example: record CustomerRecord type SQLRecord {tableNames = [["ADMINISTRATOR.1. Change in goTo restrictions.1” This topic lists the changes to the EGL language in version 7. the goTo statement could not transfer control to a label within a conditional block.0” on page 13. as explained in “Return of features that were unsupported in V7. DB2 Version 7 supports table labels up to 18 characters long.1” on page 15 “Changes to parts in EGL V7. "L1"]].1.LDAP data access EGL provides a code sample that you can customize to retrieve security or other details from a server accessed by way of Lightweight Directory Access Protocol (LDAP).1” on page 16 “Changes to system libraries and variables in EGL V7.1” on page 17 Language changes in EGL V7. and by convention were generally two characters. or outside all conditional blocks at the top of the function. keyItems = [customerNumber]} The restriction was required by an older version of DB2®.1” This topic lists the major changes to EGL parts in this version. DB2 Version 8 has no limits on table label length. “Changes to build descriptor options in EGL V7. To accommodate migration from RPG. convertNumberToUnsignedUnicodeNum See convertNumberToUnsignedUnicodeNum() SysLib. now contains multiple @printFloatingArea complex properties.getRemoteUser See getRemoteUser() J2EELib.openFileDialog See openFileDialog() Changed system functions and variables sysVar.1” on page 13 “Language changes in EGL V7. “Changes to parts in EGL V7.formConversionTable and sysVar.1” on page 14 This topic lists the changes to the EGL language in version 7.v v v v v handleHardIOErrors i4glItemsNullable localSQLScope textLiteralDefaultIsString throwNrEofExceptions See VGUIRecord properties.convertUnsignedUnicodeNumToNumber See convertUnsignedUnicodeNumToNumber() J2EELib. printFloatingAreas. See “Return of features that were unsupported in V7.1” on page 16 Introduction 15 .1” on page 14 This topic lists the major changes to EGL parts in this version. the new screenFloatingAreas property now contains multiple @screenFloatingArea complex properties. New system functions SysLib. Similarly. The syntax for floating area properties in FormGroups has changed.isUserInRole See isUserInRole() ConsoleLib. Related Concepts “What’s new in EGL V7. A new property.1.0” on page 13.1 Returned system libraries and variables The following system libraries and variables are available in this version. “Changes to build descriptor options in EGL V7. v v v v ConverseLib ConverseVar DLILib DLIVar See the EGL Language Reference for information on these libraries and variables.callConversionTable These system variables are now a CHAR(256) rather than a CHAR(8). Changes to system libraries and variables in EGL V7.getAuthenticationType See getAuthenticationType() J2EELib. 0 but are available in version 7.0” on page 13. see “Return of features that were unsupported in V7.1. For details on the functionality that was returned.0” on page 32 Changes to build descriptor options in EGL V7. Options related to Java wrappers: v enableJavaWrapperGen v sessionBeanID v wrapperPackageName Options related to Text User Interface: v fillWithNulls v formServicePgmType v genFormGroup v genHelpFormGroup v leftAlign v v v v v oneFormItemCopybook printDestination restartTransactionID setFormItemFull validateOnlyIfModified v workDBType Options related to IMS and DL/I data access: v v v v errorDestination imsFastPath imsLogID mfsDevice v mfsExtendedAttr v mfsIgnore v mfsUseTestLibrary v restoreCurrentMsgOnError v v v v spaADF spaSize spaStatusBytePosition synchOnPgmTransfer Options related to Web transactions: v v v v genResourceBundle genVGUIRecords msgTablePrefix resourceBundleLocale 16 EGL Programmer’s Guide .1 Returned build descriptor options The following build descriptor options were not available in version 7.“Changes to system libraries and variables in EGL V7. 1” on page 15 “Changes to build descriptor options in EGL V7.1 New EGL project wizard The wizards for creating the different types of EGL project have been combined into a single wizard which prompts you to choose a type of project. Open this page by right-clicking an EGL Web project. wrapperCompatibility See wrapperCompatibility. imsID See ″imsID″ in the EGL Generation Guide. including: v The New EGL Project wizard can create an EGL deployment descriptor for the new project and automatically set the deploymentDescriptor build descriptor option to the name of that deployment descriptor.1” on page 13 “Language changes in EGL V7. Related Concepts “What’s new in EGL V7.1” on page 14 This topic lists the changes to the EGL language in version 7.New build descriptor options The following build descriptor options are new in this version: wrapperJNDIPrefix See wrapperJNDIPrefix. EGL editor The EGL editor now highlights syntax errors as you type. See “Creating an EGL project” on page 71. in which case EGL will automatically add Web service deployment information to the deployment descriptor. v The EGL deployment descriptor editor has been simplified and enhanced. including tools to set attributes on multiple Web services.1” on page 13 “Language changes in EGL V7. and then clicking EGL Runtime Data Source. v When creating a new Service part. you can specify to create the Service part as a Web service.0” on page 35 User interface changes in EGL V7. clicking Preferences. Services enhancements The process of creating a service application in the workbench has been simplified in several ways. EGL Runtime Data Source page You can now create a connection and use that connection both at design time and at run time through the EGL Runtime Data Source property page. “Changes to system libraries and variables in EGL V7. Introduction 17 .1.1” on page 14 This topic lists the changes to the EGL language in version 7.1. See “Using an SQL database connection at run time” on page 202. birtEngineHome See birtEngineHome. It can also format your source code. Related Concepts “What’s new in EGL V7. See “The EGL editor” on page 155. model-driven development with EGL follows these steps: 1.For information on the transformation parameters editor and working with transformations in general. The EGL Application Transformation allows you to transform UML into EGL. but you must run the application in RCP mode. 4.What’s new in EGL V7. you may have other transformations available. see ″Model driven development of EGL code″ in the online help system. as well as graphical input fields like check boxes and buttons.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. You associate the UML model with a transformation parameters model (TPM) file. Console User Interface rich client widgets In this release. EGL does not include functionality for editing UML models graphically. rather than the standard mode for 18 EGL Programmer’s Guide . you may have other transformations available. These widgets allow you to add mouse support to your Console UI applications. but these transformations will not create EGL code. You plan your application with a UML model. generating Java or COBOL. you edit the parameters associated with the EGL application transformation to describe what the resulting EGL code will look like. and Java runtime.0. EGL contains support for rich client widgets in Console UI. see Generating source code from UML models. Depending on what products you have installed. You run the transformation to apply the transformation parameters to the UML model and create EGL code. For information on the EGL Application Transformation. see Model driven development of EGL code. 3. This file specifies which transformations will be used on the UML model and how those transformations will be applied. see ″Generating source code from UML models″ in the online help system. Depending on what products you have installed. 2. Developing an application with these widgets is similar to developing an ordinary Console UI application.For information on the EGL Application Transformation. particularly for building projects.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. For information on the transformation parameters editor and working with transformations in general. 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.0. Generally. but these transformations will not create EGL code. v Libraries can now be generated for iSeries COBOL v Support for AJAX requests (version 7. Using the transformation parameters editor. 0” on page 36 This topic covers changes to the way EGL deals with exceptions in version 7.0. “Changes to system libraries and variables in EGL V7. To create an AJAX request. has changed. the following code declares a nullable integer variable: myNullableVariable int?.0” on page 36 “User interface changes in EGL V7. you indicate an area on the page to be updated. “Changes to services in EGL V7. as in this example: myVar int? = NULL. For example. and the ANY. variables that do not hold a value themselves but act as a reference to another value. AJAX support Beginning with version 7.0 This topic lists the changes to the EGL language in version 7.0 Related tasks “Migrating from a previous version of EGL” on page 38 Language changes in EGL V7. allowing you to update a portion of a page without refreshing the entire page.0. Dictionaries.0.0.0” on page 37 Documentation changes in EGL V7.0. See “Adding rich client widgets to a Console UI program” on page 519. Related Concepts “Language changes in EGL V7. and add code to the page’s JSF Handler to process the update. “Validation changes in EGL V7.0” on page 32 “Changes to build descriptor options in EGL V7.3.Console UI applications. specify a user action to trigger the update.0” on page 35 “Changes to exception handling in EGL V7. arrays. v You can declare a nullable variable by appending a question mark ? to the variable type specification. See “Updating portions of a Web page with AJAX requests” on page 432.0” on page 28 This topic lists the EGL parts and describes their major changes in this version. EGL-controlled Web pages can issue AJAX requests. See Reference variables. Variables declared to be nullable in this way contain null until you assign a value to them. Introduction 19 . The following topics deal with major changes in this version of EGL. and CLOB primitives are reference types. v You can now set a nullable variable to null by assigning it the value NULL. Major changes Reference variables EGL now uses the concept of reference variables. Nullable types The way EGL handles nullable variables.0” This topic lists the changes to the EGL language in version 7. variables that can point to a null or empty value. BLOB. consoleForms.0” on page 24 “Changes to parts in EGL V7. For example. However. constant. which can be put on programs. libraries. The nullable modifier on function parameters is now sqlNullable. end v v v v v v v Because you can now assign a null value and compare to a null value. myInt2.writeStderr(myInt3).. myInt1 = 5. Use NULL instead. and records for migration purposes. that variable is initially null. The isNullable property is now isSQLNullable. For more information on nullable variables. In most cases. handlers. SysLib. When a variable is made nullable by I4GLItemsNullable. //writes "56" to the console. When a variable is made nullable with an explicit question mark. myInt2 = 6. When concatenating string variables. 20 EGL Programmer’s Guide . making them all nullable. if you pass a null variable to a system function. myString2 string = "everyone!". myInt3 = myInt1 :: myInt2. it works like the + operator: myString1 string = "Hello ". see the topics ″Null values and the nullable type″ and ″i4glItemsNullable″ in the EGL Language Reference. the function will return a null value. SysLib.writeStderr(myString1 + myString2). a null value is treated as an empty string. and parameter in the part. This property places an implicit question mark on each primitive variable. the following expressions are no longer used: – SET myVar NULL – if (myVar is NULL) NIL is no longer a valid literal to represent a null value.Similarly.. System functions have rules to deal with nullable variables. you can test to see whether a variable is null by comparing it to the value NULL: if (myVar == NULL) . When used with text variables.writeStderr(myString1 :: myString2). Statements New operators v The new concatenation operator (::) concatenates two variables as though those variables were strings. the behavior of each function differs with respect to nullable parameters and return values. the concatenation operator treats those variables like strings: myInt1. the initial value of that variable depends on the type of variable. See the reference information for the specific function for information on how it deals with nullable variables. In its place is the I4GLItemsNullable property. The itemsNullable build descriptor option is no longer used. SysLib. //writes "Hello everyone!" to the console twice When used with numeric variables. myInt3 int. writeStderr(myVar3). the second argument is required. or casts. This ability removes the need for functions such as MathLib. EGL truncated the source variable to fit into the target variable. //Writes "11" to the console. INT. Introduction 21 . or SMALLINT.assign() system function to replace MathLib. 2) { IsNoRefresh = yes. In addition. myVar3 int = myVar2+myVar1 as int. The statements also use braces to group their keyword modifiers. when you assigned a variable to a target variable with fewer decimal places. and the type of the target variable is not FLOAT or SMALLFLOAT If both of these criteria are false.stringAsDecimal(). for the MathLib. HEX(4). The migration tool uses the MathLib. Change in rounding behavior In previous versions. v The bitwise and (&) and bitwise or (|) operators perform a bitwise operation on two operands of type HEX(2). 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. Change to the in operator You now use the from keyword with arrays rather than using an index to limit the search.0. not truncated.v The as operator temporarily assigns. In EGL V7. myVar2 int = 6. as it did in V6.1. HEX(8). EGL truncates the source variable to the number of decimal places available in the target variable. or INT. SysLib. or as a variable. For example: call "xxx" (1. transfer. The following example shows the old syntax for searching an array beginning with the fourth element: if(a in myArray[4]) The following example shows the new syntax for the same task: if(a in myArray from 4) Conversion enhancements You can now assign a STRING directly to a DECIMAL. Changes to syntax of call. and show You can now specify the name of the target program or transaction in these statements as a direct program reference.0.0. a value to a specified type.1. FLOAT. transfer to program "xxx" passing yyy { IsExternal = yes}.round() system function.round() in situations in which the power of 10 parameter was not used. In EGL V7. The following example uses as to temporarily cast a variable of the ANY primitive type to the INT primitive type: myVar1 ANY = "5". the call statement now uses parentheses to group arguments. as a literal (in quotes). In previous versions. IsExternal = yes }. the second argument (the power of 10) was optional. these extra decimal places are rounded. regardless of what you have assigned to it previously. the ANY variable was permanently limited to the type of that value.0: Record CustomerRecord type SQLRecord { keyItems = ["customerNumber"]} customerNumber INT. end end General changes Some property values are no longer quoted strings When assigning values to properties in set value blocks. Default representation for text literals By default. If you want EGL to interpret these as a different type instead. The ANY variable could store only values compatible with that first value. For example. text literals (such as "Hello!") are treated as of the type STRING in the generated source. you can specify a function to validate user input for a variable in a JSF Handler automatically when the value of the variable changes. variables. the ANY variable can accept any EGL type. which you use to test the value: function validateMyInt(intToCheck int in) if (intToCheck >= 500) SysLib. end The following code is correct for version 7. You can use the as operator to cast an ANY variable temporarily to another type. The function specified by onValueChangeFunction accepts a parameter of the same type. //key field customerName STRING. and you can use the isa operator to test what type of data the ANY variable contains. ANY type is no longer limited to the type of its first assigned value In previous versions of EGL. variables are in scope only for statements that follow their declaration. the following code is correct for version 6. that variable was in scope for the entire function. set the new textLiteralDefaultIsString property to NO. For example. Format specifiers for INTERVAL variables You must include a format specifier when creating an INTERVAL variable: intval1 interval("yyyyMM"). the following code creates a variable and specifies its validation function: myInteger int {onValueChangeFunction = validateMyInt}. In this version. if you created a variable of the ANY type and assigned a value to that variable.setError("Number must be less than 500"). Now. even for statements that preceded the variable declaration.Variables Scope of variables within functions In previous versions of EGL. Web applications Validating variables when their values change With the onValueChangeFunction property. if you declared a variable within a function. See textLiteralDefaultIsString.0: 22 EGL Programmer’s Guide . or parts. EGL no longer uses quotes around names of fields. which is now split into the properties onConstructionFunction. //key field customerName STRING. 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. and onPostRenderFunction v parentRecord v pcbParms v v v v v psb psbParm redefines segmentRecord 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 v ENUMERATION v EXTERNALTYPE v NOCURSOR v NULL v RUNUNIT v SQLNULLABLE Introduction 23 . end File names. onPreRenderFunction. and other values continue to require quotes.Record CustomerRecord type SQLRecord { keyItems = [customerNumber]} customerNumber INT. aliases. you could define a part in the default package (that is.0” on page 28 This topic lists the EGL parts and describes their major changes in this version. a part in the root of an EGL source folder. Now you can import parts in the default package only into other parts in the default package.0 Some pieces of code that appeared to be valid in previous releases will be marked as invalid in this version. “Changes to services in EGL V7. EGL assumes that displayName = "myNewDictionary" is a name-value pair in the new dictionary. which a list of name-value pairs. with no named package containing it) and import that part for use in a part in another package. Name resolution between fields and properties You can use the ″at″ symbol (@) to distinguish between fields and properties with the same name. “Changes to system libraries and variables in EGL V7.0 Validation changes in EGL V7. instead. Following are updates to code validation that you may encounter in this version of EGL: 24 EGL Programmer’s Guide .0” on page 36 “User interface changes in EGL V7. Naming conflicts between functions and variables Within a part. assume an EGL Dictionary part.0” on page 37 Documentation changes in EGL V7. For example.0” on page 32 “Changes to build descriptor options in EGL V7.0” on page 18 “Validation changes in EGL V7. Because of part resolution rules. Related Concepts “What’s new in EGL V7. The following is a declaration of a new Dictionary part: myRef Dictionary { displayName = "myNewDictionary" }.0. See EGL part resolution rules for more information.0” on page 35 “Changes to exception handling in EGL V7. you can use the same set-value block to assign values to properties of the dictionary itself. you must use an @ operator.v THROW v WITHV60COMPAT Importing from the default package is no longer allowed In previous versions. as in the following example: myRef Dictionary { @displayName {"myNewDictionary"} }. no function may have the same name as a variable.0” on page 36 This topic covers changes to the way EGL deals with exceptions in version 7. If you want to assign a value to the displayName property for the dictionary. these validation changes do not reflect language changes.0” “Changes to parts in EGL V7. In most cases. the EGL editor is identifying code that was accepted in previous versions but did not run as expected in the generated code. You use a set-value block to assign those name-value pairs. 2){isBoolean=yes} are invalid. function main() foreach(from myRecord into myVariable). //validation error const c2 decimal(5. However.// validation error end end end record recordType type SQLRecord item1 int.2345. as in these examples: const c1 decimal(5.3) = 123.456.3) = 1. function main() msInterval = msInterval + ssInterval. such as DECIMAL(3. variable declarations such as myVar decimal(2. ssInterval interval("mmss"). end Operations with incompatible INTERVAL variables Validation now recognizes an attempt to perform assignment or a mathematical operation between two INTERVAL variables with incompatible formats.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. 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. For this reason. //validation error end end Introduction 25 . Use a BOOLEAN primitive or a numeric type with places to the left of the decimal. as in this example: Program pgm msInterval interval("yyyymm"). the variable must have at least one non-decimal place. any. //validation error Statements Size of arrays within an isa expression You cannot specify a size for an array in an isa expression.2). 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 myVariable recordType. these validation changes do not reflect language changes. the EGL editor is identifying code that was accepted in previous versions but did not run as expected in the generated code. the Service part must contain a function matching each function prototype in the Interface part. and return values must match. Following are updates to code validation that you may encounter in this version of EGL: 26 EGL Programmer’s Guide . Related tasks “Migrating from a previous version of EGL” on page 38 Validation changes in EGL V7. Related Concepts “What’s new in EGL V7. 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.Parts Service parts must have a function for every function prototype in the interfaces it implements When a Service part implements an Interface part. 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. instead. //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. In most cases.0” on page 28 This topic lists the EGL parts and describes their major changes in this version. that Record part must specify the segments property.0. Value of fillCharacter for DBCHAR and UNICODE variables Validation now requires that the fillCharacter property be set to null or blank 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. as in this example: handler myPage type JSFHandler {view="myPage.0” on page 18 “Language 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.jsp"} myField decimal(1) {dateFormat = "MM/dd/yyyy"}. 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. “Changes to parts in EGL V7. The function names. parameter lists.0” on page 19 This topic lists the changes to the EGL language in version 7. //validation error end end Introduction 27 . However. end Operations with incompatible INTERVAL variables Validation now recognizes an attempt to perform assignment or a mathematical operation between two INTERVAL variables with incompatible formats.2){isBoolean=yes} are invalid. 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 myVariable recordType. any. such as DECIMAL(3. variable declarations such as myVar decimal(2. as in these examples: const c1 decimal(5. 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.456. ssInterval interval("mmss").// validation error end end end record recordType type SQLRecord item1 int.3) = 1. as in this example: Program pgm msInterval interval("yyyymm"). the variable must have at least one non-decimal place.2). //validation error Statements Size of arrays within an isa expression You cannot specify a size for an array in an isa expression. For this reason.3) = 123. Use a BOOLEAN primitive or a numeric type with places to the left of the decimal. //validation error const c2 decimal(5. function main() msInterval = msInterval + ssInterval. function main() foreach(from myRecord into myVariable).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.2345. 0. You can also use YES to represent TRUE and NO to 28 EGL Programmer’s Guide . New primitive Like Boolean types in other languages. the Service part must contain a function matching each function prototype in the Interface part.jsp"} myField decimal(1) {dateFormat = "MM/dd/yyyy"}. Related Concepts “What’s new in EGL V7.Parts Service parts must have a function for every function prototype in the interfaces it implements When a Service part implements an Interface part. //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.0” on page 19 This topic lists the changes to the EGL language in version 7. 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.0 This topic lists the EGL parts and describes their major changes in this version. Value of fillCharacter for DBCHAR and UNICODE variables Validation now requires that the fillCharacter property be set to null or blank 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.0” This topic lists the EGL parts and describes their major changes in this version. parameter lists. “Changes to parts in EGL V7. as in this example: handler myPage type JSFHandler {view="myPage. that Record part must specify the segments property.0” on page 18 “Language changes in EGL V7. 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. the BOOLEAN EGL primitive accepts a value of TRUE or FALSE. 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. The function names. Related tasks “Migrating from a previous version of EGL” on page 38 Changes to parts in EGL V7. and return values must match. has been divided into the onConstructionFunction. use the properties selectedRowItem or selectedValueItem instead. onConstructionFunction is the most similar to onPageLoadFunction. Valid types are a data table column or an array of primitive variables not within a record. JSF Handlers perform all the same tasks as a pageHandler did in previous versions. which designated a function to run when the page loads. with some differences in properties: v The onPageLoadFunction property. that variable must be an INT type. These properties behave in a way similar to the properties selectFromListItem and selectType. For more information. 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. To use a record array or an array of primitive variables within a record as a list of selection options. see the following topics: v ExternalType part v “Calling Java” on page 128 Delegate This new type of part provides a model for a function. v If a variable in a JSF Handler has the selectFromListItem property. selectedValueItem holds the value or values from those rows instead of the index or indexes. v If variable in a JSF Handler has the selectType property set to index.1. v The cancelOnPageTransition property determines whether the page bean is removed from the session scope when the user’s browser loads a new page. and onPostRenderFunction functions. See Primitive data types. This property was added in version 6. For more information. This part replaces an Interface part with the stereotype JavaObject in previous versions.0. New parts The following parts are new in this version: ExternalType An ExternalType part represents a mapping from EGL to another language. selectedRowItem indicates a variable that holds the index (or indexes) for the row (or rows) the user selects from a screen display. v The default value for a JSFHandler scope property is now session. see Delegate part Changed parts The following parts have changed in this version: pageHandler The pageHandler part is now a Handler part with the stereotype JSFHandler.1. v You can apply the properties selectedRowItem and selectedValueItem to variables within JSF Handlers.represent FALSE. The isBoolean property is still supported on other primitive variables. Introduction 29 . onPreRenderFunction. the property’s value cannot be a record array or an array of primitive variables within a record. see the following topics: v “Executing commands when a page loads” on page 411 v JSF Handler part v onConstructionFunction v onPreRenderFunction v v v v v v v Service The way EGL uses services has changed significantly in this version. use an ExternalType part. Use @XML to interact with WSDL files.For more information. See “Changes to services in EGL V7. use an Interface part with no stereotype. For more information. v The @XSD property is no longer used. See the information on services and the Service part. or one of the following topics: v Library part v Service part v “Overview of service-oriented architecture (SOA)” on page 475 Interface The Interface part no longer has stereotypes such as BasicInterface and JavaObject. is no longer needed. see the following topics: v “Changes to services in EGL V7. which was used only on this type of Library part. v The properties allowUnqualifiedItemReferences and includeReferencedFunctions are now valid on Service parts. Instead of BasicInterface. Instead of JavaObject. see the following topics: v Interface part v ExternalType part onPostRenderFunction cancelOnPageTransition onValueChangeFunction selectType selectFromListItem selectedRowItem selectedValueItem 30 EGL Programmer’s Guide .0” on page 36 v Service part v Overview of EGL deployment descriptor file v “Overview of service-oriented architecture (SOA)” on page 475 v @xml v @bindService Library The serviceBindingLibrary type of Library part is no longer used. For more information.0” on page 36 The properties of the Service part have changed as follows: v The @WSDL property is no longer used. The runtimeBind property. which specifies fields in the record to use for the label and value when using the record in a JSF selection list.0” on page 36 Introduction 31 . Record parts with the stereotype ConsoleForm Record parts with the stereotype ConsoleForm are now considered generatable parts.0. New properties The following table lists new properties that can be used on multiple parts: Table 1. “Changes to services in EGL V7. Applicable parts v Program v Handler v Library v Service The textLiteralDefaultIsString property tells v Program EGL how to deal with text literals to v Handler promote compatibility with VisualAge v Library Generator. It replaces the itemsNullable build descriptor option. Record Record parts have the new @SelectionList property. see: v @SelectionList v “Binding a JSF single-select control to a variable” on page 401 Record parts have the new stereotype Exception. See recordNumItem. v Service v Record The i4glItemsNullable property determines whether a record emulates the behavior of I4GL in creating variables as nullable by default. See isSQLNullable.0” on page 36. Record parts with the RelativeRecord stereotype The keyItem property for this type of Record part is now the recordNumItem property. Record parts with the SQLRecord stereotype The isNullable property for fields within SQLRecord parts is now the isSQLNullable property. See “Generatable parts and non-generatable parts” on page 96. See textLiteralDefaultIsString. v Program v Handler v Library v Record Related Concepts “What’s new in EGL V7. See i4glItemsNullable.0” on page 18 “Language changes in EGL V7. New properties Property The v60ExceptionCompatibility property specifies whether the logic part uses a form of exception handling for compatibility with a previous version. See v60ExceptionCompatibility. which is used to define a custom exception.Program Programs that are the target of a call statement must have a parameter list.0” on page 19 This topic lists the changes to the EGL language in version 7. This parameter list can be empty. For more information. See “Changes to exception handling in EGL V7. but the parentheses denoting the parameter list are now required. each function behaves differently. or integer type: v MathLib. In general.sqlData (EGL system variable). Similarly. Removed system functions The following system functions are no longer necessary because you can now assign a string directly to a decimal.getApplicationAttr See getApplicationAttr() j2eeLib. floating-point.sqlData system variables.1.stringAsFloat v MathLib. see EGL library sqlLib. while sysVar.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.stringAsDecimal v MathLib.sqlData contains information that is local to the program. For more information on sqlLib. New system functions The following system functions and variables are new in this version: j2eeLib. Some system functions and libraries were removed from V7. sqlLib. it returns a null value. which are both structured records.“Changes to exception handling in EGL V7. See sysVar system variable (core fields) and sqlLib.setApplicationAttr See setApplicationAttr() MathLib. see the help topic on the specific function for information.clearApplicationAttr See clearApplicationAttr() j2eeLib.sqlData contains information that is global to the entire application.decimals See decimals() 32 EGL Programmer’s Guide . However. see “Changes to system libraries and variables in EGL V7.0. if you pass a null value to a system function.0 but are returned in V7. the SQL-related system variables in sysVar and VGVar have been moved into the new sqlLib.sqlData and sysVar.clearEGLSessionAttrs See clearEGLSessionAttrs() j2eeLib.1” on page 15.0 Global changes Most system functions have been updated to accept null values for parameters.0” on page 36 This topic covers changes to the way EGL deals with exceptions in version 7. Related tasks “Migrating from a previous version of EGL” on page 38 Changes to system libraries and variables in EGL V7. max MathLib.findStr StrLib.setWebServiceLocation StrLib.getWebServiceLocation ServiceLib.concatenateWithSeparator VGLib.integerAsChar StrLib.findStr StrLib.characterAsInt StrLib.FloatingSum MathLib.StrLib.FloatingDifference MathLib.setWebEndPoint StrLib.strLen StrLib.compareStr StrLib.FloatingDifference VGLib.FloatingProduct MathLib.compareNum MathLib.setSubStr StrLib.concatenateWithSeparator StrLib.FloatingProduct VGLib.assign VGLib.constructQuery VGLib.setErrorForComponentID See setErrorForComponentID() Changed system functions and variables The following system functions have new names: Table 2. Renamed system functions Old name ConsoleLib.indexOf See indexOf() StrLib.FloatingMod MathLib.FloatingSum MathLib.convertUnicodeNumToNumber See convertUnicodeNumToNumber() SysLib.setSubStr StrLib.FloatingQuotient VGLib.unicodeAsInt See unicodeAsInt() SysLib.textLen New name SqlLib.copyStr VGLib.byteLen StrLib.compareStr VGLib.intAsUnicode See intAsUnicode() StrLib.characterLen Introduction 33 .getTokenCount See getTokenCount() StrLib.concatenate VGLib.constructQuery MathLib.booleanAsString See booleanAsString() StrLib.copyStr StrLib.FloatingMod VGLib.min ServiceLib.FloatingQuotient MathLib.FloatingAssign MathLib.charAsInt VGLib.concatenate StrLib.intAsChar VGLib.getWebEndPoint ServiceLib.compareNum MathLib.convertNumberToUnicodeNum See convertNumberToUnicodeNum() SysLib.maximum MathLib.minimum ServiceLib. loadTable SqlLib.defineDatabaseAlias SqlLib. Now.Table 2. The fifth. instead.remote or ConvertDirection.0. In this version. commitScope. as in variable as "type". use the as keyword to cast a variable.unloadTable The following system functions have changed significantly in this version: MathLib. the function cannot accept a literal.0” on page 18 “Language changes in EGL V7.0” on page 19 This topic lists the changes to the EGL language in version 7. v The default value of the isolationLevel parameter default.1” on page 15 34 EGL Programmer’s Guide . unless VAGen compatibility mode is enabled. not serializableTransaction.setCurrentDatabase VGLib.disconnectAll SqlLib.startTransaction SysLib. the function uses the JDBC driver’s default isolation level. In this version. and sixth parameters. and its parameters have changed: v The fourth parameter. Related Concepts “What’s new in EGL V7.disconnect SqlLib.connect SysLib.startTransaction SqlLib.Connect This function was formerly SysLib.disconnect SysLib.defineDatabaseAlias SysLib.connect SqlLib. SqlLib.loadTable SysLib.local. See round(). Renamed system functions (continued) Old name SysLib. SysLib. both parameters are required.setCurrentDatabase SysLib.queryCurrentDatabase SysLib. v When the isolationLevel parameter is not specified or is set to default.disconnectAll SysLib. certain arguments in certain functions in JavaLib could accept a casting operator in parentheses. is no longer used. See convert(). “Changes to build descriptor options in EGL V7.beginDatabaseTransaction SysLib. it requires an argument of ConvertDirection. and seventh parameters are now the fourth. sixth.unloadTable New name SqlLib.Connect.beginDatabaseTransaction SqlLib. fifth.convert This direction argument of this function was formerly an ″L″ or ″R″ literal value.queryCurrentDatabase SqlLib. Change in casting syntax In past versions.0” on page 35 “Changes to system libraries and variables in EGL V7. See connect().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). see “Changes to build descriptor options in EGL V7.” 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.0.0” on page 18 “Language changes in EGL V7. “Changes to system libraries and variables in EGL V7.0” on page 19 This topic lists the changes to the EGL language in version 7. 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.Changes to build descriptor options in EGL V7. truncateExtraDecimals See truncateExtraDecimals. v serviceRuntime v webServiceEncodingStyle Some other build descriptor options were removed from V7.0 New build descriptor options The following build descriptor options are new in this version: currencyLocation See currencyLocation. separatorSymbol See separatorSymbol.0” on page 19. Related Concepts “What’s new in EGL V7.0” on page 32 Introduction 35 . includeLineNumbers See includeLineNumbers.0 but are returned in V7. Use DEU instead. maxNumericDigits See maxNumericDigits. use the I4GLItemsNullable property. deploymentDescriptor See Overview of EGL deployment descriptor file. wrapperCompatibility See wrapperCompatibility.1. See the explanation of nullable types in “Language changes in EGL V7.0. 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. For a list of all system exception records and their fields. depending on the exception type. the calling program receives an InvocationException rather than the original exception. control immediately returns to the function that called it. including throwing your own exceptions.0 EGL’s service functionality has expanded significantly in this version. The way you make a service available to other applications has changed.0. Related tasks “Migrating from a previous version of EGL” on page 38 Changes to services in EGL V7. The Exception records contain various fields. For more information about error handling. see “Handling errors” on page 148. see “V6 exception compatibility” on page 151.1” on page 16 Changes to exception handling in EGL V7. Exception stereotype for Record parts You can now define a Record with the type Exception. Within a try block you can now have multiple onException statements.0.0” on page 19 This topic lists the changes to the EGL language in version 7. as has the way you 36 EGL Programmer’s Guide . or use a number of predefined Exception Records. The Exception stereotype is at the heart of a new style of exception handling in EGL. v60ExceptionCompatibility property This new property allows you to continue to use the EGL version 6 style of exception handling for backward compatibility. even if the exception occurs in a library function. For more information.0 This topic covers changes to the way EGL deals with exceptions in version 7. Similarly.“Changes to build descriptor options in EGL V7. end The AnyException type is available to catch any exception not previously specified. If the main function fails to catch the exception. as in the following example: try get next mySerialRecord. When a function throws an exception that is not caught within the try block or is not within a try block at all. When an exception occurs in a called program.0” on page 18 “Language changes in EGL V7. Related Concepts “What’s new in EGL V7. Each onException statement must include a declaration of an Exception record variable. if any. an exception in a service function delivers a ServiceInvocationException to the calling program. EGL passes the exception upward until an onException statement catches it or the exception reaches the main function. see EGL core Exception records. onException(myEx AnyException) myErrorHandler2(myEx). onException(myEx FileIOException) myErrorHandler1(myEx). the program ends immediately and writes the message field of the exception to the log. “Overview of service-oriented architecture (SOA)” on page 475 Related reference Service part Service parts provide requesters with access to the functions in the service. either by selecting a JSP template or adding the .make an EGL application act as a service requester. Also. See “Creating a Web page” on page 392. User interface changes in EGL V7. Most important.jsp extension to the file name. See “The EGL editor” on page 155. EGL debugger When debugging an application. handler. and deployment descriptor file. library. Similarly. any logic part can now behave as a requester. but you now add Web service deployment information to the EGL deployment descriptor file. interface part. The editor also provides context-sensitive help for many EGL keywords if you highlight the keyword and press F1. you can now jump to a specific line in the code or run the application until a certain line in the code. you no longer call functions in the service binding library. or other service. In this way. you can set the debugger to use Introduction 37 . To create a Web page in an EGL Web project. or “Setting preferences for organizing import statements in the EGL editor” on page 178. to use the service in one of your logic parts). Related tasks “Elements of a service-oriented application” on page 478 The major elements of an EGL service-oriented application are the service part.0 Creating Web pages The wizards used for creating different types of Web pages have been consolidated into a single wizard. be careful to select a WebContent folder in an EGL Web project and to specify that you want a JSP file. In the New Web Page window. to act as a requester of a service (that is. which defines both how your service requesters access external services and how your service makes itself available to other applications. See “Moving parts” on page 121 or “Renaming parts” on page 120. Also. the service binding library is no longer used. See “EGL debugger commands” on page 580. click File → New → Other → Web Page. EGL editor The EGL editor now supports folding to temporarily hide sections of code. except for some changes in properties. each of these files and parts has a role in both services and service requesters. In general. General workbench enhancements Refactoring support is enhanced so you can move and rename parts without having to make as many manual corrections. In its place is the EGL deployment descriptor file. A requester can be a local or remote program. Instead. you can now generate services and requesters to iSeries COBOL and CICS. 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. and it has an ″Organize Imports″ option to order and simplify the import statements in your code. The Service part is essentially the same. “Setting preferences for folding in the EGL editor” on page 176. This document is available on the EGL Web site. EGL deployment descriptor editor EGL provides a graphical editor for working with the new EGL deployment descriptor file. Cheat sheets EGL offers a set of cheat sheets to lead you through common tasks. Migrating from a previous version of EGL This topic covers migration from an earlier version of EGL to the current version. Related Concepts “What’s new in EGL V7. see the IBM VisualAge Generator to EGL Migration Guide. See “Using cheat sheets” on page 166. v For details on migrating source code written in Informix® 4GL. See “Setting generation preferences” on page 180. See “Creating a data access application” on page 208. A local copy is available at the topic Migrating from VisualAge Generator to EGL.0” on page 18 “Language changes in EGL V7. A local copy is available at the topic Converting from IBM Informix 4GL to EGL.0” on page 19 This topic lists the changes to the EGL language in version 7. This document is available on the EGL Web site. You can also migrate to the current version of EGL from other languages: v For details on migrating source code written in VisualAge Generator.0. See Generating source code from UML models and UML Elements to EGL Transformation . See “Setting preferences for the EGL debugger” on page 604. logic parts. see the IBM Informix 4GL to EGL Conversion Utility User’s Guide. See “Encrypting passwords” on page 146. 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 “Changes to services in EGL V7.either the generated source or the EGL source for a called program or service. Generation options You can now set which parts you want to generate automatically when you save a file. 38 EGL Programmer’s Guide . and Web pages to use with a database connection. 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.0” on page 36 Password encryption EGL now encrypts your passwords in certain situations and provides a utility for encrypting passwords manually. which offers more flexibility in creating data parts. See Editing build descriptor options in the build descriptor part. Data Access Application wizard The Parts and Pages wizard and Data Parts wizard have been combined into the Data Access Application wizard. 0 with iFix 001 – Version 6. if you use the VisualAge Generator compatibility preference.Everyone running a version of EGL earlier than version 7. build the project manually by clicking the project and then clicking Project → Build Project. v Set preferences before importing projects into your new workspace. v Import all projects referenced by the project that you are migrating into your workspace. up to but not including version 7. Migration paths are provided for code at the following levels: – Version 5. because the steps for migration are different depending on your current version. You do not have to migrate the referenced projects at the same time. Important: Do not use the migration tool on code that has already been updated to EGL V7. v All Eclipse Web projects. Some minor migration changes are required to move from version 7. This does not mean that your EGL code is migrated automatically.0. are updated automatically to work in the new version of the workbench.0. up to but not including version 6.0 iFix 001 as explained in “Migrating EGL code to EGL V6.0 with iFix 001. Make the following changes to the code manually to migrate the code to version 6. 2.1.1: Introduction 39 . updates invocations of system libraries that have changed.0 migration tool” on page 44.1 – Version 7.5.0 with iFix 001 1. Doing so can create errors in your code.0 – Version 7.0 workspace. not just EGL Web projects.0 iFix 001” on page 56. but they must be present for the tool to work properly.2. up to but not including version 6.5 Follow the steps below to migrate EGL code to the current version.0 must go through a migration process before using EGL version 7. take these steps to prepare for migration: v You may need to install APARs or PTFs or both to bring your runtime environment (the environment in which you generate Java or COBOL from EGL) to the correct level for EGL version 7. Migrate the code to version 6. EGL provides tools for these migration processes. just that your Web projects are updated to the current standard. but you must migrate JSP files and their associated pageHandler parts at the same time. 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.1 – Version 6.0 or later. up to but not including version 6. using the section that represents your code’s current version: Version 5. You can migrate entire projects at a time or select individual packages or files to migrate. The tool corrects syntax changes. If you do not have automatic builds enabled.1.0 to version 7. Before you begin. and makes other updates as described in “Changes made by the V7. For example.1 up to but not including version 7. v Determine the current version level of your code.0.1.2. v Back up your code. The migration tool attempts to resolve references to parts in the migrated code.0 up to but not including version 7. corrects the names of properties that have changed. you must set it before you bring in the files you want to convert. Migrate the code from version 6.0” on page 43.copyBytes VGLib.0.concatenateBytes 3. as evidenced by an error message that indicates a problem with the argument’s primitive type.concatenate New function VGLib. However. you must change the project.0.1 No program is available to automate the migration from version 7.0 as explained in “Migrating EGL code to EGL V7. but only if the last argument in the invocation is a numeric value.1 to version 7.0 to version 7. up to but not including version 6. Migrate the code from version 6.0 to 7. and in most cases no migration is necessary. which is now an operator.0.0 1. Table 4.compareStr StrLib.0 up to but not including version 7.CopyStr StrLib. Version 6. v If you are working with a Web project that was generated for V7. Here are two exceptions: v If you use forms and you migrated to V7. Migrate the code from version 6.CopyStr StrLib.0 as explained in “Migrating EGL code to EGL V7.v Make sure that none of your identifiers (such as variable or part names) begins with the at symbol (@).concatenate New function VGLib. Version 6. v Change invocations of the following system functions.0” on page 43. Make the following changes to the code manually to migrate the code to version 6. The following changes are required to migrate forms from EGL V7 to V7. Version 7.1 1. which is now an operator. Table 3.concatenateBytes 2. but only if the last argument in the invocation is a numeric value.copyBytes VGLib.1.compareBytes VGLib.compareBytes VGLib.0.1. Manual changes to system functions Old function StrLib. no change is necessary if the project is to run on a server other than WebSphere Application Server.1.1: v Make sure that none of your identifiers (such as variable or part names) begins with the at symbol (@).0.0.1 to version 7. Most users with forms did not migrate to V7. Manual changes to system functions Old function StrLib.0 as explained in “Migrating EGL code to EGL V7.1: v Add the @ operator to all printFloatingArea and screenFloatingArea properties.0.1 to version 7. 40 EGL Programmer’s Guide .3 and whose code will run in WebSphere Application Server and will access Web services on any platform. up to but not including version 7. v Change invocations of the following system functions. because forms are not supported in that version.compareStr StrLib.0 with iFix 001.0” on page 43. you must make changes in your code by hand before you run V7. as evidenced by an error message that indicates a problem with the argument’s primitive type.0. you might need to make manual changes.5: v ExternalType function parameters require the in modifier. f.jar. “Changes to services in EGL V7.0.5 When you launch the product. The following code changes require some files or projects to migrate from EGL version 7.0. find the Application section. This check is also performed when you import a project or check a project out of a source code manager. 2.0. jaxrpc. At the bottom of the Deployment page. Web. ensuring that the build descriptor option ServerType is set to the appropriate version of WebSphere Application Server.0” on page 36 “Changes not made by the V7.jar. e. In the deployment descriptor editor.0” on page 18 “Changes made by the V7. Related concepts “What’s new in EGL V7.v Place all of the @printFloatingArea complex properties for a form inside the new printFloatingAreas property. In the Applications list. not an EGL deployment descriptor.jar.0” on page 36 This topic covers changes to the way EGL deals with exceptions in version 7. v The path to Apache jar files has changed. v BIRT report files need ICU4J (International Components for Unicode for Java) support.5.war file that represents the Web project. This deployment descriptor is a J2EE deployment descriptor.jar 3.jar. where projectName is the project name. Save and close the deployment descriptor. select the .1 to version 7. Select PARENT_FIRST in the Classloader mode list. Version 7. commons-discovery-0.2. the Workspace will display a message to that effect. all projects will be checked to see if migration is needed. c. Regenerate the project.jar.0” on page 43 Introduction 41 . go to the Deployment tab.1.0 migration tool” on page 44 “Changes to exception handling in EGL V7. b.0 migration tool” on page 54 After migrating your code to V7. wsdl4j-1. d.1 up to but not including version 7. You can then select the specific projects and resources to migrate.jar. Go to the Resource perspective (not to a Java. eglwsdl.4. or EGL perspective) and remove the following jar files from projectName/WebContent/WEB-INF/lib: axis. commons-logging-1. Related tasks “Setting EGL-to-EGL migration preferences” on page 42 “Migrating EGL code to EGL V6. Double-click Deployment Descriptor: projectNameEAR found in the root of the Web project. saaj. If you need to migrate. v Place all of the @screenFloatingArea complex properties for a form inside the new screenFloatingAreas property. The following changes are necessary to the Web project mentioned earlier: 1.0 iFix 001” on page 56 “Migrating EGL code to EGL V7. Switch the classloader for the WAR file in the associated EAR to PARENT_FIRST as follows: a. Enable the EGL V7. Click Window → Preferences. the itemsNullable build descriptor option has been replaced with the I4GLItemsNullable property. d. 42 EGL Programmer’s Guide . and those functions contain variables that are now reference types (such as arrays). In the text box by this radio button. As explained in the section on nullable types in “Language changes in EGL V7. and others apply only to one migration. expand EGL Developer and select the EGL V7. delete those Java files manually. 6. 7. type the suffix you want the migration tool to add to the changed word. Click OK.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. e. This page shows the settings for the migration tool. c. If your project has standalone functions. Follow these steps to set EGL migration preferences: 1. See “Changes made by the V7. Click Window → Preferences. Click OK again. Always. This change affects only the Java files in the same project as EGL code that you are migrating. f. just the default build descriptors. 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. 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!"). The migration tool can delete the Java files from your projects so that the Java files can be re-generated from the EGL source. 2. In the Advanced window.0 migration tool” on page 44 for more information on converting from assignment statements to move statements for reference variables. Select the Add property I4GLItemsNullable=yes if you want the migration tool to add this property. Select a radio button under Project build descriptors to update with the deployment descriptor name.0” on page 19. 9. select the check box labeled Convert assignment statements to move statements. type the prefix you want the migration tool to add to the changed word. b. In the text box by this radio button. Expand EGL and click Migration. It can update all build descriptor files. Expand General and click Capabilities. See textLiteralDefaultIsString. 3. Click Advanced. functions that are not contained by any other logic part. 5. The migration tool can set the deploymentDescriptor build descriptor option to the name of an EGL deployment descriptor file in the project. The migration tool can add this property to your logic parts automatically. that is. 8. v Add prefix sets the migration tool to add a prefix to any words in the source code that are now reserved words. If you are generating the EGL code into a different project.0 Migration check box. or none at all.0 migration capability: a. 4. Select Prompt. Some of these preferences are meaningful for both the version 6 and version 7 migration. or Never. 2.0. Select an option under Add a webservice element to the deployment descriptor for every service. 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. expand EGL Developer and select the check box labeled EGL V7.0” on page 19 This topic lists the changes to the EGL language in version 7. Click Window → Preferences. Expand General and click Capabilities.0. b.0.0” on page 36 “Language changes in EGL V7.0 Migration. 14. select Remove Web Service references from the J2EE deployment descriptor. the migration tool adds level numbers to Record parts that do not have level numbers. Click Advanced.0. f. To add a qualifier to the values of properties that have a finite list of possible values. click OK to save your changes.0: Note: Do not use the migration tool on code that has already been updated to EGL V7.0 migration capability: a. If you want the migration tool to make this change. Introduction 43 . This preference applies only to V6. Follow these steps to run the migration tool to migrate code from EGL version 6. When you are finished setting preferences. If this box is checked.0 migration. “Changes to services in EGL V7. Click OK again. 11. d. e. Set the default level number in the Default level number for record structure field. When migrating to V6. 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. 15. Enable the EGL V7. 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. c. Related tasks “Migrating from a previous version of EGL” on page 38 Migrating EGL code to EGL V7. 13. select the Add qualifiers to enumeration property values check box. Set the preferences for the migration process as described in “Setting EGL-to-EGL migration preferences” on page 42. Click OK. ensure that you have followed the complete steps for migration as explained in “Migrating from a previous version of EGL” on page 38. Under Logging options. Doing so can create errors in your code.10.0” on page 36 This topic covers changes to the way EGL deals with exceptions in version 7. 12.0.0. In the Advanced window.1 or later to version 7. the migration tool will add the type of value to the value name. 1.0 migration tool” on page 44 “Changes to exception handling in EGL V7. Related concepts “Changes made by the V7.0 Before migrating to EGL V7. When you are finished reviewing the changes.0 migration tool makes. Right-click on a selected resource and then click EGL V7.0.0” on page 36. Inspect your code for errors and for places that do not comply with EGL V7. do as follows: 1. New reserved words Depending on the preference settings. In the Project Explorer view. the migration tool adds an EGL Deployment Descriptor file to the project. If the preference to delete Java files is enabled. The migration tool updates project classpaths to reflect new names and locations of JAR files. 2. This change affects only the Java files that are in the same project as the EGL code you are migrating. Optionally. Related concepts “Changes made by the V7.0 Migration → Migrate.0” on page 36. the migration tool adds a prefix or 44 EGL Programmer’s Guide . Related tasks “Migrating from a previous version of EGL” on page 38 “Setting EGL-to-EGL migration preferences” on page 42 Changes made by the V7. 5. delete those Java files manually. You can select any number of EGL resources to migrate. If you are generating the EGL code into a different project. See the section on changes to services and service binding libraries later in this section. you can disable the V7. folders. 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. packages.0.0 migration tool” on page 54. 4.3. Examine the differences between the file in the workspace and the previous version. including removing JAR files that are no longer used. press and hold CTRL while clicking the resources. “Changes to services in EGL V7. or files that you want to migrate. Some of these changes can be controlled by the migration tool’s preferences. right-click an EGL source file that has been migrated and then click Compare With → Local History. click OK.0 migration capability to avoid migrating the same code twice. you might need to make manual changes. To select more than one resource at once. and “Changes to exception handling in EGL V7.0 migration tool” “Changes not made by the V7. You might need to make manual changes to your code as explained in “Changes not made by the V7. In the Project Explorer view. the migration tool deletes the Java files from your projects so the Java files can be re-generated from the EGL source.0 migration tool” on page 54 After migrating your code to V7. select the EGL projects. To review the changes that the tool made to the source code. 6. See “Setting EGL-to-EGL migration preferences” on page 42 for more information.0 migration tool This topic lists the changes that the V7. 3. The migration tool changes the keyItem property on records with the stereotype relativeRecord to the recordNumItem property. It puts the value of outline in brackets because this property is now an array. The migration tool changes the value of the protect and outline property on Text UI form fields to the ProtectKind and OutlineKind enumeration. Changes to the protect and outline properties on Text UI form fields Old property and value protect = yes protect = no protect = skip outline = box outline = noOutline New property and value protect = ProtectKind.noProtect protect = ProtectKind.skipProtect outline = [OutlineKind. 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 Build descriptor options wrapperCompatibility If your . the migration process checks the value of the Introduction 45 . Table 5. Properties Changes to existing properties The migration tool changes the values of properties that are no longer quoted strings. The migration tool does not change the value of protect on fields in a ConsoleForm record.eglbld file does not include the wrapperCompatibility build descriptor option.0” on page 19. See the section ″Some property values are no longer quoted strings″ in “Language changes in EGL V7.0” on page 19.suffix to existing names that conflict with new reserved words. The migration tool changes the isNullable property to isSQLNullable.protect protect = ProtectKind. See ″New reserved words″ in “Language changes in EGL V7.noOutline] 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. in which case the migration tool changes empty strings ("") to NULL. This change includes the pcbParms property.box] outline = [OutlineKind. explicit. System functions and variables General changes v The migration tool changes uses of system functions and variables that have changed names. 46 EGL Programmer’s Guide .Connect (formerlySysLib. respectively. ConvertDirection. Changes to INTERVAL variable declaration Old code intval1 interval. not before.Connect follow: Table 7. SysLib. If the variable was already at the beginning of the code block. 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. c ). Variables Variable scope within code blocks As explained in ″Scope of variables within functions″ in “Language changes in EGL V7.0” on page 32. Default specifier for INTERVAL variables The migration tool adds a default format specifier to INTERVAL variables without a specified format: Table 6. Migrated code intval1 interval("yyyyMM"). If that variable was initialized.connect( a. Some examples of how the migration tool deals with invocations of SqlLib. v The migration tool changes uses of the sysLib.Connect Old code SysLib.convert() system function to use the ConvertDirection enumeration.local and ConvertDirection. Changes to calls to SqlLib. b. v The fourth parameter of the SqlLib.enableJavaWrapperGen build descriptor option.0” on page 19.remote. serializableTransaction ). as in this example: sysLib. For more information on wrapperCompatibility. b.connect( a. so the migration tool removes it. See “Changes to system libraries and variables in EGL V7. c. SQLLib. commitScope. see wrapperCompatibility.Connect) system function. migration adds the wrapperCompatibility build descriptor option and sets it to V6. serializableTransaction ). b. If enableJavaWrapperGen is set to YES or ONLY. the migration tool converts the initializer into an assignment statement and leaves the assignment statement where the original location of the variable declaration was.convert(myOrderRec. c. the migration tool moves its initializer into an assignment statement and puts that assignment statement at the end of the variable declarations. Also. Migrated code SQLLib. myConvTable). Values of ″L″ and ″R″ are changed to ConvertDirection.connect( a.local. variables are now in scope only after their declaration. explicit. c. b.connect( a. is no longer needed. d ). The migration tool moves all local variable declarations to the beginning of the code block. serializableTransaction ).round() with only one argument are changed to use MathLib. c. uses of MathLib. result).cos() MathLib.connect( a.cosh() MathLib. g ). c. b.round() with two arguments are not changed. result). This change affects the following functions: – MathLib. d. v To maintain compatibility with rounding rules in previous versions. Changes to uses of functions in MathLib Old code result = abs(x).atan() – – – – MathLib. y). SysLib.atan2() MathLib.Connect (continued) Old code SysLib. b. f. f ).asin() – MathLib. result = round(x. g ).round() Old code result = round(x). d.Table 7.modf() MathLib.pow() Introduction 47 .floatingMod() – – – – – VGLib.floatingSum() MathLib.ldexp() – MathLib.min() MathLib. Changes to calls to SqlLib. e. Some examples follow: Table 9.frexp() MathLib. b.acos() – MathLib. e. Migrated code assign(abs(x). f ).connect( a.log() – MathLib. SQLLib. SQLLib.log10() – – – – MathLib. e.connect( a. c. result = pow(x. Changes to uses of MathLib.floatingDifference() – VGLib. c. f. b.max() MathLib. b.floatingProduct() VGLib. e. b. e. d. c.assign().connect( a.connect( a. e ). the migration tool wraps calls to functions in MathLib within MathLib. No change. Uses of MathLib. y). assign(pow(x. Also to maintain compatibility with rounding rules in previous versions.exp() – VGLib. Table 8.abs() – MathLib. c. result). Migrated code SQLLib.assign().connect( a. Migrated code assign(x.floatingQuotient() VGLib. powerOfTen). SysLib. sqrt() MathLib. Changes to console form initializers Old code newForm consoleFormType. the migration tool adds an initializer to reference variable declarations without an initializer: Table 13. result = x. result = stringAsFloat(x). In the case of stringAsDecimal. Migrated code newArray string[0]. Changes to array initializers Old code newArray string[]. result = stringAsDecimal(x) + 5.tan() MathLib. certain arguments in certain functions in JavaLib could accept a casting operator in parentheses.– – – – – MathLib. result = stringAsInt(x) + 5.sin() MathLib. Migrated code newForm consoleFormType{}. the migration tool does not know what length to give the resulting DECIMAL type.Integer" Unnecessary conversion functions The migration tool corrects uses of removed conversion functions. The migration tool initializes the following reference variables in this way: v ArrayDictionary 48 EGL Programmer’s Guide . The migration tool changes this casting to use the syntax variable as "type". result = x as Float + 5.lang. Migrated code result = x.Integer" Migrated code myVar as "java:byte" myVar as "objId:java" null as "java. result = x as Decimal() + 5. result = x. Changes to casts in JavaLib functions Old code (byte)myVar (objId)myVar (null)"java. 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. Migrated conversion functions Old code result = stringAsInt(x).lang. result = stringAsFloat(x) + 5. result = stringAsDecimal(x).tanh() Casting with system library JavaLib In previous versions. the tool adds a cast as necessary: Table 11. If the conversion function is used as part of a mathematical expression. Also. result = x as Int + 5.sinh() MathLib. as in these examples: Table 10. . end The migration tool changes this function definition to the following: function doSomething (myParam int[] out) myParam = new int[]... that is. Assignment statements for reference types When one reference variable is assigned to another. If the migration preference is disabled.. assume the following function definition: function doSomething (myParam int[] out) . a function that is not within a logic part. v If the migration tool cannot resolve both sides of an assignment statement. Changes to assignment statements for reference types Old code array1 = array2. In this case. 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. end The migration tool makes this change only for arrays and only if the arrays have the out modifier. it changes the assignment statement to a move statement as it does in any function. . 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). the associated migration preference takes effect. For example. if the migration preference is enabled. Nullable variables Expressions with null values The migration tool changes expressions with null values to the new Introduction 49 . the tool changes the assignment statement to a move statement as above. the migration tool changes the assignment statement to a move statement to keep the behavior consistent with previous versions. the migration tool adds a new statement at the first line of the function to initialize the array. The following example assumes that the variables array1 and array2 are arrays or other reference variables: Table 14. the tool makes no change to the assignment statement.v v v v BLOB CLOB Record parts with the stereotype consoleForm Dictionary In a function definition containing an array with the out modifier. Migrated code move array2 to array1. transfer. For statements within a standalone function.0” on page 19. Changes to syntax of call. 2) {IsNoRefresh = yes. it can determine that the variables on both sides of the statement are records or forms). If it cannot resolve both sides of the assignment statement. Migrated code call "xxx" (1. itemsNullable build descriptor option Depending on the preferences. myVar is NULL Migrated code myVar = NULL. the migration tool makes no change. 2 norefresh externallyDefined. transfer to program "xxx" passing yyy {IsExternal = yes}. 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. Changes to call and transfer Old code call xxx 1. transfer to program xxx passing yyy externallyDefined. it adds withV60Compat instead of byName to maintain compatibility with the previous version. v If the migration tool cannot resolve both sides of the move statement. or if the associated migration preference is enabled. the migration tool adds the byName option to move statements between two record or form variables. The migration tool makes a similar change to show statements.nullability rules explained in “Language changes in EGL V7. Table 15. it adds byName as it does in any function. The migration tool makes this change only if it can resolve both sides of the assignment statement. and show The migration tool changes the uses of these three statements to comply with their new syntax: Table 16. 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. and the migration preference is disabled. 50 EGL Programmer’s Guide . Migration of expressions with null values Old code set myVar NULL. myVar == NULL nullable modifier The migration tool changes uses of the nullable modifier on function parameters to sqlNullable. IsExternal = yes}. v The tool changes links to pages with the extension . v The tool adds cancelOnPageTransition = YES to all pageHandler parts that do not have this property defined. 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. In forward to URL Introduction 51 . The tool updates ServiceLib. 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. v The tool converts the pageHandler onPageLoadFunction property to the JSF Handler onConstructionFunction property.getWebServiceLocation and ServiceLib. which by default has the same name as the project. the migration tool changes the statement exit program to exit rununit.setWebServiceLocation. the migration tool sets the deploymentDescriptor build descriptor option to the name of the new deployment descriptor. If the preference to remove Web service references from the J2EE deployment descriptor is enabled. the migration tool creates an EGL deployment descriptor in the 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. Services @WSDL and @XSD properties The migration tool converts the @WSDL property to the @XML property and removes the @XSD property.getWebEndPoint and ServiceLib.jsp to . The isLastParamReturnValue property field of the @WSDL property is discarded. the migration tool removes these references.faces in forward to URL statements and action properties. the tool converts the elementName property field of the @WSDL property to the name property field of the @XML property. PageHandler parts Conversion to JSFHandler parts v The migration tool changes pageHandler parts to Handler parts with the stereotype JSFHandler. In the process. Changes to in with an array Old code if ( a in myArray[4] ) Migrated code if ( a in myArray from 4 ) exit statement changes In logic parts other than programs and standalone functions. The tool makes no change to exit statements within a program or standalone function.in array expression The migration tool converts statements that use in with an array to use from as well: Table 17. respectively.setWebEndPoint to ServiceLib. the migration tool uses the value of the value property.EGLmyComboBoxChoicesAsBoolean}"/> </h:selectOneMenu> The migration tool converts this tag to the following: <h:selectOneMenu styleClass="selectOneMenu" id="menu1" value="#{myPage.jsp".statements. Migrated code myLink string {displayUse = hyperlink. the migration tool updates the value attribute to remove the EGL prefix and any suffix. item2 string { value = "item3ValueProp" }. These changes are in addition to the changes that happen when the migration tool migrates the pageHandler parts to JSF Handlers. such as AsBoolean. as in the following examples: Table 19.faces". For example. forward to URL "myPage. item2 string {} = "item3ValueProp".EGLmyComboBoxValue}"> <f:selectItems value="#{myPage. Following are examples of these changes: Table 18. the tool makes this change only if the target of the forward to URL statement is a quoted string that ends with . The tool saves the changes only if the resulting value attribute correctly references a variable in the JSF Handler. the migration tool aliases variables or handler names containing an underscore character to _005f.myComboBoxChoices}"/> </h:selectOneMenu> The migration tool makes this change for the following tags: – <h:selectManyCheckboxlist> 52 EGL Programmer’s Guide . Changes to links in pageHandlers Old code myLink string {displayUse = hyperlink. assume this <h:selectOneMenu> tag: <h:selectOneMenu styleClass="selectOneMenu" id="menu1" value="#{myPage. v In some cases. JSP files The migration tool makes changes to JSP files associated with pageHandler parts to update references to variables in the JSF Handler. v For JSF tags such as <h:selectOneMenu> and any <h:selectItems> or <h:selectItem> tag inside those tags. forward to URL "myPage. action="myPage. In uses of the action property. Changes to the value property in variables in PageHandler parts Old code item1 string { value = "item1ValueProp" } = "item1Initializer". 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 . See “Running a Web page on a server” on page 448 for more information on file extensions of JSP files. The tool makes these changes only if you migrate the pageHandler parts at the same time as you migrate the JSP files.jsp. v The tool converts uses of value to initialization statements. Migrated code item1 string {} = "item1ValueProp".myComboBoxValue}"> <f:selectItems value="#{myPage. action="myPage. If the variable has both a value property and an initialization statement.jsp.jsp"}.faces"}. v For any other JSF attribute that contains an expression in the form #{beanName. the migration tool makes no change. It changes #{beanName. the migration tool adds the suffix . 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. and the file name is not already being used. If the file name is already being used. the migration tool adds the suffix _exeIdx. the migration tool checks each ConsoleForm to see if its name matches the name of its file. If the file name does not match. v Similarly. the migration tool makes additional changes to the value field: – If the selectType property is set to index. – If the selectType property is set to value. along with any necessary import statements.commandActionListener} to #{beanName. the migration tool removes the EGL prefix and any suffix such as AsBoolean or AsInteger from the list above. such as those on JSF command buttons.– – – – – <h:selectManyListbox> <h:selectManyMenu> <h:selectOneListbox> <h:selectOneMenu> <h:selectOneRadio> It also makes the change for <f:selectItems> and <f:selectItem> within these tags.toArray. the tool also adds a binding attribute with the following value: #{beanName.variableName}. v The migration tool updates any tags with actionListener attributes. In this case._commandActionListener}. 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.toArray.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. and you will have to correct your ConsoleForm parts accordingly.variableName}. the tool creates a new file with the name of the ConsoleForm and moves the ConsoleForm part into that new file. Other parts ConsoleForms Because ConsoleForm parts are now generatable parts. Introduction 53 . 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. the migration tool may add a cast to the DECIMAL type as necessary to maintain the behavior of the old code. VGUIRecord parts The migration tool sets the following properties on VGUIRecords: v60ExceptionCompatibility = YES. Project Builders When importing a migrated project into a V7. Related tasks “Migrating from a previous version of EGL” on page 38 Changes not made by the V7. rather than the EGL property. 3. Using the Down arrow button. myResult decimal(7. 4.Interface parts The migration tool removes the BasicInterface stereotype from Interface parts. Follow these steps to edit the build order in this way: 1. It also converts all Interface parts with the JavaObject stereotype to ExternalType parts. right-click the project and then click Properties. move the EGL Advanced Builder under the EGL Build Parts Model Builder and the EGL Validation Builder. ThrowNrfEofExceptions = YES Related concepts “Setting EGL-to-EGL migration preferences” on page 42 “Changes to build descriptor options in EGL V7. For example. EGL may resolve references to that name with the user-defined part.0.2). 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. In this case. In the Project Explorer view. assume the following old code: myStringNumber string = "5". select the EGL Advanced Builder. you will need to manually add a length. myResult = stringAsDecimal(myStringNumber) + 5. 5.0 migration tool After migrating your code to V7.0 workspace. Property resolution If you define a part with the same name as an EGL property. Casts in removed conversion functions If you migrated a stringAsDecimal function. Click OK. click Builders. 2. you might need to make manual changes. In the Properties window. On the Builders page. HandleHardIOErrors = NO.0” on page 35 “Language changes in EGL V7. The tool migrates this code to the following: 54 EGL Programmer’s Guide .0” on page 19 This topic lists the changes to the EGL language in version 7. To resolve this issue.0. xmi and ibm-webservicesclient-bnd. the Web deployment descriptor is named web. that variable must be an INT type. delete any EGL-generated service references from the file and retain any manually added references. On J2EE 1. you must delete the file. also found in WebContent/WEB-INF. Naming conflicts between functions and variables You cannot have a variable and a function within a logic part with the same name. v Similarly. selectFromListItem property When a variable has the selectFromListItem property. In most versions of J2EE. 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. myResult decimal(7. If you added no references to these files manually. If you did not add any service references to the file manually. if you added service references to the Web deployment descriptor file manually. To use a record array or an array of primitive variables within a record as a list of selection options.myStringNumber string = "5". the file is named webservicesclient. remove any EGL-generated service references from the files ibm-webservicesclient-ext.2) + 5. However. 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.2). You must add a length to the DECIMAL type.3. you must remove outdated service references from your metadata files manually: v For EGL Web projects. you can delete the files.xml and is located in the project’s WebContent/WEB-INF folder. Related concepts “Changes made by the V7. but the parentheses denoting the parameter list are now required.xmi. Called programs without parameter lists Programs that are the target of a call statement must have a parameter list.xml and is located in the same place. myResult = myStringNumber as decimal() + 5. myResult decimal(7. use the properties selectedRowItem or selectedValueItem instead. the property’s value cannot be a record array or an array of primitive variables within a record. 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. myResult = myStringNumber as decimal(7. This parameter list can be empty. as in the following: myStringNumber string = "5". selectType property in JSF Handlers If a variable in a JSF Handler has the selectType property set to index. Valid types are a data table column or an array of primitive variables not within a record.2).0” on page 24 Related tasks Introduction 55 . Rename the variable or the function. but you are not required to.0 migration tool” on page 44 “Validation changes in EGL V7. For more information on the code that is changed by the migration tool. In the Project Explorer view. In the Project Explorer view. Set the preferences for the migration tool. d. do as follows: 1. In the Advanced window.0 migration capability to avoid migrating the same code twice. When you are finished reviewing the changes. 5.0” on page 43 “Migrating from a previous version of EGL” on page 38 “Setting EGL-to-EGL migration preferences” on page 42 Migrating EGL code to EGL V6.0 iFix001. or a selection of files.0 iFix001.0 Migration → Migrate. c. 2. See “Setting EGL-to-EGL migration preferences” on page 42. or files that you want to migrate. To review the changes that the tool made to the source code. e.1. folders. do as follows: 1.0 iFix001. a single file. right-click an EGL source file that has been migrated and then click Compare With → Local History. To migrate EGL code to EGL V6. see “Changes made by the V6.0 iFix 001 migration tool” on page 57.0 iFix 001 The EGL V6. To select more than one resource at once. Click Advanced. expand EGL Developer and select the EGL V6. click OK.“Migrating EGL code to EGL V7. The migration tool converts the selected EGL source files to comply with EGL V6. You can select any number of EGL resources to migrate. Optionally. f. Expand General and click Capabilities. hold CTRL while clicking the resources. Click OK again.0 iFix 001 migration tool” on page 57 Related tasks “Migrating from a previous version of EGL” on page 38 “Setting EGL-to-EGL migration preferences” on page 42 56 EGL Programmer’s Guide . The migration tool can be used on an entire project.0 iFix001. 4. packages.0 migration tool converts EGL source from versions V5.2 and V6. Click OK. Doing so can create errors in your code. 3. you can disable the V6. Click Window → Preferences.0 Migration check box. Enable the EGL migration capability: a. Important: Do not use the migration tool on code that has already been updated to EGL V6. 2. Running the tool on a package or folder converts all of the EGL source files in that package or folder. Right-click a selected resource and then click EGL V6.0 to comply with EGL V6. 3. select the EGL projects. Examine the differences between the file in the workspace and the previous version. Related concepts “Changes made by the V6. b. End End v The migration tool adds level numbers to records that do not have level numbers. End After migration: Library Handler_EGL boolean_EGL Bin(4). It does not change the single equals sign when it is used as an assignment operator.0 iFix 001 migration tool The EGL V6. the tool adds the suffix _EGL to any name that is now a reserved word. If(param == 3) a = 0. See “Setting EGL-to-EGL migration preferences” on page 42. For information about the changes to properties.0 iFix 001 : v The migration tool makes changes to the way properties are specified.0 to comply with EGL V6. Important: Do not use the migration tool on code that has already been updated to EGL V6. Before migration: Function test(param int) a int.2 and V6. v The migration tool searches for variables and part names that conflict with reserved words. Doing so can create errors in your code.0 iFix 001 migration” on page 60. The following are examples of code before and after using the migration tool. see “Changes to properties during EGL V6.Changes made by the V6. End Introduction 57 .0 iFix 001. and it does not update references in EGL Build Part files. item2 int.0 migration tool converts EGL source from V5. 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. The migration tool changes those variable and part names by adding a prefix or suffix as defined in the migration preferences. Before migration: Record MyRecord item1 int. If(param = 3) a = 0. Before migration: Library Handler boolean Bin(4).1.0 iFix 001. It can also add comments to the project’s log file. The migration tool changes EGL code in these ways to comply with EGL V6. The migration tool can add comments to each file it changes. End End After migration: Function test(param int) a int. The migration tool does not rename objects of the CALL statement. By default. javaRemove sysLib.formatDate() strLib. 10 item2 int.After migration: Record MyRecord 10 item1 int.clearRequestAttr sysLib.formatTime() strLib.javaStoreCopy sysLib.storeCopy() javaLib.formatTime sysLib.invoke() javaLib. This change affects variables and functions from the sysLib and sysVar libraries.formatTimestamp sysLib. j2eeLib.javaType sysLib. Changed variable and function names from the sysLib and sysVar libraries Before migration sysLib.javaIsNull sysLib.timestampValue sysLib.javaIsObjID sysLib.remove() javaLib. End v The migration tool changes the declaration syntax of constants.extend() strLib. Before migration: intConst 3.java().javaStoreField sysLib.removeAll() javaLib.timeValue() dateTimeLib.javaGetField sysLib.storeNew() javaLib.java sysLib.extendTimestampValue sysLib.qualifiedTypeName() j2eeLib. A list of changed variables and function names from the sysLib and sysVar libraries follows: Table 20.clearRequestAttr() j2eeLib. v The migration tool changes variables and function names that have been moved to different libraries or renamed.timeValue sysLib.intervalValue sysLib.dateValue() dateTimeLib. After migration: javaLib.getField() javaLib.formatDate sysLib.isObjID() javaLib.javaStoreNew sysLib.timestampValue() javaLib.clearSessionAttr After migration dateTimeLib. clearRequestAttr(). After migration: const intConst int = 3.isNull() javaLib.intervalValue() dateTimeLib.javaStore sysLib. Before migration: sysLib.storeField() javaLib.formatTimestamp() dateTimeLib.setField() javaLib.dateValue sysLib.clearRequestAttr().javaSetField sysLib.clearSessionAttr() 58 EGL Programmer’s Guide .store() javaLib.javaRemoveAll sysLib.invoke(). validationFailed() vgLib.eventKey converseVar.currentFormattedTime vgVar.setSessionAttr() converseLib. Related tasks “Migrating EGL code to EGL V6.currentShortDate sysVar.setRequestAttr sysLib.pageEject() converseLib.getSessionAttr() j2eeLib.currentTime sysVar.getRequestAttr() j2eeLib.sqlerrmc vgVar.Table 20.getVAGSysType() vgLib.handlesysLibraryErrors vgVar.currentFormattedTime sysVar.segmentedMode sysVar.currentDate sysVar.currentJulianDate sysVar.displayMsgNum() converseLib.commitOnConverse converseVar.currentShortJulianDate dateTimeLib.sqlerrmc sysVar.handleOverflow sysVar.fieldInputLength() converseLib.handlesysLibErrors sysVar.sqlIsolationLevel vgVar. and pageHandlers for which that property is not specified.currentFormattedDate sysVar.setSessionAttr sysLib.currentFormattedGregorianDate vgVar.systemGregorianDateFormat vgVar.clearScreen sysLib.currentTimeStamp sysVar.printerAssociation sysVar.handleHardIOErrors sysVar.systemJulianDateFormat vgVar.handleOverflow vgVar. programs.currentGregorianDate vgVar.getRequestAttr sysLib.printerAssociation converseVar.currentShortJulianDate sysVar.currentTime dateTimeLib.getVAGSysType sysLib.systemGregorianDateFormat sysVar.validationMsgNum v The migration tool sets the HandleHardIOErrors property to NO for all migrated libraries.mqConditionCode sysVar.currentJulianDate vgVar.segmentedMode converseVar.clearScreen() converseLib.sqlWarn converseVar.currentFormattedJulianDate vgVar.commitOnConverse sysVar.currentTimeStamp vgVar.systemJulianDateFormat sysVar.connectionService() vgVar.sqlerrd sysVar.validationMsgNum After migration j2eeLib.displayMsgNum sysLib. Changed variable and function names from the sysLib and sysVar libraries (continued) Before migration sysLib.setRequestAttr() j2eeLib.handleHardIOErrors vgVar.sqlerrd vgVar.sqlWarn sysVar.eventKey sysVar.currentFormattedJulianDate sysVar.connectionService sysVar.fieldInputLength sysLib.sqlIsolationLevel sysVar.pageEject sysLib.mqConditionCode vgVar.0 iFix 001” on page 56 Introduction 59 .currentShortGregorianDate vgVar.validationFailed sysLib.getSessionAttr sysLib. 0 iFix 001 migration” Related reference EGL reserved words Changes to properties during EGL V6.0 migration tool makes significant changes to the way properties are specified.0 iFix 001: Table 21. A summary of these changes follows: v The migration tool renames properties whose names have changed in EGL V6.Related concepts “Migrating from a previous version of EGL” on page 38 “Setting EGL-to-EGL migration preferences” on page 42 “Changes to properties during EGL V6. Renamed properties Before migration action boolean getOptions msgDescriptor onPageLoad openOptions putOptions queueDescriptor range rangeMsgKey selectFromList sqlVar validator validatorMsgKey validatorTable validatorTableMsgKey After migration actionFunction isBoolean getOptionsRecord msgDescriptorRecord onPageLoadFunction openOptionsRecord putOptionsRecord queueDescriptorRecord validValues validValuesMsgKey selectFromListItem sqlVariableLen validatorFunction validatorFunctionMsgKey validatorDataTable validatorDataTableMsgKey v The migration tool adds double quotes to property values that are used as string literals.0 iFix 001 migration The V6. Before migration: { alias = prog } After migration: { alias = "prog" } The following properties are affected: – alias – column – currency – displayName – fileName – fillCharacter – help 60 EGL Programmer’s Guide . Introduction 61 . The migration tool uses double sets of brackets for properties that take arrays of arrays. range = (1. screenSizes = (24. functions. screenSizes = [[24. adding quotes and brackets where appropriate. end v The migration tool changes references to parts. 9) } After migration: { keyItems = ["var"]. 80]]. 80). and fields. range = [[1. the migration tool puts single element array literals in brackets to specify that an array with only one element is still an array. end After migration: Form myForm type TextForm fieldArray char(10)[5] { this[1] {color = red } }.– – – – – – – – – – – – 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 pageSize position – range – screenSize – screenSizes – tableNames – tableNameVariables – validationBypassFunctions – validationBypassKeys v For properties that take array literals. 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: { keyItems = var. Before migration: Form myForm type TextForm fieldArray char(10)[5] { fieldArray[1] {color = red } }. "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: { keyItems = (item1. item2) } After migration: { keyItems = ["item1". 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 62 EGL Programmer’s Guide . Changes to the currency property Before migration { currency = yes } { currency = no } { currency = "usd" } After migration { currency = yes } { currency = no } { currency = yes. currencySymbol = "usd" } v The migration tool changes the values of the dateFormat and timeFormat properties to be case sensitive.– – – – – – – – – – – – – – – – – – helpGroup includeMsgInTransaction includeReferencedFunctions initialized inputRequired isDecimalDigit isHexDigit isNullable isReadOnly lowerCase masked modified needsSOSI newWindow numericSeparator openQueueExclusive pfKeyEquate resident – runValidatorFromProgram – segmented – shared – – – – sqlVar upperCase wordWrap zeroFormat v The migration tool splits the currency property into two properties: currency and currencySymbol. Table 22. see ″Date. For more information.box Introduction 63 . Before migration: color = red outline = box After migration: color = ColorKind. The following table gives some examples of how the migration tool changes the currency property.red outline = OutlineKind. the migration tool adds the name of the enumeration to the value of the property. time. v If the Add qualifiers to enumeration property values check box is selected in the preferences menu. and timestamp format specifiers″ in the EGL Language Reference. and timestamps Before migration dateFormat = "yy/mm/dd" dateFormat = "YYYY/MM/DD" dateFormat = "YYYY/DDD" timeFormat = "hh:mm:ss" After migration dateFormat = "yy/MM/dd" dateFormat = "yyyy/MM/dd" dateFormat = "yyyy/DDD" timeFormat = "HH:mm:ss" v The migration tool changes the values of the defaultSelectCondition property to be of type sqlCondition. table2) } { tableNames = (table1 t1. The following table gives some examples of how the migration tool changes the tableNames property. Changes to dates.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. including changing the values of the dateFormat and timeFormat properties to be case sensitive. Before migration: { defaultSelectCondition = #sql{ hostVar02 = 4 } } After migration: { defaultSelectCondition = #sqlCondition{ // no space between #sqlCondition and the brace hostVar02 = 4 } } 64 EGL Programmer’s Guide . ["table2"]] } { tableNames = [["table1". Changes to the tableNames property Before migration { tableNames = (table1. ["table2". Table 23. "t2"]] } v The migration tool changes the way dates. table2 t2) } After migration { tableNames = [["table1"]. times and timestamps are specified. "t1"]. The first element is the table name. Following are some examples: Table 24. is the table label. "t1"]. Each array of strings must have either one or two elements. table2) } { tableNames = (table1 t1. times. if present. and the second element. ["table2"]] } { tableNames = [["table1". 0 iFix 001 migration tool” on page 57 Date/time masks and format specifiers Introduction 65 . Related tasks “Migrating EGL code to EGL V6.0 iFix 001” on page 56 “Setting EGL-to-EGL migration preferences” on page 42 “Migrating from a previous version of EGL” on page 38 Related concepts “Changes made by the V6.v The migration tool replaces the NULL value of the fillCharacter to the empty string value "". 66 EGL Programmer’s Guide . You can create packages within source folders or additional source code folders to organize your files. but in most cases (such as in the Project Explorer view). Web content folder For EGL Web projects. but be aware that they might have different names in your project. Do not edit the files in the generated code folder. EGL puts the generated code into a directory outside the workspace as specified by the genDirectory build descriptor option. 2008 67 . build files. the generated code folder is named src. and deployment descriptor files for the project. See “Creating an EGL package” on page 89 or “Creating source folders” on page 87. Source code folder EGL projects have at least one source code folder. There are no set guidelines for how to use them. Projects An EGL application contains one or more projects to hold and organize your code in folders and files. and those projects can be independent or they can reference each other and use parts from each other’s packages. By default. For COBOL output. A project is contained in a single physical folder in your workspace. and other files that control how the Web project will display in a browser. it is labeled Java Resources. named EGLSource by default. style sheet files. and that folder contains other folders. Some of these folders have default names.Contents of an EGL application This topic describes the artifacts found in a typical EGL application. EGL generates output code only for files within a source code folder. Folders An EGL project can contain several folders. 1996. the Web content folder is named © Copyright IBM Corp. The source folder contains all of the EGL source files. and files. regardless of the actual folder name on disk. You can have as many projects as you want. the Web content folder contains the Web pages. The documentation often refers to these folders by their default name. as described below. EGL then transfers the outputs to the target system based on the destHost and other related build descriptor options. for example. See “The EGL build path” on page 83 for information on references between projects. the EGL source files go in a folder named EGLSource by default. EGLBin folder The EGLBin folder is used to store internal representation files. which are used by EGL in the generation and debugging processes. The needs of your organization and design of the application that you are creating determines your use of projects. By default. 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. packages. because they are overwritten each time you generate the project. These files have the extension .eglpath The EGL build path file is named . such as programs and records.egl. not to be confused with J2EE deployment descriptors. . select the project in the Project Explorer view and then click Project → Build Project. libraries. if automatic builds and the EGL Build before generate preference are both disabled. prompting EGL to create or update the . Deployment descriptors EGL deployment descriptors. and build files. you must invoke a build manually before generating or debugging. Packages Packages are contained within source folders and group source files. META-INF folder For EGL plug-in projects.ir files. the META-INF folder contains the MANIFEST. EGL will not have current . This file lists the locations that are searched for any part that is not 68 EGL Programmer’s Guide . you will not have to spend much time working with other types of files. Generally. Source files always end in the extension . However. See “Elements of a JSF Web application” on page 389 for information on the files specific to Web projects.ir and are found in the EGLBin folder. you can set a preference within EGL to build your projects when necessary by clicking Window → Preferences → EGL → Generation and selecting Build before generate. By default. and select Build Automatically. Files The two major types of EGL files are source 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. To turn on automatic builds. Generally.eglbld. or that the generation process will not have all the parts it needs to generate. These files have the extension . because EGL usually creates them automatically from your source code and build files when the project is built. Build files Build files contain EGL build parts. this situation might mean that the generated output represents outdated source code. you can ignore these files.egldd. and records.WebContent. If you have turned off the automatic builds.MF file. such as build descriptors. contain information about deployment.ir files with which to generate your code. the workbench builds your projects automatically. files that contain EGL parts such as programs. click Project. they are used in generation and debugging. files that contain EGL build parts such as build descriptors. Internal representation files Internal representation files are an intermediate step between EGL source and generated source. To build a project. Web pages EGL Web projects can contain one or more JSP Web pages controlled by JSF Handler parts. These files have the extension .eglpath and is stored in the root of the project. Otherwise. EGL uses the JSF configuration file to determine how to navigate from page to page. See Generating source code from UML models. The plugin. Contents of an EGL application 69 . these files are part of the standard definition of an Eclipse plug-in. EGL files. or the smallest independent unit of functionality in the Eclipse workbench.eglpath file in that project. Files that apply only to EGL plug-in projects EGL plug-in projects contain several files that are not. use the search function of the help system. such as where its default build descriptors are located.xml The plugin. including the source folders in the current project and any other projects on the build path of the current project. More specifically.eglproject This file contains basic information about the EGL project. plugin. Other files Your project might contain any number of other files that are not directly related to EGL. You will rarely need to edit the reference. See “Elements of a JSF Web application” on page 389 for information on the JSF configuration file and for other files related to EGL Web projects. an open-source project. faces-config. EGLSource is a source folder in the current project.xml file is created when you generate a program within an EGL plug-in project.xml file for each Console UI program in the project. when you generate a project. or plug-ins you create yourself. Transformation parameter files When creating EGL code from a UML model. Instead.found in the current project. For more information.xml file describes the extensions that your project adds to the Eclipse framework. In the following example of an . EGL adds the files necessary for the project to function as a plug-in. strictly speaking.eglpath file. When you create an EGL plug-in project.xml For EGL Web projects. . For information about those types of files. see “The EGL build path” on page 83.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 . EGL adds a reference in the plugin. This reference is needed only when running a Console UI program in RCP mode. The workbench itself is composed largely of a collection of plug-ins.TPM file that specifies options for the transformation. either from a commercial product. EGL also adds the files necessary to define a run-time configuration of the workbench. Also. you create a . and AnotherProject is a project in the EGL build path: <?xml version="1. 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. you can extend the workbench by adding additional plug-ins. These projects differ mainly in the types of user interface they support: EGL project A general EGL project is useful for batch or reporting applications.xml file. config. EGL Rich UI project EGL Rich UI projects have most of the abilities of a general EGL project.MF file describes the requirements for a program to run as an RCP application. which in this context refers to the launch configuration for a stand-alone instance of the workbench. and you cannot convert EGL Web projects to EGL projects. Within the Rational development environment. This file is tied closely to the plugin. or anything with a character-based user interface.product.MANIFEST. This file defines what plugins are included in the workbench when running a program as an RCP application. you can use EGL wizards and other tools to write complex applications with minimal effort. Related reference Naming conventions Introduction to EGL projects In the Eclipse workbench.properties This file specifies which files from the project should be used when the plug-in is used in the workbench at run time.MF The MANIFEST. this file sets the value of system variables needed for the launch configuration. “Creating EGL source files” on page 90 The creation process is essentially the same for most EGL source files. plus the ability to create applications with JSF Web interfaces. EGL adopts this framework and keeps its source files in several different types of EGL projects. Product file EGL plug-in projects contain a file named projectName. Related tasks “Creating an EGL project” on page 71 This topic covers how to create an EGL 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 cannot convert any other type of project into an EGL Web project. Related concepts Developing EGL applications Enterprise Generation Language (EGL) is a programming language that you can use to focus on business problems instead of software technologies. plus the ability to create Rich UI applications. a project is a container for a group of related files. This file defines an Eclipse product. You can convert other types of EGL projects into an EGL plug-in project. build. You cannot convert any other type of project into an EGL Rich UI project.ini For EGL plug-in projects. and you cannot convert EGL Rich UI projects to EGL projects. 70 EGL Programmer’s Guide . EGL Web project EGL Web projects have most of the abilities of a general EGL project. where projectName is the name of the project. EAR projects contain information for deployment in the J2EE application framework. If you do not seeEGL Project Wizard. 2. select General Project and continue with the instructions on this page. or other applications with simple user interfaces. Under EGL Project Types. Contents of an EGL application 71 . 6. also called RCP projects.EGL Portlet Project EGL portlet projects contain one or more portlets for use within an enterprise portal framework. v For a project used to develop EGL Rich UI applications. v For a project that can contain portlets. In the New Project window. “Features and facets of EGL projects” on page 76 EGL projects can have additional abilities. Type a name for the project in the Project name field. select Portlet Project. Under Target Runtime Platform. See J2EE Applications. 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. EGL projects can also have additional features and facets added to them to add support for more granular pieces of functionality. “Starting to work with EGL Rich UI” on page 329 This topic tells how to start developing applications with EGL Rich UI. v For a project that can use rich client platform (RCP) user interface. select Rich UI Project and see Starting to work with EGL Rich UI. select Web Project and see Creating an EGL Web project. expand EGL and click EGL Project Wizard. Depending on the target server for the project. 3. To create an EGL project: 1. 5. select Plug-in Project. “Creating an EGL Web project” on page 73 This topic covers how to create an EGL Web project. Related tasks “Creating an EGL project” This topic covers how to create an EGL project. Creating an EGL project This topic covers how to create an EGL project. v For a general-use project appropriate for batch. 4. select the type of project: v For a project that can contain JSF Web pages or Web services. select the Show All Wizards check box. See “Features and facets of EGL projects” on page 76. added through features and facets. From the menu bar. “Creating an EGL plug-in project” on page 74 EGL plug-in projects. reporting. are useful for Console UI applications that you want to run in rich client platform (RCP) mode. select the language to which EGL will generate your project: Java or COBOL. click File → New → Project The New Project window opens. Click Next. EGL Web projects can be connected to an Enterprise Application Resource (EAR) project. If you want an EGL deployment descriptor in the project. Click Finish. change the build file that is created for you. added through features and facets. 14. Under EGL Project Features Choices. On the Order and Export tab of the EGL settings page. see Features and facets of EGL projects. such as the location of the project or what additional EGL features to add. “Features and facets of EGL projects” on page 76 EGL projects can have additional abilities. If you want to configure other options for the project. Related tasks “Creating an EGL Web project” on page 73 This topic covers how to create an EGL Web project. 15. 12. To change those values later. Under Build Descriptor Options. if any. 9. Otherwise. select any other projects in your workspace to be added to the build path of the new project. click Options. select the check boxes for the additional features to include in the project. 10. also called RCP projects. click Finish. v Select an existing build descriptor enables you to specify a build descriptor from those that are available in your workspace. 8. 11. 13. “Creating an EGL plug-in project” on page 74 EGL plug-in projects. To specify a default database connection in that build descriptor. “Starting to work with EGL Rich UI” on page 329 This topic tells how to start developing applications with EGL Rich UI. 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. which has the same name as the project. Accept the default location for the project in the Project location section or clear the Use the default location for the project check box and specify a new location. select Show Advanced Settings and then click Next. Click Next. are useful for Console UI applications that you want to run in rich client platform (RCP) mode. choose where the default build descriptor for the project will be located or created: v Create a new build descriptor means that EGL provides a new build descriptor and writes it to a new build file (extension . v Use the build descriptor specified in the EGL preferences means that EGL points to a build descriptor that you created and identified as an EGL preference. Selecting this check box also sets the deploymentDescriptor build descriptor option to the name of the deployment descriptor. On the Projects tab of the EGL Settings page. select Create an EGL service deployment descriptor.7. Related concepts “Introduction to EGL projects” on page 70 “Contents of an EGL application” on page 67 This topic describes the artifacts found in a typical EGL application. For more information on features. “Specifying database options at project creation” on page 189 72 EGL Programmer’s Guide .eglbld) that has the same name as the project. 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. 11. but include additional steps for the target runtime. To change those values later. Under Project location. 8. Choose a target runtime for the project in the Target Runtime list. select Show Advanced Settings and then click Next. 7. Creating an EGL Web project This topic covers how to create an EGL Web project. 5. Otherwise. 6. To specify a default database connection in that build descriptor. From the menu bar. If you want to configure other options for the project. Under EGL Project Types. It is best to choose a runtime now. In the New Project window. 3. change the build file that is created for you. select Web project. click Options. Under EAR Membership. 10. click File → New → Project The New Project window opens. such as adding it to an EAR application or adding additional facets. choose where the default build descriptor for the project will be located or created: v Create a new build descriptor means that EGL provides a new build descriptor and writes it to a new build file (extension .eglbld) that has the same name as the project. you must manually correct most of the references to that project. you can choose to place the project in your workspace. or the server that the project will be deployed to. Click Next. but you will need to choose a runtime before you can run the project on a server or deploy the project. select the Show All Wizards check box. you can change the target runtime later. The new project will use the EAR project’s target runtime. Type a name for the project in the Project name field. the project is not added to an EAR project. Click Next. If you do not seeEGL Project Wizard. the new EAR and EGL Web Contents of an EGL application 73 . as is the default.“Renaming an EGL project” on page 75 If you rename an EGL project. v Use the build descriptor specified in the EGL preferences means that EGL points to a build descriptor that you created and identified as an EGL preference. v Select an existing build descriptor enables you to specify a build descriptor from those that are available in your workspace. the new project will be added to that EAR project. v If you select the Add project to an EAR check box and choose an existing EAR project in the EAR Project Name list. You are not required to choose a runtime right now. To set up a new EGL Web project: 1. The steps for creating an EGL Web project are similar to those for creating an EGL project. 2. 4. expand EGL and click EGL Project Wizard. 9. You can add the new project to an EAR project later. Under Build Descriptor Options. regardless of your choice of runtime on the previous page. click Finish. specify whether to include the project as a module within an Enterprise Application Resource (EAR) project in the workspace: v If you clear the Add project to an EAR check box. or you can choose a different location. v If you select the Add project to an EAR check box and type a name for a new EAR project in the EAR Project Name list. select the check boxes for the additional features to include in the project. 19. Click Finish. 15. Related concepts “Introduction to EGL projects” on page 70 “Contents of an EGL application” on page 67 This topic describes the artifacts found in a typical EGL application. if any. the EAR Project Name field is disabled. type the name for the generated code folder. also called RCP projects. you can click Finish to complete the process and create the project with the default options. On the Project Facets page. which the same as the project name. see “Contents of an EGL application” on page 67 74 EGL Programmer’s Guide . 18. Related tasks “Creating an EGL project” on page 71 This topic covers how to create an EGL project. The default name is src. For more information on features and facets. select any facets that you may want to add to your project or select a preset facet configuration. In the Context Root field. In the Java Source Directory field. “Adding JSF component interface support to an EGL Web project” on page 464 “Adding Web transaction support to an EGL Web project” on page 562 Creating an EGL plug-in project EGL plug-in projects. In the Content Directory field. v If you selected a target runtime that does not support EAR projects on the previous page. 14. type the name for the Web content folder. are useful for Console UI applications that you want to run in rich client platform (RCP) mode. See “Features and facets of EGL projects” on page 76. 17. also called RCP projects. By default. the name of the new EAR project is the name of the EGL Web project with the suffix EAR. Click Next. For more information on the files in an EGL plug-in project. 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. see “Features and facets of EGL projects” on page 76. The default name is WebContent. 12. are useful for Console UI applications that you want to run in rich client platform (RCP) mode. select Create an EGL service deployment descriptor. Under EGL Project Features Choices. type a name for the root folder of the project when the project is deployed to a Web server or accept the default. “Creating an EGL plug-in project” EGL plug-in projects. 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. After you have filled out the information on the first page. If you want an EGL deployment descriptor in the project.projects will both use the runtime selected in the Target Runtime list on the previous page. 20. or click Next to continue setting the remainder of the options. These instructions continue with the remainder of the options. 16. You must still set the deploymentDescriptor build descriptor option to the name of the deployment descriptor before the project will use the new deployment descriptor. 13. “Console UI modes” on page 529 EGL supports three modes in which you can run Console UI applications: Swing. Enter a name for the project in the Project name field. you must manually correct most of the references to that project. 2. If you select this check box. Converting a project To convert an EGL project or an EGL Web project to an EGL plug-in project. or Console UI. From the menu bar. v EGL corrects the . 6. In the Rename Java Project window. The three modes have different abilities. “Creating an EGL Web project” on page 73 This topic covers how to create an EGL Web project. expand EGL and click EGL Project Wizard. 3. 2. See “Creating an EGL project” on page 71. 7. To rename an EGL project: 1. is a style of user interface similar to that used on a UNIX-based program that interacts with a character-based terminal. Fill in the remainder of the options for your project. right-click the project and click Refactor → Rename. Click Next. Under EGL Project Types. If you do not seeEGL Project Wizard. click File → New → Project. 8. “Building EGL Console User Interface applications” on page 513 Console User Interface. In the Project Explorer view. Curses. right-click the project in the Project Explorer view and then click Convert to EGL Plug-in Project. 3. In the New Project window. and rich client platform (RCP). select the Show All Wizards check box. Renaming an EGL project If you rename an EGL project. but in general a Console UI application behaves the same way in each mode. 5.eglproject file to point to the default build descriptors for the renamed project. 4. Click Next. The New Project window opens. Contents of an EGL application 75 . click Finish. Related tasks “Creating an EGL project” on page 71 This topic covers how to create an EGL project. EGL will make the following changes in addition to renaming the project itself: v EGL corrects the value of the genProject build descriptor option to the new name of the project. select RCP Project. type a new name for the project.Creating a new project 1. When you are finished. The remainder of the options are the same as those for an EGL project. Related concepts “Contents of an EGL application” on page 67 This topic describes the artifacts found in a typical EGL application. Select the Update references check box. 4. added through features and facets. Click Preview to see the changes that will be made as a result of renaming the project. although there is rarely any reason to remove a feature. EGL with BIRT report support Select this feature if you want to create BIRT reports based on data in the project. Click EGL Project Features. You can specify features at project creation or add features to a project later. “Renaming parts” on page 120 You can use the refactoring function of the workbench to rename parts and correct references to those parts. v References to files in the project. You must manually correct any other references to the new project name. In the Project Explorer view. make sure you are using the correct type of EGL project. The check boxes under EGL Project Features Choices are the features that you can apply to your project: Create an EGL service deployment descriptor Select this feature if the project contains programs that are available as services. To add features at project creation. Features and facets of EGL projects EGL projects can have additional abilities. see “Creating an EGL project” on page 71. After you add a feature to a project. 5. Related concepts “Introduction to EGL projects” on page 70 “Contents of an EGL application” on page 67 This topic describes the artifacts found in a typical EGL application. To complete the process. you cannot remove it. “Renaming a source file” on page 91 You can use the refactoring function of the workbench to rename source files and correct references to those files. 76 EGL Programmer’s Guide . The Properties window opens. follow these steps: 1. such as build files used in other projects. To add a feature to an existing project. right-click the project and then click Properties. v How the project is shared in a source code repository. Related tasks “Creating an EGL project” on page 71 This topic covers how to create an EGL project.v For Program parts within an EGL plug-in project. EGL corrects the reference to the program in the plugin. Features EGL project features add support for a particular behavior or type of project. 2. if you do not see a particular feature as an option for your project. click OK. The features that a project can have depend on the type of project.xml file. See “Editing the build path” on page 84. including: v References to the project in other projects’ EGL build path. Select the check boxes next to the features that you want to add to your project. EGL projects support the following features: Table 25. with Contents of an EGL application 77 . Click Window → Preferences. If you selected a feature as a default. 3. The Preferences window opens. 4. which in this context are exclusive to EGL projects. Click EGL. Features and projects Feature Jasper report support BIRT report support EGL with LDAP support EGL project Yes Yes Yes EGL Web project No Yes Yes EGL plug-in project Yes Yes Yes EGL portlet project No No ? For more information. You can also choose the features that are applied to your new EGL projects by default: 1. EGL with LDAP support Select this feature if you want to add files to your project that let you retrieve security information from an LDAP compliant server. Unlike EGL project features. EGL with low-level MQ API support Select this feature if you want to access message cues using API calls rather than EGL statements like get and add. This feature is not available in Web projects. You will find information about default features later in this section. For more information about what the features do. see the individual topic that explains how to add the feature to your project. see the related links at the end of this topic. Click OK. project facets can be applied to any project that behaves as a J2EE module. If a check box is already selected. Under Default EGL Project Features Choices. that feature has already been added to the project and you cannot remove it. select the features to you add to each new project by default.EGL with Jasper report support Select this feature if you want to create Jasper reports based on data in the project. 2. 3. it will be grayed out on the individual project Properties window. Facets Facets define characteristics and requirements for projects in the J2EE framework. EGL with i5/OS® objects support Select this feature if you want to be able to access data queues or other objects in the iSeries environment. some facets can be removed from a project. The Project Facets window opens. you can add facets at project creation or add them to an existing project. 5. The Preferences window opens. 7.certain restrictions. For example. The list shows the facets currently in the project. v The currently selected facets and their version numbers limit the other facets shown in the list. The Properties window opens. Click Finish. You can also choose a preset combination of facets from the Configurations list. ClickAdd/Remove Project Facets. facets have version numbers. Unlike project features. In the Project Explorer view. Click Window → Preferences. Like project features. You can find out more about the requirements and limitations for each facet by right-clicking the facet name and then clicking Show Constraints. 2. see Project Facets. For more information on the EGL-specific facets. Click Project Facets. select the check boxes next to the facets tat you want this project to have. if the project contains the Dynamic Web Module facet. Like project features. Follow these steps to add a facet to an existing project: 1. facets can depend on certain project types. If you want to limit the project so that it will be compatible with one or more runtimes. 8. select the facets that you want to be added to each new EGL Web project by default. Only the facets that are compatible with all selected target runtimes are shown. To remove a facet. the EJB Module facet is not listed because these two facets cannot be in the same project. click the Show Runtimes button and select the runtimes that you want the project to be compatible with. 9. Project features do not have version numbers. Click EGL. 6. and facets can depend on the presence or absence of other facets and specific version numbers of those facets. 3. Click OK. 3. 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. clear its check box. you can add features only to EGL Web projects and EGL Web projects that have been converted to EGL plug-in projects. Therefore. You can also choose the facets that are applied to your new EGL Web projects by default: 1. within EGL. 4. In the Project Facets window. right-click the EGL Web project and then click Properties. Under Default EGL Web Project Facet Choices. see the individual topic that explains how to add the facet to your project. Choose a version number for the facet by clicking the current version number and selecting the version number from the drop-down list. Related tasks “Adding JSF component interface support to an EGL Web project” on page 464 78 EGL Programmer’s Guide . Also unlike project features. 2. Not all facets can be removed. For more information on facets in general. Share the following files. if you have one Do not share the following files in a repository unless you have a reason to do so: Contents of an EGL application 79 . You need to add support only once for each project. you must add support to your project. See “Importing and exporting projects” on page 81. Sharing projects This topic explains the options for sharing projects between computers. support is available for General and Plug-in projects. “Adding support for BIRT reports to a project” on page 553 Before your EGL code can create BIRT reports. including faces-config. as well as some of the possible problems in doing so. See “Sharing projects in a repository” on page 82. resolve conflicts. JSP files. and files in the Enterprise Application Resource project. 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. including the ability to synchronize changes. and collaborate on code. Do not share any files that can be generated from other files. This method is appropriate when you want to share a project a single time. share only the files that someone else needs to work with the project. “Accessing an LDAP-compliant server” on page 190 EGL provides a code sample that you can customize to retrieve security or other details from a server accessed by way of Lightweight Directory Access Protocol (LDAP). “Using direct MQ API calls” on page 240 The MQ API is a set of program interfaces used to request services from the message queue manager. web.xml. you must add support for Jasper reports to your project and add a Java compiler to your system’s path variable. such as CVS or Rational ClearCase®. This method provides the best results for development code for many reasons. “Accessing an LDAP-compliant server” on page 190 EGL provides a code sample that you can customize to retrieve security or other details from a server accessed by way of Lightweight Directory Access Protocol (LDAP). During this beta. and you do not need to remove support if you stop using BIRT reports. such as . v Exporting an EGL project to the local file system. 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.eglproject files v Files necessary for Web projects to run on a server.eglpath and .xml. Files to share Generally.“Adding support for Jasper reports to a project” on page 549 Before you can create reports with EGL and Jasper. see Derived resources.ir files found in the EGLBin folder v Output files generated from EGL source files. but .java files and . class files created from Java files and . including the . In EGL.v Derived files. (You may want to use the Navigator view to examine derived files because the Project Explorer view filters out some types of derived files. In the context of EGL Java generation. that file will no longer be marked as derived. Moreover.ir files created from the source files are derived. or if you are trying to diagnose problems with the derived files. clicking Properties and moving to the Info page. However. For more information on which files are considered derived and why you would or would not want to include them. the file is marked as derived. even if they are generated from EGL source files.ir files created from EGL source files are automatically marked as derived.) If the Derived check box on the file’s Properties window is selected. Including derived files increases the size of the artifacts that you share. v Make sure that the project can find imported parts in the new location. For example. these Java source files are still considered derived because they are created from EGL source files. 80 EGL Programmer’s Guide . such as EGL . dependencies and links within the projects can break as the projects are moved to different locations. You can see whether a file is marked as derived by right-clicking the file in the Project Explorer view or Navigator view. Possible errors When sharing projects. the workbench does not mark Java source files as derived.ir files.class files Regardless of the type of project. Related concepts “Introduction to EGL projects” on page 70 Related tasks “Importing and exporting projects” on page 81 The workbench includes several ways to import projects and files from your local file system and export them to your local file system. 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. 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 any source files use import statements to refer to other EGL parts. including derived files might not be useful because they can be regenerated and overwritten when the files are imported into another workspace. However. If you share a derived file and someone else checks out the file. you may want to share derived files if the person you are sharing the project with cannot generate the derived files. many sharing methods (including Project Interchange files and some types of repositories) do not retain the derived flag. The workbench maintains a flag on each file to specify whether the file is derived or not. such as . However. Derived files are generated from source files and are not original data. do not share derived files. v Verify that links between Web pages still work. if it has other projects in its build path. so it is usually unnecessary to share them. The Import window opens. See “Sharing projects” on page 79 for information on derived files. Derived files generated from source files and are not original data. 7. Importing and exporting individual files With the workbench. expand Other and click Project Interchange. Select the files that you want to export and select a location for the exported file or files. Follow these steps to export one or more of your projects as a Project Interchange file: 1. 4. select the name and location for the exported file. Click File → Export. 3. expand General and choose a format for your output files. If you want to include derived files in the exported file. 4. Under Select an export destination. The guidelines also cover some common problems you might encounter when sharing EGL projects. Under Select an import source. Follow these steps to import one or more of the projects in a Project Interchange file: 1. 5. expand Other and click Project Interchange. select the projects you want to import. select the check boxes next to the projects that you want to export in the Project Interchange file. Click Next. select the Include derived files check box. The Export window opens. 4. Click Next. Click File → Export. Click Next.“Sharing projects in a repository” on page 82 These general guidelines describe EGL files that you will most likely share in a repository or source-control system. so it is typically unnecessary to include them when sharing projects. Follow these steps to export individual files from your workspace to your local file system: 1. the same as they are within the workbench. On the Export Projects page. In the Export window. Click Finish. you can also import and export individual files as separate files or as a single archive file. Click File → Import. 2. making them appropriate for sharing entire projects at once. In the To zip file field. On the Import Projects page. v Archive File compresses files into an archive file and saves that archive file to your local files system. Importing and exporting with Project Interchange Project Interchange files are archive files that contain one or more projects. 2. 3. 2. 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. 5. 6. Contents of an EGL application 81 . These are some of the common formats: v File System exports files to your local file system as individual files. 3. Click Finish. 3. it is probably not derived. In general. they often lose their derived flags. if you check a UML model and a TPM file into a repository and then check them back out again. 4. share source files and build files but not derived files. Click Finish. 2. Also. Click Finish. (If you edit a file directly. Related concepts “Introduction to EGL projects” on page 70 82 EGL Programmer’s Guide . see “Sharing projects” on page 79. The guidelines also cover some common problems you might encounter when sharing EGL projects. v Archive File extracts one or more files from an archive file and imports those files into the workspace. To import files into your workspace. Follow these steps to import individual files into your workspace from your file system: 1. the files in the repository are limited to only those necessary for the application. Related concepts “Introduction to EGL projects” on page 70 “Sharing projects” on page 79 This topic explains the options for sharing projects between computers. This way. 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.) For a discussion of derived files in the context of EGL. Click File → Import. Related tasks “Sharing projects in a repository” These general guidelines describe EGL files that you will most likely share in a repository or source-control system. Sharing projects in a repository These general guidelines describe EGL files that you will most likely share in a repository or source-control system. the workbench might not know that the two are associated. v Checking files into a repository can break connections between files. The guidelines also cover some common problems you might encounter when sharing EGL projects. when you share projects in a repository. you must first have a project to put the new files in. 5. files that are created from other files. be aware of these possible problems: v If derived files are checked into a repository. The way that you share your projects in a repository or source-control system depends on the type of repository or source-control system. see Linking a UML model to an existing TPM file. the projects are subject to the same potential errors as described in “Sharing projects” on page 79. For information on this problem. In the Import window. v When sharing projects in a repository. For example. These are some of the common formats: v File System imports one or more files directly into a project in your workspace. select the type of file you want to import.5. Click Next. In this case. as well as some of the possible problems in doing so. files that you normally wouldn’t check into a repository may appear to need to be stored in a repository. For example. the effective build path for project C is as follows: C.“Sharing projects” on page 79 This topic explains the options for sharing projects between computers. the source folders of the current project are usually the first items in the build path. D. You can also choose to export a project or source folder in your build path. in the build path for project D. so you might need to import the part to bring it into scope. You could copy the source file from project A into project B. you can use the Record part in project B as though the definition were in project B. Project C can use project E. which lists other EGL projects that you want to use in the current project. because project E is exported along with project D. project D can use project Z. E. See Name resolution in an expression. 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. D. Y v Project D D. The EGL build path also provides a way for validation to flag unknown parts and functions. Related tasks “Importing and exporting projects” on page 81 The workbench includes several ways to import projects and files from your local file system and export them to your local file system. is not exported along with project D. but that would mean duplicating the file. you must make that project available at run time. Instead. take the following project build paths: v Project C C. See “Editing the build path” on page 84. you can add project A to the build path of project B. For this reason. Y In this case. to allow your project to use parts in another project at run time. Z If. you choose to export project E but not project Z. Contents of an EGL application 83 . for example. In this case. 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. suppose project A contains a Record part and you want to create a variable based on that Record part in project B. For example. If you are generating to Java. However. however. the exported project or source folder is available to all projects that refer to the current project. project C cannot use project Z because Z. Scoping rules still apply. 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. as well as some of the possible problems in doing so. the EGL build path enables content assist to find other parts and insert correct import statements. The EGL build path EGL projects contain a build path. Then. E. because Z is in D’s build path. complete the following steps: 1. distributed build function of the generator prepares the output. the workbench prepares the output. To handle all the projects at once. 2. 3. you must be careful to avoid circular references. See the EGL Generation Guide for more information on generating in the SDK. Details for generating source code are located in the EGL Generation Guide. the build path information is stored in the . select the project and click the Up and Down buttons. Related tasks “Editing the build path” Building projects To build EGL output for Java programs. v To export a project. follow these steps: 1. which is a list of operating-system directories that are searched when the EGL SDK attempts to resolve a part reference. 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.” In general. 5. Click the check box beside each project that you want to add to the project’s build path. 4. Select the EGL Build Path properties page. see “Editing the build path. click the Order and Export tab and do as follows: v To change the position of a project in the build-path order. the build path is determined through the command-line argument eglpath. To add or remove projects in the build path. This step is done automatically unless you set the buildPlan or prep build descriptor options to no. or to set exporting for a project on the build path. Prepare the generated output. right-click a project that you want to link to other projects and then click Properties.When working with multiple EGL projects. build paths that make an infinite loop. that is. To include projects in the EGL build path. If you are generating to Java and want to use parts in a referenced project at run time. You can either 84 EGL Programmer’s Guide . In the Project Explorer view. you should be careful not to create packages with identical names in two different projects. A list of all other projects in your workspace is displayed in the Projects tab. Related tasks “Editing the build path” Editing the build path See “The EGL build path” on page 83 for information on the build path. select the related check box. you must make the referenced project available at run time. Also. if you generate output code using the EGL SDK. If you generate into a directory. 2.eglpath file. Click OK.eglpath file except that you cannot export source folders with the eglpath argument as you can with the . The eglpath argument behaves much like the . However.eglpath file in the root of the project. To put the projects in a different order or to export any of them. click the Select All or Deselect All button. The Properties window opens. select the check box next to the project that you want to export. 6. In the JAR file field. Click Add external JARs. share variables. 12. After building Project2. as opposed to the build path. Under Select the resources to export. 2. 8. it finds errors in parts A and C because it cannot resolve references to parts B and D. A key concept here is project cycles. Click Add. Follow these steps to add a referenced project as a JAR file: 1. click Java Build Path. which EGL maintains. 2. In the Properties window. 5. Click OK. Go to the Libraries tab. packages. 3. Right-click the project in which you want to use the referenced project and then click Properties. Select the Java Build Path properties page. If EGL builds Project1 first. click Projects tab. set the location for the JAR file. 10. 5. right-click a project that you want to link to other projects and then click Properties. 4. 4. In the Project Explorer view. B depends on C. The Properties window opens. assume that Project1 contains parts A and C. or you can add the referenced project to your project as a JAR file. and files Parts The Eclipse build order The build order is an Eclipse concept. A depends on B. Select the check boxes next to the projects that you want to add and then click OK. which Contents of an EGL application 85 . Select the JAR file that you exported and click Open. Related reference EGL projects. Click Next. which lists other EGL projects that you want to use in the current project. A project cycle involves two or more projects with mutual dependencies. To add a project to the Java build path of your project: 1. and C depends on D. expand Java and click JAR file. On the Java Build Path page. Right-click the project that you want to use in your project and then click Export. For example. and Project2 contains parts B and D. 11. 9. or call each other’s programs. Eclipse maintains a build order for projects that share code (such as record definitions). 6. Related concepts “The EGL build path” on page 83 EGL projects contain a build path. In the Export window. Click OK again. 7. Click Finish. 3.add that project to the Java build path of the current project. each new EGL project has a source folder named EGLSource. EGL attempts to move projects that are involved in cycles to a more optimal spot in the build order. and allows EGL to build all the projects in a single pass. EGL builds Project1 again to resolve the errors in A and C. “The EGL build path” on page 83 EGL projects contain a build path. You can also use the Build Order preference page to revert changes introduced in the build order by the optimization operation. which lists other EGL projects that you want to use in the current project. You can add and remove source folders as necessary to organize your code at high levels. which EGL generates using the . EGL projects have only one source folder and the packages within that source folder provide the organization. By default. you are using the Eclipse workbench. Changing these preferences manually may cause build errors. When you click Project → Optimize EGL Project Build Order. The value of this field limits the number of times the build will cycle through the projects. when you are working with EGL. If there are project cycles in the workspace.eglpath file (see “The EGL build path” on page 83). the build may terminate before resolving all errors. in which users perform work by pointing and clicking objects on the screen as well as by typing code. Related tasks “Creating source folders” on page 87 “Creating EGL source files” on page 90 The creation process is essentially the same for most EGL source files. Eclipse does not take project cycles into account. 86 EGL Programmer’s Guide . You can change the Max iterations when building with cycles field on the Build Order preferences page. EGL may be able to modify the build order to improve workspace build times. Related concepts “Using EGL with the Eclipse IDE” on page 1 The Eclipse IDE offers a graphical user interface (GUI) called the workbench. Related concepts “Contents of an EGL application” on page 67 This topic describes the artifacts found in a typical EGL application.produces no errors because A and C have already been built in Project1. the order that Eclipse determines is the most efficient. You can create EGL packages only within an EGL source folder. If the workspace contains no cycles. Eclipse determines the build order by asking each project for its dependencies. and EGL generates output code only for files within a source folder. If this value is too low. You can manually change the build order through the workspace preferences (Window → Preferences → General → Workspace → Build Order). However. In this way. Source folders EGL source folders contain EGL packages and files. so it is worth taking a minute to look at the tools in the workbench. but generally. Specify a name for the folder in the Folder name field. In the Project name field. specify the project to contain the new source folder. The package statement in the file. Likewise. “Source folders” on page 86 Related tasks “Creating an EGL project” on page 71 This topic covers how to create an EGL project. Because files in the default package cannot be shared by parts in other packages or projects. Technically speaking. The parts in an EGL source file all belong to the same package. but two different packages can each have a part with the same name.Creating source folders After you create a project in the workbench. click File → New → EGL Source Folder. Package names are case sensitive. even if those packages are in different projects or source folders. you should prevent conflicts between packages by not creating packages with the same name. if any. “Creating EGL source files” on page 90 The creation process is essentially the same for most EGL source files. The New Source Folder window opens. Click Finish. it is best to specify a package statement. For more information on naming conventions for packages. If you do not specify a package statement. see package. Packages prevent name conflicts by separating files into different contexts. specifies the name of that package. 4. From the main menu. Two parts with the same name cannot be defined in the same package. but it can be easier to think of a package in the same way as a folder or directory on your local system. Related reference Naming conventions Introduction to EGL packages Packages work like folders: they organize source files and prevent naming conflicts. To create a folder for grouping EGL files. a package is a named collection of related parts. you can create one or more folders within that project to contain your EGL files. the parts are stored in the root of the source folder and are considered to be in the default package. 3. 2. Contents of an EGL application 87 . Related concepts “Contents of an EGL application” on page 67 This topic describes the artifacts found in a typical EGL application. complete these steps: 1. companyb. program testProgram2 type BasicProgram function main() myVariable2 com.firstpackage. For example. you can use the part as though it were in the current package.thirdpackage. program testProgram3 type BasicProgram function main() myVariable3 myRecordPart. but this time it imports the part first: package com. Sometimes. end end Record myRecordPart type BasicRecord field1 int. the following Program part uses the Record part from the previous example: package com. end end As shorthand.companyb. field2 string.″ For example. import com.secondpackage. end end Note that the import statement uses the package path to the part and the part name. Related concepts “Contents of an EGL application” on page 67 This topic describes the artifacts found in a typical EGL application. importing a part in this way is called ″bringing the part into scope. not the source file name. specify the complete location of the part within its package. you can use the import statement to tell EGL that you want to use the part in the source file. For more information on import.companyb.myRecordPart. without specifying the complete location of the part within its package each time you use it.Working with packages When you want a part to reference another part that is in the same package. program testProgram type BasicProgram function main() myVariable myRecordPart.myRecordPart. the following Program part again uses the Record part defined earlier.companyb. The following example shows two parts in the same package: a Record part and a Program part that uses the record part: package com.firstpackage. see “Import and use statements” on page 124.companyb.firstpackage. Related reference package Scope 88 EGL Programmer’s Guide . you do not need to specify the location of the second part. If you import a part in this way. end When you want a part to reference another part that is in a different package. Creating an EGL package An EGL package is a named collection of related source parts. use the build parts editor provided in the workbench to work with build parts and build files. Source files Source files contain EGL source code in units called logic parts and data parts. To create an EGL package. See “Introduction to EGL parts” on page 95. 2. This type of file contains build parts such as build descriptor parts. The Source folder field might be pre-populated depending on the current selection in the Project Explorer. except that you can have only one generatable part in a source file. In the workbench. EGL also uses deployment descriptors in service applications and service client applications. Build files Build files contain information EGL uses to generate and deploy applications. However. click File → New → EGL Package. and resource associations parts. “Creating an EGL project” on page 71 This topic covers how to create an EGL project.egl and are written in EGL source format. 3. Click the Finish button. type the name of the EGL package. In the Package name field. Introduction to EGL files The two most common types of files in an EGL project are source files and build files. Identify a project or folder to contain the package. 5. Build files are written in Extensible Markup Language (XML) and have the extension . Source files have an extension of . 4. You can have any number of logic parts and data parts in any one source file.eglbld. Whenever possible. You must create a project or folder if you do not already have one.“Import and use statements” on page 124 Use the EGL import and use statements to expand the visibility of code elements. do the following: 1. Deployment descriptors Deployment descriptors contain information that describes how EGL services will be made available to other applications and how EGL applications will find Contents of an EGL application 89 . linkage options parts. it is possible to edit a build file with a text editor or XML editor. Related concepts “Introduction to EGL projects” on page 70 Related tasks “Creating an EGL Web project” on page 73 This topic covers how to create an EGL Web project. Select the project or folder that will contain the EGL package. click Show All Wizards. You can learn about these options in the appropriate topic for the specific part: v DataTable part 90 EGL Programmer’s Guide . Creating EGL source files The creation process is essentially the same for most EGL source files. click Browse and locate the package name. In the Package field. File names that contain EGL parts must conform to EGL part naming conventions. The file name must be same as the part name.egldd and open in the deployment descriptor editor. For example. EGL creates it for you. In the EGL source file name field. If the package name you enter here does not exist. If you do not see the part type you are looking for. click File → New → Other If you have not yet created a project or folder. From the Select a wizard window. You can change this name to that of another existing project or folder if you chose the wrong one initially. The following instructions cover any of these parts: v DataTable v EGL Source File (generic wizard) v FormGroup v Interface v JSF Handler v Library v Program v Report Handler v Service Click Next 3. select a package to hold the new file. see Naming conventions 6. See “Creating an EGL project” on page 71 2. Related reference Naming conventions “Contents of an EGL application” on page 67 This topic describes the artifacts found in a typical EGL application. Some wizards require further information. assume your file will define a program named checkCustomerBalance: Program checkCustomerBalance type BasicProgram . v With a project or folder selected in your workspace.services provided by other applications. end In this case you must name the file checkCustomerBalance. EGL will add the . You can do this in one of two ways: v Right-click a project or folder in your workspace and click New → Other. EGL shows the project or folder you previously selected...egl extension to file name automatically. type a name for the new file. 5. EGL displays a new part wizard. For more information. Deployment descriptor files have an extension of . You must specify a project or folder when you create an EGL source file. and click the type of part you want to create. 4. you must do so before creating parts. To ensure that you use the correct name of an existing package. In the Source folder field. expand EGL. Follow these steps to create a source file that contains an EGL part: 1. 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. EGL updates references to the file in the faces configuration file. In the Rename Part window. click Refactor → Rename. right-click the generatable part in the Outline view. 6. 3. If you clear the Update references check box. select this check box. type a new name for the file. 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. but it does not change the name of the JSP file. Contents of an EGL application 91 . v For JSP files that are controlled by a JSF Handler. or Parts Reference view 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. 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. EGL changes the code that calls that program to use the new name.v “Introduction to Library parts” on page 110 v “Transfer of control across programs” on page 251 v “Overview of service-oriented architecture (SOA)” on page 475 7. 4. Parts List view. The Rename Part window opens. EGL searches the build path for references to that part and changes the references to match the new name of the part. In one of the following places. With refactoring. 5. you can rename EGL source files or JSP files that are controlled by a JSF Handler. You can click Preview for a list of the changes EGL will make if you proceed. following EGL naming conventions. 1. Click OK. Click Finish. v For files that contain a JSF Handler. EGL updates the view property of the JSF Handler to refer to the new JSP file. From the pop-up menu. EGL will not search other files for references to change. For example. Related reference Naming conventions Renaming a source file You can use the refactoring function of the workbench to rename source files and correct references to those files. Related concepts “Introduction to EGL files” on page 89 Related tasks “Creating an EGL project” on page 71 This topic covers how to create an EGL project. if you rename a file that contains a called program. In most instances. place the cursor on the generatable part’s name in the EGL editor and right-click 2. v For files that contain a JSF Handler. In the Project Explorer view. Moving a source file You can use the refactoring function of the workbench to move source files and correct references to those files. Moving a file makes the following changes: 92 EGL Programmer’s Guide . If you clear the Update references to the moved elements check box. In most instances. if you renamed myWebPage. You can click Preview for a list of the changes that EGL will make if you proceed. You must search for changes and update the files manually. In the Move window.v For Program parts within an EGL plug-in project. 2. Suppose that you have a line of code that passes control to a JSF Handler like this: forward to "myWebPage". Related concepts “Generatable parts and non-generatable parts” on page 96 EGL parts can be generatable or non-generatable. “Renaming parts” on page 120 You can use the refactoring function of the workbench to rename parts and correct references to those parts. You might still need to check for other changes caused by refactoring. 4. you must manually correct most of the references to that project. “Renaming an EGL project” on page 75 If you rename an EGL project.xml file. right-click the file and then click Refactor → Move. EGL does not change labels used with the forward statement. Related tasks “Moving a source file” You can use the refactoring function of the workbench to move source files and correct references to those files. 5. EGL will not search other files for references to change. With refactoring. “Introduction to EGL files” on page 89 “Introduction to EGL parts” on page 95 Parts are the building blocks of EGL applications. The Move window opens. 3. 1. select a destination for the file. Click OK. select this check box. “Moving parts” on page 121 You can use the refactoring function of the workbench to move parts between source files and correct references to those parts. You can create a new package for the file with the Create Package button. For example. In this case. EGL does not change this forward statement to reflect the new label for the page. you can move EGL source files to a new location in an EGL package in your workspace. EGL corrects the reference to the program in the plugin. “Deleting a source file” on page 93 You can delete a source file using the workbench. 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. v For Program parts within an EGL plug-in project, EGL also corrects the reference to the program in the plugin.xml file. You might still need to check for other changes that refactoring causes. Related concepts “Introduction to EGL files” on page 89 Related tasks “Renaming a source file” on page 91 You can use the refactoring function of the workbench to rename source files and correct references to those files. “Renaming parts” on page 120 You can use the refactoring function of the workbench to rename parts and correct references to those parts. “Moving parts” on page 121 You can use the refactoring function of the workbench to move parts between source files and correct references to those parts. “Deleting a source file” You can delete a source file using the workbench. Deleting a source file You can delete a source file using the workbench. To delete a source file, select it in the Project Explorer view and: v Press Delete v Click Edit → Delete v Right-click the file and then click Delete In most cases, EGL does not correct references to the file as it does when you rename or move a source file. However, if the project is an EGL plug-in project and the file you are deleting contains a Program part, EGL removes the reference to that program in the plugin.xml file. Related concepts “Introduction to EGL files” on page 89 Related tasks “Renaming a source file” on page 91 You can use the refactoring function of the workbench to rename source files and correct references to those files. “Moving a source file” on page 92 You can use the refactoring function of the workbench to move source files and correct references to those files. Contents of an EGL application 93 “Renaming parts” on page 120 You can use the refactoring function of the workbench to rename parts and correct references to those parts. “Moving parts” on page 121 You can use the refactoring function of the workbench to move parts between source files and correct references to those parts. Creating EGL build files To create an EGL build file, complete these steps: 1. Identify a project or folder to contain the file. If you do not already have a project or folder, you must create one. 2. From the main menu, click File → New → EGL Build File. 3. From the Select Container window, type the project or folder that will contain the EGL build file in the Enter or select the parent folder field or use the directory tree to select the location. 4. Click Advanced to link the file to an existing file in the file system. Type the name of the file to be linked in the text box or click Browse to locate the file. Click Variables to work with the variables in the file that you specify. 5. Type the name of the build file in the File name field. 6. Optionally, you can click Next to select EGL parts to populate the file. 7. Click Finish to create the file without populating it with an EGL part. An extension (.eglbld) is automatically appended to the end of the file name. The EGL build file is displayed in the Project Explorer view and automatically opens in the default EGL editor. Related concepts “Introduction to EGL projects” on page 70 “Introduction to EGL parts” on page 95 Parts are the building blocks of EGL applications. Developing EGL applications Enterprise Generation Language (EGL) is a programming language that you can use to focus on business problems instead of software technologies. Within the Rational development environment, you can use EGL wizards and other tools to write complex applications with minimal effort. Creating a deployment descriptor The EGL deployment descriptor provides service-binding detail when you are generating a service, as well as service-binding detail when you are generating a logical unit (program, library, handler, or service) that invokes a service. The EGL deployment descriptor is distinct from JEE deployment descriptors. For information on JEE deployment descriptors, see Defining JEE enterprise applications (EARs). 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: 94 EGL Programmer’s Guide Click File → New → Other. The New window opens. In the New window, expand EGL and click Deployment Descriptor. Click Next. 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. 1. 2. 3. 4. 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 “Overview of service-oriented architecture (SOA)” on page 475 Related tasks “Adding Web service deployment information to the deployment descriptor” on page 496 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. “Calling a remote service” on page 485 You can call remote services from your EGL logic parts. “Exposing a service to other applications” on page 493 Your 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 97. 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 and VGUIRecords, which specify the information that you Contents of an EGL application 95 want to appear on the user interface. Others are defined with a stereotype of a logic part, as is the case with JSFHandlers, ReportHandlers, and VGWebTransactions. Other user interface parts are parts in their own right, such as FormGroups. Build parts Build parts control the generation process and set how the application will behave at run time. The most commonly used kind of build part is the build descriptor part, which contains a list of build descriptor options to define how the EGL code will be generated to the output language. Other build parts control how the application will work with other applications and resources at run time. Deployment descriptors Deployment descriptors contain information that describes how EGL services will be made available to other applications and how EGL applications will find services provided by other applications. Related concepts “Contents of an EGL application” on page 67 This topic describes the artifacts found in a typical EGL application. Related reference Parts 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 of all stereotypes except VGWebTransaction v Library parts of all stereotypes v Handler parts of all stereotypes v Service parts v v v v v v DataTable parts Record parts with the stereotype ConsoleForm Record parts with the stereotype VGUIRecord Program parts with the stereotype VGWebTransaction FormGroup parts 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. 96 EGL Programmer’s Guide v The generatable part must have the same name as the source file, minus the source file’s .egl extension. The case of the names must match. EGL deployment descriptors are considered generatable even though they do not have a part name separate from the file name. Related concepts “Introduction to EGL parts” on page 95 Parts are the building blocks of EGL applications. Introduction to data parts Data parts define a structure that stores one or more pieces of data. Data parts form the basis for a variable that you can use in a logic part. These are the three most common types of data part: Primitives EGL supplies simple data types similar to those found in most other programming languages, such as numbers, dates, characters, and large objects. Primitives form the basis for more complex data types. Here are two examples of variables created from primitives: myInteger int; myString char(50); You can find a complete list of primitives in ″Primitive data types″ in the EGL Language Reference. See “Commonly used primitives” on page 98 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 Contents of an EGL application 97 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 102. Related concepts “Contents of an EGL application” on page 67 This topic describes the artifacts found in a typical EGL application. “Other data parts” on page 102 These 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 100 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 be primitives, data items, or other records. Related reference Primitive data types DataItem part Record part 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 the EGL Language Reference. Primitive numeric types: The following numeric primitives are the most often used: INT This is a basic four-byte integer, the workhorse of internal calculations, used also for key numbers, stock quantities, or anywhere else that a whole number is appropriate. The range of values you can put in an INT is -2,147,483,648 to +2,147,483,647. DECIMAL Use decimals for any numbers that need a decimal point—currency amounts, for example, or employee hours (if you allow fractions). When you declare a 98 EGL Programmer’s Guide 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. Contents of an EGL application 99 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 97 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. “Contents of an EGL application” on page 67 This topic describes the artifacts found in a typical EGL application. Related reference Primitive data types Date/time masks and format specifiers 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 be primitives, data items, or 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); 100 EGL Programmer’s Guide 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, RelativeRecord, and CSVRecord, 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: Contents of an EGL application 101 record 10 10 10 end structRec1 type BasicRecord field1 int; field2 int; field3 int; Varying the level numbers creates substructures within the record: Record CustomerRecord type BasicRecord 10 phoneNumber CHAR(10); 20 areaCode CHAR(3); 20 localNumber CHAR(7); end In this case, the fields areaCode and localNumber are subfields of the field phoneNumber. You can access the phoneNumber field to get the entire value of the field, or you can access the areaCode or localNumber fields to get a portion of the value held in the phoneNumber field. Structured records are limited to fields with fixed length. See ″Records″ in the EGL Language Reference for more information on the limitations and uses of structured records. Related concepts “Introduction to data parts” on page 97 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. Other data parts These data parts are not used as often as the others. FormGroup A form part, like a record, contains fields; like a record, each generally represents data from a single line of a database table. The difference is that a record provides a blueprint for storage inside a program, and a form provides a blueprint for displaying that information—either on a printer (print form) or on a 3270 screen or console window (text form). A FormGroup organizes a number of form prototypes for a particular program or for related programs. 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 102 EGL Programmer’s Guide 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 “Introduction to data parts” on page 97 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. “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. Related reference Primitive data types FormGroup part Dictionary part Dictionary parts contain lists of data that you can access via a key. For example, you can create a message handling facility that uses a library and a dictionary populated with keys and messages read from a database. DataTable part ArrayDictionary 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: Contents of an EGL application 103 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]; 104 EGL Programmer’s Guide see ″Arrays″ in the EGL Language Reference. end end SysLib. See Standalone function part."). Related concepts “Introduction to data parts” on page 97 Data parts define a structure that stores one or more pieces of data. for (i from 1 to stopNumber by 1) for (j from 1 to stopNumber by 1) printProduct(i. int2 int in) returns (int) sum int = int1 + int2. "gh"}.However. you cannot use a set-value block to assign more elements to the array than currently exist in the array: smallStrArray string[2]. Program A program is the simplest kind of logic part. return (sum). program multiplicationTable type BasicProgram stopNumber int = 7. j). Data parts form the basis for a variable that you can use in a logic part. execute EGL statements. see Functions. "cd". A function can receive parameters. The following example shows a simple program part: package programs.writeStderr("Printing multiplication table through " :: stopNumber). which are the basic unit of logic. Following is a simple example of a function: Function addIntegers(int1 int in. end function printProduct(int1 int in. and return a value to the function that called it. Introduction to logic parts Logic parts define a sequence of instructions. although it is possible for a function to exist outside of a logic part and thus behave like a logic part. function main() SysLib.writeStderr("Finished. end For more details. An EGL program must contain a function named main. The program can contain any number of other functions. which is the function that is invoked when the program runs. Most logic parts contain one or more functions. "ef". smallStrArray {"ab". i. //IndexOutOfBoundsException! Array has only 2 elements! For more details on arrays. Related reference Arrays The rules for an EGL array depend on the type of the array. int2 int in) Contents of an EGL application 105 . A function is not technically a logic part. A program in EGL behaves similarly to programs in many other programming languages. j int. end function subtractIntegers(int1 int in. a service part is a collection of functions. int2 int in) returns (int) return (int1+int2). JasperReport Jasper Report Handler parts control reports that are created by EGL within the Jasper Reports framework. Functions in a library part can be invoked in any order. an interface part merely describes another logic part. ExternalType parts are used to represent Java objects. BasicHandler BasicHandler parts are the simplest kind of Handler. In EGL. you can use interfaces to plan services or to represent services that your application will use. Instead of defining actual logic. An ExternalType part contains function prototypes that allow you to invoke the logic in the Java object. as the other types of logic part do. while the main function in a program always runs first.writeStderr(int1 :: "x" :: int2 :: "=" :: int1*int2). the service part is designed to enable applications outside the current run unit to use the functions. library myMathLibrary type BasicLibrary function addIntegers(int1 int in. The following example shows a simple library part: package libraries. end end Library A library part is a collection of functions and variables that are made available locally to other logic parts. Generally. JSFHandler JSF Handler parts control Web pages. See “Elements of a service-oriented application” on page 478 for more information and examples. you can create variables in EGL that refer to elements in another language. Interface An interface part is different from most logic parts because instead of containing functions or any executable code.SysLib. See “Elements of a JSF Web application” on page 389. you will use a Handler that is specialized for a type of interface. usually a service part. ExternalType With an ExternalType part. See “Elements of an EGL JasperReport application” on page 533. int2 int in) returns (int) return (int1-int2). end end Handler A Handler part is specialized to control a particular kind of user interface. See “Elements of a service-oriented application” on page 478 for more information and examples. Service Like a library part. it contains function prototypes. Also. an ExternalType 106 EGL Programmer’s Guide . Generally. but unlike a library part. even if the function has no parameters. enclosed in parentheses. functions are not EGL parts (see Standalone function part). such as a Web service.″ If the function does not have a return type. handler. or other service. A requester can be a local or remote program. BLOB. Service part Service parts provide requesters with access to the functions in the service. v An end delimiter. as described in ″return. For more about local variables. Contents of an EGL application 107 . Related concepts “Contents of an EGL application” on page 67 This topic describes the artifacts found in a typical EGL application. Each set of parameters corresponds to an argument that passes when the function is called by another function. it cannot return data and you cannot use the function in an expression where the function must have a value.part can contain variables that represent public variables in the Java object. v A return type. When you declare a function. The name main() is reserved for the top-level function that runs first when you start or call a program. library. Except for standalone functions. see Scope. a return type cannot be an ANY. The return type must be compatible with the data type of the receiving variable. A function contains a series of EGL statements. Handler part ExternalType part ExternalType parts map EGL to external language elements. Parameter modifiers Parameters correspond to the arguments that are passed to a function. A pair of parentheses must follow the function name. which describes the type of data that the function returns to the calling function. you can specify parameters. Interface part Interface parts provide access to a remote service. v EGL statements. Functions either contain the first executable code in the program or are called from another function. Parameters correspond in number. For information about function syntax. In a service. see Functions in the EGL Language Reference. each of which has meaning within the function only. Every program part must contain a function named main() that has no parameters or return type. v A set of local variables. or CLOB type. Functions can include the following elements: v A set of parameters. Introduction to functions Functions are the fundamental units in EGL logic parts. Related reference Program part Functions Library part Library parts support the sharing of functions and variables. See “Calling Java” on page 128 for an example. a value is assigned to the argument of the calling program. See Reference variables. and the calling function receives all changes to the parameter when the function ends. The function does not receive the argument value as an input. the following rules apply: v If you intend to use the record to access a file or database in the current function or in a function called by the current function. EGL pads the copied content with blanks to meet the specified length. if you change an element of an array without changing the original value of the parameter. a copy passes to the corresponding function parameter. When you specify a limited-length string as a function parameter whose modifier is out. You cannot specify the in modifier for a record that is used to access a file or database in either the current function or in a function called by the current function. When you specify in. 108 EGL Programmer’s Guide . but the calling function does not receive changes that are made to the parameter. out Use this modifier if the parameter is used as output from the function. If the argument is a record. Reference parameters point to a location where a value is stored. the calling program will detect the change. the length limit must be the same in the parameter and the argument. it is treated as if the modifier is in. Value parameters contain the value. Any value you assign to the parameter does not affect the value that the reference points to. If the argument is a reference type. When the function returns. If the argument is a literal or constant. you must specify the inOut modifier or accept that modifier by default. This is because the parameter still points to the same area of memory that the original argument points to. the parameter is initialized according to the rules described in Data initialization. However. If the argument is a literal or constant. For example.type. If the argument is a reference type. the function receives the argument value as input. The function receives the argument value as input. When you declare parameters. a null reference passes to the corresponding function parameter. v If the argument contains fewer characters than are valid in the parameter. an array is always a reference variable. the parameter is treated as if the modifier is in. EGL truncates the copied content to fit the available length. Any value you assign to the parameter updates the corresponding variable in the calling function. inOut Use this modifier if the parameter is used as both input to and output from the function. You cannot specify the out modifier for a record that is used to access a file or database in either the current function or in a function invoked by the current function. any text input is valid: v If the argument contains more characters than are valid in the parameter. When you specify a limited-length string as a function parameter whose modifier is in. and position to the arguments that you pass to a function. you must specify a parameter modifier: in Use this modifier if the parameter is used as input to the function. EGL does not permit two functions to have the same signature. This requires a different signature for each numeric type: mathLib. even if the functions have different signatures. end Return type The return type describes the data that the invoked function returns to the invoker.2)) . The return type must be compatible with the data type of the receiving variable. BLOB. EGL uses the signature to match function code to a function call. v The overloaded functions must be in the same part. as in the following example: function getCustomerBalance (custNo INT? inOut) returns (DECIMAL(7. The second parameter specifies a journal ID. as described in return. if both are serial records). Any value you assign to the parameter updates the corresponding variable in the calling program. the return type cannot be an ANY.v If the type of record is the same for the parameter and the argument (for example. but only if the inOut modifier is in effect.abs(inputVar BIGINT) You can create overloaded functions in the following circumstances: v The function cannot be a standalone function. and returns a value of the same type as the input. The two functions have the following signatures: sysLib. Overloaded functions An overloaded function has multiple function signatures for one function name. see sqlNullable. For example. If two parts contain functions with the same name. v Because the function signature does not include the return value.abs() function accepts a range of numeric types.abs(inputVar SMALLINT) mathLib. you can call the sysLib. For more information. the function writes to the system journal. jid SMALLINT in) In another example. You can use a question mark to indicate that a parameter is nullable. When multiple functions have the same name. you cannot have two functions that are identical except for the return value. the record-specific state information such as endOfFile status is available in the function and is returned to the caller. the mathLib. Many EGL system functions are overloaded. The signature of a function is the combination of the name of the function with the number and type of its parameters..audit(record BasicRecord in) sysLib. Contents of an EGL application 109 . it passes to the corresponding function parameter as a reference. In a service. If you call the function with a single parameter.audit(record BasicRecord in. or CLOB type.. you cannot use an unqualified reference to that function name. sqlNullable This modifier is available to relational database users.audit() function with one parameter or two.abs(inputVar INT) mathLib. The return value of the function is not part of its signature. If the argument is a reference type. If no match is found.During the generation process. For more information. the generator displays an invalid arguments error. EGL uses the following rules to resolve references to unqualified function names: 1. For example. If no match is found. the generator displays an ambiguous reference error. Related reference Standalone function part Functions Scope Reference variables Data initialization return sqlNullable Introduction to Library parts Library parts support the sharing of functions and variables. If more than one function matches the number of parameters. The following stereotypes are available as part of the core EGL package: BasicLibrary Contains EGL-written functions and values for runtime use in other EGL logic parts. locally running DLL (dynamic link library. You can access a Library part by direct calls to the shared Library functions or by direct references to the shared Library variables. because an INT is closer in size to SMALLINT. EGL cannot find multiple matching functions. EGL provides many system Libraries that contain common functions. This is the most common type of Library. EGL continues to step 4. You can also create your own Libraries of functions that you use frequently. EGL searches for the best match. also sometimes called a driver). because that causes a validation error. Related concept “Introduction to logic parts” on page 105 Logic parts define a sequence of instructions. the generator displays an ambiguous reference error. NativeLibrary Enables code migrated from Informix 4GL to invoke a single. The program uses stereotypes to specialize code for functions. EGL will pick the function with the INT parameter. one with an INT parameter and the other with a BIGINT parameter. If multiple matches are found. 4. If EGL cannot find such a match. see “BasicLibrary stereotype” on page 111. which are the basic unit of logic. Most logic parts contain one or more functions. EGL searches for a function with parameters that match the types of the arguments in the function call. 5. 2. If EGL finds matching function names in more than one container (logical part). 3. the generator displays an invalid arguments error. EGL continues to step 5. If no function matches. EGL searches for a function with parameters that are assignment-compatible with the arguments in the function call. if the argument is a SMALLINT and EGL finds two functions. Most 110 EGL Programmer’s Guide . A Library part is a generatable logic part with multiple entry points. EGL searches in the current scope for all functions with matching names. At run time. or constant declaration to keep the element from being used outside of the Library. The properties that are available depend on the stereotype of the Library. The following example shows a BasicLibrary part: Contents of an EGL application 111 . “BasicLibrary stereotype” The BasicLibrary stereotype identifies a Library part that contains EGL-written functions and values for runtime use in other EGL logic parts. which are the basic unit of logic. See Library properties and NativeLibrary properties. Handler. A loose type is a special case of primitive type that is available only if you want the parameter to accept a range of argument lengths. EGL loads the Library the first time you use it. The following rules apply to a BasicLibrary: v Any generatable logic part (Program. “NativeLibrary stereotype” on page 112 Customers migrating from Informix 4GL need the NativeLibrary stereotype to hold their C language subroutines. If a Library invokes another Library. Service. and unloads it when the run unit ends. An EGL Library is generated separately from the parts that use it. see “NativeLibrary stereotype” on page 112. For more information. or another Library) can reference the functions. variables. v Public Library functions (the default) are available outside of the Library and cannot have loose type parameters. the invoked Library remains in memory as long as the invoking Library does. variable. BasicLibrary stereotype: The BasicLibrary stereotype identifies a Library part that contains EGL-written functions and values for runtime use in other EGL logic parts. and constants of a Library without specifying the Library name if that logic part includes the Library in a use statement. You might do this when the element is used only by a function within the Library. Many properties that determine the behavior of your generated code are available to Libraries.developers never use the NativeLibrary stereotype. Related concepts “Introduction to logic parts” on page 105 Logic parts define a sequence of instructions. see Loose types. Related reference Library properties NativeLibrary properties The NativeLibrary stereotype provides additional properties to the standard set of Library properties. Most logic parts contain one or more functions. For more information. v Library functions cannot include the following statements: – converse – display – forward – show – transfer v You can use the private modifier on a function. end end Related concept “Introduction to Library parts” on page 110 Library parts support the sharing of functions and variables.I4GL. customerBalance BIN(9. p2 STRING in. The following example shows a NativeLibrary part: Library myNativeLibrary type NativeLibrary {callingConvention=CallingConventionKind. p5 ANY out) end Function entryPoint2( p1 FLOAT in. You cannot define statements in the EGL function. ANY out.package com. ANY in. customerName CHAR(25). p2 DATE in. p3 SMALLINT out) end Function entryPoint3( p1 p2 p3 p4 end end ANY in.customerName. myCustomer. Related reference Library properties Loose types NativeLibrary stereotype: Customers migrating from Informix 4GL need the NativeLibrary stereotype to hold their C language subroutines. Record CustomerRecord type SQLRecord customerNumber CHAR(6). myCustomerName CHAR(25) inOut) myCustomer CustomerRecord.2). This type of Library enables your EGL-generated Java code to invoke a single. p3 TIME in. and you cannot declare variables or constants anywhere in the Library. CLOB inOut) 112 EGL Programmer’s Guide . end Library CustomerLibrary type BasicLibrary // Function Declarations function getCustomerName( myCustomerNumber CHAR(6) in. locally running DLL written in the C language.customer. dllname="mydll"} Function entryPoint1( p1 INT sqlNullable in. get myCustomer. The purpose of each function in this Library type is to provide an interface to a DLL function.companyb.customerNumber = myCustomerNumber. p4 INTERVAL in. myCustomerName = myCustomer. Service function calls You can call a function from a service much as you would call a function from a library. or another service. see “Introduction to Interface parts” on page 114. To handle the connectivity. but you must first declare a variable based on the service: myEcho EchoString. When you want to consume a service. “BasicLibrary stereotype” on page 111 The BasicLibrary stereotype identifies a Library part that contains EGL-written functions and values for runtime use in other EGL logic parts. result STRING. There are restrictions on passing reference variables to remote service functions.returnString("Hello!"). handler. use the EGL deployment descriptor file. For more information about Interface parts. The requester can be a program. Related concepts “Introduction to Library parts” on page 110 Library parts support the sharing of functions and variables. result = myEcho. refer to the EGL Generation Guide. Introduction to Service parts Service parts provide requesters with access to the functions in the service. see the following files in the EGL Language Reference: v Use of properties files for displayable text v RUIPropertiesLibrary stereotype Related concepts Use of properties files for displayable text RUIPropertiesLibrary stereotype “Introduction to Library parts” on page 110 Library parts support the sharing of functions and variables. RUIPropertiesLibrary stereotype: When you are writing a Rich UI application. you create an Interface part. set up an Rich UI properties library (stereotype RUIPropertiesLibrary) if you want to retrieve displayable text from external files rather than hard-coding the text. The interface provides EGL with a list of the functions that the service provides. For details about the deployment descriptor file. and can be local or remote. see NativeLibrary properties. For details on this stereotype.For information on properties associated specifically with this stereotype. or how your application uses an external service. A requester is a program or other code that accesses the functions that are defined in a service. The deployment descriptor file describes how other applications can use a Service part from your application. library. Related reference NativeLibrary properties The NativeLibrary stereotype provides additional properties to the standard set of Library properties. Contents of an EGL application 113 . handler. Related concepts “Overview of service-oriented architecture (SOA)” on page 475 Accessing IBM i programs as Web services “Creating EGL source files” on page 90 The creation process is essentially the same for most EGL source files. EGL adds a function to the existing Service part that calls the called program. 2. such as a Web service. Creating a service to call a program If you have a called program in your project. “Creating a WSDL file from a Service part” on page 119 You can create a sample WSDL file as a point of reference to a Service part. 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. you can create a Service part to call that program. Introduction to Interface parts Interface parts provide access to a remote service. If you type a name for a new Service part. Related reference Interface part Interface parts provide access to a remote service. right-click a file containing an EGL called program part and then click EGL Services → Create Program Call Function. “Creating a service to call a program” If you have a called program in your project. Related reference Service part Service parts provide requesters with access to the functions in the service. In the Project Explorer view. A requester can be a local or remote program. 114 EGL Programmer’s Guide . or other service. In this context. You might want to create a service in this way to act as a wrapper for the called program. If you type the name of an existing Service part and then select the Update existing files check box. Related tasks “Creating EGL source files” on page 90 The creation process is essentially the same for most EGL source files. Click Finish. or other service.Related concepts “Introduction to Interface parts” Interface parts provide access to a remote service. handler. “Creating an Interface part from a Service or ExternalType part” on page 116 You can use other parts as a models for an Interface part. Enter the location and file name information for the Service part as in “Creating EGL source files” on page 90. you can create a Service part to call that program. EGL creates the new part and adds a function that calls the called program. Service properties Service part Service parts provide requesters with access to the functions in the service. library. The New EGL Service Part window opens. 3. A requester can be a local or remote program. such as a Web service. library. 1. such as a Web service. After the interface is complete. v Providing access to the services of an organization while keeping the details of service implementation confidential. For example. – To encourage developers to focus on the functionality that the service provides rather than on the details of the implementation. To access a Web service that is created outside of your organization. The Interface part includes a set of function prototypes (see Function prototypes).) and includes only a function name. – Developers can use interfaces to begin coding client applications while the service code is under development. When you access a service through an interface. For more information. you can code the service that implements the interface. you must create a variable that is based on the part. which details how to access the service. see the EGL Generation Guide. 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. and how your application uses an external service. but when you use an Interface part. and multiple services can implement the same interface. you might ship services as generated Java classes with EGL Interface parts so that the customer can invoke the services from EGL programs. parameter list. The interface is like a contract that the service fulfills.You can also use an Interface part to access a local service in situations where you want to restrict access to the source code. You can create an interface that describes the functionality that you want to have coded in an EGL service. end You cannot use an Interface part directly in your code. Uses of interface parts v Designing the services of an organization. the interface must be bound to the location of the service implementation with a deployment descriptor file. You might want to keep logic confidential for two reasons: – To hide the source code from developers outside of your organization. v Providing access to Web services regardless of the language or location of the service implementation. The deployment descriptor file describes how other applications can use a Service part from your application. the variable refers to a service that you are running from a specific location (URI). A service can implement multiple interfaces. and return type: Interface StockQuote Function getQuote(symbol String in) returns (float). Contents of an EGL application 115 . Benefits of using interface parts to design services: – People in your organization can use an interface to decide which operations a service needs before service development begins. you must have the service-specific Web Service Description Language (WSDL) definition. The service must contain a function that matches each prototype in the interface. For information on Interface part syntax. you can avoid disclosing the logic inside the service. At run time. Each prototype has an ending semicolon (. see Interface part. library. In the Functions field. Interface part Interface parts provide access to a remote service. 5. In the Project Explorer view. In the Package field. select the functions (or function prototypes in the case of an ExternalType) that you want to include in the new Interface part. select a package to hold the new file. such as a Web service. Creating an Interface part from a Service or ExternalType part: You can use other parts as a models for an Interface part. follow these steps: 1. or other service. By convention. In the EGL source file name field. 2. If you want to overwrite an EGL source file. EGL might show multiple Interfaces on separate tabs. A requester can be a local or remote program. Function prototypes Interface properties Interface part Interface parts provide access to a remote service. The New EGL Interface Part window opens. select a source folder to hold the new file. 4. 116 EGL Programmer’s Guide . Only the functions not marked as private are shown in this list. In the Source folder field. In the case of an ExternalType part. 3. To create an Interface part from a Service or ExternalType part. select the Overwrite existing files check box. such as a Web service. Click Finish. right-click an EGL source file that includes an EGL Service or ExternalType part and then click EGL Services → Extract EGL Interface. You can change the suggested name for any of these Interfaces. Related tasks “Creating EGL source files” on page 90 The creation process is essentially the same for most EGL source files. files that contain interface parts begin with a capital letter I. The editor creates a service-specific Interface part through which you can access the service in your code. 7. Related concepts “Overview of service-oriented architecture (SOA)” on page 475 Related tasks “Creating EGL source files” on page 90 The creation process is essentially the same for most EGL source files. “Creating an Interface part from a Service or ExternalType part” You can use other parts as a models for an Interface part. You can use the Select All and Deselect All buttons to select or deselect the functions. 6. type a name for the new file that will contain the new Interface part. Related reference Service part Service parts provide requesters with access to the functions in the service.You use the WSDL definition as input to create an external service using the service module editor. handler. Related concepts “Introduction to Service parts” on page 113 Service parts provide requesters with access to the functions in the service. and you can use Delegate parts in situations that do not involve user interfaces. Introduction to ExternalType parts ExternalType parts map EGL to external language elements. An ExternalType part consists of the following components: Variable declarations These provide access to public variables in the external language element. Function prototypes Interface part Interface parts provide access to a remote service. Contents of an EGL application 117 . A Delegate part is similar to a function pointer in COBOL or C. though some associated UI technologies do. v As a way to dynamically invoke functions. Delegate part A Delegate part provides a model for a function. but mapping EGL to external language elements is generalized to include fields and constructors. or assigned the name of a matching function with the same signature (parameter and return type definition) as the Delegate part. which are the basic unit of logic. Nothing in EGL generates events. you specify the Delegate part name as a type. Related concepts “Introduction to logic parts” on page 105 Logic parts define a sequence of instructions. Still. see Delegate part.Related reference ExternalType part ExternalType parts map EGL to external language elements. The most common use for Delegate parts is as an infrastructure to register event handlers. see External type for Java code. For more information. the way you specify a Record part name when you declare a record variable. the event-driven architecture is an increasingly common model for programming. The Delegate part does not have properties. The only external element that ExternalType part supports is the Java object. Related reference External type for Java code Logic parts Delegate part Delegate parts provide models for functions. When you declare a variable. For more information about the Delegate part. You can specify a delegate variable in the place of the function name on a function invocation. Function prototypes These represent method invocations or function calls in the external type. This mapping is similar to the mapping that an Interface part provides for Service functions. Most logic parts contain one or more functions. The variable is initialized. Then you can choose the actual function to be called dynamically. including the following: v As elements in a Dictionary of function pointers. such as a Web service. optionally using the EGL new statement. see Example. for details. for JavaScript code. to use its variables and functions (unless they are declared to be static. the ExternalType part must extend the predefined Serializable ExternalType: ExternalType CustomDate extends Serializable type JavaObject { packageName="com. create a variable that is based on the ExternalType and append the variable name to the name of the method by using dot syntax (externalTypeVariable. In each of these cases.methodName()). such as Java and C#. and constructors. These concepts include extension. where EGL does not have direct access to the code.io.Constructor prototypes These define the syntax for constructing a variable of this external type using an EGL new statement. see External type for JavaScript code v HostProgram. for host programs on IBM i. you use external functionality within your program. see External type for Java code v JavaScriptObject. Otherwise. refer to a basic Java reference.io. for details. invoke it using the name of the ExternalType part and dot syntax (typeName. inheritance. One of the main uses for an ExternalType part is to create arrays of function pointers for event handling.Serializable interface. The concept of the ExternalType is similar to that of a Library or a Service. A number of the concepts used with the ExternalType part come from object-oriented languages.methodName()). you must provide certain prototypes so that EGL can perform the necessary type checking. see EGL text reports. EGL text reports use ExternalTypes in this way.Serializable interface. for Java code. An ExternalType definition reserves no storage. If you are unfamiliar with these terms. In the case of the Service or the ExternalType. see ″Syntax″ in this topic). if the associated Java class implements the java.mycompany". For more information. You must declare a variable that is based on the part. ExternalTypes that do not extend the Serializable ExternalType are assumed to be 118 EGL Programmer’s Guide . javaName="CustomDate" } // functions end Serializable ExternalType variables can be saved directly to disk and restored later. Serializable ExternalType If you are mapping an ExternalType part to a Java class that implements the java. The ExternalType part can have any of three stereotypes: v JavaObject. for details. see Accessing IBM i programs as Web services ExternalType functions If the function is marked static. Folder. The following code shows the Serializable ExternalType: ExternalType Serializable type JavaObject { JavaName = "Serializable".Transient. 3. and WSDL file name fields with the location and name of the new WSDL file. right-click the file that contains the Service part and then click EGL Services → Generate WSDL File. you must add information to the deployment descriptor that tells EGL to generate the necessary Web service wrapper. 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 493. Related tasks “Exposing a service to other applications” on page 493 Your EGL application can act as a service by exposing its functions to other applications. In the Project Explorer view. If you want to save the information in a non-Serializable ExternalType. you must recreate or edit the WSDL file. 2. so if the service information changes. Fill out the Project Source. Under Advanced. PackageName = "java. Click Finish. This file is not updated automatically. provide the deployment information to be added to the WSDL file. This method is provided mainly for compatibility and to preview the WSDL file that will be created when you deploy your service. 1. The Create WSDL file window opens. If you want to expose a Web service to other applications through a WSDL file. or unable to be saved directly to disk. Contents of an EGL application 119 . The new WSDL file is created in the location that you specified. Creating a WSDL file from a Service part You can create a sample WSDL file as a point of reference to a Service part. “Adding Web service deployment information to the deployment descriptor” on page 496 After you have coded a service part that you want to expose as a Web service.io" } end Related tasks Accessing IBM i programs as Web services Related reference ExternalType part ExternalType parts map EGL to external language elements. you must use a data source. External type for Java code External type for JavaScript code Function prototypes EGL text reports EGL text reports offer a simplified alternative to more complex reporting tools. 4. 120 EGL Programmer’s Guide . Linkage options part A linkage options part gives details on how a generated program calls or transfers to and from other programs. The Rename window opens. 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. Parts List view. v For generatable parts. and run time. and run time. Renaming parts You can use the refactoring function of the workbench to rename parts and correct references to those parts. In one of the following places. v Right-click the part in the Outline view. or Parts Reference view. More information on build parts is available in the EGL Generation Guide. test time. The part also gives details on how a generated COBOL program accesses files on remote CICS regions. Related concepts “Introduction to EGL parts” on page 95 Parts are the building blocks of EGL applications. 1. The information in this part is used at generation time and preparation 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. test time.Introduction to build parts Build parts control the generation process and set how an application will behave at run time. see Overview of EGL deployment descriptor file. In the popup menu. 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. click Refactor → Rename. 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. right-click the file that contains the part in the Project Explorer view 2. but they fit into the category of files involved in generation and deployment. The information in this part is used at generation time. Deployment descriptors EGL deployment descriptors are not build parts. The information in this part is used at generation time. select the part that you want to rename: v Place the cursor on the part name in the EGL editor and right-click. test time. Build descriptor part A build descriptor part controls the generation process and indicates what other control parts are read during that process. For more information. which are covered in the EGL Generation Guide. The information in this part is used at generation time and preparation time. Build descriptor parts contain build descriptor options. 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. 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. EGL changes variable declarations to the new name of the record v For generatable parts. if you rename a record part. following EGL naming conventions. select this check box. “Renaming an EGL project” on page 75 If you rename an EGL project. In the Rename window. Generally. EGL changes the name of the file to match the new part name v For JSF Handlers. You cannot rename functions in this way. 1. EGL will not search other files for references to change.3. EGL links the JSP file to the new part’s file. For example. v For JSF Handlers. “Moving a source file” on page 92 You can use the refactoring function of the workbench to move source files and correct references to those files. Related concepts “Introduction to EGL parts” on page 95 Parts are the building blocks of EGL applications. You can click Preview for a list of the changes that EGL will make if you proceed. Parts List view.xml file. Related tasks “Renaming a source file” on page 91 You can use the refactoring function of the workbench to rename source files and correct references to those files. If you clear the Update references check box. 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. type a new name for the part. In one of the following places. EGL updates references to the part’s file in the faces configuration file. “Moving parts” You can use the refactoring function of the workbench to move parts between source files and correct references to those parts. you must manually correct most of the references to that project. 5. but it does not change the name of the JSP file. Moving parts You can use the refactoring function of the workbench to move parts between source files and correct references to those parts. or Parts Reference view Contents of an EGL application 121 . Click OK. 4. v For Program parts within an EGL plug-in project. “Generatable parts and non-generatable parts” on page 96 EGL parts can be generatable or non-generatable. EGL also corrects the reference to the program in the plugin. 6. If you clear the Update references to the moved elements check box. You can click Preview for a list of the changes that EGL will make if you proceed. In the popup menu. Properties Properties set specific options for parts. so when creating a part. 6. “Moving a source file” on page 92 You can use the refactoring function of the workbench to move source files and correct references to those files. 4. In the Textual Move window. 5. but most properties are optional. it is possible to change a property dynamically. but it does not change the name of the JSP file. You can click Create EGL file to create a new file to put the part into. EGL links the JSP file to the new part’s file. The most common type of property is a simple property.v For generatable parts. click Refactor → Move. select this check box. Most parts can accept one or more simple properties by 122 EGL Programmer’s Guide . 3. EGL also corrects the reference to the program in the plugin. right-click the file containing the part in the Project Explorer view 2. if you move a record part. Related tasks “Renaming a source file” on page 91 You can use the refactoring function of the workbench to rename source files and correct references to those files. select a new source file for the part. 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. a name-value pair that sets an option for the part. Related concepts “Introduction to EGL parts” on page 95 Parts are the building blocks of EGL applications. EGL changes variable declarations and any import statement to the new location of the record v For JSF Handlers. v For Program parts within an EGL plug-in project. If you are moving a generatable part. In certain circumstances. Click OK. “Generatable parts and non-generatable parts” on page 96 EGL parts can be generatable or non-generatable. In general. EGL updates references to the part’s file in the faces configuration file.xml file. Generally. v For JSF Handlers. however. EGL will not search other files for references to change. The available properties are different for each part and for each stereotype. Some parts have required properties. you specify the properties when you create the part and then the properties are static. For example. “Renaming parts” on page 120 You can use the refactoring function of the workbench to rename parts and correct references to those parts. check to see what properties are appropriate. The Textual Move window opens. the target source file must have the same name as the part. you must specify a literal. you can see that this property has an effect when used on a Web page. In most cases. The handler must have a function with this name or EGL will throw a validation error. but not in a Console User Interface application. In this case. 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. the JSF Handler part accepts the onPreRenderFunction property. unquoted ″yes″ or ″no″ value. This property specifies a function within the handler that runs automatically each time the handler runs. you cannot use a boolean variable or a string variable set to ″yes″ or ″no″ for the value of the currency property. a few properties require that you supply the name of a variable or part as a value. For example. DataItem parts can include properties that apply only to specific types of user interfaces. the property is not using the value of the variable or part. separate the name-value pairs with commas: DataItem cost money(10. For example. As in the previous example. the list of properties and their values) is referred to as a set-value block. Properties are useful only in specific situations. Some properties are provided for compatibility with previous versions or migrated code and are unnecessary for new EGL applications. some accept values from lists of options called enumerations. the onPreRenderFunction is set to the name of the function refreshFunction.listing the name of the property and the value for the property within braces ( { } ) at the beginning of the part definition. Some properties accept string literals. If you specify more than one property for the part. To know which properties are provided for new code and which are used for compatibility. In other words. CurrencySymbol = "$"} end The code block that begins with the opening brace and ends with the closing brace (that is. Property values You must provide a valid value for each property. However. you cannot use a variable or constant as the value of a property. you might write the handler as follows: handler myPage type JSFHandler {onPreRenderFunction = refreshFunction} function refreshFunction() end end In this example. Inheriting and overriding properties When you create a part based on another part. it is referring to the variable or part itself. the new part inherits the properties of the old part: Contents of an EGL application 123 . some accept a ″yes″ or ″no″ value. In this case. From the topic ″currencySymbol″ in the EGL Language Reference. see the EGL Language Reference topic that covers a particular part and its properties. and others accept array literals.2) {Currency = yes. However. the variable’s color property is set to blue because the second definition overrides the first. the field myField behaves as though you had specified the color property on it. Related reference Properties Set-value blocks Import and use statements Use the EGL import and use statements to expand the visibility of code elements. myBlueInt int {color = blue}.DataItem myRedVar int {color = red} end Record myRedRecord type BasicRecord myField myRedVar. Reference variables are an exception to property transfers. myBlueInt = myRedInt. The last property specification sets the value. as in this example: myRedInt int {color = red}. as in the following example: DataItem myRedVar int {color = red} end Record myBlueRecord type BasicRecord myField myRedVar {color = blue}. properties do not transfer between most variables. EGL import and use statements are commonly used in these situations: v You import a logic part (such as a Program or Library) or a data part (such as a Record or DataItem) so that you can refer to the part as though it were part of the current package. end In this case. See ″Properties″ in the EGL Language Reference. color = blue}. 124 EGL Programmer’s Guide . In this case. the field myField overrides the red value with the blue value. v You use a library that is in your current package so that you can drop the library prefix from any function names or variable names that you use from that library. In this way. You can explicitly override properties. it is legal but not recommended to define a property twice for one part or variable. end In this case. Related concepts “Introduction to EGL parts” on page 95 Parts are the building blocks of EGL applications. as in this example: myBlueVar int {color = red. In this case. myBlueInt still has the color property set to blue. v You import an entire package so that you can refer to any of the parts that it contains as if they were part of the current package. *.CustomerLib.crmpackage. if you have libraries named CustomerLib in both the ARPackage and CRMPackage. you define a local getCustomer() function. and you can refer directly to functions in system libraries or EGL-defined enumerations without having to use them.*. Related reference import use Scope Contents of an EGL application 125 .getCustomer()."). tells EGL to include the entire CRMPackage in the scope of the current logic part. you can use the following code: package com. Example You might want to access customer information in your accounts receivable (AR) package using the data definitions and functions from your customer relations management (CRM) package.companyb.writeStdOut() system function without referring to the library because of this implicit use: writeStdOut("Progam complete.v You use a form group in your current package to gain unqualified access to the forms in that group. Only the parts you reference will be added to the code. These parts are therefore described as implicitly imported and used.arpackage. // home of CustomerLib library program CustomerTest type BasicProgram use CustomerLib.crmpackage. To call the function getCustomer() from the library CustomerLib in the package com. end end The following aspects of the example are significant: v The line import com. see import and use/ Implicit import and use You can refer directly to any of the parts that EGL defines without having to import them. v If. import com.crmpackage. For more information.companyb. you cannot generate the program unless you add the library name to the function name. later in the CustomerTest program.crmpackage. // add these functions to my scope function main() getCustomer(). v You can combine the import and use statements to refer to a function or variable in a library from a different package.companyb. as in CustomerLib. For example. EGL uses the local (ARPackage) version.companyb. v You can use a data table so the program can directly access its fields. Similarly.companyb. v If you comment out the use statement. EGL invokes that function in preference to the function of the same name in com. you can call the sysLib. use considerations for DataTable parts FormGroup properties use considerations for FormGroup parts 126 EGL Programmer’s Guide . “Content assist” on page 157 “Code templates” on page 158 “Code snippets” on page 164 Snippets are code objects that are reusable programming objects. and comments. you can create your own snippets. and helps you write EGL code. in EGL you can add comments in your code. 1996. colors keywords. In addition to the default snippets provided in the workbench. “Handling errors” on page 148 With EGL. you can decide how your program behaves in case of errors. This topic covers a few of the most common ways. Related tasks “Turning lines of code into comment lines” on page 128 As in most languages. “Encrypting passwords” on page 146 You can encrypt passwords with an EGL command-line utility. provides an explanation for problems in the code. EGL ignores any text that is commented.Working with EGL code The EGL source editor provides a number of tools that you use to create EGL files. Password encryption is supported only for Java programs and the debugger.invoke(). “Customizing runtime messages” on page 152 © Copyright IBM Corp. and declaring an ExternalType part. “Editing DataItem parts with the source assistant” on page 167 Common programming tasks These topics contain information on how to complete several common programming tasks in EGL. not for COBOL programs. They provide step-by-step instructions within a workbench view and can perform some of the steps in the task automatically. The code editor highlights invalid syntax. strings. including using the system functions in the JavaLib system library such as javaLib. Related tasks “Enabling and disabling code templates” on page 159 “Creating code templates” on page 160 “Using cheat sheets” on page 166 Cheat sheets can assist you with common tasks in the Workbench. Related concepts “The EGL editor” on page 155 The EGL code editor looks and works like a standard text editor or code editor for other languages. 2008 127 . “Calling Java” on page 128 There are several ways to call Java code when you are generating Java from EGL. Snippets can be a piece of code or a complete programming task. but it has additional features to help you edit EGL code. //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. EGL ignores any text that is commented.Turning lines of code into comment lines As in most languages. colors keywords. Follow these steps to comment lines of code in the EGL editor: 1.invoke system function. 128 EGL Programmer’s Guide . v To comment a single line or a portion of a line. or you can create a block of commented lines. including using the system functions in the JavaLib system library such as javaLib. function myPlannedFunction() end */ To comment lines. you can use the javaLib. use two virgules or slashes (//): myInt int. in EGL you can add comments in your code. Comment indicators (//) are placed at the beginning of each line in the selected range. You can comment a single line of code at once. but select Uncomment from the pop-up menu. Calling Java There are several ways to call Java code when you are generating Java from EGL. 2. and comments. In the EGL editor. The code editor highlights invalid syntax. you can type the comment characters yourself. Prerequisites v An EGL project generated to Java. Right-click the highlighted lines and then click Comment. but it has additional features to help you edit EGL code.invoke(). 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. strings. provides an explanation for problems in the code. begin the comment with /* and end the comment with */: /* This function is commented. or you can tell the EGL editor which lines to comment. and declaring an ExternalType part. and helps you write EGL code. This topic covers a few of the most common ways. Related concepts “The EGL editor” on page 155 The EGL code editor looks and works like a standard text editor or code editor for other languages. Use the same procedures to uncomment lines. highlight one or more lines of code. Related tasks “Creating EGL source files” on page 90 The creation process is essentially the same for most EGL source files. Random provides an alternate way to return a random integer. Then. 2. For more information. see as operator. in this context. AS. However. or if the method that you want to call is not defined as static. use the argument parameter of javaLib. 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". Use the javaLib. In these examples. the class resembles an EGL library and the method works like a function in this library. "java.invoke() system function to call the method. even its non-static methods. passing the name of the class and the method to call as parameters: myNumber = javaLib. you can use other functions in javaLib to initialize and use a class multiple times. Instead. "random"). you cannot use javaLib. to convert Java types to EGL: javaLib. The following example uses a different class that returns random numbers.lang. Creating an ExternalType part to represent a class If you plan to use the class often.invoke(). This method belongs to the class java.storeNew("myRandomGenerator" AS "objId:java".writeStderr(strLib. ″Static″ is a Java term that has no parallel in EGL. declare any variables that you might need to pass or that you might need to accept a return value: myNumber float.util.formatNumber(myNumber)). Then you can use the class repeatedly through javaLib.Random").storeNew(). Because the method is not defined as static. you can define an EGL ExternalType part.invoke("java. an EGL part that Working with EGL code 129 .Math and returns a random number between 0 and 1. it means that the method is ready to be called at any time and needs no initialization before use. Note the use of the casting operator. for compatibility with migrated programs.util.lang. 3. you should create an ExternalType part. In an EGL function within a logic part. the string myRandomGenerator is an identifier that represents the class.util. Calling a Java class multiple times If you plan to use methods in a Java class several times. Each time you use the class. In this case. myInt int = javaLib.invoke("java. as in ″Creating an ExternalType part to represent a class″ that follows.This example calls the method random.invoke: myInt int = javaLib.invoke("myRandomGenerator" AS "objId:java". For more details on calling Java classes and methods. or if the method that you want to use is not defined as static.invoke() to call nextInt without any preparation: //Error! The method nextInt() is not static. The method nextInt in the class java. 1. see Java access functions.Random". you can use the results of the call: sysLib. "nextInt"). "nextInt").Math". The only methods you can call in this way are the methods defined as static. you must first initialize the class and give it an identifier in EGL using javaLib. To pass a parameter to the method. and with a little less EGL code. To create a variable based on an ExternalType part. a constructor is a function that runs when a new variable that is based on the part is created. v javaName is the name of the Java class itself. This class has a non-static method named nextInt which returns a random integer. Constructors are not commonly used in EGL. Within the ExternalType part. Java packages and EGL packages work in much the same way. ExternalType Random type JavaObject {packageName = "java. and its return value. In EGL terms. a prototype links a function in the ExternalType part to a method in the Java class.writeStderr(strLib. You can name the ExternalType part with the same name as the class if you want to. They list the function or method name. 2. ExternalType Random type JavaObject {packageName = "java. The ExternalType part also requires a constructor. Also. you must be careful to match Java types to compatible EGL types and vice versa. imagine that the class is a library and the methods are functions. In an EGL source file.util". This example uses the class java. you can create variables based on it and use those variables just like you would use the names of EGL libraries.util". you must first call its constructor with the new keyword and the name of the part: myRandomGenerator Random = new Random(). end Again. sysLib.Random. see new operator. 3. 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. The code new Random() is actually a function call to the constructor() function prototype in the part definition.represents a Java class directly. After you have defined the ExternalType part. javaName = "Random"} function nextInt() returns(int). its arguments. create function prototypes that represent the methods in the class that you want to use: ExternalType Random type JavaObject {packageName = "java. end 4. for the purposes of EGL programming. 1. for more information about them. Here. javaName = "Random"} function nextInt() returns(int).formatNumber(myInt)).util. Again.util".nextInt(). Use the functions in ExternalType just like you were using an EGL library: myInt int = myRandomGenerator. which in turn refers to the constructor of the Java class. 130 EGL Programmer’s Guide . 5. function prototypes in Java are similar to function prototypes in EGL. but have no internal logic. Tables associating EGL parts and Java parts are available in Mapping EGL primitives to Java. begin defining the ExternalType part by giving it the name of the Java class you want to use. constructor(). such as those in an Interface part. 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.nextInt(). Call the function using the following syntax: Working with EGL code 131 .writeStderr(StrLib.util". javaName = "Random"} constructor(). 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. Mapping EGL primitives to Java as operator new operator Function prototypes Calling C functions with the call statement EGL programs can invoke C functions with the call statement. function nextInt() returns(int). Adding a resource associations part to an EGL build file Related reference EGL library javaLib The javaLib functions access local Java objects and classes through your generated Java code. 2.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(). end For more details on the ExternalType part. myInt int = myRandomGenerator. see ExternalType part. SysLib. See If callLink type is remoteCall. Follow these steps to invoke a C function from EGL: 1. end end externalType Random type JavaObject {packageName = "java.formatNumber(myInt)). Java access functions invoke() storeNew() ExternalType part ExternalType parts map EGL to external language elements. Related tasks “Common programming tasks” on page 127 These topics contain information on how to complete several common programming tasks in EGL. Identify the C function to call. 3. STRING 132 EGL Programmer’s Guide . The sign bits are xC for a positive number and xD for a negative number. COBOL packed format. Use the pgmName property of the callLink element as functionName. and any parameters to pass to the function as parameters.” Related reference “Mapping EGL data types to C” If callLink type is remoteCall call 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. For ASCII. MONEY PACF FLOAT SMALLFLOAT BOOLEAN HEX CHAR MBCHAR.h to convert to wchar_t char.h to convert to wchar_t. The sign bits are xF for a positive number and xD for a negative number. the data is in big-endian order. double float char. For ASCII. Table 26. with 1 representing true and 0 representing false unsigned char char char. on other systems. with data in the UTF-16 encoding. To map EGL data types to C data types for use in these parameters. the sign bits are x30 for a positive number and x70 for a negative number. the sign bits are x30 for a positive number and x70 for a negative number. NUMC DECIMAL.call functionName (parameters). DBCHAR UNICODE. For EBCDIC. EGL primitives and C primitives EGL primitive INT SMALLINT BIGINT NUM C type int (signed 4-byte integer) short (signed 2-byte integer) long long (signed 8-byte integer) COBOL zoned format. the sign bits are xF0 for a positive number and xD0 for a negative number COBOL zoned format. the data is in little-endian order. Use mbstowcs from stdlib. On Windows® and Linux®. see “Mapping EGL data types to C. use mbstowcs from stdlib. two bytes per character. as explained in “Calling C functions with the call statement” on page 131. For EBCDIC. the sign bits are xC0 for a positive number and xD0 for a negative number COBOL packed format. Related reference “Calling C functions with the call statement” on page 131 Primitive data types Calling C functions through EGL libraries EGL programs can invoke C functions through Library parts with the stereotype nativeLibrary. Working with EGL code 133 . If the element is nullable. EGL ignores this value. You can use StrLib. The field’s data c. representing the number of fields 2. in yyyMMdd format. If the element is nullable. d. EGL passes the data of the lowest-level fields. an INT value representing the length of the element’s data b. data and time types (DATE.setNullTerminator to convert trailing blanks to null. starting with ″+″ or ″-″ followed by the digits of the value as ″0″ through ″9″ The values of the text types (CHAR. UNICODE. d. a SHORT representing the element’s nullability. If the element is nullable. MBCHAR. and HEX do not end with a null byte. or StrLib. the data passed to the C function is as follows. The data of the element c. a SHORT as a filler value.setBlankTerminator to convert trailing nulls to blanks. the value of the SHORT is -1. For non-structured records. EGL ignores this value. An INT value. If the field is nullable and has a null value. in this order: 1. You could define a C struct with the same structure as the record. An INT value representing the current length of the array 2. with digits stored as ″0″ through ″9″ char.Table 26. If the element is nullable and has a null value. and INTERVAL). DBCHAR. If the element is a STRING or a record. a SHORT representing the field’s nullability. If the field is nullable. TIME. STRING). the value of the SHORT is -1. with digits stored as ″0″ through ″9″ char. TIMESTAMP. The following data for each field in the record: a. The following data for each element in the array: a. Follow these steps to prepare to invoke a C function from EGL: 1. the data passed to the C function is as follows. in this order: 1. An INT value representing the maximum size of the array 3. For arrays. An INT value representing the length of the field’s data b. Identify the C functions to use in your EGL program and make sure they return an INT value of zero it they succeed. with digits stored as ″0″ through ″9″ char. in HHmmss format. For structured records. a SHORT as a filler value. EGL primitives and C primitives (continued) EGL primitive DATE TIME TIMESTAMP INTERVAL C type char. 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 ld -G -b32 -bexpall -bnoentry -brtl file1. Compile all C code into one shared library and link it with the appropriate platform-specific stack library.o v Win32: EGLRuntimes/Win32/bin/application. In the following platform-specific examples.2. To compile all C code into a shared library: a.lib For the platform-specific application object files: v AIX: EGLRuntimes/Aix/bin/application. INTERVAL.lib /OUT:lib1_name incl_dir The directory location for the header files.o file2.dll EGLRuntimes/Win32/bin/stack. Download the EGL runtime file as explained in Installing the EGL runtime code for Java. b.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 and file2. Download the EGL runtimes and extract the stack library and application object file to your computer: a. Create a function table.o -Lstack_lib_dir -lstack -o lib1_name On Windows (the link command must be on a single line): cl /c -Iincl_dir file1. compile all of your C code into one shared library and link it with the appropriate platform-specific EGL stack library. lib1_name The name of the output library.o file2.so v Linux: EGLRuntimes/Linux/bin/libstack.c file2. Using standard methods. Note: If your C code is using any of the IBM Informix ESQL/C library functions (BIGINT. 134 EGL Programmer’s Guide . then the ESQL/C library must also be linked. DECIMAL.c link /DLL file1.o v Linux: EGLRuntimes/Linux/bin/application.obj 3. b.obj /LIBPATH:stack_lib_dir /DEFAULTLIB:stack. file1. 4.so v Win32: EGLRuntimes/Win32/bin/stack. Unzip the file to a temporary directory and find the following files: For the platform-specific stack libraries: v AIX®: EGLRuntimes/Aix/bin/libstack.c file2.c file2. DATETIME). Your C code receives values from EGL using pop external functions and returns values to EGL using return external functions. DATE.obj file2.c gcc -shared file1. stack_lib_dir The directory location for the stack library. defaultI4GLNativeLibrary Java runtime property. Create a function table based on the example above.c ld -G -b32 -bexpall -bnoentry -brtl ftable. /* Similar prototypes for other functions */ struct func_table ftab[] = { "c_fun1".lib /LIBPATH:lib_dir /DEFAULTLIB:mylib. c_fun1 and c_fun2 are names of the C functions. extern int c_fun1(int). Specify lib2_name by using the dllName property or the vgj. Indicate the end of the function table with "". c_fun2. extern int c_fun2(int). NULL. 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. "c_fun2". In the following function table example. 5. All of the functions identified in the code must have been exported from the C shared library created in a previous step. The application object file is the interface between the EGL code and the C code. Compile the function table and the appropriate platform-specific application object file into a shared library. NULL }.obj 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_fun1. and populate the function table with the appropriate C functions. int (*fptr)(int). /* Similarly for other functions */ "".obj /LIBPATH:stack_lib_dir /DEFAULTLIB:stack. where ftable. and link this shared library with the shared library created in Step 2 and the stack library. }.lib /OUT:lib2_name Working with EGL code 135 .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.o application.h> struct func_table { char *fun_name.c gcc -shared ftable. On AIX (the ld command must be on a single line): cc -c ftable.c link /DLL ftable.o application.The function table is a C source file which includes the names of all C functions to be invoked from the EGL program.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. #include <stdio. 136 EGL Programmer’s Guide . callingConvention specifies that the arguments will be passed between functions and the calling code using the argument stack mechanism. return_code). To invoke a C function from an EGL program: 1. Prior to following the instructions below. This is made clear by defining the function in a native library as follows: Library I4GLFunctions type nativeLibrary {callingConvention = I4GL. With the USE statement. function table. see Invoking a C function from an EGL program. 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 program 2. respectively) to the function and expects two arguments to be passed back (msg_status and return_code. and stack library linked. 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. msg_status. i int in. the following function invocation statement calls the C function sendmsg( ) sendmsg(chartype. It passes two arguments (chartype and 4. msg_status int out. respectively).Link the three libraries together. specify the EGL native library in the calling module. With your C shared library. For example. For information on how to invoke a C function in EGL. 4. Related concepts Linkage options part Related reference “BIGINT functions for C” on page 138 “Mapping EGL data types to C” on page 132 “DATE functions for C” on page 139 “DATETIME and INTERVAL functions for C” on page 139 “DECIMAL functions for C” on page 140 “Invoking a C function from an EGL program” “Return functions for C” on page 144 “Stack functions for C” on page 141 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. 3. you must compile and link your C code as identified in “Calling C functions through EGL libraries” on page 133. you are now ready to invoke the C functions from your EGL code. Create an EGL Library part with the stereotype nativeLibrary containing the function definition. Using the function invocation statement. dllName = "mydll"} Function sendmsg(chartype char(10) in. "nxt_bus_day: wrong number of parms (%d)\n". The C function receives an integer argument that specifies how many values were pushed on the argument stack (in this case.dllName specifies the C shared library in which this function exists. “Stack functions for C” on page 141 “Return functions for C” on page 144 Working with EGL code 137 . } ibm_lib4gl_popDate(&theDate). case 6: /* saturday -> monday*/ ++theDate. If both dllName and the system property have been specified. This is the number of values to be popped off the stack in the C function. This example shows a C function that requires exactly one argument: int nxt_bus_day(int nargs). } ibm_lib4gl_returnDate(theDate).defaultI4GLNativeLibrary system property. return(1).thur) go to next day */ ++theDate. the dllName will be used. Note: The C shared library name can also be specified using the vgj. if (nargs != 1) { fprintf(stderr. The C function should test its integer argument to see how many EGL arguments were stacked for it. /* stack result */ return(1) /* return count of stacked */ } The function returns the date of the next business day after a given date. the function checks for the number of arguments passed. The C function should not assume it has been passed the correct number of stacked values. default: /* (sun. { int theDate. ibm_lib4gl_returnDate(0L). Because the function must receive exactly one argument. it terminates the program (with an identifying message).. switch(rdayofweek(theDate)) { case 5: /* change friday -> monday */ ++theDate. nargs ). If the function receives a different number of arguments. Related reference “BIGINT functions for C” on page 138 “Mapping EGL data types to C” on page 132 “DATE functions for C” on page 139 “DATETIME and INTERVAL functions for C” on page 139 “DECIMAL functions for C” on page 140 Library part Library parts support the sharing of functions and variables. The function also needs to return values for the msg_status and return_code arguments before passing control back to the EGL program. two arguments). Information about the structure can be found in the header file int8.h. To use these functions.“Calling C functions through EGL libraries” on page 133 BIGINT functions for C Note: The following BIGINT functionality is available only to users of IBM Informix ESQL/C. Function Name ifx_int8add( ) ifx_int8cmp( ) ifx_int8copy( ) ifx_int8cvasc( ) ifx_int8cvdbl( ) ifx_int8cvdec( ) ifx_int8cvflt( ) ifx_int8cvint( ) ifx_int8cvlong( ) ifx_int8cvlong_long( ) ifx_int8div( ) ifx_int8mul( ) ifx_int8sub( ) ifx_int8toasc( ) ifx_int8todbl( ) ifx_int8todec( ) ifx_int8toflt( ) ifx_int8toint( ) ifx_int8tolong( ) ifx_int8tolong_long( ) Description Adds two BIGINT type values Compares two BIGINT type numbers Copies an ifx_int8_t structure Converts a C char type value to a BIGINT type number Converts a C double type number to a BIGINT type number Converts a decimal type value into a BIGINT type value Converts a C float type value into a BIGINT type value Converts a C int type number into a BIGINT type number Converts a C long (int on 64 bit machine) type value to a BIGINT type value Converts a C long long type (8-byte value. 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. The BIGINT data type is internally represented with the ifx_int8_t structure. Include this file in all C source files that use any of the BIGINT functions. modifications. which is included in the ESQL/C product. ESQL/C provides routines that facilitate the conversion from the BIGINT data type to other data types in the C language. long long in 32 bit and long in 64 bit) value into a BIGINT type value Divides two BIGINT numbers Multiples two BIGINT numbers Subtracts two BIGINT numbers Converts a BIGINT type value to a C char type value Converts a BIGINT type value to a C double type value Converts a BIGINT type number into a decimal type number Converts a BIGINT type number into a C float type number Converts a BIGINT type value to a C int type value Converts a BIGINT type value to a C long (int on 64 bit machine) type value Converts a C long long (long on 64 bit machine) type to a BIGINT type value 138 EGL Programmer’s Guide . 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. or analyses can produce unpredictable results. Any other operations. All operations on int8 type numbers must be performed using the following ESQL/C library functions for the int8 data type. To use these functions.h. Working with EGL code 139 . see the following: IBM Informix ESQL/C Programmer’s Manual.For more information about the individual functions. and year Converts a character string format to an internal DATE Returns a system date as an internal DATE For more information about the individual functions. You must use the following ESQL/C library functions for the datetime and interval data types to perform all operations on those types of values. Function Name rdatestr( ) rdayofweek( ) rdefmtdate( ) rfmtdate( ) rjulmdy( ) rleapyear( ) rmdyjul( ) rstrdate( ) rtoday( ) Description Converts an internal DATE to a character string format Returns the day of the week of a date in internal format Converts a specified string format to an internal DATE Converts an internal DATE to a specified string format Returns month. ESQL/C users will need to manually link their C code to the ESQL/C libraries. Related reference “BIGINT functions for C” on page 138 “DATETIME and INTERVAL functions for C” “DECIMAL functions for C” on page 140 “Invoking a C function from an EGL program” on page 136 DATETIME and INTERVAL functions for C Note: The following DATETIME and INTERVAL functionality is available only to users of IBM Informix ESQL/C. see the following: IBM Informix ESQL/C Programmer’s Manual. Include this file in all C source files that use any of the DATETIME and INTERVAL functions. They convert dates between a string format and the internal DATE format. day. day. To use these functions. The following date-manipulation functions are in the ESQL/C library. The DATETIME and INTERVAL data types are internally represented with the dtime_t and intrvl_t structures. and year from a specified DATE Determines whether the specified year is a leap year Returns an internal DATE from month. which is included in the ESQL/C product. Related reference “DATE functions for C” “DATETIME and INTERVAL functions for C” “DECIMAL functions for C” on page 140 “Invoking a C function from an EGL program” on page 136 DATE functions for C Note: The following DATE functionality is available only to users of IBM Informix ESQL/C. respectively. Information about these structures can be found in the header file datetime. ESQL/C users will need to manually link their C code to the ESQL/C libraries. Function Name dtaddinv( ) dtcurrent( ) dtcvasc( ) dtcvfmtasc( ) dtextend( ) dtsub( ) dsubinv() dttoasc( ) dttofmtasc( ) incvasc( ) incvfmtasc( ) intoasc( ) intofmtasc( ) invdivdbl( ) invdivinv( ) invextend( ) invmuldbl( ) Description Adds an interval value to a datetime value Gets the current date and time Converts an ANSI-compliant character string to a datetime value Converts a character string with a specified format to a datetime value Changes the qualifier of a datetime value Subtracts one datetime value from another Subtracts an interval value from a datetime value Converts a datetime value to an ANSI-compliant character string Converts a datetime value to a character string with a specified format Converts an ANSI-compliant character string to an interval value Converts a character string with a specified format to an interval value Converts an interval value to an ANSI-compliant character string Converts an interval value to a character string with a specified format Divides an interval value by a numeric value Divides an interval value by another interval value Extends an interval value to a different interval qualifier Multiples an interval value by a numeric value For more information about the individual functions. The data type DECIMAL is a machine-independent method for representing numbers of up to 32 significant digits. see the following: IBM Informix ESQL/C Programmer’s Manual. ESQL/C users will need to manually link their C code to the ESQL/C libraries. 140 EGL Programmer’s Guide . ESQL/C provides routines that facilitate the conversion of DECIMAL-type numbers to and from every data type allowed in the C language. In normalized form. To use these functions. with or without a decimal point. and with exponents in the range -128 to +126. Related reference “BIGINT functions for C” on page 138 “DATE functions for C” on page 139 “DECIMAL functions for C” “Invoking a C function from an EGL program” on page 136 DECIMAL functions for C Note: The following DECIMAL functionality is available only to users of IBM Informix ESQL/C. DECIMAL-type numbers consist of an exponent and a mantissa (or fractional part) in base 100. the first digit of the mantissa must be greater than zero. The pop and return external functions are provided with the argument stack library. The decimal structure and the type definition dec_t can be found in the header file decimal. modifications or analyses can produce unpredictable results. 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. Include this file in all C source files that use any of the decimal functions.The DECIMAL date type is internally represented with the dec_t structure. The called function pushes its return values onto the stack and the caller pops them off to retrieve the values. EGL uses an argument stack.h. Working with EGL code 141 . Function Name deccvasc( ) dectoasc( ) deccvint( ) dectoint( ) deccvlong( ) dectolong( ) deccvflt( ) dectoflt( ) deccvdbl( ) dectodbl( ) decadd( ) decsub( ) decmul( ) decdiv( ) deccmp( ) deccopy( ) dececvt( ) decfcvt( ) Description Converts C int1 type to DECIMAL type Converts DECIMAL type to C int1 type Converts C int type to DECIMAL type Converts DECIMAL type to C int type Converts C int4 type to DECIMAL type Converts DECIMAL type to C int4 type Converts C float type to DECIMAL type Converts DECIMAL type to C float type Converts C double type to DECMAL type Converts DECIMAL type to C double type Adds two DECIMAL numbers Subtracts two DECIMAL numbers Multiplies two DECIMAL numbers Divides two DECIMAL numbers Compares two DECIMAL numbers Copies a DECIMAL number Converts DECIMAL value to ASCII string Converts DECIMAL value to ASCII string For more information about the individual functions. Related reference “BIGINT functions for C” on page 138 “DATE functions for C” on page 139 “DATETIME and INTERVAL functions for C” on page 139 “Invoking a C function from an EGL program” on page 136 Stack functions for C To call a C function. see the following: IBM Informix ESQL/C Programmer’s Manual. which is included in the ESQL/C product. The pop external functions are described below according to the data type of the value that each pops from the argument stack. All operations on decimal type numbers must be performed using the following ESQL/C library functions for the decimal data type. Any other operations. a mechanism that passes arguments between the functions and the calling code. The return external functions are described in Return functions for C. 3. 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 v v v v extern extern extern extern extern void void void void void ibm_lib4gl_popInt4(int *liv) ibm_lib4gl_popFloat(float *fv) ibm_lib4gl_popDouble(double *dfv) ibm_lib4gl_popDecimal(dec_t *decv) ibm_lib4gl_popInt8(ifx_int8_t *bi) The following table and similar tables below map the return function names between I4GL pre-Version 7. hence the inclusion of ″4gl″ in the function names.Note: The pop functions were originally used with IBM Informix 4GL (I4GL). Removes one value from the argument stack. 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.31 name popquote popstring popvchar Version 7.31 and later: Pre-Version 7.31 and later name ibm_lib4gl_popMInt ibm_lib4gl_popInt2 ibm_lib4gl_popInt4 ibm_lib4gl_popFloat ibm_lib4gl_popDouble ibm_lib4gl_popDecimal Each of these functions. Converts its data type if necessary. 2.31 and Version 7. If the value on the stack cannot be converted to the specified type. int len) Pre-Version 7. like all library functions for popping values. 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.31 and later name ibm_lib4gl_popQuotedStr ibm_lib4gl_popString ibm_lib4gl_popVarChar 142 EGL Programmer’s Guide . int len) v extern void ibm_lib4gl_popVarChar(char *qv.31 name popint popshort poplong popflo popdub popdec Version 7. Copies the value to the designated variable. int len) v extern void ibm_lib4gl_popString(char *qv. performs the following actions: 1. an error occurs. see the IBM Informix ESQL/C Programmer’s Manual. 31 and later name ibm_lib4gl_popDate ibm_lib4gl_popDateTime ibm_lib4gl_popInterval The structure types dtime_t and intrvl_t are used to represent DATETIME and INTERVAL data in a C program. and DATETIME (TIMESTAMP) values: v extern void ibm_lib4gl_popDate(int *datv) v extern void ibm_lib4gl_popInterval(intrvl_t *iv. its trailing bytes are lost. Working with EGL code 143 . INTERVAL.31 name poplocator Version 7. Note: The functions ibm_lib4gl_popString( ) and ibm_lib4gl_popQuotedStr( ) are identical. The final byte copied to the buffer is a null byte to terminate the string. To find the true data length of a string retrieved by ibm_lib4gl_popQuotedStr( ).Both ibm_lib4gl_popQuotedStr( ) and ibm_lib4gl_popVarChar( ) copy exactly len bytes into the string buffer *qv. The len argument sets the maximum size of the receiving string buffer. Library Functions for Popping Time Values You can call the following library functions to pop DATE. int qual) Pre-Version 7. If the stacked argument is longer than len-1. Library Functions for Popping BYTE or TEXT Values You can call the following function to pop a BYTE or TEXT argument: v extern void ibm_lib4gl_popBlobLocator(loc_t **blob) Pre-Version 7. you must trim trailing spaces from the popped value. and is discussed in the IBM Informix ESQL/C Programmer’s Manual. The qual argument receives the binary representation of the DATETIME or INTERVAL qualifier. except that ibm_lib4gl_popString( ) automatically trims any trailing blanks. even if the value on the stack is an empty string. and INTERVAL variables. see the IBM Informix ESQL/C Programmer’s Manual. DATETIME. but ibm_lib4gl_popVarChar( ) does not pad to the full length. Any BYTE or TEXT argument must be popped as BYTE or TEXT because EGL provides no automatic data type conversion. Here ibm_lib4gl_popQuotedStr( ) pads with spaces as necessary. Using ibm_lib4gl_popQuotedStr( ). you receive exactly len bytes (including trailing blank spaces and the null). int qual) You can call the following library function to pop TIMESTAMP values: v extern void ibm_lib4gl_popDateTime(dtime_t *dtv.31 and later name ibm_lib4gl_popBlobLocator The structure type loc_t defines a BYTE or TEXT value. For more information about the dtime_t and intrvl_t structure types and library functions for manipulating and printing DATE. so the maximum string data length is len-1.31 name popdate popdtime popinv Version 7. 31 and later: Pre-Version 7. a mechanism that passes arguments between the functions and the calling code.31 and later name ibm_lib4gl_returnMInt ibm_lib4gl_returnInt2 144 EGL Programmer’s Guide .31 and Version 7.Related reference “BIGINT functions for C” on page 138 “Mapping EGL data types to C” on page 132 “Calling C functions through EGL libraries” on page 133 “DATE functions for C” on page 139 “DATETIME and INTERVAL functions for C” on page 139 “DECIMAL functions for C” on page 140 “Invoking a C function from an EGL program” on page 136 “Return functions for C” Return functions for C To call a C function. 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. This storage is released when the returned value is popped. Library functions for returning values The following library functions are available to return values: v v v v v extern extern extern extern extern void void void void void ibm_lib4gl_returnMInt(int iv) ibm_lib4gl_returnInt2(short siv) ibm_lib4gl_returnInt4(int lv) ibm_lib4gl_returnFloat(float *fv) 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. This situation makes it possible to return values from local variables of the function. The pop and return external functions are provided with the argument stack library. Note: The return functions were originally used with IBM Informix 4GL (I4GL).31 name retint retshort Version 7. The return external functions are described below. the pop external functions used are described in Stack functions for C. The called function pushes its return values onto the stack and the caller pops them off to retrieve the values. hence the inclusion of ″4gl″ in the function names. EGL uses an argument stack. The external return functions copy their arguments to storage allocated outside the calling function. 31 and later name ibm_lib4gl_returnInt4 ibm_lib4gl_returnFloat ibm_lib4gl_returnDouble ibm_lib4gl_returnDecimal ibm_lib4gl_returnQuotedStr ibm_lib4gl_returnString ibm_lib4gl_returnVarChar ibm_lib4gl_returnDate ibm_lib4gl_returnDateTime ibm_lib4gl_returnInterval The argument of ibm_lib4gl_returnQuotedStr( ) is a null-terminated string. it internally calls ibm_lib4gl_returnQuotedStr( ). EGL converts the data type as required when popping the value. A function that returns nothing must exit with return(0). If conversion is possible. The C function can return data in whatever form is convenient.31 name retlong retflo retdub retdec retquote retstring retvchar retdate retdtime retinv Version 7. C functions called from EGL must always exit with the statement return(n). an error occurs. I4GL data types. where n is the number of return values pushed onto the stack. and EGL primitive types for use in a Library part with the stereotype nativeLibrary. If data type conversion is not possible. The ibm_lib4gl_returnString( ) function is included only for symmetry.Pre-Version 7. Related reference “BIGINT functions for C” on page 138 “Mapping EGL data types to C” on page 132 “Invoking a C function from an EGL program” on page 136 “Calling C functions through EGL libraries” on page 133 “DATE functions for C” on page 139 “DATETIME and INTERVAL functions for C” on page 139 “DECIMAL functions for C” on page 140 “Stack functions for C” on page 141 C data types and EGL primitive types The following table shows the mapping between C data types. C data types char char char char int short ifx_int8_t Equivalent I4GL data type CHAR or CHARACTER NCHAR NVARCHAR VARCHAR INT or INTEGER SMALLINT BIGINT Equivalent EGL primitive type UNICODE(1) UNICODE(size) STRING STRING INT SMALLINT BIGINT Working with EGL code 145 . When EGL generates output files. myStringVar2 STRING. writeStdOut(myStringVar2). // displays " abc" Encrypting passwords You can encrypt passwords with an EGL command-line utility.strLib. The following tips and tricks make use of this idea. // displays "cdef" Right-justifying a character variable Tip: The following example shows how to create a fixed length character variable to hold the right-justified contents of a STRING: myCharVar CHAR(10). not for COBOL programs. myCharVar[10 .characterLen(myStringVar) : 10] = myStringVar.s. it automatically encrypts passwords in property files and literals that are passed to system functions. Password encryption is supported only for Java programs and the debugger.C data types dec_t dec_t double float loc_t loc_t int dtime_t intvl_t Equivalent I4GL data type DEC or DECIMAL(p.) or NUMERIC(p) MONEY FLOAT SMALLFLOAT TEXT BYTE DATE DATETIME INTERVAL Equivalent EGL primitive type DECIMAL(p) MONEY FLOAT SMALLFLOAT CLOB BLOB DATE TIMESTAMP INTERVAL Related reference Primitive data types “Invoking a C function from an EGL program” on page 136 Working with substrings You can use brackets to treat a CHAR(n) or STRING variable as an array of characters.connect(myDatabase. here is a call to the sqlLib.connect system function: sqlLib. For example. "myPassword"). Creating a substring Tip: The following example shows how to use the bracket syntax to create a substring: myStringVar1 STRING = "abcdefghijklmn". myStringVar2 = myStringVar1[3:6]. 146 EGL Programmer’s Guide . myUserid. writeStdOut(myCharVar). myStringVar STRING = "abc". myPasswordVariable).0. such as sqlLib. for example.java.com/ developerworks/java/jdk/. it decrypts the password automatically. myPasswordVariable).etools. or VGLib. sqlLib. 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".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.ibm. use the one with the most recent version number. b. myUserid. 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.setRemoteUser. the password is not encrypted and is displayed in the generated source.ibm. If you installed and kept a previous version of an IBM product containing EGL before installing your current product. if you hard-code your password in a place other than the function call. 7. it is automatically encrypted in the generated code. If more than one is present.runtime_version shared_resources The shared resources directory for your product. In your system’s PATH environment variable. including three numbers separated by periods. myUserid. otherwise. you may need to specify the shared resources directory that was set up in the earlier install. Add your Java executable to the system’s path: a. such as ctgKeyStorePassword v Calls to system functions.Because the password parameter is specified as a string literal.connect(myDatabase. EGL will attempt to decrypt the non-encrypted password. you must encrypt any passwords beginning with the characters crypto:. Navigate to the following location: shared_resources\plugins\ com. sysLib. sqlLib. Working with EGL code 147 .connect.egl.connect(myDatabase. EGL does not encrypt the password: myPasswordVariable string = "myPassword". For this reason. add the location of the Java SDK. IBM offers a Java SDK for download at the following Web site: http://www. Open a command prompt. See your operating system’s documentation for instructions. Follow these steps to encrypt a password: 1. 3.0. In this case.RFB_20070120_1300. version The installed version of the plugin. such as C:\Program Files\IBM\SDP70Shared on a Windows system or /opt/IBM/SDP70Shared on a Linux system. 2. However. Obtain and install a Java SDK if you do not already have one. a string separator. and the date and time that the plugin was built. unless you have a reason to use an older version. ibm.jar com. all but the most trivial (see ″I/O errors″ later in this topic) will cause your program to terminate. This is a record variable similar to variables that you declare elsewhere in EGL. 6. or you can define your own. EGL has a number of predefined exceptions (see ″EGL Exception records″ in the appendix to the EGL Language Reference). you can decide how your program behaves in case of errors.PasswordEncrypter The program displays the prompt Enter text to encrypt:. For example. For example. into places in which you would ordinarily hard-code your password. Each exception record contains at least these fields: messageID A STRING that contains the EGL message for the exception. the message that goes with messageID EGL0106E is ″A null reference was used. EGL looks for an onException statement within the try block that matches the exception type. The program returns an encrypted string beginning with the prefix crypto:. which contains the value of the array index that EGL could not process. message A STRING that contains a brief explanation of the problem. If an exception occurs inside a try block. 5. Save the changed files and regenerate the project. which is a stereotype that applies to a record. if you try to use an uninitialized array. the declaration looks something like the following: onException(myEx NullValueException) This means that if EGL throws a NullValueException inside this try block. as in the following example: 148 EGL Programmer’s Guide . you can find the EGL message ID in myEx. Each onException statement includes the declaration of an exception variable. 7.″ The exception record can contain additional fields where appropriate. EGL sets the messageID in the NullValueException record to EGL0106E. Type your password and press Enter. Copy the entire returned string.msgID. you can access fields in that exception record. Type the following command to invoke the program: java -classpath fda7. Related tasks “Common programming tasks” on page 127 These topics contain information on how to complete several common programming tasks in EGL.4. Handling errors With EGL.javart.security. For example. Handling errors means anticipating the kinds of problems that might occur in your program and providing a code path for each of them. For example. Error handling in EGL grows out of the concept of the exception. including the crypto: prefix. The try block The EGL try keyword introduces a block of code in which you can catch and handle exceptions. the IndexOutOfBoundsException has an additional field for indexValue. If you decide not to handle errors. AnyException. an exception in a service function delivers a ServiceInvocationException to the calling program. your variable takes on the type of the actual exception record. a function can catch exceptions thrown in functions it calls.try intArray[10] = 0. 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. end If you had a specific code path that you wanted to follow if EGL throws a FileIOException. In this way. When an exception occurs in a remotely called program. onException(myEx AnyException) myErrorHandler2(myEx). explained below. onException(myEx AnyException) myErrorHandler2(myEx). is available to catch any exception and is comparable to the ANY primitive type. Consider the following example: try get next mySerialRecord onException(myEx AnyException) myErrorHandler(myEx). // this may not be initialized onException(myEx NullValueException) writeStdErr(myEx). as in this example: function FuncOne(myRec serialRecordType) try FuncTwo(myRec). myErrorHandler2() deals with any exception other than a FileIOException. and if EGL throws an exception. the function ends immediately and control returns to the function that called the function that threw the error. end Here. for example. the program ends immediately and writes the message field of the exception to the log. A special type of exception. end The myErrorHandler() function could. In other words. If EGL throws an exception but no onException block catches the exception. Similarly. you could add a special check for that as follows: try get next mySerialRecord onException(myEx FileIOException) myErrorHandler1(myEx). take care of initializing the array and perform the assignment again. Working with EGL code 149 . myErrorHandler(myEx). 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. You declare a record variable for AnyException. the calling program receives an InvocationException rather than the original exception. even if the error occurs outside of a try block. The following errors are considered soft. To test for this situation. use the is or not operator. the error indicates an attempt to read a record that could not be found. but do not cause an exception to be thrown. end end throwNrfEofExceptions property By default. the program terminates. are considered hard errors. You can do so by setting the throwNrfEofExceptions program property to YES. this error indicates a second record has the same key. A hard I/O error on an indexed. this error indicates an attempt to read past the end of the file. or the program will terminate. you may prefer to have EGL throw an exception when one of these errors occurs. end However. you cannot check at the same time for hard I/O errors: while(TRUE) // endless loop try get next mySerialRecord. Soft I/O errors Error duplicate endOfFile noRecordFound Meaning For an indexed or relative record. EGL throws a RuntimeException. either of the following techniques enables you to handle the exception: v Continue after the soft error: 150 EGL Programmer’s Guide . However. Using the previous example. which means that the program continues after the soft I/O errors noRecordFound and endOfFile. However. In that case. relative. You do not have to place the I/O statement in question inside a try block to use these operators. Other errors. EGL throws an SQLException. unless you put the I/O statement inside a try block. that is. EGL makes a distinction between hard and soft I/O errors. if(myCustomer is noRecordFound) add myCustomer. end onException(myEx AnyException) myErrorHandler(myEx). such as an invalid file format or a full file. EGL throws one of the following exceptions: v If you are performing file I/O. v If you are performing SQL I/O. Soft I/O errors associate the error value with record. For a serial.Hard and soft I/O errors When you are reading or writing to a file. You must catch this error in a try block. if(mySerialRecord is endOfFile) exit while. or relative record. not likely to cause a loss of data: Table 27. For any record type. as in the following example: get myCustomer. or serial file throws a FileIOException. the throwNrfEofExceptions program property is set to NO. indexed. A hard I/O error on an SQL database throws an SQLException. if no record is found for the get statement. .errorCode = "00000008") // invalid input myErrorHandler1(). you can throw any of the predefined system exceptions. Custom exceptions records like this one automatically include the messageID and message fields. throw nullEx. end v Catch the exception. and do not specify an exception type. V6 exception compatibility For compatibility with earlier versions. if(sysVar. you can create your own exception records. As in exception handling. The difference is that V6 exceptions allow only a single onException statement. end end Throwing your own exceptions Using an EGL throw statement.try get myCustomer. for best results use the same setting for all of your programs. which is the preferred technique: try get myCustomer.errorCode = "00000012") // cannot assign value Working with EGL code 151 . you can still use the error handling methods from version 6 of EGL. just like the system exception records. and then declare a variable based on it. end . . you must declare a variable based on the record: nullEx NullValueException{}. V6 exceptions are typically handled through a try block. you must define a Record part first. end if (myCustomer is noRecordFound) add myCustomer. message = "Illegal customer number" }. You specify V6 exception mode on a program-by-program basis when you set the program’s v60ExceptionCompatibility property to YES. Record CustomerException type Exception customerNumber INT. As with other records. onException if(sysVar.. The behavior is thus the same as if the onException statement had an implied AnyException modifier: try posNum = abs(myVar). In addition to the exceptions that the system defines. onException (myEx FileIOException) if (myCustomer is noRecordFound) add myCustomer.. throw new customerException { customerNumber = custNum.. else myErrorHandler(myEx). However. posNum = abs(myVar).handleSysLibraryErrors system variable (for functions in system libraries) or vgVar.handleHardIOErrors (for file and SQL I/O) set to 1: vgVar.file Java runtime property. if(sysVar. an EGL system message is displayed by default. Related reference EGL core Exception records I/O error values throwNrfEofExceptions handleSysLibraryErrors Customizing runtime messages When an error occurs at Java run time. for SQL I/O errors.sqlData. else exit program (-1). 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.errorCode == "00000008") // invalid input myErrorHandler1(). V6 exception compatibility relies on the system variables in sysVar.messages. sysVar.errorCode system variable. 152 EGL Programmer’s Guide . any exception will cause the program to terminate.errorCode is set in the following cases: v v v v At the completion of a call statement After a call to a service After a file I/O statement such as get or replace After invoking many of the EGL system functions In addition. else myErrorHandler3().myErrorHandler2(). Related tasks “Common programming tasks” on page 127 These topics contain information on how to complete several common programming tasks in EGL. For more information. For more information about the format of a Java properties file. else if(sysVar.handleSysLibraryErrors is set to 0 (the default) and you do not use a try block to catch exceptions. vgVar.errorCode in V6 exception mode if you have the vgVar. You do not need a try block to access sysVar. however.handleSysLibraryErrors = 1. V6 exception compatibility relies on the sysVar. This property is set with the userMessageFile build descriptor option. see Exception handling.errorCode == "00000012") // cannot assign myErrorHandler2(). end end If. see Program properties file. If you are running in V6 exception mode. end Instead of being based on exception records. properties. if your code submits an invalid date mask to a system function. EGL compares the message ID of the required message to the IDs of the messages in the properties file. In properties-file format.When a message is required.Properties.file. Find the message ID of the system message you want to replace. e. one (placeholder 0) for the date mask itself. You can also use the sysLib. In the Enter or select the parent folder field. Valid examples are as follows: EGL0049E = Tried to assign {0} to {1} and failed. Working with EGL code 153 .file. EGL0049E = {1} = {0} : Overflow on assignment.messages. g. ending in . the other (placeholder 1) for the name of the system function. d. In the Project Explorer view. The program terminates if the file that is identified in the vgj. see the documentation for the Java class java. If there is no message in the properties file with a matching ID. a system message includes placeholders for the message inserts that EGL retrieves at run time. the message has two placeholders. These messages replace the default system messages.properties.util. right-click the Java Resources folder of your EGL project. If EGL finds a message in the properties file with a matching ID. An example of a valid file name is messages.messages. Other details are available in Java language documentation: v For details on how messages are processed and on what content is valid. c. expand General and click File. EGL first searches the properties file specified in vgj. ensure that your project’s Java Resources folder is selected. You can change the wording of the message to include all or some of the placeholders in any order. 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. the entry for the default message is as follows: EGL0049E = Overflow when assigning {0} to {1}. type a name for the properties file. EGL uses the default system message. In many cases. Click Finish. it uses that message. but you cannot add placeholders. f. For example. 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). The new file is created and opens in the editor. In the New window. see the documentation for the Java class java.MessageFormat. Click Next. 2.file property cannot be opened. b. Click New → Other.text. To add customized messages to the messages file: a.getMessage system function to return a message from the properties file specified in vgj. 1. To create a properties file for the customized messages: a.messages. In the File name field. or create a new message ID if you are adding a new message. file runtime property in the J2EE deployment descriptor.file. the following properties file line replaces the system message ID EGL0049E. specify the messages file: v Set the userMessageFile build descriptor option to specify name of the messages file without the . their message IDs. v Set the vgj. Click Finish.properties extension. In the Value field. double-click the project’s J2EE deployment descriptor. The Add Environment Entry window opens. if the messages file is named messages. If you generate with genProperties set to PROGRAM. if the messages file is named messages.file runtime property in the file rununit. To set the vgj.ibm.messages.file property in the file rununit. The deployment descriptor opens in the deployment descriptor editor. which by default is Overflow when assigning {0} to {1}./com. In the Project Explorer view. b. Open the file rununit. type messages. Add a line to the messages file in the following format: messageID = customMessage messageID The ID of the system message. This file is created the first time that you generate a file with the genProperties property set to GLOBAL. For example. Set the genProperties build descriptor option to GLOBAL or PROGRAM. save and close the messages file. In the Type field. This method applies only to projects used within the J2EE framework. g. 3.messages. follow these steps: a. type the name of the messages file without the . In this example.file Java runtime property.messages.messages.properties in the Java Resources folder. the runtime property that specifies the message file. e. follow these steps: a. This method applies to any type of EGL project. v Set the vgj. When you are finished adding messages. c.The documentation contains information about the system messages. and any placeholders in the message. type vgj.properties..egl. 154 EGL Programmer’s Guide . These placeholders are optional in your customized message.dita. This method applies only to projects used within the J2EE framework. See .: EGL0049E = Tried to assign {0} to {1} and failed.. For example.properties extension. the code strings {0} and {1} are placeholders for message inserts that EGL retrieves at run time. f. The userMessageFile build descriptor option sets the vgj. In the Name field.properties.messages. click Add. customMessage The custom message to display in place of the system message.messages. select String.doc/topics/rjavrun0001. Click the Variables tab. To set the vgj. c. Using one of the following methods. b. Under Environment Variables.messages.file Java runtime property in the J2EE deployment descriptor (not the EGL deployment descriptor) to specify the name of the messages file.properties. d.properties to specify the name of the messages file. 4./. For example. set the userMessageFile build descriptor option to messages. including any placeholders in the message. but it has additional features to help you edit EGL code. repeat the message IDs that you used in the first properties file. and paste code with commands in the Edit menu.messages. Replace messageFileName with the name of the name of the messages file without the .file = messageFileName c. adding a locale suffix to the new files to represent their language. and comments. For example.properties. c. In the properties file. a file with messages in German might be named messages_de. d. colors keywords. 6. see “Locales for resource bundles” on page 431. Create new properties files for each language you want to provide. b. 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. In each new file. In the new files. if the messages file is named messages. b. 5.properties and is located in the Java package of the generated program. Generate any EGL file in the project. if your original properties file was named messages. and helps you write EGL code.messages. strings.file = messages. Related concepts Program properties file Related tasks “Localizing text in Web applications” on page 426 Related reference EGL Java runtime error codes Overview of Java runtime properties errorCode getMessage() userMessageFile The EGL editor The EGL code editor looks and works like a standard text editor or code editor for other languages. create additional properties files for those languages: a. Working with EGL code 155 .the properties file is named pgmNameOrAlias. copy. without changing the message ID. Save and close the properties file. translate the text of the message. For example.properties. provides an explanation for problems in the code.properties extension. type vgj. add the following code: vgj. The code editor highlights invalid syntax. The editor uses many of the same editing functions as the other text and code editors in the workbench: v Cut.setLocale() system function. 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.properties. d. If you want to localize messages into other languages. For more information on locales. You can control how EGL code is displayed in the editor. or clicking File → Save. Code assist searches for valid keywords. v To comment or uncomment one or more lines of code. v Locate the file in a different view by clicking Navigate → Show In and then click Project Explorer. variables. v Press Ctrl+A to select the entire file. part. such as a framework for a part. See “Content assist” on page 157. or function from the list of options. Writing code faster The main tool that the EGL editor provides to speed up code development time is code assist. variable. right-click. by clicking the tabs at the top of the editor. select one or more lines. and then click Shift Right or Shift Left. the DataItem part source assistant can help you set the properties for a DataItem part. v Generate the current file by pressing CTRL+G or right-clicking the file in the Project Explorer view and then clicking Generate. Some functions of the editor require that you select one or more lines of code (sometimes referred to as a block of code). v To indent or outdent code. Outline.v Save the current file by pressing CTRL+S. and then click Comment or Uncomment. To activate code assistance. Code assist can also insert larger code templates into your code. press CTRL+Space and choose a keyword. 156 EGL Programmer’s Guide . you can double-click at the beginning or end of a code block to select the entire code block. such as package. The editor also includes wizards that can generate EGL code into the file you are editing. highlight an EGL keyword. See “Editing DataItem parts with the source assistant” on page 167. or part names that begin with the first few characters that you type and the matching code. hold the Shift key. For example. Additionally. See “Setting preferences for EGL text” on page 180. clicking the Save button on the toolbar. You can select code in any of these ways v Click and drag the mouse over one or more lines of code. Also. v Double-click a single word to select that word. Getting help The editor provides dynamic help for most EGL keywords. select one or more lines. v Switch between open files. You can also type the first few characters of a keyword. To activate dynamic help. part. or Navigator. and press F1. See “Code templates” on page 158. the F1 key provides dynamic help when you are in most EGL-related wizards and windows. v Undo your most recent change by pressing CTRL+Z or by clicking Edit → Undo. v Put the cursor at the beginning of a code block. right-click. or variable to filter the list. and use the arrow keys to move the cursor to the end of the block. Working with EGL code 157 . Click the icon again to restore the code. See “Setting preferences for folding in the EGL editor” on page 176. 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. Any profile that you create is added to the list of available profiles. variable. Related tasks “Working with EGL code” on page 127 Content assist The EGL content assist is a tool that you can use to complete programming statements without having to type the entire statement. so that you can see only the parts of the source file that you want to see. To fold a block of code. Depending on the folding preference settings. right-clicking. function. v The editor removes any unused import statements. based on the settings in the preference page. you can also ″fold″ code. You can change or remove any profile that you create. There are two formatting profiles defined within EGL: v EGL [build in] v VA Gen [build in] You cannot change the formatting preferences within these two profiles or remove these profiles. It provides a way to quickly insert an EGL keyword. certain blocks of code may be folded automatically when you open a source file in the editor. and how much white space to include in the source code. See “Setting preferences for formatting in the EGL editor” on page 177 for defining editor profile preferences. You can create one or more EGL editor profiles using the EGL Editor Formatter preference. right-click in the editor and then click Organize Imports. To organize import statements. property. You can also fold arbitrary lines of code by selecting them. including what characters and how many characters to use for indentation. and then clicking Fold Text.Organizing code The EGL editor can help organize your import statements. With the editor. v The editor combines multiple import statements to the same package into a single import statement with a wildcard character. Customizing the EGL editor The formatting preferences affect how the code is formatted in the editor. click the minus icon on the left side of the editor. See “Setting preferences for organizing import statements in the EGL editor” on page 178. Folding a block of code hides that code temporarily. Folding does not change the behavior of your code in any way. or code template. v The editor attempts to add import statements for any parts that are used in the file but are not in scope. the code collapses temporarily. whether to use upper or lower case for keywords. In addition to the default snippets provided in the workbench. and code statements that begin with pr. it presents all of the available keywords that are legal at that position. or export a template by using the Preferences window. The displayed list will contain those commands. you must type a prefix and then press Ctrl+Space. To use a template. Related concepts “Code templates” “Code snippets” on page 164 Snippets are code objects that are reusable programming objects. Snippets can be a piece of code or a complete programming task. The resulting list shows properties that are both valid for the program and not yet included in the program. Position the cursor after the comma and press Ctrl+Space to initiate the content assist. All templates whose name begins with that prefix are included in the code assist list. that template must be enabled in the code template preferences. templates are used for functions that are routine. templates. Typically. The content assist is context-sensitive. 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. do the following steps: 1. You can use the content assist to add additional properties as follows: 1. You can filter the displayed information by entering the beginning characters of the function that you want to insert and then initiate the content assist. For example. The content assist displays a list of EGL keywords and code templates legal at your current position. Press the Tab key to move to a highlighted variable. To see the templates. if you are in a set-value block for a program. v Click on an option in the list. type at least one character of the keyword or template you are searching for before or after activating the content assist. you can create your own snippets. type progr). To use the content assist. 158 EGL Programmer’s Guide . type pr and press Ctrl+Space. You can also restore a removed template if you have not exited from the workbench since it was removed. If you have modified the list of default templates. To reduce the number of items in the list. The code is inserted into the current location of the cursor. you can restore the list to its default value. You can then modify the inserted code. Code templates A code template is an outline of code that can be reused. which may be a long list. 3. 4. You can create. 2. However. the content assist offers only properties that are valid for programs. Select the desired code as described above. 2. Type a comma (. you can control the amount of information that is displayed when you initiate the content assist. those variables are highlighted in the inserted code temporarily. If you inserted a code template with variables rather than a single keyword. remove. Within an EGL source file. press Ctrl + Space.) after the last property-value pair. edit.When you initiate the content assist. import. You can narrow the list more by increasing the number of characters that you type for the search argument (for example. if you are looking for program. 3. For example. such as retrieving data from a data source. Also. you can create your own snippets. For example. 3. Related concepts “Content assist” on page 157 “Code snippets” on page 164 Snippets are code objects that are reusable programming objects. the template will be available only when the cursor is in a place where that keyword is valid. assume you have created a code template named ″myFunction″ that consists of an EGL function. Related tasks “Enabling and disabling code templates” “Creating code templates” on page 160 “Editing code templates” on page 161 “Removing code templates” on page 163 “Importing code templates” on page 162 “Exporting code templates” on page 162 “Restoring default code templates” on page 163 Enabling and disabling code templates To limit the list of code templates that is offered to you in the editor. If the beginning of the template is not an EGL keyword. follow these steps: Working with EGL code 159 . From the navigation tree. expand EGL → Editor and then click Templates. the webservice_function templates are listed in code assist. click Apply. the function template would be an option only if the cursor is in a place where a function would be valid. if the cursor is position in a place where a function is permitted. A list of templates is displayed. In addition to the default snippets provided in the workbench. you can enable or disable specific templates. Click OK to close the window. Templates are displayed in code assist only when you have typed at least one character to filter the list of options. 4. When you want to insert this template. From the Preferences window. If you select one of the templates. select the check box to the left of a template name that you want to be available in the EGL editor. To save your changes. Similarly. 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. the template can be inserted anywhere. if you begin the code template with an EGL keyword such as function. follow these steps: 1. In this case. such as my or myFunc. From the main menu. Snippets can be a piece of code or a complete programming task. not f or fun. To disable code templates in the EGL editor. and you type w. For example. not the first word of the code in the template itself. you must begin by typing letters from the name. beginning with the keyword function. click Window → Preferences. To enable code templates in the EGL editor. 2. clear the related check box. to make a template unavailable.provided the on-screen cursor is in a position where the code produced by the template is syntactically allowed. 5. The templates are always at the bottom of the list for code assist. When you want to use the new template. each of those variables resolves to the appropriate value. To create a new code template. type the template itself: v Type any text that you want to display. 5. click Apply. From the main menu. expand EGL → Editor and then click Templates. this value is for informational purposes only. v You can select an area of functionality for the template from the Context list. specify both a name and a description to uniquely identify the template. 7. each variable is highlighted to indicate that a value is required. a string. 4. When you insert a custom template in the EGL editor. Click OK to close the window. click Window → Preferences. click Insert Variable. 8. To save your changes. When you insert the template in the EGL editor. From the Preferences window. 2. A list of templates is displayed. To save your changes. Related concepts “Code templates” on page 158 Related tasks “Creating code templates” “Importing code templates” on page 162 “Exporting code templates” on page 162 “Removing code templates” on page 163 “Restoring default code templates” on page 163 Creating code templates You can create your own code template. click Window → Preferences. 3. expand EGL → Editor and then click Templates. From the main menu. follow these steps: 1. see “Code templates” on page 158. clear the check box to the left of the template names that you do not want to show in the EGL editor. From the navigation tree. In the New Template window. Related concepts “Content assist” on page 157 160 EGL Programmer’s Guide . Click OK to close the window.1. v To place an existing variable at the current cursor position. From the navigation tree. but user-defined templates are not filtered by capability like the default templates are. type a dollar sign ($) followed by a left brace ({). v To create a custom variable. 3. From the Preferences window. as in this example: ${variable} You might find it easier to insert an existing variable and change the name for your own use. and a right brace (}). click New. click Apply. In the Pattern field. After the template is created it is shown in the list of templates. you will type all or the beginning of the name and then activate code assist. For more information on naming considerations. 2. 6. For user-defined templates. Click OK to create the template. then double-click a variable. 4. 5. Snippets can be a piece of code or a complete programming task. Click the desired template from the table and then click Revert to Default. Click the desired template from the table and click Edit. Related tasks “Enabling and disabling code templates” on page 159 “Creating code templates” on page 160 “Importing code templates” on page 162 “Exporting code templates” on page 162 “Removing code templates” on page 163 “Restoring default code templates” on page 163 Working with EGL code 161 . Snippets can be a piece of code or a complete programming task. 4. you can create your own snippets. From the navigation tree. From the main menu. Related concepts “Content assist” on page 157 “Code templates” on page 158 “Code snippets” on page 164 Snippets are code objects that are reusable programming objects. 2. If the code template you edited is one of the templates provided with the product. To edit an existing code template. 4. From the navigation tree. click Window → Preferences.“Code templates” on page 158 “Code snippets” on page 164 Snippets are code objects that are reusable programming objects. 2. From the main menu. Click OK when you are finished. 6. Click OK to close the window. To save your changes. A list of templates is displayed. click Apply. In addition to the default snippets provided in the workbench. expand EGL → Editor and then click Templates. A list of templates is displayed. 3. In addition to the default snippets provided in the workbench. To save your changes. Change the desired fields in the Edit Template dialog box. you can revert to the original template as follows: 1. Click OK to close the window. 5. click Window → Preferences. click Apply. follow these steps: 1. expand EGL → Editor and then click Templates. Related tasks “Enabling and disabling code templates” on page 159 “Importing code templates” on page 162 “Exporting code templates” on page 162 “Removing code templates” on page 163 “Restoring default code templates” on page 163 Editing code templates You can modify existing code templates to fit your specific coding needs. 5. you can create your own snippets. 3. Note: As in other applications on Windows 2000/NT/XP. Snippets can be a piece of code or a complete programming task. Related tasks “Enabling and disabling code templates” on page 159 “Creating code templates” on page 160 “Importing code templates” “Removing code templates” on page 163 “Restoring default code templates” on page 163 Importing code templates You can import code templates from a file system. Select the location to save the template file in the Exporting Templates window. 5. Select the location of the template file to be imported in the Importing Templates window. To export code templates. 6. expand EGL → Editor and then click Templates. Click Save to save the templates in the specified location. 4. click Window → Preferences. 2. expand EGL → Editor and then click Templates. To import code templates. you can click an entry to select it. 162 EGL Programmer’s Guide . you can create your own snippets. you can create your own snippets. Related concepts “Content assist” on page 157 “Code templates” on page 158 “Code snippets” on page 164 Snippets are code objects that are reusable programming objects. The templates are added to the existing templates. In addition to the default snippets provided in the workbench. A list of templates is displayed.Exporting code templates You can export code templates to a file system. Select the desired templates from the table and click Export. A list of templates is displayed. 4. 5. 2. You can browse the various locations to locate the template file that you want to import. From the navigation tree. From the main menu. You can browse the various locations to locate the place that you want to save the templates. From the main menu. 3. 3. click Window → Preferences. From the navigation tree. follow these steps: 1. In addition to the default snippets provided in the workbench. can use Ctrl-click to select or deselect an entry without affecting other selections. Snippets can be a piece of code or a complete programming task. and can use Shift-click to select a set of entries that are contiguous to the entry you last clicked. follow these steps: 1. Click Import. Related concepts “Content assist” on page 157 “Code templates” on page 158 “Code snippets” on page 164 Snippets are code objects that are reusable programming objects. Select the template file to be imported and click Open. To save your changes. expand EGL → Editor and then click Templates. expand EGL → Editor and then click Templates. From the navigation tree. 3. Related concepts “Content assist” on page 157 “Code templates” on page 158 “Code snippets” on page 164 Snippets are code objects that are reusable programming objects. From the main menu. From the navigation tree.Related tasks “Enabling and disabling code templates” on page 159 “Creating code templates” on page 160 “Exporting code templates” on page 162 “Removing code templates” “Restoring default code templates” Removing code templates You can remove code templates from the list of available templates. Alternately. A list of templates is displayed. 2. click the templates that you want to remove. Related tasks “Enabling and disabling code templates” on page 159 “Creating code templates” on page 160 “Importing code templates” on page 162 “Exporting code templates” on page 162 “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. See “Editing code templates” on page 161. can use Ctrl-click to select or deselect an entry without affecting other selections. 4. In addition to the default snippets provided in the workbench. follow these steps: 1. follow these steps: 1. Working with EGL code 163 . A list of templates is displayed. click Apply. To restore the default code templates. click Window → Preferences. the removed templates cannot be restored. Snippets can be a piece of code or a complete programming task. click Window → Preferences. After you exit the workbench. you can restore a single code template to the default shipped with the product. and then click Remove. you can click an entry to select it. Click OK to close the window. From the main menu. To remove an existing code template. Note: As in other applications on Windows 2000/NT/XP. When restoring the list of code templates any modifications or templates you created will be removed. In the table. 2. You can restore the templates if you have not exited the workbench. and can use Shift-click to select a set of entries that are contiguous to the entry you last clicked. you can create your own snippets. 5. A JavaScript function that tests for the presence of a session variable. An EGL function that retrieves the hyperlinked value of a clicked row in a data table. Click OK to close the window. See “Testing browsers for a session variable” on page 425. click Restore Defaults. In addition to the default snippets provided in the workbench. If the session variable is not present. 4. Auto redirect (JSP) Get clicked row value database update Related concepts “Content assist” on page 157 “Code templates” on page 158 164 EGL Programmer’s Guide . you can create your own snippets. An EGL function that updates a single row of a relational table when passed a record from a JSF Handler. as well as code for many other technologies. Snippets can be a piece of code or a complete programming task. The Snippets view provides access to the snippets available for use. click Apply. To save your changes. Table 28. Snippets can be a piece of code or a complete programming task. See “Retrieving the value of a clicked row in a data table” on page 417. In addition to the default snippets provided in the workbench. you can create your own snippets. The Snippets view contains several pieces of EGL code. Snippets available in EGL Snippet name Set cursor focus (JSP) Description A JavaScript function that sets the cursor focus to a specified form field on a Web page. See “Updating a row in a relational table” on page 423. it forwards the browser to a different page. Related tasks “Enabling and disabling code templates” on page 159 “Creating code templates” on page 160 “Importing code templates” on page 162 “Exporting code templates” on page 162 “Removing code templates” on page 163 “Restoring default code templates” on page 163 Code snippets Snippets are code objects that are reusable programming objects. 5. Related concepts “Content assist” on page 157 “Code templates” on page 158 “Code snippets” Snippets are code objects that are reusable programming objects.3. See “Setting the focus to a form field” on page 418. The following table lists the snippets that are available in EGL. To return to the template list that was in effect at installation time. Click Window → Show View → Other. Inserting code snippets into EGL and JSP files To insert an EGL code snippet into your code. 2. the customized code forwards control to a different Web page. 4. Related concepts Snippets view “Code snippets” on page 164 Snippets are code objects that are reusable programming objects. In the Snippets view. Click OK. This snippet is intended to be placed in an EGL library. b. 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. indicating that the snippet can not be inserted at that point. This method works only when putting a snippet on a JSP file. and data parts in the snippet as appropriate to your code. “Testing browsers for a session variable” on page 425 The Auto redirect snippet in the JSP drawer of the Snippets view tests for the presence of a session variable. enter values for these variables and then click Insert. Note: If the cursor turns into a circle with a strike through it. If you selected a snippet that contains variables. “Updating a row in a relational table” on page 423 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. “Retrieving the value of a clicked row in a data table” on page 417 The getClickedRowValue snippet in the EGL drawer of the Snippets view is a function that retrieves the hyperlinked value of a clicked row in a data table. you will be prompted to enter the variables. Most snippets include comments that explain what names need to be changed. c. expand the EGL drawer. Open the Snippets view. 5. Change the predefined names of functions. v Click and drag a snippet into the source code. follow these steps: 1. Snippets can Working with EGL code 165 . a. 3. Open the file to which you want to add a snippet. Expand General and click Snippets. It must be placed within a <script> tag in a JSP page. variables. If so. You may see a window describing the variables in the snippet. This drawer contains the available EGL code snippets. If the session variable is not present.Related concepts Adding snippets from the Snippet view Snippets view Related tasks “Inserting code snippets into EGL and JSP files” “Setting the focus to a form field” on page 418 The Set cursor focus snippet in the EGL drawer of the Snippets view is a JavaScript function that sets the cursor focus to a specified form field on a Web page. 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 can click on the Click to Skip link. This snippet is intended to be placed in an EGL library. Related tasks “Content assist” on page 157 “Setting the focus to a form field” on page 418 The Set cursor focus snippet in the EGL drawer of the Snippets view is a JavaScript function that sets the cursor focus to a specified form field on a Web page. “Testing browsers for a session variable” on page 425 The Auto redirect snippet in the JSP drawer of the Snippets view tests for the presence of a session variable. As you complete each step. the cheat sheet might be able to open a wizard for you. Follow these instructions to open and use a cheat sheet: 1. “Updating a row in a relational table” on page 423 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. you might need to perform the step manually or there might be other options available as follows: v In some cases. then you can skip the step of creating an EGL Web project. For example. Click OK. v In some cases. 6. but you must fill out the wizard to complete the step. EGL offers the following cheat sheets: Create an EGL Hello World Web application Creates a simple Web application with EGL. you can click the Click to Perform link. the customized code forwards control to a different Web page. 5. “Retrieving the value of a clicked row in a data table” on page 417 The getClickedRowValue snippet in the EGL drawer of the Snippets view is a function that retrieves the hyperlinked value of a clicked row in a data table. Follow the steps in the cheat sheet. you can create your own snippets. see Working with cheat sheets.be a piece of code or a complete programming task. They provide step-by-step instructions within a workbench view and can perform some of the steps in the task automatically. Click Click to Begin to start through the cheat sheet. the cheat sheet provides an option to skip a step. 166 EGL Programmer’s Guide . The Cheat Sheet Selection window opens. For example. If this option is available. click the Click to Complete link. For more information on cheat sheets. if you already have an EGL Web project. they provide the information necessary to perform each step. the cheat sheet can perform the step or a portion of the step for you. It must be placed within a <script> tag in a JSP page. As the steps in the cheat sheet expand. If the session variable is not present. Using cheat sheets Cheat sheets can assist you with common tasks in the Workbench. 3. 4. 2. Click Help → Cheat Sheets. Expand EGL and select an EGL cheat sheet. The cheat sheet opens in a workbench view. The next step in the cheat sheet expands automatically. Depending on the step. If this option is available and you have already met the criteria. In addition to the default snippets provided in the workbench. follow these steps: 1. Open the source assistant by using one of these methods: v Press Ctrl + Shift + Z. Create an EGL data access Web application from a UML model If you have a UML model that describes a database. You can switch between different pages of properties by clicking the tabs below the Type field. 7. v Right-click the DataItem and then click Source Assistant. Working with EGL code 167 . 6. To modify DataItem properties. This cheat sheet is similar to the method described in “Creating a data access application” on page 208. The source assistant validates the values you enter and lists any errors at the bottom of the window. When there are no more validation errors listed. 5. 2. Specify values for the properties of the DataItem. DataItem parts can have one or more properties assigned to them. Related concepts “Working with EGL code” on page 127 Editing DataItem parts with the source assistant Like most parts. When you are finished editing the values. The cursor must be on the DataItem. 9. Correct any errors that are listed in the window and click Validate again. Save the EGL source file. Create a Web service Creates a simple Web service using EGL. 4. specify these values in the Length and Decimals fields.Create an EGL data access Web application from a database connection If you already have a connection to a database. 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. type the name of the DataItem in the Name field and select the type from the Type field. The source assistant closes and updates the DataItem properties to match the properties that you specified. click Validate. you can use this cheat sheet to create an EGL application that acts as a client for that service. Open an EGL source file. 3. 8. 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. These fields are not available if the DataItem does not require a length or number of decimal place values. Select the DataItem that you want to edit. click OK. you can use this cheat sheet to connect to the database and create a simple Web application based on the database schema. Data parts form the basis for a variable that you can use in a logic part. Related concepts “Introduction to data parts” on page 97 Data parts define a structure that stores one or more pieces of data. In the EGL Source Assistant window. Create a Web service client If you have a WSDL file that describes a Web service. If the type of DataItem requires a length or a number of decimal places. click Search → File.” Parts List view The Parts List view displays a table of EGL parts with details about their location and type. See “Viewing lists of parts” on page 169. it does not search your project for a text match to a string. File Search view With the File Search view.Searching for EGL files and parts The workbench provides several options for searching for and viewing EGL files and parts. To use the Parts List view. right-click the files. such as a program. 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. This method of searching is not customized for EGL use. you can search for EGL parts or references to those parts. “Locating an EGL source file in the Project Explorer view” on page 172 Searching for parts You can search for parts among the EGL projects in your workspace. This search returns part definitions and references. See “Locating an EGL source file in the Project Explorer view” on page 172. Related tasks “Searching for parts” You can search for parts among the EGL projects in your workspace. you can perform a textual search of the entire workspace or a subset of your files and projects. To open the Parts Reference view. select one or more EGL files in the Project Explorer view. Parts Reference view The Parts Reference view displays all the parts that are referenced by a single generatable logic part. You type a string and specify the search scope. and then click Open in Parts List. and the workbench searches the files for a textual match. “Viewing part references” on page 171 The EGL Parts Reference view shows a hierarchical view of the parts that are referenced in a generatable logic part. See “Viewing part references” on page 171. such as functions. From the main menu. parameters. 168 EGL Programmer’s Guide . you can use it for all types of files. For a textual search of your project. right-click a file containing a generatable logic part in the Project Explorer view and then click Open in Parts Reference. right-click the open file in the editor and then click Show In → Project Explorer. To search for a list of available parts. See “Searching for parts. follow these steps: 1. “Viewing lists of parts” on page 169 You can choose one or more EGL parts and group those parts in a list to filter or sort them. Click Search → EGL from the menu bar and type in a search string. and the types used to create variables. EGL Search view With the Search view. click Search → EGL. The Search window opens to the EGL Search tab. If you do not see Search → EGL. “Locating an EGL source file in the Project Explorer view” on page 172 Viewing lists of parts You can choose one or more EGL parts and group those parts in a list to filter or sort them. 5. and the matching part is highlighted. Click Search. 4. Working with EGL code 169 . and ″my10Part″. called a working set. Click Choose to select the working sets to search. the first match is highlighted. In the Scope section. select the option to limit your search to part declarations. click Search → Search and switch to the EGL Search tab. Type my*Part to locate parts named ″my1Part″. 6. Related concepts “Contents of an EGL application” on page 67 This topic describes the artifacts found in a typical EGL application. If there is more than one match in the file. and the types used to create variables. You can use the following wildcard symbols in your search: v A question mark (?) represents any one character v An asterisk (*) represents a series of any characters of any length For example. Working set Searches a set of projects. 3. select where to search: Workspace Searches the current workspace. the file opens in the EGL editor. part references. In the Search For section. In the Limit To section. ″my2Part″. type my?Part to locate parts named ″my1Part″ and ″my2Part″. parameters. Enclosing projects Searches the project or projects that contain the files selected in the Project Explorer view or other view.2. or select Any element to expand your search to all part types. 7. “Viewing part references” on page 171 The EGL Parts Reference view shows a hierarchical view of the parts that are referenced in a generatable logic part. such as functions. The results are displayed in the Search view. select the type of part you are searching for. Selected resources Searches the resources currently selected in the Project Explorer view or other view. Arrows in the left margin of the editor indicate the locations of each matching part. If you double-click a file in the Search view. 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. or any occurrence of the search string. but not ″my10Part″. Click the Case sensitive check box for a case-sensitive search. “Introduction to EGL parts” on page 95 Parts are the building blocks of EGL applications. Type the criteria for the search in the Search string field. v Click the Refresh button at the top right of the view to refresh the information in the view. This method can be useful for viewing all the parts that are referenced by another part. do one of the following: v In the Project Explorer view. select one or more EGL resources. enter a part name in the Part name filter field. v Go to the part in the Project Explorer view by right-clicking it and then clicking Show in Project Explorer. 2. or service and then clicking Open in Parts Reference. v Debug a program by right-clicking it and then clicking Debug EGL Program. package. Then. such as files. v To filter by part name. From the list at the top right corner of the EGL Parts List view. you can filter the list to include only certain parts: 1. When you are finished setting the filter in the EGL Parts List Filter window. projects. v Click a column header to sort the list by the part name. In the EGL Parts List Filter window. click OK. 3. click Filters. v Generate a generatable part by right-clicking it and then clicking Generate or Generate With Wizard. v Search for related EGL code by right-clicking on the part. and then selecting a scope for the search. folder. A question mark (?) represents any one character and an asterisk (*) represents a series of any characters. v Open a part in the EGL Parts Reference view by right-clicking a program. clicking References or Declarations. select one or more EGL parts. select or deselect the resources under Part Resources. right-click the selected parts and click Open in Parts List. set the criteria for the filter: v To filter by project. or filename. or file. After the EGL Parts List view is open and populated with parts. 4. v To filter by type of part. The EGL Parts List Filter window opens. library. v Filter the list of parts with the Filters list at the top right of the view. Populate the EGL Parts List view with EGL parts. v In the EGL Parts Reference view. Then. package.To populate the EGL Parts List view 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. or packages. project. Only the parts that match the filter criteria are shown in the EGL Parts List view. Related tasks 170 EGL Programmer’s Guide . See “Viewing part references” on page 171. Filtering lists of parts While viewing a list of parts in the EGL Parts List view. Related concepts “Introduction to EGL parts” on page 95 Parts are the building blocks of EGL applications. 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. type. select or deselect the types of parts under Part Type. right-click the selected resources and click Open in Parts List. handler. select the Case sensitive check box. but not ″my10Part″. you can expand its hierarchy to see the parts that are referenced. click Find. Type my*Part to locate parts named ″my1Part″. Type a search string into the Search string field.“Searching for parts” on page 168 You can search for parts among the EGL projects in your workspace. Select the options for the search. v To make a text search case-sensitive. Working with EGL code 171 . Viewing part references The EGL Parts Reference view shows a hierarchical view of the parts that are referenced in a generatable logic part. you can select a type of part to search for by clicking a radio button under Search For. ″my2Part″. Right-click the EGL Parts Reference view and then click Find in tree. and then selecting a scope for the search. When you are finished setting the criteria for the search. 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. Alternatively. 2. such as functions. After the part opens in the view. 5. 7. parameters. right-click the file that contains the part in the Project Explorer view and then click Open in Parts Reference. you can right-click the part in the Outline view or the EGL Parts List view and then click Open in Parts Reference. Part search searches for EGL parts and Text search searches for text within the part. choose to search Forward or Backward from the currently selected part. v To search for only a complete part name or text string. 3. “Locating an EGL source file in the Project Explorer view” on page 172 “Viewing part references” The EGL Parts Reference view shows a hierarchical view of the parts that are referenced in a generatable logic part. click Close. type my?Part to locate parts named ″my1Part″ and ″my2Part″. The first result of the search is highlighted in the EGL Parts Reference view. and ″my10Part″. select the Wrap search check box. select the Whole word check box. 6. In the EGL Parts Reference view. v A question mark (?) represents any one character v An asterisk (*) represents a series of any characters For example. and the types used to create variables. To move to the next result. parameters. The EGL Parts Reference Find window opens. v If you selected Part search. Choose a search type. 4. clicking References or Declarations. To open a generatable logic part in the EGL Parts Reference view. v Under Direction. v To continue searching from the other end if the search reaches the bottom or the top of the tree. When you are finished. You can also search for parts or text strings among the parts in the view: 1. and the types used to create variables. click Find. v Search for related EGL code by right-clicking on the part. such as functions. Locating an EGL source file in the Project Explorer view If you are editing an EGL source file. Preferences EGL preferences affect the way the workbench displays and works with EGL. right-click the open file in the EGL editor and then click Show in → ProjectExplorer. and comments. The code editor highlights invalid syntax. To locate an EGL source file in one of these views. “Viewing lists of parts” on page 169 You can choose one or more EGL parts and group those parts in a list to filter or sort them. and helps you write EGL code. “Enabling and disabling code templates” on page 159 “Setting general preferences” on page 173 172 EGL Programmer’s Guide . This menu option does the following tasks: v Opens the specified view. Related reference “The EGL editor” on page 155 The EGL code editor looks and works like a standard text editor or code editor for other languages. Related tasks “Enabling EGL capabilities” on page 11 Capabilities keep the workbench menus from becoming cluttered by hiding items you do not use. if it is not already open v Expands the tree nodes needed to locate the source file v Highlights the source file Related tasks “Creating EGL source files” on page 90 The creation process is essentially the same for most EGL source files. Related tasks “Searching for parts” on page 168 You can search for parts among the EGL projects in your workspace. and helps you write EGL code. Outline view. and comments. but it has additional features to help you edit EGL code. provides an explanation for problems in the code. or Navigator view. strings. Related reference “The EGL editor” on page 155 The EGL code editor looks and works like a standard text editor or code editor for other languages. strings.Related concepts “Introduction to EGL parts” on page 95 Parts are the building blocks of EGL applications. but it has additional features to help you edit EGL code. but to make them appear in the menus. colors keywords. You can also click Show in → Outline or Show in → Navigator to display where the file is in one of those views. you must enable the capability for that area of functionality. colors keywords. you can quickly locate the file in the Project Explorer view. provides an explanation for problems in the code. The code editor highlights invalid syntax. You can always perform these tasks. “Setting preferences for SQL retrieve” on page 220 “Creating an SQL database connection” on page 197 The New Connection wizard creates an SQL database connection that you can use either at design time or at run time. 3. 4. click Window → Preferences. “Setting preferences for EGL text” on page 180 “Setting preferences for Rich UI” on page 345 “Setting preferences for the Text Form editor” on page 510 “Setting bidirectional text preferences for the Text Form editor” on page 511 “Setting preferences for the Text Form editor palette entries” on page 512 Setting general preferences Set the basic EGL preferences as follows: 1. In the EGL Base section. Ensure that the VisualAge Generator compatibility check box is selected if your environment requires compatibility.eglbld) files. select the character-encoding set that will be used when you create new EGL build (.“Setting build descriptor preferences” on page 174 “Setting preferences for the EGL debugger” on page 604 This topic tells you how to change your preferences for the EGL debugger. you must enable the capability for that area of functionality. You can always perform these tasks. Select facets to be enabled by default for a new EGL Web project in the Default EGL Web Project Facet Choices section. Setting the default build descriptors “Setting preferences for the EGL editor” on page 175 “Setting EGL-to-EGL migration preferences” on page 42 “Setting generation preferences” on page 180 “Setting preferences for source styles” on page 179 “Setting preferences for Web projects” on page 465 These preferences control defaults for EGL Web projects and JSF Handler parts. Click OK to save the changes and exit the window. Related tasks “Enabling EGL capabilities” on page 11 Capabilities keep the workbench menus from becoming cluttered by hiding items you do not use. The default value is UTF-8. select whether VisualAge Generator compatibility is needed in your environment. The setting has no effect on existing build files. From the main menu. but to make them appear in the menus. click EGL in the tree. 2. “Preferences” on page 172 EGL preferences affect the way the workbench displays and works with EGL. Click Apply to save the changes and remain in the Preferences window. added through features and facets. Select features to be enabled by default for a new EGL project in the Default EGL Project Features Choices. 5. Related concepts VisualAge Generator compatibility “Features and facets of EGL projects” on page 76 EGL projects can have additional abilities. 7. Working with EGL code 173 . In the Preferences window. In the Encoding field. 6. Prompt When you select a database connection in the EGL Runtime Data Connections property page. Update default build options for project when runtime data source is modified. Never When you select a database connection. From the navigation tree. EGL updates build descriptor options automatically. click Window → Preferences. you can set the following EGL build descriptor settings: Target system build descriptor Sets the default build descriptor for generating code in the workbench. specify preferences for build descriptors. 4. EGL asks you if you want to update the build descriptor options in the master build descriptor for the project. This setting controls what happens when you select a database connection in the EGL Runtime Data Connections properties page for a project as explained in “Using an SQL database connection at run time” on page 202. Related tasks “Setting general preferences” on page 173 Setting the default build descriptors 174 EGL Programmer’s Guide . EGL uses this build descriptor if you do not specify another one for the project. In the Preferences window. Always When you select a database connection. “Setting preferences for the EGL editor” on page 175 “Setting preferences for source styles” on page 179 “Setting preferences for EGL text” on page 180 “Setting preferences for service generation” on page 498 You can set defaults for how your services are generated. Debug build descriptor Sets the default build descriptor to be used when debugging EGL code in the workbench. follow these steps: From the main menu. 2. EGL does not update build descriptor options. Click OK to save the changes and exit the window. 3. expand EGL and click Default Build Descriptor.“Setting preferences for the EGL debugger” on page 604 This topic tells you how to change your preferences for the EGL debugger. Setting build descriptor preferences To 1. Related concepts “Preferences” on page 172 EGL preferences affect the way the workbench displays and works with EGL. Click Apply to save the changes and remain in the Preferences window. EGL uses this build descriptor if you do not specify another one for the project. 3. 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. Click Apply to save the changes and remain in the Preferences window. “Setting preferences for folding in the EGL editor” on page 176 Folding enables you to collapse blocks of code in the EGL editor to hide them. click Window → Preferences. Annotate errors in text Underlines errors in the source code with a red line. “Setting general preferences” on page 173 “Setting preferences for the EGL debugger” on page 604 This topic tells you how to change your preferences for the EGL debugger.Setting preferences for the EGL editor To 1. expand EGL and click Editor. see the following topics: v “Setting preferences for folding in the EGL editor” on page 176 v “Setting preferences for organizing import statements in the EGL editor” on page 178 v “Setting preferences for source styles” on page 179 v “Enabling and disabling code templates” on page 159 Related concepts “Preferences” on page 172 EGL preferences affect the way the workbench displays and works with EGL. You can always perform these tasks. you can set the following EGL editor settings: Show line numbers Displays the line numbers in the EGL file. Related tasks “Enabling EGL capabilities” on page 11 Capabilities keep the workbench menus from becoming cluttered by hiding items you do not use. To set these options. From the navigation tree. “Setting preferences for source styles” on page 179 “Setting preferences for EGL text” on page 180 “Setting the fonts used in the EGL editor” on page 176 The EGL editor uses the fonts and colors from the general preferences in the workbench. Errors are shown after saving the file. you must enable the capability for that area of functionality. 4. When the check box next to the setting is clear. 2. “Setting preferences for organizing import statements in the EGL editor” on page 178 EGL can automatically organize the import statements in your code. Errors are shown after saving the file. Click the check box to turn the setting on. follow these steps: From the main menu. Working with EGL code 175 . but to make them appear in the menus. specify the EGL editor preferences. There are other pages with additional options for the EGL editor under the EGL page in the navigation tree. the setting is turned off. Click OK to save the changes and exit the window. In the Preferences window. Related reference “Content assist” on page 157 “Code templates” on page 158 Setting the fonts used in the EGL editor The EGL editor uses the fonts and colors from the general preferences in the workbench. Click OK to save the changes and exit the window. To 1. To set folding preferences: 1. enter the minimum number of lines in a block of properties that you want to be able to fold. Related tasks “Setting preferences for the EGL editor” on page 175 “Setting general preferences” on page 173 Setting preferences for folding in the EGL editor Folding enables you to collapse blocks of code in the EGL editor to hide them. change the fonts and colors used in the EGL editor. select the check boxes next to the sections of EGL code that you want the editor to fold automatically when you open a file. Click Apply to save the changes and remain in the Preferences window. In the Preferences window. Folding has no effect on EGL source code or generated source. 8. Click OK. On the Colors and Fonts page. including the typeface. On the Folding page of the Preferences window. and you can click Use System Font to use your computer’s default font. 2. select the Enable folding check box to enable the EGL editor to collapse sections of your code. and color. Click Change. In the Preferences window. 6. 4. it is only a tool to view the active parts of your source code while hiding parts that you are not currently working with. follow these steps: Click Window → Preferences. you can click Reset to return to the defaults for the workbench. 5. click General → Appearance → Colors and fonts. Related concepts 176 EGL Programmer’s Guide . In the Number of property block lines needed to enable folding field. EGL will automatically fold blocks of properties of the given size or larger. expand EGL and click EGL Editor Text Font. If you want to restore settings. In the Font window. 2. If you select the Properties Block check box. size. Under Initially fold these elements. select the font to use in the EGL editor. 4. 6. 5. Related concepts “Preferences” on page 172 EGL preferences affect the way the workbench displays and works with EGL. Click OK to close the Preferences window. expand EGL → Editor and click Folding. 3. 7. click Window → Preferences. From the main menu. 3. “Setting general preferences” on page 173 “Setting preferences for the EGL debugger” on page 604 This topic tells you how to change your preferences for the EGL debugger. “Setting preferences for the EGL editor” on page 175 “Setting preferences for source styles” on page 179 Working with EGL code 177 . or remove editor formatting profiles. and comments. From the main menu. v To create a new profile.“Preferences” on page 172 EGL preferences affect the way the workbench displays and works with EGL. and helps you write EGL code. expand EGL and click Editor → Formatter. Related tasks “Enabling EGL capabilities” on page 11 Capabilities keep the workbench menus from becoming cluttered by hiding items you do not use. “Setting preferences for organizing import statements in the EGL editor” on page 178 EGL can automatically organize the import statements in your code. but to make them appear in the menus. You can always perform these tasks. you can add. change. follow these steps: 1. you must enable the capability for that area of functionality. v To work with an existing profile. click New and select the features for the profile on the Edit Profile window. Related tasks “Enabling EGL capabilities” on page 11 Capabilities keep the workbench menus from becoming cluttered by hiding items you do not use. Click Rename to change the name of the profile. “Setting preferences for folding in the EGL editor” on page 176 Folding enables you to collapse blocks of code in the EGL editor to hide them. you must enable the capability for that area of functionality. colors keywords. provides an explanation for problems in the code. From the navigation tree. strings. v To remove a profile. The code editor highlights invalid syntax. but to make them appear in the menus. In the Formatter window. 3. Setting preferences for formatting in the EGL editor To specify the EGL editor formatting preferences. You can always perform these tasks. “Preferences” on page 172 EGL preferences affect the way the workbench displays and works with EGL. but it has additional features to help you edit EGL code. Related concepts “The EGL editor” on page 155 The EGL code editor looks and works like a standard text editor or code editor for other languages. “Setting preferences for the EGL editor” on page 175 “Setting preferences for organizing import statements in the EGL editor” on page 178 EGL can automatically organize the import statements in your code. click Window → Preferences. select the profile from the drop-down list and click Edit to change the settings defined in the profile. select the profile and click Remove. 2. your file might have the following similar import statements: import com.mypackage. but to make them appear in the menus.mypackage.*. click Window → Preferences. 3. To organize your import statements. Click Apply to save the changes and remain in the Preferences window. If you set the Number of imports needed field to 3. On the Organize Imports page of the Preferences window.myPart1. enter the minimum number of individual import statements in the same package to simplify into an import statement with a wild card character. v To reorder the packages and prefixes. open a source file in the editor. Alternatively. import com. and then click Organize Imports. For example. click a package or prefix in the list to select it and then click Up or Down. 178 EGL Programmer’s Guide . you must enable the capability for that area of functionality. 4. Follow these steps to set preferences for organizing the import statements in your code: 1. In the Preferences window.“Setting preferences for EGL text” on page 180 Related reference “Content assist” on page 157 “Code templates” on page 158 Setting preferences for organizing import statements in the EGL editor EGL can automatically organize the import statements in your code.myPart3. 5. the editor will simplify these import statements into the following single import statement: import com. click New and type the new name. Also. import com. You can always perform these tasks. 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. From the main menu.mypackage. In the Number of imports needed field. EGL removes unnecessary import statements from your code.mypackage. Click OK to save the changes and exit the window. You can use the asterisk character as a wild card at the end of the package name.myPart2. set the order for import statements in the list of package names: v To add a new package or prefix to the list. expand EGL → Editor and click Organize Imports. 2. right-click the file. Related tasks “Enabling EGL capabilities” on page 11 Capabilities keep the workbench menus from becoming cluttered by hiding items you do not use. Organizing import statements involves reordering and grouping the statements by the package name. Related concepts “Preferences” on page 172 EGL preferences affect the way the workbench displays and works with EGL. From the main menu. The results are shown in the Preview box. Repeat the steps for each type of text. Click the box next to the Color label. click Window → Preferences. To set a color. You can always perform these tasks. Related tasks “Enabling EGL capabilities” on page 11 Capabilities keep the workbench menus from becoming cluttered by hiding items you do not use. d. Custom Click the radio button to select a color from the color palette. You can also make the data bold. 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. Element Select the color for each element of source data in your file. 2. 3. The color palette is displayed when clicking the button next to the Custom label. click OK to save your choice. you must enable the capability for that area of functionality. Setting preferences for source styles You can change how EGL code is displayed in the EGL editor: 1. 4. expand EGL → Editor and click Source Styles. Click OK to save the changes and exit the window. Click the check box for the Bold field to bold the text. “Setting preferences for the EGL editor” on page 175 “Setting preferences for EGL text” on page 180 Working with EGL code 179 . Click Apply to save the changes and remain in the Preference window. Select the desired color and click OK. After you have selected a color. c. The color is shown in the Preview field. b. Select the type of text in the Element list. A color palette is displayed. From the navigation tree. “Setting general preferences” on page 173 “Setting preferences for the EGL debugger” on page 604 This topic tells you how to change your preferences for the EGL debugger. Related concepts “Preferences” on page 172 EGL preferences affect the way the workbench displays and works with EGL.“Setting preferences for the EGL editor” on page 175 “Setting preferences for folding in the EGL editor” on page 176 Folding enables you to collapse blocks of code in the EGL editor to hide them. follow these steps: a. but to make them appear in the menus. Click OK to save the changes and exit the window. 5. 3. click Window → Preferences. Auto generate If you select the check box next to a type of part. In the Colors and Fonts window. In the Generation window. follow these steps: From the main menu. Introduction to EGL generation Related reference destUserID destPassword Setting preferences for EGL text To change how text is displayed in the EGL editor. 180 EGL Programmer’s Guide . expand EGL and click Generation. Clearing these check boxes improves workbench performance because you will not have to wait for EGL to generate the parts each time you save.“Setting the fonts used in the EGL editor” on page 176 The EGL editor uses the fonts and colors from the general preferences in the workbench. follow these steps: 1. if you clear the check boxes. you can set the following preferences: Build before generate If you select this check box. In the navigation tree. EGL builds the project automatically prior to generation if it has not been built since the last change. Setting generation preferences To 1. 4. type the user ID and password for the computer on which the generated code is saved. However. click Window → Preferences. 3. 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. expand EGL in the tree and then click EGL Editor Text Font. Generation Destination User Information If you are generating code to a computer other than this one. From the main menu. 2. specify preferences for EGL generation. This preference takes effect only when the workbench is not set to build the project automatically. Related concepts “Preferences” on page 172 EGL preferences affect the way the workbench displays and works with EGL. expand General → Appearance and then click Colors and Fonts. EGL will generate that part automatically each time you save a file that contains that type of part. you must remember to generate the appropriate files manually before running your application. Click Apply to save the changes and remain in the Preference window. Click Change. 4. 2. 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. From the navigation tree. When you are finished making your selections. Type or select a font size in the Size field. click the Reset button. To use the default workbench font. To use the default operating system font. 8. v v v v You can see a preview of your selections in the Sample section. Related tasks “Setting preferences for the EGL editor” on page 175 “Setting preferences for source styles” on page 179 Working with EGL code 181 . 7. click the Restore Defaults button. click the Use System Font button. 9. v Select the Underline check box if you want a line under the text. Type or select a color in the Color field. Select the Strikeout check box if you want a line to run through the middle of the text. Click OK to save the changes and exit the window. click OK. Click Apply to save the changes and remain in the Preference window. 6.Type or select a font style in the Font style field. To set the font for all editors (not just the EGL editor) to the default workbench font. 182 EGL Programmer’s Guide . the information in a relational database resides in tables that can refer to each other. In very simple terms.Accessing data with EGL code If your program is going to store any of the information that it works with. 1996. Oracle. IMS is an example of a hierarchical database manager. In the mainframe world. which fetches information and puts it into a record) that focus on business logic rather than implementation details. 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. Related tasks “Reading and writing records” on page 184 “Creating a data access application” on page 208 EGL can create a simple data access application based on a database to which you are connected. “Viewing implicit SQL statements” on page 217 Common data access tasks EGL helps you perform common data processing tasks such as reading and writing to files. If you plan to work with large amounts of information. Some popular types of RDBMS include IBM DB2. A hierarchical database contains a tree-like structure. to communicate with the database manager. which you can talk to through the DL/I language. while protecting you from the implementation details. it is still common to see hierarchical databases. where segments (equivalent to tables) can have a parent segment (only one each) and multiple child segments. called SQL. it needs to use a file. and the open-source MySQL. You use a special language. typically you use a database or other type of data source for storage and retrieval. For an overview of how this works. Common processes include: © Copyright IBM Corp. The resulting application contains data parts. Microsoft® SQL Server. 2008 183 . 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. logic parts and (optionally) Web pages that are based on one or more database tables. see “Reading and writing records” on page 184. including plain sequential access files and indexed files (which keep track of data by means of a key). A relational database management system (RDBMS) keeps track of the tables and relationships. 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. The goal of information processing is to transform data (raw facts and figures) into information (data that means something and increases knowledge). The EGL strategy is to provide a few basic commands (like get. Related concepts “Creating reports with EGL” on page 531 EGL offers different ways to create reports.” 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. a stereotype is a common pattern that you can use to characterize an individual. 184 EGL Programmer’s Guide . when you apply a stereotype to a record.” Reporting and analysis EGL can present reports that include everything from checks and invoices to general ledgers and Web statistics. CRUD functions in EGL CRUD function Create Read Update Delete EGL keyword add get replace delete Furthermore. 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. 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 tailors the way it executes each of these functions based on the particular type of file with which you are working. and message queues. EGL uses the JasperReports open-source reporting package to provide this functionality. and making adjustments to inventory and customer balances. For more details. The following table shows the CRUD functions and the EGL keywords that provide those functions: Table 29. if you write a get next statement for a SQL database. using external engines to generate the report contents. In everyday use. see “Introduction to Record parts” on page 100 and topics that focus on the specific stereotypes in the EGL Language Reference.Retrieval EGL uses the get statement (and its variants) to read data from files. For example. For more details. For more on stereotypes. see “Reading and writing records. you tell EGL how it should perform I/O functions that involve that record. see “Creating reports with EGL” on page 531. For more details. databases. EGL accomplishes these tasks by means of stereotyping. see “Reading and writing records. generating picking tickets for your warehouse. For example. In much the same way. Storage EGL uses the add and replace statements to modify existing data in storage. you might be receiving orders from a Web site. Typically this means some kind of ID number. Assume that you have separately written a function called showCustomer() that returns a –1 if the user wants to delete the record. The following general scenario is possible only because EGL is so efficient at shielding you from implementation details. The forUpdate keyword tells EGL to place a hold on the data so you have the option to replace or delete it. you can do a bit more with the number that getCustomer() returns. 0 if the record is unchanged. often used as a key to the file. and 1 if the user made any changes to the record: case (showCustomer(myCustomer)) when (-1) delete myCustomer. update. which you must do outside of a generatable part: package com. simply code the following: get myCustomer forUpdate. Assume that you have separately written a function called getCustomer() that asks the user for a customer number and returns that number: myCustomer.companyb. You can then offer the information to your user with the option to change it. More specific examples are presented in the topics that deal with specific data access technologies. and its properties. Next. To read the information that matches the requested number. you will need a unique piece of information about the record.customer Record CustomerRecord type Stereotype customerNumber INT. declare a variable based on this Record part: myCustomer CustomerRecord. end The details of the record. within the body of your program. will vary depending on how you plan to use it.The I/O processing cycle Assuming that you have an existing database (typically created by a database administrator). A key is a piece of data used to index a file. EGL generates the appropriate code to read the data from the file or database and then places the information in your record variable. end If you handle errors (see “Handling errors” on page 148). To find an existing customer record. when (1) replace myCustomer. 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 185 . regular processing generally involves the create. customerName STRING. customerBalance MONEY.customerNumber = getCustomer(). Start by defining a Record. so you don’t have to look at every record to find the one that you want. and delete (CRUD) functions. read. Add a resource associations part to the build descriptor and open that part in the build parts editor.″ 3. 1. A Record part can contain any number of fields. the process of connecting to the data source is different. but this example uses a local file. The data parts within the Record part are referred to as fields. sequential files. See ″Adding a resource associations part to an EGL build file. // sets cust # try get myCustomer forUpdate. // all fields blank or 0 myCustomer. such as sequential or comma-separated value (CSV) files. These types of files differ mostly in the way they store information to the file.set myCustomer empty. including indexed files. end else myErrorHandler(ex). 2. The only difference in your program between VSAM and SQL is the stereotype you apply to the CustomerRecord definition. EGL allows you to write and read several types of files. Open the project’s build descriptor. you can decide how your program behaves in case of errors. The file itself can be a data set as well as a file on your system. you must first define a resource associations part that points to that file. 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. and you are restricted to particular variations of the EGL data access statements. Prerequisites v An EGL project Setting up a resource association To connect to a file. and comma-separated value (CSV) files. In the new resource associations part. or other records. also known as delimited files. add a new association to the location where the sequential file will go: 186 EGL Programmer’s Guide . Related tasks “Handling errors” on page 148 With EGL. the process of reading the file and writing to the file is similar for each type. Related concepts “Introduction to Record parts” on page 100 Record parts are collections of other data parts. // let user fill in remaining fields add myCustomer. data items. onException (ex AnyException) // couldn't get the record if(myCustomer is noRecordFound) // because customer # not on file if(getReply("Do you want to add this customer? (y/n)") == TRUE) showCustomer(myCustomer). and the fields can be primitives. Writing and reading to files Reading and writing to files.customerNumber = getCustomer(). However. is similar to writing and reading records in any other type of data source. This topic deals with sequential files and CSV files. 4. For more information on resource associations parts. Define a Record part to represent the records that will be stored in the file. 10 myChar char(50). this field corresponds to the value of the fileName property of serial record parts that use this file. For example. EGL will create the file when you write to it. see the EGL Generation Guide. b. For example. e. type a mnemonic for the sequential file that conforms to EGL naming requirements. Set the System field to the type of system you are using.a. You might need to use an import statement to bring it into scope: Accessing data with EGL code 187 . 2. Set the fileName property to the value of the File Name field in the resource association part entry: record mySerialRecord type serialRecord {fileName = "myFile"} 10 myInteger int. Open an EGL program or other logic part. end 6. This field is not the name of the actual file on disk. 1. Set the value of the resourceAssociations build descriptor option to the name of the resource associations part.dat If you point to a file that does not exist. if you want to use a sequential file. A new entry is displayed under Association elements. Set the File type field to seqws to represent a sequential record. Writing to the file Writing to a file is similar to writing to any other data source. 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. c. with your own values in the fields: f. in a Windows operating system. Save and close the resource associations part. The resource associations part looks like this. such as myFile. Set the systemName field to the fully qualified location of the file. 5. define a serialRecord: record mySerialRecord type serialRecord 10 myInteger int. In the File Name field of the new entry. such as win for Windows or linux for Linux. systemName should be set to something like this: C:\myFolder\myFile. d. click the Add Association button. end Now you can use the record part in your code to access the sequential file. 10 myChar char(50). In the resource associations part. myInteger = 45. The program reads the sequential file and displays the data from the record in the console: Hello! Using CSV files One of the advantages of CSV files is that they are human-readable. get next begins with the first record in the sequential file and reads the records in order. 1.writeStderr(variableRecord.no . and run the program.import myProject. In an EGL program. 3. as indicated by no data between the delimiters. delimiter = ". In general.myData. Save. Each piece of information is separated by a character called a delimiter.myData.Jorge 92. A CSVRecord for this file would look like this example: record CsvRec type CSVRecord { fileName = "CSVFile". generate. 188 EGL Programmer’s Guide . Save. 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. Note that the third piece of data in the third line is null. 5. Open an EGL program or other logic part.".mySerialRecord. Use an appropriate EGL data access statement. 4. In an EGL logic part. 5. and run the program. Here is a simple example of a CSV file: 123. 4. You might need to use an import statement to bring it into scope: import myProject. CSVRecord parts treat each of these pieces of information as a field. except that you must read the records in order.myChar = "Hello!". 2.yes. use the get next statement to read a single record and the get statement to read multiple records when you deal with serial records. Retrieve a record from the sequential file using the variable: get next variableRecord. Use the data from the sequential file: sysLib. 6. Add data to the fields in the new variable: variableRecord. declare a variable that is based on your serial record: variableRecord mySerialRecord.mySerialRecord.9/9/1999.Rahima -1. such as add to write the record to the file: add variableRecord.yes.Ludmilla This example shows three lines of data. In this context. generate. variableRecord. in this case a comma. Reading from the file Reading data from a sequential or CSV file is similar to reading from any other data source.3/9/2007.myChar). The new record is written to the end of the sequential file. 6. 3. each with four pieces of information. declare a variable that is based on your serial record: variableRecord mySerialRecord.. function main() //get the first record get next oneRecord. The textQualifier and style properties are closely related."). Related tasks Adding a resource associations part to an EGL build file Related reference resourceAssociations Resource associations part SerialRecord stereotype CSVRecord stereotype Specifying database options at project creation This topic tells you how to specify SQL database options at project creation. style = CsvStyle. get next oneRecord. firstName string. If you saved the example of a CSV file above to a file and created a resource associations element to point to it. Accessing data with EGL code 189 .quoted } jobCode int. else while (oneRecord not endOfFile) //perform this action for each record found SysLib. this configuration indicates that strings in the file can be enclosed in quotes if they contain reserved characters. The delimiter property indicates the character that separates each piece of information. You can write to the CSV file with the add statement in the same way. end end end end This program reads from the file in the same way as the previous examples that used the sequential record. you could use this record to read from and write to the file using a program like this: program readCSV type BasicProgram {} oneRecord CsvRec. the CSVRecord has some additional properties. permStatus char(3). However.writeStdout("This file is empty. in this case a comma. it refers to an element in a resource associations part that points to a file. using the get next statement.firstName). end The fileName field performs the same purpose as the serialRecord. hireDate date?. See CSVRecord stereotype for more information. if (oneRecord is endOfFile) //if there are no records SysLib.textQualifier = "\"".writeStdout(oneRecord. see Sample: EGL LDAP access. Click OK to close the Project Build Options window. The keystroke details for an existing project are as follows: 1. Click Next. 10. Accessing an LDAP-compliant server EGL provides a code sample that you can customize to retrieve security or other details from a server accessed by way of Lightweight Directory Access Protocol (LDAP). 2. When you are creating a new EGL project whose code will access an LDAP-compliant server. 3. Open the New EGL Project window: a. Click OK. Similarly. Give the project a name and select a type of project. Click Next. clear the Use Default SQL Connection check box. Finish setting options for the project as explained in “Creating an EGL project” on page 71. 3.egl and LDAPLib. select the EGL project feature EGL with LDAP Support by updating an Advanced Setting. The effect in each case is to add the server-access files LDAPExternalTypes. Expand EGL and click EGL Project Wizard. Click File → New → Other. under Build Descriptor Options. 9. EGL provides two options in dealing with SQL data. SQL databases are the workhorses of the computer world. Related tasks “Creating an EGL project” on page 71 This topic covers how to create an EGL project. A relational database maintains information in interconnected tables. 7. 8. Click Options. In the Properties window. add the EGL project feature EGL with LDAP Support from the Properties of the project. In the Project Explorer view.egl to the project. 6. For more information about LDAP. when you are adding LDAP support to an existing project. Create a database connection as explained in ″The New Connection Wizard″ in “Creating an SQL database connection” on page 197. Select the EGL with LDAP support check box 4. 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. click EGL Project Features. right-click the project and then click Properties. 2. On the next page of the wizard.1. b. In the Project Build Options window. 4. If you are doing fairly common and straightforward tasks. c. 5. Select the connection you created earlier from the Connection list. you can simply use EGL statements to perform 190 EGL Programmer’s Guide . click Create new project build descriptor(s) automatically. Topics in this section will show you how to connect EGL to your SQL database (see “Creating an SQL database connection” on page 197). You can access the SQL statements that EGL generates from your EGL code and modify them (see “Viewing implicit SQL statements” on page 217). add. Use explicit SQL through the execute #sql statement.customer_ID } Derived data in SELECT command (such as MAX() or AVG()) Use explicit SQL through the #sql directive. then create use the defaultSelectCondition property to correctly join the tables on primary and foreign keys. DELETE). Use explicit SQL through the #sql directive. Dynamic SQL (prepared SQL statement). Best practices for EGL SQL SQL objective Simple SQL data manipulation (SELECT. Use the Retrieve SQL feature in the workbench. With EGL.customer_ID = orders. delete) and let EGL generate implicit SQL. Use explicit SQL through the execute #sql statement. placing the derived fields inside the braces. Primary key controls WHERE and ORDER BY. add. Use explicit SQL through the execute #sql statement. SQL statements other than simple data manipulation (such as CREATE TABLE). In the second option. In this case EGL creates all the actual SQL statements for you. Simple SQL data manipulation with reusable Place the custom WHERE clause in the custom WHERE clause. SQL SELECT statements with custom WHERE clause. Stored procedure. replace. you can even combine the two styles. EGL approach Use EGL keywords (get. Best practices The following table shows where to use each of the EGL SQL techniques: Table 30. where the column property for the individual fields specifies the derived or computed expression. Use EGL replace. as in the following example: defaultSelectCondition = #sqlCondition{ customer. INSERT.all your I/O operations (see “Reading and writing records” on page 184). Create a custom SQLRecord. Complex or custom SQL UPDATE. or delete statements with explicit SQL (#sql directive). defaultSelectCondition property. SQL table JOIN statement. as well as shortcuts for creating SQL records (see “Retrieving SQL table data” on page 205) and complete SQL applications (see “Creating a data access application” on page 208). or DELETE statement. UPDATE. you can use a #sql directive to include your own SQL statements in your EGL code. INSERT. Use explicit SQL such as the following: open result_set with #sql{ CALL stored_proc ( :host_var) } Accessing data with EGL code 191 . Do the following in a forEach loop: a. The statements that open the cursor and that act on the rows of that cursor are related to each other by a result-set identifier.sqlData. 192 EGL Programmer’s Guide . delete. select Validate SQL from the context menu. and you reference the same identifier in the forEach statement that creates the loop. Commit changes by running the EGL commit() function. and replace statements that affect an individual row. Fetch a row by running an EGL get next statement. then initiate a loop with one of the following statements: v forEach (from result_set) v while (sqlLib.empname :: " " :: "III". You also reference the identifier in the get next.sqlcode == 0) Programmatic paging for online searches. 2. 4. Fetch another row by running an EGL get next statement. Update or delete the row by running an EGL replace or delete statement. You can use a specialized type of EGL record. Run interactive SQL using the SQL Editor in the workbench Data Perspective. The following example shows how to update a series of rows when you are coding the SQL yourself: try open selectEmp forUpdate for emp. to hold the information that you read from or write to a relational database. SQL statement validation Use the Data Access Application wizard. EGL hosts the SQL statements). // exits program end foreach(emp) emp. Result-set processing A common way to update a series of rows is as follows: 1. 3. c. EGL approach Use the EGL open command to open the result set. In the EGL editor. Best practices for EGL SQL (continued) SQL objective Processing of individual rows of the result set from a SQL SELECT statement. A host variable is a variable in an SQL statement with the same name as a variable in the host language (in this case. try replace emp. b.Table 30. onException(sqlx SqlException) myErrorHandler(sqlx). Use the Table Editor in the workbench Data Perspective.empname = emp. that option causes the selected rows to be locked for subsequent update or deletion. Retrieve data from the result set into the host variables. You specify that identifier in the open statement that opens the cursor. the SQLRecord. which must be unique across all result-set identifiers and program variables within the program. Declare and open a cursor by running an EGL open statement with the forUpdate option. Addition of data to SQL table. with an additional initial colon character (:). as well as on the close statement that closes the cursor. you can use the hold statement option. In this case. Define an SQLRecord part and the related record You define an SQLRecord part and associate each of the fields with a column in a relational table or view. SQL records and their uses After you define an SQLRecord part. After the EGL statement runs. Only fields of a primitive type can represent a database column. the record variable contains information about error conditions: try add myEmpRecord.commit(). v Accept the default behavior of the EGL statements (which should give you what you want in most cases) or make SQL changes that are appropriate for your business logic. onException(sqlx SqlException) if (myEmpRecord is unique) // if a table row had the same key myErrorHandler(sqlx). If you want to commit changes periodically as you process an EGL open statement (regardless of whether you use SQL records). you declare a variable based on that part. EGL inserts the data from myEmpRecord into EMPLOYEE. which maintains cursor position after a commit. the hold option has no effect because a converse in a segmented program ends the CICS transaction and prevents the program from retaining any file or database position. If the variable myEmpRecord is based on an SQLRecord part that references the database table EMPLOYEE. You can then use this record variable to access a relational database as though you were accessing a file. however. for example. you can include primitive fields as well as other variables. The presence of each represents a one-to-one relationship between the parent and child tables. If the SQLRecord part is not a fixed record part. // exits program end end // end while. The presence of each represents a one-to-many relationship between the parent and child tables. EGL can do this for you automatically. Accessing data with EGL code 193 .onException(sqlx SqlException) myErrorHandler(sqlx). You are especially likely to include the following kinds of variables: v Other SQL records. end end A record variable like myEmpRecord allows you to interact with a relational database as follows: v Define an SQLRecord part and declare the related record variable. you can use myEmpRecord in an EGL add statement: add myEmpRecord. If a program targeted for CICS is segmented. v Arrays of SQL records. cursor is closed automatically // when the last row in the result set is read sysLib. v Write EGL statements that perform I/O using the SQL record. see “Retrieving SQL table data” on page 205. if any. you might declare a variable based on the following SQLRecord part: Record Employee type sqlRecord { tableNames = [["EMPLOYEE"]]. If your record variable includes a field for which no table column was assigned. empname FROM EMPLOYEE WHERE empnum = :empnum EGL also places an INTO clause into the standalone SELECT statement (if no cursor declaration is involved) or into the FETCH statement associated with the 194 EGL Programmer’s Guide . EGL provides an implicit SQL statement. declare a variable based on this Record: myEmpRecord Employee. but not of type BLOB. The implicit SQL SELECT statement is as follows: SELECT empnum. EGL forms the implicit SQL statement on the assumption that the name of the field is identical to the name of the column.) For example. an implicit SQL INSERT statement places the values of the fields in the given record into the associated table column. Then. Writing SQL-related EGL statements You can create a set of EGL statements that each use the record variable as the I/O object in the statement.If level numbers precede the fields. the SQLRecord part is a fixed record part. you might code a get statement: get myEmpRecord. end Next. CLOB. For each statement. The following EGL statements correspond to the SQL statements shown: Table 31.0). The following rules apply: v The structure in each SQLRecord part must be flat (without hierarchy) v All of the fields must be primitive fields. open replace SQL statement INSERT DELETE SELECT UPDATE Using implicit SELECT statements: When you define an EGL statement that uses a record variable and that generates either an SQL SELECT statement or a cursor declaration. or STRING v None of the record fields can be a structure-field array After you define an SQLRecord part. for example. keyItems = ["empnum"] } empnum decimal(6. you declare a record variable that is based on that part. empname char(40). Implicit SQL statements EGL statement add delete get. (That statement is embedded in the cursor declaration. EGL provides an implicit SQL SELECT statement. In the case of an EGL add statement. which is not in the source but is implied by the combination of record variable and EGL statement. Customizing the SQL statements Given an EGL statement that uses an SQL record variable as the I/O object. any cross-statement relationship that is indicated by a result-set identifier takes precedence over a relationship indicated by the record variable. However. see individual keyword topics in the EGL Language Reference. In this case. much the same way as you can by using a result-set identifier. and has a search criterion (a WHERE clause) that depends on a combination of two factors: v The value you specified for the defaultSelectCondition record property. Example of using a record in a record To allow a program to retrieve data for a series of employees in a department. In this case. changes made to the SQLRecord part affect the SQL statements used at run time. Using SQL records with cursors: When you are using SQL records. EGL changes the implicit SELECT statement used in any cursor declaration that is based on that SQLRecord part. you can create two SQLRecord parts and a function. and any subsequent changes made to the SQLRecord part have no effect on the SQL statement that is used at run time. In addition. you can relate cursor-processing statements by using the same record variable in several EGL statements. managerID CHAR(6). for example. the details of that SQL statement are isolated from the SQLRecord part. employees Employee[]. you can progress in either of two ways: v You can accept the implicit SQL statement. v You can choose instead to make the SQL statement explicit. If an EGL statement opens a cursor when another cursor is open for the same record variable. the implicit SQL statement (if any) is again available at generation time. references the tables specified in the record variable. and in some cases you must specify a resultSetID. the generated code automatically closes the first cursor. as in the following example: DataItem DeptNo { column = "deptNo" } end Record Dept type SQLRecord deptNo DeptNo. If you remove an explicit SQL statement from the source. If you later indicate that a different field is to be used as the key of the SQL record. only one cursor can be open for a particular record variable. For details on the implicit SELECT statement.cursor. The INTO clause lists the host variables that receive values from the columns listed in the first clause of the SELECT statement: INTO :empnum. :empname The implicit SELECT statement reads each column value into the corresponding host variable. v A relationship (such as an equality) between two sets of values: – Names of the columns that constitute the table keys – Values of the host variables that constitute the record keys EGL infers the relationship from the tableNames record property or the usingKeys clause of the EGL statement. EGL can insert the implicit SQL statements into your code for you so you can modify them. end Accessing data with EGL code 195 . Linux. end To test for a null value. or Microsoft SQL Server Related tasks “Creating an SQL database connection” on page 197 The New Connection wizard creates an SQL database connection that you can use either at design time or at run time. as in this example: Record Employee type SQLRecord employeeID CHAR(6). end You can directly assign a null value to a variable: myEmpRecord.empDeptNo == null) .employees usingKeys myDeptRecord. end Testing for and setting NULL If you want a variable to be nullable. logic parts and (optionally) Web pages that are based on one or more database tables. Compatibility Table 32. end Function getDeptEmployees(myDeptRecord Dept) get myDeptRecord.. In that case. “Viewing implicit SQL statements” on page 217 196 EGL Programmer’s Guide . HP-UX. Windows 2000/NT/XP Issue The generated code can access DB2 UDB directly JDBC provides access to DB2 UDB.Record Employee type SQLRecord employeeID CHAR(6). z/OS UNIX® System Services. Oracle. The syntax works even if the target is not nullable. that is. the statement has the same effect as the following statement: set myEmpRecord.empDeptNo empty. empDeptNo INT?. Solaris. iSeriesC AIX. iSeriesJ. as in the following example: if (myEmpRecord. “Reading and writing records” on page 184 “Retrieving SQL table data” on page 205 “Creating a data access application” on page 208 EGL can create a simple data access application based on a database to which you are connected.empDeptNo = null.. Informix. declare the variable with the ″?″ type extension character. Compatibility considerations for SQL Platform CICS for z/OS.deptNo. The resulting application contains data parts. use a standard EGL if statement. empDeptNo DeptNo. z/OS batch. to be able to accept a null value. Prerequisites You must have a database set up and running. you have everything you need to use the EGL features that require a design-time connection. check your settings or work with your database administrator to resolve the problem. see “Supported SQL database managers” on page 200.connectionService() system function. the Test Connection button becomes available. v Right-click an EGL project and then click Properties. you can access the New Connection wizard from many of the places where an SQL connection is required. The workbench provides several places to find the New Connection wizard: v From the workbench menu. In the Properties window. Click this button to verify your connection information. by default in the lower left corner of the workbench. If you get an error message. Note: The Data perspective is not filtered for EGL. see connect(). Even if you plan to use either of these functions. click Window → Preferences → EGL → SQL Database Connections. To the right of the list labeled Connection. you might see databases listed (such as Generic JDBC or Sybase) that EGL does not support. EGL offers two other ways to create an SQL connection: v The sqlLib. The database must be one of the products that EGL supports. for programs migrated from VisualAge Generator or EGL version 5. The Database Explorer view is available in this perspective. See “Supported SQL database managers” on page 200 for more information. and includes information for other products. Right-click Connections and pick New Connection from the menu. Opening the New Connection wizard In EGL. If the test is successful. When you have given the wizard enough information. see connectionService(). The information the wizard needs varies with the type of database that you use.connect() system function. v The vgLib. it is still recommended that you have a default connection in place. however. click EGL Runtime Data Source and then click New. v Open the Data perspective (Window → Open Perspective → Other → Data). such as “Creating a data access application” on page 208 or “Retrieving SQL table data” on page 205. to activate a connection at run time. Accessing data with EGL code 197 . Thus if you run the New Connection wizard from the Data perspective. When you choose from the Select a database manager list. You are not. Use the table in ″Supported database managers″ to determine the database managers that you can use with EGL. For the list of supported databases and the information that each requires.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. click the button labeled New. the wizard fills in as many default values as it can. Creating the new connection Once you have opened the New Connection wizard as explained above. Select or clear the check boxes next to the schemas in the list. On the Filter page. 2. 3. d. Clear the Disable filter check box. 5. If you do not want to filter schemas out of the connection. If you want to filter schemas out of the connection. you can select the Expression radio button and enter a search string to indicate which tables should be included. For this reason. you can click Test Connection to make sure that the connection is working. To specify that connection. the New Connection wizard will retrieve information for each schema in the database and each table in each of those schemas. such as the SQL retrieve functionality described in “Retrieving SQL table data” on page 205. In the list under Selection. you can start filling in the information: 1. fill in the remainder of the fields on the page. Under Select a database manager. Alternately. click Finish. you can select schemas from the database to be included or ignored in the connection. such as ″IBM DB2 Universal.automatically set up to have an SQL connection at run time. depending on whether you want to select the schemas to include or the schemas to exclude from the connection. 4. Click the Selection radio button. you can save time by filtering out schemas or tables that you do not want to use with the Data Access Application wizard. Schemas that you filter out of the connection will not be available if you use this connection with the Data Access Application wizard. The EGL Data Access Application wizard requires this connection information to produce parts from the database. Retrieving this information can take time on large databases. 7. Click Finish. You should do this step first because the remainder of the fields on the page depend on this choice. 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. When you have filled out the fields in the wizard. follow these additional steps: a. Which fields you need to fill in depends on which database you are connecting to. e. The schemas in the database are listed below. select the type and version of database you are connecting to. 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. Click Next. see “Using an SQL database connection at run time” on page 202. By default. select Include selected items or Exclude selected items. c. You must select at least one schema.″ 198 EGL Programmer’s Guide . but the other areas of EGL design-time access functionality. See “Fields in the New Connection wizard”for information on the individual fields. Once you have selected the database type. do not require this information. b. and attributes.jdbc.informix.apache.jdbc.JDBC driver class This is the name of the Java class that contains the driver: v For IBM DB2 Universal Driver. 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.SQLServerDriver v For Derby. The host name of your database server.derby.OracleDriver v For the Informix JDBC NET driver. the driver class is COM. for SQL Server 2000.zip file.DB2Driver v For the Oracle JDBC thin client-side driver. the driver class is com.SQLServerDriver.microsoft.driver. the driver class is com.jdbc.app. Database The name of the specific database to which you want to connect.jdbc. the driver class is oracle.ibm.jdbc. Connection URL This is the address that EGL uses to contact the database. the driver class is com.IfxDriver v For the DataDirect SequeLink JDBC Driver for SQL Server.jar or *. The wizard will complete as many of the other fields as it can.jdbc. for example.db2. the driver class is com. type the fully qualified filenames to the db2jcc.sqlserver. d:\sqllib\java\ db2java.zip file that contains the driver class: v For IBM DB2 Universal Driver.jcc.sqlserver.jdbc. type the fully qualified filename to the db2java. port number.jdbc.microsoft.DB2jDriver v For other driver classes.db2. You can override the default values in these fields by selecting Other for your JDBC driver and specifying the appropriate JDBC driver class. such as ″jdbc:db2://localhost:50000/ SAMPLE:retrieveMessagesFromServerOnGetMessage=true.zip Accessing data with EGL code 199 . Port number The port number that you connect to on the host.jar files v For IBM DB2 APP DRIVER for Windows.SQLServerDriver v For the Microsoft JDBC Driver for SQL Server 2005.ddtek.jar and db2jcc_license_cu.DB2Driver v For IBM DB2 APP DRIVER for Windows. Class location The fully qualified location of the *.EmbeddedDriver v For Cloudscape®.ibm. refer to the documentation for the driver. the driver class is org. the driver class is com.sqlserver. Server The address of your database server.db2j.ibm.″ This URL contains a hostname. the driver class is com. which typically uses the name of your database. SID Host The ID of the server where your database is located. Related tasks “Creating a data access application” on page 208 EGL can create a simple data access application based on a database to which you are connected.jar. and mssqlserver. The resulting application contains data parts. if you require Oracle trace. type the fully qualified filename to the ifxjdbc.jar file v For Cloudscape. you can store the password here. util. and sqlserver. type the fully qualified filenames to the msbase. This information is provided so that you can obtain the right information from a database administrator. Note that the Tomcat server ignores the userID and password that you provide here and uses the values from its server configuration.jar file v For the DataDirect SequeLink JDBC Driver for SQL Server.jar. Password If your database is password protected. type the fully qualified filenames to the base. you can store the user ID here. if necessary. Note that the Tomcat server ignores the userID and password that you provide here and uses the values from its server configuration.jar or. set options in the J2EE deployment descriptors based on information in the connection. logic parts and (optionally) Web pages that are based on one or more database tables. d:\Ora81\jdbc\lib\ojdbc14. 200 EGL Programmer’s Guide . for example. “Retrieving SQL table data” on page 205 “Using an SQL database connection at run time” on page 202 To use an SQL connection at run time. ojdbc14_g. Supported SQL database managers The following table provides a list of the SQL databases that EGL supports. the New Connection wizard requests some or all of the information in the right column. “Editing or deleting an SQL database connection” on page 205 Related reference “Supported SQL database managers” The following table provides a list of the SQL databases that EGL supports. type the fully qualified pathname to the ojdbc14. For more information about these connection fields. refer to the documentation for the driver User ID If your database is password protected. see “Fields in the New Connection wizard” on page 198.jar v For the Informix JDBC NET driver.jar file v For other driver classes. msutil.v For the Oracle THIN JDBC DRIVER.jar files v For the Microsoft JDBC Driver for SQL Server.jar.jar files v For Derby.jar file.jar. type the fully qualified filename to the db2j. you must point to the connection from your project’s build descriptor and. for EGL Web projects. type the fully qualified filename to the derby. To create a connection. 0. 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 DB2 UDB iSeries V5R2.Table 33. 10. V8.2.1 v JDBC driver v Database location v JDBC driver class v Class location v Connection URL v User ID v Password Accessing data with EGL code 201 . V5R3. Supported databases Database Manager Cloudscape Versions 5.1. V8 (Compatibility v JDBC driver Mode or v Host New-Function Mode) v Port number v JDBC driver class v Class location v Connection URL v User ID v Password Derby 10. V5R4 v JDBC driver v JDBC driver class v Class location v Connection URL v User ID v Password DB2 UDB zSeries® V7.1 Setup Information v JDBC driver v JDBC driver class v Class location v Connection URL v User ID v Password DB2 UDB V8. 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 SQL Server 2000. 10.Table 33.3. set options in the J2EE deployment descriptors based on information in the connection.2. you must point to the connection from your project’s build descriptor and. The resulting application contains data parts. logic parts and (optionally) Web pages that are based on one or more database tables. 9. Supported databases (continued) Database Manager Informix Versions 9.0 Setup Information 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. 202 EGL Programmer’s Guide . Using an SQL database connection at run time To use an SQL connection at run time. 2005 v JDBC driver v Host v Port number v JDBC driver class v Class location v Connection URL v User ID v Password Related tasks “Creating a data access application” on page 208 EGL can create a simple data access application based on a database to which you are connected.4. “Creating an SQL database connection” on page 197 The New Connection wizard creates an SQL database connection that you can use either at design time or at run time. for EGL Web projects. 9. Prerequisites You will need a working connection to an SQL database. set Update default build options for project when runtime data source is modified to Prompt or Always. Now the project can use the data source through the JNDI name. 4. see “Fields in the New Connection wizard” on page 198. If the Web project is not a module within an EAR project. Refer to the server documentation for how to create a JDBC data source. Through the project’s EGL Runtime Data Source property page. see “Creating an SQL database connection” on page 197. When you select a connection. EGL creates a JNDI name for the connection. 2. select Load values from a data tools connection and select your database connection in the Connection list. For information on the individual fields. this name is the name of the database connection plus the prefix jdbc/. On the EGL Runtime Data Source page. you must associate the JNDI name with a database on the server manually. In the Properties window. To edit these values. By default. or you can create one in the process. Now. v EGL adds a reference to the JNDI name in the project’s Web deployment descriptor. Accessing data with EGL code 203 . This data source associates the JNDI name with the database itself. For instructions on setting up this connection. you need to set options in the project based on the information in the connection. EGL adds a data source to the EAR project’s deployment descriptor. as long as the EAR project or server links that JNDI name to a data source. you can select Input/modify values manually and edit the values in the fields. Creating the runtime connection for EGL Web projects For EGL Web projects. You can also click New and create a new connection. EGL can do much of this work for you automatically: v EGL updates the following build descriptor options in the project’s master build descriptor: – dbms – sqlDB – – – – – sqlID sqlJDBCDriverClass sqlJNDIName sqlPassword sqlValidationConnectionURL Whether EGL updates the build descriptor options or not depends on the build descriptor preferences. click EGL Runtime Data Source. as explained in “Setting build descriptor preferences” on page 174. Right-click your project and then click Properties. see “Creating an SQL database connection” on page 197. other projects acting as modules within this EAR project can access the database through the JNDI name. EGL uses the information in that connection to fill in the fields on the page. 1. 3. You can accept the default or edit the JNDI name field. If you want EGL to update your build descriptor options. v If the Web project is acting as a module of an enterprise application resource (EAR) project. In addition to the information from the database connection. for information on creating the connection. 6. EGL automatically updates the build descriptor options based on the connection information. even though you specified a Class location in the New Connection wizard.eglbld. Related tasks “Creating an SQL database connection” on page 197 The New Connection wizard creates an SQL database connection that you can use either at design time or at run time. see “Creating an SQL database connection” on page 197.5. 3. 2. Click the Libraries tab on the Java Build Path page. Error conditions EGL uses a different process to connect with the database at run time than it does at design time. When you select a connection. If the preference is set to Never. Creating the runtime connection for EGL projects 1. Click OK to make the updates to your project. 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. Right-click on your project name in the Project Explorer view and click Properties from the pop-up menu. Generate any parts that use the database connection. “Editing or deleting an SQL database connection” on page 205 204 EGL Programmer’s Guide . Double-click the build descriptor for your project. the build descriptor file is located in the top level of the EGLSource directory of your project and is named project. If the correct class location is not displayed. Select Java Build Path from the left pane of the Properties window. 4. Typically. EGL asks before updating the build descriptor options. If the preference is set to Prompt. If you have not already created this connection. click Add External JARs and add the class and location. The build descriptor opens in the build parts editor. 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. If you do not want EGL to set up a data source in the EAR deployment descriptor associated with this project. 4. make sure the driver is on the classpath for your project: 1. click Input/modify values manually and clear the Deploy database and connection properties when application is run on unit test server. Select the database connection to use from the Load DB options using Connection list. If the Update default build options for project when runtime data source is modified preference is set to Always. You can copy this information from your Connection. 2. no changes are made to the build descriptor options. To correct this error. see “Editing or deleting an SQL database connection” on page 205 . Save the build descriptor and close the window. Retrieving SQL table data With EGL. click Finish. In the Database Explorer view. When you are finished editing the connection. For help. press F1. Click Edit. Select the connection from the Connection list. 4. do as follows: 1. then select Edit Connection. 3. which is the connection that EGL will use to retrieve the table data: a. right-click the database connection. Click Window → Open → Perspective → Other. 2. 2. In the Select Perspective dialog box. To complete the edit. 2. b. Change information in the connection as appropriate.Editing or deleting an SQL database connection Prerequisites v An existing database connection Editing an existing connection To edit an existing database connection. or join. Click Window → Preferences. Click Window → Preferences. 2. see “Supported SQL database managers” on page 200. right-click the database connection. For a list of the required fields for each database type. 5. For details. 6. select the Show all check box and double-click Data. 3. you can edit an existing connection from the EGL preferences: 1. click Finish and then click OK to close the Preferences window. In the Database Explorer view. Alternately. Deleting an existing connection To delete an existing database connection. Related reference “Creating an SQL database connection” on page 197 The New Connection wizard creates an SQL database connection that you can use either at design time or at run time. Expand EGL and click SQL Database Connections. select the Show all check box and double-click Data. view. and then click Delete. To create SQL record fields from the definition of an SQL table: 1. “Supported SQL database managers” on page 200 The following table provides a list of the SQL databases that EGL supports. Ensure that you have set SQL preferences as appropriate. At the Select Perspective dialog. Accessing data with EGL code 205 . Set the default database connection. Step through the pages of the database connection wizard and change information as appropriate. see “Setting preferences for SQL retrieve” on page 220. you can create SQL record fields from the definition of an SQL table. Select Window > Open Perspective > Other. Expand EGL and click SQL Database Connections. do as follows: 1. and the EGL host variable is of the type DBCHAR with a length less than or equal to the length of the SQL column. EGL creates a dataItem part based on the field in the record and uses that dataItem as the field type. If you are working in the Outline view. The number of digits for a DECIMAL variable should be the same for the EGL host variable and for the column. right click the entry for the SQL record and. right-click the field and then click Create DataItem Part. as you develop each SQL record. 4. Compatibility of SQL data types and EGL primitive types An EGL host variable (see “Host variables” on page 211) and the corresponding SQL table column are compatible in any of the following situations: v The SQL column is any form of character data. proceed in this way. click SQL record > Retrieve SQL. Decide where to do the task: v In an EGL source file. including decimal places. Note: You cannot retrieve an SQL view that is defined with the DB2 condition WITH CHECK OPTIONS. click Retrieve SQL. Right-click anywhere in the record. skip to the next step. and then type a table name. or a comma-delimited list of tables. The Outline view shows a hierarchical view of the parts and other EGL code on the page. v The SQL column is any form of number and the EGL host variable is of one of these types: – BIN(4. In the menu. select one of the SQL table entries (usually SQL record with table names). You also can create an SQL record by typing the minimal content.0)/INT – BIN(18. create it: 1) Type R. press Ctrl+Space. and the EGL host variable is of the type CHAR with a length less than or equal to the length of the SQL column. or v In the Outline view.0)/SMALLINT – BIN(9. a. 5. in the pop-up menu. 206 EGL Programmer’s Guide . If you are working in the EGL source file.0)/BIGINT – DECIMAL. If you are working in the Outline view. If you do not have the SQL record. or the alias of a view. with a maximum length of 18 digits.c. 2. and in the content-assist list. v The SQL column is any form of DBCHAR data. as in this example: Record myTable type sqlRecord end b. After you create record fields. as may be easier when you already have SQL records. The connection selected in the Connection list is the default database connection. In the Outline view. you may want to gain a productivity benefit by creating the equivalent DataItem parts for the fields in the record: 1. 2) Type the name of the SQL record. as appropriate if the name of the record is the same as the name of the table. 3. c. Open the record in the EGL editor and then open the Outline view. press Tab. Select your database connection from the Connection list or create a new database connection. content is truncated on the right. No data conversion occurs during data transfer. Default mapping EGL uses a default mapping when it creates records with the Retrieve SQL feature. and the retrieve command uses the SQL-data-type maximum to assign a length. Table 34. To test for truncation. 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. The definition of an SQL table column of the type LONG VARCHAR or VARGRAPHIC. Accessing data with EGL code 207 . EGL variable characteristics SQL data type Primitive type BIGINT BIT BLOB BOOLEAN CHAR CLOB DATE DECIMAL DOUBLE FLOAT GRAPHIC INTEGER LONG VARBINARY LONG VARCHAR LONG VARGRAPHIC NUMERIC REAL SMALLINT TIME TIMESTAMP VARBINARY VARCHAR VARGRAPHIC BIGINT SMALLINT BLOB BOOLEAN CHAR CLOB DATE DECIMAL FLOAT FLOAT DBCHAR INT HEX CHAR DBCHAR DECIMAL SMALLFLOAT SMALLINT TIME TIMESTAMP HEX CHAR DBCHAR EGL variable characteristics Digits/characters Number of bytes n/a n/a n/a n/a 1–32767 n/a n/a 1-18 n/a n/a 1–16383 n/a 65534 >4000 >2000 1-18 n/a n/a n/a n/a 2–65534 ≤4000 ≤2000 8 2 n/a 1 1–32767 n/a 8 1–10 8 8 2–32766 4 32767 >4000 >4000 1–10 4 2 6 14 1–32767 ≤4000 ≤4000 The definition of an SQL table column of the type VARCHAR or VARGRAPHIC includes a maximum length. If character data is read from an SQL table column into a shorter host variable. and the retrieve command uses that maximum to assign a length to the EGL host variable. does not include a maximum length.v The SQL column is of any data type. however. use the reserved word trunc in an EGL if statement. the EGL host variable is of type HEX. The following table shows the default mapping. and the column and host variable contain the same number of bytes. v Data parts based on the table: – An SQLRecord part that represents the table – DataItem parts that represents the columns in the table v Data access functions that perform operations on the database. You can choose to put these parts into a new project or into one or more existing projects. the wizard creates these additional files and parts: 208 EGL Programmer’s Guide . You can choose to put these data access functions in libraries or in services. Also. The resulting application contains data parts. “Setting preferences for SQL database connections” on page 219 “Setting preferences for SQL retrieve” on page 220 Creating a data access application EGL can create a simple data access application based on a database to which you are connected. EGL treats the situation as it would an overflow on an assignment statement. logic parts and (optionally) Web pages that are based on one or more database tables. COBOL generation Related concepts “Accessing data with EGL code” on page 183 “Working with SQL data” on page 190 SQL (pronounced as three separate letters) refers to a language that is designed to communicate with the software that controls a relational database. Compatibility considerations for SQL data Platform Java generation Issue If numeric data is read from an SQL table column into a shorter host variable. you have the option of creating a Web interface for the data access application. a negative SQL code is returned to indicate an overflow condition. retrieving. connect to an SQL database.Compatibility Table 35. Files created for the application For each table that you select. Related tasks “Creating a data access application” EGL can create a simple data access application based on a database to which you are connected. such as adding. logic parts and (optionally) Web pages that are based on one or more database tables. If the number still does not fit. fractional parts of the number (in decimal) are deleted on the right. If the number still does not fit into the host variable. If you choose to create a Web interface. The resulting application contains data parts. leading zeros are truncated on the left. Prerequisites Before you begin. and deleting records. If numeric data is read from an SQL table column into a shorter host variable. the EGL Data Access Application wizard creates the following parts. with no indication of error. See “Creating an SQL database connection” on page 197. which enables the user to display. the tables in the database schema are listed in the Table Name list. including JSF handler parts and Web pages. which enables the user to display or insert one row – A detail page. or delete one row Projects in the application Before you begin creating the application. 3. 2. logic parts. On this page. Data parts. or you can put the files and parts into different projects. either select an existing EGL project or type the name of a new project. v You can put files and parts into a new project or into an existing project. you select the key fields for each table and which fields you want to be able to search.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. If you clear this check box. You cannot remove a key field that is defined in the database. In the Project Name field. Click Next. If you want to create a Web interface for the application. which displays multiple rows. The wizard creates a search page for each table you selected. 5. based on the user’s criteria – A create detail page. see “Creating an SQL database connection” on page 197. For more information. but at least one kind of part will go into the project you specify here. some can go into an existing project and others can go into a new project. select a database connection. In the Database Connection list. 9. Accessing data with EGL code 209 . If you are creating a Web interface. In the Table Name list. 8. logic parts. select the search fields for each table in the Choose search UI fields list. Later. The Define the Fields page has a tab for each table that you selected on the previous page. 4. that field is selected as a key already. After you have selected a database connection. and that search page will have an input field for each field that you select here. If the table already had a key field in the database. You can create a new one by clicking the New button. 7. 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. but no JSF handler parts or Web pages. and JSF handler parts (with the associated Web pages) can all go into separate projects. 10. select the check box next to the tables that you want to include in the data access application. Click File → New → Other. your application will contain logic parts and data parts that enable you to access the database. select the Generate to EGL Web project check box. expand EGL and click EGL Data Access Application. 6. Click Next. Creating the application 1. update. Select the key fields for each table in the Choose key fields list. you will be able to fine-tune where the new data parts. and Web pages will go. In the New window. If you choose to put parts into different projects. based on the kind of file and part. which accepts selection criteria from the user – A list page. If you want to put all of the new files and parts into one project. select whether you want to create library parts or service parts to hold the new data access functions. 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. go back one page and clear the Create multiple projects check box. 21. select Qualify table names with schema. in this case. choose a project. 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. Click Next. Then. Select the fields to show on the search results page by selecting check boxes in the Choose summary fields list. If you want to put all of the files in the same project. you specify only the table name in the EGL code and specify the schema name in a bind step in the JCL. or if you want to create a simple application as quickly as possible. If you select this check box. For each kind of file or part. this value becomes the value of the displayName data item property. Click Next. you will see the Configure the Fields page. The Define alternate project locations page enables you to select separate projects to hold the new data parts. If you want to put the new files and parts into different projects. The value in the Display As column will be that field’s label wherever it appears on a Web page. in this case. the wizard skips ahead to the Define Generation options page. the Configure the Fields page also has a tab for each table that you selected. 18. such as characters from DBCS languages. clear the check box. For most production databases. 20. 14. and Web interface files and parts. or if the table or column names include any characters that are not valid in ANSI SQL. Otherwise. As in previous steps. Whether you select this check box or not depends on how you are connecting to the database. This check box determines whether the EGL code will refer to the database table simply by the table name or by the schema name and the table name. select the Use delimited SQL identifiers check box. Set the display name for each field in the Modify field display name list. the EGL code will use quoted strings for the table and column names. select the Create multiple projects check box and then click Next. If you are creating a Web interface. logic parts. click Finish. select the check box. The Define project creation options page has options for the new projects and packages. clear the Create multiple projects check box. 13. type the name of the top-level package that will contain the new EGL parts. 16. 15. you select how the Web pages will display the data. 12. you specify the schema name in the EGL code to avoid specifying the table name in other places. Under Data access method. v You cannot put all of the files and parts in the same project. On this page. 19. If you want to prefix the names of the tables with the name of the database schema. The default value is the name of the database connection. In the Default package name field. If the names of any of the tables or columns in the database are SQL reserved words. 210 EGL Programmer’s Guide .11. In EGL terms. For most testing databases. Specify additional options about the projects on the next page. 17. C_NAME. EGL accommodates those programmers through the #sql directive. SQL cannot run as an independent language. 23. select a project to hold the new Web pages and JSF handler parts. select a project to hold the new logic parts (services or libraries. not the SQL table. 24.v In the Data Project Name field. Related tasks Accessing data with EGL code 211 .CUSTOMER L1 where C_NUMBER = :myCustomer. however. v In the UI Project Name field. Such variables are called host variables. For each project. v In the Data Access Project Name field. The #sql directive The EGL keyword #sql introduces a section of explicit SQL code. 25. Experienced SQL programmers. You can also use the #sql directive to call a stored procedure (see “Calling a stored procedure” on page 212). select a project to hold the new data parts.customerNumber has a colon in front of it. You can do some reasonably sophisticated database manipulation in EGL without writing a word of SQL. After the projects and files are created. might want the level of control that writing in SQL gives them. The final page of the wizard shows a summary of your choices so far. C_ADDR3. Related reference displayName Working with SQL statements With EGL you can deal with explicit SQL code in your EGL program. depending on your choices on the previous page). Related concepts SQL data access Related tasks “Creating an SQL database connection” on page 197 The New Connection wizard creates an SQL database connection that you can use either at design time or at run time. see “Viewing implicit SQL statements” on page 217. This tells EGL to look for the variable name within the EGL program. You may modify this code to fine tune your SELECT statement. delimited by braces. For more information. You can click Finish and complete the process or go back to previous pages and change your selections. 22. because EGL is the programming language that is hosting SQL. C_ADDR2. Click Next. Host variables You might have noticed in the preceding example that the variable myCustomer. C_ADDR1. you might need to add the projects to the EGL and Java build paths of other projects. select the EGL Web Project field if you want the respective project to be an EGL Web project.customerNumber }. as in the following example: get myCustomer with #sql{ select C_NUMBER. C_BALANCE from ADMINISTRATOR. See “The EGL build path” on page 83. execute p1 using myParameter. use the #sql directive and specify the name of the stored procedure in the explicit SQL: execute #sql{ CALL MYSTOREDPROCEDURE }. you can run that prepared statement with another data-access statement. use execute. pass EGL variables as host variables (see “Host variables” on page 211): myParameter int = 5. “Calling a stored procedure” You can call an SQL stored procedure with the open or execute statements and the #sql directive. a stored procedure can consist of many SQL statements. Also. like a function in EGL. you can execute the same instructions with a stored procedure as you can with a prepared statement. Fundamentally. 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. To call a stored procedure with execute. while a prepared statement can consist of only one SQL statement. The following example uses a prepared statement in combination with the execute statement: prepare p1 from "CALL MYSTOREDPROCEDURE(?)". execute #sql{ CALL MYSTOREDPROCEDURE(:myParameter) }. but in that case any result sets are ignored. You can also use execute to call stored procedures that return one or more result sets. A stored procedure is a set of instructions for a database. however. 212 EGL Programmer’s Guide . Using open to call a stored procedure You can use the open keyword to call only stored procedures that return exactly one result set. Then. To call a stored procedure that does not return a result set or that returns more than one result set. “Viewing implicit SQL statements” on page 217 Calling a stored procedure You can call an SQL stored procedure with the open or execute statements and the #sql directive.“Executing a prepared statement” on page 215 The prepare keyword constructs an SQL statement from a string. If the stored procedure accepts parameters. 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. the procedure has two parameters in addition to the cursor variable: x int = 10. get next from myResultSet into myCustomers. open rs2 with #sql { call p2( ?. A variable based on this type. There are specific rules that apply to using the open statement to call a stored procedure when you use an Oracle database: v The procedure must have at least one parameter. v If the procedure call is in a prepared statement. Special considerations for the Oracle DBMS When you work with an Oracle database. using the #sql directive. Accessing data with EGL code 213 . v The SQL code that the open statement runs should represent the first parameter of the procedure with a question mark. y int = 1000.To call a stored procedure with open. If there are no other parameters. use the #sql directive and specify the name of the stored procedure in the explicit SQL: open myResultSet with #sql{ CALL GETCUSTOMERS }. y ) }. also using #sql. which assumes a SQLRecord part named myCustomers: myCustomers myCustomers. open myResultSet with p1 using myParameter. In the first example. do not include anything in the using clause for the first parameter. v The first parameter must be have an out or inOut modifier. x. open myResultSet with #sql{ CALL GETCUSTOMERS(:myParameter) }. open rs3 with pstmt3. the procedure has no parameters except the cursor variable: open rs1 with #sql { call p1( ? ) }. can pass result sets between the parts of a program. In the next example. omit the using clause. using a prepared statement. In the next example. and must be a REF CURSOR type (an example of how to define this type is shown later). you can call either a stored procedure or a stored function. The following example uses a prepared statement in combination with the open statement: prepare p1 from "CALL GETCUSTOMERS(?)". Then you can access the result set through the myResultSet identifier. pass EGL variables as host variables: myParameter int = 5. If the stored procedure accepts parameters. called a cursor variable. as in the following example. the procedure has no parameters except the cursor variable: prepare pstmt3 from "call p1( ? )". y. x IN CHAR ) AS BEGIN OPEN c FOR SELECT firstnme. If the function has no parameters. writeStdout( "The function returned " :: x ). The following EGL code defines a stored procedure that you can call using an EGL open statement: execute #sql{ CREATE PROCEDURE ZPQPRM2( c IN OUT MYPKG. v The SQL code that the open statement runs must include a question mark to represent the value that the function returns. You can call an Oracle stored function from EGL. }. A stored function is the same as a stored procedure. the function has two parameters in addition to the cursor variable: x int = 10. empno FROM empx WHERE empno > x ORDER BY empno. do not include anything in the using clause for the first question mark. The following example shows one way to define a REF CURSOR type to Oracle. This next example calls the same function using a prepared statement: prepare q from "call ? := func1( ? )". 214 EGL Programmer’s Guide . In addition. omit the using clause. The following rules apply: v Call the function with an EGL open statement. v The function must return a REF CURSOR type. In the next example. END. :y ) }. In the first example. the called function is passed a string and returns an integer: x int. ? )". The preceding code creates a new type named MYPKG. the procedure has two parameters in addition to the cursor variable: prepare pstmt4 from "call p2( ?. open rs6 with #sql { call ? := f6( :x. using a prepared statement. y int = 1000. y string = "hello".RC12.) execute #sql{ CREATE OR REPLACE PACKAGE MYPKG AS TYPE RC12 IS REF CURSOR. writeStdout( "The function returned " :: x ). open rs4 with pstmt4 using x. }. the function has no parameters except the cursor variable: open rs5 with #sql { call ? := f5() }. In this first example. (For other ways. you can create stored functions in Oracle. using a slightly different SQL syntax than in the stored procedure call. END. also using #sql. execute #sql{ call :x := func1( :y ) }. execute q using x. refer to your Oracle documentation. v If the function call is in a prepared statement.RC12 that you can use for the type of a parameter that holds the results of a query. y.In the next example. EGL can call Oracle stored functions that return the results of a query. ?. except that it returns a value (Oracle’s stored procedures cannot return a value). using the #sql directive. open rs8 with pstmt8 using x. the function has two parameters in addition to the cursor variable: prepare pstmt8 from "call ? := f6( ?. Using prepared statements instead of explicit SQL code can improve performance for data access operations that you use repeatedly. the function has no parameters except the cursor variable: prepare pstmt7 from "call ? := f5()". v You cannot use open to call a stored procedure when generating for COBOL platforms. Accessing data with EGL code 215 . Then. Then. LAST_NAME FROM MYSCHEMA. Fundamentally. the database has to perform less processing when you execute the prepared statement. using a prepared statement. the database performs much of the processing necessary for the statement ahead of time. open rs7 with pstmt7.MYTABLE }. ? )". Whether you use a prepared statement or explicit SQL depends on how many times you use the data access operation. get myCustomers with #sql{ SELECT CUSTOMER_ID. Executing a prepared statement The prepare keyword constructs an SQL statement from a string. When you create a prepared statement. executing a prepared statement is no different from executing any explicit SQL code. Then. The following two functions are equivalent: function executeExplicitSQL() myCustomers myCustomers[0]. v You cannot call a stored procedure on a Microsoft SQL Server DBMS if the stored procedure contains any out parameters. In the next example. you can run that prepared statement with another data-access statement. you can run that prepared statement with another data-access statement. using a prepared statement. 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. Related tasks “Executing a prepared statement” The prepare keyword constructs an SQL statement from a string. y.In the next example. “Viewing implicit SQL statements” on page 217 Related reference SQL data access open open considerations for SQL execute considerations for SQL SQLRecord stereotype #sql directive Host variables Host variables allow SQL statements to use EGL variables. you can change which variable the dynamic statement uses. 216 EGL Programmer’s Guide . prepare myStatement from "SELECT CUSTOMER_ID. In other words. myString += "FROM MYSCHEMA. myHostVarString += " WHERE CUSTOMER_ID = ?". Using variables in the prepared statement Prepared statements are especially useful when you want to insert variables into the statement. assigning the statement to a new identifier: prepare myStatement from myString. for dynamic SQL statements that include variables. you use a question mark (?) to represent variables.MYTABLE". you can add a for clause to specify the SQLRecord to use with the prepared statement: myCustomer myCustomers. Like any string. but you can also use execute or open. prepare myStatement2 from myString for myCustomer. myString += "CUSTOMER_ID. the prepared statement must be appropriate for the data access statement. When creating a prepared statement. You can use prepare for standard SQL statements such as SELECT. first create a string variable to hold the statement. and for calls to stored procedures.MYTABLE". you can assign a value to the variable directly or assemble the value from multiple strings or variables: myString string = "SELECT ". myHostVarString += " FROM MYSCHEMA. get myCustomerArray with myHostVarString using myCustomerID. Variables in prepared statements are even more powerful than host variables in normal explicit SQL code. Then. In this case. LAST_NAME". prepare myStatement from myHostVarString. LAST_NAME FROM MYSCHEMA. Finally. you can change the using myCustomerID clause to use different variables in different situations. if you can execute the string as explicit SQL. The question mark acts as a placeholder into which you can insert a value later with the using clause: myCustomerID int = 5. use prepare to create the prepared statement from the variable. end The previous examples used the get statement to execute the prepared statement. LAST_NAME ". get myCustomerArray with myStatement2. execute the statement and put the results into a variable: myCustomerArray myCustomers[]. Also.end function executePreparedStatement() myCustomers myCustomers[0]. you can also prepare and execute the string as a prepared statement. In each case. Preparing and executing the statement To prepare the statement. get myCustomers with myStatement. myHostVarString string = "SELECT CUSTOMER_ID. myCustomerArray myCustomers[].MYTABLE". because you can do more than just insert an EGL variable value. In the Prepared statement identifier field. A second menu offers you the following choices: Retrieve SQL If you are in the process of defining the record. In the SQL record variable name field. For rules. select execute. Naming conventions 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. Related reference SQL data access open open considerations for SQL execute considerations for SQL SQLRecord stereotype prepare considerations for SQL #sql directive Host variables Host variables allow SQL statements to use EGL variables. this option asks EGL to Accessing data with EGL code 217 . type an identifier for the result set in the Result set identifier field. 1. Related tasks “Calling a stored procedure” on page 212 You can call an SQL stored procedure with the open or execute statements and the #sql directive. right-click a blank line and then click Add SQL Prepare Statement. 4.Creating a detailed prepared statement EGL also provides a tool that creates a prepare statement and the related execute. get. 6. EGL creates the prepare statement and related data access statement. 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. or open statement. This feature enables you to write functions that access a relational database even if you do not know any SQL at all. Within a function in your logic part. 5. In the Execution statement type field. Related concepts “Working with SQL statements” on page 211 With EGL you can deal with explicit SQL code in your EGL program. EGL can also display a default SELECT statement based on an SQL Record definition. Click OK. or open. 3. You must eventually define an SQL record variable with that name in the EGL source code. The default SELECT statement: Right-click within the first line of an SQL Record definition and select SQL Record. type a name to identify the EGL prepare statement. If you selected open in the Execution statement type field. 2.get. The Add SQL Prepare Statement window opens. see ″Naming conventions″ in the EGL Language Reference. It also enables you to generate default SQL code that you can customize. C_ADDR2. C_NAME. {column="C_NAME". C_BALANCE from ADMINISTRATOR. maxLen=25}. keyItems = [customerNumber]} customerNumber STRING customerName STRING customerAddr1 STRING customerAddr2 STRING customerAddr3 STRING customerBalance MONEY end {column="C_NUMBER".customerNumber. maxLen=25}. myCustomer. maxLen=25}.construct the record definition for you.customerAddr1. The examples in this section all use the following Record part: record CustomerRecord type SQLRecord {tableNames = [["ADMINISTRATOR. but includes an EGL into clause for the field names in the EGL record variable. based on fields in the database table. isSQLNullable=yes}.customerAddr3. Add with Into This option functions the same as Add.customerNumber }. isSQLNullable=yes. "L1"]]. You can copy the contents of this window by highlighting it and pressing Ctrl+C. See “Retrieving SQL table data” on page 205. {column="C_ADDR2". isSQLNullable=yes. {column="C_ADDR3". The Add option converts the simple I/O statement get myCustomer to the following: get myCustomer with #sql{ select C_NUMBER.CUSTOMER L1 where C_NUMBER = :myCustomer.CUSTOMER". 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. C_NAME. {column="C_ADDR1". C_BALANCE 218 EGL Programmer’s Guide . right-click anywhere in an EGL I/O statement that references a record variable based on a Record part with the SQLRecord stereotype.customerAddr2. To deal with the transformation of implicit SQL code to embedded SQL code. myCustomer. C_ADDR1. isSQLNullable=yes. myCustomer. myCustomer. maxLen=25}. This is useful if you want to update only some of the fields. maxLen=6}.customerBalance with #sql{ select C_NUMBER. C_ADDR3. see #sql directive.customerName. C_ADDR1. C_ADDR2. C_ADDR3. myCustomer. 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 remove the field names you do not want to update from the into and select clauses: get myCustomer into myCustomer. Here you include explicit SQL code as part of an EGL I/O statement that is introduced by a #sql directive. isSQLNullable=yes. For details of the #sql syntax. Choose SQL Statement from the menu. Implicit SQL statements: The opposite of an implicit SQL statement is an embedded SQL statement. 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. {column="C_BALANCE". You can clear or apply preference settings: v To restore default values. The currently selected connection in the Connection list is the default database for EGL in the workbench.CUSTOMER L1 where C_NUMBER = :myCustomer. 3. click New.customerNumber }. expand EGL. For example. Reset. this will undo all of your edits and restore the original embedded code. 2. click Apply. Click Window → Preferences. and Validate the SQL statement. If you are using DB2 you might need to set the Secondary Authentication ID field. Accessing data with EGL code 219 . From the View dialog you also have the option to Add. you need this connection when you use the EGL SQL retrieve feature. You can. Related concepts “Accessing data with EGL code” on page 183 Related tasks “Preferences” on page 172 EGL preferences affect the way the workbench displays and works with EGL. To create a new connection. View This option displays the implicit SQL code without adding to the code. See ″Secondary Authentication ID″ in this topic. edit or delete the connections. You can switch between database connections. Add with Into. see “Fields in the New Connection wizard” on page 198. highlight the code in the pop-up display and copy it by pressing Ctrl+C. 4. 5. you use database connections in two ways: v When you are developing your programs. For an explanation of the preference fields. however. or use the following steps to set up or edit the connections: 1. v When you are running or debugging your programs. and test the connections from this window. When a list of preferences is displayed. To create a new connection using the New Connection wizard. Reset If you have edited the embedded code that EGL added to your program. v To apply preference settings without exiting the preferences dialog.from ADMINISTRATOR. see “Setting preferences for SQL retrieve” on page 220. “Retrieving SQL table data” on page 205 Related reference SQLRecord stereotype #sql directive Setting preferences for SQL database connections In the workbench. Remove This option removes the embedded SQL code and returns you to your original I/O statement. see “Creating an SQL database connection” on page 197. then click SQL Database Connections. Validate This option checks to see whether the implicit SQL code is well-formed and will work correctly. click Restore Defaults. click OK. To set preferences for the SQL retrieve feature. Specify rules for creating each structure field that the SQL retrieve feature creates: a. Access rights to DB2 objects are granted to the RACF group and individual user IDs are added to the RACF group. expand EGL and then click SQL 2. This technique minimizes work when your authorization requirements change. For example. To fully understand how a secondary authorization ID can be used for your environment. the system administrator can grant access to a RACF group. Secondary Authentication ID The secondary authentication ID is more commonly known as the secondary authorization ID. v In some cases. To specify the EGL type to use when creating a structure field from an SQL character data type. v Use EGL type Unicode maps SQL char data types to EGL Unicode data types. Related tasks “Preferences” on page 172 EGL preferences affect the way the workbench displays and works with EGL. the way that platform is configured. b. that ID is used as the default schema name for all SQL statements. v Use EGL type mbChar maps SQL char data types to EGL mbChar data types. all individuals belonging to that group then get read access. if a new DB2 table is created. 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: 220 EGL Programmer’s Guide . you can use the SQL retrieve feature to create an SQL record from the columns of an SQL table. refer to your DB2 documentation. as long as they are using the secondary authorization ID. v Use EGL type char maps SQL char data types to EGL char data types. v Use EGL type limited-length string maps SQL char data types to EGL limited-length string data types.v If you are finished setting preferences. Click Window → Preferences. 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 For DB2 on zOS. a secondary authorization ID is often mapped to a RACF® group. do as follows: 1. Related reference dbms sqlJNDIName Setting preferences for SQL retrieve At EGL declaration time. Here are common examples of the secondary authorization ID: v For DB2 UDB. if you specify a secondary authorization ID. The meaning and use of the secondary authorization ID depends on the following conditions: v The DB2 platform you are using. To specify how the underscores in the table column name are reflected in the structure field name. If you want new SQL records to have the key field property set. 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. v Remove underscores means that underscores in the table column name are not included in the structure field name. If you want new SQL records to be compatible with COBOL programs (that is. Click OK to save the changes and exit the window. “Setting preferences for SQL database connections” on page 219 “Secondary Authentication ID” on page 220 Working with DL/I data IBM developed DL/I (Data Language/One) in the 1960s as a hierarchical database management system. v Use EGL type Unicode maps the SQL type to EGL Unicode data types. the letter immediately follows an underscore. 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. 3. in the table column name. d. To specify the case of the structure field name. select the Add level numbers to record definition check box. Click Apply to save the changes and remain in the Preferences window.v Use EGL type dbChar (the default) maps the SQL type to EGL dbChar data types. select the Prompt for SQL user ID and password when needed check box. except that a letter in the structure field name is rendered in uppercase if. 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 Use EGL type limited-length string maps the SQL type to EGL limited-length string data types. v Use EGL type string maps the SQL type to EGL string data types. c. to have fixed records with level numbers for structure items. 6. 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. 4. select the Retrieve primary key information from the system catalog check box. DL/I remains a widely used database system in COBOL programs today. and to use CHAR instead of STRING primitive types). Related concepts “Accessing data with EGL code” on page 183 Related tasks “Retrieving SQL table data” on page 205 “Preferences” on page 172 EGL preferences affect the way the workbench displays and works with EGL. The following terms and concepts are essential in developing a DL/I database program: Accessing data with EGL code 221 . 5. It is a single block of data divided into data fields. DL/I stores those child segments in sequence field order under that parent. DL/I call A DL/I call is an invocation of DL/I by a program. The parameter list passed for a database call provides DL/I with the following information: Function code Indicates if DL/I is to get. Segment search argument (SSA) list Lists a set of search criteria that enables DL/I to select the segments that it retrieves from the database or specify the position of segments it inserts into the database. Program Communication Block (PCB) A PCB is an entry in a PSB. These segments are arranged in a hierarchical (top down) relationship. The data structure might correspond directly to the structure of a physical or logical DL/I database or might invert the database structure through access by a secondary index. I/O area address Identifies the address of the buffer that contains the segment after it is read from the database or before it is written to the database. Program Specification Block (PSB) A PSB is a formal DL/I description of the hierarchical database structures that a program can access. For DL/I calls using AIBTDLI. see Data access using PSBs and PCBs in the EGL Language Reference. The root segment has no parent. provides the name of the PCB in the PSB. except for a root segment. For more information. Each segment can have one or more dependent segments related to it at a lower level in the hierarchy. A segment with a dependent segment is called the parent of the dependent segment. The dependent segment is called a child segment.Segments The primary unit of data in a DL/I database is the segment. Database identifier For DL/I calls using CBLTDLI. The PSB shows the hierarchical relationships that exist between types of segments. The segment at the top of the hierarchy is called a root segment. you either code the DL/I parameter list directly or use the command level interface of 222 EGL Programmer’s Guide . A segment is similar to a record. When you code a DL/I program in a language like COBOL or PL/I. When a parent segment has multiple occurrences of the same child segment type and a sequence field is defined for the child segment. has one and only one parent. The EGL record part of type PSBRecord contains the information that your program needs to interact with the DL/I PSB. replace. The value of the sequence field determines the order in which the segments are stored and retrieved from the database. points to the program communication block (PCB) that identifies the database that DL/I is to access on the call. Each database PCB describes one hierarchical data structure that a program can use. insert. Database Hierarchy A single database can contain many types of segments. or delete segments from the database. Each segment in the database. Sequence Field Each segment type in a database can have one of its fields designated as a sequence field. it first tries to read the next segment at the next lower level. this documentation uses the same example DL/I database wherever possible. it reads the next segment at the same level. DLISegment stereotype The DLISegment stereotype specializes a Record part for use with a hierarchical database. and EGL translates it into actual DL/I commands.. If no calls are issued. the current position becomes the start of the database. The pointer indicates the place in the database where a get next statement begins searching for the segment to retrieve. In this case you write DL/I pseudocode. and replace. EGL knows to generate code that works with a DL/I database. see “Example DL/I database. If the end of database condition is encountered. DL/I database support EGL supports DL/I (Data Language/I). Database position When a program is running. get. As DL/I scans the dependent segments. it accesses all the dependents of the root before scanning the next root. You can view the DL/I call created for the function. This process is called the “top to bottom. The position pointer is set on any successful DL/I call to point to the segment following the last segment accessed on the call. a hierarchical data base manager for COBOL environments. When DL/I finds a root segment. it returns to the previous level to search for the next segment. DL/I accesses each root segment in the order it appears in the database. “Example DL/I database” “DL/I examples” on page 227 Example DL/I database To provide a consistent experience and to let each example build on others. Related concepts: Data access using PSBs and PCBs Use program specification blocks (PSBs) and program communication blocks (PCBs) to describe the logical structures in a program you generate for COBOL. You can write EGL programs that access DL/I databases by using many of the same EGL statements you would use to access a relational database: add. see “DL/I examples” on page 227. the current position indicates the start of the database. EGL creates DL/I parameter lists for you based on the I/O statement and the position of the DL/I segment in the PCB. you can write DL/I programs entirely in EGL.” For sample solutions to common DL/I coding problems. left to right” search order. You can also modify the DL/I call to use additional DL/I functions. delete. When your EGL statement specifies a record variable based on the DLISegment stereotype. If there is not a lower level. As with SQL. As DL/I continues searching a database for a segment that satisfies the SSA list criteria.CICS to create the DL/I parameter list. If there are no more segments at the current level. or you can specify explicit DL/I code to get more control of the details. This Accessing data with EGL code 223 . For a diagram of an example DL/I database layout. DL/I maintains a position pointer for each PCB in the program PSB. 224 EGL Programmer’s Guide . due to the logical relationship between the two segments. and individual locations. From the program’s point of view. quantity on hand. unit price. Database layout The following database is named CUSTOMER: CUSTOMER NAME/ ADDRESS (STSCCST) CUSTOMER LOCATION (STSCLOC) CREDIT STATUS (STSCSTA) CUSTOMER HISTORY (STSCHIS) CUSTOMER ORDER (STPCORD) ITEM (STLCITM) The following details refer to the example database: v The location number in the location segment is unique for each customer. history. v The order segment is a concatenated segment containing data from two segments that are connected by a logical relationship. quantity reserved. The item description. Each location has order segments. and each order has item segments. and unit of issue are all physically stored in a separate inventory database. this information is presented as if it was part of the order item segment. quantity on order.customer database has basic customer information at the root level. For each customer there are segments for credit status. }. //define records to match segments in DL/I db Record CustomerRecordPart type DLISegment { segmentName="STSCCST". 10 itemAmount decimal(12. 10 itemQtyShipped num(6) { dliFieldName = "STFCIQS" }.2) { dliFieldName = "STFCSBL" }. }. }. 10 itemUnitPrice char(6) { dliFieldName = "STFIIPR" }. 10 itemQtyBackOrdered num(6) { dliFieldName = "STFCIQB" }. keyItem="customerNo" } 10 customerNo char(6) { dliFieldName = "STQCCNO" 10 customerName char(25) { dliFieldName = "STUCCNM" 10 customerAddr1 char(25) { dliFieldName = "STQCCA1" 10 customerAddr2 char(25) { dliFieldName = "STQCCA2" 10 customerAddr3 char(25) { dliFieldName = "STQCCA3" end Record LocationRecordPart type DLISegment { segmentName="STSCLOC". 10 itemQtyOnOrder num(6) { dliFieldName = "STFIIOH" }. }. v The history segment is a variable length segment. 10 itemQtyOnHand num(6) { dliFieldName = "STFIIQH" }. EGL DLISegment Records EGL represents each of these segments in your program as records of type DLISegment.2) { dliFieldName = "STFCSCL" }. end Record HistoryRecordPart type DLISegment { segmentName="STSCHIS".v There is only one credit segment per customer so no key field is necessary. }. //key field 15 itemInventoryNo char(6) { dliFieldName = "STKCIIN" }.2) { dliFieldName = "STFCIAM" }. 15 itemLineNo smallint { dliFieldName = "STQCILI" }. 10 itemQtyReserved num(6) { dliFieldName = "STFIIQR" }. //key field Record OrderRecordPart type DLISegment { segmentName="STPCORD". From time to time we will also show examples of DL/I calls using DL/I versions of segment and field names (8 characters maximum). 10 itemUnitOfIssue char(1) { dliFieldName = "STFIIUN" }. 10 creditBalance decimal(12. keyItem="historyDateNo" } 10 historySegmentLength smallint { dliFieldName = "STGCSL" }. 10 itemDescription char(25) { dliFieldName = "STFIIDS" }. Accessing data with EGL code 225 . The following code sample shows how you can define this database structure in EGL. 10 itemNumber char(6) { dliFieldName = "STQIINO" }. Those DL/I names are also shown in the example. lengthItem="historySegmentLength". 10 itemQtyOrdered num(6) { dliFieldName = "STFCIQO" }. end Record CreditRecordPart type DLISegment { segmentName="STSCSTA" } 10 creditLimit decimal(12. }. //key field Record ItemRecordPart type DLISegment { segmentName="STLCITM". }. 10 historyDateNo char(12) { dliFieldName = "STQCHDN" }. }. }.2) { dliFieldName = "STFCOAM" end }. keyItem="locationNo" } 10 locationNo char(6) { dliFieldName = "STQCLNO" 10 locationName char(25) { dliFieldName = "STFCLNM" 10 locationAddr1 char(25) { dliFieldName = "STFCLA1" 10 locationAddr2 char(25) { dliFieldName = "STFCLA2" 10 locationAddr3 char(25) { dliFieldName = "STFCLA3" end }. }. keyItem="orderDateNo" } 10 orderDateNo char(12) { dliFieldName = "STQCODN" 10 orderReference char(25) { dliFieldName = "STFCORF" 10 orderItemCount num(6) { dliFieldName = "STFCOIC" 10 orderAmount decimal(12. }. { dliFieldName = "STKCCKEY" }. keyItem="itemKey" } 10 itemKey char(8). //key field }. PARENT=STSCCST SENSEG NAME=STSCHIS.TP } }.POS=S SENSEG NAME=STSCCST. callInterface = CBLTDLI } } //create variables for the records myCustomer CustomerRecordPart. myOrder OrderRecordPart.MODIFY=YES PCB TYPE=TP. parentRecord = "OrderRecordPart" }. ELAALT ELAEXP STDCDBL TITLE 'PSB FOR PROCESSING SAMPLE DATA BASES' PCB TYPE=TP. parentRecord = "CustomerRecordPart" }]}}. A PCB is defined with the name STDCDBL.CMPAT=YES. @relationship { segmentRecord = "HistoryRecordPart". @relationship { segmentRecord = "ItemRecordPart". parentRecord = "CustomerRecordPart" }.TP } }. myItem ItemRecordPart. elaexp ALT_PCBRecord { @PCB { pcbType = PCBKind. }. parentRecord = "LocationRecordPart" }. }. // database PCB customerPCB DB_PCBRecord { @PCB { pcbType = DB.PARENT=0 SENSEG NAME=STSCLOC.EXPRESS=YES PCB TYPE=DB. elaalt ALT_PCBRecord { @PCB { pcbType = PCBKind.PARENT=STSCCST PSBGEN LANG=ASSEM. @relationship { segmentRecord = "CreditRecordPart". hierarchy = [ @relationship { segmentRecord = "CustomerRecordPart" }.10 10 10 10 end historyReference char(25) historyItemCount smallint historyAmount decimal(12. myLocation LocationRecordPart. }. parentRecord = "CustomerRecordPart" }.2) historyStatus char(77) { { { { dliFieldName dliFieldName dliFieldName dliFieldName = = = = "STFCHRF" "STFCHIC" "STQCHAM" "STQCLOS" }.PSBNAME=STBICLG END EGL PSBRecord The following code represents the IMS PSB in the EGL program: //define overall db layout in PSB Record CustomerPSBRecordPart type PSBRecord { defaultPSBName="STBICLG" } // three PCBs required for CBLTDLI on IMS iopcb IO_PCBRecord { @PCB { pcbType = PCBKind.PARENT=STPCORD SENSEG NAME=STSCSTA. the DBDNAME is set to CUSTOMER.PROCOPT=AP. IMS PSB In the following PSB definition on the host.DBDNAME=CUSTOMER. @DLI{ psb = "myPSB".TP } }.MODIFY=YES. @relationship { segmentRecord = "OrderRecordPart". end Sample EGL program The following program outline is set up to use the CUSTOMER database: program PrintCatalog type basicProgram { alias="PRINT".PARENT=STSCCST SENSEG NAME=STPCORD.KEYLEN=50. pcbName = "STDCDBL". the customerPCB in the next section sets the pcbName property to this name. myCrStatus CreditRecordPart myHistory HistoryRecordPart 226 EGL Programmer’s Guide . @relationship { segmentRecord = "LocationRecordPart".PARENT=STSCLOC SENSEG NAME=STLCITM. the name of the database. orderDateno) }.locationNo) STSOCORD (STQCODN = :myOrder. Consider the situation in which you want to retrieve the items for a particular order. To limit the scope of the search to the currently established dependent chain.. a hierarchical data base manager for COBOL environments.myPSB CustomerPSBRecordPart.customerNo) STSCLOC (STQCLNO = :myLocation. end EGL creates the following pseudo-DL/I code for the get next inParent statement: GNP STLCITM Searching with another non-key field You can use any field in a segment as a search argument on a DL/I call by modifying the search arguments (SSAs) for the call. You can use the following to retrieve the order: get myOrder with #dli { GU STSCCST (STQCCNO = :myCustomer. DL/I examples These DL/I examples use the same example DL/I database as described in Example DL/I database. while (myItem not noRecordFound) // process the current item get next inParent myItem. function main() .. use the get next inParent statement. if you wanted to read through the customer database and retrieve the customer segment and credit Accessing data with EGL code 227 . Following are some examples of typical techniques for DL/I database I/O: v “Searching within a parent segment” v “Searching with another non-key field” v v v v v “Searching based on information in another record” on page 228 “Searching for a non-root segment” on page 229 “Searching with a secondary index” on page 230 “Using path calls to access multiple segments” on page 232 “Reading all segments with a single I/O statement” on page 232 v “Using dynamic arrays” on page 233 Searching within a parent segment The default get next statement starts at the current position in the database and searches through the entire database for the next occurrence of the target segment under any parent. For example. Then you can use the following to retrieve the line segments within the order: get next inParent myItem. end end Related concepts: “Working with DL/I data” on page 221 Related reference: DL/I database support EGL supports DL/I (Data Language/I). 3.. The definition for targetBalance should match the definition for the creditBalance field in the credit segment. Searching based on information in another record You might want to search based on information in another record. v Use the #dli directive and explicit DL/I I/O so that you can use the customerParm. Write a get next statement for the myCrStatus record.00.segment for each customer with a credit balance greater than a specified amount. get next myCustomer. Add a #dli directive to the line. Add a qualified SSA that looks for a segment where the amount in the creditBalance field is greater than targetBalance.customerNo and then use implicit DL/I I/O as follows: myCustomer..customerNo to myCustomer.2) (for example. ″targetBalance″) that contains the specified amount that you want to search for. EGL creates the normal default SSAs. define a variable of type decimal(12. The disadvantage is the very slight performance overhead of moving the customer number to the segment record.2). The following sample code illustrates this process: targetBalance decimal(12. 2. targetBalance = 10.customerNo = CustomerParm. There are three ways to code this as follows: v Assign the value of customerParm.000. In this case. 4. Consider the situation in which the customer number is passed to the program in a parameter record as follows: Record CustomerData type basicRecord 10 customerNo char(6) . end Program myProgram (customerParm CustomerData) { @DLI{ psb = "myCustomerPSB" }} //declare variables myCustomerPSB CustomerPSBRecordPart.customerNo) The advantage of this technique is that it is very simple. You want to search on the creditBalance field (STFCSBL) in the credit segment (STSCSTA). resulting in the following pseudo-DL/I code: GU STSCCST (STQCCNO = :myCustomer. Include a path command code (*D) to retrieve the customer segment (STSCCST) that corresponds to the credit segment.customerNo) } . To do this.customerNo.customerNo.myCrStatus with #dli{ GU STSCCST*D STSCSTA (STFCSBL >= :targetBalance) }. You want to retrieve the customer segment based on the value in customerParm. myCustomer CustomerRecordPart. you would define the DL/I call search arguments as follows: 1. get myCustomer.customerNo field as the host variable as follows: get myCustomer with #dli { GU STSCCST (STQCCNO = :customerParm. 228 EGL Programmer’s Guide . modifying the default code. However. You have defined the following record variables in your program: myCustomer CustomerRecordPart. change the variable declaration for myCustomer to CustomerRecordPart. and that the keyItem for CustomerRecordPart is customerNo.customerNo) STSCLOC (STQCLNO = :myLocation.locationNo) Notice that while EGL correctly associated the variable myLocation with the segment STSCLOC. The disadvantage is that EGL now uses customerParm as the qualifier for every implicit DL/I database I/O statement that uses the CustomerRecordPart. EGL only knows that myLocation is of type LocationRecordPart. EGL cannot automatically determine the name of the program variable to use as the qualifier for the segment. However. //key field . For example. whose parent segment is CustomerRecordPart. it does take slightly longer to paste in the default #dli directive and then modify the code to use the correct record variable name for the parameter record. keyItem="customerNo".This technique avoids the performance overhead of moving the customer number. EGL creates the entire chain of SSAs for you based on the hierarchical position of the target segment in the PCB.customerNo as follows: get myCustomer. for the higher level segments in the hierarchy. If you use the following get statement: get myLocation. hostVarQualifier="customerParm" } 10 customerNo char(6) { dliFieldName = "STQCCNO" }. EGL was unable to find the variable myCustomer that is based on the CustomerRecordPart.customerNo to myCustomer. You can solve this problem in several ways: v You can name your record variables with the same name as the record parts on which they are based.customerNo) The advantage of this technique is that it results in the same pseudo-DL/I code that you coded for the #dli directive.. myLocation LocationRecordPart. The pseudo-DL/I code that EGL creates in this case is: GU STSCCST (STQCCNO = :customerParm. EGL will create the following pseudo-DL/I code: GU STSCCST (STQCCNO = :CustomerRecordPart. end Then you can use implicit DL/I I/O without having to first assign customerParm. v Add the hostVarQualifier property in the DLISegment record to specify the qualifier for the host variable as follows: Record CustomerRecordPart type DLISegment {segmentName="STSCCST". Accessing data with EGL code 229 .. CustomerRecordPart CustomerRecordPart. without you actually having to code the #dli directive. Searching for a non-root segment You can use implicit DL/I database I/O to retrieve a non-root segment. Consider the situation where the customer segment STSCCST is the parent of the location segment STSCLOC and you want to retrieve only the data for the location segment. locationNo) Because EGL creates the default SSAs from the PCB hierarchy information. The disadvantage is the same as for any explicit I/O -.locationNo) The advantage of this technique is that you can use implicit DL/I database I/O and have different names for the record variables and the DL/I segment records. v Use the #dli directive and explicit DL/I database I/O as follows: get myLocation with #dli { GU STSCCST (STQCCNO = :myCustomer. . hierarchy = [ @relationship { segmentRecord = "CustomerRecordPart" }.if the hierarchy or the key fields change.customerNo) STSCLOC (STQCLNO = :myLocation. pcbName = "STDCNAM". Searching with a secondary index Sometimes the DL/I PSB indicates that a database structure is to be accessed with a secondary index.customerNo) STSCLOC (STQCLNO = :myLocation.. EGL will produce the correct pseudo-DL/I code: GU STSCCST (STQCCNO = :myCustomer. For example.EGL creates the same pseudo-DL/I code: GU STSCCST (STQCCNO = :CustomerRecordPart. hostVarQualifier = "myCustomer" } 10 customerNo char(6) { dliFieldName = "STQCCNO" }.. //key field . The disadvantage is that EGL now uses myCustomer as the qualifier for every implicit DL/I database I/O statement that uses the CustomerRecordPart.. It is an easy technique to use if the host variable qualifier or field name is different from the record variable that is based on the DL/I segment record. if you have another view of the customer database in which customerName is the secondary index. secondaryIndex = "STUCCNM".customerNo) STSCLOC (STQCLNO = :myLocation. You notify EGL about the use of a secondary index by including the secondaryIndex property in the PCB record within the PSBRecord.. v Modify your definition for CustomerRecordPart to include the hostVarQualifier property as follows: Record CustomerRecordPart type DLISegment { segmentName="STSCCST". your database administrator enters an index key name next to the root segment in the runtime PCB definition. keyItem="customerNo". then you can add an additional PCB record to the PSB Record part as follows: // database PCB for customer by Name customerNamePCB DB_PCBRecord { @PCB { pcbType = DB. When this situation occurs.locationNo) The advantage of this technique is that it is very clear which host variables are being used. this is an easy way of ensuring that the variable names EGL uses match your program’s record variable declarations. The disadvantage is that this technique does not follow the general practice of using different names for parts and variables. ] } } 230 EGL Programmer’s Guide . end Now if you use the following get statement: get myLocation. the explicit DL/I database I/O statement does not change automatically. The pcbName property must match an actual DL/I database PCB in the runtime PSB. the database hierarchy as viewed by your program needs to be reflected in the corresponding PCB record is as follows: // orders view of customer database ordersByReferencePCB DB_PCBRecord { @PCB { pcbType = DB. The secondaryIndex property must provide the same field name as your database administrator specifies in the XDFLD statement of the runtime PCB. the database structure is inverted. If the secondary index database is the second PCB record in the PSB record. you can retrieve both the order and the customer by modifying the SSA to delete the comparison for the location and customer segments as follows: Accessing data with EGL code 231 . end Assuming the order reference number is unique to each customer and order. the you do not need to use keys for the location and customer segments. v The DL/I name of the secondary index field (property secondaryIndex = "STUCCNM"). In this case. there might be a secondary index on a lower level segment in the physical database. you must include the usingPCB keyword. EGL will create the pseudo-DL/I code based on the first PCB record in the PSB record that includes the CustomerRecord part. If you issue a get statement to locate a customer. parentRecord = "OrderRecordPart" }. Assuming the ordersByReferencePCB is now your default PCB. parentRecord = "OrderRecordPart" } ]} }. pcbName = "STDCDBL". as in the following example so that EGL will use the correct PCB: get myCustomer usingPCB customerNamePCB. For example. There are now two PCB records in the PSB record that include the CustomerRecordPart in their hierarchy. @relationship { segmentRecord = "ItemRecordPart". get myCustomer. secondaryIndex = "STFCORF". @relationship { segmentRecord = "LocationRecordPart". as in the following example: myCustomer CustomerRecordPart. parentRecord = "LocationRecordPart" }. v The EGL field name for the comparison value (property dliFieldName = "STUCCNM" and then the corresponding field name customerName). @relationship { segmentRecord = "CustomerRecordPart". //use DL/I name hierarchy = [ @relationship { segmentRecord = "OrderRecordPart" }. EGL will create the following pseudo-DL/I code: GU STSCCST (STUCCNM = :myCustomer. if there is a secondary index on the orderReference field in the order segment. In some cases.customerName) Notice that EGL used the record variable name from the get statement (myCustomer) and the PCB specified by the usingPCB keyword (customerNamePCB) to find the following information: v The DL/I name of the segment (property segmentName = "STSCCST"). get myOrder.forUpdate statement. the subsequent replace statement affects every segment retrieved. Follow these steps to use this technique: 1. The default DL/I call EGL builds for a delete function that follows a get forUpdate statement with D command codes does not delete each segment retrieved. Write a get next statement for the record that represents the largest segment in the database. myLocation.customerNo) STSCLOC*D (STQCLNO = :myLocation. For example. Declare the records in the program and specify that each of the records redefines the record used in step 1 above so that all the records occupy the same area of memory. Access the retrieved segment from the corresponding record structure. This statement generates the following DL/I pseudocode: GU STSCCST*D (STQCCNO = :myCustomer.segmentName after the get next statement to determine the type of segment that was retrieved. you can read in the customer. HistoryRecordPart is the largest DLISegment record: myHistory HistoryRecordPart redefCustomer CustomerRecordPart {redefines=myHistory}.. myOrder forUpdate. If you issue a DL/I get next statement with no SSAs. Add the default DL/I call to your code. 5. Edit the #dli directive to delete the single SSA. myOrder. myLocation. 2.orderReference) STSCLOC STSCCST }. redefLocation LocationRecordPart {redefines=myHistory}. as in the following example. 3. location. replace myOrder with #dli{ REPL STSCCST*N STSCLOC*N STPCORD }. . It deletes only the target segment specified on the delete statement... Using path calls to access multiple segments If you invoke an EGL I/O statement with a dependent segment record object. This ensures that any segment you read will not exceed allocated memory. and order segments on the same call: get myCustomer. In this example.locationNo) STPCORD (STQCDDN = :myOrder. which replaces only the location and order segments: get myCustomer.. Check dliVar. Create records matching the other segments in the database. 4. myCustomer with #dli{ GU STPCORD*D (STQCODN = :myOrder. Reading all segments with a single I/O statement You can use a single I/O statement to read all segments in a database.orderDateNo) If you use the D command code on a get. you can read in any of the segments on the path from the root to the object at the same time. 232 EGL Programmer’s Guide . Here is an example of code that will print everything in the customer database. when retrieving an order segment from our example customer database. DL/I returns the next segment in the database regardless of its type. You can do this simply by adding the records for the path call to the statement. You can prevent replacement of a selected segment by specifying an explicit N command code in the SSA for the replace keyword. customerNo = "123456". whatever type it is. Filling the dynamic array for the first batch of 20 orders with a get statement requires an initial GU call followed by a loop of GN calls until the array is full or DL/I runs out of segment occurrences. // get the next batch of 20 orders EGL creates the following pseudo-DL/I code for the get statement: get myOrderArray with #dli{ GU STSCCST (STQCCNO = :CustomerRecordPart. you must use some special techniques so that EGL will create the correct code. EGL creates the following pseudo-DLI code for the get next statement: get next myOrderArray with #dli{ GN STPCORD }. EGL treats the GN call as a loop and provides the logic to loop until the array is full or DL/I runs out of segment occurrences.. The get next statement provides the correct pseudo-DL/I code to retrieve the second batch of orders. the GU call retrieves the first order segment.//read next segment.segmentName) when "STSCCST" printCustomer().. However.orderDateNo) GN STPCORD }. myLocation. myLocation LocationRecordPart.. //so what type was it? case (dliVar.locationNo) STPCORD (STQCODN = :OrderRecordPart. Similarly. myOrderArray OrderRecordPart [] {maxsize = 20}. get myOrderArray. the pseudo-DL/I code for the get statement is Accessing data with EGL code 233 . Consider the situation in which you have defined record variables and a dynamic array as follows: myCustomer CustomerRecordPart.locationNo = "ABCDEF". do some processing get next myOrderArray. Because there is no key field for the array itself (only for members of the array). end end // it was a customer // it was a location Using dynamic arrays You can use the get and get next statements to retrieve DL/I segments to a dynamic array.customerNo) STSCLOC (STQCLNO = :LocationRecordPart. EGL treats the get next statement as a loop and provides the loop control logic for you. In the pseudo-DL/I code that EGL creates. .. into history record while (myHistory not EOF) get next myHistory with #dli{ GN }. // fill the array the first time . // array of orders You can use a get statement to fill the array the first time and a get next statement to retrieve a second group of 20 orders as follows: myCustomer. when "STSCLOC" printLocation(). myOrder OrderRecordPart. myOrderDateNo = "20050730A003". The disadvantage is that this technique does not follow the general practice of using different names for parts and variables. Then change your PSB record to use the new names as follows: Record CustomerPSBRecordPart type PSBRecord { defaultPSBName="STBICLG" } // database PCB customerPCB DB_PCBRecord { @PCB { pcbType = DB. end to the following: Record STSCCST type DLISegment { segmentName="STSCCST". Because EGL creates the default SSAs from the PCB hierarchy information. parentRecord="STSCLOC"} ]}}.the names of the qualifiers for the host variables are not the names of the record variables in your program.. change the customer record part definition from the following: Record CustomerRecordPart type DLISegment { segmentName="STSCCST".orderDateNo) GN STPCORD }. parentRecord="STSCCST"}. //key field . myOrderArray STPCORD [] {maxsize = 20}. You can solve this problem in several ways: v Name your DL/I segment records with the same name as the segments in the DL/I database. hierarchy = [ @relationship { segmentRecord = "STSCCST" }. keyItem="customerNo" } 10 customerNo char(6) { dliFieldName = "STQCCNO" }. @relationship {segmentRecord="STPCORD". end Change the declaration of your record variables and myOrderArray so that they reference the new DL/I segment record parts as follows: STSCCST CustomerRecordPart. For example. this is an easy way of ensuring that the variable names EGL uses match your program’s record variable declarations. @relationship {segmentRecord="STSCLOC". v Use the #dli directive and explicit DL/I database I/O as follows: 234 EGL Programmer’s Guide .not exactly correct -. //key field . get myOrderArray.customerNo) STSCLOC (STQCLNO = :STSCLOC.. pcbName = "STDCDBL".locationNo) STPCORD (STQCODN = :STPCORD. STPCORD OrderRecordPart. end Make similar changes for the location segment (STSCLOC) and the order segment (STPCORD).. Also change your record variable names to be the same name as the segments in the DL/I database.. keyItem="customerNo" } 10 customerNo char(6) { dliFieldName = "STQCCNO" }. STSCLOC LocationRecordPart. // array of orders Now when you issue the following get statement: // fill the array the first time EGL creates the following pseudo-DL/I code for the get statement and the host variable qualifiers use the correct record variable names: get myOrderArray with #dli{ GU STSCCST (STQCCNO = :STSCCST. The disadvantage of this technique is the same as for any explicit I/O -.. LocationRecordPart. get myOrderArray with #dli{ GU STSCCST (STQCCNO = :myCustomer. programs communicate by writing to and reading messages from queues.customerNo) STSCLOC (STQCLNO = :myLocation.orderDateNo) GN STPCORD }.orderDateNo) GN STPCORD }.locationNo) STPCORD (STQCODN = :myOrder.get myOrderArray with #dli{ GU STSCCST (STQCCNO = :myCustomer. // fill the array the first time EGL will produce the correct pseudo-DL/I code: get myOrderArray with #dli{ GU STSCCST (STQCCNO = :myCustomer.customerNo) STSCLOC (STQCLNO = :myLocation. The advantage of this technique is that it is very clear which host variables are being used. hostVarQualifier = "myCustomer" } 10 customerNo char(6) { dliFieldName = "STQCCNO" }. The disadvantage is that EGL now uses myCustomer as the qualifier for every implicit DL/I database I/O statement that uses the CustomerRecordPart. // array of orders get myOrderArray. myOrder OrderRecordPart.orderDateNo = "". Accessing data with EGL code 235 .customerNo) STSCLOC (STQCLNO = :myLocation. //key field .locationNo) STPCORD (STQCODN >= :myOrder. With message queueing.locationNo) STPCORD (STQCODN = :myOrder.if the hierarchy or the key fields change. Related concepts “Working with DL/I data” on page 221 Related reference #dli directive dliVar system variable “Example DL/I database” on page 223 Working with MQ message queues Message queueing provides an alternative to calling a remote program. For example.. keyItem="customerNo". and OrderRecordPart. end Now if you use the following record declarations and get statement: myCustomer CustomerRecodPart.orderDateNo) // using >= instead of = GN STPCORD }. This technique is particularly useful if you must change the default DL/I code -. myLocation LocationRecordPart. myOrderArray OrderRecordPart [] {maxsize = 20}.for example if you do not know the first order number for the customer and want to use the following DL/I code: myOrder. The advantage of this technique is that you can use implicit DL/I database I/O and have different names for the record variables and the DL/I segment records. change the CustomerRecordPart to the following: Record CustomerRecordPart type DLISegment { segmentName="STSCCST". v Modify the definition for each of your DL/I segment records to include the hostVarQualifier property with the name of your program record variable. the explicit DL/I database I/O statement does not change automatically. not by the queue manager. to support older programs. v Workloads can be balanced by starting multiple servers for processing a single queue. Subsequent sections provide the details of creating MQ programs in EGL. New code should use EGL keywords to communicate with message queues. v Communication can be driven by events. v Communicating programs do not need to be running concurrently.The Message Queue Interface (MQI) is an IBM specification of an application programming interface (API) for accessing the MQ (formerly MQSeries®) message and queuing services that support data transfer between programs running on a wide variety of IBM and non-IBM platforms. A message queue can be on the same system as a program (local) or on another system (remote). For more information. EGL supports calls to MQ message queues in two ways: v You can use EGL-specific keywords like add and get next. Programs that use message queueing techniques have the following features: v There is no physical connection between programs. committed or rolled back along with database or file updates. v Communication network access functions are built into the queue managers. The structure and content of the program information is determined by the communicating programs. v Intermittent communication link failures do not prevent messages from being delivered. An MQI message is a string of data sent from one program to another. v Availability can be increased by assigning multiple alternative processors to service a queue. 236 EGL Programmer’s Guide . v Communicating programs can run in parallel. EGL uses resource associations to determine the queue to which the record is assigned. v Work is carried out by small. self-contained programs. Defining messages in EGL EGL uses a record with the MQRecord stereotype to create the internal representation of a message. not into the programs. In this case EGL handles all the details of generating MQ API calls. An MQI message consists of program information and routing information used by the message queue manager (control information). Queue managers manage access to queues and transmission of data between queues. The services allow programs to communicate without knowledge of the lower levels of the communication network and without knowledge of the location of the other programs. v You can write MQ API calls directly. v Messages can be assigned priorities. v Messages can be recoverable resources. see “Defining resource associations for message queues” on page 237. see MQRecord properties. Enter a file type (fileType property) of MQ for the element. 7. One set of properties tells EGL how to create the API commands it generates to communicate with MQ. If you want to specify different properties for different systems. Use resource associations to: v Define the queue manager name and queue name v Define the system v Convert message formats To define a resource associations part for message queues. Specify the system resource name (systemName property) in the following form: [queueManagerName:]queueName Accessing data with EGL code 237 . Click Finish.. Specify the platform on which the message queue is located (system property). The system and file type carry over from the left side. Click Add Association to add a new element. For more information about these properties. and other basic information. Create a resource association part by right-clicking the build file in the Outline view and selecting Add Part.MQRecords follow the same general rules as other EGL records. 6. “Reading from and writing to message queues” on page 238 Write to message queues with the EGL add statement. 8. click Add System and specify additional systems.. 5. Open an EGL build file by right-clicking the file name in the Project Explorer and selecting Open With → EGL Build Parts Editor. Select Resource Association from the wizard dialog and click Next. 3. Related tasks “Defining resource associations for message queues” You can define resource associations to specify default values for EGL programs that access message queues. Specify a file name (fileName property) to identify the element. EGL displays the Resource Association part. Related reference MQRecord properties Defining resource associations for message queues You can define resource associations to specify default values for EGL programs that access message queues. perform the following steps: 1. For each file name and system on the left side of the editor.. the logical queue name (queueName). “Using direct MQ API calls” on page 240 The MQ API is a set of program interfaces used to request services from the message queue manager. 4. you can specify properties on the right side. read with get next. Another set provides the physical name of the message queue to use (fileName). the size of the variable length record (lengthItem). Specify a name for the Resource Association part and an optional free-form description. They consists of message data as well as a number of properties. The entry will apply to any message queue record whose fileName property matches the name you enter here. 2. After you have read from or written to a message queue you may need to commit or roll back your changes. the queue manager is the default queue manager defined for your system. EGL checks to see if there is an active connection to a queue manager. Connecting to queue managers You can connect to only one queue manager at a time in an EGL program. If you specify a conversion table. Otherwise the add or the get next statement will use the current open connection instead of attempting to connect to the queue manager specified in the system resource name. EGL uses the system resource name in add and get next statements for the message queue record. The system resource name for message queue records defines the queue manager name and queue name. If there is not already an active connection. The queueManagerName identifies the queue manager on which the queue is defined. Reading from and writing to message queues Write to message queues with the EGL add statement. EGL automatically disconnects from the queue manager when the program ends. a default system resource name is defined by the fileName property of the message queue record. and from remote format to local format when the message is read from the queue. EGL connects to the default queue manager for the system. EGL converts the message from local format to remote format when the message is added to the queue. EGL performs conversion using the message queue record structure to identify the data type of fields in the message. EGL automatically connects to the queue manager on the first add or get next statement in a program. If the queue manager name is not specified. 238 EGL Programmer’s Guide . 9. it creates one. The default queue manager is the queue manager to which the program is connected. using the queue manager name specified in the system resource name associated with the message queue record. If the system resource name is not specified in a resource association file. You can optionally specify a conversion table if you want data format conversion to be performed on the message. EGL provides sample functions named MQCONN and MQDISC that call the MQCONN and MQDISC routines from the MQ API.Specify only the queueName if you want to use the default queue manager. EGL uses the queue manager name to connect to the queue manager before accessing the queue. The first time you use an EGL statement with an MQ record during a program. Use these functions in the following circumstances: v If the connection queue manager and the queue manager to which the queue belongs are different. closing any open files and committing the current unit of work if it is still open. The queueName identifies the queue that is accessed by the operation. If no queue manager name is specified. The system resource name is used as the initial value for the fileName property for the MQRecord and identifies the default queue associated with the record. If not. use an MQCONN function call to connect before issuing the add or get next statement in the program. read with get next. Connects to the queue manager.When you use the get next statement. see “Using direct MQ API calls” on page 240. You must use a local definition of the remote queue on the currently connected queue manager if both of the following circumstances are true: v You are writing messages to a queue on another Queue Manager using the add statement. EGL performs the following actions: 1. Opens the connection to the queue. Accessing data with EGL code 239 . 3. v You previously wrote a message to a queue using the add statement. EGL performs the following actions: 1. 2. different libraries are provided for threaded and non-threaded environments as well. and HP). In workstation environments (Windows NT®. You must use the close statement after an add statement to close the connection to the queue in any of the following circumstances: v Before using the get next statement. Opens the queue. AIX.v If you want a long running program to disconnect from the queue manager before the program ends. v To release the queue for access by another program. EGL saves the connection handle for future add statements. Reading messages from queues Read messages from queues using the get next statement with the message queue record as the I/O object. v You previously read a message from a queue using the get next statement. On AIX and HP systems. EGL automatically closes the connection to the queue on program termination. Puts the message on the queue. Solaris. MQ provides different runtime libraries for MQ programs depending on whether the program is running on the same system as the message queue manager or whether the program is running as an MQ client communicating with a manager on a server system. OS/2®. Writing messages to queues Write messages to queues using the add statement with the message queue record as the I/O object. You must use a local definition of the remote queue on the currently connected queue manager if both of the following circumstances are true: v You are reading messages from a queue on another Queue Manager using the get next statement. if the queue manager is not already connected. v To release the queue if you have a long running program and have completed work with the queue. use an MQCONN function call to do the initial connection and an MQDISC function call to disconnect after all queue access is complete. Establishes the connection to the queue. 2. if the queue is not already open. Gets the next message from the queue. For more information on MQCONN and MQDISC. 3. like DB2 databases. the resources for different managers are committed independently from one another. EGL automatically issues the appropriate MQ calls for commits and rollbacks when you use sysLib. Committing or rolling back messages When you combine messages in a transaction that defines a unit of work. everything included in the transaction is finalized. New code should use the EGL add and get next statements to access message queue information. EGL supports the following MQI functions: v Connecting and disconnecting from the queue manager (MQCONN or MQCONNX. v To release the queue for access by another program. v To release the queue if you have a long running program and have completed work with the queue. When a unit of work is rolled back. EGL automatically closes the connection to the queue on program termination. The MQ API (also known as the MQ Interface. and the lack of flexibility.commit() and sysLib.rollback(). using a two-phase commit protocol. everything included in the transaction is removed. With message queueing. the ease of making mistakes. Related tasks “Using direct MQ API calls” The MQ API is a set of program interfaces used to request services from the message queue manager. message queue commits and rollbacks are coordinated with commits and rollbacks for other recoverable resources. the MQI should only be used to maintain existing code. The methods used for commits and rollbacks depend on your environment. Because of the complexity of the interface. MQDISC) 240 EGL Programmer’s Guide . When a unit of work is committed. In other environments. or MQI) accesses the message queue manager directly.You must use the close statement after a get next statement to close the connection to the queue in any of the following circumstances: v Before using the add statement. The following environments handle commits and rollbacks independently of MQ: v AS/400® v CICS for MVS/ESA™ v CICS for VSE/ESA™ v IMS In these transaction environments. programs communicate by writing to and reading messages from queues. the messages can be committed or rolled back as a group. Related concepts “Working with MQ message queues” on page 235 Message queueing provides an alternative to calling a remote program. Using direct MQ API calls The MQ API is a set of program interfaces used to request services from the message queue manager. MQI parameters are either data items or records. MQ reusable parts EGL provides a set of reusable parts. use direct MQ API calls. MQCLOSE) Reading a message from a queue (MQGET) Writing a message to a queue (MQPUT) Writing a single message to a queue with an implicit open and close of the queue (MQPUT1) v Requesting or setting attributes of a queue manager object such as a queue (MQINQ. The data items in the records have the same names as the corresponding fields in the COBOL structures. MQBACK) v v v v To 1. Table 36.ibm. The following table shows the names of the sample records for direct MQ calls. Select Properties. MQPUT. Increase the length of these items if you reuse MQSTATE in a program that requires larger buffers. Sample records for MQ calls Record MQBO MQCNO MQDH MQDLH MQGMO MQINTATTRS MQMD Description Begin options Connect options Distribution header Dead-letter header Get-message options parameter Integer attributes parameter Message descriptor parameter Initializer function MQBO_INIT MQCNO_INIT MQDH_INIT MQDLH_INIT MQGMO_INIT MQINTATTRS_INIT MQMD_INIT Accessing data with EGL code 241 . Click EGL Project Features in the left side of the Properties dialog. 4.resources_version\MqReusableParts directory.etools. The MQSTATE and MQATTRIBUTES sample records contain declarations for most data item parameters. Record names are the same as the COBOL structure names. and MQPUT1 calls) and the CHARATTRS (character attributes buffer parameter used with MQINQ and MQSET calls) are both defined with a length of 1024 characters.egl. 2. 5. records. which are parameters.Opening and closing a queue (MQOPEN. MQSET) v Beginning a unit of work (MQBEGIN) v Committing or backing out changes (MQCMIT. The source files for these parts are located in the SDP70Shared\plugins\ com. Check the box next to EGL with low-level MQ API support. Sample records are provided to define the format of record parameters and special purpose messages and message headers. The BUFFER parameter (message buffer parameter used with MQGET. and functions that you can use or modify to make direct calls to the MQ API. 3. except that the COBOL names use a hyphen (-) as a token separator instead of an underscore. Click OK. you must enable an EGL Project Feature: Right-click the project name in the Project Explorer view. Table 37. With message queueing. read with get next.Table 36. Using linkage options for MQ run-time library selection Use an EGL linkage options part to indicate which runtime library you want to use. programs communicate by writing to and reading messages from queues. Sample records for MQ calls (continued) Record MQMD1 MQMDE MQOD MQOR MQPMO MQRMH MQRR MQSELECTORS MQTM MQTMC2 MQXQH Description Message descriptor (version 1) Message descriptor extension Object descriptor parameter Object record Put-message options structure Message reference header Response record Attribute selectors parameter Trigger message structure Trigger message 2 (character format) Transmission queue header Initializer function MQMD1_INIT MQMDE_INIT MQOD_INIT MQOR_INIT MQPMO_INIT MQRMH_INIT MQRR_INIT MQSELECTORS_INIT MQTM_INIT MQTMC2_INIT MQXQH_INIT The following table shows the sample EGL functions that call MQ API functions. Related tasks “Reading from and writing to message queues” on page 238 Write to message queues with the EGL add statement. EGL functions that call MQ API functions Function MQCONN MQCONNX MQDISC MQOPEN MQCLOSE MQGET MQPUT MQPUT1 MQINQ MQSET MQBEGIN MQCMIT MQBACK Description Connect to message queue manager Extended connect Disconnect from message queue manager Open a message queue Close a message queue Read a message from a queue Write a message to a queue Write a single message to a queue including queue open and close Inquire about queue attributes Set queue attributes Begin a logical unit of work Commit a logical unit of work Back out a logical unit of work Related concepts “Working with MQ message queues” on page 235 Message queueing provides an alternative to calling a remote program. 242 EGL Programmer’s Guide . sl libmqic. threaded environment MQ manager MQ client MQ library mqm.The MQ reusable parts shipped with EGL include sample linkage options parts for all supported environments.sl csomqm csomqic csomqicr libmqm. Linkage options for MQ programs MQ library Environment description Windows Windows AIX AIX AIX MQ manager MQ client MQ manager MQ client MQ manager.so csomqm csomqic libmqm. threaded environment MQ client. If you are testing or running with an MQ client or threaded library.lkg libmqm_r.a Wrapper DLL name csomqm32 csomqc32 csomqm csomqic csomqmr Linkage options mqm32. Generated Java programs require a special format for the linkage options entry.lkg HP-UX libmqic_r.a libmqm_r. The following table shows which linkage options part to use in each environment. specify the linkage options part as a test or generation option.lib mqic32.lkg Solaris Solaris libmqm. Related concepts Accessing data with EGL code 243 .a libmqic. non-threaded library. Table 38.lkg libmqic. or copy the entries in the parts to your own linkage options.lkg mqic32. The entry should look like the following example: :calllink applname=elaq* library=mqWrapperDllNname linktype=csocall parmform=commptr remotecomtype=direct remoteapptype=nonvg contable=javaConversionTableName mqWrapperDllNname The wrapper dll name for your run-time environment from the table.a csomqicr libmqic_r.lkg AIX libmqic_r. threaded environment MQ manager MQ client MQ manager.lkg libmqm_r. You can use the linkage options parts directly.lib libmqm.sl csomqmr libmqic_r.lkg libmqm. threaded environment MQ client. you must also move the part to a file and set the CSOLINKTBL environment variable to the file name.sl libmqm_r. if you need to specify entries for other program calls.lkg libmqic.lkg HP-UX HP-UX HP-UX libmqm.so libmqic.lkg libmqic. Refer to the EGL Generation Guide for help in determining which conversion table to choose.lkg If you are testing or running with an MQ manager. javaConversionTableName The java conversion table for your language and the system on which the program is running. The iSeries operating system has its own API to handle program-to-program communication. see the EGL Language Reference. it creates a record and adds that new record to the queue. Data queues are similar to MQ message queues. to hold a flag that lets one program tell another to perform garbage collection. for the cobol directory. For details of these Record parts and function calls.ibm. Working with iSeries objects EGL provides a library and Record definitions to communicate with data queues and data areas on the iSeries. v A library of EGL functions that wrap iSystem API calls.egl.egl file in the SDP70Shared\plugins\ com. One uses the record to update a database.resources_version\iSeriesObjects directory.etools.“Working with MQ message queues” on page 235 Message queueing provides an alternative to calling a remote program. The communication can take place through one of two objects: v A data area is a fixed-size object that any job running on the system can read from or write to. so your choice of which object to use generally depends on the complexity of your task. With message queueing. Related tasks 244 EGL Programmer’s Guide . among others. Copy one of these files into your current project: – iCobolLib. A data queue scenario is typically more complex.resources_version\iSeriesObjects directory.etools. for the java directory. This is an EGL source file located in one of two subdirectories under the SDP70Shared\plugins\ com. Another uses the same record to generate an invoice.egl.egl for Java generation. programs communicate by writing to and reading messages from queues. For each request. for example. – iJavaLib.egl for COBOL generation.ibm. You might use a data area. v Other applications listen for new records created by the first application. Think of it as a virtual whiteboard. This is not a system library that you automatically have access to. You can set it up to contain one of the following kinds of data: – A character string of up to 2000 bytes – A decimal number – A Boolean value (TRUE or FALSE) v A data queue is a variable-length object that can hold any number of messages from any number of jobs. EGL supports these iSeries objects in two ways: v EGL Record parts that correspond to various iSystem objects. Related tasks “Defining resource associations for message queues” on page 237 You can define resource associations to specify default values for EGL programs that access message queues. as in the following example: v One application listens for a specific type of request. including data areas and data queues. A data area has lower overhead than a data queue. The Record parts are located in the CommonDataParts. In COBOL environments. If your code associates these individual properties with a FormGroup. but numbers and Latin alphabetic strings within the text are presented left to right. in XML format. Working with bidirectional data Bidirectional (bidi) languages such as Arabic and Hebrew are languages in which the text is presented to the user ordered from right to left. the order in which the characters are entered in the input field. programs communicate by writing to and reading messages from queues. use a bidirectional runtime file. individual properties controlled this behavior. If you change the individual properties. v To control the format of bidirectional text strings between a server and client. and other bidirectional format characteristics require the program to convert bidirectional text strings from one format to another: v To control the format of bidirectional text strings in FormGroup fields. EGL will use the new values to update the runtime file.“Working with MQ message queues” on page 235 Message queueing provides an alternative to calling a remote program. These differences in the ordering scheme.5). In addition. contains a set of options that control the bidirectional behavior for the fields in the form groups associated with an application. the text is usually stored in logical order. the order in which characters appear within program variables can vary. which is the same order in which the text appears on the user interface. use a bidirectional conversion table. With message queueing. Several of these options correspond to existing bidi properties: v bidiInput v orientation v numericSwapping v symmetricSwapping Before the bidirectional runtime file was added to EGL (prior to version 7. Those properties are still part of EGL. This file. Bidirectional runtime file The bidiRuntime build descriptor option specifies a bidirectional runtime file. In Java environments. text orientation. For information on how to set up the bidirectional runtime file. see “Creating a bidirectional runtime file” on page 247. Bidirectional conversion table Accessing data with EGL code 245 . changing the runtime file will cause EGL to change the values of the individual properties accordingly. the text in program variables is usually in visual order. Related reference iSeries Record definitions EGL provides Record definitions that correspond to objects in the iSeries environment. iSeries function calls iSeries functions provide access to data queues and data areas. To use a bidi conversion table.Specify a bidi conversion table as the value of that property (for example.bct file name for the conversionTable property (for example.bct") . which means that the calling program specifies the bidi conversion table before calling the other program.to 4-character file name with the . The program references the name of the conversion table to indicate how attribute conversion should be performed. You can find more information about the sysVar. you must do the following: v Create bidi conversion tables that specify the transformations that should occur.bct. You build the bidi conversion table file using the bidi conversion table wizard. You can create multiple BCTs to support different bidi format conversions. 246 EGL Programmer’s Guide . 2. along with any other formatting transformation requested in the table. see “Creating a bidirectional conversion table” on page 249.callConversionTable system variable. v Specify the bidi conversion table for use in generation. customize the linkage options part so that the conversionTable property is in the callLink element for the called program.bct") in any protocol other than local. Set the clientCodeSet and serverCodeSet build descriptor options to control the conversion of the code page from ASCII to EBCDIC as shown in the next table. specify the .bct" .bct.egldd) file. For more information. using an EGL wizard. The way in which you specify the bidi conversion table differs depending on the code you are generating: – When you generate for a COBOL environment. using one of the following options: . Note that different tables are needed for converting data being passed between a Java client and a COBOL host and for converting data to be displayed in a text or print form in a Java environment.bct extension.callConversionTable system variable in the topic ″callConversionTable″ in the EGL Language Reference. you can set the value of formConversionTable in a program by adding the following statement at the beginning of the program: sysVar. The bidi conversion table controls the transformation of literal text from logical to visual order for the COBOL environment. if you have created a bidi conversion table named hct1. In all cases. clientCodeSet and serverCodeSet build descriptor option values Language Arabic Hebrew clientCodeSet IBM-864 IBM-1255 serverCodeSet IBM-420 IBM-424 – When you generate a Java program that calls a remote COBOL program. conversionTable="hct1. the bidi conversion table reference is specified as the 1.formConversionTable = "hct1. conversionTable="hct.Set the property to PROGRAMCONTROLLED. For example. Table 39. The file is in XML format and has a file extension of . do the following: 1.EGL uses a bidirectional conversion table (BCT) to perform conversions between ″server″ and ″client″ formats. – When specifying EGL bindings for a service in an EGL deployment descriptor (. Set the bidiConversionTable build descriptor option to the name of the bidi conversion table you created for COBOL generation. The caller specifies the table by assigning the bidi conversion table name to the sysVar. ″Implicit″ has the same meaning as ″logical. Under Enter or select the parent folder. add a statement to the program that assigns the conversion table name to the sysVar. Accessing data with EGL code 247 . 5. The directory must be in the classpath for the application that uses it. Select one of the following values: LTR (default) If you want the fields to display in left-to-right orientation.xml extension. The Runtime Bidi settings page opens.– When developing a program that you plan to generate to Java and that program uses text or print forms with bidi language text. For File name. enter a name for the bidirectional runtime file. Click Next. The Bidi Format Configuration window opens. Click File → New → Other. The name must have the . Click Next. Text Orientation Equivalent to the orientation property (see orientation). Related tasks “Creating a bidirectional runtime file” You can use an EGL wizard to create a bidirectional runtime file. Visual If you want to store bidi characters in the order in which they appear on the screen (this option is provided for historical reasons). RTL If you want the fields to display in right-to-left orientation. 3.formConversionTable system function before showing the form. 6. follow these steps: 1. Select one of the following values: Yes (default) If you want to enable symmetric swapping. The New window opens.″ and is used here for consistency with the bidirectional conversion table (see “Working with bidirectional data” on page 245). Click to expand EGL. 2. then click Bidi Format Configuration. To use the wizard. Creating a bidirectional runtime file You can use an EGL wizard to create a bidirectional runtime file. set the following fields under Runtime Text attributes: Ordering Scheme Equivalent to the bidiInput property (see bidiInput). 7. To provide bidi settings for code generation. 4. “Creating a bidirectional conversion table” on page 249 You can use an EGL wizard to create a bidirectional conversion table (BCT). enter the name folder where you want to create the file. No If symmetric characters are already swapped. Select one of the following values: Implicit (default) If you want to store bidi characters in the order in which they are typed. Symmetric Swapping Equivalent to the symmetricSwapping property (see symmetricSwapping). To provide bidi settings for the Java runtime environment. Select one of the following values: Yes (default) If you want to enable symmetric swapping. digits display in nominal form. Select one of the following values: Nominal (default) All digits display in nominal form (known as Arabic numerals in English). with no modifications. Contextual Digits display according to the preceding data. Any Digits display as stored. No If symmetric characters are already swapped. Numeric Swapping Equivalent to the numericSwapping property (see numericSwapping). Numerals Determines the way that digits display inside forms. Related concepts “Working with bidirectional data” on page 245 248 EGL Programmer’s Guide . Encoding Select the appropriate encoding from the following list: v UnicodeBig (default) v UnicodeBigUnmarked v UnicodeLittle v UnicodeLittleUnmarked v UTF-8 8. set the following fields under Java Emulator Configuration: Symmetric Swapping Equivalent to the symmetricSwapping property (see symmetricSwapping).Note: The default value here is the opposite of the default value of the symmetricSwapping property. Select one of the following values: Yes (default) If you want to enable numeric swapping. Note: The default value here is the opposite of the default value of the symmetricSwapping property. Note: The default value here is the opposite of the default value of the numericSwapping property. The table is displayed for editing. Save and close the window when you have finished. Click Finish. No If numeric characters are already swapped. digits display in national form. Otherwise. If the preceding data is Arabic. 9. National All digits display in national form (known as Hindi numerals in Arabic). 4. enter the name folder where you want to create the table.System. Note that for Java generation. Click Next. you should usually set the ordering scheme to Visual and set the server code page to Cp420 for Arabic or Cp424 for Hebrew.lang. The New Bidi Conversion Table window opens. The Client System settings page opens. Click File → New → Other.bct extension. Accessing data with EGL code 249 . and must have the . 3. 5. Encoding for bidi conversion tables Use COBOL generation COBOL generation Java program that calls a remote COBOL program or EGL service Java program that calls a remote COBOL program or EGL service Java program that uses text or print forms Java program that uses text or print forms Language Arabic Hebrew Arabic Client encoding for Server encoding for bidi conversion table bidi conversion table Cp1256 Cp1255 Cp1256 Cp864 Cp1255 Cp420 Hebrew Cp1255 Cp424 Arabic Cp1256 Cp1256 Hebrew Cp1255 Cp1255 8. including UTF-8. Change any or Client Text attributes necessary.file. Click Next. the ordering scheme should be set to Implicit. The New window opens.Creating a bidirectional conversion table You can use an EGL wizard to create a bidirectional conversion table (BCT). then click Bidi Conversion Table. 7. In the Code page list. To use the wizard. select the encoding for the type of application you are generating. Click to expand Bidi Conversion Table Wizard. 10. Under Enter or select the parent folder. Change any Client System properties necessary. Click Next. the following considerations apply: v For Java generation. The directory must be in the classpath for the application that uses it. The name of a bidi conversion table used with EGL programs must have four characters or less. follow these steps: 1. 2. You can specify any valid code page for client and server. while encoding should be the same as your local system encoding. For File name. For the Ordering Scheme of server attributes. The client format will depend on the client that you use. 6. The following table shows some examples: Table 40. the conversion table client code page must be the same as the java. The Server System settings page opens.encoding set for the Java Virtual Machine when the program runs. v For COBOL generation. enter a name for the Bidi Conversion table. 9. Click Next. The Conversion Options page opens. Change the Server System properties and Server Text attributes if necessary. 12. Related concepts “Working with bidirectional data” on page 245 250 EGL Programmer’s Guide .11. 13. Click Finish. Change the Arabic Conversion Options and General Conversion Options if necessary. 14. In a program that runs as a z/OS or IMS BMP main batch program or as a Java main text or main batch program.Transfer of control across programs EGL provides several ways to switch control from one program to another: v The call statement gives control to another program and optionally passes a series of values. the content of the variable is changed in the caller. Control returns to the caller when the called program ends. closes cursors. but closes files. For more information. which are available to the invoked program.startTransaction(). or information for a remote transaction for CICS). . although an automatic server-side commit may occur. the behavior depends on the setting of build descriptor option synchOnTrxTransfer: v If the value of synchOnTrxTransfer is YES. which receives data received from the user as well as data that was passed without change from the originating program. and starts a program in the same run unit. 1996. v The vgLib.startTransaction() system function starts a run unit asynchronously. You may specify characteristics of the call by setting a callLink element of the linkage options part. 2008 251 . v The EGL show statement ends a main textUI program or a main VGWebTransaction program and shows data to the user. see startTransaction() and Using linkage options parts in a call or transfer. The operation does not end the transferring program and does not affect the databases. releases locks. you might need to generate the program with a linkage options part. – A transfer to transaction statement does the following: . closes cursors. files. end the transferring program. but does not close or commit resources. The call statement does not commit databases or other recoverable resources. You cannot use one of these transfer statements in a called program. and locks in the transferring program. For more information. see transfer and Using linkage options parts in a call or transfer. asynchLink element to provide additional information (such as a package name for Java. this statement commits recoverable resources. closes files. see call and Using linkage options parts in a call or transfer. which is an area in the receiving program. v If the value of synchOnTrxTransfer is NO (the default). You have the option to pass data into the input record. closes files. © Copyright IBM Corp. For more information about restrictions and other issues. – A transfer to program statement does not commit or rollback recoverable resources. v Two types of transfer statements give control from one main program to another. After the user submits the form or Web page. If your program invokes vgLib. the transfer statement commits recoverable resources. and starts a new transaction. and starts a program in the same run unit. the show statement optionally forwards control to a second main program. If the called program changes any data that was passed as a variable. the transfer statement also starts a program in the same run unit. and optionally pass a record whose data is accepted into the receiving program’s input record.In a main program that runs under CICS or IMS/VS. 8 bytes 6 bytes 2-byte length data for form field Figure 1. see forward. The first 6 bytes of the adjunct field are set to blanks. The field length is set to the length of the field defined in the map. and releases locks. closes files. For more information.. 3. The statement performs the following actions: 1. Format of the form area passed using the call statement 252 EGL Programmer’s Guide . The last 2 bytes of the adjunct field contain the length of the data. The target in this case is another program or a Web page. the show statement is affected by the settings in the linkage options part. For more information. a called program cannot change the attributes of form variable. the forward statement is invoked from a JSF Handler or from a program that runs in a Java environment. For more information. If the receiving structure in the called program is not a form. v Finally. see ″forward″ in the EGL Language Reference. see show. Ends the code. Format of a text or print form passed on a call Text or print forms that you pass on a call are defined with 8 bytes of adjunct fields preceding each field data content area.psbData structure v A PCBRecord The following sections provide more information. Commits recoverable resources. the structure should have space for the 8 bytes before each data item. transferToTransaction element.In relation to textUI programs. A called program can only change the data in the variable fields in the passed form. Related tasks “Calling programs in CICS environments” on page 254 “Transferring control in CICS environments” on page 261 “Calling programs in IMS and z/OS batch environments” on page 267 “Transferring control in the IMS/VS environment” on page 275 “Transferring control in IMS BMP and z/OS batch environments” on page 270 Related reference “Reference information for special parameters on call or transfer statement” Reference information for special parameters on call or transfer statement You can use the following special parameters on a call or transfer statement: v A text or print form passed on a call statement v The dliLib. Forwards control. 2. The target in this case is another program or a Web page. It does not include the 8-byte prefix. For example. The address points to the CICS user interface block (UIB).psbData structure for passing PSB information between programs. the address points to the user interface block (UIB). The last 2 bytes contain status information (for example. it is implemented as a 12-byte field consisting of an 8-byte PSB name followed by a 4-byte address. Format of dliLib. On CICS.psbData. High order byte must have bit 0 = 1 Figure 2.psbData structure EGL-generated COBOL programs use the dliLib. the 2-byte binary fields must be aligned on a 2-byte boundary. an indication of whether the PSB contains status information). which starts at the third byte of the 8-byte field.psbData structure as a parameter. Format of the dliLib. The UIB is 6 bytes long. The simulated UIB is 6 bytes long.psbData structure and PCB record parameters.psbData PCB Number n Format of a PCBRecord There are special considerations for the dliLib. The first 4 bytes contain the address of the PCB address list for the PSB. Refer to the online help system for additional information about dliLib.psbData PSB Name Pointer to UIB Pointer to PCB List Status information PCB Number 0 (I/O) PCB Number 1 PCB Number 2 . the address points to a simulated UIB.psbData is a 12-byte structure consisting of an 8-byte PSB name followed by a 4-byte address. The last 2 bytes must contain binary zeros. The first 4 bytes contain the address of the PCB address list for the PSB. If you pass the dliLib. The figure below shows the format of dliLib. The PCB address list must be the list pointed to by register 1 when the IMS or the DL/I region controller invoked the first program in the DL/I run unit. Transfer of control across programs 253 .psbData. Pointer to dliLib. . dliLib. . On non-CICS systems.When passing a form as a parameter from an AIX system to a non-AIX system and vice versa. For a localCall. You must create a CICS RDO PROGRAM entry for any called program that is called with the following linkage options: 254 EGL Programmer’s Guide . In the CICS environments. STATIC Standard static COBOL call. Instead EGL generates a standard dynamic COBOL call. remoteCall A call that is to be made from one CICS region to another or from a generated Java program to a generated COBOL program that runs in CICS. CICSLINK is only supported in the following situations: v The callLink element for the called program specifies a remoteCall.A PCB record parameter is always passed using a 4-byte pointer because the called program must point to the actual DL/I PCB in DL/I calls. then issues a CBLTDLI call against that address. The above considerations are true for both AIBTDLI and CBLTDLI interfaces. Related concepts “Transfer of control across programs” on page 251 Related tasks “Calling programs in CICS environments” “Calling programs in IMS and z/OS batch environments” on page 267 “Transferring control in IMS BMP and z/OS batch environments” on page 270 Calling programs in CICS environments Use the linkage options part to specify how you want EGL to generate the call statement. The called program must be link edited with the calling program. you can specify one of the following values for the type property for a callLink element in the linkage options part: localCall A call that is to be made in the same CICS region. CICSLINK CICS LINK command (default for CICS programs). you can also specify the linkType property that determines the actual call statement as follows: DYNAMIC Standard dynamic COBOL call. In all other cases. the 4-byte pointer is moved into the COMMAREA at the position to be occupied by the PCB record argument. EGL does not generate a CICS LINK command for linkType = CICSLINK. The called program cannot use a copy of the PCB. the same call as if you specified linkType = DYNAMIC for the callLink element for the called program. including where CICSLINK is the default. v The callLink element for the called program specifies parmForm = CHANNEL. EGL uses the AIB control block to look up the PCB address of the AIB PCB name. When COMMDATA is specified. If you specified the AIBTDLI interface (the default) in the callInterface field corresponding to the @DLI program property. v The call statement specifies isExternal = YES or the callLink element for the called program specifies pgmType = EXTERNALLYDEFINED. if the called program is a PL/I Transfer of control across programs 255 . The containers are named EGL-PARM-1 through EGL-PARM-n. For more information. for a localCall. The first two parameters are the EXEC interface block (EIB) and COMMAREA followed by the call statement parameters. Table 41. set the type property to remoteCall and the linkType property to either COMMPTR or COMMDATA depending on how the called program expects to receive its parameters. If either the calling or called program is a PL/I program. you must set the linkType property to CICSLINK. Not valid if calling from a CICS program. The call statement is generated as a CICS LINK command with data passed in the COMMAREA control block (COMMDATA). All calls described here are local calls between programs running on the same CICS system. CHANNEL Parameters are passed in containers in a channel. Valid parameter format and linkage combinations for CICS COMMPTR DYNAMICValid STATIC Valid COMMDATA OSLINK Valid Valid Valid Valid Valid No No CICSOSLINK CHANNEL Valid Valid No No No No Valid Valid CICSLINK Valid REMOTE Valid if calling from an Valid EGL-generated Java program. v If the calling program is a generated Java program and the called program runs on CICS. where the maximum value of n is 30. COMMDATA Parameter data is passed in the COMMAREA (default for CICS programs if the property type is remoteCall).v localCall with the linkType property set to DYNAMIC or CICSLINK. The called program cannot contain any CICS statements or be an EGL program. see Linkage options part. In addition. set the type property to remoteCall and the linkType property to COMMDATA. No COMMAREA is passed in the CHANNEL parameter format. you can use the CICS autoinstall function for programs. OSLINK Parameters are passed using a standard COBOL parameter list. Alternatively. Called programs can also run on a different system than the calling program as follows: v If both programs run in CICS. v remoteCall You can also specify how the parameters on the call statement are to be passed to the called program: COMMPTR Pointers to the parameters are passed in the COMMAREA (default for CICS programs if the property type is localCall). CICSOSLINK A standard COBOL parameter list is used. COMMAREA pointer (COMMPTR) parameter format For the COMMPTR parameter format. as in a program that was previously called from a CSP/AE (Cross System Product/Application Execution) program. Format of call statement parameters for CICS The following sections provide a more detailed description of the parameter formats used for call statement in the CICS environment. The first is the address of the EXEC interface block (EIB). The high-order bit is set on for the last parameter address in the COMMAREA for the parameter format COMMPTR. pointers are passed in the CICS COMMAREA. The length of the 256 EGL Programmer’s Guide . The following sections give the specifics for using parameters with the call statement. The COMMAREA is generated in the calling program’s COBOL working storage area. Bit 0 = 1 . The figure below illustrates the COMMPTR parameter format. Pointers to the parameters are passed in the COMMAREA. If the calling program is a PL/I program. Register 1 Address of EIB Address of COMMAREA 4 Byte Parm Pointer High Order Byte.see note) When you set the endCommarea build descriptor option to YES for the calling program.program. . 1 to 30 Parameter pointers 4 Byte Parm Pointer X’FFFFFFFF’ List End (optional . . the calling program adds the x’FFFFFFFF’ fullword at the end of the parameter list. you must either specify isExternal = YES on the call statement or specify pgmType = EXTERNALLYDEFINED in the callLink element for the called program. For more information.psbData structure” on page 253 and “Format of a PCBRecord” on page 253. see “Format of the dliLib.psbData or a PCBRecord as a parameter. you must specify linkType = CICSLINK in the callLink element for the called EGL program. You should set endCommarea to YES only when the called program requires this terminal fullword. Register 1 points to a list of pointers. Note: Special considerations apply if you pass dliLib. followed by the address of the COMMAREA. the required space must be defined within the fixed portion of the record. the called EGL program must not do any I/O. The called program must be one of the following: v A non-EGL program that does not contain any EXEC CICS commands v An EGL program that is generated for the ZOSBATCH environment. In this case.COMMAREA does not include the 4 bytes for this fullword unless endCommarea is set to YES. The first is the address of the EIB. Transfer of control across programs 257 . Register 1 points to a list of pointers. In addition. The figure below illustrates the OSLINK parameter format. Register 1 Address of EIB Address of COMMAREA Parameter Data OSLINK parameter format For the OSLINK parameter format. you must specify linkType = DYNAMIC in the callLink entry for the called EGL program. The called program must return the parameter values in the COMMAREA in the same order. The calling program moves the returned parameter values in the COMMAREA back to the original parameters. Under certain conditions. followed by the address of the COMMAREA. CICS passes a copy of the COMMAREA to the called program. Register 1 points to a list of pointers that are the addresses of buffers of parameter data (one for each parameter). If variable length records are passed. If a variable length record is passed that has the lengthItem property set. Each parameter value is moved to the COMMAREA. Only the parameters specified on the call statement are passed. The high-order bit is set for the last address in the parameter list for parameter format OSLINK. the EIB and COMMAREA are not passed. The COMMAREA is generated in the calling program’s working storage area. COMMAREA data (COMMDATA) parameter format For the COMMDATA parameter format. Actual parameter data is passed in the COMMAREA. The figure below illustrates the COMMDATA parameter format. where the values adjoin one another without regard for boundary alignment. space is reserved for the maximum length record as defined to EGL. OSLINK is valid only for DYNAMIC and STATIC linkage types. the actual data is passed in a single buffer in the CICS COMMAREA. 258 EGL Programmer’s Guide . The figure below illustrates the CICSOSLINK parameter format. The containers are named EGL-PARM-1 through EGL-PARM-n. followed by the address of the COMMAREA. Bit 0 = 1 . . 4 Byte Parm Pointer CHANNEL parameter format 1 to 30 parameter pointers For the CHANNEL parameter format. the channel has the same name as the called program. Bit 0 = 1 . Register 1 points to a list of pointers. No COMMAREA is passed in the CHANNEL parameter format. where the maximum value of n is 30. Register 1 Address of EIB Address of COMMAREA 4 Byte Parm Pointer High Order Byte. . followed by the addresses of buffers of parameter data (one for each parameter).Register 1 4 Byte Parm Pointer High Order Byte. A channel is a set of containers that function like parameters for passing data between CICS programs. the program uses a CICS API call to retrieve the name of the channel that was passed. containers are passed in a channel. when an EGL called program receives a channel. . . CICSOSLINK is valid only for STATIC and DYNAMIC linkage types. However. 4 Byte Parm Pointer 1 to 30 parameter pointers CICSOSLINK parameter format For the CICSOSLINK parameter format. The first is the address of the EIB. When an EGL generated program passes a channel to a called program. the EIB and COMMAREA are always passed as the first two parameters followed by the parameters specified on the call statement. The program must also be link-edited according to CICS command level programming rules. if the non-EGL program is written in a language other than assembler or COBOL. Calls from an EGL program to a non-EGL program The call statement that calls a non-EGL program is implemented in the same way as when calling an EGL program. Refer to the CICS application programmer’s reference for more details. as shown in the following table: Table 42. and parmForm properties. If the linkage type or parameter format is changed. the COBOL runtime environment disables the CICS abend handling requested by the calling program on entry to the called program.000 bytes representing the record 4 bytes representing the pointer to the STRING (the called program must be EGL) Calls from an EGL program to an EGL program The called program runs and returns control to the calling program when the program ends or an exit program statement is encountered. the called program and all programs that call it must be generated again. STATIC. Up to 30 parameters can be passed on the call statement. Record (33. For a description of the parameter formats used for calls. you can set the linkType option in the callLink entry for the called program to DYNAMIC. No CICS SYNCPOINT occurs as a result of a call statement. The user program name must be defined to CICS and the program must exist in the operating system load library. and EGL STRING.For example. if you pass three parameters of type INT. see “Format of call statement parameters for CICS” on page 256. linkType. or a NOT FOUND condition results. For a description of the parameter formats used for calls. v Specify pgmType = EXTERNALLYDEFINED on the callLink entry for the called program. In this situation. The type. Example containers and parameters Container name EGL-PARM-1 EGL-PARM-2 EGL-PARM-3 Value in container 4 bytes representing the INT 33. linkType.000 bytes). you must include a callLink entry for the non-EGL program in the linkage option part with the correct values for the type. you must also specify one of the following options: v Set the isExternal property to YES on the EGL call statement. If the non-EGL program is written in assembler or COBOL. If the non-EGL program uses a linkage convention other than the default (linkType = CICSLINK and parmForm = COMMPTR). However. or CICSLINK. or if it is called using EXEC CICS LINK. Handling abends on calls from EGL programs to non-EGL programs In CICS there are abend handling considerations when an EGL program uses a COBOL CALL instead of a CICS LINK to call a non-EGL COBOL program. see ″Format of call statement parameters″ above. Transfer of control across programs 259 . and parmForm properties for a called program must be identical when generating both the calling and called program. The called program should reinstate the abend handler for the EGL program by issuing a CICS POP HANDLE statement on entry to the called program and a CICS PUSH HANDLE statement on exit from the called program. the channel will include three containers. This might lead to an unnecessary copy of a shared table remaining in storage. No Rational COBOL Runtime for zSeries error messages are issued by the abend handler. . Examples of COMMPTR definitions in programs When an EGL program uses CICSLINK and COMMPTR to pass parameters to a non-EGL program. . . 02 PARM1A 02 PARM2A 02 PARM3A 01 PARM1.DFHEICAP PARMAREA. . pointers to the parameters are passed in the CICS COMMAREA. PARMPTR.PARM3PTR Address parameter list Address parameter 1 Address parameter 2 Address parameter 3 And so on F F F * L10 L20 L200 Define storage layout of parmlist Passed pointer to parameter 1 Passed pointer to parameter 2 Passed pointer to parameter 3 Define storage layout of passed parm Parameter is a record Fields in record structure " " " " And so on L5 * L5 L5 Define storage layout of passed parm Parameter is single data item level-77 Define storage layout of passed parm Parameter is working storage Fields in working storage " " And so on COBOL receiving parameters from CICSLINK with COMMPTR: LINKAGE SECTION. The following sections show examples of how non-EGL programs can receive parameters passed using CICSLINK and COMMPTR. normal error cleanup for the EGL program is not performed. The shared table use count is not updated when the program ends unsuccessfully. USAGE IS POINTER. Refer to the application programming guide for your CICS environment for more information on using COBOL calls in a CICS environment. 01 DFHCOMMAREA. USAGE IS POINTER.PARM3A PARM3. PARM2 DSECT L7701 DS PARM3 DSECT WORKSTOR EQU FLD5 DS FLD6 DS . Assembler language receiving parameters from CICSLINK with COMMPTR: L USING L USING L USING L USING . . PIC X(20).PARM2PTR PARM3PTR. 03 FLD1 03 FLD2 03 FLD3 . . 02 RECORD.PARM1PTR PARM2PTR. PARMAREA DSECT PARM1A DS PARM2A DS PARM3A DS PARM1 DSECT RECORD EQU FLD1 DS FLD2 DS FLD3 DS . .PARM1A PARM1.PARM2A PARM2. PIC X(10).PARMPTR PARM1PTR. PIC X(200). USAGE IS POINTER. And so on 260 EGL Programmer’s Guide .If the abend handler is not reinstated and an abnormal termination occurs in the called program. Related concepts “Transfer of control across programs” on page 251 Related tasks “Transferring control in CICS environments” Transferring control in CICS environments Transfers in the CICS environment are supported in the following ways: v A transfer to program statement is implemented as a CICS XCTL command. PROCEDURE DIVISION. 01 PARM2. If they are not the same the results are not predictable. 02 WORKSTOR. The format of variables in the parameter list must match the definition specified for the parameters received by the called program. 03 FLD5 PIC X(5). The following example shows the format of CICS LINK for a program call to a program generated with the COMMPTR parameter format: EXEC CICS LINK PROGRAM('MYAPPL') COMMAREA(record of pointers) LENGTH(length of COMMAREA) If the linkType is DYNAMIC or STATIC. . which is stored in register 15. Calls from a non-EGL program to an EGL program The EGL program must be defined as a called program. The calling non-EGL program is responsible for setting the parameters as specified in the linkage option part for the called program when it was generated. And so on . v A transfer to transaction statement is implemented as one of the following commands: – a CICS START command if the genReturnImmediate build descriptor option is set to NO – a CICS RETURN IMMEDIATE command if the genReturnImmediate build descriptor option is set to YES Setting genReturnImmediate to YES is supported only for CICS for z/OS systems Transfer of control across programs 261 . This return code. can be tested by the calling non-EGL programs.returnCode. SET ADDRESS OF PARM1 TO PARM1A SET ADDRESS OF PARM2 TO PARM2A SET ADDRESS OF PARM3 TO PARM3A . . And so on . 01 PARM3. 02 L7701 PIC X(5). 03 FLD6 PIC X(5). at exit the called EGL program sets the COBOL special register RETURN-CODE to the value of the EGL variable sysVar. .. See “Format of call statement parameters for CICS” on page 256 for diagrams of the linkage generated for different parameter formats as specified in the linkage option part. Transfer from an EGL program to an EGL program using transfer to program The EGL program immediately transfers control to the target program using a CICS XCTL command. A transfer to program from an EGL program to a non-EGL program is implemented in the same way as a transfer from one EGL program to another. if specified. The following sections provide a more detailed description of how a transfer to program statement works in the CICS environment. A CICS SYNCPOINT occurs on a transfer to program statement if either of the following situations occurs: v You set the synchOnPgmTransfer build descriptor option to YES and a PSB is scheduled. and linkType = EXTERNALLYDEFINED in the transferToProgram element in the linkage options part used during generation. toPgm. That parameter must point to a valid EGL program name. A record. The originating program must be defined as a main program. is passed in the COMMAREA. Otherwise. no CICS SYNCPOINT occurs. You must either specify isExternal = YES on the transfer to program statement or specify fromPgm. Transfer from a non-EGL program to an EGL program using CICS XCTL The originating program issues a CICS XCTL command to transfer to the target EGL program. The following example shows the command that EGL generates to transfer program control: EXEC CICS XCTL('applnam') COMMAREA(record) LENGTH(length of record) Transfer from an EGL program to a non-EGL program using transfer to program The EGL program immediately transfers control to the target non-EGL program by issuing a CICS XCTL to the program name specified in the transfer to program statement. v You set the synchOnPgmTransfer build descriptor option to NO for the originating program and the originating program had scheduled a PSB and different default PSB names were specified for the PSB records for the two programs. A transfer to program statement continues the same CICS transaction. and the target program name is the only required parameter. A record can be passed and will be used to initialize the record identified by the inputRecord property of the EGL program. A CICS SYNCPOINT occurs on a transfer to program statement if a PSB is scheduled. is passed in the COMMAREA. The isExternal property or the EXTERNALLYDEFINED link type indicate that all resources allocated by Rational COBOL Runtime for zSeries are released. Transfer to program A transfer to program statement can specify an optional record.v A show statement with an associated form and a returning clause is implemented as a CICS RETURN TRANSID command. The non-EGL program receives data in the COMMAREA. EXEC CICS XCTL ('applnam') COMMAREA(record) LENGTH (length of record) 262 EGL Programmer’s Guide . A record. if specified. transactionID within the program before the first converse statement. transfer to transaction with genReturnImmediate=″NO″: If you set the genReturnImmediate build descriptor option to NO. You can set sysVar. it sets sysVar. The following sections provide a more detailed description of how a transfer to transaction statement works in the CICS environment. The new transaction is scheduled as soon as the first transaction ends. CICS starts the new CICS transaction on the same terminal as the originating program if the terminal is not currently in TRANSACTION status. the originating program issues an EXEC CICS START command for the target transaction. Recoverable resources are committed as part of the transfer process. The following example shows the format of the START command that EGL generates if a record is specified in the transfer to transaction statement: EXEC CICS START TRANSID('transid') FROM(record) LENGTH(length of record) TERMID(current-terminal) EGL always includes the TERMID option of the CICS START command if the transfer to transaction is issued from a main text UI program. If a record is specified in the transfer to transaction statement. be sure that before the target program issues a converse statement. The transaction is not invoked unless the terminal is in TRANSCEIVE status in the CICS TCT. v Moving the transaction code to sysVar. when the input from the terminal is received. A START command refers to a CICS transaction ID that is 4 characters or less. After starting the new transaction.transactionID to the proper transaction code by doing one of the following: v Specifying the transaction code as the restartTransactionID build descriptor option. the record is passed as FROM data on the EXEC CICS START command. transfer to transaction with genReturnImmediate=″YES″: If you set the genReturnImmediate build descriptor option to YES. the originating program Transfer of control across programs 263 . Transfer to transaction A transfer to transaction statement can specify an optional record. the program issuing the transfer to transaction statement ends. the FROM and LENGTH parameters are not used. Otherwise. This transfer to transaction statement causes a new CICS transaction to be invoked. Transfer from an EGL program to an EGL program using transfer to transaction The following sections describe the differences in the transfer to transaction statement depending on the value you specify for the genReturnImmediate build descriptor option. the default value in sysVar.If the target program is segmented. The started transaction can start a non-EGL program or an EGL program defined as a main text UI program.transactionID (the current transaction code) causes the non-EGL program to be restarted instead of the target EGL program. otherwise.transactionID to a transaction code associated with the target program in a CICS TRANSACTION entry. You must either specify isExternal = YES on the transfer to transaction statement or specify the toPgm and externallyDefined = YES in the transferToTransaction element in the linkage options part used during generation. The first 10 bytes of the COMMAREA received by the target program is binary zeros. EXEC CICS RETURN TRANSID('transid') COMMAREA(name of COMMAREA) LENGTH(length of COMMAREA) IMMEDIATE Transfer from an EGL program to a non-EGL program using transfer to transaction A transfer to transaction statement from an EGL program to a non-EGL program is implemented in different ways depending on the genReturnImmediate build descriptor option. Because transfer to transaction starts a new CICS transaction. A record can be passed in the FROM area of the START command. If the genReturnImmediate build descriptor option is set to NO. The first 10 bytes are binary zeros indicating that this is a transfer to transaction statement passing a record. the transfer to transaction statement is implemented as an EXEC CICS START command. that record is found in the COMMAREA starting at the 11th byte. The transaction is not invoked unless the terminal is in TRANSCEIVE status in the CICS TCT. If a record is specified in the transfer to transaction statement. If a record is specified. it is used to initialize the record identified by the inputRecord property for the EGL program.issues an EXEC CICS RETURN IMMEDIATE command for the target program. The following CICS command retrieves the passed record: EXEC CICS RETRIEVE INTO(myWorkingStorageArea) LENGTH(workLength) Be sure to put the length of myWorkingStorageArea into workLength before executing the RETRIEVE command. The following example shows the EXEC CICS RETURN IMMEDIATE command that EGL generates if a record is specified on the transfer to transaction statement. the record is passed in the 11th through nth bytes of the COMMAREA. CICS also passes the length of the retrieved data to the program. This length is zero if no record is passed. If a record is passed. If the genReturnImmediate build descriptor option is set to YES. The terminal must be specified in the TERMID option of the CICS START command if a main text UI program is being started. a CICS SYNCPOINT occurs as a result of the transfer statement. The record passed when using a transfer to transaction statement is put into CICS temporary storage. You can use the isExternal or the externallyDefined option to provide documentation that this is a transfer to a non-EGL program. The example below shows the format of the START command that can be used when passing a record to the EGL program: 264 EGL Programmer’s Guide . The target EGL program can specify a form in its inputForm property that will be displayed automatically when the program loads. then the transfer to transaction statement is implemented as an EXEC CICS RETURN IMMEDIATE. The non-EGL target program must retrieve the record into its own data area. Transfer from a non-EGL program to an EGL program using CICS START The program can issue a CICS START command for the CICS transaction ID associated with an EGL program. the originating (non-EGL) program can issue a CICS RETURN IMMEDIATE command for the CICS transaction. you must set the genReturnImmediate build descriptor option to YES when generating the EGL program to be started. The target transaction must be associated with an EGL program. Transfer using show If you want to specify a form name in a transfer of control. it is used to initialize the record identified by the inputRecord property for the EGL program. The target EGL program can specify a form in its inputForm property that will be displayed automatically when the program loads. The first 10 bytes must be binary zeros. Using asynchronous tasks You can use the EGL system function vgLib. the originating program displays the form and returns to CICS. The CICS RETURN command specifies the target transaction ID from the show statement as the next transaction to be scheduled when the program user responds to the screen. The following example shows the format of the CICS RETURN IMMEDIATE when you pass a record to the EGL program: EXEC CICS RETURN TRANSID('transid') COMMAREA(10 bytes of low-values + record) LENGTH(10 + length of record) IMMEDIATE If you use CICS RETURN IMMEDIATE to transfer to an EGL program. Transfer of control across programs 265 . When you specify a form name with a show statement that includes a returning clause. A record can be passed in the COMMAREA and must start in the 11th byte. Transfer from a non-EGL program to an EGL program using CICS RETURN IMMEDIATE If the EGL program was generated with the genReturnImmediate build descriptor option set to YES. The target program must have a form specified in its inputForm property. The following sections describe the techniques. the record is received in the COMMAREA by the target transaction and is used to initialize the record specified by the inputRecord property of the target program. If a record is passed. You cannot transfer to a non-EGL program using a show statement. You can also write a non-EGL program to start an EGL program asynchronously.startTransaction() to start an asynchronous transaction. you must use the show statement. The target transaction receives control after the user presses an event key. You can write the program that is started for the asynchronous transaction in either EGL or non-EGL. and this form must be identical to the form specified in the show statement. you can set the genReturnImmediate build descriptor option to either YES or NO when you generate the target program. If a record is specified in the show statement.EXEC CICS START TRANSID('transid') FROM(record) LENGTH(length of record) TERMID(current-terminal) If the originating program uses the EXEC CICS START command. v The target transaction must have a CICS TRANSACTION entry. v If the value of the termID parameter is binary zeros. To end the current transaction and start a new transaction at the current terminal. EGL issues the CICS START command with or without an associated device: v If termID is not specified. For example. specifically. The prID and termID parameters are ignored if the target transaction is started on a remote system. EGL assigns the current terminal identifier to the TERMID option in the CICS START command. Only the actual data portion of the record is passed in the FROM option of the CICS START command. prID. v If termID is specified and its value is not binary zeros. it must issue a CICS RETRIEVE to get the passed work area and terminal information. you can specify a different region by defining the asynchLink element in the linkage options part that is used when you generate the program that calls the vgLib. For more information. use the transfer to transaction or show statement rather than the vgLib.startTransaction(requestRecord. The requestRecord must be in the following format: v Bytes 1-2 of the record must be a SMALLINT field that is set to the length of the data portion of the record plus 10. termID The default behavior is to start a program that resides in the same CICS region.startTransaction() system function. EGL associates the specified device (terminal or printer) with the target transaction. If the started transaction is associated with an EGL program. To set the termID CHAR field to binary zeros. v If the first program in the started transaction is a non-EGL program. v Bytes 7-10 must be blank. that EGL program receives the data portion of the requestRecord into the record specified by the inputRecord property. EGL assigns the value of the prID parameter to the RTERMID option in the CICS START command but does not include the TERMID option. see “Retrieving data for a started task in a non-EGL program” on page 267. specifically. Depending on the value of the termID parameter. EGL assigns the value of termID to the TERMID option in the CICS START command but does not include the RTERMID option. however. 266 EGL Programmer’s Guide . Results are not predictable if the value in termID is the CICS terminal ID that is associated with the current transaction.Starting asynchronous tasks from an EGL program An EGL program starts an asynchronous task with a vgLib.startTransaction() statement that generates a CICS START command. v Bytes 3-6 must contain the CICS transaction ID. if you set the build descriptor option printDestination to TERMINALID when you generate the started EGL program. EGL associates no terminal with the target transaction.startTransaction() function might look like: vgLib. as in the following example: myCHAR = x"00000000". use an assignment statement containing a hex literal for 4 bytes of binary zeros. the prID parameter is the printer ID that is used to initialize the converseVar. v The data portion of the requestRecord starts in byte 11. the vgLib. EGL associates the current terminal with the target transaction.startTransaction() system function. specifically. In addition.printerAssociation system variable in the target transaction. Related concepts “Transfer of control across programs” on page 251 Related tasks “Calling programs in CICS environments” on page 254 Calling programs in IMS and z/OS batch environments In non-CICS environments. even though the value might be all zeros.printerAssociation in the started EGL program. standard OS linkage conventions are used. The results are not predictable if you specify the terminal ID that is associated with the current transaction.startTransaction() function. it contains the printer (prID parameter) specified for the vgLib. Transfer of control across programs 267 . The RTERMID and TERMID options have the following meanings when starting asynchronous tasks: v If you want to start an asynchronous task without an associated CICS terminal ID.startTransaction() system function (from byte 11 through the end of the requestRecord). v If you want to start a task with an associated terminal ID. the RTERMID value is used to initialize converseVar. The program can receive the data that was passed by doing the following: EXEC CICS RETRIEVE INTO (workRecord) LENGTH(length of workRecord) RTERMID(userRtermid) The options for the CICS RETRIEVE command have the following meanings when the non-EGL program is started as a result of vgLib. then omit the TERMID keyword from the START command. If the RTERMID option is not 4 bytes of binary zeros. The called program runs and returns to the calling program when the program ends. then the value you specify in the TERMID option should be a valid CICS terminal ID.startTransaction(): v workRecord must be defined to match the data portion of the requestRecord that you used in the vgLib. it should be ignored. Retrieving data for a started task in a non-EGL program Non-EGL programs started with the vgLib. v The value in the RTERMID option should be the print destination for the started EGL program. v If the RTERMID option contains 4 bytes of binary zeros. Up to 30 parameters can be passed on a call statement.Starting an EGL program asynchronously from a non-EGL program To start an asynchronous transaction that is associated with an EGL program from a non-EGL program. if you set the build descriptor option printDestination to TERMINALID when you generate the started EGL program. It uses the workRecord to initialize the record specified by the inputRecord property of the EGL program.startTransaction() system function must always include the RTERMID option on the CICS RETRIEVE command that is used to retrieve the passed record. v Be sure to put the length of workRecord into LENGTH. issue a CICS START command like the following: EXEC CICS START ('transid') FROM(workRecord) LENGTH(length of workRecord) TERMID(destTermid) RTERMID(asyncPrintDest) The started EGL program must be a main basic program. For more information. High Order Byte. and z/OS Batch can call subprograms generated for the z/OS Batch environment. The compiled COBOL CALL passes parameters using standard linkage conventions. Sharing called programs between environments Programs generated for IMS/VS. Bit 0 = 1 4 Byte Parm Pointer 1 to 30 parameter pointers Special considerations apply if you pass dliLib. with all parameters passed by reference. Calls from a non-EGL program to an EGL program The non-EGL program uses a standard COBOL CALL statement to call the EGL program. You can do this by generating the z/OS Batch program (with the build descriptor option prep set to NO) for all potential runtime environments before generating it for z/OS Batch (with the build descriptor option prep set to YES). not by content. Calls to programs written in PL/I must be made as static calls. Register 1 points to a list of parameter addresses. as in the following illustration. follow the rules for interfacing to other languages described in the application programming guide for your release of COBOL. If the non-EGL program is not written in COBOL. Calls from programs written in PL/I must be made as static calls. IMS BMP. not by content. . . You must ensure that the z/OS Batch program does not do anything that is not supported in all the runtime environments.Use the linkage options part to specify the type of linkage generated for a call statement. Register 1 4 Byte Parm Pointer .psbData or a PCBRecord as a parameter. 268 EGL Programmer’s Guide . All parameters are passed by reference. For non-CICS environments. see “Format of the dliLib. Use the linkage options to specify whether the COBOL CALL is a dynamic or static call. If the non-EGL program is not written in COBOL. you can specify that the call statement be generated either as a DYNAMIC or a STATIC COBOL call with parameters passed using a standard COBOL parameter list (OSLINK). follow the rules for interfacing to other languages described in the application programming guide for your release of COBOL.psbData structure” on page 253 and “Format of a PCBRecord” on page 253. The parameters on the EGL call statement are the parameters on the COBOL CALL. Calls from an EGL program to a non-EGL program A call to a non-EGL program is generated in the same way as a call to an EGL program. The high order byte of the last parameter address is set to 1. All parameters are passed by reference. Calls from an EGL program to an EGL program EGL call statements are generated as standard COBOL CALLs. SELALMD represents the runtime services load library. substituting your program name for the name YOURPROG. set the parmForm property of the callLink element to COMMDATA. The called CICS program can be EGL developed or externally developed. see Link edit part examples. You must link edit the appropriate wrapper program with your EGL program. Use the linkage options part to specify how you want EGL to generate the call statement: v The type must be remoteCall. Transfer of control across programs 269 . use the link edit commands as shown below. When processing the call statement. and the program calls EGL programs repeatedly. create a link edit part with the same name as your EGL program. v To pass parameters to the called program. EGL generates the necessary COBOL code to call via EXCI. see “Calling programs in CICS environments” on page 254. EGL provides a wrapper program for each environment. If your EGL program does not need to be link edited with any programs other than the wrapper program. To do this automatically. To avoid the overhead and perform initialization and termination once. v The remoteComType must be CICSEXCI. for example). then Rational COBOL Runtime for zSeries performs initialization and termination functions on each call. z/OS Batch control statements: CHANGE NONVGRTN(YOURPROG) CHANGE ELAAPPL(ELAWBAT) INCLUDE SELALMD(ELAWBAT) ENTRY ELARMAIN NAME YOURPROG(R) IMS BMP control statements: CHANGE NONVGRTN(YOURPROG) CHANGE ELAAPPL(ELAWBMP) INCLUDE SELALMD(ELAWBMP) ENTRY ELARMAIN NAME YOURPROG(R) IMS/VS control statements: CHANGE NONVGRTN(YOURPROG) CHANGE ELAAPPL(ELAWIMS) INCLUDE SELALMD(ELAWIMS) ENTRY ELARMAIN NAME YOURPROG(R) If you need to link your program with other modules (such as a PL/I program. Calling a CICS program from an EGL z/OS batch program z/OS uses the External CICS Interface (EXCI) to call programs in a CICS region. Calling a CICS program from the z/OS batch environment has the following limitations: v Client unit of work is not supported. For more information on these linkage options.Avoiding multiple calls to runtime services initialization If the first program invoked in the run unit is a non-EGL program. The overhead for these calls can be significant if the number of calls is large. v You cannot pass EGL variable length parameters (such as STRING type variables) to the called program. j). v DL/I is not supported. 270 EGL Programmer’s Guide . a program named calledExci is called from z/OS batch. implemented as an OS XCTL macro. – transfer to transaction. Example In the following example. or as an OS XCTL macro when transferring to a non-EGL program.psbData structure” on page 253 “Format of a PCBRecord” on page 253 Related tasks “Transferring control in the IMS/VS environment” on page 275 “Transferring control in IMS BMP and z/OS batch environments” “Calling programs in CICS environments” on page 254 Transferring control in IMS BMP and z/OS batch environments Transfers in the IMS BMP and z/OS batch environments are implemented in the following ways: v An EGL program initiates the transfer with either of the following statements: – transfer to program.v Channels and containers are not supported for the EXCI call from the z/OS batch environment. v A non-EGL program initiates a transfer to an EGL program with the OS XCTL command. implemented as either a static or dynamic call when transferring to another EGL program. Related concepts “Transfer of control across programs” on page 251 Related reference “Format of the dliLib. The call uses the following linkage options: v remoteComType = CICSEXCI (required) v alias = CALLED v location = NQA17C03 (required) v luwControl = SERVER v parmForm = COMMDATA v v v v v pgmName = calledExci remotePgmType = EGL | EXTERNALLYDEFINED (has no effect) serverID = ABCD (default is CSMI) type = REMOTE conversiontable (has no effect) The calling program includes the following EGL statement: call "calledExci"(d. The next table outlines the different ways of implementing the transfers. control again returns to the EGL COBOL runtime stub program. the transferring EGL program ends and returns to a COBOL runtime stub program linked with the EGL program. the transferring EGL program ends and returns control to the EGL COBOL runtime stub linked with the EGL program. The stub issues an OS XCTL macro to transfer to the target program. The EGL COBOL runtime stub program remains in control. the transferring EGL program ends and returns to the EGL COBOL runtime stub program linked with the EGL program. If the EGL transfer-to program in turn uses a transfer to program statement. the EGL transfer-to program starts at its main function. Both COBOL and Rational COBOL Runtime for zSeries use termination logic for the OS XCTL.EGL Statement transfer to program From Program EGL To Program EGL Non-EGL How Implemented COBOL CALL OS XCTL Non-EGL transfer to transaction EGL EGL EGL Non-EGL Non-EGL EGL The EGL build server statically links an EGL COBOL runtime stub program with each generated main program. Transfer from an EGL program to an EGL program using transfer to program When an EGL program uses a transfer to program statement to transfer control to another EGL program. You can set the synchOnTrxTransfer build descriptor option to YES to control commit points. Both COBOL and Rational COBOL Runtime for zSeries clean up and reestablish the runtime environment each time an OS XCTL macro is used. The stub also fulfills the transfer request in response to a transfer statement issued by any program in the run unit. and the EGL runtime environment remains active. Both COBOL and Rational COBOL Runtime for zSeries clean up the runtime environment each time an OS XCTL macro is used. The stub issues an OS XCTL macro to transfer to the non-EGL program. The non-EGL program establishes it own runtime environment and does any initialization logic Transfer of control across programs 271 . In each case. which handles the requested transfer. for the EGL transfer-from program. The stub issues a static or dynamic call in accordance with the linkage options part specified at generation time. This EGL COBOL runtime stub activates the EGL runtime environment and starts the first program in the run unit. Both COBOL and Rational COBOL Runtime for zSeries use termination and initialization logic for the OS XCTL. Transfer from an EGL program to an EGL program using transfer to transaction When an EGL program uses a transfer to transaction statement to transfer control to another EGL program. Transfer to a non-EGL program using either transfer to program or transfer to transaction When an EGL program uses a transfer to program or transfer to transaction statement to transfer control to a non-EGL program. 272 EGL Programmer’s Guide . For more information. only the record specified on the transfer is passed. Two ways of passing parameters with the OS XCTL command are described in the following sections. The second parameter. If the EGL program was started with a PSB.psbData structure. Reference information for transfers The following sections describe the two ways of passing parameters to an EGL program using an OS XCTL command. used only if the EGL program is a DL/I program. v Specify the externallyDefined option in the linkage options part. The target program can issue a FREEMAIN for the parameters passed from the EGL program. and the working storage data. The first parameter is the working storage buffer consisting of a 2-byte binary length field containing the buffer length (working storage data length plus 10). Otherwise. you must indicate that you are transferring to a non-EGL program. in the linkage information for the transferToProgram or transferToTransaction element. is the dliLib. an 8-byte filler field.psbData structure are passed as OS XCTL parameters. When a transfer to program or transfer to transaction statement is used. Standard linkage conventions One or two parameters are passed to the receiving program on the OS XCTL. both the record specified on the transfer and the dliLib. You can set the build descriptor option synchOnTrxTransfer to YES to control commit points.psbData. The FREEMAIN length is the value in the length field plus 100. See “Standard linkage conventions.psbData structure” on page 253.” Special considerations apply if you pass dliLib. see “Format of the dliLib. The following diagram shows the format of the parameter list that the transferring program should pass. Transfer from a non-EGL program to an EGL program using OS XCTL Transfers from a non-EGL program to an EGL program in the IMS BMP and z/OS batch environments can be implemented by using an OS XCTL to the EGL program.required by the OS XCTL. The FREEMAIN address is the address in register 1. in one of the following ways: v Set the property isExternal to yes on the transfer statement. Register 1 is 0 if no parameters are passed. obtain a single area for all passed data with a length equal to the length of the working storage data you want to pass plus 110 bytes (see the figure below).psbData Length (2 bytes) Filler (8 bytes) Working Storage Data dliLib.psbData Figure 3. put the length and filler fields starting at offset 100 in the area.psbData structure” on page 253 for the format of the dliLib. Transfer of control across programs 273 . and move the working storage data to be passed into the area at offset 110.psbData structure.Register 1 High order byte must have bit 0 = 1 Pointer to Working Storage Pointer to dliLib. Standard linkage conventions that support FREEMAIN in the EGL program If you want Rational COBOL Runtime for zSeries to issue a FREEMAIN for the areas passed to the EGL program. Register 1 can be set to 0 if there is nothing to pass. Passing parameters on OS XCTL: Example 1 See “Format of the dliLib. Set up the parameter list pointers at the top of the area. Issue the OS XCTL macro with register 1 pointing to the start of the area. psbData 008 PSB name 016 Simulated UIB pointer 020 Simulated UIB 026 Reserved for Host Services 100 Length of working storage 102 Reserved for Host Services 110 Working storage data PCB Address List Figure 4. Passing parameters on OS XCTL: Example 2 Note: The high-order bit must be turned on for one of the following pointers: v The pointer to working storage if dliLib.psbData if dliLib.psbData is not passed v The pointer to dliLib.psbData structure” on page 253 Related tasks “Calling programs in IMS and z/OS batch environments” on page 267 “Transferring control in the IMS/VS environment” on page 275 274 EGL Programmer’s Guide . The input record for the EGL program is initialized according to data type if the EGL program is started with this interface.Register 1 000 Pointer to working storage 004 Pointer to dliLib. Related concepts “Transfer of control across programs” on page 251 Related reference “Format of the dliLib. The PCBs must map to the PSB definition expected by the EGL program. the non-EGL program can also transfer to the EGL program. passing a list of PCBs as parameters on the OS XCTL.psbData is passed. The EGL program receives control in this way if it is started as a DL/I z/OS batch job. PCB list linkage If the EGL program is a DL/I program. For a nonconversational MPP. this is less efficient than a deferred switch because the target program must be processed twice: once to display the input form and once to read the data entered by the program user. the message switch is achieved by modifying the SPA to specify the new transaction name before sending it back to IMS (using the I/O PCB). the program inserts a message using an alternate PCB that has its destination set to the new transaction name. v If inputForm is specified. The EGL program uses the defined properties for all other field properties. the message switch is achieved by including the next transaction name on the map in such a way that it becomes the first 8 bytes of the input message. For a nonconversational MPP. either a deferred program-to-program message switch (EGL show statement) or an immediate program-to-program message switch (EGL transfer to transaction statement) can be used. The definition and generation options of the target non-EGL program or EGL program control the type of switch that is possible and the way the data is passed. the program displays default data in any fields that did not have the MDT attribute set and were not modified by the program user. However. For more information. For a conversational MPP. an immediate message switch is required. If a non-EGL program does a deferred program-to-program message switch to an EGL program. see “Transferring to and from IMSADF II programs” on page 293. If the program user requests help or if edit errors occur. Transferring from conversational to nonconversational or from nonconversational to conversational is not supported for EGL programs. For a conversational MPP. The following types of message switches are supported: Immediate message switch Program A passes control directly to a transaction that is associated with program B without first responding to the originating terminal. the EGL program should use a deferred Transfer of control across programs 275 . A non-EGL program can invoke EGL MPP programs using an IMS program-to-program message switch. the program does this by inserting the scratch pad area (SPA) using an alternate PCB that has its destination set to the new transaction name. Deferred message switch Program A responds to the terminal and informs IMS to start a transaction that is associated with program B on the next input from the terminal.Transferring control in the IMS/VS environment Different considerations apply for transferring when IMSADF II programs are involved. the input form (identified in the inputForm property) is automatically displayed by the target program. the use of the property inputForm determines which type of message switch is valid: v If inputForm is not specified. Transferring program control with a transfer to transaction statement is not supported for IMS/VS main basic programs. If the target transaction is an EGL program. the non-EGL program should turn on the modified data tag (MDT) attribute for all fields on the form and should set all other field properties to the values that were defined during form definition. If the target transaction is a non-EGL program that needs form input from the message queue at the start of processing. If the immediate switch is used. EGL main Text UI programs that are generated for the IMS/VS target environment run as IMS message processing programs (MPPs). v An MFS map (EGL form) can be passed on a show statement only. If spaStatusBytePosition=n is specified. 276 EGL Programmer’s Guide . the segmentation status byte is placed in either position 15 or the last byte of the SPA. Generate both programs as conversational (spaSize > 0). Depending on whether you use a transfer to transaction or a show statement to accomplish the transfer. it uses a transfer to transaction statement to send a record. Program switching in conversational EGL programs (non-IMSADF interface) Action Coding and generating Immediate switch (optional input form) Define both programs as segmented = YES. Performing the transfer Using an input form Passing a record Specifying segmentation status byte The target program can optionally have an input form. it does this using a show with a form and an optional record. The transferring program must write the form to a message queue associated with the terminal after first writing the SPA. Deferred switch (with input form) Define both programs as segmented = YES. if any. the EGL program should use an immediate program-to-program message switch (EGL transfer to transaction statement).program-to-program message switch (EGL show statement). based on the value of n. However. Transferring between conversational programs The following table shows the methods used to pass data between conversational programs (generated with spaSize > 0 build descriptor option). Otherwise. If spaStatusBytePosition is specified. Note: The segmentation status byte specified by spaStatusBytePosition is used only for program-to-program transfers for conversational programs. is transferred in the SPA. The target program uses the value of the segmentation status byte when there is an input form integrity problem caused by the program user pressing PA1 or PA2. If it is an EGL program. Generate both programs as conversational (spaSize > 0). The way data is passed is controlled by the following factors: v Whether the program is conversational or nonconversational. The byte is present for transfers between conversational programs and other programs. the following can be passed between two programs: v A scratch pad area (SPA) can be passed on either a transfer to transaction or a show statement. The transferring program cannot send a form. A target non-EGL program should always ignore the value of the segmentation status byte. The record is transferred in the SPA. a transferring non-EGL program should always set the byte to blank. v Whether the switch is immediate or deferred. If it is an EGL program. The target program must have an input form. Table 43. The record. The target program always ignores the value of the segmentation status byte. the segmentation status byte is always placed in the last byte of the SPA. Different FormGroups can be used by the two programs. A conversational program always uses an SPA. v From an EGL program to a non-EGL program. end // end main end // end ProgramA program ProgramB type textUIProgram // inputForm is optional {segmented=yes. see “Format of the IMS SPA for message switching” on page 286 and “Format of the IMS MFS message input descriptor (MID)” on page 289. v On a show statement. EGL uses that data to initialize the input form for the program. on a deferred switch. .transferName = 'trx1b'. inputRecord="basicRecord1".For more information and layouts. EGL sends the form to the terminal. inputRecord="basicRecord1". // FormGroup use FORMGX.. The SPA is passed on both immediate and deferred message switches. @DLI { psb="psb" } } // Declarations basicRecord1 TRANSFER_RECORD. psb PSB1B. Transfer of control across programs 277 .. psb PSB1A. Immediate switch between two EGL programs: With this technique. two segmented conversational EGL programs can change both the transaction name and the PSB name without presenting a form to the program user. program ProgramA type textUIProgram {segmented=yes.. v From a non-EGL program to an EGL program. v When you use a transfer to transaction or a show statement to pass a record to another transaction. sysVar. If such a form exists. EGL does this as follows: v When the transaction first starts for a user. The example below shows a skeleton definition of the two programs. Conversational immediate program-to-program message switch Conversational immediate program-to-program message switches are supported in the following situations: v Between two EGL programs.. transfer to transaction sysVar. function main() . EGL sets the data portion of the SPA to the data in the specified record. EGL will check for a passed form. In addition. EGL initializes the input record for that program from the data portion of the SPA. When you generate an EGL main Text UI program with spaSize > 0. you can pass an MFS map to a terminal. @DLI { psb="psb" } } // Declarations basicRecord1 TRANSFER_RECORD. inputForm="form2". EGL uses the SPA as follows v When the transaction first starts for a user.transferName passing basicRecord1. end // end main end // end ProgramB The EGL-generated program control logic automatically handles the SPA and the record (basicRecord1) that is passed from Program A to Program B. The non-EGL program should initialize the segmentation status byte to blank before inserting the SPA. The data area of the SPA contains the record that the EGL program passed on the transfer to transaction statement. The EGL program must be defined similarly to program A in ″Immediate switch between two EGL programs″ above. SPA ID. the segmentation status byte is at the end of the SPA. The non-EGL program must do the following: 1. For the required layout of the SPA. If you specified spaSize=n and spaStatusBytePosition=p as build descriptor options. The EGL-generated program control logic removes the header information (length. 2. The spaSize build descriptor option must specify the SPA size that is being used by the non-EGL program. The SPA is created by the EGL program control logic.// FormGroup use FORMGY.. transaction name). regardless of the value of spaStatusBytePosition. the segmentation status byte is at the end of the SPA. regardless of the value of spaStatusBytePosition. The EGL program must be defined similarly to program B in ″Immediate switch between two EGL programs″ above. The non-EGL program must issue a get unique to the I/O PCB to read the SPA. Insert the SPA into an alternate PCB. Immediate switch from EGL program to non-EGL program: The non-EGL program must be an IMS conversational program. The spaSize build descriptor option must specify the SPA size that is being used by the non-EGL program.. Immediate switch from non-EGL program to EGL program: The non-EGL program must be an IMS conversational program. If you specified spaSize=n and spaStatusBytePosition=p as build descriptor options. The data area in the SPA must match the definition of the input record expected by the EGL program. The non-EGL program should ignore the last byte of the SPA. Create the SPA in the format defined in “Format of the IMS SPA for message switching” on page 286. The alternate PCB must have its destination set to the transaction name for the EGL program. see “Format of the IMS SPA for message switching” on page 286. so the EGL program receives only the data. function main() // generated EGL logic does the following: // initializes basicRecord1 // if inputForm is specified: // converses form2 // performs edits for form2 // converses form2 until form2 passes all edits // gives control to the first statement in the main function . The data area of the SPAs for programs A and B must be at least large enough to hold the larger of the records involved. 278 EGL Programmer’s Guide . You do not have to transfer a record.... v From a non-EGL program to an EGL program. end // end main end // end ProgramA program ProgramB type textUIProgram // inputForm is required {segmented=yes. function main() . inputForm="map2". The spaSize build descriptor option must specify the SPA size that is being used by the non-EGL program. two segmented conversational EGL programs can change both the transaction name and the PSB name when a form is presented to the program user. end // end main end // end ProgramB Deferred switch from non-EGL program to EGL program: The non-EGL program must be an IMS conversational program. // FormGroup use FORMG2. . inputRecord="basicRecord2". @DLI { psb="psb" } } // Declarations basicRecord2 TRANSFER_RECORD. The non-EGL program must do the following: Transfer of control across programs 279 . psb PSB2A..transferName passing basicRecord2. function main() // generated EGL logic does the following: // initializes basicRecord2 // performs edits for map2 // converses map2 until map2 passes all edits // gives control to the first statement in the main function .Conversational deferred program-to-program message switch Conversational deferred program-to-program message switches are supported in the following situations: v Between two EGL programs. @DLI { psb="psb" } } // Declarations basicRecord2 TRANSFER_RECORD. but a form is required. // FormGroup use FORMG2.. The example below shows a skeleton definition of the two programs. You must use the same formGroup for both programs. The EGL program must be defined similarly to program B in ″Deferred switch between two EGL programs″ above.. inputRecord="basicRecord2". psb PSB2B. program ProgramA type textUIProgram {segmented=yes. sysVar.transferName = 'trx2b'. show form2 returning to sysVar. Deferred switch between two EGL programs: With this technique. v From an EGL program to a non-EGL program. The non-EGL program must set the modified data tag (MDT) attribute for all variable data fields on the MFS map (EGL form) to be passed to the EGL program on the deferred switch. transaction name). 2. The SPA is created by the EGL program control logic. The EGL program must set the modified property to YES for all variable data fields on the form that are required as input in the non-EGL program. The EGL program must be defined similarly to program A in ″Deferred switch between two EGL programs″ above. For the required layout of the SPA. The data area in the SPA must match the definition of the input record expected by the EGL program. If you specified spaSize=n and spaStatusBytePosition=p as build descriptor options. then you must initialize the segmentation status byte at the offset within the SPA specified by spaStatusBytePosition=p. Create the SPA in the format defined in “Format of the IMS SPA for message switching” on page 286. Issue a get unique to the I/O PCB to read the SPA. EGL generates a COBOL copybook for the MID/MOD record layout that should be used by the non-EGL program to ensure that the record formats match. SPA ID. then an input map integrity problem has occurred. not the first transaction in the conversation). Deferred switch from EGL program to non-EGL program: The non-EGL program must be an IMS conversational program. The EGL program control logic removes the header information (length. The non-EGL program should ignore the value of the segmentation status byte. Issue a get next to the I/O PCB to retrieve the message input descriptor that corresponds to the message output descriptor used by the EGL program. see “Format of the IMS MFS message input descriptor (MID)” on page 289. the segmentation status byte is either at position 15 or at the last byte of the SPA. All other attributes should be left at their default values. The data area of the SPA contains the record that the EGL program passed on the show statement.1. If EZEMAP-SSM-FILLCHAR is true and this is not an initial SPA (that is. 2. Take whatever action is appropriate for the program to recover the data that was lost from the input map. 3. so the EGL program receives only the data. Initialize the segmentation status byte to blank. EGL generates a COBOL copybook for the MID/MOD record layout that should be used by the non-EGL program to ensure that the record formats match. 3. Insert the SPA into the I/O PCB. The non-EGL program must do the following: 1. Insert the MFS map (EGL form) into the I/O PCB using the message output descriptor that corresponds to the message input descriptor in the EGL program. 280 EGL Programmer’s Guide . see “Format of the IMS MFS message input descriptor (MID)” on page 289. The spaSize build descriptor option must specify the SPA size that is being used by the non-EGL program. possibly because the program user has pressed PA1 or PA2. Use the value of the map MID field EZEMAP-SSM-STATUS to determine whether there has been a MFS map (EGL form) integrity problem. If you specified spaSize=n and spaStatusBytePosition=p as build descriptor options. This might involve issuing an error message to the program user and restarting the transaction or taking other recovery actions depending on the program design. see “Format of the IMS SPA for message switching” on page 286. For the required layout of the map. For the required layout of the map. v From a non-EGL program to an EGL program. The transferring program must write the form to a message queue associated with the terminal. it uses a show statement with a form and an optional record. If it is an EGL program. v From an EGL program to a non-EGL program. For better performance. The record. v An MFS map (EGL form). A nonconversational program is a main textUI program generated with the spaSize build descriptor option set to 0 (as is the default). Deferred switch (with input form) Define both programs as segmented = YES. Immediate switch between two EGL programs: When developing EGL programs. Generate both programs as nonconversational (spaSize = 0). however. For the record layout and an example of the COBOL definition for a map message input descriptor (MID) for a deferred program-to-program message switch. Table 44. The target program must have an input form. it uses a transfer to transaction with a record. See “Format of EGL input message segment for IMS message switch” on page 288.Transferring between nonconversational programs The following table shows the methods used to pass data between nonconversational programs. If it is an EGL program. The same MID and MOD definitions are used for conversational and nonconversational transfers. Nonconversational immediate program-to-program message switch Nonconversational immediate program-to-program message switches are supported in the following situations: v Between two EGL programs. Depending on whether a transfer to transaction or a show statement used. The record is transferred in the message. The transferring program cannot send a form. The outlines of the two programs are identical to those in a conversational immediate switch between two EGL programs. the difference is in the value of the spaSize build descriptor option at generation time. Performing the transfer Using an input form Passing a record The target program can optionally have an input form. Different form groups can be used by the two programs. except that the spaSize build descriptor option is set to 0 (nonconversational). Generate both programs as nonconversational (spaSize = 0). you may omit the inputForm for program B: Transfer of control across programs 281 . With this technique two nonconversational EGL programs can change both the transaction name and the PSB name without presenting a form to the program user. if any. this technique is the same as transferring with segmented conversational EGL programs. is transferred in the work database. the following can be passed on a transfer between two nonconversational programs: v An IMS message segment. see “Format of the IMS MFS message input descriptor (MID)” on page 289. Program switching in nonconversational EGL programs (non-IMSADF interface) Action Coding and generating Immediate switch (optional input form) Define both programs as segmented = YES. . sysVar. The non-EGL program must supply the header information (length. inputRecord="basicRecord1".″ The non-EGL program must insert a message to an alternate PCB. end // end main end // end ProgramB The EGL-generated program control logic automatically handles the IMS message that is used to transfer control and the record that is passed from program A to B. so the EGL program receives only the data. psb PSB1B. @DLI { psb="psb" } } // Declarations basicRecord1 TRANSFER_RECORD. see “Format of EGL input message segment for IMS message switch” on page 288. and transaction name) in the message. inputForm="form2".. inputRecord="basicRecord1".. Immediate switch from EGL program to non-EGL program: The non-EGL program must be an IMS nonconversational program.. transfer to transaction sysVar. Immediate switch from non-EGL program to EGL program: The non-EGL program must be an IMS nonconversational program. function main() // generated EGL logic does the following: // initializes basicRecord1 // if inputForm is specified: // converses form2 // performs edits for form2 // converses form2 until form2 passes all edits // gives control to the first statement in the main function . The destination must be set to the transaction name for the EGL program. The EGL-generated program control logic automatically removes the header information.program ProgramA type textUIProgram {segmented=yes. end // end main end // end ProgramA program ProgramB type textUIProgram // omit inputForm for better performance {segmented=yes. // FormGroup use FORMGY.transferName = 'trx1b'.″ 282 EGL Programmer’s Guide .transferName passing basicRecord1... psb PSB1A. ZZ. . The EGL program must be defined similarly to program A in the nonconversational ″Immediate switch between two EGL programs. // FormGroup use FORMGX. For the required layout of the message. function main() . The EGL program must be defined similarly to program B in the nonconversational ″Immediate switch between two EGL programs. @DLI { psb="psb" } } // Declarations basicRecord1 TRANSFER_RECORD. Deferred switch between two EGL programs: From an EGL developer’s viewpoint. With this technique two nonconversational EGL programs can change both the transaction name and the PSB name when a form is presented to the program user.transferName passing basicRecord2. @DLI { psb="psb" } } // Declarations basicRecord2 TRANSFER_RECORD. The outlines of the two programs are identical to those in the conversational deferred switch between two EGL programs. but a form is required. v From a non-EGL program to an EGL program. inputRecord="basicRecord2". ZZ. Nonconversational deferred program-to-program message switch Nonconversational deferred program-to-program message switches are supported in the following situations: v Between two EGL programs.. indicating nonconversational programs. end // end main end // end ProgramA program ProgramB type textUIProgram // inputForm is required {segmented=yes. You do not have to transfer a record. show form2 returning to sysVar. the difference is in the value of the spaSize build descriptor option at generation time: program ProgramA type textUIProgram {segmented=yes. function main() . inputRecord="basicRecord2". inputForm="map2". . sysVar. this technique is identical to transferring with segmented conversational EGL programs. so the EGL program defines only the data.The non-EGL program must issue a get unique to the I/O PCB to retrieve the record that the EGL program passed on the transfer to transaction statement.. function main() // generated EGL logic does the following: // initializes basicRecord2 // performs edits for map2 // converses map2 until map2 passes all edits Transfer of control across programs 283 . // FormGroup use FORMG2. psb PSB2B. transaction name).. see “Format of EGL input message segment for IMS message switch” on page 288. @DLI { psb="psb" } } // Declarations basicRecord2 TRANSFER_RECORD. The EGL-generated program control logic automatically supplies the header information (length. For the required layout of the message. You must use the same formGroup for both programs. the non-EGL program must be prepared to accept the header information. psb PSB2A. v From an EGL program to a non-EGL program.transferName = 'trx2b'. // FormGroup use FORMG2.. except that the spaSize build descriptor option is set to 0. However. The EGL program must be defined similarly to program B in the nonconversational ″Deferred switch between two EGL programs. Interfacing through serial files in IMS EGL programs can communicate with non-EGL programs by performing add or get next statements on records in serial files that are associated with the IMS message queue. EGL generates a COBOL copybook for the MID/MOD record layout that should be used by the non-EGL program to ensure that the record formats match. see “Using the EGL COBOL runtime work database for IMS/VS” on page 291. For details. see “Format of the IMS MFS message input descriptor (MID)” on page 289..″ The EGL program must set the modified property to YES for all variable data fields on the form that are needed as input in the non-EGL program. The following types of programs can add records to serial files: v Main textUI programs v Main basic programs v Called programs Only main basic programs can retrieve records from serial files (using get next). see “Format of the IMS MFS message input descriptor (MID)” on page 289. The non-EGL program must do the following: 1. For the required layout of the map. All other attributes should be left at their default values. If a record is being transferred. Deferred switch from EGL program to non-EGL program: The non-EGL program must be an IMS nonconversational program. For the required layout of the map. If you are transferring a record. Insert the MFS map (EGL form) to the I/O PCB using the message output descriptor that corresponds to the message input descriptor used by the EGL program. EGL generates a COBOL copybook for the MID/MOD record layout that should be used by the non-EGL program to ensure that the record formats match. call ELATSGET to retrieve the record that the EGL program passed on the show statement from the work database. The non-EGL program must set the modified data tag (MDT) attribute for all variable data fields on the map to be passed to the EGL program on the deferred switch. end // end main end // end ProgramB Deferred switch from non-EGL program to EGL program: The non-EGL program must be an IMS nonconversational program. see “Using the EGL COBOL runtime work database for IMS/VS” on page 291. Issue a get unique to the I/O PCB to retrieve the message input descriptor that corresponds to the message output descriptor used by the EGL program.″ The non-EGL program must do the following: 1. call ELATSPUT to save the record in the work database for the EGL program. 284 EGL Programmer’s Guide .. For details on using ELATSPUT. 2.// gives control to the first statement in the main function . 2. The EGL program must be defined similarly to program A in the nonconversational ″Deferred switch between two EGL programs. The EGL program is only concerned with the actual data in the message. This must be the name of an alternate PCB. The format of the message actually inserted to the message queue and received by the non-EGL program is shown in the table in the previous section. An EGL basic program uses get next to read a serial file associated with the I/O PCB and then processes the message. From non-EGL program to EGL program A non-EGL program can write a series of records to the IMS message queue for later processing by an EGL basic program. running as either an MPP or a transaction-driven batch message processing program (BMP). This area contains the data items defined in the EGL serial record. can then use the file to read the messages with get next statements. running as either an MPP or a transaction-driven BMP. ZZ. The IMS transaction name for the EGL program. the EGL program automatically adds the IMS message header in front of the record data. An EGL basic program. The non-EGL program must insert a record in the format shown in the following table to an alternate I/O PCB associated with the transaction that processes the record. v The PCB name to be used. and then inserts the message to the alternate PCB. and transaction name). A non-EGL program running as either an MPP or a transaction-driven BMP can process the message queue. so the program receives only the message data in the serial record. The EGL program automatically removes the IMS message header (segment length. and transaction name). From EGL program to non-EGL program When an EGL program does an add to a serial file associated with a message queue. The EGL program automatically strips the header information from the message and puts the data into the serial record. The transaction name is created from the default systemName specified in the ResourceAssociations part at generation time. ZZ. Table 45. ″From non-EGL program to EGL program.″ Related concepts “Transfer of control across programs” on page 251 Related reference Transfer of control across programs 285 .Between EGL programs An EGL program can add a series of serial records to the IMS message queue by specifying the following information in a ResourceAssociations part at generation: v Indication that the file is a message queue (fileType set to smsgq or mmsgq). Format of the record inserted to the message queue Field Segment length Reserved (ZZ) IMS transaction name Programdefined fields Length in bytes 2 2 8 Variable Type of data Binary Binary Character Variable Description The length of the segment. Do not include IMS header information in the EGL serial record definition. or in the value of the resourceAssociation variable for the record (if it is used to override the default). The EGL program automatically handles the IMS header information (segment length. Reserved. spaStatusBytePosition This optional field is set either to 15 (if the status byte is to precede the data) or to the same value as spaSize (if the status byte follows the data). and IMS transaction name) as well as the EGL requirement for a Segmentation Status Byte. This area contains the record passed on the transfer to transaction statement and received by the target program in its input record. It indicates whether data was saved in the work database. This name must not be changed by the MPP. SPA ID. v “Format of the IMS SPA for message switching” v “Format of EGL input message segment for IMS message switch” on page 288 v “Format of the IMS MFS message input descriptor (MID)” on page 289 v “Using the EGL COBOL runtime work database for IMS/VS” on page 291 Format of the IMS SPA for message switching EGL defines the format of the IMS scratch pad area based on the following build descriptor options: spaSize Specifies the total length of the SPA. Format of IMS scratch pad area Field SPA length SPA ID Length in bytes 2 4 Type of data Binary Binary Description The length of the segment. Table 46. IMS transaction name Segmentation Status Byte (Optional) 8 1 Character Hexadecimal Program data Variable Variable 286 EGL Programmer’s Guide . including the fields required by IMS (SPA length.“Format of the IMS SPA for message switching” “Format of the IMS MFS message input descriptor (MID)” on page 289 “Using the EGL COBOL runtime work database for IMS/VS” on page 291 “Format of EGL input message segment for IMS message switch” on page 288 Related tasks “Transferring to and from IMSADF II programs” on page 293 Reference information for IMS/VS transfers The following sections provide reference information for call and transfer statements in the IMS/VS environment or when DL/I databases are being used. A unique name used to identify the SPA to IMS. This optional byte is present if spaSize=n and spaStatusBytePosition=15 was specified and this is a deferred switch. The IMS transaction name for the EGL program. . Refer to the IMS/VS documentation for your system for additional information.. the byte indicates whether data was saved in the work database. The specific field names are used for illustrative purposes only. This optional byte is also present if spaSize=n and spaStatusBytePosition=n was specified and this is a deferred switch.... PIC . The data identified as ″Program data″ in the table above is treated as the input record for the target program.. Format of IMS scratch pad area (continued) Field Segmentation Status Byte (Optional) Length in bytes 1 Type of data Hexadecimal Description This optional byte is present if this is an immediate switch.. it indicates whether data was saved in the work database.. This optional byte is present if spaSize=n and spaStatusBytePosition=n was specified and this is an immediate switch. and the input Transfer of control across programs 287 . In this case the contents of the byte are ignored... (The status byte position will always be either 15.... and if spaSize=n and spaStatusBytePosition=n.. .. This optional byte is also present if spaSize=n and spaStatusBytePosition=n was specified and this is a deferred switch..... PIC .. It indicates whether data was saved in the work database. PIC X(1). the record specified on the transfer to transaction or show statement. This technique enables a non-EGL program to store data in the SPA and switch to an EGL program (or a series of EGL programs) that use or modify the SPA data... See Note 1. or equal to the size of the SPA if the status byte follows the data. The following example shows the COBOL definition for a scratch pad area passed in either a deferred or an immediate program-to-program message switch for conversational processing... 01 SPA. . if the status byte is to precede the data. 10 data-item-1 10 data-item-2 ..) In this case the contents of the byte are ignored. the actual field names might vary in the generated code.... X(1). 2. The EGL program can eventually switch back to a non-EGL program with information from the EGL program contained in the SPA. This optional byte is present if spaSize=n and spaStatusBytePosition=15 was specified and this is a deferred switch... 05 CSP-OPTIONAL-SSM-BYTE PIC PIC PIC PIC S9(4) COMP... SPA size and transfer record size: The following table defines how the SPA.. Follow the IMS restrictions regarding changes in the SPA size.... In this case... In this case. See Note 2..... The following notes apply to this example: 1.Table 46.. X(8). Keep in mind that PL/I requires a 4-byte length field rather than the 2-byte length field used for COBOL.. * SPA IO area.. S9(9) COMP. 05 SPA-LENGTH 05 SPA-ID 05 IMS-TRAN-NAME 05 CSP-OPTIONAL-SSM-BYTE 05 CSP-APPL-WS-DATA.. Reserved for IMS. Initialization of Size of the program data area Extra bytes of the program data area in in the SPA exceeds the size of the SPA are truncated when it is moved target into the input record. The following table shows the record layout: Table 48. the optional record is passed as a message segment for an immediate program-to-program message switch. The following example shows the COBOL definition for a working storage record passed via the message queue for an immediate program-to-program message switch. The IMS transaction name for the EGL program. program’s EGL record named as input record for the target program. and the remaining bytes of SPA are initialized to blanks. transfer record size The size of the program data area in the SPA exceeds the size of the EGL record named in the transfer to transaction or show statement. that of the EGL record named in the transfer to transaction. Keep in mind that PL/I requires a 4-byte length field rather than the 2-byte length field used for COBOL. the actual field names might vary in the generated code. 288 EGL Programmer’s Guide . and the remaining bytes of the input record are initialized based on the data type.record for the target program are related for conversational processing. transfer to transaction The size of the program data Extra bytes of the EGL record are area in the SPA is less than truncated. The fields defined for the EGL record. The specific field names are used for illustrative purposes only. Table 47. Format of EGL input message segment for IMS message switch When you use the transfer to transaction statement in an IMS nonconversational program. input record Initialization of Size of the program data area in the SPA is less than that of target the EGL record named as program’s input record for the target input record program. Relationship of IMS SPA to transfer record Function transfer to transaction Data area size vs. The input record is initialized from the program data area in the SPA. Refer to the IMS/VS documentation for your system for additional information. Results The program data area in the SPA is created using the entire EGL record. Format for nonconversational immediate message switch Field Segment length Reserved IMS transaction name Program data Length in bytes 2 2 8 Variable Type of data Binary Binary Character Variable Description The length of the segment. Related concepts “Transfer of control across programs” on page 251 Related tasks “Transferring control in the IMS/VS environment” on page 275 Related reference “Reference information for IMS/VS transfers” on page 286 The following sections provide reference information for call and transfer statements in the IMS/VS environment or when DL/I databases are being used. .. PIC X(8).... Transfer of control across programs Additional Rational COBOL Runtime for zSeries fields Program form fields 51 Variable Variable Variable 289 ............ some fields in the MOD are ignored.......... In addition..... the IMS transaction name and the value of the COND parameter (form name) are reversed... Table 49... 05 CSP-IMS-SEG-LENGTH 05 CSP-ZZ 05 CSP-IMS-TRANNAME 05 CSP-APPL-WS-DATA. 10 data-item-1 10 data-item-2 PIC .....01 CSP-APPL-WS-RECORD..... Format of the MFS message input descriptor (MID) Field Segment length Reserved IMS transaction name Reserved Form name Length in bytes 2 2 8 1 8 Type of data Binary Binary Character Character Character Description The length of the segment. PIC .. Reserved for IMS. This area contains the fields defined for the EGL form.... The IMS transaction name for the EGL program..... A group of fields that Rational COBOL Runtime for zSeries uses to validate the form........ Reserved for Rational COBOL Runtime for zSeries... 10 data-item-1 10 data-item-2 PIC S9(4) COMP... PIC S9(4) COMP... PIC ... PIC ..... the optional record is passed via the work database for a deferred program-to-program message switch..... Value for MFS COND parameter from the MID of a deferred program-to-program message switch...... Format of record for show statement When you use the show statement in an IMS nonconversational program. The following table shows the record layout: 01 CSP-APPL-WS-RECORD.. 05 CSP-APPL-WS-DATA.... The table below shows the record layout for a MID. For an MFS MOD............ Format of the IMS MFS message input descriptor (MID) The IMS MFS message input descriptor (MID) and message output descriptor (MOD) that are used to read and write forms to terminals for a deferred program-to-program message switch share the same basic format. Related concepts “Transfer of control across programs” on page 251 Related tasks “Transferring control in the IMS/VS environment” on page 275 “Transferring to and from IMSADF II programs” on page 293 Related reference “Reference information for IMS/VS transfers” on page 286 The following sections provide reference information for call and transfer statements in the IMS/VS environment or when DL/I databases are being used. The total length of all fields prior to the start of the program form fields is 72 bytes. Note 8 . 290 EGL Programmer’s Guide . 10 EZEMAP-HELP-MAP-NAME 10 EZEMAP-CURSOR. PIC X(8).. 15 EZEMAP-DATE PIC X(8). SCA is set to blanks. PIC X(2) OCCURS 5 TIMES. In a MID. 15 EZEMAP-BYPASS-PF-KEY PIC S9(4) COMP. REDEFINES EZEMAP-ZZ PIC S9(4) COMP. Note 1 PIC X(8). PIC X(2). 10 EZEMAP-LL 10 EZEMAP-ZZ 15 EZEMAP-Z1 15 EZEMAP-Z2 10 EZEMAP-ZZ-BIN 10 EZEMAP-MID-TRANCODE. Note 4 88 EZEMAP-SSM-PREMODIFIED VALUE X"0081".The following example shows the COBOL definition for a form message input descriptor (MID) for a deferred program-to-program message switch. PIC X(1). 15 EZEDATA PIC . . 05 EZEMAP-HEADER.. Note 7 15 EZEATTR PIC X(08). In a MOD. the transaction name and the map name are reversed. 05 EZEMFS-form-HEADER PIC X(72). SCA must be initialized to binary zeros by the program that inserts the MOD. 15 EZEMAP-COL PIC S9(4) COMP. 15 EZEMAP-ROW PIC S9(4) COMP. If a conversational transaction is started by using an IMS /FORMAT command. . 15 EZEMAP-MOD-MAP 10 FILLER 10 EZEMAP-MOD-TRANCODE. Refer to the IMS/VS documentation for your system for additional information. 10 EZEMAP-GEN-DATE-TIME. PIC X(1). Note 3 PIC X(2). 10 EZEMAP-SSM-STATUS PIC X(1). * CopyMember ELAAHMMI 01 EZEMAP-IO-AREA. IMS removes the transaction name from the data stream. 10 formField. Note 2 REDEFINES EZEMAP-SCA PIC S9(4) COMP. PIC X(1). 88 EZEMAP-SSM-FILL-CHAR VALUE X"FF". PIC X(8). 88 EZEMAP-SSM-WSR-SAVED VALUE "C". 10 EZEMAP-SSM-STATUS-ATTR PIC X(2). PIC X(2). 88 EZEMAP-SSM-WSR-MAP-SAVED VALUE "D".. The specific field names are used for illustrative purposes only. the actual field names might vary in the generated code. VALUE "MAP ". PIC X(4). 15 EZEMAP-TIME PIC X(8). The following notes apply to this example: 1. Note 5 88 EZEMAP-SSM-INVALID VALUE X"40" X"FF" X"00". Note 6 05 EZEMAP-DATA. * Copymember for form group formGroup 01 EZEMFS-form REDEFINES EZEMAP-IO-AREA. Keep in mind that PL/I requires a 4-byte length field rather than the 2-byte length field used for COBOL. 15 EZEMAP-MID-MAP 10 EZEMAP-STRUCTURE-TYPE 88 EZEMAP-IS-A-MAP 10 EZEMAP-SCA 10 EZEMAP-SCA-BIN 10 EZEMAP-EZEAID 10 EZEMAP-HELP-PF-KEY 10 EZEMAP-BYPASS-PF-KEYS. 2. For a MOD. an OCCURS clause is used. Related concepts “Transfer of control across programs” on page 251 Related tasks “Transferring control in the IMS/VS environment” on page 275 “Transferring to and from IMSADF II programs” on page 293 Related reference “Reference information for IMS/VS transfers” on page 286 The following sections provide reference information for call and transfer statements in the IMS/VS environment or when DL/I databases are being used. 5. Any value placed in these fields is not returned on input.3. 4. Otherwise. v ELATSPUT to store data into the work database. Rational COBOL Runtime for zSeries provides subroutines that can be used by a non-EGL program to store or retrieve data from the work database. this field should be initialized using the level 88 EZEMAP-SSM-INVALID. 6. it should use the level 88 EZEMAP-SSM-WSR-SAVED to set this field. In a MOD. If either EZEMAP-SSM-WSR-SAVED or EZEMAP-SSM-WSR-MAP-SAVED is true. there is a record in the work database to restore. the name specified by the alias property for the form. Form is the actual name of the form defined in EGL. Transfer of control across programs 291 . the EZEAID fields through the EZEMAP-GEN-DATETIME fields can be left blank. or the alias name if one had to be assigned at generation time. The transferring program must set EZEMAP-SSM-PREMODIFIED to TRUE to ensure that the value of EZEMAP-SSM-STATUS is transmitted to the target program. The PIC representation varies based on the type and length of the form field. the work database is used to save data when a show statement specifies both a form and a record. The non-EGL program can use this copybook to correctly define the message format that the EGL program needs in the input form and the message format received when an EGL program transfers control to a non-EGL program. Using the EGL COBOL runtime work database for IMS/VS EGL programs can pass both a form and a record for a deferred program-to-program message switch. or the alias for the FormGroup if one was specified. If the formField is an array. 8. EGL generates a COBOL copybook of the MID/MOD associated with a FormGroup. The name of the copybook part is the FormGroup name. Both the originating and target programs or transactions must use the same physical work database. The target program should test the value of EZEMAP-SSM-STATUS to determine if there is data in the work database to restore. If the transferring program puts data in the work database for the target nonconversational program to use in initializing its input record. The two service routines that non-EGL programs can use to interface to the work database are: v ELATSGET to retrieve data from the work database. formField is the actual name of a field defined in the form or the alias name if one had to be assigned at generation time. When the segmented program is generated as nonconversational (without an SPA). 7. The calling program must take the appropriate action when an error occurs. MOVE "ELATSGET" TO modname. the PCB contains the status code that indicates the error. modname is an 8-byte character field. parm5. If a DL/I work database is used. CALL modname USING parm1. In the previous example. other error Truncation occurs when the calling program attempts to restore data into a buffer that is smaller than the data that was previously saved. If the buffer is larger than the data that was previously saved. ELATSGET does not issue any error messages. In the previous example. ELATSGET provides the following return codes: Table 50. If a DB2 work database is used. parm3. truncation occurred Read failed. record not found Read failed. parm3. The logical terminal identifier is used as the work database key. Writing to a work database (ELATSPUT) in IMS: You can use ELATSPUT to write a record to the work database before you perform a deferred program switch to an EGL program. CALL modname USING parm1. parm2. and parm1 through parm6 are as follows: v Record buffer 292 EGL Programmer’s Guide . ELATSGET return codes Code 0 4 8 12 Meaning Read successful Read successful. MOVE "ELATSPUT" TO modname. This method avoids having to link this module for each program that uses it. the full-word binary (5th parameter) contains the SQL code that indicates the error.Reading from a work database (ELATSGET) in IMS: You can use ELATSGET to read a record from the work database after a deferred program switch from an EGL program. The logical terminal identifier is used as the work database key. The ELATSPUT module is dynamically loaded in the following invocation sequence at run time. modname is an 8-byte character field. and parm1 through parm6 are as follows: v Record buffer v Length of buffer (fullword binary) v Target transaction code (8 bytes padded with blanks) v I/O PCB v ELAWORK PCB (or fullword of binary zeros if a DB2 work database is used) v Return code (fullword binary). This method avoids having to link this module to each program that uses it. parm2. The ELATSGET module is dynamically loaded in the following invocation sequence at run time. parm6. parm4. parm5. the trailing portion of the buffer is initialized to blanks. parm6. parm4. other error ELATSPUT does not issue any error messages. both EGL programs must set spaADF to YES. existing record replaced Write failed. If a DB2 work database is used. All EGL programs involved in a transfer where the possibility exists of a transfer to an IMSADF II program must set the spaADF build descriptor option to YES. however: v Because of differences in the way EGL and IMSADF II programs pass the PCB information. Because of differences in map layout conventions. if EGL program A can transfer either to EGL program B or to IMSADF II program C. deferred program-to-program message switches between IMSADF II and EGL programs are not supported. Please note the following. If a DL/I work database is used. For example. new record added Write successful. the fullword binary (5th parameter) contains the SQL code that indicates the error. v Different considerations apply for transferring between EGL programs when IMSADF II programs are involved. ELATSPUT return codes Code 0 4 12 Meaning Write successful.v v v v v Length of record (fullword binary) Target transaction code (8 bytes padded with blanks) I/O PCB ELAWORK PCB (or fullword of binary zeros if a DB2 work database is used) Return code (fullword binary) ELATSPUT provides the following return codes: Table 51. Transfer of control across programs 293 . the PCB contains the status code that indicates the error. IMSADF II secondary transactions can be processed by EGL batch programs. EGL cannot be used to write IMSADF II special processing routines. Related concepts “Transfer of control across programs” on page 251 Related tasks “Transferring control in the IMS/VS environment” on page 275 “Transferring to and from IMSADF II programs” Related reference “Reference information for IMS/VS transfers” on page 286 The following sections provide reference information for call and transfer statements in the IMS/VS environment or when DL/I databases are being used. even if program B never transfers to an IMSADF II program. The calling program must take the appropriate action when an error occurs. Transferring to and from IMSADF II programs Generated EGL programs can transfer to or from IMSADF programs. Immediate program-to-program message switches can be performed between IMSADF II conversational programs and EGL segmented conversational programs generated with the spaADF build descriptor option set to YES. In addition. 3 * char(66) . 3 SPATRX char(3) . Refer to the IMSADF II documentation for your system for additional information. The EGL generated program name (and therefore. 3 * char(4) . // Refer to the IMSADF Application Development Guide // Appendix E for details on which fields to update. 3 SPALEGTH smallint . 3 SPACGTRX char(3) . 3 SPATRANS char(8) . changes made by an EGL program to the Rational COBOL Runtime work database do not affect the IMSADF II work database.IMSADF II conversational processing EGL cannot be used to initiate IMSADF II. 3 SPAKEYID char(255) . 3 * char(397) . 3 SPASHOTR char(8) . define the EGL program to IMSADF II in the same way that you define a transaction that is written entirely in COBOL. 3 SPARTNCD int . end // end ADFWKDB Rational COBOL Runtime for zSeries does not share its work database with IMSADF II. Use this DLISegment definition // to retrieve data from and store data into the ADF work database. 3 SPAPGOPT smallint . the two databases have different formats. 4 RDFSWITH smallint . This is supported only when the IMSADF II program system uses the IMSADF II 28-byte SPA with a work database. 3 SPASECTX smallint . // *********************** Record ADFWKDB type DLISegment { keyItem = "LTERMNME" } 3 LTERMNME char(8) . T A constant. but can be used to receive control from and return control to the IMSADF II transaction driver. 3 SPAFLDSG char(5192) . the load module name) must obey the following IMSADF II naming convention: ssssTcc ssss The IMSADF II program system ID. 3 * char(6) . 3 SPABITS hex(2) . The code example below shows an EGL DLISegment record definition for the IMSADF II. work database. Changes to the IMSADF II work database do not affect the Rational COBOL Runtime work database. //*** RECORD=ADFWKDB **** // The sample segment layout of the ADFWORK database default // segment size is 6000 bytes. The fields in this definition are limited to those you must modify if an EGL program is transferring directly to the IMSADF II conversational transaction driver. Starting from the IMSADF II side. 3 * char(31) . 294 EGL Programmer’s Guide . 3 SPAFIRST smallint . 3 SPASWITH char(2) . Similarly. Release 2. 3 * char(4) . Version 2. The program control logic uses the Rational COBOL Runtime work database or a second message segment following the SPA to pass records between the EGL programs. The EGL program control logic inserts the SPA to cause an immediate program-to-program message switch back to IMSADF II. When IMS schedules the new transaction. Both deferred and immediate program-to-program message switches can be used between the EGL programs. be sure to include a database PCB in the EGL program’s PSB definition.transferName to the name of the new transaction to be started. the EGL program can eventually do an immediate program-to-program message switch back to the IMSADF II conversational transaction driver. Set sysVar. your EGL program should set flags in the IMSADF II work database that tell the transaction driver what to do when it receives control. From EGL program to IMSADF II transaction driver To switch back to the IMSADF II transaction driver. As in a COBOL program. If multiple EGL programs run before transferring back to the IMSADF II conversational transaction driver. IMSADF II does an immediate program-to-program message switch to the requested transaction. where p specifies an available byte in the IMSADF II SPA that can be used for EGL’s segmentation status byte. the EGL program processes the IMSADF II work database the way it would any other program database. IMSADF II writes its own 28-byte SPA to the IMS message queue to perform the switch. The EGL program transfers control using a transfer to transaction statement that specifies no record. and spaStatusBytePosition build descriptor options. all the EGL programs must be generated with these same build descriptor options. All EGL programs involved in a series of message switches that started from the IMSADF II transaction driver must have the same spaSize. Therefore. thereby preserving the IMSADF II-formatted SPA.cc The cluster code (SOMTX) operand used to generate the transaction that causes the switch to the EGL program. this variable must contain the same value that was placed in the IMSADF II variable SPATRANS. the EGL program control logic reads the IMSADF II SPA from the I/O PCB. spaADF. Refer to your IMSADF II documentation for information on the positions in the SPA that are available. Switching directly to the IMSADF II sign-on transaction is not supported. Refer to the IMSADF II documentation for your system for additional information. Transferring with conversational programs in ADF mode The techniques described in this section are used only when there is a transfer from IMSADF II to a series of EGL programs and non-EGL programs prior to Transfer of control across programs 295 . Use the record definition above to access the IMSADF II work database. the EGL program control logic does not modify the SPA in any way. Because of these build descriptor options. If you access the IMSADF II work database. The EGL program must be generated with the spaADF build descriptor option set to YES and spaSize set to 28 to match the IMSADF II SPA size. the EGL program can access the IMSADF II work database to use information or to modify information in the IMSADF II communication area. If you use a DL/I IMSADF II work database. You can also specify the spaStatusBytePosition=p build descriptor option. From IMSADF II transaction driver to EGL program When the program user enters the IMSADF II transaction ID that corresponds to the EGL program. the target program always ignores the value of the segmentation status byte that is located in the SPA at the offset specified. ADF mode does not support transfers between segmented nonconversational programs. Generate both programs as conversational with the spaSize build descriptor set to 28 and the spaADF build descriptor option set to YES. The two 296 EGL Programmer’s Guide . These conventions differ from the techniques used when IMSADF II is not involved in that special techniques are used to pass a record so the SPA can remain intact. If spaStatusBytePosition was specified. input form. Performing the transfer Using an input form Passing a record The target program can optionally The target program must have an have an input form. The byte is present for transfers between conversational programs and other programs. Transfers between EGL conversational programs Action Coding and generating Immediate switch (optional input form) Define both programs as segmented = YES. Deferred switch (with input form) Define both programs as segmented = YES. see “Transferring control in the IMS/VS environment” on page 275. it does this using a transfer to transaction statement with a record. For transfers when IMSADF II is not involved. the program control logic automatically preserves the IMSADF II SPA. Specifying segmentation status byte The segmentation status byte specified by spaStatusBytePosition is used only for program to program transfers for conversational programs. v From a non-EGL program to an EGL program. The record. if any. Generate both programs as conversational with the spaSize build descriptor set to 28 and the spaADF build descriptor option set to YES.transferring back to IMSADF II. If it is an EGL program. Immediate switch between two EGL programs: With this technique two segmented conversational EGL programs can change both the transaction name and the PSB name without presenting a form to the program user. v From an EGL program to a non-EGL program. The record is transferred in a message segment following the SPA. a transferring non-EGL program should always set the byte to blank. A target non-EGL program can ignore the value of the segmentation status byte. it does this using a show statement with a form and an optional record. The originating program cannot send a form. Table 52. is transferred through the work database. If spaStatusBytePosition was specified. The following table shows the conventions used for transferring between EGL programs when the spaADF build descriptor option is set to YES. the target program uses the value of the segmentation status byte at the offset specified when there is an input form integrity problem caused by the program user pressing PA1 or PA2. If it is an EGL program. Conversational immediate program-to-program message switch Conversational immediate program-to-program message switches are supported as follows: v Between two EGL programs. The originating program must write the form to a message queue associated with the terminal after first writing the SPA. If only a single EGL program runs and then transfers back to IMSADF II. However. remember that you must set the spaADF build descriptor option to YES when IMSADF II programs are involved. see “Format of EGL input message segment for IMS message switch” on page 288. 2. Issue a get next to the I/O PCB to read the message that contains the record that was passed by the EGL program. see “Format of EGL input message segment for IMS message switch” on page 288. If you specified a spaStatusBytePosition build descriptor option. see ″Immediate switch between two EGL programs″ in “Transferring control in the IMS/VS environment” on page 275. The EGL program control logic automatically preserves the SPA and manages the record that is passed as a message segment following the SPA for both programs A and B. For a skeleton definition of the two programs. 2. remember that you must set the spaADF build descriptor option to YES when IMSADF II programs are involved. with the destination set to the transaction name for the EGL program.programs can use different form groups. v From a non-EGL program to an EGL program. The non-EGL program should ignore the value of the segmentation status byte. Transfer of control across programs 297 . For the required layout of the message. The EGL program must be defined similarly to program A in ″Immediate switch between two EGL programs″ in “Transferring control in the IMS/VS environment” on page 275. This SPA is in the original IMSADF II format. Preserve the IMSADF II SPA format. If you specified a spaStatusBytePosition build descriptor option. Immediate switch from non-EGL program to EGL program: The non-EGL program must be an IMS conversational program. The non-EGL program must do the following: 1. Initialize the segmentation status byte to blank before inserting the SPA. The non-EGL program must do the following: 1. Conversational deferred program-to-program message switch Conversational deferred program-to-program message switches are supported as follows: v Between two EGL programs. unchanged by the EGL program. the segmentation status byte is in the SPA at the offset specified. The EGL program must be defined similarly to program B in ″Immediate switch between two EGL programs″ in “Transferring control in the IMS/VS environment” on page 275. Insert the input record as a message segment after the SPA into the same alternate PCB. v From an EGL program to a non-EGL program. Specify the same spaSize build descriptor option (28 bytes) for both programs A and B. Immediate switch from EGL program to non-EGL program: The non-EGL program must be an IMS conversational program. Preserve the IMSADF II SPA format. remember that you must set the spaADF build descriptor option to YES when IMSADF II programs are involved. For the required layout of the message. the segmentation status byte is in the SPA at the offset specified. 3. Insert the SPA to an alternate PCB. Issue a get unique to the I/O PCB to read the SPA. 3. remember that you must set the spaADF build descriptor option to YES when IMSADF II programs are involved. the segmentation status byte is in the SPA at the offset specified. If you specified a spaStatusBytePosition build descriptor option. 2. see “Format of the IMS MFS message input descriptor (MID)” on page 289. 298 EGL Programmer’s Guide . 4. see ″Deferred switch between two EGL programs″ in “Transferring control in the IMS/VS environment” on page 275. unchanged by the EGL program. Define the EGL program similarly to program B in ″Deferred switch between two EGL programs″ in “Transferring control in the IMS/VS environment” on page 275. The non-EGL program must do the following: 1. Preserve the IMSADF II SPA format. Insert the SPA to the I/O PCB. 3. Deferred switch from EGL program to non-EGL program: The non-EGL program must be an IMS conversational program. All other attributes should be left at their default values. The non-EGL program must set the modified data tag (MDT) attribute for all variable data fields on the form to be passed to the EGL program on the deferred switch. The two programs must use the same FormGroup. Insert the form to the I/O PCB using the message output descriptor that corresponds to the message input descriptor in the EGL program. 3. remember that you must set the spaADF build descriptor option to YES when IMSADF II programs are involved. see “Format of the IMS MFS message input descriptor (MID)” on page 289. For the required layout of the form. 2. For details see “Using the EGL COBOL runtime work database for IMS/VS” on page 291.Deferred switch between two EGL programs: With this technique two segmented conversational EGL programs can change both the transaction name and the PSB name when a form is presented to the program user. Deferred switch from non-EGL program to EGL program: The non-EGL program must be an IMS conversational program. EGL creates a COBOL copybook for the MID/MOD record layout that the non-EGL program should use to ensure that the record formats match. For the required layout of the map. but a form is required. Call ELATSPUT to save the record that you want to pass to the EGL program via the work database. Issue a get next to the I/O PCB to retrieve the message input descriptor that corresponds to the message output descriptor used by the EGL program. Define the EGL program similarly to program A in ″Deferred switch between two EGL programs″ in “Transferring control in the IMS/VS environment” on page 275. Initialize the segmentation status byte to blank before inserting the SPA. This SPA is in the original IMSADF II format. The non-EGL program must do the following: 1. Issue a get unique to the I/O PCB to read the SPA. EGL creates a COBOL copybook for the MID/MOD record layout that the non-EGL program should use to ensure that the record formats match. For a skeleton definition of the two programs. Use the value of the MID form field EZEMAP-SSM-STATUS to determine whether a record was passed in the work database. remember that you must set the spaADF build descriptor option to YES when IMSADF II programs are involved. The EGL program must set the modified property to YES for all variable data fields on the form that the non-EGL program needs as input. You do not have to transfer a record. The iSeries environment does not support the show statement to transfer to a non-EGL program. c. If the segmentation status byte has the value C. 5.v If either EZEMAP-SSM-WSR-SAVED or EZEMAP-SSM-WSR-MAP-SAVED is true. Related concepts “Transfer of control across programs” on page 251 Related reference “Format of EGL input message segment for IMS message switch” on page 288 “Format of the IMS MFS message input descriptor (MID)” on page 289 Related tasks “Transferring control in the IMS/VS environment” on page 275 “Using the EGL COBOL runtime work database for IMS/VS” on page 291 Transferring control in the iSeries COBOL environment In the iSeries environment. D. v Using the transfer to transaction statement. it is passed as a parameter using a standard system argument list. Retrieve it as described in step 4 below. Preserve the IMSADF II SPA format. Parameters are passed using a standard system argument list. Related concepts “Transfer of control across programs” on page 251 Transfer of control across programs 299 . then a record was saved in the work database and you can retrieve it as described in step 4 below. In this situation. If a record is specified. the following types of transfer of control are possible to and from EGL programs: v Using the call statement. 4. the call uses the standard iSeries CALL interface. probably because the program user has pressed PA1 or PA2. This might involve issuing an error message to the program user and restarting the transaction or other recovery actions depending on the program design. When you use the transfer to program or transfer to transaction statement. if you specified a spaStatusBytePosition build descriptor option. then an input form integrity problem has occurred. the program can use the segmentation status byte to determine if a record was saved in the work database prior to the transfer. For details see “Using the EGL COBOL runtime work database for IMS/VS” on page 291. The transferring program is removed from the program invocation stack and does not resume control when the target program ends. Call ELATSGET to retrieve the record saved by the EGL program in the work database. If you are calling a non-EGL program from an EGL program. Take whatever action is appropriate for the program to recover the data that was lost from the input form. control is passed directly to the target program using the iSeries XCTL interface. v If EZEMAP-SSM-FILL-CHAR is true and this is not an initial SPA. v Using the transfer to program statement. or d. then there is a record in the work database. you must do one of the following: v Define the EGL program as a service. For more information. v Create Java wrapper classes for the EGL program. the following types of transfer of control are possible to and from EGL programs: v Using the call statement. v Using the transfer to program statement. Related concepts “Transfer of control across programs” on page 251 Calling to and from Java programs The following types of transfer of control are possible in EGL: v EGL-generated Java program to EGL-generated Java program v v v v Non-EGL Java program to EGL program EGL-generated Java program to non-EGL Java program EGL-generated Java program to DLL EGL-generated Java program to . the call uses the standard iSeries CALL interface. v Identified with a linkage option part. The iSeries environment does not support the show statement to transfer to a non-EGL program. For more information. it is passed as a parameter using a standard system argument list.BAT file EGL-generated Java program to EGL-generated Java program Calling one EGL-generated program from another is as simple as invoking the Java class for the target program using a call statement. Be aware. v Using the transfer to transaction statement. of package dependencies. see Generating Java wrappers.Transferring control in the iSeries RPG environment In the iSeries environment. If you are calling a non-EGL program from an EGL program. control is passed directly to the target program using the iSeries XCTL interface. You must invoke a class that is one of the following: v Within the same package as the calling program. see Linkage options part. however. The transferring program is removed from the program invocation stack and does not resume control when the target program ends. v Qualified with a package name using dot syntax. Non-EGL Java program to EGL program To invoke an EGL-generated program from a non-EGL Java program. see Generating EGL and Web services. When you use the transfer to program or transfer to transaction statement. Parameters are passed using a standard system argument list.EXE or . 300 EGL Programmer’s Guide . If a record is specified. For more information. The program accessed on IMS is not the called program itself. sysLib. from EGL-generated Java code. You create a Library part of type nativeLibrary to act as an interface between your EGL program and the DLL. and can use the alias property of the functions where function names do not match EGL conventions. Access the functions by using dot syntax (library.so. EGL-generated Java program to DLL You can call functions in a single. EGL-generated Java program to . The Interface part contains function descriptions for the Java methods you wish to call. the Transfer of control across programs 301 .method()). invoke it using the name of the Interface part and dot syntax (interfacePart. control returns to the calling EGL program. The file extension for the DLL depends on your environment (examples include .method()). . EGL cannot instantiate a Java class. As shown later. Related concepts “Transfer of control across programs” on page 251 Linkage options part Related tasks Generating EGL and Web services Generating Java wrappers Calling an IMS program from EGL-generated Java code You can call an IMS program remotely. when the executable terminates. C or COBOL) from an EGL Java program. for example. create a variable based on that Interface part and use it in much the same way you would a library. Invoke the Java method in one of two ways: v If the function is marked static.sl). The Library part lists function names and parameters.exe executable file). v Otherwise. and . non-EGL dynamic link library (DLL) (written in. Note that the Java class must provide a method to instantiate itself.EGL-generated Java program to non-EGL Java program To invoke non-EGL Java code from Java code generated by EGL. both the EGL program and the executable run at the same time.EXE or . appending the interface variable name to the name of the method using dot syntax (interface. you must create an Interface part of type JavaObject.bat or a . but is a catcher program provided by Rational COBOL Runtime for zSeries. then keeps running. sysLib.BAT file EGL provides two functions that allow you to call a system command (such as a .dll.function()) or by creating a use declaration for the library to make its functions global to your program.callCmd() This function transfers control to a specified executable.startCmd() This function transfers control to a specified executable. The called program can be generated from EGL or VisualAge Generator or can be written in another language. For version 7. Use the following IMS system definition as a model: APPLCTN PGMTYPE=TP. 2. Creates a system definition that associates a transaction (for example. create a second load module. TRAN1) with a PSB (for example. as well as the called program name and parameters. 5. In the build descriptor used to generate the program. If you want to add an alias after 64. IMS Connect returns the data to your Java code. IMS schedules PSB1. the systems programmer carries out the following tasks: a. which starts the catcher program. Because TRAN1 has been invoked. 4.0 and later of EGL. EGL runtime takes the name of the IMS transaction code from the linkage options part used at generation time of the calling program. program name (PGMX). 302 EGL Programmer’s Guide . to TRAN1).MODE=SNGL. 8. You place a statement in your Java program to call PGMX and to supply parameters for that program.PSB=PSB1 TRANSACT CODE=TRAN1. The transaction TRAN1 must be defined to IMS as a message processing program. 7. The linkage can include up to 64 aliases of this kind. The effect of that task is to assign an alias for each runtime PSB associated with any transactions that are invoked remotely by EGL-generated Java code. IMS Connect reads the data from the queue and returns the data to the calling program. IMS Connect sends the transaction code (TRAN1). the catcher program submits the returned data to the IMS queue. On IMS. serverID property to the appropriate transaction code (in this case. the catcher program is ELAISVN7. you set the linkage build descriptor option to a linkage options part called pgmLinkage. The name of the catcher program depends on the version of EGL you use. 4. Here is an example: 1. At run time. and parameters to the IMS message queue.EDIT=ULC Data will be folded to uppercase characters if the statement EDIT=ULC is omitted from the transaction definition. or ELAISVN for an earlier version) to assign it the alias PSB1. which places the returned data on the IMS message queue. On regaining control. and you can give the module any name you choose. When PGMX finishes.system programmer must re-link that catcher program. For earlier versions of EGL. 3. 2. b. then calls PGMX. The runtime process is as follows: 1. the catcher program is ELAISVN. Links the catcher program (ELAISVN7 for EGL version 7 or later. 6. you set the callLink element. EGL uses the connectors of IMS Connect to submit this transaction code. PSB1). In that linkage options part for program PGMX. The catcher program reads the called program name and parameters from the message queue and uses a z/OS call to invoke the requested program. control returns to the catcher program. 9. The catcher program reads the message queue for the program name (PGMX) and parameters. 5. 3. to the IMS message queue. usually ELAISVN7 (or ELAISVN for versions of EGL earlier than version 7). 2. Create a second PSB that is named for the first program in that transaction. you must do as follows: 1. but in another transaction on IMS. in this case. If you want your called program to be called. not only from remote code. the catcher program is named ELAISVN: //L EXEC ELARLINK //L.SYSIN DD * INCLUDE SELALMD(ELAISVN7) ENTRY ELAISVN7 ALIAS PSB1 ALIAS PSB2 NAME loadModuleName(R) /* loadLibraryName Name of the load library loadModuleName Name of the load module. IMS requires that the name of a runtime PSB be identical to the name (or. in this case to assign the aliases PSB1 and PSB2. If you are using a version of EGL earlier than version 7. the alias) of the first program in a transaction.Here is an example of the JCL the system programmer might use to re-link the catcher program ELAISVN7.DSN=loadLibraryName //L. Structure that PSB like the PSB scheduled for the remote invocation.SYSLMOD DD DISP=SHR. Related concepts “Transfer of control across programs” on page 251 “Developing EGL programs for the IMS environment” on page 307 Transfer of control across programs 303 . 304 EGL Programmer’s Guide . You can find this manual in PDF form on the EGL Cafe site: http://www.5 Generation for z/VSE feature Reference Manual (SC19-2539-00). The following highlights apply to developing for the VSE environment: v You can develop traditional 3270 or batch applications. v Unlike the z/OS environment which uses a build server to prepare the output of COBOL generation for runtime.ibm. You can also develop VGWebTransaction programs. VSE uses a preparation process that is similar to that used by VisualAge Generator. Related reference “Developing EGL programs for the IMS environment” on page 307 © Copyright IBM Corp. v Install and customize IBM Rational COBOL Runtime for z/VSE. To use the Generation for VSE feature. which provides the runtime support for the VSE environment (similar to the runtime support for z/OS that is provided by IBM Rational COBOL Runtime for zSeries). you must do the following things: v Install the feature and then enable the feature by purchasing and applying the license for IBM Rational Business Developer Extension for VSE. The feature provides the COBOL generation capability for the VSE environment. refer to the Program Directory for Rational COBOL Runtime for z/VSE (GI10-8803-00). developing for VSE Batch is similar to developing for z/OS Batch. including compatibility considerations for VSE that differ from z/OS. The VSE preparation process uses the following templates and procedures: – Preparation JCL templates that are included with the Generation for VSE feature – Preparation JCL procedures that are included with IBM Rational COBOL Runtime for z/VSE For more information about developing and generating EGL programs in the VSE environment.Developing EGL programs for the VSE environment Rational Business Developer provides a Generation for VSE feature that you can use to generate EGL as COBOL source for the z/VSE environment.com/software/rational/cafe/community/egl/documentation For more information about installing and customizing the VSE runtime support. Therefore. v Developing for VSE CICS is similar to developing for z/OS CICS. 1996. much (but not all) of the information in the online help that describes these two z/OS environments also applies to the VSE environment. 2008 305 . refer to the Rational Business Developer V7. 306 EGL Programmer’s Guide . The next two sections provide information particular to each of the two program types. which accept or display a text form. refer to the EGL Language Reference. You must set the segmented program property to YES.printerAssociation to change the IMS logical terminal name. © Copyright IBM Corp. and for that purpose. specify the file type as SMSGQ. For an overview of the runtime behavior. You can interact with the terminal by using the converse statement. you code a print statement to display a print form. In addition. EGL handles the details of I/O PCB access. v Basic programs. the file type associated with the serial record may be SMSGQ or MMSGQ. at run time you can use converseVar. 2008 307 . For output to a message queue. Depending on program and build-part characteristics. For details.startTransaction().Developing EGL programs for the IMS environment EGL allows you to develop programs that run on IMS. For more information on how to interact with IMS control blocks. which neither accept nor display text forms. v You can send output to a printer. see “Using serial and print files in IMS” on page 319. you can generate programs to run in any of the following regions: v a message processing program (MPP) region v an IMS FastPath (IFP) region v a batch message processing (BMP) region Factors for each of these regions are discussed separately below. Alternatively. see “EGL support for runtime PSBs and PCBs” on page 310. and for that purpose. The following considerations apply to both Text UI and basic programs: v You can send output to another message queue. and also specify the IMS logical terminal name for the printer. You associate the printer (at generation time) with an alternate PCB or an express alternate PCB. Text UI programs If you code a main program that accepts or displays a text form. the effect of build descriptors is also discussed in detail. you code an add statement to write a serial record that is associated (at generation time) with an alternate PCB or with an express alternate PCB. Generating for the MPP region You can generate two types of programs for the MPP region: v Text UI programs. 1996. v You cannot access indexed or relative files. which presents a text form and responds to the user’s input by processing the statement that follows the converse statement. v You can start an asynchronous transaction using vgLib. In most environments. Your program can run as an IMS conversational or nonconversational program. Instead the target program must read the transferred record from the message queue. see the topic that describes the statement syntax. see the topic that describes the statement syntax. in which case the situation is the same as described for an MPP region. when a main basic program is started. An EGL-generated called basic program can be called from EGL-generated Java code on another platform. Your program can run as an IMS nonconversational program and can transfer to a program or call another program in the same IMS/VS system. Basic programs If you code a main program that neither accepts nor displays a text form. You can use the show statement to return to the beginning of the same program or to another program. an EGL-generated called program cannot read from a message queue. see one of the following topics: v “Transferring control in the IMS/VS environment” on page 275 v “Transferring to and from IMSADF II programs” on page 293 . This is not true of a main basic program that is generated for the IMS BMP environment. For details. On IMS. use of multi-segment input message queues (including the use of converse statements) is not recommended for IMS fast path programs for performance reasons. For more information. For restrictions that apply to a particular type of statement. To retrieve that input. On IMS. see “Using serial and print files in IMS” on page 319. Generating for the MPP IMS FastPath region You can generate both Text UI and basic programs to run in an IMS FastPath (IFP) region. The show statement must specify the same form that the receiving program specifies as its inputForm. A basic program cannot use the transfer to transaction statement. For input from a message queue. except that (in keeping with IMS requirements) the program must be nonconversational. 308 EGL Programmer’s Guide . In addition. a called Text UI program is not supported. you code a loop that reads one message after another into a serial record that is associated with the I/O PCB. the program’s input record is initialized from the record that was passed by the transferring program. can transfer to or call another program. you must be sure to code your program so the form and record provide all the necessary information to continue the interaction with the program user. Use of the show statement limits the data that is saved to just the information in the form and record that are specified on the show statement.Although use of a converse statement is relatively simple. For restrictions that apply to a particular type of statement. A main Text UI program can transfer to or from a non-EGL IMS or IMSADF II program on the same IMS system. you get better performance by using a show statement. the file type associated with the serial record may be SMSGQ or MMSGQ. and can issue a show statement with a returning clause. input is available from the IMS message queue. However. at run time you can use recordName. You can cause a CHKP call by: v Using the sysLib. v Multiple-segment input message queues are not supported. The use of single-segment and multi-segment message queues is as described earlier for IMS MPP programs. You associate the printer (at generation time) with a GSAM PCB.VGTDLI() must use only the call types supported for fast path transactions. and vgLib.commit() service routine before the end of a batch-oriented BMP v Making sure that the get next statement for a serial file associated with an IMS message queue receives an endOfFile (QC status code) before the end of a transaction-oriented BMP. In this case. set the imsFastPath build descriptor option to YES. and vgLib. To create a transaction-oriented IMS BMP program. For that purpose. v dliLib. To create a batch-oriented IMS BMP program. A show statement is permitted. you can do the following in an IMS BMP or z/OS batch program: v Receive input or send output to a GSAM file.EGLTDLI(). the program must cause either a SYNC or CHKP call to commit the updates. see “Using serial and print files in IMS” on page 319. You also specify the file type as GSAM and specify the name of the GSAM data set. In particular. These restrictions result in the following limitations on the use of EGL functions with fast path programs: v A transfer to transaction statement is supported only to a non-fast path program.resourceAssociation to change the name of the data set. An IMS BMP program can use any of the EGL statements that a program generated for z/OS batch can use. and for that purpose you code a print statement. dliLib.VGTDLI() function calls using the I/O PCB or an alternate response PCB To indicate that you want a nonconversational program to run as an IMS fast path program. When a batch program runs in the IMS BMP environment and updates IMS fast path databases. you must retrieve input from the IMS message queue by coding a loop that reads one message after another into a serial record that is associated with the I/O PCB. v Send print output to a GSAM data set. do not read input from the IMS message queue. you code an add statement to write a serial record that is associated (at generation time) with a GSAM PCB. This option causes the generated program to limit its use of IMS functions to that permitted by IMS fast path support. An IMS BMP program can also send output to another message queue or printer as described for IMS MPP programs. the transferred-to program is responsible for responding to the terminal.IMS imposes restrictions on fast path programs.AIBTDLI(). v Only one of the following actions can be done for each get unique to the I/O PCB: – transfer to transaction or show statement – add statement for serial file associated with an alternate response PCB – dliLib. For details. Developing EGL programs for the IMS environment 309 . Alternatively.EGLTDLI(). Generating for the IMS BMP region You can generate a basic program that runs in an IMS BMP region.AIBTDLI(). Use of fast path restricts the amount and type of diagnostic data that is provided when an error occurs in the generated program. dliLib. or v When your code is accessing GSAM files. To generate a program for the IMS BMP region. set that value to zero (as is the default). IMS BMP.printerAssociation to change the name of the output GSAM data set. or z/OS batch. set the build descriptor option spaSize. To generate a program for an MPP or IFP region. set system to IMSBMP. Additional build descriptor options apply only to the IMS/VS or IMS BMP environments: v imsLogID v v v v v mfsExtendedAttr mfsIgnore mfsUseTestLibrary formServicePgmType spaStatusBytePosition The mfsDevice must also be set before you generate your formGroup. set the build descriptor option spaADF to YES. set system to IMS/VS. as is possible when the target system is CICS. Related concepts “Transfer of control across programs” on page 251 Related reference “EGL support for runtime PSBs and PCBs” Related tasks “Using serial and print files in IMS” on page 319 “Transferring control in the IMS/VS environment” on page 275 “Transferring to and from IMSADF II programs” on page 293 EGL support for runtime PSBs and PCBs This topic concerns tasks that are appropriate in the following cases: v When the target for EGL generation is IMS BMP or IMS/VS. To ensure that a program is nonconversational.specify the file type as GSAM and specify the name of the GSAM data set. Alternatively. A called program cannot read from a message queue. IMS/VS. 310 EGL Programmer’s Guide . by setting options in the build descriptor that is used at generation time. v To indicate that a conversational program transfers to or from an IMSADF II program. set the build descriptor option imsFastPath to YES. v To generate a FastPath program (which runs in an IFP region). or v When your code is accessing DL/I databases. Your code can transfer to or call another IMS BMP program. The following options also apply: v To mandate the size of a SPA (as needed for a conversational program). at run time you can use converseVar. Effect of build descriptor options You enforce some decisions outside of your code. as is possible when the target system is IMS BMP or z/OS batch. Your next. The I/O PCB also provides access to other IMS capabilities. CICS The value of the PSB record property defaultPSBName is (by default) the name of the runtime PSB. for example. predefined PCB record parts: IO_ PCBRecord Used to interact with an I/O PCB.You customize EGL program elements as needed to generate a COBOL program that can access your organization’s program specification blocks (PSBs) and program communication blocks (PCBs). The next list provides details on the runtime PSB in each of the target systems. psbRef. Define a PSB record part. in which case the message is sent to its destination regardless of whether a commit or rollback occurs. EGL places that name in the psbName field of the system variable dliLib. That part includes the set of PCB records that will be used when accessing IMS message queues. define the DLISegment record parts that you will reference in database PCB records (if any). Those blocks are called the runtime PSBs and runtime PCBs. Each PCB record is based on one of the following. GSAM_PCBRecord Used to reference a GSAM PCB. When your program attempts an I/O operation against a DL/I database. which is used when a z/OS batch or IMS BMP program accesses a serial file that acts as a root-only DL/I database. property field psb to the name of the PSB record. DL/I databases. in which case the message is sent to its destination only if a commit occurs. The runtime database PCB specifies the data that can be accessed and the type of access that is valid. First. The runtime PCB may be either of the following kinds: v An alternate PCB. for more information on the syntax. see Set-value blocks. checkpoint and restart of a batch program. This type of record allows your code to write output to a message queue that is associated either with another transaction or with a device other than the terminal associated with the I/O PCB. or GSAM files. When the first DL/I I/O occurs.psbData. but you can assign a different value to that library field. which indicates that no PSB is scheduled. Developing EGL programs for the IMS environment 311 . The initial value of the field is zero. ALT_PCBRecord Used to reference a teleprocessing PCB other than the I/O PCB.psbName to schedule a runtime PSB. which acts as follows: v Uses the value in dliLib. or v An express alternate PCB. which allows for input from a program or terminal and (if the input came from a terminal) allows for output to the same terminal. EGL runtime issues a PSB schedule call. primary tasks are as follows: 1. the value in psbName determines what runtime PSB is used. The system variable dliLib.psbData has a second field. make the PSB and PCB information available: v Declare a record that is based on the PSB record part v Set the program property @dli. In the program. 2. DB_PCBRecord Used to reference a database PCB. which represents a DL/I database accessible from your program.psbData. v Sets dliLib.psbData.psbRef to an address with which that PSB can be accessed. Note: You must avoid writing logic that assigns any value to dliLib.psbData.psbRef. During a call, you can use the variable dliLib.psbData to ″pass the PSB″ (really, to pass a name and the related address). During a transfer, details of runtime behavior depend on how the transfer occurs: v If the transfer is by a show statement with a returning clause or by a transfer to transaction statement, the scheduled PSB ends because a commit point occurs during the transfer, and a PSB is not passed to the target program. v If the transfer is by a transfer to program statement, the default behavior depends on whether a PSB is scheduled: – If a PSB is not scheduled, no commit point occurs. – If a PSB is scheduled, that PSB ends because a commit point occurs during the transfer, and a PSB is not passed to the target program. But in this case an alternative outcome is possible, with the benefit that you can minimize the difference in behavior when the transferring program is generated for CICS as compared to when that program is generated for IMS/VS. The alternative outcome occurs when four conditions are met: - The target system is z/OS CICS; - The target program is generated by EGL; - The build descriptor option synchOnPgmTransfer is set to NO; and - The default PSB referenced in the PSB record of the transferring program is the same as the default PSB referenced in the PSB record of the target program. In this case, a commit point does not occur, and EGL passes the scheduled PSB to the target program. Note: The default PSB is the value of the defaultPSBName property, which is set in the PSB record part that is the basis of a program’s PSB record. The default value of that property is the name of the record part. To see examples of PSB records, see DLISegment stereotype. DB PCBs are valid in the runtime PSB. IMS BMP The PSB parameter in the runtime JCL identifies the runtime PSB used throughout the job step. Although you can customize the JCL at deployment time, EGL generates the default PSB parameter value in the runtime JCL by assigning the value of the PSB record property defaultPSBName. For IMS BMP, EGL requires that the following PCBs be in the runtime PSB: 1. In the zero (first) position, the I/O PCB. Be sure that your IMS system programmer sets CMPAT to YES when developing the PSBGEN job, even if you are generating a batch-oriented BMP. 2. An alternate PCB, which is usually in the second position. 3. An express alternate PCB, which is usually in the third position. DB and GSAM PCBs are also valid. 312 EGL Programmer’s Guide IMS/VS The rules of IMS system definition ensure that the name of the main program is the name of the runtime PSB, which is available throughout the transaction. For IMS/VS, EGL requires that the following PCBs be in the runtime PSB: 1. In the zero (first) position, the I/O PCB. Your IMS system programmer can set CMPAT to YES when developing the PSBGEN job, though the action is optional. 2. An alternate PCB, which is usually in the second position. 3. An express alternate PCB, which is usually in the third position. DB PCBs are also valid. If the value of build descriptor option workDBType is DLI (as is the default), set one of your runtime DB PCBs for the EGL work database, which is identified as ELAWORK either in the runtime PSB or as the name of the EGL PCB record. Note: It is recommended that you specify the last database PCB in your runtime PSB as ELAWORK so that, if you decide to change to an SQL work database, you can easily remove that PCB. z/OS batch The PSB parameter in the runtime JCL identifies the runtime PSB used throughout the job step. Although you can customize the JCL at deployment time, EGL generates the default PSB parameter value by assigning the value of the PSB record property defaultPSBName. For z/OS batch, EGL requires that the first runtime PCB be the I/O PCB. Be sure that your IMS system programmer sets CMPAT to YES when developing the PSBGEN job. In addition, EGL requires two additional PCBs of any type be present in the runtime PSB. DB and GSAM PCBs are valid, as are alternate PSBs. Your code cannot use the alternate PSBs, however; their validity allows use of the same runtime PSB for z/OS batch and IMS BMP. EGL adjusts for an initial two or three I/O and teleprocessing PCBs if they are declared in the PSB record but are not present in the runtime PSB. This adjustment allows you to generate the same program across different environments. In relation to CICS, for example, EGL runtime ignores the initial I/O and alternate PCB records if they are present in your code. Requirements for the PSB record part The structure of your PSB record part is closely related to the structure of your runtime PSB, and two other issues are in play: v The target system affects which PCBs are required in the PSB record part, as described earlier. v The value of the program property @dli, property field callInterface (whether AIBTDLI or CBLTDLI) also affects the requirements for your PSB record part. When callInterface is AIBTDLI When the callInterface field is set to AIBTDLI (as is the default), access to a given runtime PCB is by PCB name, and the structure of the PSB record in your program does not need to reflect the structure of a runtime PSB. However, you must make the runtime PCBs available to EGL: Developing EGL programs for the IMS environment 313 v For IMS/VS, IMS BMP, or z/OS batch, the first PCB in the runtime PSB must be an I/O PCB. IMS always uses the name IOPCB as the name of the I/O PCB; v For IMS/VS and IMS BMP, EGL uses the following names for the other required PCBs: – ELAALT for the alternate PCB. – ELAEXP for the express alternate PCB. – ELAWORK if you use a DL/I database as the EGL work database in the IMS/VS environment, In this case, you do not need to include the database hierarchy information in the EGL PCB record, and your IMS system programmer should use the macro ELAPCB when defining the runtime PSB, as shown later. (At generation time, you indicate that the work database is a DL/I database by accepting the default value for the build descriptor option workDBType.) You can specify the names for those PCBs in one of the following ways: – Ask your IMS system programmer to specify the EGL-required PCB name in the PSBGEN job that creates the runtime PSB. The following example uses a label to provide the name for the alternate PCB and includes the PCBNAME parameter to provide the name for the express alternate PCB and work database PCB: ELAALT PCB TYPE=TP,MODIFY=YES PCB TYPE=TP,MODIFY=YES,EXPRESS=YES,PCBNAME=ELAEXP ELAPCB LABEL=ELAWORK In this case, you do not need to include the PCB records in your PSB record part. – If your IMS programmer uses different names from those required by EGL, you must include the required PCB records in your PSB record part and must associate the EGL-required name with the name in your runtime PSB. Assume, for example, that your runtime PSB includes the following PCBs: PCB TYPE=TP,MODIFY=YES,PCBNAME=MYALTPCB PCB TYPE=TP,MODIFY=YES,EXPRESS=YES,PCBNAME=MYEXPPCB ELAPCB LABEL=MYWORKDB In this case, your PSB record part includes the PCB records as follows: Record MYPSB type PSBRecordPart ELAALT ALT_PCBRecord {@PCB {pcbType = PCBKind.TP, PCBName = "MYALTPCB"}}; ELAEXP ALT_PCBRecord {@PCB {pcbType = PCBKind.TP, PCBName = "MYEXPPCB"}}; ELAWORK DB_PCBRecord {@PCB {pcbType = PCBKind.DB, PCBName = "MYWORKDB"}}; end When the callInterface field is set to AIBTDLI, you need to declare only the PCB records that are used in your program, as well as any of the required PCBs that have a different runtime name from the EGL-required name. This rule applies to main and called programs. When callInterface is CBLTDLI If you set the callInterface field to CBLTDLI, access to a given runtime PCB is by address rather than by name. With the exception of I/O and alternate PCB records that EGL ignores so you can generate the same program across different environments, the structure of the PSB record in a main program must reflect at least the initial PCBs in the runtime PSB: v The PSB record cannot have more PCB records than the number of PCBs in the runtime PSB but can have fewer v The position of each PCB record must match the position of the related runtime PCB and must be of the same type as that PCB 314 EGL Programmer’s Guide If the target system is IMS/VS and you are using a DL/I database as the EGL work database, you do not need to include the database hierarchy information in the EGL PCB record, and your IMS system programmer should use the macro ELAPCB when defining the runtime PSB. (At generation time, you indicate that the work database is a DL/I database by accepting the default value for the build descriptor option workDBType.) The situation in called programs is as follows: v If you pass a PSB record to the called program, you are passing an address used to access the runtime PSB. You must set up at least the initial part of the PSB record part as you did in the main program, including the PCB records for the I/O, alternate, and alternate express PCBs (if used in a particular environment), as well as other PCB records needed in the called program. You also must set the program property @dli, property field psbParm. v If you pass PCB records to the called program (as is preferred), you are passing addresses used to access each runtime PCB. You still must set up at least the I/O, alternate, and alternate express PCBs (if used in a particular environment); but aside from those, you need to declare only the PCB records that are needed in the called program. You also must set the program property @dli, property field pcbParms. If you specify properties pcbParms and psbParm in a called program, the PCB-specific addresses in the former override the equivalent addresses in the latter; the passed PSB record is ignored. For main or called programs that are generated for IMS/VS or IMS BMP, the default behavior is as follows: v The second PCB record refers to the alternate PCB v The third PCB record refers to the express alternate PCB If you use ELAALT as the name of a record other than the second or if you use ELAEXP as the name of a record other than the third, the name takes precedence; EGL assumes that the named PCB record refers to the appropriate type of runtime PCB. Related concepts “Developing EGL programs for the IMS environment” on page 307 Interacting with terminals in IMS Typical IMS programs use a message-driven structure like that in the figure below: Developing EGL programs for the IMS environment 315 Message From Terminal 1 Output Queue To printer or other transaction Message Input Queue Transaction Program From Terminal 2 Queue Message Relational or DL/I Database Back to original terminal Message In this example, the IMS controller starts the transaction program when the message queue associated with the program contains a message. Another program might have put the message on the queue, or the controller might have read input from the terminal. The program takes the message off the queue, does any required database I/O, and adds messages to output queues to continue processing. The output queue can represent the input terminal, another terminal or printer, or a queue associated with another transaction. The program then loops back to the beginning and processes the next message on its input queue. Typical PL/I or COBOL programs must continue the cycle until the message queue is empty because multiple terminals run the same transaction concurrently. However, EGL textUI programs automatically loop to read the next message in the queue. You do not need to define message queue control functions directly. You can define programs for IMS just as you define programs for CICS, that use a synchronous logic structure instead of a message-driven structure. The following figure shows an example of a synchronous program: 316 EGL Programmer’s Guide Start Application End Terminal Database or File With the synchronous model, you only need to consider the processing that must occur for a single user at a single terminal. This simplifies both the design and the definition of the program. IMS requires you to commit all database changes and to release all database locks and positions when waiting for user input. In EGL, this means creating a segmented program. When you define the program, remember that EGL performs a commit with each converse I/O statement. You must understand how segmentation works to develop programs for IMS; see Segmentation in Text UI programs. Related concepts “Developing EGL programs for the IMS environment” on page 307 Defining forms for IMS programs EGL generates your FormGroup parts into IMS Message Format Services (MFS) maps. Each form that you define for use in the IMS environment must provide space for the following: v An 8-byte constant field that is used to store the IMS transaction name v A 2-byte area that EGL uses to record the types of information stored in the work database You can define the 8-byte constant field with the protect and dark attributes. The attribute byte on the form becomes the attribute byte in the EGL-generated MFS control block. The 8-byte constant contains the name of the IMS transaction that is started when the form is processed. Specifying the constant on the form enables the user to specify the IMS /FORMAT command to display a formatted screen to start a transaction. Do not use the /FORMAT command if variable fields on the form have initial default values. If the /FORMAT command is used, the default values do not appear. If you do not define an 8-byte, protected, dark constant on the form, EGL searches for any string of 9 blanks on the form and sets this area aside as a protected, dark variable field (1 byte attribute, 8 bytes of data) in the generated MFS map. The generated program uses this field to store the name for the next IMS transaction to Developing EGL programs for the IMS environment 317 be run after a converse or show statement. The user cannot use the /FORMAT command to start a transaction for these forms because IMS does not have a default transaction name. You do not need to explicitly define the 2-byte area on a form. EGL selects two adjacent blank bytes on the map and treats it as a protected, dark variable field (1 byte attribute, 1 byte of data). Estimating the size of MFS blocks for a formGroup When EGL generates a formGroup, it generates the MFS control blocks for that formGroup. There are three types of MFS control blocks: Device input format (DIF) and device output format (DOF) These control blocks describe the arrangement of data fields and literals in the device presentation space (for example, the screen for 3270 devices). For 3270-type devices, a single set of statements describes both the DIF and the DOF. For printers, only a DOF is needed. Each device field is given a name that statements can refer to in the message input and output descriptors. For EGL FormGroup parts, the DOF is always larger than the DIF because the DOF includes form constants. Message output descriptor (MOD) This control block describes the various fields of information in the output message inserted by the program. It also identifies corresponding device fields where the data for each message field is moved. Message input descriptor (MID) This control block describes the various fields of information in the input message retrieved by the program. The MID identifies the corresponding device field from which the data for each message field came. MFS control blocks cannot exceed 32748 bytes. If you are using a large FormGroup part, the following formulas offer a guideline for estimating an upper limit for the size of the control blocks that will be generated. Using these formulas during your design helps you determine whether your FormGroup parts should be split into smaller ones. If a generated control block is too large, MFS generation issues a 3022 abnormal termination. Calculating the DOF size for display devices The following formula helps you estimate the size of the DOF: DOF Size 150 + (388 + (208 + (63 = * Number of printer forms in the formGroup) * Number of display forms in the formGroup) * Number of variable field occurrences on display forms in the formGroup) + (62 * Number of constant fields on display forms in the formGroup) +(1.12 * Total length of all constant fields on display forms in the formGroup) Calculating the DOF size for printer devices The following formula helps you estimate the size of the DOF: DOF Size 206 + (68 + (374 + (63 = * Number of printer forms in the formGroup) * Number of display forms in the formGroup) * Number of variable field occurrences on printer 318 EGL Programmer’s Guide forms in the formGroup) (62 * Number of constant fields on printer forms in the formGroup) +(1.12 * Total length of all constant fields on printer forms in the formGroup) + Calculating the MOD size for all forms The following formula helps you estimate the size of the MOD: MOD Size 36 + (724 + (202 + (52 = * Number of display forms in the formGroup) * Number of printer forms in the formGroup) * Number of variable field occurrences in the formGroup) Calculating the MID size for terminal maps The following formula helps you estimate the size of the MID for terminal maps: MID Size = 36 + (858 * Number of display forms in the formGroup) + (52 * Number of variable field occurrences for display forms in the formGroup) Related concepts “Developing EGL programs for the IMS environment” on page 307 Using serial and print files in IMS Serial files must be implemented as IMS message queues in IMS/VS. They can be implemented as message queues, OS/VS files, VSAM files, or GSAM files for IMS BMP. Serial files can be implemented as OS/VS files, VSAM files, or GSAM files for z/OS batch. The following discussion deals with using serial files for GSAM files or message queues. Using serial files as GSAM files EGL programs that run in the IMS BMP or z/OS batch environments can implement serial files as GSAM files. You can use the add, get next, and close I/O statements for serial files that you implement as GSAM files. Here is a list of differences between GSAM and normal serial file processing: v A GSAM file requires a DBD. v A GSAM file requires a PCB in the IMS PSB. You must define this PCB in the IMS runtime PSB and in the EGL PSB definition. In your program, you must declare a record variable that is based on the PSB record part. v A GSAM file is read or written through DL/I calls. The generated COBOL program handles this automatically, based on the I/O statements that you request. v A GSAM file is checkpointed and restarted in the same way as a DL/I database. However, to recover the GSAM file requires the use of symbolic checkpoint and restart instead of basic checkpoint. EGL does not support the record search argument for GSAM or undefined length records. You identify a serial file or print file as a GSAM file by using the resource association part during generation to specify a file type of GSAM and a PCB name. When you associate a serial file with a GSAM file, you must include the following information: Developing EGL programs for the IMS environment 319 Resource name Indicates the 1- to 44-character data set name that is used in the sample runtime JCL. The file name from the record definition is used as the DD name in the sample runtime JCL. File type Specifies GSAM as the file type to associate the serial file or printer output with a GSAM file. PCB name Specifies a PCB name for the serial file that is associated with the GSAM file. If you do not specify one, the default is the first GSAM PCB in the EGL PSB. Using serial files as message queues Online programs that run in IMS/VS implement serial files as IMS message queues. Programs that run as IMS BMP programs can also implement serial files as message queues. You can use the add and get next I/O statements as well as close for output files. If you select IMS/VS or IMS BMP as the target runtime environment, you can define serial or print files as being associated with a message queue. You must associate all serial files and print files with message queues for IMS/VS. Only a single input file can be associated with the message queue. You can associate a serial file or print file with a message queue by using a resource association part during generation and specifying the file type and a PCB name. When you associate a serial file with a message queue, you must define the following resource information: Resource name You must indicate the 1- to 8-character destination ID for printer or serial file data. The name must match the ID of an IMS logical terminal or a transaction code that is defined in the IMS system definition. The file name is the default resource name for the message queue. You can override this default in the resource association part. If the PCB that you select is a modifiable alternate or express alternate PCB, you can override the default message queue name at run time by setting a value for record.resourceAssociation for a file or converseVar.printerAssociation for a printer in the program. record.resourceAssociation is treated as a local variable. Setting record.resourceAssociation for a record in one program does not affect record.resourceAssociation in another program. An add statement writes to the message queue identified by the setting of record.resourceAssociation for that program. Message queue type You can specify single-segment message queues or multiple-segment message queues. Single-segment message queues (SMSGQs) For a single-segment message queue, each record that you add or that you read (with a get next) from the serial file is a complete message. The generated COBOL program issues an IMS PURG call between records that are added to a single-segment message queue. The generated COBOL program issues an IMS get unique for each get next statement. Multiple-segment message queues (MMSGQs) 320 EGL Programmer’s Guide For multiple-segment message queues, a series of adds to the serial file is treated as though each add statement were for a segment of a single message. The message is not ended until you issue a close statement or reach a commit point. The generated COBOL program issues an IMS PURG call for the close statement. You can then begin adding segments of another message and close it. Multiple-segment message queues are not valid for print files. If you issue a get next statement for a MMSGQ serial file, the generated program issues an IMS get unique call to get the first segment of the message. Additional get next statements result in GN calls to get the remaining segments of the message. At the end of all the segments in a message, the generated COBOL program sets the noRecordFound record state. If you continue scanning, the generated program starts another series of get unique (GU) calls, followed by get next (GN) calls. When no more messages are found, the generated program returns an endOfFile state. PCB name You must also specify a PCB name for the serial file that is associated with a message queue. You must specify the name assigned to the I/O PCB as the PCB name for a serial input file. The I/O PCB is the only message queue used for input. If you use a serial input file, you must use a main batch or called batch program. The generated program handles all I/O PCB logic for main textUI programs. You can specify the PCB name for a serial output file. The PCB name must be the name assigned to an alternate PCB record. The default PCB name is the name of the first alternate PCB in the PSB. You can only send output to the I/O PCB by using one of the following system functions: v vgLib.VGTDLI() v dliLib.AIBTDLI() v dliLib.EGLTDLI() Defining records to use with message queues When you define a serial record to associate with a message queue, you should define only the program data. The generated COBOL program adds the IMS message header (length, ZZ, and transaction code) for an add statement and removes it for a get next statement. Checking the results of serial file I/O statements When a serial file is associated with a message queue or GSAM database, the generated program issues a DL/I call to implement the I/O operation. When the DL/I call completes, Rational COBOL Runtime for zSeries performs the following functions: v For get next statements, the record state is set based on the DL/I status code. The sysVar.sessionID and sysVar.userID fields are updated from the user ID field of the I/O PCB when the generated program issues a GU call for the I/O PCB. This happens at the first get next statement for a serial file defined as a multiple-segment message queue (MMSGQ), and at each get next statement for a single-segment message queue (SMSGQ). The EGL sysVar.transactionID field is updated from the transaction name in the IMS message header after each get next statement that results in a GU call for the I/O PCB. v For an add or close statement, the record state is updated based on the DL/I status code. Developing EGL programs for the IMS environment 321 After a DL/I call that involves either the message queue or GSAM, the dliVar fields are not updated. These fields are updated only for functions that access DL/I segment records. This allows a program written for a CICS transient data queue or an OS/VS serial file to run consistently when the file is changed to a message queue or GSAM database in an IMS environment. You should check the I/O error values to determine if endOfFile, noRecordFound, or other error occurred on the serial file. If you need more detailed information from the PCB, use the field names in the IO_PCBRecord or the ALT_PCBRecord. Consider a situation in which your PSB variable (named myPSB) declares an ALT_PCBRecord named myAltPCB, and you used myAltPCB as the PCB name in your resource association. To reference the DL/I status code after an add statement, use myPSB.myAltPCB.statusCode. EGL I/O error code endOfFile noRecordFound ioError hardIOError EGL I/O error code endOfFile ioError hardIOError IMS Messsage Queue status code QC QD any non-blank status code Severity Soft Soft Hard or soft non-blank other than QC, QD, CE, CF, CG, Hard CI, CJ, CK, CL GSAM status code GB any non-blank status code non-blank other than GB Severity Soft Hard or soft Hard Using print files as message queues For IMS/VS you must associate print files with message queues. For IMS BMP, you can associate print files with message queues. You associate print files with message queues the same way you associate serial files with message queues, with the exception that SMSGQ is the only valid file type for a resource association whose file name is ″printer″. In your IMS system definition, you must define the message queue name that you use in the runtime environment as a logical terminal. You can use converseVar.printerAssociation to change the printer destination at run time. For example, you could define a table of user IDs and the printer ID that each user normally uses. By setting converseVar.printerAssociation, you can route the printer output to a printer near the program user. Related concepts “Developing EGL programs for the IMS environment” on page 307 Example IMS program code These excerpts from EGL programs show interaction with IMS terminals, message queues, and serial files. Example of output to a serial file associated with a message queue Here are some code excerpts from an EGL program that accesses message queues. The program carries out the following tasks: 1. Requests input from a terminal using a form. 2. Reads the response. 3. Updates a serial record with information based on the user input. 322 EGL Programmer’s Guide 4. Outputs the serial record to another transaction for later batch processing. The program assumes the following associations in your IMS environment: v IMS transaction code MYTRXCD1 is associated with a PSB named MYTRXCD1. v IMS transaction code NEXTTRX is associated with a PSB named MYTRXCD2. //define PSB Record addToQueue type PSBRecord { defaultPSBName="MYTRXCD1" } // three PCBs required for CBLTDLI on IMS iopcb IO_PCBRecord { @PCB { pcbType = TP } }; elaalt ALT_PCBRecord { @PCB { pcbType = TP } }; elaexp ALT_PCBRecord { @PCB { pcbType = TP } }; // other database PCBs ... end Record myTransactionPart type serialRecord { fileName="MYMSGQUE" } ... end program addtrans type textUIProgram { alias = "MYTRXCD1", // IMS requires pgm to match PSB name segmented = yes, @DLI { psb = "mypsb" }} use MYFORMS; // MYFORMS is a formGroup containing FORM1 // serial record for message queue // psb // declare variables myTransaction myTransactionPart; mypsb addToQueue; function main() ... converse FORM1; // do whatever processing is necessary move FORM1 to myTransaction byName; add myTransaction; ... end end When you generate, you must specify a resource association part that associates the serial file with a message queue and that provides the name of the transaction to which it is to be sent, along with the name of the PCB to use. Consider the following example, which also includes an association element that makes possible the input of the message-queue data by a batch program, as described later: <ResourceAssociations name="IMS_RESOURCE_ASSOCIATION"> <association fileName="MYMSGQUE"> <imsvs> <smsgq systemName="NEXTTRX" pcbName="elaalt"/> </imsvs> </association> <association fileName="MYINQUE"> <imsvs> <smsgq systemName="NEXTTRX" pcbName="iopcb"/> </imsvs> </association> </ResourceAssociations> Because addtrans is a textUI program, EGL generates control logic to interface to the IMS environment. IMS programs are expected to read the input message queue until the queue is empty. Therefore, EGL generates logic into the program so that Developing EGL programs for the IMS environment 323 Key changes show in bold in the example below: //define PSB Record getFromQueue type PSBRecord { defaultPSBName="MYTRXCD2" } // three PCBs required for CBLTDLI on IMS iopcb IO_PCBRecord { @PCB { pcbType = TP } } elaalt ALT_PCBRecord { @PCB { pcbType = TP } }. the program loops to read the next input message from the queue. you only need to consider the processing that must occur for a single user at a single terminal. EGL sets sysVar. IMS schedules the PSB associated with the transaction code MYTRXCD1. Assume USER1 and USER2 both enter MYTRXCD1 on their terminals at the same time. The systemName property is optional. you must also specify a resource association part that associates the serial file with a message queue. 324 EGL Programmer’s Guide . as shown in the ResourceAssociations part in the previous section. though it does not have to be. EGL generates control logic into the program to handle the complex situation on IMS when you have multiple users in contention for the resources. for more information. elaexp ALT_PCBRecord { @PCB { pcbType = TP } }. 1. see ″Multiple users and message queues″ in this topic. The program reads the message queue associated with the transaction that started the program. Assume that USER1’s transaction code ends up first on the message queue associated with MYTRXCD1. That PSB happens to be named MYTRXCD1 as well.transactionID based on the IMS transaction id in the input message.once the program responds to the current user (using a converse or show statement) or transfers the responsibility for responding (using a transfer to transaction statement). In this case. Example of IMS batch processing You can also create a program to process the messages that program addtrans writes to the message queue. The program can use the same serial record that addtrans used. For an overview. Mutliple users and message queues When you write an EGL program. based on the IMS system definition. but with a new file name because a different PCB name is required. mypsb getFromQueue. // other database PCBs end program gettrans type basicProgram { alias = "MYTRXCD2" @DLI { psb = "mypsb" }} // declare variables myTransaction myTransactionPart {fileName="MYINQUE"}. // serial record for message queue // psb function main() while (myTransaction not endOfFile) get next myTransaction. see “Interacting with terminals in IMS” on page 315. as well as the name of the PCB to use. // do whatever processing is necessary end end end When you generate the program for either the IMS/VS or the IMS BMP environments. the I/O PCB is used for input. The program must be a basic program that gets records from a serial file and associates the serial file with the I/O PCB. saves all data. Therefore IMS loads the program MYTRXCD1 (known as addtrans to EGL). The EGL-generated control logic determines that this response is a continuation of USER1’s processing. and does the following: v Restores USER1’s data (including the location of the converse statement) v Refreshes a number of system variables v Runs any validation checks that FORM1 requested v Assuming no input errors.The program associated with the PSB. The EGL-generated control logic in program MYTRXCD1 determines that this is the first time the program has been invoked for USER1. 5. and sends a response to USER1. the program reaches another converse statement. and continues processing. The program then loops back to check the message queue again. so processing begins at the top. Here the program is likely to find USER1’s response to the converse statement. reaching the converse statement. if USER1 responds to the most recent console message. Program MYTRXCD1 ends. restores all data. Eventually the program reaches the converse statement and performs the following actions: v Saves the data for all records and forms the program is using v Saves information about where in the program the converse statement occurred v Performs the ISRT command with the specified form 4. 8. Related concepts “Developing EGL programs for the IMS environment” on page 307 Related tasks “Interacting with terminals in IMS” on page 315 Developing EGL programs for the IMS environment 325 . 2. Later. resumes processing at the statement after the converse statement 6. The program follows the same steps for USER2 that it did for USER1. Assume that USER2 has gone to lunch and there is nothing left on the message queue associated with the transaction code MYTRXCD1. IMS will once again have a message on the queue associated with transaction code MYTRXCD1 and will start the program MYTRXCD1 again. sending the form. must have the same name as the PSB in IMS. Eventually. 3. then looping back to check the message queue again. 7. Following the logic that EGL added. The EGL-generated control logic determines that this response is a continuation of USER1’s processing. the program loops back to the beginning and finds USER2 waiting on the message queue. however. 326 EGL Programmer’s Guide . For advanced purposes. For example. not on the remote machine that serves the Web page. a developer can write custom JavaScript or use JavaScript libraries instead of relying on the default behavior provided by EGL. which is converted automatically to output that is useful for running a business. even as the user continues working elsewhere on the page. After the user selects a purchase order from a list box. redraws only one area of the page. © Copyright IBM Corp. A developer writes Rich UI applications using EGL syntax. however. The output in this case is client-side JavaScript. After the user clicks a radio button.org/) v Microsoft Silverlight (http://silverlight. for example. in most cases. 2008 327 . An extension of client-side JavaScript is Ajax.net/) A Rich UI application can act as the front end for services that access databases and do other complex processing. you do the following tasks in the EGL Rich UI perspective: 1. which are described in Overview of service access: v SOAP Web services v REST Web services that are provided by third parties such as Yahoo and Google v EGL REST services. a technology that permits the runtime invocation of remote code and the subsequent update of a portion of a Web page. providing greater flexibility so that the user’s experience can go beyond receiving and submitting a page. Open the handler in the EGL Rich UI editor and add content to the Rich UI handler in the following ways: v By dragging on-screen controls called widgets onto a Web page surface. the JavaScript logic might request transmission of order-item details from the remote Web server and then place those details in a table displayed to the user. In this situation. Create a kind of EGL handler part called an EGL Rich UI handler 3. you can use Rich UI to access the following software: v The Dojo Toolkit (http://dojotoolkit. Create a Rich UI project 2. In this way. The technology builds on an idea central to EGL: write simple code. at run time. Client-side JavaScript is important because it makes the Web page more responsive. the application can access content from the server but can save time by selecting. you can set widget properties by typing values into dialogs that are part of the Rich UI editor. You can access the following kinds of services. which content is transmitted. the logic might respond by changing the content of a text box. which are REST Web services for which the access code is particularly simple Outline of development tasks As a Rich UI developer. v By coding widget details directly into the Rich UI handler. The change occurs quickly because the JavaScript runs locally and.Overview of EGL Rich UI EGL Rich UI is a new technology for writing applications that will be deployed on Web servers. 1996. called client-side because the JavaScript runs in the browser. for example. The Design view and Source view are integrated: changes to the Design view are reflected in the Source view.v By writing the following kinds of logic directly into the Rich UI handler: – Startup logic. You can drag-and-drop widgets from a palette into the display and then customize those widgets in the Properties view. where you can run your logic. The editor includes the following views: v The Design view is a graphical design area that shows the displayable content of the Rich UI handler. However. v The Source view provides the EGL editor. You can easily switch to an external browser if you prefer. which runs when the browser first receives the application from a Web server – Event logic. changes to the Source view are reflected in the Design view. Rich UI does not support service access in this case. internal to the Workbench. The EGL Rich UI Editor You can use the EGL Rich UI editor to modify a Rich UI handler and to preview the handler’s runtime behavior. if possible. which runs in response to user actions such as a button click When you are ready to deploy your code. where you update logic and add or update widgets. and. The EGL Rich UI Perspective Here is the EGL Rich UI perspective as it appears when a Rich UI handler is open in the Rich UI editor: 328 EGL Programmer’s Guide . v The Preview view is a browser. you use the EGL deployment wizard and store output in one of the following locations: v A Web project that is configured for WebSphere Application Server v A Web project that is configured for Apache Tomcat v A directory whose content is ultimately provided to a simple HTTP server such as the Apache HTTP server. Overview of EGL Rich UI 329 . The Capabilities page is displayed.Related concepts “Understanding how browsers handle a Rich UI application” on page 334 “Introduction to the EGL Rich UI editor” on page 337 You can use the EGL Rich UI editor to modify a Rich UI handler and to preview the handler’s runtime behavior. Overview of service access Overview of EGL Rich UI generation and deployment “Securing a Rich UI application” on page 352 Related tasks “Starting to work with EGL Rich UI” This topic tells how to start developing applications with EGL Rich UI. The Preferences dialog box is displayed. enable the Rich UI capability: v Click Window > Preferences. v Expand General and click Capabilities. Enabling the Rich UI capability If you are working in an existing workspace. Related reference Rich UI handler part Rich UI widgets Reference to widgets Extending the Rich UI widget set Starting to work with EGL Rich UI This topic tells how to start developing applications with EGL Rich UI. egl and select Open with → EGL Rich UI Editor. expand the project com. switch to the EGL Rich UI perspective: v Click Window -> Open Perspective -> Other v At the Open Perspective dialog. The Advanced Capabilities dialog is displayed.egl 4. 3. Otherwise. However.ibm.rui. Select the Preview tab at the bottom of the editor. The New EGL Project page is displayed. package contents. click . The New Project wizard is displayed. Switching to the EGL Rich UI perspective When you first open the Workbench. Click Rich UI technical sample.egl. In the workbench Project Explorer. 3. v Click Apply to save your changes and remain on the Preferences dialog box. Click File -> New -> Project. In the File types section. 4. complete the task by clicking Finish. Expand EGL. Click Window > Preferences.egl. If you previously set the Rich UI editor to be the default for EGL files. Follow the on-screen directions and try out the alternatives presented there. 5. click Default 5.ibm. double-click EGL Rich UI Setting the Rich UI editor as the default for EGL files If most of your EGL work will involve Rich UI.v Click Advanced. do as follows: 1. Creating your first Rich UI project When you want to work outside of the Rich UI samples project. click OK to save the changes and exit the page. Type a project name and select Rich UI Project. Expand General and Editors and click File Associations. or click Cancel to cancel the changes and exit the dialog box. double-click contents. If your workbench does not already have the project com. The File Associations dialog is displayed.samples. v Click EGL Rich UI and click OK. 2. 9. click EGL Project and then Next. 2. 7. Technology samples. Click the entry to import the samples. continue here: 330 EGL Programmer’s Guide . file EGL Source. Expand Samples. if you want to consider additional options. 8. click EGL Rich UI Editor and. click the entry to it. you will want to make the Rich UI editor the default for EGL files: 1. 2. In most cases. The Preferences dialog box is displayed.rui_1. The Help dialog box is displayed.0. Alternatively. at the right.egl. right-click contents. Click Help -> Samples. 6. 3. In the Associated editors section.0. Click OK Accessing the Rich UI samples We recommend that you use the Rich UI samples to explore the technology: 1. The EGL Settings page is displayed. ignore references to Handlers (other than Rich UI handlers) and Programs – Ignore Build parts other than the build descriptor and the deployment descriptor v Content assist v Searching for EGL files and parts v Setting Preferences in the EGL editor. (ii) to export a project. otherwise. the following topics: – Setting Preferences for folding in the EGL editor – Setting Preferences for organizing import statements in the EGL editor – Setting Preferences for source styles – Enabling and disabling code templates Overview of EGL Rich UI 331 . An EGL service deployment descriptor lets your application access remote services in a flexible way. Click the check box beside each project that you want to add to the project’s EGL build path. The overhead of including the descriptor is small. d. see IBM Rational Business Developer with EGL: http://www. select the related check box. and (iii) to handle all the projects at once. so that at configuration time. select the check box for Use the default location for the project.html The content of that book will be included in a new work that focuses on Rich UI. To include the project in the directory that stores the current workspace. Click Next. click the Order and Export tab and do as follows: (i) To change the position of a project in the build-path order. f. See the following topics in the EGL Programmer’s Guide (aside from topics specifically on Rich UI): v Using EGL with the Eclipse IDE v Introduction to EGL projects through Properties: – In relation to Data parts. ignore references to Form Group and ArrayDictionary – In relation to Logic parts. and we recommend that you select the check box for Create an EGL service deployment descriptor regardless of your intent. specifically. select the project and click the Up and Down buttons. Click Next so that the EGL Project page is displayed. specify a different directory by clearing the check box and using the Browse mechanism. Reviewing general information on EGL EGL Cafe provides is a center of information about the products that include EGL: http://www. click the Select All or Deselect All button. The Projects tab lists all other projects in your workspace. b. an installer can change the details of service access. e.mc-store.0 with EGL is expected from MC Press in May 2009.a.com/software/rational/eglcafe For a concise introduction to EGL. To put the projects in a different order or to export any of them. Enterprise Web 2.com/5087. c.ibm. Click Finish. and Web transactions. v Record stereotypes other than BasicRecord and ExceptionRecord. and SQL Record parts. but only to invoke services. Not supported are the Record part properties containerContextDependent. structured Record parts. arrays of supported types. Text UI. and printer access is supported only by service access. i4glItemsNullable. converse. DECIMAL. Rich UI supports non-structured Record parts. Interface parts. When you work with Rich UI. reports. INTERVAL. UNICODE. exit while. related statements such as forEach and get. SMALLFLOAT. and z/OS batch. ConverseLib. v The following types are not supported: ArrayDictionary. TIME. v The following statements are not supported: add. forEach. v Details that are specific to Java or COBOL processing. BIN (but only in the absence of decimal places). freeSQL. exit if. VgLib. INT. v Only the following variations of the exit statement are supported: exit for. and textLiteralDefaultIsString. display. PACF. Service parts. get. all such access is handled by invoked services. CHAR. However. PortalLib SqlLib. replace. and VgVar. TIMESTAMP. J2eeLib. LobLib. Boolean. Dictionary. IMS. openUI. See the following topics in the EGL Generation Guide (aside from topics specifically on Rich UI): v Introduction to EGL generation v Build descriptor part Reviewing compatibility issues Here are the major compatibility issues: v File. stereotype SQLRecord (as well as stereotypes BasicRecord and ExceptionRecord). goTo. and exit case. continue. v Function overloading is not supported v Generation of the following outputs is not supported: programs. open. STRING (but only in the absence of a size limit) . JavaLib. delete. NUMC. DliLib. DataItem. forward. services. FLOAT. NUMBER. and related Exception records. Exception. data tables.v EGL debugger commands v Setting preferences for the EGL debugger Exclude the following subjects when reviewing the EGL Language Reference: v File and database access. move. MONEY. JSF. NUM. print. prepare. v System libraries ConsoleLib. forms. HEX. form groups. execute. 332 EGL Programmer’s Guide . BLOB. BIN (with decimal places). database. v User interfaces. and transfer. and parts specific to the technologies Console UI. v The Program-related statements transfer and call. DBCHAR. not directly by the Rich UI application code. set. or other outputs that are specific to Java or COBOL. CICS. and non-structured Basic. in particular. External types (stereotype JavaScript). v The following types are supported: ANY. BIGINT. close. v Compatibility with VisualAge Generator or Informix 4GL. v Reporting is not directly supported. DATE. v A version of the call statement is supported. CLOB. SMALLINT. MBCHAR. Delegate. NUM. details related to J2EE. STRING (with a size limit). DataTable. as a property value) before or after the variable is declared. DliVar. the data-type restrictions noted earlier limit the support for the following mathLib functions: abs. v The three bitwise operators (& | Xor) are not supported.v The following system libraries are not supported: ConsoleLib. and MBCHAR are not supported. v The StrLib constant nullFill is not supported. v Elsewhere in EGL. setNullTerminator(). as described in Rich UI debugging. getTokenCount(). ConverseLib. Also. v Only the following variations of the is and not operators are supported: use of sysVar. intAsChar(). defaultMoneyForm(). DliLib. Also. see Understanding how browsers handle a Rich UI application and then Rich UI Handler part. end v The details on using the EGL debugger are slightly different. v Rich UI code cannot compare a variable of type ANY to a value variable: // Not supported if (myAny == 1) . intAsUnicode(). min. writeStdError(). J2eeLib. the data-type restrictions noted earlier limit the support for the following mathLib functions: getNextToken() and indexOf(). with the following exception: widgets can be referenced in the initialUI or children property before the widgets are declared. v The only supported sysVar variable is sysVar. defaultNumericFormat(). precision. formatNumber(). Related concepts “Overview of EGL Rich UI” on page 327 “Understanding how browsers handle a Rich UI application” on page 334 “Introduction to the EGL Rich UI editor” on page 337 You can use the EGL Rich UI editor to modify a Rich UI handler and to preview the handler’s runtime behavior. setBlankTerminator(). JavaLib. unicodeAsInt().systemType and record-specific tests of blanks and numeric. PortalLib ReportLib. SqlLib. a variable must be declared before it is used. and round. nor is the in operator. max. charAsInt().systemType. In Rich UI. DBCHAR. v The mathLib function assign() is not supported. v Literals of type CHAR. v The following dateTimeLib functions are not supported: intervalValue() and intervalValueWithPattern(). v The only supported sysLib functions are conditionAsInt(). To understand the initialUI and children properties. Overview of service access Overview of EGL Rich UI generation and deployment “Securing a Rich UI application” on page 352 Related tasks Rich UI debugging Related reference Rich UI handler part Rich UI widgets Reference to widgets Overview of EGL Rich UI 333 . a variable may be used (for example. and writeStdOut(). LobLib. getNextToken(). and VgVar. VgLib. v The following strLib functions are not supported: byteLen(). the browser transmits a request to a Web server. Consider the following Web-page content: Six widgets are displayed: v The enclosing box is myBox v The upper box within myBox is myBox02 and includes the text field myHelloField v The lower box within myBox is myBox03 and includes the text field myInTextField. Example widgets are buttons and text fields. The browser then uses the values in those data areas to display on-screen controls. The purpose is twofold: v To help you learn the technology faster. an IBM server replies with a message that the browser uses to display the IBM home page. The address identifies a specific server and indicates what content is to be returned to the browser. The question that is of interest now is. as is possible if you understand the runtime effect of what you code at development time v To make it easy for you to do advanced tasks When a user enters a Web address into a browser. For example.Understanding how browsers handle a Rich UI application This topic gives details on how browsers handle a Rich UI application at run time.ibm. which is usually on a second machine. if you enter the address http://www.com. how does the browser use the message? The browser brings portions of the message into an internal set of data areas. which are commonly called widgets. the button myButton. and the textField myOutTextField The internal data areas used by the browser are represented as an inverted tree: 334 EGL Programmer’s Guide . The following rules describe the default behavior: v A widget that reflects a child element is displayed within the widget that reflects a parent node v A widget that reflects a sibling element is displayed below or to the right of a widget that reflects the immediately previous sibling element We often use a technical shorthand that communicates the main idea without distinguishing between the displayed widgets and the DOM elements. But in all cases.The tree is composed of a root -. we might say. a widget reflects the information in a subtree of several elements. The topmost element that is available to you is named body. which are units of information. Instead of the previous list. at least to some extent. the spacial relationship among the displayed widgets reflects the DOM-tree organization. a widget reflects the information in a single DOM element. and myOutTextField are siblings In the simplest case (as in our example). ″A widget is contained within its parent. A set of rules describes both the tree and how to access the data that the tree represents. That set of rules is called the Document Object Model (DOM).″ The DOM tree organization does not completely describe how the widgets are arranged. and a sibling is displayed below or to the right of an earlier sibling.named document -. A parent element may include detail that causes the child widgets to be arranged in one of two ways: one sibling below the next or one sibling to the right Overview of EGL Rich UI 335 . myButton. We refer to the tree as the DOM tree. and we refer to the relationships among the DOM elements by using terms of family relationships: v myBox03 and myInTextField are parent and child v myBox and myButton are ancestor and descendant v myInTextField.and a set of elements. In other cases. The elements subordinate to body are specific to your application. When you work in the Source tab of the Rich UI editor or in the EGL editor. some of the tasks needed for initial DOM-tree creation are handled for you automatically during a drag-and-drop operation. by the browser-window size. In general terms.of the next. which the user can update at run time in most cases. Related concepts “Overview of EGL Rich UI” on page 327 “Introduction to the EGL Rich UI editor” on page 337 You can use the EGL Rich UI editor to modify a Rich UI handler and to preview the handler’s runtime behavior. The display also may be affected by the specifics of a given browser.″ as in our example. We say that a widget or its changes are ″displayable″ rather than ″displayed″ because a widget in a DOM tree can be hidden from view. However. you declare widgets much as you declare integers. you might set the text of a button to ″Input to Output. 2. TextField for text fields. 3. changing. Your code can also update the tree—adding. the widgets are displayable only if your code also adds those widgets to the DOM tree. For example. you can write code directly and even reference DOM elements explicitly. The central point is as follows: Your main task in Web-page development is to create and update a DOM tree. Overview of service access Overview of EGL Rich UI generation and deployment “Securing a Rich UI application” on page 352 Related reference Rich UI handler part Rich UI widgets Reference to widgets Extending the Rich UI widget set 336 EGL Programmer’s Guide . When you work in the Design tab of the Rich UI editor. you create and update a DOM tree in three steps: 1. Add widgets to the initial DOM tree. and removing widgets—in response to runtime events such as a user’s clicking a button. the display may be affected by settings in a cascading style sheet. changing. Alter the DOM tree by adding. and so forth—and customize the widget properties. Last. for example. Declare widgets of specific types—Button for buttons. When you develop a Web page with Rich UI. and removing widgets at those points in your code when you want the changes to be displayable. That property Overview of EGL Rich UI 337 . if possible.Introduction to the EGL Rich UI editor You can use the EGL Rich UI editor to modify a Rich UI handler and to preview the handler’s runtime behavior. the entire surface is a selected drop location. where you update logic and add or update widgets. where you can run your logic. Here is an example of an open file in the Rich UI editor. The Rich UI editor includes three views: v As shown in the example. the Design surface is a rectangular area that shows the displayable content of the Rich UI handler. v The Preview view is a browser. You can easily switch to an external browser if you prefer. changes to the Source view are reflected in the Design view. and the color of that area is green by default. The Design view and Source view are integrated: changes to the Design view are reflected in the Source view. When you hover over a potential drop location. You can customize the colors in the Workbench preferences. When you first drag a widget to the Design surface. the area is called a selected drop location. Using the Design surface to create a DOM tree When you drag a widget from the palette to the Design surface. and. the areas that can receive the widget are called potential drop locations. and the effect of the drop is to declare the widget and to identify it as the first element in the Rich UI handler’s initialUI property. and the color of those areas is yellow by default. v The Source view provides an embedded version of the EGL editor. You can drag-and-drop widgets from the palette into the Design surface and then customize those widgets in the Properties view. internal to the Workbench. Understanding the transparency options The Design surface is composed of two layers. 338 EGL Programmer’s Guide . to add a child element to the element that represents the container. You can repeatedly fulfill drag-and-drop operations. as described in Setting preferences for Rich UI appearance.egl in two ways. whether in the Source tab of the Rich UI editor or in the EGL editor. specifically.accepts an array of widgets at development time. You can set those transparency options by setting a Workbench preference. the elements in the Rich UI handler’s initialUI array become children of the document element. When you are working in the editor. Specifically. At the bottom is the EGL editor. a pattern of white and transparent dots. the following screen shot displays the file GridDemo. or (on Windows platforms) a white layer with a varying level of transparency. which displays widgets. For example. Your subsequent work continues to build the DOM tree. The background of the top layer can have any of the following characteristics: transparent. The drag-and-drop operation is an alternative to writing a widget declaration and array assignment in the code itself. v If the initially placed widget was a container—for example. with the placement of a widget determining what array is affected and where the widget is placed in the array. including initial text values. The bottom layer is the Web browser. The array is ultimately used to create a DOM tree. Your work in either editor affects the same file and is reflected in the content displayed in the other editor. At the top is the Design tab of the Rich UI editor. you can change the transparency options that are in use for the editing session. including angle brackets at each corner of each widget. The effect is ultimately to add a child element to the DOM tree. a box—you can place the second widget inside the first. along with a palette that lists the available Widget types. Your placement of the new widget is either before or after the first widget and indicates where the widget is placed in the array. that is. When you drag another widget to the Design surface. you have the following choices: v You can place the widget adjacent to the initially placed widget. The top layer is an editing overlay. The effect on your source code is to add an element to the children property of the container. The effect on your source code is to declare the second widget and to identify it as another element in the initialUI array. New widget declarations are added to the source code before the declarations that were already there. Combining the EGL Rich UI editor and the EGL editor You can complement the features in the Rich UI editor by opening a single file in both the EGL Rich UI editor and the EGL editor. the order of the statements is opposite to the order of the drag-and-drop operations. with the order of initialUI array elements at development time equivalent to the order of sibling DOM elements at run time. which is a runtime data structure described in Understanding how browsers handle a Web application. you can open the Rich UI editor by double-clicking an EGL file in the Project Explorer.Related concepts “Overview of EGL Rich UI” on page 327 “Understanding how browsers handle a Rich UI application” on page 334 Related tasks “Opening the EGL Rich UI editor” “Creating a Web interface in the Rich UI editor” on page 340 This topic describes how to add. Related reference Rich UI handler part Rich UI widgets Reference to widgets Extending the Rich UI widget set Opening the EGL Rich UI editor As described in Starting to work with EGL Rich UI. you can set the EGL Rich UI editor to be the default editor for every EGL file and then. Here are the alternative procedures: v To open an existing file: 1. and delete widgets in the EGL Rich UI editor. In each case. select. in most cases. move. “Running a Web application in the EGL Rich UI editor” on page 344 “Starting to work with EGL Rich UI” on page 329 This topic tells how to start developing applications with EGL Rich UI. which you access by clicking on the Design tab. Right-click on the EGL file in the Project Explorer Overview of EGL Rich UI 339 . you work on the Design surface. move. 3. At the selected drop location. A wizard is displayed. Adding a widget Add a widget to a Rich UI handler: 1. Click a Widget type in the palette and hold the left mouse button 2. and delete widgets in the EGL Rich UI editor. Use the widget-placement guide to help identify where to drop the widget 4. Expand EGL Select Rich UI Handler 4. release the mouse button 340 EGL Programmer’s Guide . select. 2.2. select. Related reference Rich UI handler part Rich UI widgets Reference to widgets Extending the Rich UI widget set Creating a Web interface in the Rich UI editor This topic describes how to add. v To 1. Complete the wizard If v v v the EGL source editor automatically opens: Close the source editor Right-click on the empty new file in the Project Explorer Select Open with → EGL Rich UI Editor Related concepts “Overview of EGL Rich UI” on page 327 “Understanding how browsers handle a Rich UI application” on page 334 Related tasks “Introduction to the EGL Rich UI editor” on page 337 You can use the EGL Rich UI editor to modify a Rich UI handler and to preview the handler’s runtime behavior. and delete widgets in the EGL Rich UI editor. move. “Running a Web application in the EGL Rich UI editor” on page 344 “Starting to work with EGL Rich UI” on page 329 This topic tells how to start developing applications with EGL Rich UI. “Creating a Web interface in the Rich UI editor” This topic describes how to add. In each case. Drag the widget to the Design surface 3. see Introduction to the EGL Rich UI editor. you work on the Design surface. which you access by clicking on the Design tab. Select Open with → EGL Rich UI Editor create a new file and open it in the Rich UI editor: Select menu item File → New → Other. In each case. which you access by clicking on the Design tab. you work on the Design surface. To learn the implication of the actions described here. Here is the toolbar: Overview of EGL Rich UI 341 . Related concepts “Overview of EGL Rich UI” on page 327 “Understanding how browsers handle a Rich UI application” on page 334 Related tasks “Introduction to the EGL Rich UI editor” on page 337 You can use the EGL Rich UI editor to modify a Rich UI handler and to preview the handler’s runtime behavior. making each one the current one in turn. “Running a Web application in the EGL Rich UI editor” on page 344 “Starting to work with EGL Rich UI” on page 329 This topic tells how to start developing applications with EGL Rich UI. You can move or delete the current widget as described in the next sections. click the Design tab. select Delete. Moving a widget Move a widget from one location to another: 1. Related reference Rich UI handler part Rich UI widgets Reference to widgets Extending the Rich UI widget set Using the tools on the Design surface To design an EGL Rich UI application in the EGL Rich UI editor. The deletion removes the reference to the widget in the handler-specific initialUI property or in the container-widget-specific children property. or v Right-click the widget and. release the mouse button Deleting a widget Delete a widget: v Click the widget and press the Delete key. click the area repeatedly to cycle through the available widgets. At the selected drop location. “Using the tools on the Design surface” “Selecting a palette” on page 342 “Setting widget properties and events” on page 343 You use the Properties and Events views when working at the Design surface of the Rich UI editor. Use the widget-placement guide to help identify where to drop the widget 4. Click a widget on the Design surface and hold the left mouse button 2.Selecting a widget when multiple widgets overlap When multiple widgets overlap a given area. but does not remove the widget declaration from the Rich UI handler. at the popup menu. Drag the widget to the preferred location 3. v The next tool is the Configure bidirectional options tool. The default palette is tied to the Rich UI editor. Again. which is also a toggle. and in each case you can right-click the palette or one of its drawers to display a menu that provides Eclipse-based options. which (if enabled) lets you open the preference page described in Setting preferences for Rich UI bidirectional text. which is a toggle. Click it to access the preferences that are described in Setting preferences for Rich UI appearance. Related reference Rich UI handler part Rich UI widgets Reference to widgets Selecting a palette Two palettes are available to the Rich UI editor. v The second tool is the Show browser size controls tool. Click it to refresh the Web page. Click it to display or hide the scroll bars that let you specify the browser size within the constraints that you set in the preferences. which searches the Workspace for widgets that have the @VEWidget complex property and then refreshes the palette to reflect the outcome of that search. For an introduction to embedded handlers. “Setting preferences for Rich UI appearance” on page 347 “Opening the EGL Rich UI editor” on page 339 “Using the tools on the Design surface” on page 341 “Setting widget properties and events” on page 343 You use the Properties and Events views when working at the Design surface of the Rich UI editor. 342 EGL Programmer’s Guide . as may be necessary after you change the widgets in an embedded handler. see Rich UI handler part. which are described in Setting preferences for Rich UI appearance.The tools on the Design surface provide the following functionality. Click it to display or hide the transparency tools. v The fourth tool is the Configure preferences tool. Each provides the same widgets as the other. v Second to the right is the Refresh palette tool. further details are in Setting preferences for Rich UI appearance. You can resize the width of the palette or dock it on the left or right. as indicated by the hover help that is displayed when you move the mouse over a given tool: v At the left is the Show transparency controls tool. See that topic for details on enabling the tool on the Design surface. “Running a Web application in the EGL Rich UI editor” on page 344 “Starting to work with EGL Rich UI” on page 329 This topic tells how to start developing applications with EGL Rich UI. v At the right is the Refresh web page tool. Related concepts “Overview of EGL Rich UI” on page 327 “Understanding how browsers handle a Rich UI application” on page 334 Related tasks “Introduction to the EGL Rich UI editor” on page 337 You can use the EGL Rich UI editor to modify a Rich UI handler and to preview the handler’s runtime behavior. On returning to the Color selection Overview of EGL Rich UI 343 . do as follows: 1. click the Number format radio button and the subordinate Color button. and the editor updates when you press Tab or Enter. If you want the extra flexibility provided by the Palette view. To remove a property value from a list box. 2. Click the color or background Color property. The Color selection dialog is displayed 2. close the Palette view. Click Palette and then OK. If you want to return to the Rich UI editor palette. To make the Properties and Events views available. do as follows: 1. 3. which you can move anywhere in the perspective or detach from the Workbench. Right-click a widget and select Properties Setting properties At the Properties tab. The Show View dialog is displayed. select the (none). you can add a value to a widget property. To handle color selection. do as follows: 1. Related concepts “Overview of EGL Rich UI” on page 327 “Understanding how browsers handle a Rich UI application” on page 334 Related tasks “Introduction to the EGL Rich UI editor” on page 337 You can use the EGL Rich UI editor to modify a Rich UI handler and to preview the handler’s runtime behavior. “Opening the EGL Rich UI editor” on page 339 “Using the tools on the Design surface” on page 341 “Setting widget properties and events” You use the Properties and Events views when working at the Design surface of the Rich UI editor. To remove a property value from a text box. Expand General. Three alternatives are available: v To work in the traditional Color dialog. Click the Design tab 2. The effect of selecting the Palette view is to close the Rich UI editor palette. if available.The other palette is a view. “Running a Web application in the EGL Rich UI editor” on page 344 “Starting to work with EGL Rich UI” on page 329 This topic tells how to start developing applications with EGL Rich UI. Click Window -> Show View -> Other. select the value and press the Delete key. Related reference Rich UI handler part Rich UI widgets Reference to widgets Setting widget properties and events You use the Properties and Events views when working at the Design surface of the Rich UI editor. ensure that the checkbox is selected. v To select from a list of named colors instead. Click OK. you can also specify whether the numeric color values retained from the Color dialog should be saved in RGB or hexadecimal format. v Alternatively. Related concepts “Overview of EGL Rich UI” on page 327 “Understanding how browsers handle a Rich UI application” on page 334 Related tasks “Introduction to the EGL Rich UI editor” on page 337 You can use the EGL Rich UI editor to modify a Rich UI handler and to preview the handler’s runtime behavior. Select the event of interest and click the New event handler icon. “Opening the EGL Rich UI editor” on page 339 “Using the tools on the Design surface” on page 341 “Selecting a palette” on page 342 “Running a Web application in the EGL Rich UI editor” “Starting to work with EGL Rich UI” on page 329 This topic tells how to start developing applications with EGL Rich UI. RGB and hexadecimal formats are both valid. you also add an entry for an event property such onClick. to create a new function. Specify the function name and click OK. you can specify which Rich UI handler function to run in response to an event such as a user’s click on a button. Specify the function name and. Here are the keystroke details: v To specify an existing Rich UI handler function. click the Custom radio button option. The New event handler dialog is displayed. Related reference Rich UI handler part Rich UI widgets Reference to widgets Running a Web application in the EGL Rich UI editor To run an EGL Rich UI application in the EGL Rich UI editor. Also at the Events tab. if you want to link the function to the event. 3. Creating new functions and enabling events At the Events tab. you can create a new function in the Rich UI handler: 1. do as follows: 1. The New event handler dialog is displayed. select the event of interest and use the dropdown to select the function name. 2. Here is the toolbar: 344 EGL Programmer’s Guide . click the Name Format radio button and select a color. In this case.dialog. v To specify a value of your own. Click the New event handler icon. 2. click the Preview tab. You can select which external browser is invoked by setting a system preference: 1. as indicated by the hover help that is displayed when you move the mouse over a given tool: v At the left is the Debug tool. The Rich UI dialog box is displayed. Click it to access the preferences that are described in Setting preferences for Rich UI appearance. Related reference Rich UI handler part Rich UI widgets Reference to widgets Extending the Rich UI widget set Setting preferences for Rich UI Set the initial Rich UI preferences as follows: 1. Select one of two values in the Generation mode list box: Development mode The generated output has information required by the EGL debugger and the EGL Rich UI editor. “Starting to work with EGL Rich UI” on page 329 This topic tells how to start developing applications with EGL Rich UI. Click it to place the output of the Rich UI application in an external browser as well as in the Preview view. From the main menu. v The third tool is the Configure preferences tool. move. see EGL Rich UI debugging. Related concepts “Introduction to the EGL Rich UI editor” on page 337 You can use the EGL Rich UI editor to modify a Rich UI handler and to preview the handler’s runtime behavior. and delete widgets in the EGL Rich UI editor. 2. Click Window -> Preferences. select. which you access by clicking on the Design tab. expand General and click Web Browser. For details. At the Preferences dialog. Overview of EGL Rich UI 345 . In each case.The tools at the Preview tab provide the following functionality. “Overview of EGL Rich UI” on page 327 “Understanding how browsers handle a Rich UI application” on page 334 Related tasks Rich UI debugging “Setting preferences for Rich UI appearance” on page 347 “Opening the EGL Rich UI editor” on page 339 “Creating a Web interface in the Rich UI editor” on page 340 This topic describes how to add. 3. Expand EGL and then Rich UI. However. 2. v At the right is the Refresh Web page tool. 3. v Second is the Launch external browser tool. Click it to rerun a generated Web page from the start. you can select your external browser by selecting from the list of browsers shown at that dialog and then clicking OK. click Window → Preferences. you work on the Design surface. The Preferences page is displayed. The check boxes Use Internal Web Browser and Use External Web Browser have no effect on Rich UI. Specify a locale for the EGL runtime messages. “Setting preferences for Rich UI appearance” on page 347 “Setting preferences for Rich UI bidirectional text” on page 349 When you establish preferences for Rich UI bidirectional text. To add a locale. you provide initial values for the bidirectional settings assigned to widgets as they are dragged from the palette and dropped on the Design surface. Related concepts “Preferences” on page 172 EGL preferences affect the way the workbench displays and works with EGL. Click Apply to save your changes and remain in the Preferences page. In the Locales area. c. or click Cancel to cancel the changes and exit the page. 4. Click OK. For details. Double-click a locale entry b. “Starting to work with EGL Rich UI” on page 329 This topic tells how to start developing applications with EGL Rich UI. Specify a locale code and description. 346 EGL Programmer’s Guide . To remove a locale from the list. by clicking in the Runtime Messages Locale column and selecting from a list. You can always perform these tasks. see Use of properties files for displayable text. click Restore Defaults. 6. Alternatively. you can click into the Locale Description or Locale Code column and change the content. b. but to make them appear in the menus. specify the locales that are available in the Rich UI editor and in the Rich UI deployment wizard. Click Remove At the Rich UI dialog box. Click Add. you must enable the capability for that area of functionality. Also. which are provided by the EGL Runtime and are distinct from the messages included in a properties file that you customize. even if that locale is distinct from the locale used for the messages that you provide. do as follows: a. We introduce that wizard in Overview of Rich UI generation and deployment. If you want to return the settings on the Rich UI dialaog to the original product settings. d. click OK to save the changes and exit the page. The settings are used for globalization. The Create a new locale dialog is displayed.Deployment mode The generated output lacks the extra information but is smaller and more efficient. do as follows: a. Deployment mode is appropriate immediately before you add fully tested code to a production environment. 5. Related tasks “Enabling EGL capabilities” on page 11 Capabilities keep the workbench menus from becoming cluttered by hiding items you do not use. “Setting preferences for Rich UI deployment” on page 351 Preferences guide the behavior of the Rich UI deployment wizard. you can assign a locale for the EGL runtime messages. The availability of a locale means that you can invoke and deploy a Rich UI application that provides messages appropriate to the locale. Click Apply to save your changes and remain on the Preferences dialog box. you are likely to prefer hiding the controls. General tab At the General tab. click Restore Defaults. click Window → Preferences. v Dotted transparency pattern means that the background is a pattern of white and transparent dots. The background of the top layer can have any of the following characteristics: transparent. which affect the background of the top layer of the Design surface: v Fully transparent means that the background is transparent. 2. do as follows: 1. as is the default setting for this preference. The bottom layer is the Web browser. you can change the transparency options that are in use for the editing session. The refresh rate of your monitor may cause the pattern to shimmer. do as follows: 1. In the Transparency section. or (on Windows platforms) a white layer with a varying level of transparency. the assigned names might be Button1. When you start working with Rich UI. the Rich UI editor creates its own variable name. Source. which vary how widgets are displayed in the Design tab of the Rich UI editor. 2. From the main menu.Setting preferences for Rich UI appearance Begin to set the appearance of the Rich UI editor as follows: 1. 3. or Preview to indicate which tab to initially use whenever you open the Rich UI editor. In the Widget creation section. which is the widget type name (for example. If you want to return the settings on the Appearance pane to the original product settings. The options are as follows: a. select one of the following transparency modes. The top layer is an editing overlay. The Design surface is composed of two layers. indicate how to handle the transparency controls. For example. The Preferences dialog box is displayed. The transparency options provided in the Appearance pane affect the behavior of the Rich UI editor every time you open the editor. indicate whether the Rich UI editor must prompt you for a variable name each time you drag a widget from the palette to the Design surface. including initial text values. Variable transparency means that the background is a white layer with a varying level of transparency. or a pattern of white and transparent dots. with three tabs: General. and so forth. The transparency controls are particularly useful when you are working on a Design surface with many widgets that are close together. In the Editor tab section. Browser size. when you are working in the editor. v On Windows platforms. Expand EGL and Rich UI. The dotted Overview of EGL Rich UI 347 . You vary the level by changing the numeric value of a slider. Alternatively. On completing the tabs. select Design. Button2. Box1. click OK to save the changes and exit the dialog box. and then click Appearance. Button) followed by a sequentially assigned integer. and Languages. including angle brackets at each corner of each widget. or click Cancel to cancel the changes and exit the dialog box. Select or clear the check box Show transparency controls to indicate whether to display the transparency controls. However. 2. The Appearance page is displayed. If you clear the checkbox. which displays widgets. Next. We describe each tab in turn. b. Change the numeric values of the sliders to specify the default height and width in pixels. Also. whether for greater responsiveness or for less usage of runtime resources such as memory. You can change the maximum and minimum only by returning to the Appearance page. However. occurs when you attempt to drop a widget for which the type is defined in a project that is not already in the EGL build path. The dependency issue arises in this case because the Widget types available in the palette may be from any project in the workspace. Select the checkbox to cause a prompt. where you can choose or refine a color. In the Dependencies section. for the border and the selected drop location. you can select (or clear) a check box to include (or exclude) the displayed pattern. you can cause the Rich UI editor to prompt you before adding a project to the EGL build path. Clearing the checkbox means that your usual transparency mode remains in effect. One effect of selecting Optimize to use fewer resources is that you increase the amount of time needed to display content when you select the Design or Preview tab. 348 EGL Programmer’s Guide . you can change the browser-size options for the file being edited. The checkbox named Enable semi-transparency while dragging allows use of a temporary transparency mode as you drag a widget from the palette to the Design surface or from one location on the Design surface to another.transparency pattern described earlier is roughly equivalent to the variable transparency pattern at 38%. Similarly. The nature of project dependencies is described in The EGL build path. 4. when you are working in the editor. 5. specify details on the following issues: v The border of the currently selected widget v The potential drop locations for a widget being dragged from the palette to the Design surface or from one location on the Design surface to another v The selected drop location. Browser size tab In the Browser size tab. 2. change the numeric values of the sliders to specify the minimum and maximum height and width that are valid in any file open in the Rich UI editor. In the Colors section. you are likely to prefer hiding the controls. if any. In the Performance section. The options are as follows: 1. which is a potential drop location over which the widget is hovering during a drag-and-drop operation For the border and each location. which lets you add the entry to the EGL build path or to cancel the operation. Select or clear the check box Browser size controls to indicate whether to display the controls when a file is opened in the Rich UI editor. you set options that are in effect whenever you open the Rich UI editor. you can click the adjacent button to display a color dialog. The checkbox has no effect if your usual transparency mode is the dotted transparency pattern. as is the default setting for this preference. 6. Clear the checkbox to add the entry automatically. Selecting the checkbox means that the temporary mode is the dotted transparency pattern. The prompt. The default you set becomes the browser size that is provided initially in the Rich UI editor. When you start working with Rich UI. you set the browser size that is appropriate for a specific kind of device such as a cell phone. select the radio button that reflects your current need. c. Specifically. if any. To display and edit the bidirectional text fields in visual mode (the way the text will be displayed). Select the Enable bidirectional support checkbox. Related concepts “Preferences” on page 172 EGL preferences affect the way the workbench displays and works with EGL. “Starting to work with EGL Rich UI” on page 329 This topic tells how to start developing applications with EGL Rich UI. select Enable visual data ordering. you provide initial values for the bidirectional settings assigned to widgets as they are dragged from the palette and dropped on the Design surface. We introduce that wizard in Overview of Rich UI generation and deployment. From the main menu. You can always perform these tasks. In the Runtime messages locale list box. 2. 3. For languages that read from right to left. For details on the use of locales. the other options are available. select the locale for the EGL runtime messages. 5. you assign values that determine what messages to use when you run Rich UI applications in the Preview tab of the Rich UI editor or in an external browser. Overview of EGL Rich UI 349 . select Enable right-to-left orientation. which are provided by the EGL Runtime and are distinct from the messages included in a properties file that you customize. “Enabling EGL capabilities” on page 11 Capabilities keep the workbench menus from becoming cluttered by hiding items you do not use. Related tasks “Setting preferences for Rich UI” on page 345 “Setting preferences for Rich UI bidirectional text” When you establish preferences for Rich UI bidirectional text. In the Rich UI handler locale list box. When you work in the Languages tab. you choose among locales that are listed in the Rich UI pane. select the locale for the messages included in a properties file. The Preferences dialog box is displayed. that you customize. Expand EGL and select Bidirectional text. Setting preferences for Rich UI bidirectional text When you establish preferences for Rich UI bidirectional text. you provide initial values for the bidirectional settings assigned to widgets as they are dragged from the palette and dropped on the Design surface. as described in Setting preferences for Rich UI. click Window → Preferences. “Setting preferences for Rich UI deployment” on page 351 Preferences guide the behavior of the Rich UI deployment wizard. You can set these preferences only if you previously enabled bidirectional text as follows: 1. The Bidirectional text page is displayed. 2. After this check box is selected. but to make them appear in the menus. 4. see Use of properties files for displayable text. Your tasks are as follows: 1.Languages tab In the Languages tab. you must enable the capability for that area of functionality. If the value is ″Yes″. and }. that is. Click Apply to save your changes and remain on the Preferences dialog box. or click Cancel to cancel the changes and exit the dialog box. click OK to save the changes and exit the dialog box. click Window → Preferences. left to right. Visual is appropriate for Arabic or Hebrew content derived from a machine that runs z/OS or IBM i. the displayed characters are ″BA″. The order of display is the order of input. From the main menu. To use Hindi numerals. Numeric Swapping Lets you use Hindi numerals in Arabic text. the widgets acts as a standard non-bidirectional widget v When you specify RTL. Reverse Text direction The setting indicates whether to reverse the text direction in the widget. >.Here are the steps for setting the Rich UI preferences: 1. The Preferences dialog box is displayed. <. and click on Bidirectional text. “Enabling EGL capabilities” on page 11 Capabilities keep the workbench menus from becoming cluttered by hiding 350 EGL Programmer’s Guide . the displayed characters are ″AB″. and { with >. and then Appearance. the text-typing orientation for input fields is right-to-left. The Bidirectional text page is displayed. the effect is to replace paired characters such as <. which is also the order in which the data is stored in local memory. set numericSwap and reverseTextDirection to Yes. 3. 2. scroll bars for dropdown lists appear on the left. click Restore Defaults. Alternatively. 5. If you want to return the settings on the Bidirectional text pane to the original product settings. Related tasks “Setting preferences for Rich UI” on page 345 “Setting preferences for Rich UI appearance” on page 347 “Setting preferences for Rich UI deployment” on page 351 Preferences guide the behavior of the Rich UI deployment wizard. Expand EGL. Symmetric Swapping This setting indicates whether to replace pairs of special characters and in this way to preserve the logical meaning of the presented text. v If the setting is Logical. Related concepts “Preferences” on page 172 EGL preferences affect the way the workbench displays and works with EGL. Establish the following settings: Widget Orientation The setting is either LTR (left-to-right) or RTL (right to left): v When you specify LTR. and the text is right-aligned Text Layout The setting is either Visual or Logical: v If the setting is Visual and the user types ″A″ and then ″B″ (and if ″A″ and ″B″ are characters in a bidirectional language). the widgets are mirrored. 4. [. In most cases. ]. We introduce that wizard in Overview of Rich UI generation and deployment. Rich UI. In the Prompts area. “Setting preferences for Rich UI appearance” on page 347 “Enabling EGL capabilities” on page 11 Capabilities keep the workbench menus from becoming cluttered by hiding items you do not use. Related concepts Overview of EGL Rich UI generation and deployment “Preferences” on page 172 EGL preferences affect the way the workbench displays and works with EGL. 5. 6. but to make them appear in the menus. the generation mode remains Development. Click Apply to save your changes and remain on the Preferences dialog box. but to make them appear in the menus. 4. Alternatively. Set the deployment preferences as follows: 1. Clearing the check box means that the deployment will proceed without a prompt. Expand EGL and Rich UI and then click Deployment. “Starting to work with EGL Rich UI” on page 329 This topic tells how to start developing applications with EGL Rich UI. “Starting to work with EGL Rich UI” on page 329 This topic tells how to start developing applications with EGL Rich UI. You can always perform these tasks. click Window → Preferences. The Preferences dialog box is displayed. 3. you must enable the capability for that area of functionality. Selecting the check box means that the wizard must prompt you to change the generation mode to Deployment. 2. as described in Setting preferences for Rich UI. indicate what is to occur when the generation mode is Development and you run the Rich UI deployment wizard. For details on the use of locales. click OK to save the changes and exit the dialog box. see Use of properties files for displayable text. If you want to return the settings on the Deployment page to the original product settings. you provide initial values for the bidirectional settings assigned to widgets as they are dragged from the palette and dropped on the Design surface. you select which locales are supported by default when you run the Rich UI deployment wizard.items you do not use. Setting preferences for Rich UI deployment Preferences guide the behavior of the Rich UI deployment wizard. We introduce that wizard in Overview of Rich UI generation and deployment. Related tasks “Setting preferences for Rich UI” on page 345 “Setting preferences for Rich UI bidirectional text” on page 349 When you establish preferences for Rich UI bidirectional text. In the Rich UI Application locales area. The Deployment page is displayed. You can always perform these tasks. or click Cancel to cancel the changes and exit the dialog box. Related reference Use of properties files for displayable text Overview of EGL Rich UI 351 . From the main menu. and no regeneration occurs. click Restore Defaults. All the locales that are available to you in the Rich UI Application locales area are listed in the Rich UI pane. you must enable the capability for that area of functionality. Typically. also consult the online documentation of your application server and other security documentation. Attackers know how to exploit the vulnerabilities of applications. interactive Web applications. All kinds of organizations have been victimized. Because security is a large and complex topic. When you apply security early in the development cycle.Securing a Rich UI application Implementing security is an integral part of Web application development that you should consider carefully when you design a Rich UI application. the security design should be determined early and integrated with the design of the application. such as IBM® WebSphere® Application Server or Apache 352 EGL Programmer’s Guide . the process can be easier and you can avoid problems that might be costly if found late in the cycle. Even if the JSF application was not originally secure. The best approach to avoid such problems is to eliminate weaknesses before they can be exploited. security is configured after a Rich UI application is deployed. This section contains considerations that are specific to securing the resources that are related to Rich UI applications. A Web container is synonymous to a JEE application server. Security is not available when you preview a Rich UI application from the EGL Rich UI editor. Related concepts “Overview of Rich UI security” “Authentication and Authorization” on page 353 “Confidentiality and Integrity” on page 355 “Resources to secure” on page 355 “JSF versus Rich UI applications” on page 357 “Using Web container-managed (JEE) authentication” on page 357 “Using application-managed (custom) authentication” on page 362 “Authentication summary” on page 367 “Authorization” on page 368 “Overview of SSL” on page 377 “Overview of EGL Rich UI” on page 327 Related tasks “Preventing client-side security threats” on page 376 Related reference “Sample login and error pages for JEE form-based authentication” on page 374 “JEE security example” on page 369 Overview of Rich UI security Security can be managed either by a Web container (the environment in which an application runs) or by the application itself.5. with results ranging from simple embarrassment to the public distribution of sensitive data. You might need to change the design of the application. however.1 presents security risks that must be mitigated. In the rush to unveil new dynamic. developers sometimes forgo adding security measures. It also provides a quick overview and examples of how to configure and use Java™ Enterprise Edition (JEE) authentication and Secure Sockets Layer (SSL). the introduction of the EGL Rich UI Proxy in V7. You should also evaluate JSF applications that are rewritten into Rich UI applications for security issues. is also known as custom security. Web container-managed security is also known as JEE or J2EE security. JEE security can also be programmatic because it includes some security-related APIs that can be called from within an application. Both kinds of security have advantages and drawbacks that you must understand before you implement them. Integrity Ensures that the data that flows between a sender and recipient was not modified in transit Related concepts “Securing a Rich UI application” on page 352 “Authentication and Authorization” “Confidentiality and Integrity” on page 355 Overview of service access Overview of EGL Rich UI generation and deployment Related reference Rich UI handler part Rich UI widgets Authentication and Authorization Authentication and authorization support can be provided by the following: v Web container-managed (JEE) security that is provided by application servers. Typically. authentication occurs by providing a user id and password in a login screen. You can choose to use either declarative or programmatic security. confidentiality. the application code contains explicit security calls.Tomcat. Consider using JEE security to protect your Rich UI application in the following cases: v The entire Rich UI application needs to be secured. Major components of security include authentication. Application-managed (custom) security is programmatic because security is handled completely from within the application. Authorization The process of determining whether a user has permission to access a particular resource Confidentiality Guarantees that the data that is passed between a sender and recipient is protected from eavesdroppers. application-managed security. Overview of EGL Rich UI 353 . Web container-managed (JEE) security is declarative because security constraints are defined in deployment descriptors or configuration files. and integrity: Authentication The method by which the identity of a user is verified. v Application-managed (custom) security that is written in the application. Security that is written by the developer of the application. such as WebSphere Application Server or Apache Tomcat. With programmatic security. In declarative security. security policies are defined outside of the application in deployment descriptors or configuration files so the application is security-unaware. authorization. Declarative authorization is available because security information is specified in deployment descriptors. you can use a customized login screen with the look and feel of the application instead of the browser-provided login dialog. Rich UI applications should perform authorization either declaratively or through custom. such as Lightweight Directory Access Protocol (LDAP) directory servers or relational databases used with JEE security. password. see ″EGL single sign-on. such as isUserInRole().″. For example. v You do not want to write security-related code in your application. such as adding a new user to the repository. Web container-managed (JEE) security Web container-managed security transfers the responsibility of user authentication and authorization to the container. JEE security uses roles to manage access to resources. it is not available from the Workbench. 354 EGL Programmer’s Guide . The client resends the request to the server. The application servers access these deployment descriptors to determine if a specific user is assigned to a role and decides whether a particular resource can be accessed by that role. v You want to access the user id. requests a Web page from a server without providing a user id and password. Therefore. allowing the EGL developer to focus on business logic. In JEE form-based authentication. Consider using custom security to protect your Rich UI application in the following cases: v Access to some or all of your Rich UI application needs to be restricted. The user id and password are passed to the server in the form data instead of in the HTTP header of the request. JEE authorization can be declarative or programmatic. You need to deploy a Rich UI application to WebSphere or Tomcat to apply and test security. the server returns a 401 response code and the client prompts the user again. the user bob might be mapped to the role administrator. If the user is authenticated. these functions are not available from within a Rich UI application. If the user id and password are invalid. user-provided code. or both from within the application. Users and groups are mapped to appropriate roles. In JEE basic authentication (also known as HTTP basic authentication). User registries. The client then prompts the user for a user id and password by displaying a default login dialog to the user. when a client. For more details. v You want to combine the authentication of your Rich UI application with the authentication of other resources that the application uses in a process called EGL single sign-on. A system administrator must perform administrative tasks. are external to the JEE environment. While JEE security also includes programmatic authorization through the use of APIs.v You do not need to access security-related information from within the Rich UI application. While JEE security is available through WebSphere Application Server and Apache Tomcat. such as a browser. Certain roles are allowed access to certain resources. the server returns the requested page. the server sends back a 401 response code. Two common types of JEE authentication are basic and form-based. including the user id and password in the HTTP header. It is important that you authenticate over SSL. you can combine both forms of security. see ″Overview of SSL. If an HTML file is secure. For more information about SSL. If you prefer. JEE basic. which allows a server to confirm the identity of a client. which allows a client to confirm the identity of a server. whether you use JEE form-based. you must authenticate before you access the Rich UI application that is defined in the HTML file. review the documentation in this chapter and the more detailed online documentation for your application server.″ Related concepts “Overview of Rich UI security” on page 352 “Authentication and Authorization” on page 353 Resources to secure When you determine which resources to secure. You might want to use custom security to authenticate users before they can access restricted parts of your application. and client authentication. SSL also includes server authentication. HTML files are generated into the WebContent folder (or into a subfolder in the WebContent folder) of your deployed project. Related concepts “Overview of Rich UI security” on page 352 “Confidentiality and Integrity” “Authentication summary” on page 367 Related tasks “Using Web container-managed (JEE) authentication” on page 357 “Using application-managed (custom) authentication” on page 362 Confidentiality and Integrity Although you can use JEE security to secure Web resources from unauthenticated or unauthorized users. To secure the entire HTML file. you cannot avoid it if JEE security alone is not sufficient to express the security model of an application. Custom authorization can provide a more granular level of authorization than JEE roles. Application-managed (custom) security If Web container-managed security is not suitable for your needs. you can use custom security. Overview of EGL Rich UI 355 . and provides confidentiality through encryption. you can use Secure Sockets Layer (SSL). SSL guarantees data integrity. For these purposes. you can use JEE authentication. Although custom security requires that you add security-related code to your Rich UI application.To determine if JEE security is appropriate for your situation. or custom authentication. review all of the components that have a URL mapping and that your Rich UI application accesses: Generated HTML file EGL generates a Rich UI application into an HTML file. ensures that messages between a client and server are not tampered with or modified. you can build custom security into your Rich UI application. JEE security cannot prevent the data that flows between a client and server from being intercepted or read. To restrict sensitive areas of the Rich UI application. While the HTML file runs in a browser. authentication is required only before you can access the HTML file.EGL Rich UI Proxy The EGL Rich UI Proxy handles communication between the HTML file that EGL generates for a Rich UI application and Web services Because of the Same Origin policy for JavaScript™. the Rich UI application should display a user-defined login screen to prompt the user for the values to pass to setHTTPBasicAuthentication. Because the URL of the EGL Rich UI Proxy is visible in the JavaScript that EGL generates for your Rich UI application. Whenever you need a different set of credentials to pass to a Web service. Instead.javart. you can store it in your Rich UI handler or a library for future Web service calls.jar. All Web services that are invoked in a Rich UI application are accessed through the proxy. If both the HTML file and EGL Rich UI Proxy are secure. it can reduce the possibility of one occurring. the HTML file uses a Java servlet known as the EGL Rich UI Proxy. Related concepts “Overview of Rich UI security” on page 352 “Authentication and Authorization” on page 353 “Confidentiality and Integrity” on page 355 356 EGL Programmer’s Guide . if the application invokes no Web services). you access secure Web services by passing a valid user id and password in the HTTP header. it can be used to instigate JavaScript hijacking attacks. the EGL Rich UI Proxy runs on an application server. the HTML file cannot invoke a Web service that has a different origin (defined as protocol. In HTTP basic authentication. see Removing access to the EGL Rich UI Proxy servlet. and port) than that of the HTML file. To get to Web services on different origins.RestServiceServlet and is shipped with the EGL runtime in fda7. The servlet is deployed to the same project as your generated HTML file. If your Rich UI application does not use the EGL Rich UI Proxy (that is. before the application calls a Web service that is invoked through the proxy). domain. Otherwise. which sets these values in the header. While this action cannot guarantee protection against Web threats. The EGL Rich UI Proxy servlet is of the type com. To avoid security exposures. you must prompt the user again.services. setHTTPBasicAuthentication. authentication is required before you can access the proxy (that is. If you leave the proxy unsecured. EGL Web service To secure EGL Web services that are generated into a Web project. you must prevent the proxy from being used by anyone other than your Rich UI client to invoke Web services. you can use JEE basic authentication to prevent the proxy from being invoked by an unauthenticated client. you can use JEE security through HTTP basic authentication. never hardcode the user id and password into the Rich UI application. Once you obtain the password. Precede each call to a secure Web service with a call to setHTTPBasicAuthentication. remove access to the proxy from your deployed project.ibm. If the EGL Rich UI Proxy is secure and the HTML file is not. EGL provides a system function in ServiceLib. For more information. you cannot use JEE authentication. which Rich UI applications use to call Web services. is not needed by JSF applications because JSF handlers are generated into Java instead of JavaScript. You can use these repositories to store user ids. Each JSP is generated into its own file and has its own URL. Instead. JEE security that is provided by WebSphere Application Server or Apache Tomcat. passwords. such as the HTML file generated for your Rich UI application. the EGL Rich UI Proxy. Depending on your choices. such as the local OS registry. not in a Web browser. you must generate those services into Java because Web services run on an application server. and other security information. In JEE authentication. After resources. Application servers support various types of repositories. you can secure the resources in your deployed project from unauthenticated users by using the Web container-based. EGL generates the contents of all the Rich UI handlers in an application into JavaScript in a single HTML file. If your Rich UI application calls EGL Web services. For JSF applications. You should understand these ramifications because they can affect the type of security you choose to implement. which might need to be secured from unauthenticated users using JEE security. If you want to make some of the areas of your Rich UI application public. users will have to authenticate before they can access those resources. For Rich UI applications. use custom security to prompt users to log in before they can access the restricted parts of your application. and custom directories such as relational databases and flat files. a system administrator performs administration tasks. Every action that the Web container or JRE takes on behalf of the user is done only if the user belongs to a set of roles that have permission to take that action. such as adding or deleting user data from a repository. LDAP directories. you can keep some JSPs in your JSF application public and restrict other JSPs to authenticated users. and Web services. or realms. If you choose to secure a URL with JEE security. To secure the entire Rich UI application. The JSF handler and EGL parts it references are generated into Java. Overview of EGL Rich UI 357 . you can choose to include some or all of the JSPs in your JSF application. The user is only requested to authenticate once even if multiple resources are secured. you can use JEE security. When securing URLs. Related concepts “Using Web container-managed (JEE) authentication” “Using application-managed (custom) authentication” on page 362 Using Web container-managed (JEE) authentication After you deploy a Rich UI application.JSF versus Rich UI applications Differences exist between generated and deployed JSF applications and Rich UI applications. users will be prompted to authenticate before they can access any part of your Rich UI application. The HTML file that EGL generates for a Rich UI application is associated with a single URL that can be secured with JEE security. independently of the applications that access the repository. Another major difference between JSF and Rich UI applications is that the EGL Rich UI Proxy. each JSF handler is associated with a Faces JSP. are secured with JEE security. In V7. and getAuthenticationType()) are not available from Rich UI handlers. Security information. use SSL in conjunction with these types of authentication.5. Related concepts “Overview of Rich UI security” on page 352 “Securing a Rich UI application” on page 352 Related tasks “Defining URL patterns for Rich UI resources” “Securing the HTML file by using form-based authentication” on page 359 “Securing the EGL Rich UI Proxy by using basic authentication” on page 359 “Removing access to the EGL Rich UI Proxy servlet” on page 360 “Securing EGL Web services by using basic authentication” on page 361 Defining URL patterns for Rich UI resources Security constraints define how the content of a Web project is protected. the password is encoded using the Base64 encoding scheme. EGL Rich UI Proxy.1. In both JEE basic and form-based authentication. isUserInRole().xml and application. To ensure that the password is not compromised. a format that is easy to decode. see ″Overview of SSL. specify /* as the URL pattern. The J2EELib system functions that are available for programmatic security from JSF handlers (getRemoteUser().xml. such as roles and constraints. Specifying /* as your URL pattern secures your HTML page. . and SOAP and REST services. The following sections contain information on how to secure the various components of a Rich UI application: v Securing the HTML file by using form-based authentication v Securing the EGL Rich UI Proxy by using basic authentication v Securing EGL Web services by using basic authentication Those sections also refer to URL patterns. access to resources is granted to roles.In JEE role-based security. are defined declaratively.xml) of your deployed project. To secure all the resources that are in the WebContent folder of a deployed project. you must use declarative JEE security with Rich UI applications. see WebSphere Application Server or Apache Tomcat documentation.″ For more details on Web container-managed authentication. specify the URLs of the resources to secure. which are then mapped to actual user registry entries. in the security constraints in the deployment descriptor (web. To use JEE security to protect a resource. in deployment descriptors such as web. For an introduction to SSL. Related concepts “Overview of Rich UI security” on page 352 “Securing a Rich UI application” on page 352 “Using Web container-managed (JEE) authentication” on page 357 Related tasks “Securing the HTML file by using form-based authentication” on page 359 “Securing the EGL Rich UI Proxy by using basic authentication” on page 359 “Removing access to the EGL Rich UI Proxy servlet” on page 360 358 EGL Programmer’s Guide . or outside of the application. such as displaying specific error messages. which can be easily decoded.″ To secure the HTML file that EGL generates for a Rich UI application named RSSReader. By using JEE basic authentication. the Web server uses a browser-provided dialog to collect a user id and password. specify a URL pattern of /___proxy (three underscores). When you use form-based authentication to secure the HTML file. This dialog looks like the following dialog for Mozilla® Firefox® V2. By specifying this pattern. see ″Sample login and error pages for JEE form-based authentication. in a security constraint in your web. users will gain access to the EGL Rich UI Proxy as well as the HTML file.0: Overview of EGL Rich UI 359 .xml. Users cannot access any part of the Rich UI application until they authenticate. specify a URL pattern of /RSSReader. Require users to authenticate to the proxy before it can be used to process Web service calls. you prevent unauthenticated users from accessing the proxy. If you require users to authenticate. The encoding scheme for the password is Base64 encoding. To secure the EGL Rich UI Proxy.html is in a subdirectory of WebContent named Secured. you prevent unauthenticated clients from accessing the proxy for illegal purposes.html. After logging in. include the EGL Rich UI Proxy in the security constraint.html. specify a URL pattern of /Secured/RSSReader. error handling. To secure the EGL Rich UI Proxy. If an authentication error occurs.“Securing EGL Web services by using basic authentication” on page 361 Securing the HTML file by using form-based authentication To secure your Rich UI application. use SSL connections with form-based authentication. To ensure password confidentiality. If RSSReader. an error page is returned with the status code of the response set to 401. For sample login and error pages that you can use with form-based authentication. you can use JEE form-based authentication (the most popular Web authentication method in use) for which you to supply your own customized login page that contains a user id and password. specify a URL pattern of /___proxy (three underscores). Related concepts “Overview of Rich UI security” on page 352 “Securing a Rich UI application” on page 352 “Using Web container-managed (JEE) authentication” on page 357 Related tasks “Defining URL patterns for Rich UI resources” on page 358 “Securing the EGL Rich UI Proxy by using basic authentication” “Removing access to the EGL Rich UI Proxy servlet” on page 360 “Securing EGL Web services by using basic authentication” on page 361 Securing the EGL Rich UI Proxy by using basic authentication Use JEE basic authentication to secure the EGL Rich UI Proxy. is difficult to implement. When you use form-based authentication. Use JEE basic authentication to secure the proxy. If you want to protect sensitive parts of your application without securing the entire Rich UI application. This response code is presented to the user on an error page with a generic error message. bypassing the browser-provided dialog. To prevent the user from seeing the browser-provided dialog. you can use custom security. including the EGL Rich UI Proxy. they can also access the proxy.xml of your deployed project so a third party cannot access it. the EGL Rich UI Proxy will not be used. After users authenticate. Leave the proxy unsecured. 360 EGL Programmer’s Guide . You can combine authentication for custom security with JEE authentication of the EGL Rich UI Proxy in a process called EGL single sign-on. The HTTP standard requires that when login fails. the login page that is specified for form-based authentication is displayed. the server returns a response code of 401. Related concepts “EGL single sign-on” on page 362 “Overview of Rich UI security” on page 352 “Securing a Rich UI application” on page 352 “Using Web container-managed (JEE) authentication” on page 357 Related tasks “Defining URL patterns for Rich UI resources” on page 358 “Securing the HTML file by using form-based authentication” on page 359 “Removing access to the EGL Rich UI Proxy servlet” “Securing EGL Web services by using basic authentication” on page 361 Removing access to the EGL Rich UI Proxy servlet If your Rich UI application does not call Web SOAP or REST services. The dialog is redisplayed until a valid user id and password are entered. you cannot customize the dialog to look like the rest of your Rich UI application.If you use this login dialog. 3. Remove the EGL Rich UI Proxy servlet from the web. you have three options: 1. you use a user-defined login screen to capture credentials that allow the end user to authenticate to more than one resource. If you use JEE security to protect both the HTML file and EGL Rich UI Proxy. In EGL single sign-on. In this case. When a user requests the HTML file. use EGL single sign-on. use form-based authentication. 2. xml. If you choose Option 3. specify ″BASIC″ as your authentication type. If you are only securing services in your project. Related concepts “Overview of Rich UI security” on page 352 “Securing a Rich UI application” on page 352 “Using Web container-managed (JEE) authentication” on page 357 Related tasks Overview of EGL Rich UI 361 . To secure a specific function in a SOAP service. specify a URL pattern of /restservices/*. 5. select /___proxy->EGLRichUIProxy. You can replace the asterisk with a specific name to secure a specific SOAP service. 4. click EGLRichUIProxy. Save your changes and exit the Deployment Descriptor Editor. In the URL Mappings pane. as in /restservices/accountService/checkBalance. Double-click on the deployment descriptor (WebContent/WEB-INF/web. To secure all EGL SOAP services in a Web project. To secure a specific function in a REST service. edit the web. see JEE security example.Option 1 is the best option for EGL. For directions on how to use JEE basic authentication to secure the EGL Riche UI Proxy. 6. It is simple and removes all security risks that are related to the proxy. 3. Click the Servlets tab. To secure all EGL REST services in a Web project. To remove access to the EGL Rich UI Proxy: 1.xml and add a servlet URL mapping into EGLRichUIProxy by using the URL pattern /___proxy. you leave the EGL Rich UI Proxy vulnerable to security threats. in a security constraint in the web.xml) of your deployed Web project to open it with the Deployment Descriptor Editor. Click Remove. as in /services/ accountService/checkBalance.xml. In the Servlets and JSPs pane. You can replace the asterisk with a specific name to secure a specific REST service. 2. Option 2 is valid. as described in EGL Rich UI Proxy. specify the service and function name. but it requires more work from the EGL developer or a security administrator. specify a URL pattern of /services/*. If you want to invoke Web services from your Rich UI application later. Related concepts “Overview of Rich UI security” on page 352 “Securing a Rich UI application” on page 352 “Using Web container-managed (JEE) authentication” on page 357 Related tasks “Defining “Securing “Securing “Securing URL patterns for Rich UI resources” on page 358 the HTML file by using form-based authentication” on page 359 the EGL Rich UI Proxy by using basic authentication” on page 359 EGL Web services by using basic authentication” Securing EGL Web services by using basic authentication You can use JEE security and basic authentication to secure EGL Web services that are generated into an EGL Web project. in a security constraint in the web. specify the service and function name. “Defining URL patterns for Rich UI resources” on page 358 “Securing the HTML file by using form-based authentication” on page 359 “Securing the EGL Rich UI Proxy by using basic authentication” on page 359 “Removing access to the EGL Rich UI Proxy servlet” on page 360 Using application-managed (custom) authentication If you do not want to use JEE authentication to secure your HTML file. use the PasswordTextField widget in your Rich UI handler. You can integrate this form of security into the rest of the application. your Rich UI application must include a user-defined login screen. the Rich UI application must define a login screen that contains a user ID field. which parts can be accessed only after logging in with a valid user id and password). width = 80 }. and Web services do not need to be the same. password field. 362 EGL Programmer’s Guide . use SSL to ensure that the user id and password are secure during transmission between the browser and server. as in the following example: useridLabel TextLabel { text = "User ID:". Although the user registries that you use for authentication to the application. see Overview of SSL. Even if you are not using JEE security protect to the HTML file. and command button. A design that uses EGL single sign-on will reduce the number of times a user will have to authenticate. This is an important factor to remember when you design your Rich UI application. You must still use JEE security to protect the EGL Rich UI Proxy and Web services. For EGL single sign-on. useridField TextField { width = 100 }. To hide the password as it is being typed. you can combine the following aspects of security into a single step: authentication to your application (protected by custom security) and authentication to the EGL Rich UI Proxy (protected by JEE security). Related concepts “EGL single sign-on” “Accessing user repositories” on page 364 “Adding a new user to a repository” on page 366 “Authentication summary” on page 367 EGL single sign-on Combining application and proxy authentication By using EGL single sign-on. When you use custom security. margin = 3 }. The first step in defining custom security is to determine which parts of the application should be secured (that is. you can incorporate custom security into your Rich UI application. use JEE security to secure the EGL Rich UI Proxy. useridField ]. When authenticating with custom security. Your Rich UI application can require authentication to occur either at the beginning of the application or before accessing a restricted area. For an introduction to SSL. useridBox Box { children = [ useridLabel. EGL Rich UI Proxy. You can also include authentication to Web services. the user ID and password used during EGL single sign-on must exist in all the relevant user registries to prevent an authentication error. The authenticate function for the EGL code above might look like the following example: function authenticate( e Event in ) ServiceLib. passwordField ]. To implement EGL single sign-on. authentication to the proxy occurs before authentication to your application. However.text.passwordField. passwordField. Because the Web container steps in.setHTTPBasicAuthentication() system function before you call the secure Web service and pass it the user ID and password used for EGL single sign-on. handles login failures. columns = 1.setHTTPBasicAuthentication(srvc. the Web container. end Adding Web service authentication Typically. a request is sent to the EGL Rich UI Proxy. a browser-provided login screen that is similar to the example in ″Using basic authentication to secure the EGL Rich UI Proxy″ will be displayed the first time a Web service is invoked. a Rich UI application must prompt the user for a user ID and password.setProxyBasicAuthentication(useridField. a user must log in before accessing it. button Button { text = "Log in". width = 80 }. width = 200 }. Before you call the service to log in to the application.text ) returning to loginCallback onException loginException.text ) returning to withdrawCallback onException withdrawException. If a user has not logged in yet. Because the proxy is secured with JEE basic authentication.setProxyBasicAuthentication() system function to pass the user ID and password to authenticate to the proxy. onClick ::= authenticate }. useridField. passwordBox.text ). use the ServiceLib.text. passwordBox Box { children = [ passwordLabel. srvc LDAPLoginService{ @bindService }. With EGL single sign-on. Therefore. Whenever a Web service is called. margin = 3}. you can pass the user ID and password that you use for EGL single sign-on to a secure Web service.login( useridField. invoke this system function.text. For EGL single sign-on to work. when the user authenticates to the Rich UI application using the user-defined login screen above. design the Rich UI application so that the Web service for authentication to the application is invoked before any other Web service. Overview of EGL Rich UI 363 . invoke the ServiceLib. passwordField PasswordTextField { width = 100 }. children = [ useridBox. not the application. passwordField. To do so. ui Box { background = "blue". Because the EGL Rich UI Proxy is secured using JEE basic authentication. call srvc.text. end Handling authentication errors If you use EGL single sign-on to authenticate to your application and to the EGL Rich UI Proxy. call srvc. passwordField. function withdraw( e Event in ) ServiceLib.withdraw( useridField. to authenticate to a secure Web service. button ]. Doing so bypasses the browser-provided login dialog. srvc BankingService{ @bindService }.passwordLabel TextLabel { text = "Password:". authenticating to the application is combined with authentication to the proxy in one step. you can no longer authenticate in a single step.text ). EGL passes those credentials (user ID and password) to JEE security to use to authenticate to the proxy also. setHTTPBasicAuthentication() to set a valid user ID and password in the HTTP header before consuming the Web service. relational databases. If an error occurs when users authenticate to a Web service that is secured with HTTP basic authentication. the user id and password that the end user enters in the login screen must exist in each of the various repositories. a browser-provided login dialog is displayed so that they can try to authenticate again.core. such as LDAP directories. control falls into the exception handler that is specified on the call statement. The following example shows the specifics of this kind of error: Web service authentication error Configuration A Web service is secured using JEE basic authentication. detail2 is set to ″Unauthorized″. the user must authenticate to the EGL Rich UI Proxy first. Error A ServiceInvocationException is thrown with message ID ″EGL1539E″ and message. your Rich UI application must handle the error. detail3 is set to ″Server returned HTTP response code: 401 for URL: {0}″. and log in to the application. The application should direct users to re-enter a valid user ID and password in the user-defined login screen and to click the ″Login″ button again. When the Web service returns. Related concepts “Accessing user repositories” “Adding a new user to a repository” on page 366 “Authentication summary” on page 367 Accessing user repositories You can use various types of repositories.ServiceInvocationException″. If both EGL Rich UI Proxy and Web service authentication are successful but an error occurs when you try to authenticate to your application. and flat files with either JEE or custom security. ″name″: ″egl. and Web services. After users enter valid credentials for the EGL Rich UI Proxy. In JEE basic authentication. 364 EGL Programmer’s Guide . URL: {0}″ is issued where {0} is the URL of the Web service. Web services. they must authenticate to the application. Problem A valid user ID and password for the Web service are not found in the HTTP header.At this point. You can use EGL single-sign on to access different repositories to authenticate to the application. or both afterward. Web services. The application cannot access the password that a user enters on this dialog. control passes to the callback or ″returning to″ function that is specified on your call statement. detail1 of the ServiceInvocationException is set to ″401″. or both. proxy. the Web container prompts the browser to display this dialog until the user logs in successfully. For single-sign on to succeed. ″An exception occurred while communicating with the service. If users enter an invalid password for EGL Rich UI Proxy authentication on the login screen. Your Rich UI application must detect this error and present appropriate instructions to the user to reauthenticate. Solution Call ServiceLib. naming.initial".put( "java. PackageName = "javax.2/docs/guide/jndi/jndi-ldap. null ). // Set LDAP-specific properties. "3" ).put( "java.ldap. PackageName = "javax. end externalType InitialLdapContext extends InitialDirContext type JavaObject { JavaName = "InitialLdapContext".security. mods ModificationItemArray in ).security.protocol". "com. "ldap://localhost:389/o=sample" ). configure the application server to connect to the LDAP directory server.sun. null ). To use EGL code to access an LDAP directory.put( "java. Before you access an LDAP directory for JEE authentication.xml file.naming.naming. specify this information in the Administrative Console.url".4. specify this information in the \conf\server.LdapCtxFactory" ). hashtable. hashtable. hashtable.ldap" } constructor( environment Hashtable in.authentication".put( "java.ldap.naming. // Set JNDI environment properties. // Properties can be found at // http://java. // userid and password are passed in as strings.security.factory.naming. connCtls ControlArray in ). For WebSphere Application Server.version".naming. Overview of EGL Rich UI 365 . "simple" ). end externalType ModificationItemArray extends Object type JavaObject { JavaName = "ModificationItem[]".directory" } end // Instantiate a hashtable for binding criteria.naming. for Apache Tomcat. "uid=" + userid + ".html.naming. ctx InitialLdapContext = new InitialLdapContext( hashtable. PackageName = "javax.ou=people. "follow" ). Here is an example of EGL code that establishes a connection to an LDAP directory server: // External types needed to access an LDAP directory server.security.put( "java.principal".naming.put( "java. You can also use EGL code that is generated into Java and running on a server to access an LDAP directory.put( "java. hashtable.sun. password ).directory" } function modifyAttributes( name String in.referral". The service can use EGL external types that map to JNDI LDAP Java classes to access an LDAP directory. hashtable Hashtable = new Hashtable().ldap" } end externalType InitialDirContext type JavaObject { JavaName = "InitialDirContext". hashtable.The most popular type of repository is a Lightweight Directory Access Protocol (LDAP) directory.o=sample").com/j2se/1. hashtable. which is a specialized database that is optimized for read access and that organizes its data in a tree structure.naming.naming. hashtable.credentials".provider.naming. // Connect to the LDAP directory server.put( "java. define either an EGL REST or SOAP service. PackageName = "javax. externalType ControlArray type JavaObject { JavaName = "Control[]". // Hashtable is already defined within EGL. hashtable.jndi. the Rich UI handler can use a hyperlink widget that is similar to the following example: registerLink Hyperlink = new Hyperlink { target = "_blank". Therefore. In this case. Note that the tighter your user registry is controlled.if ( ctx != null ) // Retrieve data . when you require new users to go through a system administrator. If you use JEE security to secure the proxy. the JSF page can invoke a JavaScript ″window. if the repository is mainly a way to keep a log of users and new users constantly request access. Related concepts 366 EGL Programmer’s Guide . if the user must be a company employee or must possess a bank account to access a Web site. If you must add new users to a repository with your Rich UI application. you can use a JSF application to add a new user to the repository. If you use a Web service to write the code to add a new user. a system administrator likely wants to tightly control access to the repository. you can use a Web service to add a new user only if the proxy is not protected by JEE security. If the proxy is secure. it might be inconvenient or impractical to go through a system administrator. To link to a JSF application in a new window to update the repository. including code that retrieves and modifies data in an LDAP directory. Therefore. Although securing your EGL Rich UI Proxy with JEE security prevents unauthenticated users from accessing the proxy. end For more sample EGL code.. the tighter the security will be of your Rich UI application and EGL Rich UI Proxy. The method that you choose depends largely on the level of security that you need.close″.. it does not prevent malicious authenticated users from using the proxy to inflict damage. href = "http://localhost:9080/LDAPSample/ldapLogin. the EGL Rich UI Proxy will be more secure than if you allow the application to add new entries to the user registry.faces". text = "Click here to register" }. a new user cannot access it. You can write the code as either a Web service or a JSF application. On the other hand. For example. you have two options to give new users permission to access the secure areas: a system or security administrator can add a new user to the repository or the Rich UI application can contain code to add a new user to the repository. see ″EGL LDAP Access″ or ″J2EE Security with EGL LDAP Access″ in the IBM Rational® Business Developer documentation (in the ″Contents″ under ″Samples″). an application might add new users to the repository. Related concepts “EGL single sign-on” on page 362 “Adding a new user to a repository” “Authentication summary” on page 367 Adding a new user to a repository If your Rich UI application requires security. This code must run on an application server. To close the window after authentication completes. the EGL Rich UI Proxy has to invoke the code. you can write EGL code to add the users. Overview of EGL Rich UI 367 . use JEE security. Securing data is vital to keeping your passwords from being compromised. If your entire Rich UI application needs to be secured and you do not need to access security credentials from within the application. If possible. Secure the proxy with JEE authentication (scenario 6). the proxy is still publicly accessible. Use SSL. Otherwise.setHTTPBasicAuthentication system function. 3. Otherwise. to secure data transmitted to and from your Rich UI application. 2. include the URL pattern of the proxy in your security constraint. For each of the eight scenarios (columns). If your application requires custom security or calls secure Web services. consider using EGL single sign-on to eliminate the need for a user to log in more than once. an ″X″ represents a secure resource. the proxy is publicly accessible. If possible. Secure the proxy with JEE authentication (scenario 5). remove access to the EGL Rich UI Proxy by deleting its URL mapping from the deployment descriptor. do not implement this scenario. Authentication scenario 1 HTML file EGL Rich UI Proxy Web service 2 x x 3* 4 5* x x x 6* 7 x 8* x x x x x x Scenario descriptions 1. do not implement this scenario. If you use JEE form-based authentication for your HTML file.“EGL single sign-on” on page 362 “Accessing user repositories” on page 364 “Authentication summary” Authentication summary During the design phase of your Rich UI application. do not implement this scenario. Secure the proxy with JEE basic authentication (scenario 3). In this scenario. consider using JEE authentication. The safer scenarios are identified with an ″*″. In this scenario. These scenarios assume that the HTML file is calling Web services. Table 53. In this scenario. use JEE basic authentication to secure the proxy. This scenario is safer than the first two. 4. To secure the EGL Rich UI Proxy. If possible. you might need to implement custom security. the proxy is secured with JEE basic authentication. You can secure Web services using by JEE basic authentication and set a user id and password in the HTTP header before invoking them by using the ServiceLib. determine the type of security that you need and integrate that security with the rest of your application. the proxy is publicly accessible. The following table summarizes the combinations of resources that you can secure with JEE or custom authentication. described in Overview of SSL. Otherwise. Although the HTML file is secured with either JEE or custom security. do not implement this scenario. One way to implement authorization is to organize user entries into groups in a repository like an LDAP directory. roles are bound to users and groups in the application. LDAP directory. If possible. Thus.getRemoteUser EGL system functions. and Web services match.5. a user-defined login screen is required to obtain Web service credentials. For Apache Tomcat. this scenario can be safe. For details concerning authorization. Actual users and groups who are mapped to that logical role can access those resources. use form-based authentication.xml file. consider securing the HTML file with custom authentication. A logical security role has permission to access certain resources. the proxy is publicly accessible. Related concepts “Securing a Rich UI application” on page 352 “Overview of Rich UI security” on page 352 Authorization You can perform authorization through JEE security or through the application itself. In this scenario.1 because the JEE security that is used from a Rich UI application must be declarative. 6. Although you can check authorization in a JSF application by calling the J2EELib. The web. the proxy. the user must log in twice. 7. or relational database. use EGL single sign-on to combine application authentication with JEE authentication to the proxy. 368 EGL Programmer’s Guide . perhaps because programmatic security is unavailable or the overhead of administering JEE security roles is too high. use EGL single sign-on to combine Web service authentication with JEE basic authentication to the proxy. A user-defined login screen is required in the application to authenticate to the secure Web services. Secure the proxy with JEE authentication (scenario 8). If the credentials to authenticate to the HTML file. Apache Tomcat. If JEE authorization is not suitable for your Rich UI application.xml deployment descriptor specifies the type of access that is granted to each role. For WebSphere Application Server. If the HTML file is secured with custom security and the credentials to log in to the HTML file match those used to log in to the proxy. the binding occurs in a repository such as the tomcat-users. see your WebSphere Application Server. You can then invoke a Web service from your Rich UI application to retrieve an entry from the repository and check if a user is in a group that has access a certain resource.5. If Web service does not require security. Although the Rich UI application does not require authentication.xml. If the credentials that are used to log in to the Web service match those that are used to log in to the proxy. which should never be hardcoded into the application.isUserInRole and J2EELib. JEE security uses roles to manage access to resources. or LDAP directory server documentation. these system functions are not available from a Rich UI application in V7. Then use EGL single sign-on to capture credentials for all three types of resources. use form-based authentication to require the user to log in only once. authorization can be accomplished using your own application code. 8. If both the HTML file and proxy are secured with JEE security. If both the HTML file and proxy are secured with JEE security. xml in the Deployment Descriptor Editor.xml: v Security roles v Security constraints v Authentication method From the Project Explorer in the EGL Rich UI perspective.xml.Related information “Overview of Rich UI security” on page 352 “Authentication and Authorization” on page 353 “Confidentiality and Integrity” on page 355 “Resources to secure” on page 355 JEE security example The following example shows how to use JEE basic authentication to secure an EGL Rich UI Proxy in a Web project to which a Rich UI application has been deployed.xml. v By editing the web.xml for WebSphere” on page 371 “Enabling security by using the Administrative Console for WebSphere” on page 372 “Binding roles to users and groups in tomcat-users.xml” on page 373 Specifying security criteria in web. In the application. In tomcat-users. specify security criteria 2. In the web. In the web. perform the following steps: 1. specify security criteria 3. specify security criteria 2. Using the Security Editor You can use the Security Editor to define the following things in web. open the Security Editor by double-clicking on the Security Editor icon of your deployed project. Enable security in the server configuration For Apache Tomcat.xml” “Specifying security criteria in application. Overview of EGL Rich UI 369 . perform the following steps: 1.xml) in two ways: v By using the Security Editor.xml.xml. Use the Administrative Console to enable security 4. bind roles to users and groups Related concepts “Overview of Rich UI security” on page 352 “Authentication and Authorization” on page 353 “Confidentiality and Integrity” on page 355 Related tasks “Specifying security criteria in web. The Security Editor is used in this example because it provides an easy way to specify and view security criteria.xml You can specify security criteria in the deployment descriptor of your deployed project (web. For WebSphere Application Server. In the Resources pane. type user as the role name and click Add. preventing tampering of messages in transit between a client and server. v Click Finish. Roles are mapped to actual user registry entries. define a security constraint. click BASIC. click OK. you must specify the user data constraint directly into the web. For the authentication method. INTEGRAL. To secure the proxy and allow anyone in the user role to access the proxy. To see the security constraints. 3. If you use a value of INTEGRAL or CONFIDENTIAL. TRACE. right click on /___proxy (user) and click Assign Roles.xml because that information is not available from the Security Editor. 4. select user and click Advanced>>>. Save your changes and close the Security Editor. In the Select Roles window. A CONFIDENTIAL setting guarantees confidentiality. expand the folder with your project name. open the deployment descriptor of your deployed project by double-clicking on the deployment descriptor. you should see /___proxy. You can set a user data constraint to a value of NONE. which specifies how you can access the /___proxy secure resource. Defining a user data constraint A user data constraint specifies how data is protected while it is in transit between a client and server. DELETE. The userConstraint security constraint contains the default HTTP method access (GET. 370 EGL Programmer’s Guide . OPTIONS). If you do not want to use the default user data constraint (NONE). Click OK. users must be assigned roles to access resources. type Sample registry. To name the example. Defining security constraints To specify the resources that are protected and the roles that have access to the resources. 1. HEAD. Click OK. An INTEGRAL value guarantees content integrity. EGLRichUIProxy. 5. 2. Click Authentication. v Select the Security tab. PUT. or CONFIDENTIAL. in the Resources pane. in the Security Editor. To specify a user data constraint in the web. POST. preventing reading of data by others during the transfer. v In the Add Roles window. click Security Preferences.xml: v From the EGL Rich UI perspective. To change the defaults for your security constraints. You should see the userConstraint security constraint that is mapped to user. drag the user role from the Security Roles pane to /___proxy in the Resources pane. 3. 2. v In the Create a Security Role dialog. Selecting an authentication method To specify an authentication method: 1. Under Servlet Mappings. and Servlet Mappings.Defining security roles In JEE role-based security. Servlets. requests must be submitted over SSL. select INTEGRAL or CONFIDENTIAL.xml). click OK. use the Security Editor. click user. 7.xml for WebSphere” “Enabling security by using the Administrative Console for WebSphere” on page 372 “Binding roles to users and groups in tomcat-users. Related concepts “Overview of Rich UI security” on page 352 “Authentication and Authorization” on page 353 “Confidentiality and Integrity” on page 355 Related tasks “Specifying security criteria in web. Related concepts “Overview of Rich UI security” on page 352 “Authentication and Authorization” on page 353 “Confidentiality and Integrity” on page 355 Related tasks “Specifying security criteria in application. Click OK.xml) in two ways: v By using the Security Editor v By editing application. 2. Click Role Mapping. Save your changes and close the Security Editor. In the WAS Specific Role Mappings window.v Under Security Constraints.xml to actual users and groups in your user registry. 5. click userConstraint.xml” on page 369 “Enabling security by using the Administrative Console for WebSphere” on page 372 Overview of EGL Rich UI 371 . Using the Security Editor To bind the roles that are defined in your web. v To require that requests be submitted over SSL.xml The Security Editor is used in the following example because it provides an easy way to specify and view security criteria. under User Data Constraint. To open the Security Editor from the Project Explorer in the EGL Rich UI perspective. 6. Click Map User. In the Map User window. 4.xml” on page 373 Specifying security criteria in application. click All Authenticated Users. This binding information is stored in the deployment descriptor of your Enterprise Application project (application. double-click on the Security Editor icon of your deployed project. you can specify security criteria in the deployment descriptor of your Enterprise Application project (application. 3.xml for WebSphere When you use WebSphere Application Server. In the WAS Specific Role Mappings window. Defining security role bindings To define security role bindings: 1. and infrastructure. which also selects Enable application security. Click OK to return to Secure administration. Before you start the server again. 2. l. Expand Security. .1 or V7.0. type a user id.1. 3.0. start a WebSphere V6. Exit the Administrative Console and stop the server. i. 372 EGL Programmer’s Guide . the user id is not really used. 3. double click WebSphere Application Server V6. Clear the Use Java 2 security to restrict access to local resources checkbox. applications. take the following steps: a. 2.xml” on page 373 Enabling security in the server configuration for WebSphere To enable security in the server configuration: 1.0. d. c. Because administrative security is not yet enabled.1 or V7. which you must also enter in the User ID field of the server configuration that is described in the next section. Click Configure. j. click Manually provide connection settings and select SOAP as the server connection type. For WebSphere V6. When you are prompted. The configuration page for the realm opens.xml” on page 369 “Specifying security criteria in application. click Administration → Run administrative console. In this example. 4. Click Enable administrative security. under the Server section. select SOAP as the server connection type. under the Server section. From the Available realm definitions. and infrastructure for WebSphere V6.0. use Local operating system. In the Administrative Console. For WebSphere V7. h. For WebSphere V6.″ Related concepts “Overview of Rich UI security” on page 352 “Authentication and Authorization” on page 353 “Confidentiality and Integrity” on page 355 Related tasks “Specifying security criteria in web. For Local operating system. type the user id that you use to log in to your operating system. Click Set as current. For WebSphere V7. select Secure administration.1 or Global security for WebSphere V7. applications.1 or V7. To open your WebSphere Application Server V6. g. select the type of user registry to use. Click Apply → Save. f. Enter the properties. select Global security. e. Note the Primary administrative user name. From the Servers view in the Workbench.0 server. Right click on the server. k.“Binding roles to users and groups in tomcat-users.1.xml” on page 373 Enabling security by using the Administrative Console for WebSphere To enable application and administrative security: 1. follow the instructions in ″Enable security in the server configuration for WebSphere.xml for WebSphere” on page 371 “Binding roles to users and groups in tomcat-users. b.0 server in the Servers view. 5. Before you can access the proxy.xml” on page 369 “Specifying security criteria in application. 6. a request for that Web service is sent to the EGL Rich UI Proxy.xml for WebSphere” on page 371 “Enabling security by using the Administrative Console for WebSphere” on page 372 Running a Rich UI application with a secure proxy When a Web service is invoked from a Rich UI application.xml for WebSphere” on page 371 “Enabling security by using the Administrative Console for WebSphere” on page 372 “Binding roles to users and groups in tomcat-users.xml When you use Apache Tomcat V5. If an authentication error occurs. ensure that the user id and password in your server configuration match those that you used to log in to your operating system. the user repository in a production environment is typically an LDAP directory or relational database. the user id and password that you use to log in to your operating system are also used to authenticate to the EGL Rich UI Proxy. Type the user ID and password that you set in your Administrative Console. Overview of EGL Rich UI 373 .0. The User ID field should match the Primary administrative user name field in the Configuration page of your realm in the Administrative Console. Start the server.0. Save your changes and exit the server configuration. In the tomcat-users.xml file.5 or V6. Related concepts “Overview of Rich UI security” on page 352 “Authentication and Authorization” on page 353 “Confidentiality and Integrity” on page 355 Related tasks “Specifying security criteria in web.xml” Binding roles to users and groups in tomcat-users. you must enter a valid user id and password into a browser-specific dialog. such as the following dialog for Mozilla Firefox V2.xml file. click Security is enabled on this server.4. which is located in the <tomcat-users> <user name="bob" password="guesswhat" roles="user"/> </tomcat-users> Related concepts “Overview of Rich UI security” on page 352 “Authentication and Authorization” on page 353 “Confidentiality and Integrity” on page 355 Related tasks “Specifying security criteria in web. but by default is the tomcat-users. For this example. For this example.xml” on page 369 “Specifying security criteria in application. type the password that you use to log in to your operating system. Under the Security section. For Windows®. When you are finished. use the Task Manager to ensure the java. Related concepts “EGL single sign-on” on page 362 WebSphere Application Server hints and tips: If you want to turn off administrative security but cannot start the server to run the Administrative Console. Go to the WebSphere Application Server install directory. before you restart. 4. When testing your Rich UI application. Related concepts “Overview of Rich UI security” on page 352 “Authentication and Authorization” on page 353 “Confidentiality and Integrity” on page 355 Sample login and error pages for JEE form-based authentication In JEE form-based authentication. you can specify a customized login page and an error page. type quit. which prompts the user to enter a user id and 374 EGL Programmer’s Guide . make sure you specified SOAP as your server connection type in your WebSphere server configuration. clear the Security is enabled on this server checkbox in the server configuration before restarting the server. After turning off administrative security. If you have trouble starting your server with administrative security enabled.You can use EGL single sign-on to combine custom authentication to your application with JEE authentication to the EGL Rich UI Proxy and bypass this dialog. you can turn off administrative security from the command line: 1. you might have to stop the server and exit the Workbench in order to clear all saved values. When the system prompt redisplays. type securityoff.exe process for the server has finished. The login page. Type bin\wsadmin. after authenticating with JEE security. if you make a change to your application or configuration and want to retest authentication.bat –conntype NONE 3. 2. dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html. Copy and save this code in login.jsp under the WebContent folder.01 Transitional//EN" "http://www. When the Web container receives a request for the j_security_check servlet. <%@ page language="java" contentType="text/html. If authentication fails.password. the error page is displayed. Two HTTP request parameters (form input fields) must always be in the request.org/TR/html4/loose. refers to a special j_security_check servlet. charset=ISO-8859-1" pageEncoding="ISO-8859-1"%> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4. one called j_username and the other. charset=ISO-8859-1"> <title>Sample Login Page for JEE Security</title> <style type="text/css">H1 {color: navy}</style> </head> <body> <table width="500" border="0"> <tbody> <tr> <td colspan="3" width="80%" align="center"><b><font face="Verdana"size="+2" color="#15406a">Sample Login</font></b><hr> </td> </tr> <tr> <td colspan="3" width="560" height="65"> <form method="POST" action="j_security_check"> <div> <table width="100%" border="1" bgcolor="#e9e9e9"> <tbody> <tr> <td align="right" width="169" bgcolor="#e9e9e9"><b> <font face="Verdana">User id:</font></b></td> <td width="315"><input type="text" name="j_username"></td> </tr> <tr> <td align="right" width="169" bgcolor="#e9e9e9"> <font face="Verdana"><b>Password:</b></font></td> <td width="315"><input type="password" name="j_password"></td> </tr> <tr bgcolor="white"> <td align="right" width="169" bgcolor="white"></td> <td width="315"><input type="submit" value="Login"></td> </tr> </tbody> </table> </div> </form></td> </tr> <tr> <td colspan="3" width="560" align="center" height="58" valign="top"> <script> document.w3.write(Date()+". Below is code for a sample login page.") </script> </td> </tr> </tbody> </table></body> </html> Overview of EGL Rich UI 375 . it passes the request to the security mechanism of WebSphere Application Server to perform the authentication. j_password. SQL injection.0 applications including cross-site scripting.The following code is for a sample error page. and try again. <%@ page language="java" contentType="text/html. a system administrator should control the access of your user registry. Therefore. However. charset=ISO-8859-1" pageEncoding="ISO-8859-1"%> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4. For example. and JavaScript hijacking. it is very difficult for EGL to defend against certain types of attacks like cross-site scripting and SQL injection without limiting the types of applications customers can write. you cannot retrieve user ids from the 376 EGL Programmer’s Guide . the technologies that provide a richer interactive experience can also make applications less secure. rather than one supplied through JEE form-based authentication or the browser-provided login dialog from JEE basic authentication.01 Transitional//EN" "http://www. securing the proxy with JEE security does not prevent authenticated users from using the proxy for unintended purposes. Copy and save this code in error. The more tightly your user registry is controlled. (In your Rich UI application. You can prevent unauthenticated clients from calling the proxy and reduce the possibility of proxy misuse by securing the EGL Rich UI Proxy with JEE security. However.w3. the safer your proxy will be. Rich UI applications are susceptible to the security vulnerabilities that threaten any Web 2.</td> </tr> </tbody> </table></body> </html> Related concepts “Overview of Rich UI security” on page 352 “Authentication and Authorization” on page 353 “Confidentiality and Integrity” on page 355 “Using Web container-managed (JEE) authentication” on page 357 Preventing client-side security threats Unfortunately. for security reasons. When you use EGL. You can keep a log of the end users who have accessed your Rich UI application if you are using your own login screen.org/TR/html4/loose. It also guards its usage of ″eval″ in runtime code.jsp under the WebContent folder. Please check your user id and password. EGL prevents malicious data being sent to the client using either JavaScript Object Notation (JSON) or XML. charset=ISO-8859-1"> <title>Sample Error Page for JEE Security</title> <style type="text/css">H1 {color: navy}</style> </head> <body> <table width="500" border="0"> <tbody> <tr> <td colspan="3" width="80%" align="center"><b><font face="Verdana" size="+2" color="#15406a">Sample Login Error</font></b><hr> </td> </tr> <tr> <td colspan="3" width="560" align="center" height="58" valign="top"><br>Authentication error.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html. you are protected from some of these client-side threats. Whenever a Web service is invoked in your Rich UI application. Related reference “SSL-related errors” on page 378 “SSL terminology” on page 380 “SSL example” on page 381 Using SSL with Rich UI applications When the HTML file that EGL generates for your Rich UI application is requested. insuring against imposters. the EGL Rich UI Proxy creates a Overview of EGL Rich UI 377 . Always use an SSL-enabled port with the HTTPS protocol. the client uses a URL that starts with HTTPS:// instead of with HTTP://. and is used extensively for securing communications. Also check the documentation of your application server to see if it maintains logs that might be of help to you. SSL example focuses solely on WebSphere Application Server. a connection is made between the browser and the server to which your Rich UI application (including the EGL Rich UI Proxy) was deployed. By using SSL. SSL is a protocol that runs above TCP/IP and below higher-level application protocols such as HTTP and LDAP. Although much of the SSL material in these topics applies to both WebSphere and Tomcat. For instructions on how to install and configure SSL for Tomcat. a server authenticates itself to the client. In SSL. you can prevent the interception and tampering of messages and provide confidentiality through encryption. To initiate an HTTP-based SSL connection. and the client optionally authenticates itself to the server.) This log could help you determine the guilty party if an authenticated user is illegally using your EGL Rich UI Proxy for anything from calling Web services on other domains to instigating JavaScript hijacking attacks. Related concepts “Overview of Rich UI security” on page 352 “Authentication and Authorization” on page 353 “Confidentiality and Integrity” on page 355 Overview of SSL Secure Sockets Layer (SSL) ensures data integrity and confidentiality.application server if you are using JEE security. see Apache Tomcat documentation Related concepts “Overview of Rich UI security” on page 352 “Authentication and Authorization” on page 353 “Confidentiality and Integrity” on page 355 “SSL transport between WebSphere Application Server and LDAP” on page 386 “How SSL works” on page 380 Related tasks “Using SSL with Rich UI applications” “Preventing SSL handshaking exceptions” on page 385 “Starting to work with EGL Rich UI” on page 329 This topic tells how to start developing applications with EGL Rich UI. new connection between its server and the one on which the Web service is deployed. When a Web service is invoked with the SSL protocol. For instance. To require SSL for the request. After you require SSL.xml to INTEGRAL or CONFIDENTIAL. Requesting an HTML file with the SSL protocol (HTTPS) results in an SSL connection between the browser and server. If you use JEE authentication to secure an HTML file or the EGL Rich UI Proxy.xml. These connections are independent of one another and can use different protocols. consider purchasing or writing a Java redirect filter. invoke the Web service by using the HTTPS protocol. but HTTPS is not used on the request. When you use custom authentication. When you secure Web services with HTTP basic authentication. ensure that the Rich UI application also uses the SSL protocol to protect the user id and password in the channel between the browser and server. you might see the following errors: Proxy Configuration 378 EGL Programmer’s Guide .xml of the Web service project to INTEGRAL or CONFIDENTIAL. set the user data constraint in the web. to require SSL for the request. which you can specify on the Filters tab of your web. the EGL Rich UI Proxy creates a new SSL-enabled connection between its server and the one on which the Web service is deployed. you have various options to require HTTPS for the HTML file request. When you use JEE authentication. require SSL to protect the user id and password during transmission. you can configure your Web server to redirect all HTTP requests to HTTPS. You can use these filters to redirect certain HTTP requests to their HTTPS equivalent. require SSL to protect the user id and password from eavesdroppers as they are transmitted between the browser and server. To redirect a specific HTML request. set the user data constraint in theweb. Related concepts “Overview of Rich UI security” on page 352 “Authentication and Authorization” on page 353 “Confidentiality and Integrity” on page 355 “Overview of SSL” on page 377 “SSL transport between WebSphere Application Server and LDAP” on page 386 “How SSL works” on page 380 Related tasks “Preventing SSL handshaking exceptions” on page 385 “Starting to work with EGL Rich UI” on page 329 This topic tells how to start developing applications with EGL Rich UI. When you invoke a secure Web service with SSL. Related reference “SSL-related errors” “SSL terminology” on page 380 “SSL example” on page 381 SSL-related errors If the EGL Rich UI Proxy or Web service requires SSL. the protocol that is used to request the HTML file is the protocol that is used to request the proxy. Problem HTTP is used to request the Web service instead of HTTPS. Related concepts “Overview of Rich UI security” on page 352 “Authentication and Authorization” on page 353 “Confidentiality and Integrity” on page 355 “Overview of SSL” on page 377 “SSL transport between WebSphere Application Server and LDAP” on page 386 “How SSL works” on page 380 Related tasks “Using SSL with Rich UI applications” on page 377 “Preventing SSL handshaking exceptions” on page 385 “Starting to work with EGL Rich UI” on page 329 This topic tells how to start developing applications with EGL Rich UI. The received request was ’’. The same is true for the domain name and port number. Solution Request the Web service with HTTPS instead of HTTP. ″The request could not be converted to a service call. detail1 of the ServiceInvocationException is set to ″302″. ″An error occurred on proxy at ‘{0}’ while trying to invoke service on ‘{1}’″ where {0} is the URL of the proxy and {1} is the URL of the Web service. Web service Configuration A Web service is secured by using JEE basic authentication and includes a CONFIDENTIAL or INTEGRAL user data constraint. detail2 is set to ″Found″. Related reference “SSL terminology” on page 380 “SSL example” on page 381 Overview of EGL Rich UI 379 . Error A ServiceInvocationException is thrown with messageID ″CRRUI3655E″ and the message.″ Solution Request the HTML file with HTTPS instead of HTTP. Problem HTTP is used to request the proxy instead of HTTPS.) Errors A ServiceInvocationException is thrown with messageID ″CRRUI3658E″ and the message. (Because of the Same Origin policy for JavaScript. detail2 is set to ″Found″. detail1 of the ServiceInvocationException is set to ″302″. A ServiceInvocationException is thrown with messageID ″EGL1546E″ and the message. ″An error occurred while processing response object: ‘ReferenceError: urlString is not defined’″.The EGL Rich UI Proxy is secured by using JEE basic authentication and includes a CONFIDENTIAL or INTEGRAL user data constraint. but not covered here. which are stored as signer certificates from target servers whom you have deemed trustworthy. They are faster than asymmetric algorithms but can be insecure. Asymmetric algorithms use a pair of keys. The opposite occurs in client authentication.SSL terminology A key store is a file that contains public and private keys. 380 EGL Programmer’s Guide . you can use WebSphere Application Server to create self-signed certificates. they are much slower than symmetric algorithms. If the target uses a self-signed certificate. Trusted parties called Certificate Authorities (CAs) issue digital certificates. duration of validity. which is also supported through SSL. Public keys are stored as signer certificates and are sent to the clients that request them. To reap the benefits of both algorithms. Because one key is always kept private. Related concepts “Overview of Rich UI security” on page 352 “Authentication and Authorization” on page 353 “Confidentiality and Integrity” on page 355 “Overview of SSL” on page 377 “SSL transport between WebSphere Application Server and LDAP” on page 386 “How SSL works” Related tasks “Using SSL with Rich UI applications” on page 377 “Preventing SSL handshaking exceptions” on page 385 “Starting to work with EGL Rich UI” on page 329 This topic tells how to start developing applications with EGL Rich UI. Related reference “SSL-related errors” on page 378 “SSL example” on page 381 How SSL works SSL uses both symmetric and asymmetric encryption algorithms. one of the keys is kept private while the other is made public. add the CA root certificate to your trust store. SSL encapsulates a symmetric key that is randomly selected each time inside a message that is encrypted with an asymmetric algorithm. In SSL server authentication. Private keys are stored in the personal certificates and are never sent to others. Certificates contain data such as the owner’s name and email address. A trust store is a file that contains public keys. After both the client and server possess the symmetric key. web site address. however. extract the public certificate from the server key store and add the extracted certificate into the trust store as a signer certificate. asymmetric algorithms are generally secure. Symmetric algorithms use the same key to encrypt and decrypt data. the client prompts the server to prove its identity. A certificate is sent from the server to the client during SSL authentication to confirm the identity of the server. and certificate ID of the person who certifies or signs this information. For internal Web sites that do not need a CA certificate. Data encrypted using one key can only be decrypted using the other. Otherwise. the symmetric key is used instead of the asymmetric ones. Client authentication is used when the server needs to send confidential financial information to a customer but wants to verify the identity of the recipient first. Typically. 5.0 are described below. SSL uses the following process: 1.1 was released. and that the certificate is related to the contacted site. Related concepts “Overview of Rich UI security” on page 352 “Authentication and Authorization” on page 353 “Confidentiality and Integrity” on page 355 “Overview of SSL” on page 377 “SSL transport between WebSphere Application Server and LDAP” on page 386 Related tasks “Using SSL with Rich UI applications” on page 377 “Preventing SSL handshaking exceptions” on page 385 “Starting to work with EGL Rich UI” on page 329 This topic tells how to start developing applications with EGL Rich UI. Create an SSL-enabled port To create a sample SSL-enabled port. To request a secure page.0 with SSL to run Rich UI applications. certificates were managed through the use of an external tool called iKeyman. Although you can use WebSphere V6.When server authentication is requested. a uses HTTPS. 6.1 and V7. you can use the Administrative Console to manage both certificates and keys. see your WebSphere Application Server documentation. along with the encrypted URL required and other encrypted HTTP data. 2.1. the instructions for doing so are not included here. 3. For more details.0 to create and use your own SSL-enabled port. see Apache Tomcat documentation. The differences between V6. Overview of EGL Rich UI 381 . The server sends the client its public key and certificate. take the following steps. The client checks that the certificate was issued by a trusted party (usually a trusted Certificate Authority) that the certificate is still valid. As of WebSphere Application Server V6. Before WebSphere Application Server V6. Related reference “SSL-related errors” on page 378 “SSL terminology” on page 380 “SSL example” SSL example The following example illustrates how to use WebSphere V6.1 or V7. The client uses the public key to encrypt a random symmetric encryption key and sends it to the server. The server sends back the requested HTML document and HTTP data that are encrypted with the symmetric key. The client decrypts the HTTP data and HTML document using the symmetric key and displays the information. 4. 7. The server decrypts the symmetric encryption key using its private key and uses the symmetric key to decrypt the URL and HTTP data. For instructions on how to install and configure SSL for Tomcat. Repeat this process for NodeDefaultTrustStore.1 or V7. Type the following values for the certificate: Alias SampleCert Common name Sample Server Organization IBM 6.Changing your key store and trust store passwords In the following procedure. click Create a self-signed certificate. For WebSphere V7. Under Related Items. Log in to the Administrative Console. Type your new password into the Change password and Confirm password fields. Click Run administrative console. click NodeDefaultKeyStore. you create a new self-signed certificate in your WebSphere Application Server default key store and import the certificate into your default trust store. click SSL configurations. 6.0. 4. 5. 10. Creating a personal certificate A self-signed certificate is useful when you are testing or when your Web site is behind a firewall. 3. 11. Creating an SSL configuration WebSphere Application Server uses SSL configurations for SSL-based transports. Click OK. Before you use the default key and trust stores. change their passwords from the defaults to another value to create a more secure environment. From the left-hand pane. click Create → Self-signed certificate. 8. Under Related Items. Under Additional Properties. click Personal certificates. 4. 3. expand Security and click SSL certificates and key management. From your list of key stores and trust stores. you should now see samplecert. Click Change password.0. Click New. Otherwise. 2.1. 9. 7. Click OK.1. 3. For WebSphere V7. For WebSphere V6. click NodeDefaultKeyStore. For WebSphere V6. click Key stores and certificates. Expand Security and click SSL certificate and key management.0 server 2. Type the following values: 382 EGL Programmer’s Guide . Start your WebSphere V6. 5. click NodeDefaultKeyStore. 2. Right click on the server and click Administration. To create a personal certificate: 1. obtain a certificate from a Certificate Authority. To change your key store and trust store passwords: 1. 4. To create an SSL configuration: 1. In the list of certificates. Click OK. 5. Click Finish → Save. pick another port number and use that number for the rest of the exercise. To select the Transport chain template. Click New.1. Under Container Settings. 2. expand Web Container Settings and click Web container transport chains. from the left-hand pane. click WebContainer-Secure(templates/chains | webcontainer-chains. Creating a Web container transport chain Create a Web container transport chain to use the SSL configuration that you created: 1. 6. 9. Click server1 or your server name. Overview of EGL Rich UI 383 . Click Next. and click Save. Click OK → Save. 4. Click SSL inbound channel. select SampleConfig . Ensure that samplecert is selected as the Default server certificate alias and the Default client certificate alias. expand Servers and click Application servers. Associate the sample SSL configuration with this transport chain: 1. expand Servers and Server Types. Click Next. For WebSphere V7. Under SSL Configuration. For WebSphere V6. 11. you should see SampleConfig. type SampleInboundSecure. 6. 3. 4. 10. In the list of SSL configurations. In the Transport chain name field.Name SampleConfig Trust store name NodeDefaultTrustStore Keystore name NodeDefaultKeyStore 5.xml#Chain_2). 8. SampleInboundSecure is now listed as a Web container transport chain.0. Click Get certificate aliases. from the left-hand pane. Click SampleInboundSecure. Click WebSphere application servers. 7. 2. from the drop-down list. type the following values: Port SamplePort Host * Port number 9444 If port 9444 is already in use. 3. In the Select a port page. from the Select SSL Configuration drop-down list. To verify the certificate. click Host Aliases. click the View Certificate button. Click default_host. you should see 9444.html v In your Project Explorer. Change the port to 9444. If you are using a self-signed certificate. On the Host Aliases page. OK → Save. 2. continue. take one of the following steps: v Open a browser such as Internet Explorer. Related reference “SSL-related errors” on page 378 384 EGL Programmer’s Guide . expand Environment and click Virtual Hosts .1 or V7. 4.html in the RSSReaderSample context. or Mozilla Firefox. If the Common Name on the certificate does not match the domain name in the requested URL (localhost. Safari®. On your WebSphere server.Adding the SSL-enabled port to the virtual host Add port 9444 to the virtual host: 1. To request an HTML file such as RSSReader. Stop and restart the server. in this case). If so. To prevent ″man-in-the-middle″ attacks. click New. start a WebSphere V6. 5. Under Additional Properties. 6. install the EAR that contains your deployed Rich UI application. In the list of ports. where a rogue program intercepts all communication between a client and server. Port 9444 is now an SSL-enabled port. Keep * as the host name. then click Run on Server. Related concepts “Overview of Rich UI security” on page 352 “Authentication and Authorization” on page 353 “Confidentiality and Integrity” on page 355 “Overview of SSL” on page 377 “SSL transport between WebSphere Application Server and LDAP” on page 386 “How SSL works” on page 380 Related tasks “Using SSL with Rich UI applications” on page 377 “Preventing SSL handshaking exceptions” on page 385 “Starting to work with EGL Rich UI” on page 329 This topic tells how to start developing applications with EGL Rich UI. Click Run As. In the left-hand pane. or another warning. you might see a ″Security Alert″. Click the ″View Certificate″ or ″Examine Certificate″ button to verify if the certificate is correct. you might also see a ″Security Error: Domain Name Mismatch″ error. Using the new SSL-enabled port to run a sample To use your port. ″Website Certified by an Unknown Authority″. 3. and continue as appropriate. This warning indicates that the certificate was signed by an unknown certifying authority. right-click on an HTML file of an application that has been published to WebSphere.0 server. the client must verify the server domain name that is specified in the certificate. depending upon the browser. Enter a URL in your browser using the newly-enabled SSL port: https://localhost:9444/ RSSReaderSample/RSSReader. a security alert dialog is displayed. ensure that the certificate of a server can be found in the trust store of a client. the certificate that belongs to the server of the Web service must be in the trust store of the server of the EGL Rich UI Proxy before the connection is initiated. enter the URL of the Web service in a browser over HTTPS. Click Retrieve signer information → OK. the connection between the proxy and Web service uses SSL. Right click the server. Save the certificate to a file. 8. Overview of EGL Rich UI 385 . To obtain a copy of the server’s certificate when calling a third-party Web service. Under Related Items. Details tab. Click the appropriate trust store. This connection is independent of the connection between the browser and proxy. The proxy is deployed to the same location as the generated HTML file of your Rich UI application. 4. you a handshaking error occurs. If you try to use the SSL-enabled port 9444 you created in ″SSL Example″ to request a Web service called from an HTML file requested on the WebSphere default SSL port 9443. To fix this problem. The way in which you receive the certificate of the server varies depending on the browser. 5. import the certificate that is associated with port 9444 into the trust store that is associated with port 9443: 1. and ″Copy to File″ button. Alternatively. Click Signer certificates. Click Administration → Run administrative console.1 or V7. Use the Administrative Console to open the trust store of your EGL Rich UI Proxy and import the saved certificate as a signer certificate. Specify the following values: Host localhost Port 9444 SSL configuration for outbound connection NodeDefaultSSLSettings Keystore name SampleCert 10. Expand Security and click SSL certificates and key management. the EGL Rich UI Proxy establishes a HTTP or HTTPS connection between the proxy and Web service. 7. 3. When a Web service is invoked from a Rich UI application. Otherwise a handshaking error occurs. If the Web service has an HTTPS protocol. Because no browser is available to display a security alert and prompt for a response. Log in to the Administrative Console. If the certificate is not found in the trust store and the client is a browser.“SSL terminology” on page 380 Preventing SSL handshaking exceptions To prevent SSL handshaking exceptions. 6. click Key stores and certificates. A user can use the dialog to view the certificate and select whether to proceed. A common way is through a ″View Certificate″ button. Start the WebSphere V6. Click Retrieve from port. you can connect to the remote SSL host and port and receive the signer certificate during the handshake by using the ″Retrieve from port″ option.0 server that contains your EGL Rich UI Proxy. 2. 9. Restart the server. You should now be able to request a Web service on port 9444 from port 9443 without receiving a handshaking error. Related concepts “Overview of Rich UI security” on page 352 “Authentication and Authorization” on page 353 “Confidentiality and Integrity” on page 355 “Overview of SSL” on page 377 “SSL transport between WebSphere Application Server and LDAP” “How SSL works” on page 380 Related tasks “Using SSL with Rich UI applications” on page 377 “Starting to work with EGL Rich UI” on page 329 This topic tells how to start developing applications with EGL Rich UI. Related reference “SSL-related errors” on page 378 “SSL terminology” on page 380 “SSL example” on page 381 SSL transport between WebSphere Application Server and LDAP If you use an LDAP directory as your registry, WebSphere Application Server verifies the password of a user by using the standard ldap_bind, which requires sending the password to the LDAP directory server. A password can flow in clear text when you use a non-SSL channel between WebSphere and the LDAP directory server. To use SSL, create a certificate for the LDAP directory and import it into the trust store of your server. Also enable SSL on your LDAP directory server. For more details, see LDAP directory server and application server documentation. Related concepts “Overview of Rich UI security” on page 352 “Authentication and Authorization” on page 353 “Confidentiality and Integrity” on page 355 “Overview of SSL” on page 377 “How SSL works” on page 380 Related tasks “Using SSL with Rich UI applications” on page 377 “Preventing SSL handshaking exceptions” on page 385 “Starting to work with EGL Rich UI” on page 329 This topic tells how to start developing applications with EGL Rich UI. Related reference “SSL-related errors” on page 378 “SSL terminology” on page 380 “SSL example” on page 381 IBM Rational AppScan IBM Rational AppScan® is a Web application security assessment suite that you can use to identify and fix common Web application vulnerabilities. Use Rational AppScan to scan and test the code that EGL generates for your EGL Rich UI application to pinpoint any critical areas that are susceptible to a Web attack. For more information on the Rational AppScan product line, see http://www306.ibm.com/software/rational/offerings/websecurity/webappsecurity.html. 386 EGL Programmer’s Guide Related concepts “Overview of Rich UI security” on page 352 “Authentication and Authorization” on page 353 “Confidentiality and Integrity” on page 355 Overview of EGL Rich UI 387 388 EGL Programmer’s Guide Building EGL JSF Web applications In an EGL JSF 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. EGL also supports two other ways to write code for Web browsers: v Rich UI applications v Web transactions, which are available for compatibility with previous versions of EGL Related concepts “Elements of a JSF 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 394 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. “Overview of EGL Rich UI” on page 327 Related reference “Working with Web transaction applications in EGL” on page 561 Related reference Web pages with JavaServer Faces Elements of a JSF 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 411. 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 © Copyright IBM Corp. 1996, 2008 389 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 part 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. For more information on JSP files, see JavaServer Pages (JSP) technology. For more information on JSF technology, see JavaServer Faces (JSF) overview. 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 408. 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. For more information on the Web deployment descriptor, see Configuring Web applications using the Web deployment descriptor editor. 390 EGL Programmer’s Guide 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.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. For information on working with Web diagrams, see Web diagrams and the Web diagram editor. 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 about using style sheet files, see Defining styles. For more information about using JavaScript, see Adding code to Web pages. 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 392 When you create a Web page in an EGL Web project, EGL creates a JSF Handler part to go along with the page. “Binding JSF controls to EGL variables and functions” on page 394 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. “Navigating among Web pages with navigation rules” on page 408 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. “Forwarding data between Web pages” on page 410 You 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 411 A JSF Handler can include functions that run automatically when the page loads. “Retrieving the value of a clicked row in a data table” on page 417 The getClickedRowValue snippet in the EGL drawer of the Snippets view is a function that retrieves the hyperlinked value of a clicked row in a data table. “Setting the focus to a form field” on page 418 The Set cursor focus snippet in the EGL drawer of the Snippets view is a JavaScript function that sets the cursor focus to a specified form field on a Web page. It must be placed within a <script> tag in a JSP page. Building EGL JSF Web applications 391 “Updating a row in a relational table” on page 423 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. “Storing data in the user’s session” on page 424 “Testing browsers for a session variable” on page 425 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. “Localizing text in Web applications” on page 426 “Creating a resource bundle” on page 430 “Locales for resource bundles” on page 431 “Running a Web page on a server” on page 448 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. “Accessing the JSF component tree with the source assistant” on page 454 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. 392 EGL Programmer’s Guide 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. See Page templates for more information on templates. 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. Click Next. Set the location and file name of the new Handler part. Click Finish. 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: 3. 4. 5. 6. myInputVar string {displayUse = input}; For other options for the displayUse property, see displayUse. 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 465 These preferences control defaults for EGL Web projects and JSF Handler parts. Adding a Web server You must have a Web server started and synchronized before you can run Web applications. Building EGL JSF Web applications 393 A Web server is a program that delivers responses to HTTP requests from a Web browser. EGL can work with a variety of Web servers, many of which have multiple versions. For this reason this topic can offer only very general instructions. For more information, refer to the documentation for the specific Web server software. Set up a new Web server by following these steps: 1. Go to Window → Preferences → Server → Installed runtimes and click Add. 2. Select the type of runtime to install from the displayed list, then click Next. 3. Enter the path to the directory where the server programs are located, as well as any other requested information (which varies with the type of runtime), then click Finish. If you are in the EGL perspective, you can now add a Server view to the workbench (Window → Show View → Other → Server → Servers). From this view, you can create a Server based on the Installed Runtime you just created. 1. Right-click anywhere in the blank Server view and select New → Server from the pop-up menu. 2. Select the server type from the list. Your Server runtime should appear automatically in the appropriate text box. Click Next. 3. Accept the default server settings on the next page and click Next. 4. Add any projects that will use the server to the Configured projects list. If you use an EAR project, the projects that use the EAR will appear underneath it. Click Finish when you are done. You should now be able to right-click the name of the server in the Server view and choose Start from the pop-up menu. Related concepts “Common tasks in Web applications” on page 391 This section covers some common tasks that you might want to perform when working with EGL Web applications. “Working with Web transaction applications in EGL” on page 561 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 395. 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 397. 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 401. 394 EGL Programmer’s Guide 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 404. 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 407. 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 397 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. “Binding a JSF single-select control to a variable” on page 401 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. “Returning the indexes of selected rows in a data table” on page 404 “Binding JSF controls to services” on page 407 Binding functions and variables from a service to controls on a Web page is no different from binding any other type of functions and variables, but EGL provides shortcuts for working with service controls in this way. Related reference JSF Handler part Component tree access Binding a JSF button to a function: When you bind a JSF button to a function in the JSF Handler, the function runs when the user clicks the button. The easiest way to accept a command from a Web page is to write the function first and then bind it to the button: 1. Create a Web page in an EGL Web project. 2. In the page’s JSF Handler, create a function. At this point, you only need the basics of the function to do the binding; you can code the logic for the function later. 3. Save the JSF Handler. 4. Open the associated JSP file. Building EGL JSF Web applications 395 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 397 for a limitation having to do with the location of buttons and controls within a <form> tag. Related concepts “Building EGL JSF Web applications” on page 389 In an EGL JSF Web application, EGL logic parts control Web pages, enabling you to put data on Web pages, get data from user input on Web pages, and forward users from page to page. Related tasks “Binding JSF controls to EGL variables and functions” on page 394 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. “Binding a control on a Web page to a variable” on page 397 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. 396 EGL Programmer’s Guide “Binding a JSF single-select control to a variable” on page 401 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. “Returning the indexes of selected rows in a data table” on page 404 “Binding JSF controls to services” on page 407 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. Binding a control on a Web page to a variable: You can bind a variable in the JSF Handler to an input or output control on the Web page. When a variable is bound to a control on the page and the user changes the value in the control, the value of the variable changes to match, and if the logic in the JSF Handler changes the value of the variable, the value on the page changes to match. There are several ways to bind Web page controls to EGL variables: v Create the controls automatically from existing EGL variables. v Create the controls yourself and explicitly bind variables to those controls. v Create both the controls and the variables at the same time. Creating JSF controls automatically from EGL variables With this method, you create variables in the JSF Handler and then allow EGL to create appropriate representations on the page. 1. Open the JSF Handler that is associated with the Web page. If you are looking at the JSP file in the editor, you can open its JSF Handler by right-clicking the page and then clicking Edit page code. 2. In the JSF Handler, define one or more EGL primitives, data items, or record variables, and save the file. To be used on the Web page, the variables must be directly within the JSF Handler part and not within any function in the part. 3. Open the JSP file. 4. In the Page Data view, expand JSF Handler. The variables that are defined in the JSF Handler are listed here. 5. Drag the variable from the Page Data view directly onto the Web page. Depending on the type of variable that you drag, the Insert Control or Insert List Control window opens. 6. Click a radio button under Create controls for: v If you want read-only output controls, select Displaying an existing record. v If you want editable input controls, select Updating an existing record or Creating a new record. In this context, the two options are equivalent. This wizard treats all EGL variables as if they were records. 7. If you selected a record variable or more than one variable, select the check boxes next to the controls or variables that you want to display. You can also choose a type of control to represent the controls or variables from the Control type column. 8. Click Finish. Building EGL JSF Web applications 397 If you want to make the control editable for input and output. Drag the variable from the Page Data view directly onto the control on the Web page. expand JSF Handler. Select Add controls to display the EGL element on the page. 6. 6. single primitive variables or data items can be bound to single input or output controls. 1. or record variable. expand the EGL drawer. Depending on the type of variable. use a Data Table control and create a column in the data table for each field in the record. or record variables and save the file. In the Palette view. 5. you can open its JSF Handler by right-clicking the page and then clicking Edit page code. 7. In the Page Data view. select whether you want a primitive. If you are looking at the JSP file in the editor. For primitive variables.The controls are added to the page. 9. If you want the variable to be an array. 4. Name the variable in the Enter the name of the field field. such as an Output text control. The variables defined in the JSF Handler are listed here. and they are automatically bound to the variables that you dragged onto the page. 3. Open the JSP file. the Insert Control or Insert List Control window opens. In the JSF Handler. Arrays and records need to be bound to columns within a data table. This method is useful if you want to design the look of your page first and then add data. 2. For data items and records. choose a part from your project. For example. The rest of the options on the page differ depending on the type of variable you choose. expand the Enhanced Faces Components drawer and drag a control onto the Web page. Under Type Selection. 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. use an output control. The Create a New EGL Data Variable window opens. 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. 5. choose a primitive type and specify a dimension if appropriate. To be used on the Web page. data item. 3. 8. Select the type of variable. 1. select the Array check box and specify a starting length in the Size field. From the Palette view. define one or more EGL primitive. data item. Creating JSF controls and binding them manually You can create your own controls and bind them manually to EGL variables. 2. use an Input control. For records. the variables must be directly within the JSF Handler part and not within any function in the part. Click a radio button under Create controls for: 398 EGL Programmer’s Guide . 4. making sure to use appropriate controls for the EGL variable types. If you want the control to be read-only. Open the JSF Handler associated with the Web page. Click OK. Drag a New Variable onto the page. Click Finish._postRender}"> <h:form id="form1" styleClass="form"> <h:inputText id="text1" styleClass="inputText" value="#{formTestPage._preRender}" postRender="#{formTestPage. the two options are equivalent.jsp"} stringOne string. stringTwo string. For example. you can type values into the controls. The code of the body of the Web page might look like this: <body> <hx:scriptCollector id="scriptCollector1" preRender="#{formTestPage. This example assumes that you have placed the button and controls in the same HTML form. This wizard treats all EGL variables as though they were records.stringTwo_Ref}"></h:inputText> <br> <hx:commandExButton id="buttonDoSomething1" styleClass="commandExButton" type="submit" value="doSomething" action="#{formTestPage. and see the values that you typed written to the console. One major limitation is that the JSF Handler receives only the changed variables from the form that is submitted on the Web page. assume the following JSF Handler with two variables and one function: handler formTestPage type JSFHandler {view = "formTestPage. select the check boxes next to the fields that you want to display. 10.doSomething}" actionListener="#{formTestPage. function doSomething() SysLib. 11. If you selected a record variable with more than one field. In this context.v If you want read-only output controls. v If you want editable input controls.stringOne_Ref}"></h:inputText> <br> <h:inputText id="text2" styleClass="inputText" value="#{formTestPage. select Updating an existing record or Creating a new record. end end If you bind the function to a button and the variables to two input controls._commandActionListener}"> </hx:commandExButton> </h:form> </hx:scriptCollector> </body> Building EGL JSF Web applications 399 .writeStderr("stringOne = " + stringOne).stringTwo}" binding="#{formTestPage. Limitations Binding controls to variables has limitations because of the way Web pages behave. You can also choose a type of control to represent the fields or variables from the Control type column.writeStderr("stringTwo = " + stringTwo). press the button. SysLib. select Displaying an existing record.stringOne}" binding="#{formTestPage. you can begin developing the Web page’s behavior.stringTwo}" binding="#{formTestPage. both input controls are made available to the JSF Handler. enabling you to put data on Web pages. This means binding. “Binding a JSF button to a function” on page 395 When you bind a JSF button to a function in the JSF Handler. Related tasks “Binding JSF controls to EGL variables and functions” on page 394 When you have a JSP file and an associated JSF Handler part. However. if you put the controls on the page far apart. when you click the button. and the variable bound to the first control is not changed._preRender}" postRender="#{formTestPage. and forward users from page to page. “Returning the indexes of selected rows in a data table” on page 404 400 EGL Programmer’s Guide . elements on the Web page to variables and functions in the JSF Handler._postRender}"> <h:inputText id="text1" styleClass="inputText" value="#{formTestPage. This way. or connecting. get data from user input on Web pages. the first input control is outside the form. “Binding a JSF single-select control to a variable” on page 401 Binding a JSF single-select control.stringOne}" binding="#{formTestPage.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). that is. but the second input control and the button are within the form.doSomething}" actionListener="#{formTestPage. the JSF Handler receives only the second control. EGL logic parts control Web pages. the values typed into the input controls are assigned to the variables in the handler. When you click the button now._commandActionListener}"> </hx:commandExButton> </h:form> </hx:scriptCollector> </body> In this case. Related concepts “Building EGL JSF Web applications” on page 389 In an EGL JSF Web application. the function runs when the user clicks the button.stringTwo_Ref}"></h:inputText> <br> <hx:commandExButton id="buttonDoSomething1" styleClass="commandExButton" type="submit" value="doSomething" action="#{formTestPage. they might not be within the same form tag: <body> <hx:scriptCollector id="scriptCollector1" preRender="#{formTestPage. 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.stringOne_Ref}"></h:inputText> <br> <h:form id="form1" styleClass="form"> <h:inputText id="text2" styleClass="inputText" value="#{formTestPage. 5. See ″Using an array of records as the selection options.single select. "Fourth choice". In general. In each case. 7. as well as a single variable to hold the value of the selected option. List Box . 4. The simplest way to do this is by defining an array of strings and populating the array with the options for the control. On the page that is associated with the JSF Handler. drag the variable that represents the list of options (in this case. The control is added to your page and it is automatically bound to the variables in the JSF Handler. "Second choice". "Fourth choice"}. Assign values to the array. or Radio Button Group. you need to create an array that represents the options in the control. "Second choice". 6. the options will be added dynamically depending on the number of elements in the list of options at run time. SelectedValueItem = selectedChoice}. In a JSF Handler. "Third choice". You can check which variables the JSF control is bound to by clicking the control to select it and then opening the Properties view. 9. click Displaying an existing record. 8. Click Finish. create an array of strings to hold the options for the single-select control: selectionOptions string[4]. In the Properties view. The Insert List Control window opens. 2. select the type of single-select JSF control to put on the page. Indicate that the single variable receives the option selected from the list of options by adding the SelectedValueItem property to the list of options: selectionOptions string[4] {"First choice". You can assign values dynamically or simply assign literal values to the array: selectionOptions string[4] {"First choice". the Value field represents the variable that will receive the value of the selected option. "Third choice". 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. such as a combo box or group of radio buttons. See ″Using an array of STRING as the selection options. but EGL provides shortcuts for working with service controls in this way. You can choose from Combobox (also called a list box or drop-down box). 3. Create a string variable to hold the selected option: selectedChoice string. Binding a JSF single-select control to a variable: Binding a JSF single-select control.″ Using an array of STRING as the selection options 1. and Building EGL JSF Web applications 401 . selectionOptions) from the Page Data view onto the page. In the Insert List Control window. Under Control Type. 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. Save and generate the JSF Handler.″ Alternatively.“Binding JSF controls to services” on page 407 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. You can assign values dynamically or simply assign literal values to the array. Using an array of records as the selection options The method of using an array of strings as the selection options is simple. string.jsp"} selectionOptions string[4] {"First choice". In a Record part. valueItem = optionValue}} displayOption string. selectedChoice outputMessage string. When you click the button. In this case. list box. Assign values to the array. This is a complete example of a JSF Handler that uses a single-select control in this way: handler singleSelect type JSFHandler {view = "singleSelect. 2. the output control displays the text of the option you selected in the JSF single-select control. function getChoice() outputMessage = "You chose: " + selectedChoice. To use an array of records as the selection options: 1."Second choice". but you must select two of these fields to be the label and the value. 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.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. or radio button group based on this variable. "Third choice". optionValue string. but it might not be the most convenient method. 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. In the JSF Handler. You will also need to bind the outputMessage variable to an output control and the getChoice function to a button on the page. create an array that is based on this Record part: selectionOptions optionsRec[3]. end The record can contain other fields. 3."Fourth choice". You might want to use the onPreRenderFunction to set values for this array: 402 EGL Programmer’s Guide . or you might need to use one value for the option and pass a different value to the selection result variable. SelectedValueItem = selectedChoice}. You might need to retrieve the options from an array of records. end end This example assumes that you have dragged the selectionOptions variable onto the page and created a combo box. click Displaying an existing record. The Insert List Control window opens. 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}.optionValue = selectionOptions[2].displayOption selectionOptions[2]. 7. = "Option three". selectionOptions from the Page Data view onto the page. 5.displayOption selectionOptions[2].displayOption selectionOptions[1]. the options will be added dynamically depending on the number of elements in the list of selection options at run time.function onPreRender() selectionOptions[1]. In the Insert List Control window. 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. 6. = "Option two". Save and generate the JSF Handler. 8. "second option". This is a complete example of a JSF Handler that uses a single-select control in this way: handler singleSelect type JSFHandler {view = "singleSelect.optionValue = 403 . "first option".single select. Building EGL JSF Web applications function onPreRender() selectionOptions[1]. 9.optionValue = selectionOptions[2]. 10.optionValue = selectionOptions[3].optionValue = end selectedChoice string. In the Properties view. You can check which variables the JSF control is bound to by clicking the control to select it and then opening the Properties view. You can choose from Combobox (also called a list or drop-down box). onPreRenderFunction = onPreRender} selectionOptions optionsRec[3] {selectedValueItem = selectedChoice}. string. List Box . On the page that is associated with the JSF Handler. = "Option one". "third option".displayOption selectionOptions[3]. selectedChoice outputMessage string. The control is added to your page and it is automatically bound to the variables in the JSF Handler. Click Finish. 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. the Value field represents the variable that will receive the value of the selected option.displayOption selectionOptions[1]. = "Option two". "third option". "second option". = "Option three". Under Control Type. select the type of single-select JSF control to put on the page. drag the variable that represents the list of selection options (in this case. "first option". In each case. 4.jsp".displayOption selectionOptions[3]. = "Option one". or Radio Button Group.optionValue = selectionOptions[3]. Related concepts “Building EGL JSF Web applications” on page 389 In an EGL JSF Web application. the function runs when the user clicks the button. you might select several rows for deletion. valueItem = optionValue}} displayOption string. list box. or radio button group that is based on this variable. This means binding. EGL logic parts control Web pages. but EGL provides shortcuts for working with service controls in this way. With this column of check boxes. When a variable is bound to a control on the page and the user changes the value in the control. For example. enabling you to put data on Web pages. the value on the page changes to match. Related reference selectFromListItem 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. When you click the button. “Returning the indexes of selected rows in a data table” “Binding JSF controls to services” on page 407 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. You also need to bind the outputMessage variable to an output control and the getChoice function to a button on the page. or connecting. and forward users from page to page. you can select one or more rows in the table to perform a particular action on. Related tasks “Binding JSF controls to EGL variables and functions” on page 394 When you have a JSP file and an associated JSF Handler part. and if the logic in the JSF Handler changes the value of the variable. “Binding a JSF button to a function” on page 395 When you bind a JSF button to a function in the JSF Handler. 404 EGL Programmer’s Guide . “Binding a control on a Web page to a variable” on page 397 You can bind a variable in the JSF Handler to an input or output control on the Web page. the output control displays the text of the option that you selected in the JSF single-select control. you can begin developing the Web page’s behavior. optionValue string. end end record optionsRec type BasicRecord {@SelectionList {labelItem = displayOption. the value of the variable changes to match.end function getChoice() outputMessage = "You chose: " + selectedChoice. get data from user input on Web pages. end This example assumes that you have dragged the selectionOptions variable onto the page and created a combo box. elements on the Web page to variables and functions in the JSF Handler. 4. select a radio button under Create controls for. For example. Then the user can select one or more of the check boxes. create an array of records to represent the table of data you want shown on the page: purchaseList customerPurchase[3]. EGL automatically converts 0-based JSF arrays to 1-based EGL arrays. if the check boxes for the first. If you want read-only output controls. to be able to select multiple rows in a JSF data table. 6.4]. end 2. unlabeled column that contains check box elements. 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. and fourth rows in the data table are selected. For the record variable. If you click the check box control to select it and go to the Properties view. 3. third. You might want to put this retrieval logic in the function specified in the onPreRenderFunction property of the JSF Handler. This table includes a small. set the selectedRowItem property to the name of the array that will hold the indexes of the selected records: purchaseList customerPurchase[3] {selectedRowItem = allSelectedRows}. but you can retrieve the data from a database or populate the array in any other way. EGL sets the array of integers to [1. In this way. totalPurchases decimal(10. select Updating an existing record. In the Insert List Control.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. Click Finish. drag the array of records from the Page Data view onto the page. On the Web page. This example displays a list of customers and their total purchases and enables you to select one or more rows to add together: 1. The example later in this topic will assign literal values to the array. Create the array of integers that will hold the indexes of the selected records: allSelectedRows int[0]. If you want editable input controls. 7. The records are displayed on the page as a JSF data table. Building EGL JSF Web applications 405 . The Insert List Control window opens. Retrieve data to populate this array with the data that you want the user to select on the page. select Displaying an existing record.2).3. 5. In the JSF Handler for an EGL-controlled Web page. EGL indicates which rows were selected by returning an array of integers that represent the indexes of the selected rows. 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 uses the following sample Record part: record customerPurchase type BasicRecord custName string. //indexes of the selected rows allSelectedRows int[0].totalPurchases = "232. purchaseSum += purchaseList[customerIndexToAdd]. for (counter from 1 to allSelectedRows.totalPurchases. purchaseList[3]. 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. for example: For example.totalPurchases = "500. EGL logic parts control Web pages.jsp"} //Array of customer records and their purchase amount purchaseList customerPurchase[3] {selectedRowItem = allSelectedRows}. end function sumRows() purchaseSum = 0. This means binding. //Sum of selected purchases purchaseSum decimal(10.custName = "Company C".2). view = "multiSelectPage. 406 EGL Programmer’s Guide . or connecting. end end end record customerPurchase type BasicRecord custName string.55".Now the integer array will hold the row numbers of the rows that are selected on the Web page. function onPreRender() //initialize the array of customers purchaseList[1].12".totalPurchases = "499. purchaseList[3].23". Related concepts “Building EGL JSF Web applications” on page 389 In an EGL JSF Web application. enabling you to put data on Web pages. You can define a function to process the selected records when a user clicks a button on the page.custName = "Company B".custName = "Company A". and forward users from page to page. respectively. elements on the Web page to variables and functions in the JSF Handler. totalPurchases decimal(10.2). get data from user input on Web pages. counter int = 0. this JSF Handler uses a selection column in this way: handler multiSelectPage type JSFHandler {onPreRenderFunction = onPreRender.getSize() by 1) customerIndexToAdd = allSelectedRows[counter]. you can begin developing the Web page’s behavior. purchaseList[2]. purchaseList[2]. customerIndexToAdd int. Related tasks “Binding JSF controls to EGL variables and functions” on page 394 When you have a JSP file and an associated JSF Handler part. purchaseList[1]. and variables and functions are added to the JSF Handler. 6. Building EGL JSF Web applications 407 . 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. This task has the following prerequisites: v An EGL Web project and Web page. select the service that you want to use in the Select a service list. the function runs when the user clicks the button. See “Adding service client binding information from a WSDL file” on page 489. 3. but EGL provides shortcuts for working with service controls in this way. The Page Data view now shows the service in its Services folder. drag a Service onto the page. In the Add Service window. “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. such as a combo box or group of radio buttons. Click Finish. v A service client binding. but EGL provides shortcuts for working with service controls in this way. 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. drag the service onto the page. You can select more than one function by pressing and holding Ctrl and clicking the functions. The Add Service window opens. select the function that you want to use.“Binding a JSF button to a function” on page 395 When you bind a JSF button to a function in the JSF Handler. The Insert Service window opens. or “Calling a remote service” on page 485. “Binding a JSF single-select control to a variable” on page 401 Binding a JSF single-select control. Open the Web page in the editor. From the EGL drawer of the Palette view. When a variable is bound to a control on the page and the user changes the value in the control. “Binding a control on a Web page to a variable” on page 397 You can bind a variable in the JSF Handler to an input or output control on the Web page. The Select a function list shows the functions that are available in this service. Under Select a function. 5. 4. the value of the variable changes to match. From the Services folder of the Page Data view. 2. To bind functions and variables from a service to fields on a Web page: 1. and if the logic in the JSF Handler changes the value of the variable. Related reference selectFromListItem 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. “Calling a local service” on page 483. the value on the page changes to match. listing all the services for which you have defined client bindings. 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 397 and “Binding a JSF button to a function” on page 395. 10. when navigating to a Web page in a different application. Related tasks “Binding JSF controls to EGL variables and functions” on page 394 When you have a JSP file and an associated JSF Handler part. When navigating among pages in an EGL applications. On the Results Form page. Click Finish. when using forward to label. such as a combo box or group of radio buttons. set the options for the input controls. use forward to label. and if the logic in the JSF Handler changes the value of the variable. and forward users from page to page. 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. the value of the variable changes to match. In the Function list. This means binding. “Binding a JSF single-select control to a variable” on page 401 Binding a JSF single-select control. “Binding a control on a Web page to a variable” on page 397 You can bind a variable in the JSF Handler to an input or output control on the Web page. 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. EGL logic parts control Web pages. Click Next. EGL works closely with JavaServer Faces (JSF) navigation functionality to control page navigation in this way. get data from user input on Web pages. forwarding the user from one page to another and passing data between pages. you specify a navigation rule that in turn points to the target page. you specify an absolute or relative URL to the target page. the default. When a variable is bound to a control on the page and the user changes the value in the control. set the options for the output controls. A JSF redirect prompts the user’s Web browser to load a different target page. use forward to URL. Under Fields to display. the function runs when the user clicks the button. 11. enabling you to put data on Web pages. “Returning the indexes of selected rows in a data table” on page 404 Related reference selectFromListItem Navigating among Web pages with navigation rules A JSF Handler can control the navigation on a Web site. or connecting. Related concepts “Building EGL JSF Web applications” on page 389 In an EGL JSF Web application. elements on the Web page to variables and functions in the JSF Handler. The JSF servlet responds to a forward statement by issuing either a forward or a redirect. “Binding a JSF button to a function” on page 395 When you bind a JSF button to a function in the JSF Handler. the effect is the same as if the user had typed the new URL into the 408 EGL Programmer’s Guide . the value on the page changes to match. EGL provides two ways to navigate to another page: forward to URL and forward to label.7. When using forward to URL. 8. select a function to use on the page. you can begin developing the Web page’s behavior. 9. onPreRenderFunction.jsp in the same directory as the page that used the navigation rule. relative links to files such as images and stylesheets must be relative to the original page. In the case of the JSF forward. a page named myPage. A JSF forward.browser’s address bar.jsp</to-view-id> <redirect/> </navigation-case> Building EGL JSF Web applications 409 . In this case. loads the new page in the browser without indicating to the browser that the location has changed. which is in the WebContent/WEB-INF folder of your EGL Web project. In the functions defined in the onConstructionFunction. because the browser is not viewing the same page that it requested from the servlet. In this case.egl. the request information is available to the new target page. For example. you can use forward to URL but not forward to label.jsp to a file named myPage02. To find the navigation rule that points to a page. When you know the navigation rule of the target page. rather than the forwarded target page. This navigation rule will result in a JSF forward as described above. look in the faces-config. Forwarding to a label When navigating from page to page within an EGL application. This file lists the rules and the pages to which those rules lead. not to be confused with an EGL forward statement. 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. to forward to the page myPage. By default. For example. for example. the label is myPage and the link refers to a page named myPage. use forward to label. use a relative URL reference.xml file.. though it is displaying the new target page. because the browser will interpret the links relative to the original page. To navigate to a page in a different EGL Web project. In this case.jsp might have a JSF Handler named myPage in a file named myPage. you must know the name of the JSF navigation rule that points to the target page. to link from the page myProject01/myPage01. use the following navigation rule: <navigation-case> <from-outcome>myPage02</from-outcome> <to-view-id>/.jsp</to-view-id> </navigation-case> The navigation rule contains two strings: a label for the rule and a relative link to the target page. including the loss of any request information that was passed to the first page. the browser and servlet are out of sync. Note the beginning slash before the file name of the page. the navigation rule for this page is myPage. However./myProject02/myPage02. use the following code: forward to label "myPage". the browser believes that it is still at the original page location. This mismatch can cause problems. To forward the user from one page to another. The previous example used a navigation rule that looks like this: <navigation-case> <from-outcome>myPage</from-outcome> <to-view-id>/myPage.jsp in a project named myProject02. which is a requirement for the navigation rule.jsp. you can use the EGL forward statement to send the user’s Web browser to that target page. or onPostRenderFunction properties of a JSF Handler. By default. When forwarding to another page controlled by an EGL JSF Handler.jsp". view = "myPage. as explained in “Running a Web page on a server” on page 448. you can leave the parameters out of the functions if you do not plan to use the passed data in that function. JSF uses a redirect rather than a forward when navigating from a page in one project to a page in another project.com". set the functions defined in the JSF Handler properties onConstructionFunction./myPage02.jsp. Related reference JSF Handler part forward considerations for JSF “Forwarding data between Web pages” You can use the forward statement to pass data from one Web page to another when you transfer control.jsp"} function onPreRender(myIntVariable int. Follow these steps to pass data between two Web pages: 1.faces or . You can also specify a relative URL: forward to URL ".. just like any other function would receive parameters.ibm. 2. you can specify a URL relative to the context root.jsp". See “Navigating among Web pages with navigation rules” on page 408 for information on forwarding to a different Web page. In the page that will receive the data. the following JSF Handler is set to receive an integer and a character parameter: handler myPage type JSFHandler {onPreRenderFunction = onPreRender. the specified functions must have matching parameters because all functions receive the passed data. Forwarding to a URL 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. be sure to use the correct extension of . and onPostRenderFunction to receive the parameters. Finally. However. use a forward statement and include the data in the same order as the functions that will accept it: 410 EGL Programmer’s Guide . For example. myCharVariable char(100)) end end If you define more than one of these JSF Handler properties. Forwarding data between Web pages You can use the forward statement to pass data from one Web page to another when you transfer control. or the directory that contains all of the projects on the server: forward to URL "/myProject02/myPage02. In the page that forwards the data. onPreRenderFunction.The <redirect/> tag is required for a navigation rule pointing to a target page in a different project. and their types must be compatible with the types defined in the functions of the target page. which is represented at run time by a page bean. EGL works closely with JavaServer Faces (JSF) navigation functionality to control page navigation in this way. whether the bean was in the user’s session or not. this function runs each time the user visits the page. onPostRenderFunction. the onConstructionFunction runs again when the user returns to the page because the page bean must be reloaded. 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. forward myInteger. this function runs only the first time that the user visits the page. and onConstructionFunction allow you to specify functions that run at different points in the page’s life cycle. “Executing commands when a page loads” A JSF Handler can include functions that run automatically when the page loads. the bean is still available. for pages set to session scope. In this case. because the bean is recreated each time. Building EGL JSF Web applications 411 . The variables must be separated by commas. the onPreRenderFunction runs the first time the page bean is loaded. the page bean is removed from the session when the user moves to another page. If the scope of the page is set to session (the default). The JSF Handler properties onPreRenderFunction.myInteger int = 5. However. even if the user browses away from the page. except when the page is redisplayed due to a JSF validation error. In this case. the bean does not remain active when the user browses away from the page. v The function that is specified in the onPreRenderFunction property is not affected by the scope of the page. If the scope of the page is set to request. any data stored in the bean is lost. and the bean must be loaded again if the user returns to the page. In this way. Use onPreRenderFunction instead. This function runs each time the server begins rendering the page. even if the scope property is set to session. myChar to "myPage". This function is useful for one-time initialization tasks. EGL loads the JSF Handler. forwarding the user from one page to another and passing data between pages. Related reference “Navigating among Web pages with navigation rules” on page 408 A JSF Handler can control the navigation on a Web site. When these functions run depends on the value of the scope property of the page. JSF Handler part forward Executing commands when a page loads A JSF Handler can include functions that run automatically when the page loads. the bean remains active during the user’s session. If the user returns to the page. For pages set to request scope. v The function that is specified in the onConstructionFunction property runs when the page bean is loaded. When the user visits an EGL-controlled Web page for the first time. Therefore. myChar char(100) = "Hello". if the cancelOnPageTransition property of the JSF Handler is set to yes. See onConstructionFunction for more information on this property. and whenever the page is redisplayed due to a JSF validation error.Command from the Enhanced Faces Components drawer of the Palette view.jsp. 3. create a new Web page named loadTest. This function runs the first time the page bean is loaded. v You can specify the same function for more than one of these properties. but it runs every time the server finishes rendering the page. whenever another page directs the user to this page. 7. whenever another page directs the user to this page.jsp"} numberOfLoads int. v If the functions accept parameters. scope = session.jsp page.whenever the user refreshes the page. On the loadTest.". From the Page Data view. Now the variable in the JSF Handler is bound to the output field on the page. messageString string. messageString = "You have viewed this page " + numberOfLoads + " times. Save the JSF Handler and close it. drag messageString directly onto the output field. The following example of a JSF Handler illustrates the use of two of these functions: 1. Alternatively. v The function that is specified in the onPostRenderFunction property is similar to the onPreRenderFunction. the parameters must match. add an Output field from the Enhanced Faces Components drawer of the Palette view. onPreRenderFunction = onPreRender. Open the JSF Handler of the new page by right-clicking the open page in the editor and then clicking Edit Page Code. end function forwardBack() forward numberOfLoads to "loadTest". add a Button . end function onPreRender(incomingNumber int) numberOfLoads = incomingNumber + 1. function onConstruction() numberOfLoads = 0. whenever the user refreshes the page. Change the code in the JSF Handler to match this example: package jsfhandlers. 2. handler loadTest type JSFHandler {onConstructionFunction = onConstruction. 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. end end 4. but this means that the function might run more than once. view = "loadTest. 5. 412 EGL Programmer’s Guide . and whenever the page is redisplayed due to a JSF validation error. In an EGL Web project. If you specify more than one of these properties. you can define parameters in one function but not in another. Next to the output field. 6. These functions have the following limitations: v The functions specified in the onConstructionFunction and onPreRenderFunction properties cannot access the JSF component tree as explained in “Accessing the JSF component tree with the source assistant” on page 454. However.″ In this case. because this function is called after the page is rendered and sent to the browser. and republish the project to the server. the variable will never exceed 1 because the onConstructionFunction function sets the variable to zero each time you refresh the page. However. these functions can use sysLib. v The functions specified in the onConstructionFunction and onPreRenderFunction properties cannot set the error message for a component with sysLib. the changes to the page will not be visible to the user until the page is refreshed. the user can select one of these options or continue typing different text: Building EGL JSF Web applications 413 . sets the variable to 1. 9. see the topics dedicated to these properties.setErrorForComponentID(). Related reference onPreRenderFunction onPostRenderFunction onConstructionFunction Providing type-ahead support for input controls JSF text input controls can use the JSF type-ahead feature to anticipate what a user might be typing into the input control. v These functions can use a forward to URL statement. The function specified in the onPostRenderFunction can use sysLib. and sets the message string variable to ″You have viewed this page 1 times.setError(). The first time that you run this page. If you try the example with scope set to request. 10. but the onConstructionFunction function is not. Remember to save your changes to the JSF Handler.″ Each subsequent time you reload the page. drag forwardBack() directly onto the command button. From the Page Data view. demonstrating that the onPreRenderFunction function is running each time. the function specified in the onPreRenderFunction property runs.setError(). generate. the function specified in the onConstructionFunction property runs first and sets the numberOfLoads variable to zero. Input controls with type-ahead present a list of options based on the first few characters that the user types into the control. For more information. but not forward to label. The function specified in the onPostRenderFunction property can access the JSF component tree. Then. Save the page and generate the project. it displays ″You have viewed this page 1 times. Then. the variable will increase by one.8. Run the page on a server. Now the button is bound to the function in the JSF Handler. This method works just like the validValues method. set the typeahead property to YES: state STRING {typeahead = YES}. 1. the type-ahead feature filters the options to match the new values that the user has typed into the field: EGL can obtain the options for the type-ahead input field in one of three ways: v EGL can compare what the user has typed with the values in the validValues property for the variable bound to the control. create a character or numeric variable to represent the value typed in the input field on the page: state STRING. using either the validValues or validatorDataTable properties: v If you use validValues. Using options from a Data Table or from a list of valid values The simplest way to provide options for the type-ahead function is to associate the variable bound to the field with a list of options. Typically. v You can define a custom function to assemble an array of options to present to the user. In a JSF Handler part.As the user continues to type. 2. the type-ahead feature presents all of the values in the list of valid values that start with the same characters as the user has typed. In this case. but in this case. The steps for using type-ahead depend on which of these methods you use to obtain the list of options. specify the options as the values of the property: 414 EGL Programmer’s Guide . either in a Data Table or in a list of valid values. Associate the variable with a list of options. 3. type-ahead presents options that have the same starting characters as the characters that the user has already typed in. v EGL can compare what the user has typed with the values in a DataTable part specified in a variable’s validatorDataTable property. the function can return an arbitrary array of options. On the variable. dataTable stateAbbrevs type MatchValidTable {shared = no. and likewise with the letter ″N″ and the abbreviations beginning with ″N. Ensure that the Control type for the variable is set to Input field. v If you use a Data Table. 7. Click Finish. the function must return an array of STRING. providing the same information as in the validValues example above: package data. Type-ahead can be used only on input controls.["NJ"]. You may need to bring the Data Table part into scope with an import statement. An input control is created on the page that is bound to the variable in the JSF Handler and is configured to use type-ahead. states beginning with the letters ″A″ and ″N.″ When the user types the letter ″A″ into the input control."AL". set the validatorDataTable property on the variable to the name of the Data Table. validValues = ["AK"."AZ". ["NM"]."ND"]}.["NH"].["AL"]. drag the variable from the Page Data view onto the Web page. The matching Data Table might look like this example. representing the type-ahead options presented in the input control. 6. resident = no} 3 abbrev char(2). 5. On the Web page. you can create a function that dynamically determines the options at run time."AR". Also.["ND"] ]} end Data Tables used with type-ahead must be of the type MatchValidTable.state STRING {typeahead = YES. "NC".["NE"].upperCase( key )."NV". representing the text that the user has typed into the input control. click Updating an existing record.["NV"]. // Return any state names for which //the key is a substring of the full state name.″ When using type-ahead with a list of valid values."NY". key_upper string = strlib. the valid values cannot contain a range.["NY"]. 1. The Insert Record window opens. the valid values are the abbreviations of U.["AR"]. Using options from a custom function For more control over the options presented in type-ahead. In the Insert Record window. state string {typeahead = YES. {contents = [ ["AK"]."NJ". ValidatorDataTable = data. In this example. This function must accept exactly one parameter: a STRING."NH".S. "NM".stateAbbrevs}. 4. create the function that determines the type-ahead options. ["NC"].["AZ"]. function getStateChoices( key string in ) returns( string[] ) results string[0]. type-ahead will provide the abbreviations beginning with ″A″."NE". In a JSF Handler or a Library part. Building EGL JSF Web applications 415 . The code if ( strlib. // Search for values with the same starting characters. The Insert Record window opens. 4. On the variable. ["NORTH DAKOTA"]. create a character or numeric variable to represent the value typed in the input field on the page: state STRING. In a JSF Handler part. In the Insert Record window. results. drag the variable from the Page Data view onto the Web page. and if so. key_upper ) == 1 ) // This value starts with the same characters as the key. // Add it to the list of options. end end return( results ). ["NEW YORK"] ]} end 2. with the values in a Data Table. the function could retrieve data from any source. for ( i int from 1 to syslib. ["ARIZONA"]. ["ARKANSAS"]. ["NEBRASKA"].fullname[i] ). On the Web page. value = strlib.fullname[i] ). click Updating an existing record.fullname[i] ). package data. {contents = [ ["ALASKA"].appendElement( states. 416 EGL Programmer’s Guide .value string. ["NEW HAMPSHIRE"]. ["NEVADA"]. ["ALABAMA"]. the code results. key_upper ) == 1 ) determines if the value in the Data Table starts with the characters that the user has typed. such as a database or record variable. resident = no} 3 fullname char(20).size( states ) ) // Compare each value in the data table to the key. dataTable states type MatchValidTable {shared = no. represented by the variable key.indexOf( value. 5. Although this function uses information from a Data Table like the following example. end This function compares the text that the user has typed into the input control. ["NEW JERSEY"]. set the typeaheadFunction property to the name of the function: state STRING {typeaheadFunction = getStateChoices}.upperCase( states. adds the value in the Data Table to the array of options for type-ahead. ["NEW MEXICO"].appendElement( states.indexOf( value. if ( strlib. ["NORTH CAROLINA"]. 3. In the Properties view. Click Finish. On the Web page. Type-ahead can be used only on input controls. You can set the size of the type-ahead field. define a character or string variable to receive the clicked value. set the options for the type-ahead feature.) Building EGL JSF Web applications 417 .6. In a JSF Handler. This snippet has the following prerequisites: 1. 3. follow these steps: 1. For more information on the options associated with type-ahead. The names of the JSP identifiers have not been changed from the default. Related reference validValues validatorDataTable typeahead typeaheadFunction Retrieving the value of a clicked row in a data table The getClickedRowValue snippet in the EGL drawer of the Snippets view is a function that retrieves the hyperlinked value of a clicked row in a data table. how long the control should wait before providing options. 2. not session. 3. 2. The page is defined as request in scope in faces-config. see Typeahead Complete Component. This snippet must be placed in an EGL JSF Handler part. To set these options. Place the cursor on a blank line in the JSF Handler where it is legal to add a function. An input control is created on the page that is bound to the variable in the JSF Handler and is configured to use type-ahead. and how the input control should behave while waiting for EGL to return the options. open the Properties view. Setting options for type-ahead You can customize the appearance and behavior of the type-ahead functionality on the page.xml. The type-ahead icon is located immediately to the right of the input control on which type-ahead is enabled. (This snippet includes an entire EGL function. follow these directions: 1. To insert and configure this snippet. 7. click the type-ahead icon to select it. The JSP page has a data table. With the type-ahead icon selected. 2. Ensure that the Control type for the variable is set to Input field. For more information. you can create your own snippets. In the Insert Template window. The hyperlink links to its own page.3. 7. For example. "javax. "getViewRoot"). specify the name of the JSP page. "form1:table1:param1"). javaLib. drag the Set cursor focus snippet to a blank line within the <script> tag you just added.store((objId)"root". not the code of the JSF Handler part. In the EGL drawer of the Snippets view. 4.FacesContext".invoke((objId)"parm". end Related concepts “Code snippets” on page 164 Snippets are code objects that are reusable programming objects. 6. 3. "getCurrentInstance"). 5. The code that is inserted by this snippet follows: function getVal() javaLib. In the snippet code. (objId)"root".snippet code goes here --> </script> 2. The Insert Template window opens. use [3] to set focus to the fourth field on the page. To insert and configure this snippet: 1. type the name of the variable as the value of the receivingVar variable. Click Insert.faces. From the EGL drawer of the Snippets view. set the action property to the getVal() function. 8. Add a <script> tag within the <head> tag of the JSP file as in this example: <script type="text/javascript"> <!-. 418 EGL Programmer’s Guide . For more information. 9. Snippets can be a piece of code or a complete programming task. From the Enhanced Faces Components drawer in the Palette view. "getValue"). see Inserting EGL code snippets. "findComponent". (objId)"context".store((objId)"context".store((objId)"parm". Related tasks “Inserting code snippets into EGL and JSP files” on page 165 Setting the focus to a form field The Set cursor focus snippet in the EGL drawer of the Snippets view is a JavaScript function that sets the cursor focus to a specified form field on a Web page. For the target of the command hyperlink. add a command hyperlink to a field in the data table. The form fields are numbered beginning with zero. see Inserting code snippets into EGL and JSP files. replace both instances of [n] with the number of the form field which will receive focus. double-click the Get clicked row value snippet. On the All tab of the Properties view. In addition to the default snippets provided in the workbench. This snippet goes into the code of the JSP file. 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. javaLib. It must be placed within a <script> tag in a JSP page. recVar = javaLib.context. "> 6. Save the file. 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.select()." as in the following example: <body onload="setfocus().setError system function sets the message of a display error component.4. replace both instances of form1 to the value of the ID attribute of the form to which you want to set focus. and JSF finds the display error component that is associated with an input component on the page. you pass the name of an EGL variable in the JSF Handler to the function. usually to notify the user of a problem on the page.setErrorForComponentID function sets the message of a display error component. The display error component is represented by an <h:message> JSF tag.setError and sysLib.getElementById('form1'). A JSF Handler can set the value of error message components in these ways: v The sysLib. Follow these steps to display an error message on a Web page with EGL: Building EGL JSF Web applications 419 . you can set the value of these error message components from the page’s JSF Handler.elements[n]. 5. you can create your own snippets. The code inserted by this snippet is as follows: function setFocus() { document. given the name of a variable that is bound to an input component on the page.focus(). v The sysLib. With the sysLib. given the ID of an input component on the page. document. this type of component must specify the ID of an input component on the page. } Related concepts “Code snippets” on page 164 Snippets are code objects that are reusable programming objects. In addition to the default snippets provided in the workbench.elements[n]. 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. Related tasks “Inserting code snippets into EGL and JSP files” on page 165 Displaying error messages on Web pages JSF Web pages can include error messages to provide feedback. For this reason. add the attribute onload="setFocus(). In the snippet code. Snippets can be a piece of code or a complete programming task. and the ID of the input component for which it provides feedback is specified in its for attribute. – It displays only the error messages not associated with a specific component. In other words.setErrorForComponentID system functions. In the <body> tag of the JSP page. JSF shows the error message in the display error component associated with the specified input component. which in turn to that specified EGL variable.getElementById('form1'). such as the dialect. 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. The locale identifies the language of the strings in the bundle and.inputString_Ref}"> </h:inputText> <h:message id="message1" styleClass="message" for="inputComponent"> </h:message> 420 EGL Programmer’s Guide . a resource bundle that contains English as it is spoken in the United States might be named resourceBundle_en_US. Optionally. Optionally. In the following example. the error message in the resource bundle might look like this: error02=The specified value is shorter than five characters: {0} 2. see “Locales for resource bundles” on page 431. Click the display error component to select it. Inserts are represented by an integer in braces and will be replaced with a value you specify when you display the error message. From the Palette view. You can use JSF display errors only with input components. drag a Display Error component onto the page.1. 7. locale The locale of the resource bundle. and {2}. As described in “Creating a resource bundle” on page 430. create an input component. On a Web page in an EGL Web project. such as en_US. 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. create a resource bundle to hold the error messages.properties. add messages to the file in the format keyname=messageText. In the Properties view. you can include inserts in the message. optionally. more specific information about the specialization of the language. For example. {1}. Error messages can contain several inserts per message.properties prefix The prefix of the resource bundle file name is arbitrary. 4. 5. or geographic location. Bind the input component to a variable in the JSF Handler associated with the page. At this point. In short. such as this: error01=The specified value is too short. 6. but the prefix must be the same for each resource bundle in the application. 3. such as an input text component. under Display error message for the component.inputString}" binding="#{errorMessageTest. With one insert. the code of the Web page shows that the error message is associated with the input component. For more information on locales. variety. you will create a file named in the following format: prefix_locale. set the Id field to the ID of the input component. Then. You should put the display error component near the input component so it will be clear which component is associated with the error message. numbered such as {0}. myField. This parameter must be compatible with the STRING type."). Use sysLib. The quoted key of the message in the resource bundle. v If you want to use an error message in a resource bundle with zero or one inserts. because sysLib. a period.setError(inputString. Following is an example of this method: SysLib. b. This example assumes a resource bundle with a message definition similar to this example: error02=The specified value is shorter than five characters: {0} v If you want to use an error message in a resource bundle with two or more inserts. Set the userMessageFile build descriptor option to the prefix of the resource bundle file name.setError or sysLib. as in myRecord.setError supports error messages with only zero or one insert: a. For example. b.jsp". 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.setError. For a field within a record. In the JSF Handler associated with the page. the value to be used in that insert. The unquoted name of the EGL variable in the JSF Handler. inputString). If the message expects an insert. 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. you must use sysLib.getMessage to put the inserts into the message and create a string containing the complete message: errorMessageString string = sysLib. msgResource = "resourceBundle"} In this case. and the field name.setError(inputString. "". The unquoted name of the EGL variable in the JSF Handler. if you want to issue an error related to the variable inputString. 9. using an error message with the key error02 and the same variable as an insert value. An empty string. For a field within a record.setErrorForComponentID system function to set the error message.getMessage in coordination with sysLib. pass these three parameters in order: a. as in myRecord. the file name excluding the extension and the locale code): handler errorMessageTest type JSFHandler {view = "errorMessageTest. Building EGL JSF Web applications 421 . Use the sysLib. [inputString. you would use this EGL code: SysLib. "error02". pass these three parameters in order: a.myField. the resource bundle is named resourceBundle_en_US. c. Save the page. and the field name. 10.8. b. The text of the error message as a string. specify the record name. c. a period.properties and so the msgResource property is set to resourceBundle. specify the record name. "This is the text of the error message. set the msgResource JSF Handler property to the prefix of the resource bundle (that is. the same value as you set in the msgResource JSF Handler property.getMessage("error03". "five"]). Also. it assumes a resource bundle named resourceBundle_locale. 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. similar to the previous examples.setError. consisting of the ID of the form on the page.c. v In most cases.setErrorForComponentID in a way similar to sysLib. if you know the ID of the input component with which you want to associate the error message."). the following JSF Handler tests a value typed into an input component on a Web page to see if the value is long enough.setErrorForComponentID takes the quoted identifier of the input component. It must be at least {1} characters long.jsp". as in this example: error03=The string {0} is too short.setError("The string is too short. However. It also assumes a message in the resource bundle with a key error01. If the value is too short. "". as explained above. since it is usually more convenient to use the EGL variable name as the reference point for the error message. "error01".setError without specifying a variable name: SysLib. Pass the error message string to sysLib. you will use sysLib. errorMessageString). where locale is the locale code of the language you are using. Related reference 422 EGL Programmer’s Guide . This example assumes an error message in the resource bundle with two inserts. v If you want to display the error message on the display errors component. the JSF Handler displays an error message. "error02". inputString). except that sysLib.properties.setError(inputString. rather than a display error component associated with a specific input component.setError(inputString.setError: SysLib.setError to set the error message.characterLen(inputString) < 5) SysLib. For example. rather than the name of the EGL variable: SysLib. a colon. pass the error message to sysLib.setErrorForComponentId("form1:inputComponent". See Display Errors. function validateString() if (StrLib. handler errorMessageTest type JSFHandler {view = "errorMessageTest2. you can use sysLib. This example assumes an input component on the page with the ID inputComponent and a display error component associated with it. inputString). The example uses a message in that resource bundle file similar to the following: error02=The specified value is shorter than five characters: {0} JSF can also set the values of error message components as part of user input validation. msgResource = "resourceBundle"} inputString string. and the ID of the input component. the cursor must be placed where a function is legal. Set the value of KeyColumn to the primary key column of the table.call this function passing //the EGL_RecordName Record as a parameter EGL_RecordNameOld EGL_RecordName. //you would insert after this call move EGL_RecordNameNew to EGL_RecordNameOld byName.setError() setErrorForComponentID() msgResource 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. you can create your own snippets. This snippet inserts the following code: Function updateRec(EGL_RecordNameNew EGL_RecordName) //Function name . 5. //And replace the row in the database. Snippets can be a piece of code or a complete programming task. sysLib.rollback(). //cancel all database updates //(assuming this is permitted by your database) // and call a custom error handling routine or something end end Related concepts “Code snippets” on page 164 Snippets are code objects that are reusable programming objects. Save the file.Table_Key_column_ID = EGL_RecordNameNew. Click Insert. set the value of TableName to the name of the table you are updating. 6. //Commit your changes to the Database onException (ex AnyException) //If the update fails. //Note that if you had custom processing to do. double-click the database update snippet. 3. //Get the existing row. In the EGL drawer of the Snippets view. get EGL_RecordNameOld forUpdate. //used to lock the table row. In the EGL editor. and obtain the existing row values //prior to update try EGL_RecordNameOld. This snippet is intended to be placed in an EGL library.commit().. In addition to the default snippets provided in the workbench. In the Insert Template window. place the cursor where you want the snippet to go. //A copy of the Record. sysLib. //Move the updated values to the copy-row replace EGL_RecordNameOld. Because this snippet is a complete EGL function. The Insert Template window opens. To insert and configure this snippet: 1. 4..Table_Key_column_ID. Related tasks “Inserting code snippets into EGL and JSP files” on page 165 Building EGL JSF Web applications 423 . 2. pass a string identifier and an EGL variable to the session object: myVar string = "Hello". myVar). To retrieve the value later. handler sessionPageOne type JSFHandler {scope = request. the server loads the page’s JSF Handler. If the scope property of the JSF Handler is set to session and its cancelOnPageTransition property is set to no.jsp"} userRecord sessionRecord. stores that bean in the session object as a session variable. However. the bean remains in the session object until the session ends or the bean times out. forward to "sessionPageTwo". If the application needs to remember details about the user’s actions. A more complete example of two JSF Handlers that set and retrieve a session variable follows. it must explicitly store that information somewhere. J2EELib. variables in the Handler can retain their values during the session. function storeAndForward() J2EELib. Setting and retrieving session variables To set a session variable. end 424 EGL Programmer’s Guide . 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. represented at run time as a page bean. When a user visits an EGL-controlled Web page.setSessionAttr("mySessionRecord". A much more efficient way to use the session object (and. Still. userRecord). J2EELib. putting data in the session object is useful in the short term if done efficiently.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. page beans can take up large amounts of memory.getSessionAttr system function with the same identifier and a new variable: myVarFromSession string. 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.getSessionAttr("mySessionVar". not all the variables in its Handlers. even if the user moves to another page. use the J2EELib. Web applications often store these details in the user’s session object. In this way. view = "sessionPageOne. and uses that bean to provide the logic for the page.setSessionAttr("mySessionVar". In this way. The first Handler sets the session variable: package jsfhandlers. an area of memory on the server that stores temporary information about one user’s transactions and interaction with the Web application. myVarFromSession). in turn. you retain only the data the application needs. clearSessionAttr function: J2EELib. end end Like the previous Handler. This snippet goes Building EGL JSF Web applications 425 .end record sessionRecord type BasicRecord userName string. submittedRecord). To insert and configure this snippet: 1. 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. If the session variable is not present. function onPreRender() J2EELib. this example assumes that you have bound the fields in the record to output variables on the sessionPageTwo. the record is added to the user’s session variable. along with a command button bound to the storeAndForward function. and the user is forwarded to another page. When the user clicks the button bound to the storeAndForward function. end This example assumes a Web page named sessionPageOne.jsp page. From the EGL drawer of the Snippets view. onPreRenderFunction = onPreRender} submittedRecord sessionRecord. idNumber int. represented by the following JSF Handler: package jsfhandlers. The snippet must be placed within the <head> tag of a JSP page after the <pageEncoding> tag. drag the Auto redirect snippet to a blank line in the JSP file within the <head> tag of the page. Related reference EGL library j2eeLib 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.clearSessionAttr("mySessionRecord").getSessionAttr("mySessionRecord". the customized code forwards control to a different Web page. This Handler retrieves the data from the session variable and assigns it to a variable for temporary use within the JSF Handler.jsp". For more information on session-related functions. Also.clearEGLSessionAttrs function.jsp with two input fields bound to the fields in the record. handler sessionPageTwo type JSFHandler {view = "sessionPageTwo. you can remove all EGL-controlled session variables from the user’s session object with the J2EELib. see ″EGL library j2eeLib″ in the EGL Language Reference. Each resource bundle is specific to a human language. you must create a resource bundle for each language that you want to support. To use a translatable string as the value of a JSF field. Also. 2.jsp". 5. set the SessionAttribute variable to the name of the session variable that is being tested. Snippets can be a piece of code or a complete programming task. you must bind the field to the translatable string directly. you cannot assign the key of the translatable string to an EGL variable bound to the field. The default value is EGLWeb. The sections below cover some different uses of these strings on web pages. To localize a Web application.sendRedirect(redirectURL).getAttribute("userID") == null )) { String redirectURL = "http://localhost:9080/EGLWeb/faces/Login. you cannot bind that field to an EGL variable at all.jsp. Using translatable strings as output fields To use a translatable string as the value of a JSF field. so that when you switch to a different resource bundle. See “Storing data in the user’s session” on page 424. The Insert Template window opens. The code inserted by this snippet is as follows: <% if ((session. The default value is Login. see Inserting code snippets into EGL and JSP files. 6. These resource bundles contain strings to be presented on the Web pages at run time. Set the PageName variable to the name of the page that the browser will be redirected to if the session variable is absent. } %> Related concepts “Code snippets” on page 164 Snippets are code objects that are reusable programming objects. such as an output field. you can create your own snippets. you can use translatable strings as the error messages for Web pages. response.into the code of the JSP file. In the Insert Template window. When you have customized the values in the Insert Template window. as in these steps: 426 EGL Programmer’s Guide . Save the file. Set the ApplicationName variable to the name of your project or application. the strings on the Web pages switch to a different language. Instead. not the code of the JSF Handler part. In addition to the default snippets provided in the workbench. Related tasks “Inserting code snippets into EGL and JSP files” on page 165 “Storing data in the user’s session” on page 424 Localizing text in Web applications You can localize your Web application so that the Web pages will display in different languages. For more information. click Insert. 4. 3. The default value is UserID. see “Displaying error messages on Web pages” on page 419. You can use translatable strings as the text on Web pages. but in this case you will use a string from a resource bundle instead. Select the string that you want to use on the field and click OK. 2. Set your workbench preferences to use a default mnemonic to represent the resource bundle: a. In either case. 5. In the Properties view. In the Choose/Create Properties File window. Next to the Value field. 6. such as an output field. Click OK to close the Choose/Create Properties File window. On a JSP file in your EGL Web project. Building EGL JSF Web applications 427 . the server will use the string as the value of the field. expand EGL and click Page Designer. 2. it must match the mnemonic that is used in the File identifier field in the Choose/Create Properties File window as explained earlier. In the Preferences window. 10. 3. or go to the New File tab to create a new resource bundle. The table on the String Resource tab shows the strings from the file. you select a variable from your JSF Handler from this window. create a resource bundle to hold the strings that you want to use in the application. this mnemonic is labels. By default. click the Select Page Data Object button. but if you change it. from the Enhanced Faces Components drawer of the Palette view . you might create a resource bundle named myBundle_en_US. Using translatable strings in EGL properties You can also use translatable strings as the values of certain EGL properties. if you are using American English. By default. See “Creating a resource bundle” on page 430. For example. type a mnemonic for the translatable strings. In the resource bundle. This field shows the text for the component. 8. You can use the strings that are already there or add new strings with the Add Resource button. it must match the mnemonic set in the EGL Page Designer preferences as explained in “Setting preferences for Web projects” on page 465. as in this example: myString01=Hello there! myString02=Welcome to my Web page. but if you change it. enter a mnemonic to represent the file in the File identifier field. Typically. find the Value field. 9. adhere to the naming and placement conventions explained in “Creating a resource bundle” on page 430. d. Click Add Properties File.properties. The field shows the key of the translatable string. select the resource bundle file that you want to use on the Existing File tab. Click the field to select it. most notably DisplayName: 1. c. After you have selected or created a resource bundle file. 3. When you run the page. b.1. In the jsfhandlers package of your project’s Java Resources folder. Click Window → Preferences. add keys and string values for the text that you want to use on the Web pages. drag onto the page a JSF output component. Click OK. In the Loadbundle variable field. The Select Page Data Object window opens. 4. this mnemonic is labels. 7. Go to the String Resource tab. but a string from the resource bundle. In the JSF Handler for the Web page. add a <locale-config> tag: 428 EGL Programmer’s Guide . drag the variable onto the page. and the var attribute specifies the start of the translatable string used in the code.xml file. the names of the other resource bundles must begin with myBundle. 6.4. This file is found in the folder WebContent/WEB-INF. This code specifies that the translatable strings represented on the page as labels. directly below the code <f:view>: <f:loadBundle basename="myBundle" var="labels"/> 7. This symbol indicates that the value comes from the given key in the resource bundle. 5. If the name of your first resource bundle is myBundle_en_US. Create one resource bundle for each language that your application supports. the code created in the JSP is as follows: <hx:commandExButton id="buttonMyFieldString1" styleClass="commandExButton" type="submit" value="#{labels. On the JSP that is associated with the JSF Handler._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. This example assumes that your resource bundles are named myBundle_locale.keyname are found in the resource bundle files named with the prefix myBundle. that string will appear prominently at the top of the page. if you drag the variable in the previous example onto a page. Note the percent sign (%) in the value of DisplayName. See ″Creating a page from an existing JSF Handler part″ in “Creating a Web page” on page 392. 2. Using translatable strings for different languages at run time To use translatable strings for different languages at run time: 1. The basename attribute of this tag specifies the prefix of the resource bundle file name. In the code of the JSP. In the Project Explorer view. Within the <application> tag of the faces-config. For example.xml to open it. composed of the mnemonic that you entered in the preferences plus the key that you used in the JSF Handler. Action = "DoSomething"}. you can also use a translatable string for the title property of the JSF Handler. DisplayName = "%myString01".properties and that you used the default mnemonic labels. 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. respectively.properties. 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. add the following line of code.myString01}" actionListener="#{testResourceBundle. Set the values of the basename and var attributes to the prefix of your resource bundle and the mnemonic. The file name of each resource bundle in the application must have the same prefix. and when EGL creates the page. 3. double-click the file faces-config. If you use this method. if your application supports American English. add the following code within the <locale-config> tag: <default-locale>de</default-locale> It is good practice to specify a default locale. Related concepts “Locales for resource bundles” on page 431 Related tasks “Customizing runtime messages” on page 152 “Creating a resource bundle” on page 430 Related reference displayName help Building EGL JSF Web applications 429 . </application> </faces-config> If you define a default locale. Note: Each locale that is defined in this file must have a matching resource bundle defined for that locale. but it is not required. 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> . For example. For example. Save and close the file. 7.. 5.. add a <default-locale> tag that contains the locale of the default resource bundle. </application </faces-config> 4. Test your application with your Web browser set to different languages to see the different strings. add a <supported-locale> tag for each locale that your application supports. 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. Following the <default-locale> tag.. Within the <locale-config> tag. 6.. you must also define that locale as a supported locale.<faces-config> <application> <locale-config> </locale-config> . but the prefix must be the same for each resource bundle in the application. locale The locale of the resource bundle. Click Next. To create a resource bundle: 1. but each resource bundle must have a different locale and the same prefix. 8.Creating a resource bundle A resource bundle contains a series of strings to be presented at run time. The file name of the resource bundle must be in this format: prefix_locale. For example. or geographic location. With resource bundles. Click Finish. variety. This key is placed in the Web pages to indicate which text from the resource bundle to insert. you can localize your applications by including a different resource bundle for each language that you want to support. In the Project Explorer view. The locale identifies the language of the strings in the bundle and. 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. and the new file opens in the editor. a key named WelcomeText might indicate introductory text to be shown at the top of a page.properties. stringtext The text that is associated with the key. 4. a resource bundle that contains English as it is spoken in the United States might be named resourceBundle_en_US. Each resource bundle must define a string for each key that is used in the application. The new file is created in the folder that you right-clicked. click New → Other. right-click the folder in which you want to create the resource bundle. From the menu. The New window opens. This folder must be within the Java Resources folder of an EGL Web project. In the File name field. In the New window. Add strings to the new resource bundle in the following format: keyname=stringtext keyname The key name of the string. see “Locales for resource bundles” on page 431. expand General and click File. For example. For more information on locales. a fatal error will be generated.properties prefix The prefix of the resource bundle file name is arbitrary. optionally. Related concepts “Locales for resource bundles” on page 431 Related tasks 430 EGL Programmer’s Guide . 2. 3. 7. more specific information about the specialization of the language. 6. Save and close the file. 5. such as the dialect. type a name for the new resource bundle. such as en_US. You can create as many resource bundles for your application as you want. or geographic location of the language. followed by a country code. Each additional identifier after the first identifier enables you to indicate a more specific language by specifying the dialect. The identifiers are separated with an underscore character. For example. the page uses the string values that are specified on the page at definition time. An English resource bundle might be named resourceBundle_en. In this way. 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. These two resource bundles might be named resourceBundle_no_NO_A.properties. For example.properties. if the user requests the locale no_NO_B. Locales consist of one to three identifiers. It is good programming practice to include a default resource bundle. A more complex locale includes a language code followed by a country code. while a British English resource bundle might be named resourceBundle_en_GB. before the . Alternately. The language code is part of the Java specification. If the user requests a locale that is more specific than any of the locales in the application.properties extension.properties and resourceBundle_no_NO_B.properties. variety. and GB indicates Great Britain. The simplest locales indicate a human language with a single identifier. The variant code is not part of the Java specification. The variant code defines a more specific dialect or variety of the language in the resource bundle. The locale indicates the specific human language of the strings in the resource bundle. the locale no_NO is used. This identifier is the language code of the language that is used in the resource bundle. The most complex locale includes a language code. For example. If no default resource bundle is specified. If the user requests a locale that exactly matches a locale in the application. The default resource bundle has no locale. Related tasks “Creating a resource bundle” on page 430 “Customizing runtime messages” on page 152 “Localizing text in Web applications” on page 426 Building EGL JSF Web applications 431 . and es indicates Spanish. The locale is indicated by the end of the file name. you could use the variant codes A and B to distinguish between two different varieties of Norwegian spoken in Norway. the language code en indicates English. the application uses a resource bundle with a more general locale. the country code US indicates the United States. you could define a standard type of Norwegian as the locale no_NO and define a variant as no_NO_B. The country code indicates a country where the dialect of the language is spoken. or if no locale can be loaded for the Web page. followed by a variant code. For example. an American English resource bundle might be named resourceBundle_en_US. but the only available Norwegian locale is no_NO. the resource bundle that represents that locale is the source of the strings that are used in the application.“Customizing runtime messages” on page 152 “Localizing text in Web applications” on page 426 Locales for resource bundles Each resource bundle has a different locale.properties. The country code is part of the Java specification. while still displaying the rest of the page. No other part of the page will be affected. Create the page and JSF Handler. The servlet calls the function in the JSF Handler indicated by the onPreRenderFunction property. running the functions indicated by the onConstructionFunction. however. indicate the user event that will trigger the AJAX request. as applicable. or external) and any parameters to include with the request. 5. 9. 6. The browser sends the request to the servlet. Indicate the area of the page that you want to change as a result of the AJAX request. 8. providing this function with the parameters in the request. 6. the JSF Handler is not aware of the changes. and onPostRenderFunction JSF Handler properties. either by clicking a link or by triggering a forward statement in the JSF Handler. Setting up a JSP file and a JSF Handler to use AJAX requests involves these general steps: 1. 5. You can set up an EGL-controlled JSP file to call the JSF Handler’s onPreRenderFunction and provide a limited update to the page. 4. The onPreRenderFunction function runs. 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. including the parameters specified in the request. The servlet sends the page to the browser. The following is the life cycle of a typical AJAX page in EGL: 1. This technique can make Web applications faster and more efficient than if an entire page had to reload after each user action. 3. 4. 2. Define the request to send from the page to the JSF Handler. if the user changes the value of input controls on the page. Write code in the JSF Handler to process the request. including the type of request (refresh.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. The cycle of AJAX requests continues until the user goes to another page. 3. On the page. The servlet renders the complete page. The servlet renders the portion of the page specified by the AJAX request and updates this portion of the page in the browser. the variables in the JSF Handler are not 432 EGL Programmer’s Guide . submit. 2. The user triggers the AJAX request. In other words. The user begins to fill out the input fields on the page. updating controls in the area on the page specified by the AJAX request. 7. Design the page and populate the page with JSF controls that are bound to variables and functions in the JSF Handler. it does not provide information on the state of the page to the JSF Handler. onPreRenderFunction. such as selecting or moving away from a particular text control. The JSF Handler receives these parameters along with the request. For more information. The J2EELib. see “Updating a page with a submit request” on page 439. The page might look like this example: Building EGL JSF Web applications 433 . Submit This type of request prompts the servlet to update the values of the controls in a specified area of the page. The AJAX request. triggered by the combo box. 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.updated to match the page controls to which the variables are bound. you can add one or more parameters to the request. For more information. see “Updating a page with a refresh request” on page 436. making the request more modular and efficient. Unlike what happens in the refresh request. the variables in the JSF Handler are not updated to the new values of the controls to which the variables are bound. as well as to update the values of the variables in the JSF Handler. because all of the variables are updated to match the current state of the page. see “Updating a page with a portion of another page” on page 442. Therefore. passes the selected operation and the two input controls to the onPreRenderFunction of the JSF Handler. it is not necessary to pass parameters with a Submit request. if there are any. 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. which performs the mathematical operation and updates an output control showing the answer.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. 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. For more information. If the JSF Handler needs information from the page to complete the refresh request. This limitation reduces the amount of data sent in the request.getQueryParameter() system function retrieves the parameters from the AJAX request. but as before. 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. Any value other than NULL indicates that the function has been called as the result of an AJAX refresh or submit request: if (J2EELib. field1_Ref}" styleClass="inputText"> </h:inputText> </td> </tr> <tr> <td align="left">Field2:</td> <td style="width:5px"></td> <td> <h:inputText id="input2" value="#{calculatorPage. charset=UTF-8"> <link rel="stylesheet" type="text/css" href="theme/stylesheet._postRender}"> <h:form id="form1" styleClass="form"> <TABLE> <TBODY> <tr> <td align="left">Field1:</td> <td style="width:5px"></td> <td> <h:inputText id="input1" value="#{calculatorPage.operation}"> <f:selectItem itemValue="add" itemLabel="add" /> 434 EGL Programmer’s Guide .field2_Ref}" styleClass="inputText"> </h:inputText> </td> </tr> <tr> <td align="left">Operation:</td> <td style="width:5px"></td> <td> <h:selectOneMenu id="operationComboBox" styleClass="selectOneMenu" value="#{calculatorPage.css" title="Style"> </head> <f:view> <body> <hx:scriptCollector id="scriptCollector1" preRender="#{calculatorPage.The following is the code of the JSP file: <html> <head> <title>calculatorPage</title> <meta http-equiv="Content-Type" content="text/html.field2}" binding="#{calculatorPage.field1}" binding="#{calculatorPage._preRender}" postRender="#{calculatorPage. operationComboBox"> </hx:ajaxRefreshRequest> </td> </tr> </TBODY> </TABLE> </h:form> </hx:scriptCollector> </body> </f:view> </html> The following is the code of the JSF Handler that goes with this page: package jsfhandlers.getQueryParameter("$$ajaxmode") == null) output = "Enter values and an operation.jsp"} field1 float.getQueryParameter("input1").getQueryParameter("operationComboBox")) when ("add") output = param1 + param2. handler calculatorPage type JSFHandler {onPreRenderFunction = onPreRender. param2 float = J2EELib.input2. when ("divide") Building EGL JSF Web applications 435 . function onPreRender() if (J2EELib.<f:selectItem itemValue="subtract" itemLabel="subtract" /> <f:selectItem itemValue="multiply" itemLabel="multiply" /> <f:selectItem itemValue="divide" itemLabel="divide" /> </h:selectOneMenu> <hx:behavior event="onblur" target="operationComboBox" behaviorAction="get" targetAction="updatablePanel"></hx:behavior></td> </tr> <tr> <td align="left">Output:</td> <td style="width:5px"></td> <td> <h:panelGroup id="updatablePanel" styleClass="panelGroup"> <h:outputText id="output" value="#{calculatorPage.". field2 float. else calculateAnswer(). when ("subtract") output = param1 .param2.output}" binding="#{calculatorPage.getQueryParameter("input2"). when ("multiply") output = param1 * param2. view = "calculatorPage. output string. operation string. case (J2EELib. end end function calculateAnswer() param1 float = J2EELib.output_Ref}" styleClass="outputText"> </h:outputText> </h:panelGroup> <hx:ajaxRefreshRequest id="ajaxRefreshRequest1" target="updatablePanel" params="input1. message}" binding="#{myPage. is a good control to use because it is only a container and is not visible on the page. Set the ID attributes of any controls on the page that you want to pass as parameters in the request. Then. 436 EGL Programmer’s Guide . 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. Set the ID attribute of the panel control to a value that is unique on the page. On the Web page. the refresh request does not update the variables in the JSF Handler to match the controls on the 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.message_Ref}" styleClass="outputText" /> </h:panelGrid> 4. JSF panel controls serve mainly as containers and organizers for other JSF controls. These controls do not need to be within the panel control. and optionally any parameters to be passed along with the request. only a single output control is within the panel. In this case. you specify an area of the page to be updated. Do this by adding a JSF behavior to an input control on the page and then selecting an event to trigger the request. but only input controls can trigger requests. In this way. <h:panelGrid id="updatablePanel" styleclass="panelGrid"> <h:outputText id="textToUpdate" value="#{myPage. an event to trigger the request. this type of request is intended to be modular and efficient. The control containing the behavior does not need to be within the panel control. 3. and they must be input controls. The following steps assume that you have a JSF Handler with variables bound to controls on a Web page: 1. but their ID attributes must be unique on the page. Specify the user event that will trigger the AJAX request. you configure the JSF Handler’s onPreRenderFunction to update the specified part of the page. AJAX requests in EGL can update only the parts of the page within a JSF panel control.Group Box control. 5. end end end Related tasks “Updating a page with a refresh request” “Updating a page with a submit request” on page 439 “Updating a page with a portion of another page” on page 442 Related reference getQueryParameter() 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.output = param1 / param2. However. The Panel . You will need to specify this ID in the AJAX request. Follow these steps to add an AJAX refresh request to a Web page. found in the Enhanced Faces Components drawer of the Palette view. 2. With this type of request. a. you use the onFocus event. and onSelect.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. select the Allow Ajax updates check box. On the Web page. from the left side of the view. select the event. For example. In the Target list. On the Ajax tab. f. onMouseOver. e. open the Properties view. Create the request by specifying the panel to update and the parameters for the request: a. On the Web page. select the input control that you want to use as the trigger. such as onBlur. d. c. In the Quick Edit view.name}" binding="#{myPage. b. With the control selected. open the Quick Edit view. c. select Invoke Ajax behavior on the specified tag. To perform the request when the user moves focus away from a particular control. Click Refresh as the type of request. you can make the AJAX request occur when the user moves the focus into a particular control. click the button labeled Click to edit Ajax request properties. Other commonly used events include onClick. In this case. In the Action list. Building EGL JSF Web applications 437 . Under the types of requests. if you attach a behavior to an input text control and set it to use the onBlur event. f. you use the onBlur event. Now the behavior to trigger the AJAX request is attached to the control. e. the code on the page might look like this: <h:inputText id="nameText" value="#{myPage. go to the Ajax tab under the type of panel control. select the panel control. With the panel selected. Select the Use pre-defined behavior check box. b.For example. On the properties view. d. select the ID of the panel you want to update. else //The page is loading as the result of an AJAX request. end end 438 EGL Programmer’s Guide .g. if you want to pass the current value of an input control on the page as a parameter. function onPreRender() if (J2EELib. this parameter has a null value. add that input control’s ID here. you might want to detect which case has caused the function to run. when the function runs as the result of an AJAX request. h. For example. 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. //Perform AJAX updating operations here. In the Target list. the AJAX request might look like this example: 7. Because the onPreRenderFunction runs when the page first loads as well as on every AJAX request. //Perform page loading operations here.getQueryParameter("$$ajaxmode") == NULL) //The page is loading for the first time. configure the onPreRenderFunction to accept the request. For example. 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. In the JSF Handler for the page. When the function runs as the result of a normal page loading operation. select the ID attribute of the panel you want to update. the new request might look like this: <hx:ajaxRefreshRequest id="ajaxRefreshRequest1" target="updatablePanel" params="nameText"> </hx:ajaxRefreshRequest> In the editor. if you choose to pass the value of an input control on the page. the parameter will contain a value. You can do this by testing for the value of the parameter $$ajaxmode. In this case. 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.8. you can update the controls on the page by setting the values of the variables bound to those controls. “Updating a page with a submit request” “Updating a page with a portion of another page” on page 442 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. indicate the area of the page that you want to update with the AJAX request by creating a JSF panel control on the page. found in the Enhanced Faces Components drawer of the Palette view. like a refresh request. only the controls within a JSF panel control are updated. see “Updating portions of a Web page with AJAX requests” on page 432. while still displaying the rest of the page.GetQueryParameter("nameText")::"!". you specify an area of the page to be updated and an event to trigger the request. You can update only the controls within the panel in the request. if you passed the value of a text control with the ID nameText. Unlike a refresh request. However. On the Web page. is a good control to use because it is only a container and is not visible on the page. you configure the JSF Handler’s onPreRenderFunction to update the specified part of the page. AJAX requests in EGL can update only the parts of the page within a JSF panel control. Follow these steps to add an AJAX submit request to a Web page. You can retrieve the parameters passed with the request by using the J2EELib. 3. Then. The Panel . Related tasks “Updating portions of a Web page with AJAX requests” on page 432 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.getQueryParameter() system function. 2. With this type of request. you can retrieve the value of that parameter with the following code: outputText = "Hello "::J2EELib. JSF panel controls serve mainly as containers and organizers for other JSF controls. For example.Group Box control. For an example of an AJAX refresh request. The code of the panel control might look like the following example. Building EGL JSF Web applications 439 . Once you have determined that the onPreRenderFunction has been invoked as the result of an AJAX request. only a single output control is within the panel. You can set up an EGL-controlled JSP file to call the JSF Handler’s onPreRenderFunction and provide a limited update to the page. Set the ID attribute of the panel control to a value that is unique on the page. The following steps assume that you have a JSF Handler with variables bound to controls on a Web page: 1. This technique can make Web applications faster and more efficient than if an entire page had to reload after each user action. Place the JSF controls that you want to update inside the panel control and make sure that the controls are bound to EGL variables. You will need to specify this ID in the AJAX request. In the Action list. To perform the request when the user moves focus away from a particular control. e. 440 EGL Programmer’s Guide .message}" binding="#{myPage. open the Quick Edit view. Now the behavior to trigger the AJAX request is attached to the control. The control containing the behavior does not need to be within the panel control. select the ID of the panel you want to update. d.<h:panelGrid id="updatablePanel" styleclass="panelGrid"> <h:outputText id="textToUpdate" value="#{myPage. In the Quick Edit view. Do this by adding a JSF behavior to an input control on the page and then selecting an event to trigger the request. c. from the left side of the view. you use the onFocus event. such as onBlur. select the input control that you want to use as the trigger. select Invoke Ajax behavior on the specified tag. Create the request by specifying the panel to update: a. a. On the Web page. With the control selected. For example. b. the code on the page might look like this: <h:inputText id="nameText" value="#{myPage. Specify the user event that will trigger the AJAX request. For example. onMouseOver. On the Web page. if you attach a behavior to an input text control and set it to use the onBlur event. you can make the AJAX request occur when the user moves the focus into a particular control. you use the onBlur event. select the panel control. f. but only input controls can trigger requests. Select the Use pre-defined behavior check box. and onSelect.name_Ref}" styleClass="inputText" > <hx:behavior event="onblur" id="behavior1" behaviorAction="get" targetAction="updatablePanel"> </hx:behavior> </h:inputText> The behavior might look like this example: 5. In this case. In the Target list.message_Ref}" styleClass="outputText" /> </h:panelGrid> 4. Other commonly used events include onClick. select the event.name}" binding="#{myPage. configure the onPreRenderFunction to accept the request. you might want to detect which case has caused the function to run. For example.b. function onPreRender() if (J2EELib. open the Properties view. With the panel selected. In the Target list. On the Ajax tab. else //The page is loading as the result of an AJAX request. select the Allow Ajax updates check box. You can do this by testing for the value of the parameter $$ajaxmode.getQueryParameter("$$ajaxmode") == NULL) //The page is loading for the first time. c. this parameter has a null value. e. On the Properties view. Click Submit as the type of request. go to the Ajax tab under the type of panel control. In the JSF Handler for the page. the new request might look like this: <hx:ajaxRefreshSubmit id="ajaxRefreshSubmit1" target="updatablePanel"> </hx:ajaxRefreshSubmit> 6. Building EGL JSF Web applications 441 . The Properties view looks like this example: f. Under the types of requests in the Properties view. the parameter will contain a value. d. select the ID attribute of the panel you want to update. g. click the button labeled Click to edit Ajax request properties. //Perform page loading operations here. When the function runs as the result of a normal page loading operation. when the function runs as the result of an AJAX request. Because the onPreRenderFunction runs when the page first loads as well as on every AJAX request. Once you have determined that the onPreRenderFunction has been called as the result of an AJAX request. you can pass parameters to the second 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. while still displaying the rest of the page. add a panel control and give it an ID unique on the page. configure the onPreRenderFunction to accept the request. you can update the controls on the page by setting the values of the variables bound to those controls. you specify an area of the first page to be updated. d. end end 7. Like the refresh type of request. 442 EGL Programmer’s Guide . On this page. Because the onPreRenderFunction runs when the page first loads as well as on every AJAX request. In the JSF Handler for the page. This technique can make Web applications faster and more efficient than if an entire page had to reload after each user action. an event to trigger the request. this parameter has a null value. when the function runs as the result of an AJAX request. c. Create a JSP file and JSF Handler as you would ordinarily create an EGL-controlled Web page. The onPreRenderFunction function can receive these parameters with the J2EELib. Related tasks “Updating portions of a Web page with AJAX requests” on page 432 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. You can update only the controls within the panel in the request. Unlike the other types of request. The request will instruct the servlet to take the content from this panel and use it on another page. the parameter will contain a value. With this type of request. “Updating a page with a refresh request” on page 436 “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. When the function runs as the result of a normal page loading operation. and optionally any parameters to be passed along with the request. you might want to detect which case has caused the function to run. You can set up an EGL-controlled JSP file to call the JSF Handler’s onPreRenderFunction and provide a limited update to the 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. Add the content into the panel control.getQueryParameter system function. b. Create a source page to hold the content that you want to use on another page: a.//Perform AJAX updating operations here. You can do this by testing for the value of the parameter $$ajaxmode. the external AJAX request goes to another page. Do this by adding a JSF behavior to an input control on the page and then selecting an event to trigger the request. you use the onBlur event. you can make the AJAX request occur when the user moves the focus into a particular control. the code on the page might look like this: Building EGL JSF Web applications 443 . Create the target page into which the content will be placed: a. You can retrieve the parameters passed with the request by using the J2EELib. if you passed the value of a text control with the ID nameText. c. In the Target list. With the control selected. On this page. To perform the request when the user moves focus away from a particular control. c. b. b. add a panel control and give it an ID unique on the page. select the ID of the panel you want to update. e. Specify the user event that will trigger the AJAX request. The contents of this panel will be replaced with the panel on the source page. In the Action list. Now the behavior to trigger the AJAX request is attached to the control. such as onBlur. //Perform AJAX updating operations here. The control containing the behavior does not need to be within the panel control.GetQueryParameter("nameText")::"!". a. add JSF controls to the panel.getQueryParameter() system function. Optionally. Select the Use pre-defined behavior check box. f. On the Web page. In the Quick Edit view. d. You can update only the controls within the panel in the request. //Perform page loading operations here. and onSelect. if you attach a behavior to an input text control and set it to use the onBlur event. For example. open the Quick Edit view. end end e. else //The page is loading as the result of an AJAX request. select the input control that you want to use as the trigger. Create a JSP file and JSF Handler as you would ordinarily create an EGL-controlled Web page. 3. The panel can be blank or populated with controls when the AJAX request replaces it with the panel on the source page. but only input controls can trigger requests. 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. onMouseOver. For example.function onPreRender() if (J2EELib. you can retrieve the value of that parameter with the following code: outputText = "Hello "::J2EELib. select Invoke Ajax behavior on the specified tag. Other commonly used events include onClick. In this case.getQueryParameter("$$ajaxmode") == NULL) //The page is loading for the first time. select the event. you use the onFocus event. 2. from the left side of the view. For example. b. In the Source field. if you want to pass the current value of an input control on the page as a parameter. 444 EGL Programmer’s Guide . f. select the ID attribute of the panel on the target page you want to update. enter the relative path to the source page.<h:inputText id="nameText" value="#{myPage. the request will retrieve the entire source page (that is. If you leave this field blank. On the Ajax tab. as explained in “Running a Web page on a server” on page 448. enter the ID of the panel control on the source page. open the Properties view. g. everything within the <body> tag). select the panel control. Click External as the type of request. In the Target list. c.jsp for the target page. 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. i. In the URL field. e. select the Allow Ajax updates check box. The contents of this panel will replace the contents of the panel on the target page. Under the types of requests. not just the panel control. click the button labeled Click to edit Ajax request properties.name}" binding="#{myPage. j. On the properties view. add that input control’s ID here. h. Be sure to use the correct extension of . On the target page. go to the Ajax tab under the type of panel control. Create the request by specifying the panel to update and the parameters for the request: a.name_Ref}" styleClass="inputText" > <hx:behavior event="onblur" id="behavior1" behaviorAction="get" targetAction="updatablePanel"> </hx:behavior> </h:inputText> The behavior might look like this example: 4. With the panel selected.faces or . d. The servlet invokes the onPreRenderFunction function on the source page and when that function has finished. The target page includes a group of check boxes that allow the user to select a value. For example. named targetPage. The AJAX request passes this value to the source 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. if you choose to pass the value of an input control on the page.css" title="Style"> </head> <f:view> <body> <hx:scriptCollector id="scriptCollector1"> Building EGL JSF Web applications 445 .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. it removes the panel from the source page and inserts it into the target page. charset=UTF-8"> <link rel="stylesheet" type="text/css" href="theme/stylesheet. Example The following example shows two pages that work together with an AJAX external request as explained in this topic. which renders a replacement panel based on the value of the message.jsp: <html> <head> <title>targetPage</title> <meta http-equiv="Content-Type" content="text/html. The page and its request look like this example: The following is the code of the target page. along with any parameters. the servlet will pass the AJAX external request to the source page. indicating that this request will run when the panel’s event is triggered. v The tag <h:outputText> is a JSF output text control that displays a static message as a prompt.egl: package jsfhandlers. v The tag <hx:behavior> specifies the event that triggers the AJAX request. the event is onchange. The following is the JSF Handler that would go with this page. the request includes the selection in the check box group as a parameter. v The tag <h:selectOneRadio> is a JSF check box group control that offers three options. In this case. handler targetPage type JSFHandler {view = "targetPage. the ID of the panel to retrieve from the source page.<h:form id="form1" styleClass="form"> <h:panelGroup id="targetPanel" styleClass="panelGroup"> <h:outputText id="promptMessage" styleClass="outputText" value="What is your favorite type of friut?"> </h:outputText> <h:selectOneRadio disabledClass="selectOneRadio_Disabled" enabledClass="selectOneRadio_Enabled" id="fruitName" styleClass="selectOneRadio"> <f:selectItem itemValue="bananas" itemLabel="bananas" /> <f:selectItem itemValue="apples" itemLabel="apples" /> <f:selectItem itemValue="grapes" itemLabel="grapes" /> </h:selectOneRadio> <hx:behavior event="onchange" target="fruitName" behaviorAction="get" targetAction="targetPanel"> </hx:behavior> </h:panelGroup> <hx:ajaxExternalRequest id="ajaxExternalRequest1" target="targetPanel" href="sourcePage. and the parameter to pass with the request.faces" source="sourcePanel" params="fruitName"> </hx:ajaxExternalRequest> </h:form> </hx:scriptCollector> </body> </f:view> </html> The following are some technical details about the target page: v The tag <h:panelGroup> is the JSF panel control that will be updated. which will be the parameter passed along with the request. This check box group has the ID attribute fruitName. It has the ID attribute targetPanel. The other attributes of the request point to the location of the source page. named targetPage. v The tag <hx:ajaxExternalRequest> defines the AJAX request itself. This tag’s target attribute points to the panel control.jsp"} end 446 EGL Programmer’s Guide . In this case. The behavior’s attributes point to the ID of the panel control and the radio button group. which means that the AJAX request is triggered when the selection in the radio button group changes. The page looks like this: Following is the JSF Handler that would go with this page. Following is the code of the source page. Because this example uses an external request. In this case.message}" binding="#{sourcePage.message_Ref}"> </h:outputText> </h:panelGroup> </hx:scriptCollector> </body> </f:view> </html> This page contains a panel control that will be used to replace the panel on the target page.jsp: <html> <head> <title>sourcePage</title> <meta http-equiv="Content-Type" content="text/html. the panel contains a single output field that is bound to a variable in the page’s JSF Handler. named sourcePage.egl: package jsfhandlers._preRender}" postRender="#{sourcePage. charset=UTF-8"> <link rel="stylesheet" type="text/css" href="theme/stylesheet. Building EGL JSF Web applications 447 ._postRender}"> <h:panelGroup id="sourcePanel" styleClass="panelGroup"> <h:outputText id="text1" styleClass="outputText" value="#{sourcePage. handler sourcePage type JSFHandler {onPreRenderFunction = onPreRender. so that page’s JSF Handler will process the request.css" title="Style"> </head> <f:view> <body> <hx:scriptCollector id="scriptCollector1" preRender="#{sourcePage. named sourcePage.No special code is required in the JSF Handler for the target page. the request goes to the source page. ". The request then uses the contents of the panel on the source page to replace the contents of the panel on the target page. v A server defined in the workbench. 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. You can set up an EGL-controlled JSP file to call the JSF Handler’s onPreRenderFunction and provide a limited update to the page.view = "sourcePage. but now you can choose whether to generate Handlers automatically or not. when ("grapes") message = "Grapes grow on vines and can be made into wine.getQueryParameter("fruitName")) when ("bananas") message = "Bananas are a yellow tropical fruit. See “Setting generation preferences” on page 180. while still displaying the rest of the page.". See Creating a server. If so. Note that in past versions of EGL. you can run the page on a server to see how it will look when deployed. it might publish automatically when you save changes to the Web project. If the server is not already running. Depending on the server and its settings. wait until the server’s status is listed as Synchronized. JSF Handlers were generated automatically when you saved the file. This task has the following prerequisites: v An EGL Web project with at least one Web page. 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. publishing will happen automatically when you run the page. This technique can make Web applications faster and more efficient than if an entire page had to reload after each user action. Related tasks “Updating portions of a Web page with AJAX requests” on page 432 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. 448 EGL Programmer’s Guide . 2.jsp"} message string = "No value set". If the server is already running. function onPreRender() if (J2EELib. Save any unsaved files and generate the project. To run a Web page on a server in the workbench: 1. when ("apples") message = "Apples grow on trees in many parts of the world". publish the new versions of your files to the server by right-clicking the server in the Servers view and then clicking Publish. “Updating a page with a submit request” on page 439 “Updating a page with a refresh request” on page 436 Running a Web page on a server When you are working with a Web page in EGL. in this case.getQueryParameter("fruitName") != null) case (J2EELib. The properties file contains key-value properties such as database connection and EGL environment variables. As long as the server is running. conflicts between these two different URLs can cause links to break when you test Web pages in the workbench.jsp will not work because JSF sets the location for the target page as myProject/myOtherPage. select the Set server as project default check box.faces In each case. if necessary. or open the original page as myProject/faces/ myPage.properties file generated from the project build descriptor. 5. relative links to a page named myProject/ myOtherPage.jsp in a project named myProject. replacing the actual .faces. 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. If you have not yet defined a default server for the project. In this case. Click Finish.faces extension to the file name. and portnumber refers to the port of that server. you must either change the link to myProject/faces/myOtherPage.jsp. If you want to use this server each time your run a page. which controls the run-time display of the JSP files. In the Run On Server window. if you run a Web page named myPage. For example. a minimal footprint.jsp You may also see this URL: http://hostname:portnumber/myProject/myPage. the internal Web browser might open to the following URL: http://hostname:portnumber/myProject/faces/myPage. and the page opens in the internal Web browser of the workbench.3.faces. it adds the . hostname refers to the name of your local server. JSF adds the /faces prefix to the URL. You can deploy the following kinds of EGL applications on the i5/OS integrated Web application server: v The application has to be a JSF handler program with or without database access. 4.faces and myProject/faces/myOtherPage. 6. easy to configure. which can be used to affect the runtime behaviors of the deployed application. Building EGL JSF Web applications 449 . Using the i5/OS integrated Web application server EGL supports development for the i5/OS integrated Web application server. select a server to use. In the Project Explorer view. secure environment for hosting dynamic Web applications on i5/OS. However. The URL of the Web page is set by the JavaServer Faces (JSF). The i5/OS integrated Web application server offers an economical alternative to WAS or Tomcat for the i5/OS environment and allows users to install applications (WAR or WAB) and configure database connections. v The application can access the rununit.jsp or myProject/myOtherPage. The server starts.jsp. Note that in the first case. If the page opens as myProject/myPage. In the other case. such as localhost. right-click the JSP file (not the EGL source file with the JSF Handler) and then click Run As → Run on Server. the Run On Server window opens. These URLs are equivalent and refer to the same JSP file and JSF Handler part.jsp extension. This example uses the name EGLi501 for the server instance: 1. you can specify a datasource (Connection ID) to be used by the application during generation in the EGL sqlDB build descriptor option. The Connection ID can be configured via the i5/OS integrated Web Application server Admin UI under Resource Management → Manage Database Connection link. Alternatively. Click Next to accept the default values. Click Next. the Connection ID can be defined manually from a database. 5. select the server instance where you want to install the application (EGLi501 in this example). If the applications to be installed on the server perform database I/O. 6. define a Connection ID for each data source. Select Create Application Server from Common Tasks and Wizards. Example The following scenario shows how to deploy a typical JSF handler application to the i5/OS integrated Web application server. 4. enter an Application Server Name such as EGLi501.v If the application needs to perform database access. Create a server instance in i5/OS if one is not available. 3. 450 EGL Programmer’s Guide . 2.properties file used at runtime. On the Sample Application screen. From the i5/OS Admin Console GUI. On the Specify User ID screen. click Next to accept the default port numbers. v EGL Web Services support is not available for this environment v EGL debug support is not available for this environment. On the Select Application Server Version and Type screen.properties file in the conf/override folder in your installation directory. click Next to accept the default port numbers. On the Specify Internal Ports screen. 10. note the port number to invoke the server instance during an application test. Other runtime platforms have not been verified. define a connection ID for each database by following these steps: 1. 7. On the Summary screen. select i5/OS integrated Web application server. click Next. The IBM Web Administration for i5/OS screen is displayed. On the Create a New HTTP Server screen. The option is generated as a property in the rununit. – If the application does not use the sqlLib. Click Next. 9. 8. v EGL support has been tested and verified with i5/OS (V5R4 and V6R1) integrated Web application server. v Test your Web application with WAS or Tomcat before deploying it. click Finish.connect() function to dynamically connect to a datasource (Connection ID). Authorization may be required for the access. The following limitations apply: v RBD does not support i5/OS integrated Web application server as a Targeted Runtime when creating an EGL Web project via the New Project wizard. Click Next. The Connection ID for the datasource can be configured as follows: – You must configure the server instance. Access the remote i5/OS Admin Console GUI from a browser. On the Specify Application Server Name screen. v A library name for the DB2 database for Schema name.com\root 2. select the appropriate connection type from the Database connection type pull-down menu.faces hostName The host name for the i5/OS system. 8. click Next to accept the default values. 6. and click Manage Details. On the Manage Installed Applications screen. Click Next. Your application must use the Connection ID as the datasource when accessing information from the database. On the Manage Integrated Web Application Server screen. Copy the local WAR file to the remote i5/OS system: >> copy d:\genout\EglWebProj. click Next to accept the default name. On the Summary screen. click Manage Installed Applications. On the Install New Application screen. which you can edit or delete. enter the path name of the application WAR or WAB file. portNum The port ID for the server instance. 7. On the Specify Database Connection Information screen. The Manage Database Connections screen displays the database connection you just created. click Next to accept the default values. On the Summary screen. On the Provide options to perform the install screen. click Finish. Click Next.2. 4.rchland.war z:\eglwars Use the following steps to install an application WAR or WAB file to the server instance: 1. Enter a unique identifier (or *Default) for Connection ID. Map a network drive on your local system to access the remote i5/OS system: >> net use z: \\lp11ut8. On the JNDI Name screen. On the Context Root Port Mapping screen. On the Manage All Servers screen. Copy the WAR file to the i5/OS environment by following these steps: 1. Test a JSF handler with the Web Application Server by entering the URL for the JSF application into a browser in the following form: http://hostName:portNum/contextRoot/pageName. click Create. Select Manage Database Connections under Resource Configuration. 3. 4. 5. On the Manage Database Connections screen. click Finish. 6. On the Specify Database Connection Type screen. Create a directory in i5/OS to store the WAR file. 7. select the server instance (EGLi501 in this example). 5. provide the following information: v The appropriate value for Database location (LOCAL is the default). click Install. or click Browse to navigate to the file. 3.ibm. Click Next. make a folder in the network drive z: >> md eglwars 3. 2. For example. v The Connection User ID and Password if required. Building EGL JSF Web applications 451 . xml. which involves use of login and error pages). you can customize the following JSP pages: v Sample login JSP <%@ page language="java" contentType="text/html. which is handled by a JEE-compliant Web application server. Form. This topic gives a few details. specify the authentication method (for example. and specify the related detail (for example..xml) that accompanies the application code. get data from user input on Web pages. Assigning roles and constraints in web. charset=ISO-8859-1" pageEncoding="ISO-8859-1"%> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4. and forward users from page to page.contextRoot The context root of the installed application.xml In JEE security. To customize web. right click the deployment descriptor and click the Pages tab 2. You also may want to review the documentation for your Web application server. as in the following: http://. Also stored in web. permission to access Web resources is based on a security role such as clerk or manager./MyPage. references to the specific login and error pages) Creating login and error pages If you are using the Form authentication method. as in the following example: Related concepts “Building EGL JSF Web applications” on page 389 In an EGL JSF Web application. enabling you to put data on Web pages. In the Login box.. Using JEE container-managed security To secure a JSF Web applications. including sample login and error JSPs. EGL logic parts control Web pages. The following considerations apply to running test cases in the browser: v If you use the Firefox browser.org/TR/html4/loose. charset=ISO-8859-1"> 452 EGL Programmer’s Guide . do as follows: 1./faces/MyPage...faces // do not use // do this instead Instead use JSF suffix servlet mapping. Each role is a developer-assigned status and is stored in the JEE deployment descriptor (web.xml is a set of constraints that define which Web pages are available to the users who are ultimately assigned to a given role. some of the JSF data table frames might be missing on the test pages. v Do not use JSF prefix servlet mapping in the URL.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html.w3.jsp http://. pageName The name of the JSF page to be displayed. as well as a list of EGL security-related functions.01 Transitional//EN" "http://www. you can use container-managed security. In your Web project. charset=ISO-8859-1"> <title>Insert title here</title> </head> <H1>Login Error Page</H1> <body> Status = Login Error !!! </body> </html> Assigning users and groups in application.xml). try changing the server connection type from RMI to SOAP.1 This section mentions issues that are specific to WebSphere Application Server 6.1. then “Secure administration. Choose a realm (for example.redbooks. usually by working at the Security tab for that file. In the Security section. 2.com/abstracts/sg246316.xml A deployer (usually a system administrator) associates each security role with specific users and groups. Handling issues specific to WebSphere Application Server 6. Open the Administrative Console 2. Click “Security”. LDAP) to use as your user registry and configure that realm 5. Create a new server from the Servers view or open an existing one. do as follows in Eclipse: 1. select ″Security is enabled on this server″ and fill in the user ID and password fields. Select both “Enable administrative security” and “Enable application security” 4. see IBM WebSphere Application Server V6. charset=ISO-8859-1" pageEncoding="ISO-8859-1"%> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4. do as follows: 1.org/TR/html4/loose <html> <head> <meta http-equiv="Content-Type" content="text/html.1 Security Handbook.<title>Insert title here</title> </head> <H1>Login Page</H1> <body> <form method="POST" action="j_security_check"> User Name : <input type="text" name="j_username"/> Password : <input type="password" name="j_password"/> <input type="submit" value="Login"/> </form> </body> </html> v Sample error JSP <%@ page language="java" contentType="text/html. The deployer makes that association by customizing the EAR project deployment description (application.html. Using system functions that support JEE security Building EGL JSF Web applications 453 .ibm. For a more detailed review.01 Transitional//EN" "http://www. If you have trouble running JEE security. and infrastructure” 3. which is an IBM Redbook (SG24-6316-01) that can be accessed at http://www. To configure container-managed security in WebSphere Application Server. applications. Apply and save your changes If you are accessing Web Application Server from an Eclipse-based product.w3. The following security-related functions. If no authentication is in use. Related concepts “Accessing an LDAP-compliant server” on page 190 EGL provides a code sample that you can customize to retrieve security or other details from a server accessed by way of Lightweight Directory Access Protocol (LDAP). if any. this function returns an empty string. A runtime knowledge of a user’s role lets the application direct processing in accordance with authorization rules. myInputVar string = "Hello". the server may need to review a security certificate before deciding whether to accept the data). or the more secure CLIENT_CERT (for client certification. Related reference getAuthenticationType() getRemoteUser() isUserInRole() 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. from the system library J2EELib.setStyle("color : red"). In this way. If no JEE authentication method is in use.egl. The following example includes EGL code to access a JSF control: package jsfhandlers. regardless of the authentication type. 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.jsf. myInputField. this function returns an empty string. function changeColor() myInputField HtmlInputText. To access a JSF control from a JSF Handler: 454 EGL Programmer’s Guide . v isUserInRole returns a Boolean that indicates whether the user is included in a specified role. v getAuthenticationType returns the JEE authentication method. you can change the appearance and behavior of these controls from a JSF Handler.ibm. v getRemoteUser returns the user’s login ID. viewRootVar = myViewRoot} myViewRoot UIViewRoot. handler myPage type JSFHandler {view = "myPage.*. this function returns an empty string. in which case authentication data is encrypted and.jsp". as an option. import com. are available in any JSF handler. The authentication methods used most often are FORM (in which case the user can log out without ending the browser session). If no such authentication is in use.findComponent("form1:text1"). myInputField = viewRoot. displaying the JSF controls on the page. On a blank line inside a function in the JSF Handler. 3. You can use the IDs or control types to find the control you want. refer to the functions of the ExternalType parts in the com. you might want to change the ID attribute of the JSF controls so they will be easier to identify. In the JSF Handler of the page. v The second line of code associates that variable with the JSF control. In this example. press Ctrl+Shift+Z. If you create the Faces JSP file after you add support for the JSF component interface to the project. In the above example. a variable of the type HtmlInputText is defined to access a JSF input text control. Optionally.jsp".ibm.ibm. When this code runs. using this code: myInputField = myViewRoot. 2. select the JSF control you want to access. Make sure that your EGL Web project has support for the JSF component interface. or you can hover the mouse over the controls to see their attributes. this code is added to the JSF Handler’s file automatically. In the previous 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. 8. the following code uses the setStyle function to change the text in an input control to the color red: myInputField.egl. the style of the input control is changed. which is located within a form named form1. declare a variable of the type UIViewRoot. Building EGL JSF Web applications 455 . 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. 6. v Add the following import statement: import com. as in this example: myViewRoot UIViewRoot. Create a Web page and add one or more JSF controls to it. The EGL Source Assistant window opens.jsf package.findComponent("form1:text1"). the variable is associated with a JSF input text control named text1. See “Adding JSF component interface support to an EGL Web project” on page 464. v Specify the name of the UIViewRoot variable in the viewRootVar JSF Handler property: handler myPage type JSFHandler {view = "myPage. v Within the JSF Handler of the page. 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. using this code: myInputField HtmlInputText. You do not need to edit these parts. 7.1. Use the variable to change the JSF control. To see the full list of operations you can call on a given control.egl. add the following code. For example. In the EGL Source Assistant window. 4.jsf. viewRootVar = myViewRoot} 5.* The packages that are imported by this statement contain a group of ExternalType parts which provide access to Java code in the JSF controls. Click OK.setStyle("color : red"). setStyle("font-weight: bold"). the setWidth function sets the width of a control in pixels. v You cannot access JSF controls in this way in the onConstructionFunction and onPreRenderFunction functions in the Handler.ibm. v In most cases.setStyle(myStyleString).. the changes to the page will not be visible to the user until the page is refreshed.Following are some notes about accessing JSF controls with EGL code: v For the complete list of JSF functions that are accessible in EGL. use the following code to change a control’s text to bold and red.setStyle("color: red"). and then set the same control’s text to bold with the code myComponent. However. However. Because many of the parameters passed to these functions are inserted into HTML attributes. because this function is called after the page is rendered and sent to the browser. even if the name of the function suggests that the parameter is a numerical or boolean value. To set the width of a control to 300 pixels.getStyle() + ". For more detailed information. v Because many of the functions set or return information from HTML attributes. myComponent. For example. see the documentation for Faces controls. You might change an HTML attribute that is needed for the page to work correctly. the text will be bold but not red. you should be aware of the HTML attributes that are connected to the functions that you are using. font-weight: bold". or else the control might not display properly. Be sure to test any changes that you make to Web pages. See the related tasks for some examples. without overwriting any previous changes to that control’s style: myStyleString string.jsf.egl file note the functions that change HTML attributes directly.egl in the package com. it might seem to take a numeric data type as a parameter. Because this parameter is a measurement. For example. this function must receive a string. paying attention to how the list of changes is delimited. For example. retrieve the current state of the control and append the new data. open the file FacesHtmlComponent. The function specified in the onPostRenderFunction property can access the JSF component tree. if you change the style class of a control as in Changing the style class of a JSF control. For example. myStyleString = myComponent. they must be passed as EGL string variables. be sure to pass the correct data type. if you set a control’s text to red with the code myComponent. To add several changes to a JSF control. because the change to bold overwrites the change to red. v When passing a parameter to one of these functions.egl. you must pass a string variable with the value ″300″. color: red. The comments in the FacesHtmlComponent. that new style class of the control must be available to the page in a CSS file or style tag. or in a percentage of its original size if the percent (%) symbol is appended. The functions are briefly explained in comments to this file. This file is added to your project when you add support for the JSF component interface. Related tasks “Changing the target of a JSF link” on page 457 “Changing the style of a JSF control” on page 458 “Changing the style class of a JSF control” on page 459 “Setting event handlers for a JSF control” on page 460 “Setting the size of a JSF image” on page 461 “Enabling or disabling JSF controls” on page 462 456 EGL Programmer’s Guide . There are many different changes that you can make to JSF controls. the changes that you make to the JSF controls are not cumulative. * v You must declare a variable of the type UIViewRoot within the JSF Handler. press Ctrl+Shift+Z. The EGL source assistant adds two lines of EGL code to the JSF Handler. select the JSF control that you want to access. Click OK. For example. 2. Related tasks “Adding JSF component interface support to an EGL Web project” on page 464 “Changing the style class of a JSF control” on page 459 “Changing the style of a JSF control” on page 458 “Enabling or disabling JSF controls” on page 462 “Setting the size of a JSF image” on page 461 “Setting event handlers for a JSF control” on page 460 “Setting JSF data table properties” on page 463 Related reference Component tree access viewRootVar Building EGL JSF Web applications 457 . In the EGL Source Assistant window. 3.findComponent("form1:linkEx1").egl. v The JSF Handler that is associated with the Web page must have the following import statement: import com.jsf. For example. displaying the JSF controls on the page. see “Accessing the JSF component tree with the source assistant” on page 454. change the target of the link with the setTarget() function.“Setting JSF data table properties” on page 463 Related reference Component tree access viewRootVar Changing the target of a JSF link You can change the target attribute of a JavaServer Faces (JSF) link from a JSF Handler.ibm. 4. linkEx1 = myViewRoot. This task has the following prerequisites: v Your EGL Web project must have support for the JSF component interface. The EGL Source Assistant window opens. The first line defines an EGL variable of the type that matches the JSF link that you selected.setTarget("_blank"). For example. To change the target attribute of a JSF link from a JSF Handler: 1. the code might look like this: linkEx1 HtmlOutputLink. Using the EGL variable that is created by the source assistant. add this code: linkEx1. See “Adding JSF component interface support to an EGL Web project” on page 464. v You must specify the name of the of the UIViewRoot variable in the viewRootVar JSF Handler property. you can set the target attribute of a link to _blank to make that link open in a new browser window. to make the link open in a new window. The second line associates that variable with the JSF link. On a blank line inside a function in the JSF Handler. For more information on these prerequisites. see Changing the style class of a JSF control. 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. Click OK. text1. On a blank line inside a function in the JSF Handler. 3. The EGL source assistant adds two lines of EGL code to the JSF Handler. Adds a red border composed of a solid line around the control. v You must specify the name of the of the UIViewRoot variable in the viewRootVar JSF Handler property. the style attribute of the input control is changed.setStyle("border-style : solid. such as changing the text color. When this code runs. use this code: text1. This task has the following prerequisites: v Your EGL Web project must have support for the JSF component interface. Sets the size of the font in the control to 20 points. v The JSF Handler that is associated with the Web page must have the following import statement: import com. In this example. to change the color to red and the size to 20 points. See “Adding JSF component interface support to an EGL Web project” on page 464. 458 EGL Programmer’s Guide . text1.findComponent("form1:text1"). The EGL Source Assistant window opens. For example. In the EGL Source Assistant window. font-size: 20pt"). see “Accessing the JSF component tree with the source assistant” on page 454. separate changes with semicolons (.setStyle("font-size : 20pt").setStyle("text-align: center"). change the style of the JSF control with the setStyle function. To make more than one change to the style of a control.* v You must declare a variable of the type UIViewRoot within the JSF Handler.setStyle("color : red. displaying the JSF controls on the page.setStyle("color : red"). For more information on these prerequisites. the code to access a JSF input text control might look like this: text1 HtmlInputText.ibm. To make a larger change in the control’s appearance by changing its style class. For example. to change the text in a text control to red. Follow these steps to change the style of a JSF control from an EGL JSF Handler: 1. Centers the text within the control. Some examples of other changes you can make to the style of a control follow. For example. select the JSF control that you want to access. text1.egl. 2.Changing the style of a JSF control You can change the appearance of a JavaServer Faces (JSF) control with EGL code. 4. press Ctrl+Shift+Z. text1 = myViewRoot.). The first line defines an EGL variable of the type that matches the JSF control that you selected. The second line associates that variable with the JSF control.jsf. add this code: text1. border-color : red"). Not all styles are compatible with all JSF controls. Using the EGL variable that the source assistant created. see “Accessing the JSF component tree with the source assistant” on page 454. not to be confused with a Java class. text1.text1. The EGL Source Assistant window opens. is a group of zero to many commands that describes the appearance of an element on a Web page. The second line associates that variable with the JSF control. See “Adding JSF component interface support to an EGL Web project” on page 464. To make smaller changes to a JSF control’s style. v The JSF Handler that is associated with the Web page must have the following import statement: import com.setStyle("font-weight : bold").egl. select the JSF control you want to access. On a blank line inside a function in the Handler. Style classes are defined with the Cascading Style Sheets language. The first line defines an EGL variable of the type that matches the JSF control that you selected. JSF controls can be assigned a style class with the class attribute. This task has the following prerequisites: v Your EGL Web project must have support for the JSF component interface. displaying the JSF controls on the page.* v You must declare a variable of the type UIViewRoot within the JSF Handler. such as changing the text color. A style class.ibm. v You must specify the name of the of the UIViewRoot variable in the viewRootVar JSF Handler property. see “Changing the style of a JSF control” on page 458. For example. You can change the style class of a JSF control on a Faces JSP file from one class to another.setStyle("height : 50px"). Makes the text within the control bold. For more information on these prerequisites. the code to access a JSF input text control might look like this: Building EGL JSF Web applications 459 . a language that can control many different aspects of the appearance of a Web page. The EGL source assistant adds two lines of EGL code to the JSF Handler. Makes the control 50 pixels tall.jsf. Related tasks “Adding JSF component interface support to an EGL Web project” on page 464 “Accessing the JSF component tree with the source assistant” on page 454 “Changing the style class of a JSF control” “Changing the target of a JSF link” on page 457 “Enabling or disabling JSF controls” on page 462 “Setting the size of a JSF image” on page 461 “Setting event handlers for a JSF control” on page 460 “Setting JSF data table properties” on page 463 Related reference Component tree access viewRootVar Changing the style class of a JSF control Like many elements on a Web page. To change the style class of a JSF control from an EGL JSF Handler: 1. 3. In the EGL Source Assistant window. press Ctrl+Shift+Z. 2. Click OK. displaying the JSF controls on the page. or you can remove an event handler from a control. the style class of the input control is changed.setStyleClass("errorField"). set the style class of the JSF control with the setStyleClass function. see “Accessing the JSF component tree with the source assistant” on page 454. For example. an event handler is a JavaScript function that is called when a specific event happens on the page. text1 = myViewRoot.findComponent("form1:text1"). you can assign a function to a text input control using the onClick event handler. In this context. the function defined as the onClick event handler runs. For example. See “Adding JSF component interface support to an EGL Web project” on page 464. the HTML code displayed by the browser looks like this: <input id="form1:text1" type="text" name="form1:text1" class="errorField" /> Related tasks “Adding JSF component interface support to an EGL Web project” on page 464 “Accessing the JSF component tree with the source assistant” on page 454 “Changing the style of a JSF control” on page 458 “Changing the target of a JSF link” on page 457 “Enabling or disabling JSF controls” on page 462 “Setting the size of a JSF image” on page 461 “Setting event handlers for a JSF control” “Setting JSF data table properties” on page 463 Related reference Component tree access viewRootVar 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. This task has the following prerequisites: v Your EGL Web project must have support for the JSF component interface. In this example. When the control is clicked in the browser.* v You must declare a variable of the type UIViewRoot within the JSF Handler. 460 EGL Programmer’s Guide . 4. to set a text control to a style class named errorField. The EGL Source Assistant window opens. add this code: text1. v You must specify the name of the of the UIViewRoot variable in the viewRootVar JSF Handler property. Follow these steps to assign or remove an event handler from a JSF control: 1. v The JSF Handler that is associated with the Web page must have the following import statement: import com.text1 HtmlInputText.ibm. Using the EGL variable that the source assistant created.jsf. For more information on these prerequisites. On a blank line inside a function in the JSF Handler. The JavaScript function that is used as an event handler must be available to the page. press Ctrl+Shift+Z. You cannot use an EGL function as an event handler for a JSF control. either in a <script> tag on the page itself or in a script file that is linked to the page. When this code runs.egl. findComponent("form1:text1"). To remove an event handler from a JSF control. Follow these steps to change the size of a JSF image control with an EGL JSF Handler: Building EGL JSF Web applications 461 . assign or remove the event handlers.setOnclick("").ibm.* v You must declare a variable of the type UIViewRoot within the JSF Handler.egl. 4. See “Adding JSF component interface support to an EGL Web project” on page 464. select the JSF image control that you want to access. The EGL source assistant adds two lines of EGL code to the JSF Handler.setOnclick("myFunction"). This task has the following prerequisites: v Your EGL Web project must have support for the JSF component interface. Related tasks “Adding JSF component interface support to an EGL Web project” on page 464 “Accessing the JSF component tree with the source assistant” on page 454 “Changing the style class of a JSF control” on page 459 “Changing the style of a JSF control” on page 458 “Changing the target of a JSF link” on page 457 “Enabling or disabling JSF controls” on page 462 “Setting the size of a JSF image” “Setting JSF data table properties” on page 463 Related reference Component tree access viewRootVar 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.2. You must use a Faces image control. 3. v The JSF Handler that is associated with the Web page must have the following import statement: import com. text1 = myViewRoot. Using the EGL variable that the source assistant created. The second line associates that variable with the JSF control. The first line defines an EGL variable of the type that matches the JSF control that you selected. an EGL JSF Handler cannot directly change ordinary HTML image tags. For example. see “Accessing the JSF component tree with the source assistant” on page 454. v You must specify the name of the of the UIViewRoot variable in the viewRootVar JSF Handler property. add this code: text1. Click OK. For more information on these prerequisites. assign it a blank string as an event handler: text1.jsf. the code to access a JSF input text control might look like this: text1 HtmlInputText. to assign the JavaScript function myFunction() as the onClick event handler for the text control. In the EGL Source Assistant window. For example. the code to access a JSF image control might look like this: imageEx1 HtmlGraphicImageEx. see “Accessing the JSF component tree with the source assistant” on page 454. The EGL Source Assistant window opens.egl. v You must specify the name of the of the UIViewRoot variable in the viewRootVar JSF Handler property. For example. to make the image 300 pixels wide and 200 pixels tall. passing each function a string or literal that specifies the measurement in pixels. This task has the following prerequisites: v Your EGL Web project must have support for the JSF component interface. To enable or disable a JSF control with an EGL JSF Handler: 1. v The JSF Handler that is associated with the Web page must have the following import statement: import com. The EGL Source Assistant window opens.setHeight("300").1. Using the EGL variable that the source assistant created. The second line associates that variable with the JSF control. press Ctrl+Shift+Z. imageEx1. 2.ibm. The EGL source assistant adds two lines of EGL code to the JSF Handler. displaying the JSF controls on the page. press Ctrl+Shift+Z. A disabled control cannot be edited or changed on the Web page. select the JSF image control that you want to access. Related tasks “Adding JSF component interface support to an EGL Web project” on page 464 “Accessing the JSF component tree with the source assistant” on page 454 “Changing the style class of a JSF control” on page 459 “Changing the style of a JSF control” on page 458 “Changing the target of a JSF link” on page 457 “Enabling or disabling JSF controls” “Setting event handlers for a JSF control” on page 460 “Setting JSF data table properties” on page 463 Related reference Component tree access viewRootVar Enabling or disabling JSF controls You can enable or disable JSF input controls and command buttons with EGL code. In the EGL Source Assistant window. add this code: imageEx1.findComponent("imageEx1"). On a blank line inside a function in the JSF Handler. The first line defines an EGL variable of the type that matches the JSF control that you selected. Click OK. For example. On a blank line inside a function in the JSF Handler. 4.setWidth("300"). imageEx1 = myViewRoot. change the size of the JSF image control with the setHeight and setWidth functions. See “Adding JSF component interface support to an EGL Web project” on page 464. 3. 462 EGL Programmer’s Guide .* v You must declare a variable of the type UIViewRoot within the JSF Handler.jsf. For more information on these prerequisites. displaying the JSF controls on the page. select the JSF data table control that you want to access. select the JSF control that you want to access. Related tasks “Adding JSF component interface support to an EGL Web project” on page 464 “Accessing the JSF component tree with the source assistant” on page 454 “Changing the style class of a JSF control” on page 459 “Changing the style of a JSF control” on page 458 “Changing the target of a JSF link” on page 457 “Setting the size of a JSF image” on page 461 “Setting event handlers for a JSF control” on page 460 “Setting JSF data table properties” Related reference Component tree access viewRootVar 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. 3. to enable a text control. In the EGL Source Assistant window. Click OK. See “Adding JSF component interface support to an EGL Web project” on page 464. This task has the following prerequisites: v Your EGL Web project must have support for the JSF component interface.2. v You must specify the name of the of the UIViewRoot variable in the viewRootVar JSF Handler property. add this code: text1. 4. v The JSF Handler that is associated with the Web page must have the following import statement: import com. The EGL source assistant adds two lines of EGL code to the JSF Handler.* v You must declare a variable of the type UIViewRoot within the JSF Handler.ibm.setDisabled(no). text1 = myViewRoot.setDisabled(yes). the code to access a JSF input text control might look like this: text1 HtmlInputText. For example. Using the EGL variable that the source assistant created. The first line defines an EGL variable of the type that matches the JSF control that you selected. To change the properties of a JSF data table control: 1. enable or disable the JSF control with the setDisabled function. To disable the text control. Building EGL JSF Web applications 463 . On a blank line inside a function in the JSF Handler. The second line associates that variable with the JSF control. The EGL Source Assistant window opens. press Ctrl+Shift+Z.egl. add this code: text1. For more information on these prerequisites.jsf. see “Accessing the JSF component tree with the source assistant” on page 454. 2. For example.findComponent("form1:text1"). displaying the JSF controls on the page. In the EGL Source Assistant window. 3. The EGL source assistant adds two lines of EGL code to the JSF Handler. the code to access a JSF input text control might look like this: table1 HtmlDataTable. 5. The first line defines an EGL variable of the type that matches the JSF control that you selected. 3. Click Add/Remove Project Facets. MyRowClass2"). You can add these packages when you create an EGL Web project. change the properties of the data table. 4. Click Finish. You cannot remove support for the JSF component interface from a project. add this code: table1.jsf to your project. Select the EGL support with JSF Component Interfaces check box.egl. the project already has support for the JSF component interface. As explained in “Accessing the JSF component tree with the source assistant” on page 454. add this code: table1. In the Project Explorer view. The second line associates that variable with the JSF control. To make the rows of the data table alternate between the two style classes MyRowClass1 and MyRowClass2. this package contains ExternalType parts that you can use to access JSF components on the page. For example. to change the rowClasses property of the table to the style class MyRowClass1.setRowClasses("MyRowClass1"). or you can add them to an existing EGL Web project by following these steps: 1. right-click the EGL Web project and then click Properties. 2. 4. In the Properties window. Related tasks “Adding JSF component interface support to an EGL Web project” “Accessing the JSF component tree with the source assistant” on page 454 “Changing the style class of a JSF control” on page 459 “Changing the style of a JSF control” on page 458 “Changing the target of a JSF link” on page 457 “Enabling or disabling JSF controls” on page 462 “Setting the size of a JSF image” on page 461 “Setting event handlers for a JSF control” on page 460 Related reference Component tree access viewRootVar 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.findComponent("table1"). table1 = viewRoot. Adding support for the JSF component interface adds a package named com. Click OK. 6. For example. Using the EGL variable that the source assistant created.setRowClasses("MyRowClass1. Click OK. 464 EGL Programmer’s Guide . If this check box is already selected. your EGL Web project must contain the packages that enable you to access the JSF component tree.ibm. click Project Facets. The default value is labels. These check boxes tell EGL to delete the JSP file that is associated with a JSF Handler if you delete the JSF Handler. Related Reference JSF Handler part Building EGL JSF Web applications 465 . expand EGL and click Page Designer.Related tasks “Creating an EGL Web project” on page 73 This topic covers how to create an EGL Web project. set the name of the variable to use to represent resource bundles in your pages. Click Apply to save the changes and remain in the Preferences window. “Accessing the JSF component tree with the source assistant” on page 454 Related reference Component tree access Setting preferences for Web projects These preferences control defaults for EGL Web projects and JSF Handler parts. 6. In the JSFHandler Package field. Set preferences for refactoring EGL Web projects and JSF Handler parts in the check boxes at the bottom of the page. but you can change this value as explained in “Localizing text in Web applications” on page 426. From the navigation tree. 5. From the main menu. Related concepts “Preferences” on page 172 EGL preferences affect the way the workbench displays and works with EGL. You can also delete the generated output when you delete a JSF Handler. Click OK to save the changes and exit the window. To specify preferences for Web projects and JSF Handler parts. 3. In the Loadbundle variable field. click Window → Preferences. follow these steps: 1. specify the location of JSF Handler parts in your EGL Web projects. 2. and vice versa. 4. 466 EGL Programmer’s Guide . under the control of a portal server. if we had displayed the portlet in Edit mode. It uses programs called portlet to process user requests and generate dynamic content. the EGL logic parts control portlets. Each user is able to provide this customization data. For example.Building EGL portlet applications A portal page combines a number of independent windows. the portlets and combining their output into a single Web page. All portlets are required to provide View mode support. In our weather portlet example. Edit. or may be more context specific. In this mode. These parts allow you to put data in a Portal and get input from users. managing the lifecycle of. and providing various services to. and differs only in the ways noted in this section. 2008 467 . EGL portlet development follows the EGL Web application programming model. portlets generate their normal dynamic content. Each page of a portal is divided into “windows” that display the dynamic content generated by a single portlet. which means that the portlet will display different data depending on who is logged in. © Copyright IBM Corp. you can have a portlet that displays the local weather in the portlet window. in the example weather portlet. mode and window state. it would wait for the user to enter the local zip code in order to customize the weather display. and minimized. Window state The window state of a portlet is an indicator of the amount of page real estate that the portlet will occupy. we can choose to limit its display to the temperature and a graphic that indicates the current weather conditions. The portal acts as a container for the portlets. the portlet author might want to limit the amount of page space that the portlet requires. Because the portlet window might be small. Help mode support is optional. Portlet mode A portlet mode is an indication of the function that the portlet will perform to produce specific content or perform a certain task. For instance. maximized. Edit mode support is optional. Common portlet modes are View. In an EGL portlet application. 1996. Portlet overview WebSphere Portal Server is a content aggregator. and Help. or portlets. The normal window state indicates that the portlet may be sharing the page with any either any number of other portlets. The help can be a single screen displaying help for the entire portlet. Help mode causes the portlet to display information on the use of the portlet. Portlets can have three possible states: normal. Portlet windows have two user modifiable properties. Portlet can also be displayed in Edit mode. the wizard will create two JSF Handlers called MyPortletView and MyPortletEdit Java Server Pages (JSP) files Java Server Pages in a portlet application represent a fragment of a portal page. the JSF Handler part backs a JSP that represents an entire Web page.A maximized window state can show that the portlet will either be the only one that is portlet displayed or that it will be given more space than the other portlets on the page. JSF Handler part JSF Handlers for portlet applications are developed in exactly the same way as handlers for other Web applications. Unlike JSPs for standard Web applications where each JSP represents an entire Web 468 EGL Programmer’s Guide . The portlets that are within the application can interact with each other when placed on the same Portal page. Prerequisites To use EGL portlets. The container might choose not to render the portlet at all. In standard Web applications. portlet applications are composed of JSP files that are backed by JSF Handler parts and other configuration files. the portlet should display little or no information. If we designate the weather portlet as maximized then it could display a local forecast information for multiple days. As with other EGL based Web applications.0 or later Related concepts “Elements of a Portlet Application” “Managing Portlet Sessions” on page 469 “Inter-Portlet Communication” on page 470 “J2EELib” on page 471 Related tasks “Creating a Web Page” on page 471 “Adding a Portlet to the Application” on page 472 “Adding Support for Additional Portlet Modes” on page 473 Related reference EGL library portalLib Elements of a Portlet Application A portlet application is a Web application that can contain multiple portlets. For more information regarding EGL Web application development. you must have the following products installed: v Rational Application Developer with the Portal tool feature installed v IBM WebSphere Portal Server V6. In a portlet application. there is at least one JSF Handler and a corresponding JSP file for each supported mode of each portlet in the application. which means that it is not likely a minimized portlet will display during page rendering. and specify that it will support view and edit modes. When minimized. see “Building EGL JSF Web applications” on page 389. When you use the New EGL Portlet wizard to create a portlet named MyPortlet. “Managing Portlet Sessions” “Inter-Portlet Communication” on page 470 “J2EELib” on page 471 Related tasks “Creating a Web Page” on page 471 “Adding a Portlet to the Application” on page 472 “Adding Support for Additional Portlet Modes” on page 473 Related reference EGL library portalLib Managing Portlet Sessions Portlets commonly collect state information that you must save between requests from a client. Portlet sessions are similar to Web application sessions. Unlike Web application sessions. For example. SessionScopeKind. It is the responsibility of the portlet container to combine these fragments into a valid web page.xml file located in the project’s Web Content/WEB-INF folder v As the Portlet Deployment Descriptor file located in the root of the project. Related concepts “Building EGL portlet applications” on page 467 A portal page combines a number of independent windows. “myValue”. only visible in the Project Explorer view. A way to manage this information is to save it as a session attribute. under the control of a portal server. This parameter takes an enumerated value of type SessionScopeKind.setPortletSessionAttr() function. each portlet JSP represents only the fragment of the portal page that is confined to the individual portlet window.setPortletSessionAttr(“myKey”. The portlet deployment descriptor is visible in your EGL portlet project in two places: v As the portlet.page. use the following function call in the JSF Handler: portalLib. For this reason.portletScope). to add a session attribute that is only accessible to the declaring portlet. you must specify the level of access to the attribute within the portlet application. When you add an attribute to the session. a Portlet session has scope. Window state The portlet deployment descriptor provides configuration and deployment information for your portlet application. Related concepts Building EGL portlet applications 469 . or portlets. Do this through the scope parameter of the portalLib. These references point to the same file. you must not add HTML markup head and body tags to your portlet JSPs. Portlet sessions do have one major difference. and managing their attributes is the conceptual equivalent. A session attribute that is placed in the portlet scope is easily accessible only to the portlet that added it. “Elements of a Portlet Application” on page 468 “Inter-Portlet Communication” “J2EELib” on page 471 Related tasks “Creating a Web Page” on page 471 “Adding a Portlet to the Application” on page 472 “Adding Support for Additional Portlet Modes” on page 473 Related reference EGL library portalLib Inter-Portlet Communication One of the most useful features of a portlet is that it can communicate with other portlets. While rendering. all portlets can access the application scope attribute and use it to appropriately respond to the user action. When user interaction occurs on a portal page. you can use the PortletSession as a “scratchpad” for passing information. or portlets. The PortletSession is the mechanism that the portal uses for identifying and storing transient information about a user across multiple browser requests.“Building EGL portlet applications” on page 467 A portal page combines a number of independent windows. Although the standard portlet API does not define a communication mechanism. under the control of a portal server. renders itself. under the control of a portal server. each portlet on the page. the following sequence of events happens: 1. This portlet can add attributes to the application scope of the session. and the other portlets in the application can read the values and use them. 2. The attribute will then be accessible to all portlets in the application. including the one that handled the event. “Elements of a Portlet Application” on page 468 “Managing Portlet Sessions” on page 469 “J2EELib” on page 471 Related tasks “Creating a Web Page” on page 471 “Adding a Portlet to the Application” on page 472 “Adding Support for Additional Portlet Modes” on page 473 Related reference EGL library portalLib 470 EGL Programmer’s Guide . The portlet where the event occurred processes the event first. or portlets. The portlet request lifecycle makes communication of this sort possible. One portlet in an application can write to the PortletSession. After the portlet finishes responding to the event. Related concepts “Building EGL portlet applications” on page 467 A portal page combines a number of independent windows. 4. 8. Each mode has an initial JSP that is specified as a parameter in the portlet. This template is creates a JSP fragment. 7. Building EGL portlet applications 471 . The location must be in the Web Content folder of the EGL Portlet project. select EGL portlet project. 5. 3.egl extension. The accompanying JSF handler will be put into the project’s jsfhandlers package unless you specified a different package in the workbench preferences. 2. select the location for the new Web page. In the Folder field. but if you can use the J2EELib functions getRequestAttr() and setRequestAttr() within a portlet. The accompanying JSF handler will have the same name with an *. however. Make sure that the template you use for the Web page is the Portlet JSP template.J2EELib J2EELib provides a number of functions that are useful to Web application developers. EGL creates a navigation rule in the JSF configuration file that allows you to forward users to this page. or portlets. Most JSF applications should not need request attributes. It is a good practice to append the file name with the name of the mode to which the content belongs. not JSP. Related concepts “Building EGL portlet applications” on page 467 A portal page combines a number of independent windows. Additionally. portalLib does not provide functions for setting request attributes for a portlet. Click Finish. Expand Web and click Web page. enter the name of the new Web page. In the File Name field.b. The new Web page and its JSF Handler part are created in your Web project. Click File → New → Other. To 1. add additional pages to the portlet: In the Project Explorer view. 6. Click Next. The New window opens. You can accomplish most functions found in J2EELib with the corresponding functions in PortalLi.xml file for the application. rather than an entire Web page. “Elements of a Portlet Application” on page 468 “Managing Portlet Sessions” on page 469 “Inter-Portlet Communication” on page 470 Related tasks “Creating a Web Page” “Adding a Portlet to the Application” on page 472 “Adding Support for Additional Portlet Modes” on page 473 Related reference EGL library portalLib Creating a Web Page Each mode of a portlet can be composed of multiple JSPs and JSF Handler parts. under the control of a portal server. Related concepts “Building EGL portlet applications” on page 467 A portal page combines a number of independent windows. 1. The faces-config. 3. or portlets. A JSP and corresponding JSF Handler will be created for each supported portlet mode. “Elements of a Portlet Application” on page 468 “Managing Portlet Sessions” on page 469 “Inter-Portlet Communication” on page 470 “J2EELib” on page 471 Related tasks “Adding a Portlet to the Application” “Adding Support for Additional Portlet Modes” on page 473 Related reference EGL library portalLib Adding a Portlet to the Application A portlet application can be composed of multiple portlets in a portlet project. Click Finish. Related concepts “Building EGL portlet applications” on page 467 A portal page combines a number of independent windows. Click File → New → Other → EGL → EGL Portlet. under the control of a portal server. In the Project Explorer view. or portlets. In the Portlet name field. under the control of a portal server.After the page has been created. In the Content types and modes table. check the modes you want the portlet to support. “Elements of a Portlet Application” on page 468 “Managing Portlet Sessions” on page 469 “Inter-Portlet Communication” on page 470 “J2EELib” on page 471 Related tasks “Creating a Web Page” on page 471 “Adding Support for Additional Portlet Modes” on page 473 Related reference EGL library portalLib 472 EGL Programmer’s Guide . Use the New EGL Portlet wizard to add portlets to the project.xml files will be updated to support the new portlet. enter the name of the new portlet. select the your EGL portlet project. 2. 4. The EGL Portlet Project wizard can be used to create the initial portlet in an application. you can use the EGL forward statement to navigate from the main page to the newly created page.xml and portlet. 5. The new portlet will be created in the target project. To add portlet modes to an existing portlet: 1. select the portlet to which you will be adding the mode.portlet. enter the path to the JSP to be used for this mode.0 are: v view v edit v help v config v edit_defaults 7. EGL based JSF portlets use initialization parameters to specify which JSP file to display as the initial content for each supported portlet mode.config com.ibm. Find the Supported Modes section. you can still add modes after the portlet has been created. Valid values are: v v v v com.help 9.ibm. This value should be relative to the context root of the web application. you define portlet modes when the New EGL Portlet Project or New EGL Portlet wizards.ibm. 8.page. Click OK.faces. 6. The cursor will become active in the Portlet modes list. 3. “Elements of a Portlet Application” on page 468 “Managing Portlet Sessions” on page 469 “Inter-Portlet Communication” on page 470 “J2EELib” on page 471 Related tasks “Creating a Web Page” on page 471 “Adding a Portlet to the Application” on page 472 Related reference Building EGL portlet applications 473 . In the Name field.xml file and select Open With → JSR 168 Portlet Deployment Descriptor Editor. Select the Portlets tab at the bottom of the editor. 5. or portlets.edit com. Find the Initialization section.portlet.ibm. Select text/html and click the Edit.page. however.Adding Support for Additional Portlet Modes Typically. Related concepts “Building EGL portlet applications” on page 467 A portal page combines a number of independent windows.portlet.page.faces.faces. click Add. Click Add. 4. Valid values for WebSphere Portal Server 6. Right click on the portlet. under the control of a portal server. Create a new Web Page to represent the initial content of the mode as described in the section Creating a Web Page. Under Portlet modes. In the Portlets list.faces. you will enter a predefined parameter name indicating the mode this JSP will support. In the Value field. Click OK.view com.page. 2. This section contains initialization parameters that are read when the portlet is loaded by the portlet container. Type the name of the mode ytaht you want to add.portlet. EGL library portalLib 474 EGL Programmer’s Guide . The requesting code usually has no details on the service location. which are customized units of software that run in a network. Like the requester. with the appropriate runtime technology. 2008 475 . SOA implies a style of development. with concern for the business as a whole and with an increased focus on modularity and reuse. and many aspects of the development task are unaffected. the invoked services are in a hierarchy. partners. while changes to the internal logic of a service require few or no changes to the requester The relative independence of the service and other software is called loose coupling. and customers. A service can handle interactions within your company. The technology is based on services. a change to a service orientation is a change in emphasis. The location is set when the service is deployed. Often. A service v Handles a business process such as calculating an insurance quote or distributing email.Overview of service-oriented architecture (SOA) SOA is a way of organizing software. © Copyright IBM Corp. as well as between your company and its suppliers. The location of service requesters can extend worldwide. the service can be almost anywhere. The flexibility offered by loose coupling protects your company from excessive costs when business or technical requirements change. From the point of view of a developer. or handles a relatively technical task such as accessing a database. can access a traditional program and respond to different kinds of requesters—for example. Structure of a service-oriented application A service-oriented application is an application composed largely of services. 1996. to Web applications v Is relatively independent of other software so that changes to a requester require few or no changes to the service. a requester or network may be able to redirect a request to a service at a different location. or provides business data and the technical details needed to construct a graphical interface v Can access another service and. At run time. depending on security issues and on the runtime software used to access a particular service. First. fulfill the three-level model described here. for example. an integration service might invoke a series of business services to verify the details provided by an insurance-policy applicant. Great complexity is possible. which calculates a quote and returns the quote to the software (for example. Many applications. each of which handles the relatively technical task of reading from and writing to data-storage areas such as databases and message queues. however. that the Web application can access a data-access service to assign initial values in a form. Some integration services.Web application Service-oriented application Integration service Business service Business service Data-access service Data-access service Data-access service Databases The topmost level contains one or more integration services. Business Implications of SOA SOA has several important implications for business. for example. The third level consists of data-access services. each of which controls a flow of activities such as processing an applicant’s request for insurance coverage. A data-access service is most often invoked from the business layer. a Web application) that invoked the service-oriented application. When each component is a relatively 476 EGL Programmer’s Guide . Each integration service invokes one or more business services. to the extent that loose coupling is in effect. changes made to the service logic won’t force significant changes to requesters of that software.″ the integration service invokes yet another business service. provide different operations to different requesters. If the business services return values that are judged to mean ″issue a policy. For example. The second level is composed of services that each fulfill a relatively low-level business task. and some invoke other integration services and are said to be composed of those services. but the easy access of services means. “Calling a local service” on page 483 You can call an EGL or native service that is local to your application without exposing that service as a Web service. in comparison to the testing required to deploy software that was written from scratch. Overview of service-oriented architecture (SOA) 477 . and deployment descriptor file. which currently include service programs on IBM i. which may be written in a language other than EGL. This topic concerns SOAP (Web) service invocation. Last. the firm’s business analysts and software professionals can share information knowledgeably. SOA also has an important effect on how people work together. by increasing the reliability of the software inventory over time. The firm can do less extensive testing if an existing service is placed in a new application. or as REST services. Related concepts “Elements of a service-oriented application” on page 478 The major elements of an EGL service-oriented application are the service part. “Calling a remote service” on page 485 You can call remote services from your EGL logic parts. letting the organization use the best available technologies. Notice The preceding overview of service-oriented architecture is largely from SOA for the Business Developer (http://www.html). Your company benefits from reuse in at least two ways: first. or native services. or SOAP (Web) services. well-designed services are more likely to be reusable. The only EGL-application that can access a REST service is a Rich UI application. and second. each of these files and parts has a role in both services and service requesters. a company’s ability to respond quickly and well to change is known as agility. To the extent that a collection of coarse-grained services handles your company’s business procedures. “Types of services” on page 481 You can generate your service parts as EGL services. published by MC Press. The main promise of service-oriented architecture is that a well-crafted SOA will increase agility over time. interface part. In general. An EGL-based requester can access EGL services. a service can even be redeployed to another machine without changing logic or recompiling the code. and can understand all the implications of changing a business procedure. by avoiding the expense of developing new software. meaning that the area of concern is broad enough so business people can understand the purpose of the service even if they know little about software. and the accessed service in that case may be written in EGL or another language. as SOAP (Web) services. can include end users in early deliberations about the purpose and scope of each service. Aside from the most technical services. Often. a well-written service is coarse-grained. your company can respond to business or technological changes more quickly and with less expense and confusion. In general.standalone unit. A further implication is that your company can develop services for different platforms and with different implementation languages. Ease of human communication is an important benefit of SOA and suggests that the architecture will become the primary organizing principle for business. Related tasks “Adding service client binding information from a WSDL file” on page 489 Service client binding information tells how the EGL runtime connects to a service being invoked by your EGL code.com/5079.mc-store. Related reference Service part Service parts provide requesters with access to the functions in the service. You can have only one service part in a file. the functions in a service are no different than those in a library: they receive parameters.“Exposing a service to other applications” on page 493 Your EGL application can act as a service by exposing its functions to other applications. end function subtractIntegers(intOne int in. Service part The service part is a logic part that exposes functions to other applications. Elements of a service-oriented application The major elements of an EGL service-oriented application are the service part. or other service. “Setting preferences for service generation” on page 498 You can set defaults for how your services are generated. perform logic. and that file can contain no other generatable parts. In other words. However. In EGL terms. and access data. A requester can be a local or remote program. return parameters. meaning that they do not remember interactions with a client or change after an interaction with a client. v Services can have private functions. v Requesters can call the functions in a service but cannot reference its variables. interface part. handler. In general. library. services differ from libraries in several ways: v Services can expose their functions to a wide range of applications. a service works much like a library: v Services are groups of functions. intTwo int in) returns (int) return (intOne + intTwo). Her is a example of a simple service part: Service calculatorService function addIntegers(intOne int in. it is as though that service is being used for the first time. while a library can remember changes in its global memory as long as its run unit is running. Fundamentally. and deployment descriptor file. intTwo int in) returns (int) 478 EGL Programmer’s Guide . 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. functions that can be called only by other functions in the same service. v Services are generatable parts. the global memory of a service is re-initialized every time it is used. each of these files and parts has a role in both services and service requesters. v Services are stateless. v Services can encapsulate functions that you want to reuse in other parts of your application. not just EGL applications. Each time a service is used. or summaries of functions.intTwo). parameters. An interface part is designed to be implemented by one or more service parts.calculatorInterface. This is an example of a simple interface part: interface calculatorInterface function addIntegers(intOne int in. Separate additional interfaces with commas. the interface part must be in scope for the service part to implement it. Interface parts are rarely required. its arguments. add the implements keyword after the service name. v Interfaces provide a concise summary of a service. but they can be helpful in the service development process: v The interface enables you to plan the service ahead of time. In this case. and its return value. See ″Function prototypes″ in the EGL Language Reference for more information on prototypes. intTwo int in) returns (int) return (intOne + intTwo).return (intOne . Like any type of part. A function prototype lists the function or method name. end function subtractIntegers(intOne int in. the function definitions in the service part must match the prototypes. followed by the interface name. using the same name. explaining what the service can do without providing all of the details of implementing the service.intTwo). intTwo int in) returns (int). import interfaces. end end Overview of service-oriented architecture (SOA) 479 . and return value. but no internal logic. Also. When a service part implements an interface part. intTwo int in) returns (int) return (intOne . that service part must define each function that is prototyped in the interface part. intTwo int in) returns (int). end end Interface part An interface part contains function prototypes. end To make a service implement an interface. function subtractIntegers(intOne int in. and EGL warns you if the service deviates from the interface. v Interfaces can serve as requirements for development or compliance. Service calculatorService implements calculatorInterface function addIntegers(intOne int in. the prototypes summarize functions in a service part. v Interfaces can be useful in accessing a service remotely. or SOAP (Web) services. You might encounter WSDL files in your EGL applications in two areas: v When acting as a requester of a service. In this case. see Overview of service access. because it will be overwritten each time you generate the deployment descriptor file. you can create parts and binding information directly from the WSDL file of the particular service. see Defining JEE enterprise applications (EARs). or native services. not to be confused with JEE 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. See “Adding service client binding information from a WSDL file” on page 489 for more information. see Web Services Description Language (WSDL). An EGL-based requester can access EGL services. which currently include service programs on IBM i.Deployment descriptor file The EGL deployment descriptor file (extension . 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. Related concepts “Types of services” on page 481 You can generate your service parts as EGL services. Therefore. The only EGL-application that can access a REST service is a Rich UI application. treat the WSDL file as you treat any generated output. For more information on Web Services Description Language (WSDL).egldd. v Web service deployment information lists service parts in your application that you want to expose to other applications. v When you generate a service part as a Web service. The information in the deployment descriptor includes details about how the service will be deployed and made available to other applications. “Overview of service-oriented architecture (SOA)” on page 475 Overview of service access Related tasks 480 EGL Programmer’s Guide . For a review of the difference between Web (SOAP) services and REST services. Web Services Description Language (WSDL) file Web Services Description Language (WSDL) files are a standard way of communicating information about Web (SOAP) services. or as REST services. For information on JEE deployment descriptors. but not about REST services. and the accessed service in that case may be written in EGL or another language. The EGL deployment descriptor is distinct from JEE deployment descriptors. EGL creates a WSDL file that other services can use to invoke your service. which may be written in a language other than EGL. 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. as SOAP (Web) services. and the accessed service in that case may be written in EGL or another language. library. or other service. The only EGL-application that can access a REST service is a Rich UI application. For details on the distinction between SOAP (Web) services and REST services. a name–along with service-access details that are associated with that key. Related reference Service part Service parts provide requesters with access to the functions in the service. you expose it by adding deployment information in the EGL deployment descriptor file. see “Exposing a service to other applications” on page 493. Services and requesters EGL services are based on the Service part.“Adding service client binding information from a WSDL file” on page 489 Service client binding information tells how the EGL runtime connects to a service being invoked by your EGL code. but only the Service part can be exposed to a requester. “Exposing a service to other applications” on page 493 Your EGL application can act as a service by exposing its functions to other applications. Interface part Interface parts provide access to a remote service. but if you fail to specify a Overview of service-oriented architecture (SOA) 481 . When coding a requester. For details. After you have written the Service part. This topic concerns SOAP (Web) service invocation. “Calling a local service” on page 483 You can call an EGL or native service that is local to your application without exposing that service as a Web service. such as a Web service. do as follows: v Add a service client binding in the deployment descriptor. including a Service part. The service client binding has a binding key–essentially. “Setting preferences for service generation” on page 498 You can set defaults for how your services are generated. handler. Any EGL logic part. which may be written in a language other than EGL. see Overview of service access. and in this way provide the details necessary to access the service. v Create a variable based on the Service part or on an equivalent Interface part. as SOAP (Web) services. You must set the complex property @BindService in the variable declaration. which currently include service programs on IBM i. A Service part can contain other parts. or as REST services. “Calling a remote service” on page 485 You can call remote services from your EGL logic parts. Parts Function prototypes Types of services You can generate your service parts as EGL services. A requester can be a local or remote program. a logic part similar to a library. can behave as a requester. or SOAP (Web) services. or native services. An EGL-based requester can access EGL services. v Relate the variable to the service client binding. myStatus = theService.theOperation(). – A failure to access the native service or a non-zero return code throws the exception ServiceInvocationException. If the native service returns an integer. v In the case of a Native binding. the following rules apply: – Parameters must be of fixed length. Related concepts “Overview of service-oriented architecture (SOA)” on page 475 Overview of service access Accessing IBM i programs as Web services “Elements of a service-oriented application” on page 478 The major elements of an EGL service-oriented application are the service part. For example. as suggested here: theService myEGLInterfacePart {@BindService{}}. You cannot change the binding detail at run time. data is transferred in a binary format that provides access to a System i® service program. data in transferred in a specific and widely used text-based format called SOAP. Related tasks 482 EGL Programmer’s Guide . the service code is included in the EGL-generated code. you can invoke a service operation named theOperation in either of two ways. The benefit of an EGL binding is that the connection is relatively fast because binary data is exchanged. The cost is that non-EGL code cannot access the service. In this case. Two kinds of access are supported: – If you are accessing that program from EGL-generated COBOL code that is on the same System i machine. myStatus INT. Binding requesters to services EGL provides different ways to bind requesters to services: v In the case of an EGL binding.binding key when you code that property. non-structured records are not supported. binary data is transferred in a format that is specific to EGL. nor is a value of type STRING. dynamic arrays are not supported. v In the case of a SOAP (Web) binding. – The service can return an integer or no value at all. use the protocol SYSTEM-I. In general. each of these files and parts has a role in both services and service requesters. use the protocol JAVA400. v In the case of a REST binding. Also. When your code accesses a System i service program. without using the extra runtime processing required to access a Web service. // either of the next invocations is valid if an integer is returned theService. as described in the EGL Language Reference appendix EGL core Exception records. interface part. – If you are accessing that program from EGL code on a Java platform. other EGL code can still access the service directly. data can be transferred across the Web. but not in the SOAP format. the system assumes that the binding key is the name of the part on which the variable is based. see “Calling a remote service” on page 485. and deployment descriptor file. Even if a service written in EGL is deployed as a Web service.theOperation(). For further details.LOCAL. The client binding information tells EGL where to find the service at run time. Open the client project’s deployment descriptor file. a local service is either an EGL service part (in your project or in a project that is in your project’s build path) or is a System i service program being accessed from an EGL-generated COBOL program that runs on the same machine.) 2. In the requester.“Calling a remote service” on page 485 You can call remote services from your EGL logic parts. end end 2. create the service part. intTwo int in) returns (int) return (intOne . 3.intTwo). Add a client binding to the deployment descriptor. “Calling a local service” You can call an EGL or native service that is local to your application without exposing that service as a Web service. A simple example of a service part follows: service CalculatorService function addIntegers(intOne int in. For more information. Create a program or other logic part to act as the requester. For a native service. In the case of an EGL service. Calling a local service involves these general steps: 1. intTwo int in) returns (int) return (intOne + intTwo). Create a client binding in the deployment descriptor file. Accessing a service in EGL Rich UI Calling a local service You can call an EGL or native service that is local to your application without exposing that service as a Web service. a. end function subtractIntegers(intOne int in. click Add. create a new one and add it as the value of the deploymentDescriptor build descriptor option. (You can also use an interface part to interact with the EGL service part. see “Calling a remote service” on page 485. create a variable based on the service or interface part and bind that variable to the service. The Add a Service Binding window opens. Overview of service-oriented architecture (SOA) 483 . under the heading Service Client Bindings. see “Creating a deployment descriptor” on page 94. In this context. “Exposing a service to other applications” on page 493 Your EGL application can act as a service by exposing its functions to other applications. Use the variable to access the service. 1. For other cases. On the Service Client Bindings page of the deployment descriptor editor. 4. create a service part with the functions that you want to expose to the requester. For an EGL service. 5. create an interface part that represents the functions being made available from the System i program. If the project does not have a deployment descriptor file. and then generate the service. b. The Service Name field is populated with the fully qualified name of the part. Note that this binding cannot be set at run time. Right-click the part and then click EGL Services → Create EGL Service Client Binding. click EGL Binding or Native Binding and then click Next. or library. and the EGL Binding Name field is populated with the default name for the client binding. Save. The definition includes one and only one of the following attributes: binddir. import services. For EGL Binding: 1) Next to the EGL Binding Name field. as described in the EGL Generation Guide. program localClientProgram type BasicProgram localEGLService CalculatorService. function main() end end 5. f. The part must be in scope. 2) Select the protocol SYSTEM-I LOCAL. which is the library in which the service program resides. Then. program localClientProgram type BasicProgram 484 EGL Programmer’s Guide . import services. click Browse. In the previous examples.c. provide the required details. the default name is be the same as the service part. 3. click Browse. Click Finish. 2) In the EGL Interface Selection window. close. which is a fully qualified binding directory such as LIBNAME/BIND_DIR_NAME. you can create the binding information directly from that part. or CalculatorService.CalculatorService. as used to access the service program.For details on those settings. 4. In the requester. You can change the name. create a variable based on the service or interface part. For Native Binding: 1) Next to the Native Binding Name field. Apply the @BindService complex property to the variable and set the bindingKey property field to the name of the client binding. select the service part that you want to access (or an interface part that identifies the functions of interest) and click OK. only at development time. g. If you have the service part in your workspace. this binding was named CalculatorService. In the Add a Service Binding window. see the EGL Generation Guide section on Deployment descriptor options for service clients. e.CalculatorService. Now the deployment descriptor has client binding information that points to the local service. In this case. choose a deployment descriptor file and fill in the protocol and attribute information. 3) Under Choose protocol type. You can update the binding information later by selecting the client binding and editing the information under EGL Service Client Binding Details. and generate the deployment descriptor. Create a program or other logic part to act as the requester. d. or a predefined shareable protocol based on SYSTEM-I LOCAL. program localClientProgram type BasicProgram localEGLService CalculatorService {@BindService{bindingKey = "CalculatorService"}}.addIntegers(5. Related reference Interface part Interface parts provide access to a remote service. you can use the service in an EGL logic part with a variable that represents the service. Calling a remote service You can call remote services from your EGL logic parts. outputString string. Related concepts “Overview of service-oriented architecture (SOA)” on page 475 Related tasks “Creating EGL source files” on page 90 The creation process is essentially the same for most EGL source files.writeStderr(outputString). handler. or other service. such as a Web service. outputString = "5+5=". SysLib.5). outputString += localEGLService. library. Overview of service-oriented architecture (SOA) 485 . “Calling a remote service” You can call remote services from your EGL logic parts.CalculatorService. or service) that invokes a service. A requester can be a local or remote program. function main() end end 6. Service part Service parts provide requesters with access to the functions in the service. library. generate.localEGLService CalculatorService {@BindService{bindingKey = "CalculatorService"}}. end end 7. you can use the service through the variable: import services. function main() SysLib. “Creating a deployment descriptor” on page 94 The EGL deployment descriptor provides service-binding detail when you are generating a service. handler. and run the program. as well as service-binding detail when you are generating a logical unit (program. “Creating a service-access variable and binding it to a service” on page 491 After you have created binding information for a service. After you have created a variable that represents a service and bound that service to the service part using the client binding information. Save.writeStderr("Calling local EGL service: "). click SOAP (Web) Binding. Open the deployment descriptor in the deployment descriptor editor. do as follows: 1. follow the steps described in Adding service client binding information for an EGL service. 3. bind that variable to the service using the binding information. However. v In the Session Cookie ID field. In most cases. you create service client binding information that tells EGL where to find the service at run time. you must be accessing the service from a Rich UI application. it is up to you to ensure that the function prototypes in the interface part accurately represent the real functions in the service. property field bindingKey. To add the service client binding information for a remote service. click Add. 5. specify a string that identifies the first qualifiers in the URI being used to access the service.EGL Binding. In the Add a Service Binding window. Specify the following details. The name will be the value of the property @BindService. or Native Binding and then click Next. Next to the Native Binding Name field. In a logic part. This name will be the value of the bindingKey property field when you declare a variable to invoke the service. For EGL Binding. specify a string that identifies the session cookie provided to the EGL Rich UI Proxy from a service. 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. 2. click Browse next to the EGL Binding Name field name and retrieve an Interface or Service part. v Alternatively. under the heading Service Client Bindings. 4. and receive any return variable. EGL can create an interface part automatically from the information in the WSDL file. as used when you declare a variable to invoke the service. v In the baseURI field. you create a variable that is based on the interface part or service part. On the Service Client Bindings page of the deployment descriptor editor. 7. 2. v If you are using an EGL service.Fundamentally. In your deployment descriptor file. which are explained in Creating an Interface part to access a REST service and Declaring an interface to access a REST service: v Specify the EGL binding name. For SOAP (Web) Binding. calling a service is equivalent to calling a function in an EGL library: you specify the name of the function in the service. In this case. you can copy an interface part or service part from the other application. See “Creating a service-access variable and binding it to a service” on page 491 for more information. 3. 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. click Browse. 6. 486 EGL Programmer’s Guide . follow the steps described in Adding service client binding information from a WSDL file. and then use the service through the variable. you can create your own interface part. Calling a remote service has the following general steps: 1. pass any required arguments. REST (Web) Binding. For REST (Web) Binding. For Native Binding: a. Related concepts “Overview of service-oriented architecture (SOA)” on page 475 Related tasks “Adding Web service deployment information to the deployment descriptor” on page 496 After you have coded a service part that you want to expose as a Web service. 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: Overview of service-oriented architecture (SOA) 487 . not a non-structured record or of type STRING. Select the protocol JAVA400. such as a Web service. Related reference Interface part Interface parts provide access to a remote service.b. handler. For details on adding binding information for a Web service. A requester can be a local or remote program. “Adding service client binding information for an EGL service” Service client binding information tells how the EGL runtime connects to a service being invoked by your EGL code. or other service. Note that the service parameters in this case must be of fixed length. library. Creating an Interface part to access a REST service Declaring an interface to access a REST service “Calling a local service” on page 483 You can call an EGL or native service that is local to your application without exposing that service as a Web service. you must add information to the deployment descriptor that tells EGL to generate the necessary Web service wrapper. This topic concerns EGL service invocation. For details on the required settings. Click Finish. You can update the binding information later by selecting the client binding and editing the information under EGL Service Client Binding Details. see the EGL Generation Guide section on Deployment descriptor options for service clients. not Web service invocation. 8. see “Adding service client binding information from a WSDL file” on page 489. This topic concerns EGL service invocation. “Adding service client binding information from a WSDL file” on page 489 Service client binding information tells how the EGL runtime connects to a service being invoked by your EGL code. not Web service invocation. This topic concerns SOAP (Web) service invocation. Adding service client binding information for an EGL service Service client binding information tells how the EGL runtime connects to a service being invoked by your EGL code. or a predefined shareable protocol based on JAVA400. Service part Service parts provide requesters with access to the functions in the service. 5. as well as service-binding detail when you are generating a logical unit (program. In the EGL Interface Selection window. The new client binding is listed in the Service Bindings list. Adding the service client binding information To add the service client binding information: 1. 8. 7. On the Add an EGL Binding page. click Add. handler. Click Finish. On the Service Client Bindings tab. In this case. You can accept the default value for the EGL Binding Name or type a different name. Related tasks “Overview of service-oriented architecture (SOA)” on page 475 “Creating a deployment descriptor” on page 94 The EGL deployment descriptor provides service-binding detail when you are generating a service. Right-click the part and then click EGL Services → Create EGL Service Client Binding. you can use that part directly as a local service. click EGL Binding and then click Next. This name will be the value of the bindingKey property field when you use the service in your logic parts. under the Service Client Bindings heading. See “Calling a local service” on page 483 for more information. – If you do not have access to the other project. 6. choose a deployment descriptor file and fill in the protocol and attribute information for the binding as in the steps above. 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. it is up to you to ensure that the function prototypes in the interface part accurately represent the real functions in the service. In the Add a Service Binding window. Then. library. Now you can use the binding in your code as explained in “Creating a service-access variable and binding it to a service” on page 491. 3.– 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. or service) that invokes a service. click the Browse button. v Otherwise. you can create an interface part with functions that match the functions in the service. Alternately. select the interface part or service part that you will use to represent the service and click OK. Open the deployment descriptor in the deployment descriptor editor. you can create the binding information directly from that service part. if you have the service part in your workspace already. which is next to the EGL Binding Name field. 2. – You can copy a service part or interface part from another EGL project to use in your project. 4. You can update the binding information later by selecting the client binding and editing the information under EGL Service Binding. v Choose LOCAL for a service in the same project or within your project’s build path. 488 EGL Programmer’s Guide . choose a specific protocol type and then fill in the information for the binding in the Attributes list. This topic concerns SOAP (Web) service invocation. the Browse mechanism lets you search throughout your Workspace. Under Interface Options. 4. click Web Binding and then click Next. “Calling a local service” on page 483 You can call an EGL or native service that is local to your application without exposing that service as a Web service. you must ensure that the function prototypes in the Interface part accurately represent the functions in the service. Adding the service client binding information 1. or other service. “Creating a service-access variable and binding it to a service” on page 491 After you have created binding information for a service. clicking EGL Build Path. You can accept the default value for the Web Binding Name or type in a different name. 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. Overview of service-oriented architecture (SOA) 489 . located somewhere in your workspace. You can also create your own Interface part and select it under Use existing EGL interface. 6. 3. In this case. If that checkbox is checked. A requester can be a local or remote program. Related reference Interface part Interface parts provide access to a remote service. click Generate EGL Interface from WSDL file. Service part Service parts provide requesters with access to the functions in the service. Open the EGL deployment descriptor in the deployment descriptor editor. If that checkbox is cleared. you can use the service in an EGL logic part with a variable that represents the service. (You can access the build-path details by right clicking your project. 2. Next to the WSDL File field.“Adding service client binding information from a WSDL file” Service client binding information tells how the EGL runtime connects to a service being invoked by your EGL code. and at the resulting dialog box. Adding service client binding information from a WSDL file Service client binding information tells how the EGL runtime connects to a service being invoked by your EGL code. the Browse mechanism lets you search in the EGL source folders of your project and in the EGL source folders of any project listed in your project’s EGL build path. In the Add a Service Binding window. such as a Web service. library.) 5. under the Service Client Bindings heading. On the Service Client Bindings tab. This topic concerns SOAP (Web) service invocation. click Add. The name will be the value of the bindingKey property field when you access the service. This choice represents the preferred method for creating an Interface part to represent the service at development time. you can select the checkbox Choose WSDL file from workspace and copy it to the current project if the WSDL file is not in your EGL project but is elsewhere in your workspace. clicking Properties. handler. select the ports that you want to generate into interfaces. In the WSDL URI field. 9. Click Next. 12. select the name of the deployment descriptor file to add information to. 10. Related tasks “Creating a deployment descriptor” on page 94 The EGL deployment descriptor provides service-binding detail when you are generating a service. you can enter that location here and use that version of the service. select the interfaces you want to use from the WSDL file. Click Next. 2. or service) that invokes a service. you have the option of specifying a string that overrides the URL specified in the WSDL file. handler. See “Creating a service-access variable and binding it to a service” on page 491. Click Finish. If you know that the service is available at a location other than the location specified in the WSDL file. Click Next. In the EGL deployment descriptor file name field. If you want to update information already in a deployment descriptor file. 11. Click Next. 8. You can select or clear the check box for any of the functions and in this way choose which functions are represented in the new Interface part. You can select or clear the check box for any of the functions to choose which functions will be in the new interface part. and EGL source file name fields. In the Project Explorer view. On the next page. each interface has a tab on which each function in the selected interfaces is listed. right-click the WSDL file and then click Create EGL Interfaces and Web Client Binding. In the table of ports. You can change the binding name. Set the location and name for the new interface part in the Source folder.7. 490 EGL Programmer’s Guide . select the Update all existing bindings check box. Shortcut You can add client binding information directly from a WSDL file in your project with the following shortcut: 1. Click Finish. 3. 7. Set the location and name for the new interface part in the Source folder. 4. library. Package. On the next page. 10. 6. 8. such as a different version of the service used for production or testing. On the New EGL Interface page. 13. 9. as well as service-binding detail when you are generating a logical unit (program. which is the label for the Web service deployment listing in the deployment descriptor file. Now you can create variables based on the interface part and use these variables to access the service. Package. 5. each Interface part has a tab that lists each function in the selected Interface part. and EGL source file name fields. On the New EGL Interface page. select the Interface parts that you want to create from the WSDL file. abs() directly). you type the name of the library. Service. such as a Program. A requester can be a local or remote program. 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. followed by any arguments the function expects: myInt int = MathLib. or Handler Binding a variable explicitly To bind a variable to an external service. Overview of service-oriented architecture (SOA) 491 . or other service. to the service itself. calling a service requires more preparation than calling a library. An Interface part or Service part.“Creating a service-access variable and binding it to a service” After you have created binding information for a service. and the name of the function. In the previous example. or bound. Library. such as a Web service. you can use the service in an EGL logic part with a variable that represents the service. Creating an Interface part to access a Web service in Rich UI Declaring an interface to access a Web service in Rich UI Related reference Interface part Interface parts provide access to a remote service. However. 2).addIntegers(1. a period. but instead is using a variable that represents that service. Any EGL logic part. Service part Service parts provide requesters with access to the functions in the service. library. Creating a service-access variable and binding it to a service After you have created binding information for a service. you can use the service in an EGL logic part with a variable that represents the service. The binding information in the deployment descriptor file tells EGL how to bind that variable to the service at run time. A call to a function within a service looks the same because the call uses similar syntax: mySum int = Calculator. “Calling a local service” on page 483 You can call an EGL or native service that is local to your application without exposing that service as a Web service. However. Prerequisites v v v v An EGL project Client binding information for a Web service or an EGL 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. When you call a function within a library. the call to a service is different because the code is not calling the service directly (as the example above called MathLib. Calculator is a variable that is created from a Service part or Interface part and then linked. “Calling a remote service” on page 485 You can call remote services from your EGL logic parts. handler.abs(-5). Use the bindService() function to bind the variable to the service implementation: myTranslator = ServiceLib.CalculatorService" name="CalculatorService"/> In this case. but the @BindService complex property is still required: myCalculator CalculatorService {@BindService}. assume the following entry in the deployment descriptor file: <webBinding interface="interfaces. 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.SpeechTranslator" name="TranslateGerman" port="GermanPort"/> You could create and bind two variables. 1.bindService("TranslateSpanish"). use functions in the EGL library ServiceLib instead of the @BindService property. If you do not specify a value in the bindingKey property field. Suppose that you have created entries in the deployment descriptor file for two slightly different service implementations: <webBinding interface="interfaces.getQuote("IBM").SpeechTranslator" name="TranslateSpanish" port="SpanishPort"/> <webBinding interface="interfaces. 2. For example. mySum int = myCalculator.StockQuote" name="quoteBinding"/> This entry is named quoteBinding and refers to an Interface part or Service part in the interfaces package named StockQuote. 492 EGL Programmer’s Guide .addIntegers(1. one for each of these entries.For example. or to change the service to which a variable is bound. An alternate way is to create one variable based on the Interface part that the entries share. you can omit the bindingKey property field. Create a variable that is based on the Interface or Service part in the deployment descriptor entry: myTranslator SpeechTranslator. EGL assumes that the name of the entry in the deployment descriptor matches the name of the Interface part or Service part. 1).bindService() system function to bind the variable to the service that you want to use. 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 489: <webBinding interface="interfaces. and then use the ServiceLib. This option is not available for local access of a native service on System i. To bind a variable dynamically. Binding a variable dynamically Dynamic binding enables you to choose a service at run time. “Calling a local service” on page 483 You can call an EGL or native service that is local to your application without exposing that service as a Web service. Optionally. its parameters.bindService("TranslateGerman"). Distribute the binding information for your service so other applications can connect to your service. Creating an EGL service has these general steps: 1. Overview of service-oriented architecture (SOA) 493 .translate ("This sentence is in Spanish"). A requester can be a local or remote program. You can put the Interface part in the same package as your service or in another package. 4. or other service. define one or more Interface parts. such as a Web service. 3. but have no internal logic. and its return value. Code one or more EGL Service parts and any other parts they may need. handler. Creating an interface (optional) 1. the myTranslator variable is now bound to the entry in the deployment descriptor file named TranslateSpanish. This topic concerns SOAP (Web) service invocation. See “Creating EGL source files” on page 90.translate ("This sentence is in German"). “Calling a remote service” on page 485 You can call remote services from your EGL logic parts. library. Interface parts contain function prototypes. you can use the variable to access the alternate implementation of the service: myGermanString string = myTranslator. 3. Use the variable to access the service: mySpanishString string = myTranslator.In this case. 4. which list the function’s name. Service part Service parts provide requesters with access to the functions in the service. Add binding information for the service in the EGL deployment descriptor file. At this point. Related tasks “Adding service client binding information from a WSDL file” on page 489 Service client binding information tells how the EGL runtime connects to a service being invoked by your EGL code. This topic concerns EGL service invocation. Create an EGL Interface part. Exposing a service to other applications Your EGL application can act as a service by exposing its functions to other applications. Related reference Interface part Interface parts provide access to a remote service. Later. “Adding service client binding information for an EGL service” on page 487 Service client binding information tells how the EGL runtime connects to a service being invoked by your EGL code. you can use bindService() again to bind the service to a different implementation: myTranslator = ServiceLib. 5. 2. not Web service invocation. the scoping rules for interfaces are the same as for any other part. the service must define each function that is prototyped in each interface. These functions are referred to as public. In the Interface part. EGL creates stub functions for the functions that are defined in the interface. and the input and output parameters of those functions must match those of the prototypes in the interface. When a service implements an interface. as well as if any function prototype in the interface is not defined in the service. intTwo int in) returns (int) return(intOne + intTwo). you can select an interface to implement when you create the service. 1. end Provide prototypes in the interface only for the functions that you intend to expose to other applications. including any functions defined in the interface and any private functions your services may need: package services. EGL produces an error if any function in a service does not match the prototype of the same name in the interface. Only the service itself can access its private functions. interface calculatorInterface function addIntegers(intOne int in. Create an EGL Service part. including the name of the function. If you want the Service part to use an interface. and its return value. function subtractIntegers(intOne int in. write function prototypes that describe the functions your service performs. service calculatorService implements interfaces. In that case. intTwo int in) returns (int).calculatorInterface //Add functions here. In this case. Also. end Alternately. that service must define each function that is listed in the interface. and those additional functions can optionally be defined as private. intTwo int in) 494 EGL Programmer’s Guide . Write the code for the functions in the service. See “Creating EGL source files” on page 90.2.calculatorInterface function addIntegers(intOne int in. Coding a Service part You code a Service part in much the same way as a Library part. its parameters and their types. a service can implement more than one interface. intTwo int in) returns (int). The service can contain functions that are not described in the interface. Functions in a service are public by default. 2. service calculatorService implements interfaces. add an implements clause to the service part: package services. 3. but any logic part or application can access the public functions of the service. if any: package interfaces. end function subtractIntegers(intOne int in. library. handler.returns (int) return(intOne . handler. end private function getAbsoluteValueInteger(intOne int in) returns(int) return(MathLib. end end Adding Web service deployment information Now.intTwo). such as a Web service. you must distribute its information so client applications can use the service. “Calling a local service” on page 483 You can call an EGL or native service that is local to your application without exposing that service as a Web service. library. you must distribute the WSDL file that is created when you generate the project. or for an EGL client application to access the service through a Web service connection. or other service. or service) that invokes a service. “Creating a deployment descriptor” on page 94 The EGL deployment descriptor provides service-binding detail when you are generating a service. as well as service-binding detail when you are generating a logical unit (program. Distribute the binding information After you have coded and deployed your service application. For an EGL client application to access your service. you need only distribute the binding information that the client needs. EGL requesters can access your Service part directly. you must add information to the deployment descriptor that tells EGL to generate the necessary Web service wrapper. See Adding Web service deployment information to the deployment descriptor. Service part Service parts provide requesters with access to the functions in the service. you must expose your service as a SOAP or REST service. “Creating EGL source files” on page 90 The creation process is essentially the same for most EGL source files. “Calling a remote service” on page 485 You can call remote services from your EGL logic parts. Related reference Interface part Interface parts provide access to a remote service. Related tasks “Adding Web service deployment information to the deployment descriptor” on page 496 After you have coded a service part that you want to expose as a Web service. which involves adding Web service deployment information to the deployment descriptor file. For a non-EGL client application to access the service.abs(intOne)). A requester can be a local or remote program. However. for non-EGL requesters to access the service. Function prototypes Overview of service-oriented architecture (SOA) 495 . the WSDL service and port elements. In the CICS URI field. indicate whether you want EGL to generate the Web service each time you generate the deployment descriptor. 5. 2. for example. specify a value in the Style field. Click Finish. If you intend to create the WSDL file later. select document-wrapped unless the requesters need rpc. 4. you also may need to specify the access details under Platform-Specific Properties. or highlight the service-binding name and click Open. 6. 3.com. a REST (Web) service. Prerequisites v An EGL project v A Service part v An EGL deployment descriptor file Adding the deployment information 1. within that file. or both. Click Add. 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. Avoid the overhead of generating the Web service if you are not changing the service part when you generate the deployment descriptor. If you check Use Existing WSDL file.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. as well as the URI used to access the service. In the Add Web Services window. specifically. If you intend to run the SOAP (Web) service on CICS.example. where serviceName is the name of the Service part: services/serviceName 496 EGL Programmer’s Guide . indicate whether you want to identify the service characteristics with an existing WSDL file. and if so. Select a service part in the list on the left: v In the Generate column. v To access the service logic. whether you want the service generated as a SOAP (Web) service. URI The qualifier you are specifying. assign the low-level qualifier for the address used to access the SOAP service. double-click an entry in the Implementation column. you can specify the WSDL file and. Each service part that you chose is listed on the Services Deployment page. www. By default. the value is as follows. Additional information varies by service type: v For a SOAP (Web) service. the access protocol. The full address is as follows: http://domain:portNumber/URI domain The domain name. you must add information to the deployment descriptor that tells EGL to generate the necessary Web service wrapper. portNumber The number of the server-machine port that receives the request. Open the EGL deployment descriptor file and go to the Service Deployment tab. you can select or clear the Stateful checkbox to indicate whether the service is providing access to a stateful host program on IBM i. See Deployment descriptor options for service clients. enter a mnemonic for the new protocol. assign the low-level qualifier for the address used to access the REST service. In general. The issue is explained in Accessing IBM i programs as Web services. portNumber The number of the server-machine port that receives the request. 5. In relation to WebSphere Application Server. 7. select a type of protocol. see “Creating a deployment descriptor” on page 94. the value is in the JEE EAR deployment descriptor (application. 4. Open the EGL deployment descriptor file for your project. 6. The full address is as follows: http://domain:portNumber/contextRoot/restservices/URI domain The domain name. In the deployment descriptor editor. The default is the name of the Web project. Under Attributes. and deployment descriptor file. Use Local for services in the same project. which in most cases causes an automatic generation of output from that file. Under Choose protocol type.com. 2. www. go to the Protocols tab. The new protocol is listed under Sharable Protocols. If your project does not have a deployment descriptor file. To create and use a shared protocol: 1. In the Protocol Name. Under Sharable Protocols. click Add. set the options for the protocol. 7. Click Finish. Accessing IBM i programs as Web services “Overview of service-oriented architecture (SOA)” on page 475 Related tasks “Exposing a service to other applications” on page 493 Your EGL application can act as a service by exposing its functions to other applications. each of these files and parts has a role in both services and service requesters. Also. 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. These options differ for each type of protocol. Related concepts “Elements of a service-oriented application” on page 478 The major elements of an EGL service-oriented application are the service part.v For a REST (Web) service. and you can use that protocol when you create a new service client binding or Web service binding.xml). in the URI field. Related tasks Overview of service-oriented architecture (SOA) 497 . URI The qualifier you are specifying. Save the deployment descriptor. The Add Protocol window opens.example. for example. 3. interface part. contextRoot A setting in the Web project. expand EGL and click Service. From the menu bar. 3. In the left pane of the Preferences window. This topic concerns SOAP (Web) service invocation. 2. 4. v Under WSDL Generation. 1. enter the default host name and port to place in WSDL files generated to describe EGL Web services. Related concepts “Overview of service-oriented architecture (SOA)” on page 475 Related tasks “Setting general preferences” on page 173 498 EGL Programmer’s Guide . You can restore the default settings by clicking Restore Defaults. In the right pane of the Preferences window. “Calling a local service” on page 483 You can call an EGL or native service that is local to your application without exposing that service as a Web service. Setting preferences for service generation You can set defaults for how your services are generated. click Window → Preferences. select the preferences for generating Web services: v Under WSDL Document Style/Encoding. select Document-Literal Wrapped unless the requesters require RPC-Literal. Click OK to save your changes. The Preferences window opens.“Calling a remote service” on page 485 You can call remote services from your EGL logic parts. “Adding service client binding information from a WSDL file” on page 489 Service client binding information tells how the EGL runtime connects to a service being invoked by your EGL code. You can use the EGL Text UI technology to create a very basic user interface. If you press the F3 key. Properties determine how each field is displayed or printed within the form. like one you would find on a mainframe.eventKey not pf3) myTextForm. end if (ConverseVar. The EGL converse statement gives control to the form.msgField = myMessage. myMessage char(25) = "myMessage". A form contains fields that are displayed together on a screen page or sent together to a printer. Example To create a simple Text UI program. control returns to the program and the program processes the information in the form.eventKey is pf1) myMessage = "Hello World". This means you can generate programs for both COBOL and Java that present an identical interface to the user. function main() while (ConverseVar. when the user presses a key. 1996. Text UI programs carry on a conversation with the user. converse myTextForm. 2008 499 . if (ConverseVar.80]} msgField CHAR(80).eventKey is pf3) exit program. the program exits. end end Next. end end end end If you press the F1 key. the message changes from ″myMessage″ to ″Hello World″.Building EGL Text User Interface applications A Text UI application presents a text-based user interface similar to that of a 5250 or 3270 terminal. create a program with a use statement that references the FormGroup: Program HelloWorld type textUIprogram {} use myFormgroup. Related concepts “Elements of a text user interface application” on page 500 A Text UI application relies on Form parts to define a user interface. in a new EGL source file. © Copyright IBM Corp. first create a FormGroup in a new EGL source file: FormGroup myFormGroup Form myTextForm type textForm {formSize=[10. Text UI interfaces are based on forms. Each EGL Form part must be part of a FormGroup. a subtype of text forms. Related reference FormGroup part Form part Building EGL Text User Interface applications with the Text Form editor With the EGL Text Form editor. You can switch between the graphical representation and the source code by clicking the Design and Source tabs at the bottom of the editor.Text UI A text UI application presents a text-based user interface similar to that of a 5250 or 3270 terminal. display help information to explain how the interface works. v A print form defines a layout that is sent to a printer. A Form part can be one of the following two types: v A text form defines a layout that is displayed on a 3270 screen or in a command window. which displays the EGL properties of the form or field currently selected in the editor. 500 EGL Programmer’s Guide . v The Palette view. v The Properties view. their form parts. Help forms. Form parts Form parts describe a set of fields on a user interface. At any time. Changes to the Source view or Design view are reflected immediately in the other view. which displays the types of forms and fields that can be created in the editor. FormGroup parts A FormGroup part contains one or more Form parts. The Text Form editor works with FormGroup parts. you can click the Source tab at the bottom of the editor and see the EGL source code that the editor is generating. which displays the graphical representation of the form group and that form group’s source code. you can edit a FormGroup part graphically. Text UI A text UI application presents a text-based user interface similar to that of a 5250 or 3270 terminal. The Text Form editor has these parts: v The editor itself. and the fields in those form parts in much the same way as other graphical editors work with files such as Web pages and Web diagrams. Related reference FormGroup part Form part converse considerations for Text UI Elements of a text user interface application A Text UI application relies on Form parts to define a user interface. Related concepts “Building EGL Text User Interface applications” on page 499 A Text UI application presents a text-based user interface similar to that of a 5250 or 3270 terminal. To resize a form group. enabling you to mimic the appearance of the form group at run time. which displays a hierarchical view of the form group open in the editor. and fields. To edit the properties of a form group. Many of the same options are available when you right-click a form to open its menu. edit. These templates are listed in the Templates drawer of the Palette view. and show or hide sample values in fields. See “Filtering the editor” on page 509. edit. and delete fields in a form. To switch filters. v The Text Form editor uses templates to create commonly used types of forms. click it to select it. or edit filters. See “Creating a simple text or print form” on page 502. increase or decrease the zoom level. The Text Form editor has these features: v The Text Form editor can edit the size and properties of a form group. and then use the Properties view to edit its properties. See“Creating a constant field” on page 502 or “Creating a variable field” on page 503. these options can display a grid over the form group. To create a field. v The Text Form editor can create. create a filters. To create a form. “Creating a form from a template” on page 505. “Setting preferences for the Text Form editor palette entries” on page 512 “Setting bidirectional text preferences for the Text Form editor” on page 511 Related reference “Display options for the EGL Text Form editor” on page 510 FormGroup part Form part Building EGL Text User Interface applications 501 . These forms have pre-made borders. Related tasks “Creating a simple text or print form” on page 502 “Setting preferences for the Text Form editor” on page 510 “Creating a form from a template” on page 505 The EGL Text Form editor uses templates to create commonly used types of forms and fields. click it to select it. You can add a field only within an existing form. such as popup forms and popup menus. See“Display options for the EGL Text Form editor” on page 510 or “Setting preferences for the Text Form editor” on page 510. For example. open it in the Text Form editor and choose a size in characters from the list at the top of the editor. You can also drag a form to move it. drag a field to move it. you can create. click the appropriate type of field on the Palette view and draw a rectangle that represents the size and location of the field in the editor. You can also copy and paste a field. and then use the Properties view to edit its properties. To edit a form. open the form group in the Text Form editor and change its properties in the Properties view. v You can customize the appearance of the Text Form editor by using the display options at the top of the editor and by setting the editor preferences in the Preferences window. and delete forms in a form group. or resize a field using the resize handles that are on the border of a selected form.v The Outline view. use the Filters button at the top of the editor. v With the Text Form editor. v Filters can prevent forms from being shown in the Text Form editor. click the appropriate type of form on the Palette view and draw a rectangle that represents the size and location of the form in the editor. Many of the same options are available when you right-click a field to open its menu. sections. To edit a field. or resize it using the resize handles that are on the border of a selected form. type a name for the form in the Enter part name field. add a form to the form group. 2. See “Creating a form from a template” on page 505. This name will be the name of the form part in the EGL source code.” 3. See“Creating a constant field” and “Creating a variable field” on page 503. To insert a constant field into a form. constant fields cannot be accessed by EGL code. See “Creating a simple text or print form. click and drag a rectangle that indicates the size and shape of the form. 7. 3. click either Text Form or Print Form. These templates are listed in the Templates drawer of the Palette view. 5. Click the form and edit its properties in the Properties view. follow these steps: 1. If the form group has no forms. Click OK. Open a form group in the EGL Text Form editor. click a type of constant field to add. On the form group in the editor. 2. Add fields to the form as appropriate. You can also create forms based on the templates in the Palette view.“Filtering the editor” on page 509 Creating a simple text or print form To 1. Related concepts “Building EGL Text User Interface applications with the Text Form editor” on page 500 “Display options for the EGL Text Form editor” on page 510 Related tasks “Filtering the editor” on page 509 “Creating “Creating “Creating “Creating a a a a popup form” on page 506 popup menu” on page 507 constant field” variable field” on page 503 “Creating a form from a template” on page 505 The EGL Text Form editor uses templates to create commonly used types of forms and fields. The following types of constant fields are available by default: 502 EGL Programmer’s Guide . 4. Related reference Form part Creating a constant field Constant fields display a string of text that does not change in a form. Unlike variable fields. On the Palette view. On the Palette view. 6. These templates create forms with predefined appearances and fields. follow these steps: Open a form group in the Text Form editor. In the Create Form Part Window. The Create Form Part window opens. create a form in the EGL Text Form editor. The following types of variable fields are available by default: Table 55. See “Setting preferences for the Text Form editor palette entries” on page 512. Unlike constant fields. When the field is the correct size. 6. Open a form group in the EGL Text Form editor. click a type of variable field to add. Type the text you that want to display in the field. In the Properties view. 7. You can customize the individual fields after placing them on a form. To insert a variable field into a form. On the Palette view. If the form group has no forms. 4. click and hold the mouse to draw a rectangle that represents the size and location of the field. A preview box next to the mouse cursor shows you the size of the field and its location relative to the form. Variable fields that are available in the Palette view Field name Input Output Message Default color Green Green Red Default intensity Normal Normal Bold Default highlighting Underlined None None Default protection No Skip Skip Building EGL Text User Interface applications 503 . 5. set the properties for the new field. intensity. Within a form in the editor. You can also customize the default color. See “Creating a simple text or print form” on page 502.Table 54. Constant fields that are available in the Palette view Field name Title Column Heading Label Instructions Help Default color Blue Blue Cyan Cyan White Default intensity Bold Bold Normal Normal Normal Default highlighting None None None None None Default protection Skip Skip Skip Skip Skip These fields are samples of commonly used constant text fields in a text-based interface. 2. Related concepts “Building EGL Text User Interface applications with the Text Form editor” on page 500 Related tasks “Setting preferences for the Text Form editor palette entries” on page 512 “Creating a variable field” Related reference Form part Creating a variable field Variable fields can serve as input or output text in a form. Note: You can add a field only within an existing form. add a form to the form group. Each variable field is based on an EGL primitive or a DataItem part. 3. release the mouse. The new field is created. variable fields can be accessed by EGL code. and highlighting of the fields that are available in the Palette view. follow these steps: 1. If the Array check box is selected. see ″Form field properties″ in the EGL Language Reference. For example. A preview box next to the mouse cursor shows you the size of the field and its location relative to the form. type the name of the new field in the Name field. see Form field properties. You can customize the individual fields after placing them on a form. 15. Click dataItem from the Type list. click a primitive type from the Type list. click the field to select it and set the properties for the field in the Properties view. select the Array check box. Under Spaces. You can also customize the default color. Choose an orientation of Down or Across from the Index Orientation buttons. On the Array Properties page of the New EGL Field window. Within a form in the editor. 12. Do one of the following to select the type of field: v To use a primitive type. The Select a DataItem Part window opens. and highlighting of the fields available in the Palette view. Note: You can add a field only within an existing form. Be aware that display properties affect the way EGL displays the variable on a printed form or on the screen. but not the way the variable is stored. 14. The New EGL Field window opens. setting the align property to right for a CHAR variable does not 504 EGL Programmer’s Guide . 7. Click Finish. 11. The new field is created and you do not need to follow the rest of these steps. If you want to make the field an array. 9. 8. As necessary. click Next and continue following these steps. because they are applicable only if you are creating an array. For more information about properties for form fields. The new field is created in the form group. When the field is the correct size. c. v To use a DataItem part. 5. click Finish and stop here. In the Select a DataItem Part window. 4. After you have created the new field. release the mouse. See “Setting preferences for the Text Form editor palette entries” on page 512. 13. Variable fields that are available in the Palette view (continued) Field name Password Default color Green Default intensity Invisible Default highlighting None Default protection No These fields are samples of commonly used variable text fields in a text-based interface. 10. 6. click a DataItem part from the list or type the name of one. For more information about properties for form fields. Click OK.Table 55. click and hold the mouse to draw a rectangle that represents the size and location of the field. In the New EGL Field window. type the size of the array in the Array Size field. b. type the amount of space between the array’s rows and columns in the Lines between rows and Spaces between columns fields. type values in the Dimensions field or fields to set the dimensions of the new variable field. type the number of vertical and horizontal fields in the Fields Down and Fields Across fields. Under Layout. Otherwise. follow these steps: a. intensity. These forms have pre-made borders. When you are finished editing the field’s properties in the Edit Type Properties window. see“Creating a popup form” on page 506 or “Creating a popup menu” on page 507. v Change the precision of the field by specifying a new number in the Precision field. These templates are listed in the Templates drawer of the Palette view.) Because variable fields have no default value. To create a form from a template. you can double-click it in the editor to open the Edit Type Properties window. The Text Form editor can create forms from templates. they can be invisible if they are not highlighted. and fields. To create fields representing data from an EGL record. To mark each variable field with appropriate sample text.right-align the contents of the variable. v Select a new type of field from the Type list. Related concepts “Building EGL Text User Interface applications with the Text Form editor” on page 500 Related tasks “Setting preferences for the Text Form editor palette entries” on page 512 “Creating a constant field” on page 502 Related reference Form part Creating a form from a template The EGL Text Form editor uses templates to create commonly used types of forms and fields. (For a shortcut to right-justify a variable. Related concepts “Building EGL Text User Interface applications with the Text Form editor” on page 500 “Creating a form from a template” The EGL Text Form editor uses templates to create commonly used types of forms and fields. From this window you can edit the field in the following ways: v Change the field’s name by typing a new name in the Field Name field. EGL right-aligns the information on the page or screen only. After you have created a variable field. click OK. see “Displaying a record in a text or print form” on page 507. The Text Form editor can create a group of fields using an EGL record as a template. Related tasks “Setting preferences for the Text Form editor” on page 510 “Creating a simple text or print form” on page 502 “Creating a constant field” on page 502 “Creating a variable field” on page 503 “Creating a popup menu” on page 507 Building EGL Text User Interface applications 505 . sections. see “Right-justifying a character variable” on page 146. click the Toggle Sample Values button at the top of the editor. These templates are listed in the Templates drawer of the Palette view. When you are finished adding sections to the popup field. Click OK. Under Popup Sections. Click an intensity for the border from the Intensity list. follow these steps: 1. c. 5. click Finish. The Create Popup Form Section window opens. 7. This name will be the name of the form part in the EGL source code. which is displayed at the bottom of the New Popup Form Template window. 6. Click a highlight value from the Highlight radio buttons. In the New Popup Form Template window. In the Create Form Part Window. d. click Popup Form. On the form group in the editor. type a name for the form in the Enter part name field. Do not type a number greater than the number of remaining effective rows. The new popup form is created in the editor. 10. but popup forms are created with pre-made features like borders and sections. See“Creating a constant field” on page 502 and “Creating a variable field” on page 503. Open a form group in the Text Form editor. 12. You must add at least one section to the form. The Create Form Part window opens. a popup form is the same as an ordinary text form. a. Add fields to the form as appropriate. Repeat the following steps for each section that you want to add to the form. type the number of rows in the section. type a name for the section in the Section Name field. 4. 11. Fundamentally. Click OK. click the Add button. Click a color for the border from the Color list. 2. In the Number of rows field.“Creating a popup form” “Displaying a record in a text or print form” on page 507 Creating a popup form A popup form is a special kind of form that can be added to a form group. In the Create Popup Form Section window. These templates are listed in the Templates drawer of the Palette view. specify the characters to use for the form’s borders in the Vertical Character and Horizontal Character fields. Related concepts “Building EGL Text User Interface applications with the Text Form editor” on page 500 “Creating a form from a template” on page 505 The EGL Text Form editor uses templates to create commonly used types of forms and fields. Note: The total number of rows in the popup field’s sections cannot exceed the total number of rows in the popup field. e. 3. b. 8. Related tasks 506 EGL Programmer’s Guide . The New Popup Form Template window opens. click and drag a rectangle that indicates the size and shape of the popup form. Use the Up and Down buttons to set the order of the fields. When adding sections. On the Palette view. pay attention to the Remaining Effective Rows field and remember that dividers between the sections require an additional row for each new field. 9. To create a popup form in the EGL Text Form editor. these fields are populated with the size of the form you created in the editor. In the Menu Title field. Open a form group in the Text Form editor. but popup menus are created with pre-made features like a title. See “Creating a constant field” on page 502 and “Creating a variable field” on page 503. The Create Form Part window opens. Add fields to the new popup menu and edit the existing fields as appropriate. The New Popup Menu Template window opens.“Setting preferences for the Text Form editor” on page 510 “Creating a simple text or print form” on page 502 “Creating a constant field” on page 502 “Creating a variable field” on page 503 “Creating a popup menu” Creating a popup menu A popup menu is a special kind of form that can be added to a form group. specify the size of the popup menu in the Width and Height fields. follow these steps: 1. a popup menu is the same as an ordinary text form. and a specified number of menu options. The new popup menu is created in the editor. 9. These templates are listed in the Templates drawer of the Palette view. This name will be the name of the form part in the EGL source code. In the New Popup Menu Template. In the Number of Menu Options field. To create the form fields. which is found in the Templates drawer of the Palette view. 6. click Popup Menu. type a name for the form in the Enter part name field. Building EGL Text User Interface applications 507 . type any additional help text for the menu. 3. Fundamentally. help text. type the number of menu options that the popup menu will have. On the form group in the editor. click and drag a rectangle that indicates the size and shape of the popup menu. 10. 11. 8. creates a group of form fields that are equivalent to the fields in an EGL record part. In the Menu Help Text field. To create a popup menu in the EGL Text Form editor. 4. Click OK. Related concepts “Building EGL Text User Interface applications with the Text Form editor” on page 500 “Creating a form from a template” on page 505 The EGL Text Form editor uses templates to create commonly used types of forms and fields. follow these steps: 1. 2. By default. In the Create Form Part Window. 7. On the Palette view. Related tasks “Setting preferences for the Text Form editor” on page 510 “Creating “Creating “Creating “Creating a a a a simple text or print form” on page 502 constant field” on page 502 variable field” on page 503 popup form” on page 506 Displaying a record in a text or print form The Record template. Click Finish. Open a form group in the EGL Text Form editor. type the title of the menu. 5. select a type for the field. See “Creating a simple text or print form” on page 502. Within a form in the editor. h. g. If you want the field to be an input field. select the Create header row check box. 3. v To move fields up or down in the list. d. release the mouse. In the Edit Table Entry window. c. The Select a Record Part dialog opens. 12. In the EGL Record Placement. If necessary for the type you have selected. 9. enter the precision for the field in the Precision field.2. g. Create a form. d. In the Type list. Otherwise. 7. click Browse. The Edit Table Entry window opens. Click the Add button. click its name and then click Remove . v To edit a field. f. b. When the record is the correct size. Using one or more of the following methods. f. Otherwise. In the Edit Table Entry window. If necessary for the type you have selected. In the Type list. type a name for the field in the Field Name box. Click the field’s name. click the name of the record part that you want to use or type the name of a record part. 11. 508 EGL Programmer’s Guide . clear the check box. follow these steps: a. In the Select a Record Part dialog. Specify a width for the field in the Field Width field. Note: You can add a record only within an existing form. 10. select the Make this field an input field check box. The Edit Table Entry window opens. use the Up and Down buttons. type a name for the field in the Field Name box. specify the precision for the field in the Precision field. select the Make this field an input field check box. choose a vertical or horizontal orientation for the fields. A preview box next to the mouse cursor shows you the size of the record fields and their location relative to the field. If you want the group of fields to have a header row. Specify a width for the field in the Field Width field. clear the check box. 5. e. The Create a Record window is populated with a list of the fields in that record. select a type for the field. follow these steps: a. b. c. Click the Edit button. 4. If you want the field to be an input field. The EGL Record Placement window opens. Click OK. 8. e. In the Number of Rows field. On the Palette view. 6. click Record. Click OK. specify the number of rows you want the group of fields to have. click and hold the mouse to draw a rectangle that represents the size and location of the fields. v To add a field. Click OK. select and organize the record part fields that you want to display as fields in the form: v To remove a field. Using the Orientation radio buttons. Related concepts “Building EGL Text User Interface applications with the Text Form editor” on page 500 “Display options for the EGL Text Form editor” on page 510 Related tasks “Creating a simple text or print form” on page 502 Building EGL Text User Interface applications 509 . Click OK. create a new filter in the EGL Text Form editor. You can switch between active filters with the list next to the Filters button at the top of the editor. The New Filter dialog box opens. v Click the Select All button to show every form. edit. 2. you can manage your filters by using the following functions: v Select filters from the list. Select the forms to be displayed while the filter is active by doing one or more of the following steps: v Clear the check boxes next to the forms that you want hidden by the filter.13. v Select which forms are displayed when the filter is active. or delete filters. 6. Filters affect only the presentation of the form group at design time. In the New Filter dialog box. You can define any number of filters. type a name for the filter and click OK. From the Filters window. The Filters window opens. You can switch filters by using the list next to the Filters button. To create. v Add a new filter by clicking New. To 1. click the Filters button. 3. v Delete a filter by selecting it from the list and clicking Remove. click the Filters button. Related tasks “Creating a simple text or print form” on page 502 “Creating a constant field” on page 502 “Creating a variable field” on page 503 Filtering the editor Filters limit which forms are shown in the EGL Text Form editor. click the New button. v Click the Deselect All button to hide every form. but only one filter can be active at a time. These templates are listed in the Templates drawer of the Palette view. follow these steps: Open a form group in the Text Form editor. 5. In the Filters view. Related concepts “Building EGL Text User Interface applications with the Text Form editor” on page 500 “Creating a form from a template” on page 505 The EGL Text Form editor uses templates to create commonly used types of forms and fields. In the Text Form editor. Click Finish. 4. they do not affect the EGL code in any way. v Select the check boxes next to the forms that you want shown by the filter. The new filter is active. select a grid color for the Text Form editor. Toggle 4 color mode Allows you to switch between monochromatic and 4-color modes. follow these steps: 1. Zoom Level Sets the magnification level of the editor. select the preferences for the Text Form editor: v In the Background Color field. which are otherwise invisible. select the Highlight fields check box and select a color. To change the preferences for the Text Form editor. The Preferences window opens. click a font for the fields and click a size from the adjacent list. These options do not change the appearance of the form group at run time. 510 EGL Programmer’s Guide . Toggle Gridlines This option displays a grid over the form group to help in sizing and arranging forms. In the right pane of the Preferences window.” Toggle Sample Values This option inserts sample values into variable fields. To change the color of the grid. v In the Grid Color field. Filters Sets the active filters.Display options for the EGL Text Form editor The EGL Text Form editor has display options that enable you to control how form groups are displayed in the editor at design time. select the Show rulers check box. v If you want to show a border around fields. select a background color for the Text Form editor. From the menu bar. Toggle Black and White Mode This option switches the background of the editor from black to white. From left to right at the top of the editor. such as the background color and grid color. click Window → Preferences. See “Filtering the editor” on page 509. Related concepts “Building EGL Text User Interface applications with the Text Form editor” on page 500 Related tasks “Filtering the editor” on page 509 “Setting preferences for the Text Form editor” Setting preferences for the Text Form editor The preferences for the EGL Text Form editor can change the appearance of the Text Form editor. In the left pane of the Preferences window. 2. v If you want to show rulers at the top and left side of the Text Form editor. expand EGL and click Text Form editor. v In the Font list. these are the buttons that control the display options: Size This drop-down list allows you to select a new size for the form. see “Setting preferences for the Text Form editor. Toggle rulers Shows or hides rulers at the top and left side of the editor. 3. select the Visually demonstrate blinking fields check box. v To display and edit the bidirectional text fields in visual mode (the way they will be displayed). click Window → Preferences. 4. it only changes their appearance at design time. v For languages that read from right to left. Note: You can restore the EGL Text Form editor preferences window to its default settings by clicking Restore Defaults. Building EGL Text User Interface applications 511 . To change the preferences for the Text Form editor’s support of bidirectional languages. In the right pane of the Preferences window. the top right corner is defined as the location (1. select the preferences for the Text Form editor’s support of bidirectional languages: v To enable the use of bidirectional language options in the Text Form editor. follow these steps: 1. This option does not change the appearance of the fields at run time. select Enable right-to-left orientation. v To default to visual display ordering in the Text Form editor (instead of logical ordering). A monospace font is a font whose characters all have the same width.1) is the top left corner.Note: Choose a monospace font to ensure that your fields display at the correct size in the Text Form editor. all of the other options are available. click OK. see “Working with bidirectional data” on page 245. For more information. select Enable visual data ordering by default. With a left-to-right orientation. you can change the bidirectional settings for an individual formGroup to be different from the settings in the Preferences window. select Endable right-to-left orientation by default. With this button. the location (1. From the menu bar. v If you want blinking fields to be displayed in italic type in the editor. 3. Related concepts “Building EGL Text User Interface applications with the Text Form editor” on page 500 “Filtering the editor” on page 509 Related tasks “Setting preferences for the Text Form editor palette entries” on page 512 “Setting bidirectional text preferences for the Text Form editor” Setting bidirectional text preferences for the Text Form editor The EGL Text Form editor supports languages such as Arabic and Hebrew in which the text is written right to left but numbers and Latin alphabetic strings within the text are presented left to right. select Enable bidirectional settings button. In the left pane of the Preferences window. The Preferences window opens. After this check box is selected.1). expand EGL and click EGL bidi preferences. 2. When you are finished setting the preferences for the EGL Text Form editor. select Enable visual data ordering. v To use right-to-left map coordinates for the Text Form editor. When a form group is set to use right-to-left map coordinates. select the Bi-directional options enabled check box. such as Courier New. v To place a button on the Text Form editor that enables you to change the bidirectional settings for a formGroup. 3. 2. BIDI support is available in all COBOL environments. select the following options: v From the Color list. choose whether the field is protected from user update by default. and is not available on Linux. v From the Protect radio buttons. From the menu bar. select Enable numeric swapping by default. 4. v To reverse directional punctuation characters like < and (.The only reason to use right-to-left orientation in the form editor is to make the design of a right-to-left form easier. click a default color for that type of field. In the left pane of the Preferences window. for each type of constant and variable field in the Palette Entries list. When you are finished setting the preferences for the palette entries. intensity. click a default highlighting style for that type of field. v From the Intensity list. select Enable symmetric swapping by default. click Window → Preferences. BIDI support for Text UI and the Text UI Debugger in Java environments is available on Windows-based systems only. expand EGL → EGL Text Form editor and click EGL Palette Entries. The Preferences window opens. or Arabic to Hindi. v To switch numerals from Hindi to Arabic. click a default intensity for that type of field. In the right pane of the Preferences window. and highlighting for the types of constant and variable fields in the palette. Note: You can restore all of the palette entries to their default settings by clicking Restore Defaults. To change these preferences. click OK Related concepts “Building EGL Text User Interface applications with the Text Form editor” on page 500 Related tasks “Setting preferences for the Text Form editor” on page 510 “Creating a constant field” on page 502 “Creating a variable field” on page 503 Related reference Form field properties 512 EGL Programmer’s Guide . v From the Highlight radio buttons. follow these steps: 1. You can restore the EGL Text Form editor preferences window to its default settings by clicking Restore Defaults. Related concepts “Building EGL Text User Interface applications with the Text Form editor” on page 500 “Filtering the editor” on page 509 “Working with bidirectional data” on page 245 Related tasks “Setting preferences for the Text Form editor palette entries” Setting preferences for the Text Form editor palette entries The preferences for the EGL Text Form editor palette control the default color. while several different types of parts can represent the interface itself. However. Instead. a console user interface shows only text on the screen. The three modes have different abilities. and which actions happen when the user performs tasks in the interface. EGL Console UI applications separate the interface from the logic used to create that interface. 2008 513 . but in general a Console UI application behaves the same way in each mode. the fields in a ConsoleForm define the © Copyright IBM Corp. Curses. or Console UI. Related reference Console UI parts openUI Elements of a Console UI application A Console UI application can use several different types of EGL parts to supply data and several different types of EGL variables to create the interface. Console UI forms and fields A ConsoleForm part is a record of fields to be shown on the user interface. you can use additional Console UI components called widgets to add additional functionality. and it responds only to the keyboard. 1996. See “Console UI modes” on page 529. 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. 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. no graphics or buttons. “Adding rich client widgets to a Console UI program” on page 519 When running in rich client platform (RCP) mode. An ordinary EGL program provides the logic for the application. is a style of user interface similar to that used on a UNIX-based program that interacts with a character-based terminal. Related tasks “Creating a Console User Interface” on page 516 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 rich client platform (RCP).Building EGL Console User Interface applications Console 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. not the mouse. Like many types of applications with user interfaces. “Console UI modes” on page 529 EGL supports three modes in which you can run Console UI applications: Swing. As the term character-based suggests. “Running Console UI applications” on page 528 The process for running a Console UI application differs slightly depending on the mode you are running in. When showing a menu on the interface. here is a simple Console UI record that defines a form: Record CustomerConsoleRecord type consoleForm {formSize = [10. ArrayDictionary part An ArrayDictionary is a type of EGL part that is often used to represent data in Console UI. you define arrays of consoleFields that represent the columns. PhoneNum consoleField {fieldLen = 20."}. a length in characters. a Console UI program can use them to display data or accept input. A field in a console UI record can be as simple as a name. in this case ″Welcome to my console.4]. name="customer_id"}. = "Three". a menu is a set of options from which the user is expected to choose one. end Of the five fields in this form. these fields are sometimes referred to as a form. it cannot change at run time. = "One". position = [5. Menu and MenuItem parts In Console UI. Lname consoleField {fieldLen = 20. Unlike an array of records. This field is named with an asterisk (*) and serves as header or explanatory text.name = "Customer Record"} * consoleField {position = [1. one is a constant string of text. ID consoleField {fieldLen = 5.4]. As a group. labelText = "Option One"}. A detailed example of an ArrayDictionary in Console UI is available at Using an array dictionary in Console UI. in an ArrayDictionary. you define a menu part and then define the options as an array of menuItem parts in the menuItems menu property. labelText = "Option Three"} See “Creating a Console User Interface” on page 516 for an example of how to respond when the user selects one of the options. = "Two". name="last_name"}. The Console UI program links the fields on the screen with other EGL variables. 514 EGL Programmer’s Guide . position = [3. in which you define one record part that represents a row and then create an array of those rows. position = [6. name="phone"}.location and label of the fields that are shown on the screen. A detailed example of an ArrayDictionary in Console UI is available at ″Using an array dictionary in Console UI″ in the EGL Language Reference.40]. labelText = "Option Two"}. the following menu defines three options from which the user can choose: new Menu {labelText = menuItems = [ new MenuItem{name new MenuItem{name new MenuItem{name ]} "Choose an option: ". Defining data by the columns can be useful in Console UI because ArrayDictionaries scroll automatically in the limited space on a Console UI window. Fname consoleField {fieldLen = 20.4]. For example. position = [4.4]. For example. value = "Welcome to my console.″ The other fields are variable.4]. name="first_name"}. and a position on the screen. you need to convert your project to an EGL plug-in project. // Step 3: Create variables for the form fields. Related tasks “Creating a Console User Interface” on page 516 Console UI relies on the openUI statement to define which forms and fields are shown on the interface. uses functions in the EGL library ConsoleLib to display that window.openWindowWithForm(myWindow. myConsoleUIRecord CustomerConsoleRecord.myConsoleUIRecord).Console UI program The Console UI program is an ordinary EGL program that creates and controls the interface. last_name. first_name. myWindow window {name="My Window". “Adding rich client widgets to a Console UI program” on page 519 When running in rich client platform (RCP) mode. consoleLib. and which actions happen when the user performs tasks in the interface. such as ConsoleForm parts. phone end end end For more information on using Console UI programs. // Step 4: Open the window and open the form inside the window.1]}. see “Creating an EGL plug-in project” on page 74. In general. see “Console UI modes” on page 529. For more information about the modes you can run your Console UI application in. and then populates that window with parts that represent the interface. customer_id int. last_name. For more information on EGL plug-in projects. openUI myConsoleUIRecord bind customer_id. first_name. “Running Console UI applications” on page 528 The process for running a Console UI application differs slightly depending on the mode you are running in. which variables those forms and fields are bound to. 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. see “Creating a Console User Interface” on page 516. phone char(30). The EGL Plug-in project With EGL. you can use additional Console UI components called widgets to add additional functionality. // Step 2: Create a window. it creates a Window variable. position=[1. Related reference Menu Using an array dictionary in Console UI Building EGL Console User Interface applications 515 . 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. // Step 5: Link the variables to the fields in the form. but don't open it yet. Console UI applications separate the interface from the data being managed by the interface. 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.40]. or bind.name = "Customer Record"} * consoleField {position = [1. Fname consoleField {fieldLen = 20. 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. position = [3. myConsoleRec CustomerConsoleRecord{name = "myForm"}.4]. ConsoleLib. position = [4.4].displayForm(myConsoleRec). Binding data to the fields in the window Like many other types of applications with user interfaces. when the person using the interface changes a value in the consoleForm. ID consoleField {fieldLen = 5. name="customer_id"}. end end Record CustomerConsoleRecord type consoleForm {formSize = [10. position = [5.1]}.openWindow(myWindow). program basicConsole type BasicProgram function main() myWindow Window {name = "My Window". which variables those forms and fields are bound to. name="last_name"}. the value of the variable changes to match. name="phone"}.displayForm() to open the form in the window. When you create a Console UI in EGL. ConsoleLib. value = "Welcome to my console. the value in the form changes to match. 516 EGL Programmer’s Guide . you create the interface with parts like consoleForms and then use the openUI statement to connect. those parts to variables in your program. Then. when your code changes the value of the variable. Conversely. name="first_name"}. position = [6. Because this form does not enable any interaction. the window closes as soon as it opens. and which actions happen when the user performs tasks in the interface. PhoneNum consoleField {fieldLen = 20. this interface is not very useful because it does not enable the user to interact with the form or window at all.4]. position = [1. Lname consoleField {fieldLen = 20.4]."}. end However.4].ConsoleForm Console UI parts openUI Creating a Console User Interface Console UI relies on the openUI statement to define which forms and fields are shown on the interface. displayForm(myConsoleRec). but it begins with a description of an event. position = [6.openWindow(myWindow). ConsoleLib. PhoneNum consoleField {fieldLen = 20. Fname consoleField {fieldLen = 20. myConsoleRec CustomerConsoleRecord{name = "myForm"}. name="customer_id"}.4]. phone char(30). the window stays open so the user can tab through the fields and type values. name="phone"}. The line of code that begins openUI myConsoleRec bind customer_id. This event handler is called when the user types a value in the customer_id field and moves the cursor out of the field: program basicConsole type BasicProgram function main() myWindow Window {name = "My Window". openUI myConsoleRec bind customer_id. ID consoleField {fieldLen = 5.. first_name.openWindow(myWindow).. ConsoleLib. value = "Welcome to my console. name="first_name"}.1]}. position = [5. last_name. position = [1.4].4]. the event handler that is associated with that action is called. position = [3. myConsoleRec CustomerConsoleRecord{name = "myForm"}. end Now when you run this program. ConsoleLib. first_name. An event handler contains EGL statements like a function. such as a key being pressed or a value being typed in a field. position = [1."}. The following example adds an event handler to the previous example. phone end end end Record CustomerConsoleRecord type consoleForm {formSize = [10. position = [4. Lname consoleField {fieldLen = 20.1]}. name="last_name"}.name = "Customer Record"} * consoleField {position = [1. When the user presses a key or types a value in a field. customer_id int. Building EGL Console User Interface applications 517 .4].4]. ConsoleLib.40]. last_name.The following example expands on the previous example to bind four variables to the four editable fields in the consoleForm: program basicConsole type BasicProgram function main() myWindow Window {name = "My Window". 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.displayForm(myConsoleRec). you must define event handlers that tell EGL what to do in response to the action. labelText = "Option Two"}. position = [6. last_name. 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. last_name. Related tasks 518 EGL Programmer’s Guide .4]. openUI myConsoleRec bind customer_id.name = "Customer Record"} * consoleField {position = [1.displayAtLine("You chose option One". name="first_name"}. = "Two".labelText = "Exit"} onEvent(MENU_ACTION:("Exit")) exit openUI. 5). position = [4. onEvent(MENU_ACTION:("One")) consolelib.displayAtLine("You chose option Two".4]. position = [5.customer_id int. name="phone"}. end To respond when a user chooses an option in a menu. first_name. see openUI. Lname consoleField {fieldLen = 20. name="customer_id"}. onEvent(MENU_ACTION:("Two")) consolelib.4]. name="last_name"}. = "Exit". PhoneNum consoleField {fieldLen = 20. 5).40]. use the MENU_ACTION event handler: program menuTest type BasicProgram function main() openUI new Menu {labelText = menuItems = [ new MenuItem{name new MenuItem{name new MenuItem{name ]} "Choose an option". phone onEvent(AFTER_FIELD:"customer_id") if (customer_id == 3) first_name = "John". Fname consoleField {fieldLen = 20.labelText = "Option One"}."}. position = [3. phone char(30). value = "Welcome to my console. ID consoleField {fieldLen = 5.4].4]. end end end end Record CustomerConsoleRecord type consoleForm {formSize = [10. = "One". end end end In this example. first_name. For other kinds of event handlers. With the bind clause of the openUI statement. This step is not required for button widgets because the button widgets do not need a variable. or combo boxes (also called drop-down boxes) In general. bind the variable to the widget. 3. using a rich client widget in your Console UI program involves these steps: 1.SELECTION_CHANGED event. Related reference openUI Console UI parts Adding rich client widgets to a Console UI program When running in rich client platform (RCP) mode. v For single-selection widgets. use the ConsoleList. See the following topics: v “Adding a button widget” on page 520 v “Adding a check box widget” on page 522 v “Adding a single-selection widget” on page 524 These widgets are supported only when running in RCP mode. In the Console UI program.SELECTION_CHANGED event.PUSHED event. See “Console UI modes” on page 529. no variable is needed. “Running Console UI applications” on page 528 The process for running a Console UI application differs slightly depending on the mode you are running in. Create the widget as a field in a console form and specify the properties for the field. 4. list boxes. use the ConsoleRadiogroup.“Adding rich client widgets to a Console UI program” When running in rich client platform (RCP) mode. v For list boxes. 2. v For radio button groups.STATE_CHANGED event. create a variable to represent the state of the widget: v For check boxes. Building EGL Console User Interface applications 519 . use the ConsoleCombo. you can use additional Console UI components called widgets to add additional functionality. you can use additional Console UI components called widgets to add additional functionality. create an INT variable. use the ConsoleButton. such as radio button groups. v For buttons. EGL supports the following rich client widgets: v buttons v check boxes v single-selection widgets. v For combo boxes. Create an event handler for the widget: v For check boxes. v For buttons.SELECTION_CHANGED event. create a BOOLEAN variable. Rich client widgets enable a Console UI interface to behave less like a character-based interface and more like a graphical user interface. use the ConsoleCheckbox. Related concepts “Elements of a Console UI application” on page 513 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. and when the user clears the check box. height. Therefore. Record buttonForm type ConsoleForm {formSize=[12. specify the following properties for the button: name text bounds An array of four integers that represent the row. 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. which variables those forms and fields are bound to.4. you must bind a boolean variable to the check box. “Running Console UI applications” on page 528 The process for running a Console UI application differs slightly depending on the mode you are running in. You only need to create the button and specify an event handler to run when the button is clicked. and list box are similar because they both require the user to select a single option from a group of options. the check box widget has a state. respectively 3. and width of the button.40]} myButton consoleButton {name = "simpleButton". just like you would bind a text variable to a text field in a console form. create the button by using the consoleButton predefined part. “Adding a single-selection widget” on page 524 The combo box. In a console form. “Adding a check box widget” on page 522 Unlike the button widget. The three modes have different abilities. text = "Click here". the variable is set to TRUE. “Console UI modes” on page 529 EGL supports three modes in which you can run Console UI applications: Swing.1. it is either checked or not checked. column. specify an event handler for the button’s PUSHED event: A mnemonic that you will use later to link the button to an event handler The label for the button 520 EGL Programmer’s Guide . end 2. Curses. “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. but in general a Console UI application behaves the same way in each mode. 1. bounds=[4. Related tasks “Creating a Console User Interface” on page 516 Console UI relies on the openUI statement to define which forms and fields are shown on the interface. radio button group. At minimum. You only need to create the button and specify an event handler to run when the button is clicked.15]}. the variable is set to FALSE. Within an openUI statement. This part represents the button widget. and rich client platform (RCP). and which actions happen when the user performs tasks in the interface. When the user selects the check box. SysLib.4.1]}. openWindow(myWindow).PUSHED : "simpleButton") SysLib. In the file programs/simpleButton. counter int=0. end Related concepts “Elements of a Console UI application” on page 513 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. position = [1. record buttonForm type ConsoleForm { formsize=[12.4.onEvent(ConsoleButton. Building EGL Console User Interface applications 521 .". keepGoing boolean = true.1.PUSHED : "exitButton") keepGoing = false.1]. onEvent(ConsoleButton.egl: package forms.PUSHED : "simpleButton") counter+=1.15]}. text = "Click here". A complete example of a Console UI program that uses a button in this way follows.writeStderr("You pushed the button."). bounds=[6. fieldLen = 20}. end end end end In the file forms/buttonForm.writeStderr(textValue). while (keepGoing == true) openUI { bindingByName=no } myForm bind textValue OnEvent(ConsoleButton.15]}. myButton consoleButton {name = "simpleButton".40] } introText consoleField {name="introText". text = "Click to exit". textValue = "You have clicked the button " +counter+" times.1. function main() myWindow WINDOW {name="myWindow".egl: package programs. myForm buttonForm {}. bounds=[4. position = [1.buttonForm program simpleButton type BasicProgram textValue string. import forms. displayForm(myForm). exitButton consoleButton {name = "exitButton". you must bind a boolean variable to the check box. Therefore.“Console UI modes” on page 529 EGL supports three modes in which you can run Console UI applications: Swing. “Adding a check box widget” Unlike the button widget. text = "Click here". the variable is set to FALSE. the variable is set to FALSE. just like you would bind a text variable to a text field in a console form. When the user selects the check box. and rich client platform (RCP). At minimum. Therefore. it is either checked or not checked. “Adding a single-selection widget” on page 524 The combo box. “Adding rich client widgets to a Console UI program” on page 519 When running in rich client platform (RCP) mode. you must bind a boolean variable to the check box. and when the user clears the check box. In a console form.40]} myCheck consoleCheckbox {name = "simpleCheck". and width of the check box. column. Related tasks “Creating a Console User Interface” on page 516 Console UI relies on the openUI statement to define which forms and fields are shown on the interface. the check box widget has a state. Record checkForm type ConsoleForm {formSize=[12.4. Curses. and list box are similar because they both require the user to select a single option from a group of options. and when the user clears the check box. When the user selects the check box.1. the variable is set to TRUE. Related reference Console UI parts openUI Adding a check box widget Unlike the button widget. The three modes have different abilities. the variable is set to TRUE. but in general a Console UI application behaves the same way in each mode. you can use additional Console UI components called widgets to add additional functionality. bounds=[4. height. radio button group. specify the following properties for the check box: name text bounds An array of four integers that represent the row. end 2. it is either checked or not checked.15]}. 1. and which actions happen when the user performs tasks in the interface. “Running Console UI applications” on page 528 The process for running a Console UI application differs slightly depending on the mode you are running in. respectively 3. create the check box by using the consoleCheckbox predefined part. the check box widget has a state. which variables those forms and fields are bound to. just like you would bind a text variable to a text field in a console form. Create a boolean variable to represent the state of the check box: A mnemonic that you will use later to link the check box to an event handler The label for the check box 522 EGL Programmer’s Guide . 1]}. else textValue = "Cleared". With an openUI statement. fieldLen = 20}. while (keepGoing == true) openUI myForm bind textValue.STATE_CHANGED : "simpleCheck") if (myCheckVar == true) textValue = "Checked". else SysLib. specify an event handler for the check box’s STATE_CHANGED event: onEvent(ConsoleCheckbox.writeStderr("Checked"). onEvent(ConsoleCheckbox.checkState boolean = false. program simpleCheckbox type BasicProgram function main() myWindow WINDOW {name="myWindow".egl: package programs. open the form and bind the variable to the check box: myForm checkForm {}. 4. myCheck consoleCheckbox Building EGL Console User Interface applications 523 . keepGoing boolean = true. position = [1. openWindow(myWindow).checkForm. import forms. textValue string = "Text.PUSHED : "exitButton") keepGoing = false. end A complete example of a Console UI program that uses a check box in this way follows: In the file programs/simpleCheckbox.1].40] } introText consoleField {name="introText". end end end end end In the file forms/checkForm. myForm checkForm {}. myCheckVar onEvent(ConsoleButton. position = [1. Within the openUI statement. openUI myForm bind checkState //event handlers go here end 5.writeStderr("Cleared").STATE_CHANGED : "simpleCheck") if (checkState == true) SysLib.egl: package forms. displayForm(myForm). record checkForm type ConsoleForm { formsize=[12. myCheckVar boolean = false.". 17]}. radio button group. exitButton consoleButton {name = "exitButton". In a console form. Like the check box widget. “Adding a button widget” on page 520 The button widget is the simplest rich client widget because it does not need to maintain a state like the others. the single-selection widgets must be bound to an INT variable to represent the index of the currently selected option.1. bounds=[6.2. “Running Console UI applications” on page 528 The process for running a Console UI application differs slightly depending on the mode you are running in. and list box are similar because they both require the user to select a single option from a group of options.15]}. “Adding rich client widgets to a Console UI program” on page 519 When running in rich client platform (RCP) mode. 1. which variables those forms and fields are bound to. bounds=[3. text="Checkbox".1. radio button group. and list box are similar because they both require the user to select a single option from a group of options. Related reference Console UI parts openUI Adding a single-selection widget The combo box.5. and rich client platform (RCP). instead of a boolean variable.{name="simpleCheck".4. and which actions happen when the user performs tasks in the interface.40] } myRadio consoleRadioGroup {name = "radio".4. The three modes have different abilities. “Adding a single-selection widget” The combo box.15]}. end Related concepts “Elements of a Console UI application” on page 513 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. myCombo consoleCombo 524 EGL Programmer’s Guide . bounds = [1. You only need to create the button and specify an event handler to run when the button is clicked. you can use additional Console UI components called widgets to add additional functionality. but in general a Console UI application behaves the same way in each mode. create the widget using the predefined parts: record singleSelectForm type ConsoleForm { formsize=[12. the single-selection widgets must be bound to a variable that represents their states. text = "Click to exit". Curses. “Console UI modes” on page 529 EGL supports three modes in which you can run Console UI applications: Swing. Related tasks “Creating a Console User Interface” on page 516 Console UI relies on the openUI statement to define which forms and fields are shown on the interface. However. import forms. comboValue.SELECTION_CHANGED : "list") SysLib."four". function main() myWindow WINDOW {name="myWindow". 5. Between creating the form variable and displaying the form in a window. position=[1. myForm.SELECTION_CHANGED : "combo") SysLib.myList. Within the openUI statement.15]}. displayForm(myForm). open the form and bind the variables to the widgets: openUI myForm bind radioValue.myRadio.writeStdout("Combo selected: "::comboValue).2. onEvent(ConsoleList. specify an event handler for the widget’s SELECTION_CHANGED event: onEvent (ConsoleRadioGroup.myCombo. program singleSelectTest type BasicProgram {} radioValue.myCombo. myForm singleSelectForm{}.2. listValue int = 2. myForm. bounds = [7.writeStdout("List selected: "::listValue). respectively 3. comboValue.items = ["one".{name = "combo"."two". At minimum."three".2."five". specify the following fields for each widget: name bounds An array of four integers that represent the row. myForm singleSelectForm{}. position=[1. "Option Three"]. "Option Two". comboValue.singleSelectForm. myForm.1]}. "Option Three"].18]}. openWindow(myWindow).1. 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/singleSelectTest.SELECTION_CHANGED : "radio") SysLib.egl: package programs. height. "Option Two"."six"]. create an integer variable to represent the state of the widget: radioValue. With an openUI statement. end 2. and width of the widget.items = ["Option One".items = Building EGL Console User Interface applications 525 . openWindow(myWindow). In a program. column. A mnemonic that you will use later to link the widget to an event handler 4.1]}. define the options in the widget with an array of variables or literals: myWindow WINDOW {name="myWindow". myForm. listValue int = 2. listValue //event handlers go here end 6. myList ConsoleList {name ="list". bounds = [9.items = ["Option One". onEvent (ConsoleCombo.writeStdout("Radio selected: "::radioValue). end end end In the file forms/singleSelectForm.15]}. "Option Two".writeStdout("List selected: "::listValue)."five"."six"]. the appropriate event handler runs and.writeStdout("Radio selected: "::radioValue)."four"."three"."two".40] } myRadio consoleRadioGroup {name = "radio". myForm.egl: package forms.18]}.SELECTION_CHANGED : "list") SysLib. openUI myForm bind radioValue.17]}. myList ConsoleList {name ="list". prints a message to the Console view: 526 EGL Programmer’s Guide . onEvent (ConsoleCombo. "Option Three"]. bounds = [1.["Option One". "Option Three"].2.writeStdout("Combo selected: "::comboValue).4. myForm.2. onEvent(ConsoleList.items = ["Option One". bounds = [7. comboValue.items = ["one".SELECTION_CHANGED : "radio") SysLib.2.myRadio.SELECTION_CHANGED : "combo") SysLib. end When you run the EGL program in RCP mode. "Option Two". the user interface looks like this: Each time you change the selection in one of the widgets. record singleSelectForm type ConsoleForm { formsize=[12. myCombo consoleCombo {name = "combo".2. displayForm(myForm). listValue onEvent (ConsoleRadioGroup. in this case.myList.1. bounds = [9. the variable contains the number 5. If the first item is selected. the variable is set to TRUE.list1. “Adding rich client widgets to a Console UI program” on page 519 When running in rich client platform (RCP) mode. The three modes have different abilities. the variable contains 50. Building EGL Console User Interface applications 527 . and when the user clears the check box. or 2+16+32. Each item in the list is assigned a multiple of two according to its position: the first item is 1. but in general a Console UI application behaves the same way in each mode.multipleSelect = TRUE. you must bind a boolean variable to the check box. the fourth is 8. allowing the user to select more than one item from the list. the sixth is 32. the check box widget has a state. which is the sum of the values for the two selected items. When multipleSelect is set to false (as is the default) the value of the variable bound to the widget contains the index of the selected item. Curses. it is either checked or not checked. the variable contains 3. Related concepts “Elements of a Console UI application” on page 513 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. and which actions happen when the user performs tasks in the interface. the variable is set to FALSE. “Console UI modes” on page 529 EGL supports three modes in which you can run Console UI applications: Swing. “Running Console UI applications” on page 528 The process for running a Console UI application differs slightly depending on the mode you are running in. if the fifth item is selected. just like you would bind a text variable to a text field in a console form. If the second. which variables those forms and fields are bound to. the fifth is 16. Therefore. When the user selects the check box. and so on. the variable contains the number 1. If the first and second items are selected. “Adding a check box widget” on page 522 Unlike the button widget. if only the first item is selected. For example. you can use additional Console UI components called widgets to add additional functionality. the second is 2. Related tasks “Creating a Console User Interface” on page 516 Console UI relies on the openUI statement to define which forms and fields are shown on the interface.The list box can also behave as a multiple-selection widget. The value of the variable is the sum of the values of all the selected items. fifth. and sixth items are selected. the variable contains a binary representation of the selected items. and rich client platform (RCP). set the widget’s multipleSelect property to true: myForm. When multipleSelect is set to true. To allow users to select more than one item from the list. the third is 4. the variable contains 1. For information on the different modes available for Console UI applications. see “Console UI modes” on page 529. Related reference Console UI parts openUI Running Console UI applications The process for running a Console UI application differs slightly depending on the mode you are running in. 2. Curses. Save all changed files and generate the project. The Java file has the same name as your program part. expand the Java Resources folder and find the Java program to which your program part was generated. but with a . You only need to create the button and specify an event handler to run when the button is clicked. In your EGL project. Save all changed files and generate the project. Running in Swing or Curses mode Running in Swing or Curses mode is no different from running any EGL application generated to Java: 1. you can use the enhanced GUI features of the workbench. the Console UI program must be in an EGL plug-in project. 3. 528 EGL Programmer’s Guide . is a style of user interface similar to that used on a UNIX-based program that interacts with a character-based terminal. and copying and pasting text between fields. 2. including using the mouse to select fields. Right-click the program file and then click Run As → Java Application. See “Creating an EGL plug-in project” on page 74. The program opens in a new window. Running in RCP mode To run a Console UI program in rich client platform (RCP) mode. or Console UI. and rich client platform (RCP). 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. but in general a Console UI application behaves the same way in each mode. “Console UI modes” on page 529 EGL supports three modes in which you can run Console UI applications: Swing. The three modes have different abilities. right-click the file that contains the Console UI program part and then click Run As RCP.“Adding a button widget” on page 520 The button widget is the simplest rich client widget because it does not need to maintain a state like the others. In your EGL project. not the Java file: 1. In this window.java extension. Related concepts “Building EGL Console User Interface applications” on page 513 Console User Interface. Swing mode Swing mode is the default mode for Console UI applications. However. Curses mode Curses mode is similar to Swing mode. Also.Console UI modes EGL supports three modes in which you can run Console UI applications: Swing. such as drop-down boxes. because these features are now enabled. After you have added the EGL Curses library to your project. If you run the generated Java output from a Console UI program. enabling you to copy and paste text between fields. or widgets. RCP mode Rich client platform (RCP) mode is similar to Swing mode. EGL applications use SWT libraries instead of Swing libraries. but Curses mode is intended for users who use telnet to access a UNIX system or who use a terminal device. but you can generally not run an application designed for RCP mode in another mode. keyboard combinations like Ctrl+X might behave differently in RCP mode. Building EGL Console User Interface applications 529 . Finally. which means that you can run an application designed for another mode in RCP mode. 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. that the other modes do not. Formatting masks are not supported in RCP mode. A Console UI program behaves similarly in RCP mode as in Swing or Curses mode. the user can skip between fields in any order. v Because copying and pasting text is enabled in RCP mode. generate it. The other modes do not support these widgets. The main difference is that you can use the mouse and enhanced keyboard features of the workbench in a RCP program. except that in RCP mode. but in general a Console UI application behaves the same way in each mode. If you write a Console UI program. The three modes have different abilities. that program runs in Curses mode. and rich client platform (RCP). For information on how to install the EGL Curses library. the resulting program runs in Swing mode. see Installing the EGL runtime code for Java. Curses mode becomes the default mode for running Console UI applications. RCP mode supports enhanced UI components. the user might be able to make the program behave differently in RCP mode: v Because the mouse is enabled in RCP mode. RCP applications have mouse functionality and enhanced keyboard functionality. Curses. and clickable buttons. and run the generated Java source without making any other changes. check boxes. A Console UI application running in Swing mode uses Java Swing libraries to simulate a UNIX interface like that of Curses mode. where in the other modes the user must move between fields in a specific order. 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. Related concepts “Building EGL Console User Interface applications” on page 513 Console User Interface. Related tasks “Running Console UI applications” on page 528 The process for running a Console UI application differs slightly depending on the mode you are running in. 530 EGL Programmer’s Guide . is a style of user interface similar to that used on a UNIX-based program that interacts with a character-based terminal. or Console UI. 1996. not affiliated with IBM. including JasperReports. You can use the Handler part to respond to a limited list of specific events during the output of report data. The addition of an EGL JasperReports handler means you can create dynamic reports that respond to events that occur as the report is generated. JasperReports engine The JasperReport engine allows the greatest complexity. If all you need is a simple text report.Creating reports with EGL EGL offers different ways to create reports. which can be quite complex. You must create custom report programs for COBOL. 2008 531 . and comma separated values (CSV) for use with Excel. You can design a report in the Report Design perspective of your Workbench and then write EGL code that drives report creation. using external engines to generate the report contents. v The Business Intelligence and Reporting Tools (BIRT) engine creates reports in HTML or PDF format. XML. Each engine has its particular advantages and drawbacks. and ExternalType. EGL support is available in JSF handlers and in programs generated for Java. including graphics. HTML. v The EGL text report engine creates plain text reports. EGL text report engine The EGL text report engine draws on EGL parts such as the generic Handler. such as reaching maximum values on subtotals. comma-separated. With greater flexibility comes increased effort required in using the product. HTML. are third-party products. JasperReports may be a more powerful tool than you need. It is particularly useful for the migration of reports from I4GL. You use a design file to dictate the layout. You can create a report by using the following capabilities: v The JasperReports engine creates reports in formats including PDF. Mastering the design file is difficult enough that third-party applications are available to help you. BIRT engine BIRT is an Eclipse-based reporting system that allows for sophisticated output in PDF or HTML format. graphs. One common drawback is that these reports run on Java only. Output options include PDF. passing information to the subreport from the report or subreport that calls it. and charts. These applications. tables. like using a jet plane for a short trip down the street. as detailed in the following sections. Your data source can be anything you can read from in EGL. © Copyright IBM Corp. plain text. You can nest as many subreports as you want to any depth. It should take far less time to create a simple report design with this engine than with JasperReports or BIRT. and plain text. or changing between various commission structures. Delegate. Generate the project and run the report driver program. See “Running a report of type JasperReport” on page 545 EGL does not require that you perform these tasks in a particular order. including graphics. the only available output format for the EGL text report engine is a plain text file (though you may also direct output to stdout). create a report handler with additional functions that are called by the report design file. HTML. you must write and generate the report handler first and then compile the report design file. you must run the report driver program again. follow these general steps: 1. and charts. including PDF. HTML.As the name implies. EGL compiles the report design file each time you save a change to the report design file. Create and compile a JasperReports report design file. Creating reports with JasperReports EGL uses the JasperReports framework to create reports in several formats. if your report design file calls functions in the report handler. a report handler can give you greater control over the data put into the report. Write a report driver program. 4. tables. and plain text. EGL support for BIRT is available when you code either JSF handlers or programs generated for Java. comma-separated values. 2. EGL does not automatically refresh exported reports. Related concepts “Creating reports with JasperReports” EGL uses the JasperReports framework to create reports in several formats. and plain text. See “Creating an EGL JasperReport handler” on page 541. “Creating reports with BIRT” on page 551 Business Intelligence and Reporting Tools (BIRT) is an Eclipse-based reporting system that allows for sophisticated output in PDF or HTML format. This engine is particularly useful for migrating reports from Informix 4GL. 3. See “Writing code to drive a report of type JasperReport” on page 538. For example. Additionally. comma-separated values. but you must be aware of dependencies between the files. or you can direct EGL to compile the report design file by clicking Project → Clean → Clean all projects. If you change the report design or if the data used in the report changes. To create and export a report using the JasperReports framework in EGL. “Creating EGL text reports” on page 556 EGL offers its own report engine (an external Java class) that produces a simple text report. graphs. Related tasks 532 EGL Programmer’s Guide . Optionally. including PDF. See “Creating the JasperReport design file” on page 534. Related concepts EGL reports “Elements of an EGL JasperReport application” on page 533 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. The workbench does not provide a graphical way to create report design files.“Creating the JasperReport design file” on page 534 The JasperReport design file specifies the layout and appearance of the report. the report automatically calls functions in the report handler at certain points during Creating reports with EGL 533 . which your report driver program uses to create the report. EGL compiles it into a . When you have finished writing the report design file. “Creating an EGL JasperReport handler” on page 541 “Running a report of type JasperReport” on page 545 Related Reference EGL library reportLib EGL JasperReport Handler Elements of an EGL JasperReport 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. Report design file The report design file is an XML file with a . Unless you import a working design file (with the extension . you will need to create or modify one. Also. Report driver program Generally. see “Creating the JasperReport design file” on page 534. Additionally. an EGL program does the work of populating the report with data and exporting its output. You can define a function in the report handler and then call that function from a specific place in the report design file. retrieves data for the report.jasper file that is compiled from a report design file.jrxml extension that describes how the report will look and where the data will be displayed. a report handler can give you greater control over the data put into the report. For more information on the report design file and an example. You can code the XML file yourself or use a third-party tool. “Writing code to drive a report of type JasperReport” on page 538 A report-driver program is an ordinary EGL program that runs a report using a . 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.jasper).jasper file. see “Writing code to drive a report of type JasperReport” on page 538. Report handler The report handler is an EGL logic part that provides additional functions to be executed when the report runs. 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. The EGL report driver passes your connection information to JasperReports.org You can use a file with the . Related tasks “Creating an EGL JasperReport handler” on page 541 “Creating the JasperReport design file” The JasperReport design file specifies the layout and appearance of the report. you will need to create or modify one. Related concepts “Creating reports with EGL” on page 531 EGL offers different ways to create reports. create a report of the type DataSource. To add a design document to a package.xml extension for your source. after it runs and at the beginning and end of each page. For more detailed information than you will find in this topic.databaseConnection. The report handler is optional. see the following Web site: http://jasperforge. You can manipulate much of the data and the appearance of the report from the report driver program and the report design file. Include your SQL query in the XML design file source. 2.jrxml extension.jasper). follow these steps: 1.jasper). “Writing code to drive a report of type JasperReport” on page 538 A report-driver program is an ordinary EGL program that runs a report using a . straightforward database query. Customize the XML source file to use one of the following data sources: v When you have a fairly simple.the report-creation process. v Use a text editor to write JasperReports XML source information into a new text file and save the file as a .jrxml file. For example. Make sure the file you create has a . 3. Place the XML design document in the same EGL package as your report driver file and optional EGL report handler. the report calls functions in the report handler before the report runs. Create a design document in one of the following ways: v Use a third-party JasperReports design tool (like JasperAssistant or iReport).jasper file that is compiled from a report design file. you will need to create or modify one. although this can slow your compilation. Unless you import a working design file (with the extension . “Running a report of type JasperReport” on page 545 Related Reference EGL JasperReport Handler Creating the JasperReport design file The JasperReport design file specifies the layout and appearance of the report. JasperReports works best with the .jrxml extension. but you might want to use a report handler if you need to respond to events in the report. using external engines to generate the report contents. 534 EGL Programmer’s Guide . Unless you import a working design file (with the extension . dtd"> <jasperReport name="simpleReport"> <field <field <field <field name="CUSTOMER_ID" class="java.lang.sqlStatement.String" /> name="FIRST_NAME" class="java.sourceforge. or need to build your SQL statement dynamically.lang. 4.net/dtds/jasperreport.lang.String" /> <pageHeader> <band height="30"> <staticText> <reportElement x="0" y="0" width="70" height="24" /> <text> <![CDATA[Customer ID: ]]> </text> </staticText> <staticText> <reportElement x="140" y="0" width="70" height="24" /> <text> <![CDATA[First name: ]]> </text> </staticText> <staticText> <reportElement x="280" y="0" width="70" height="24" /> <text> <![CDATA[Last name: ]]> </text> </staticText> <staticText> <reportElement x="420" y="0" width="70" height="24" /> <text> <![CDATA[Phone: ]]> </text> </staticText> </band> </pageHeader> <detail> <band height="30"> <textField> <reportElement x="0" y="0" width="70" height="24" /> <textFieldExpression> <![CDATA[$F{CUSTOMER_ID}]]> </textFieldExpression> </textField> <textField> Creating reports with EGL 535 . v When your data comes from somewhere other than a database.reportData. Compile the source file. no connection information is necessary.String" /> name="LAST_NAME" class="java.0" encoding="UTF-8" ?> <!DOCTYPE jasperReport PUBLIC "//JasperReports//DTD Report Design//EN" "http://jasperreports.String" /> name="PHONE" class="java. create a report of the type DataSource. create a report of the type DataSource. The EGL report driver passes complete report data to JasperReports.v When you need to perform complex database operations. The EGL report driver includes your SQL query and passes the result set to JasperReports. An example of a report design file follows: <?xml version="1.lang. illegal characters (such as ″. a last name.class_type"></field> Field_Name A column name in the result set from the query in your design file.databaseConnection Include connection information in your EGL source file and include your SQL query in the XML design file source. and the <detail> section prints rows of data based on the data provided by the report driver program.lang. The following sections offer specifics for the different types of XML source files. that identifies the type of data to which Field_Name refers Place the fields on the report with a TextFieldExpression tag: <textFieldExpression class="java. or other conflicts.lang. 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). The <pageHeader> section prints column headers. The field names must conform to Java variable name conventions. EGL source files of the type DataSource.lang class.<reportElement x="140" y="0" width="70" height="24" /> <textFieldExpression> <![CDATA[$F{FIRST_NAME}]]> </textFieldExpression> </textField> <textField> <reportElement x="280" y="0" width="70" height="24" /> <textFieldExpression> <![CDATA[$F{LAST_NAME}]]> </textFieldExpression> </textField> <textField> <reportElement x="420" y="0" width="70" height="24" /> <textFieldExpression> <![CDATA[$F{PHONE}]]> </textFieldExpression> </textField> </band> </detail> </jasperReport> This example report design file prints four columns of information: an ID number.class_type"> <![CDATA[$F{Field_Name}]]> </textFieldExpression> 536 EGL Programmer’s Guide . a first name. and a phone number.″). such as Integer or String. 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. Class_Type A java. You can use aliases for column names within your SQL statement to handle duplicate names. This information covers very simple cases. In the XML design file.sqlStatement Place your SQL statement in the EGL report driver file. You can alias the column names within your SQL statement if necessary. define the specific fields that you want to print on the report. You can either specify your connection explicitly in your report driver or use the default connection in your build descriptor.lang.lang.jasper file in the parallel bin\package_name directory. For guidelines on creating an XML design document and a report handler simultaneously.class_type"></field> Field_Name The name of a field exactly as you specify it in your EGL source file Class_Type A java.class_type"> <![CDATA[$F{Field_Name}]]> </textFieldExpression> Compiling the XML design file source EGL automatically compiles any . you do not use a database.class_type"> <![CDATA[$F{Field_Name}]]> </textFieldExpression> EGL source files of the type DataSource. either in your XML source or in the EGL report driver.EGL source files of the type DataSource. The field names refer to column names in your SQL statement’s result set: <field name="Field_Name" class="java.reportData In this instance. For an Creating reports with EGL 537 .jrxml file is free of errors v The javac compiler is in your execution path EGL places the compiled . identifying the type of data to which Field_Name refers Place the fields on the report with a TextFieldExpression tag: <textFieldExpression class="java. so you do not need a connection or SQL statement.lang class such as Integer or String.lang class such as Integer or String.jrxml file that it finds in the package directory in the EGL source folder. Instead define the specific fields that you want to use from the records that you create in the EGL report driver: <field name="Field_Name" class="java. Class_Type A java.lang.lang. You can manually create and copy the . see “Creating reports with JasperReports” on page 532. The field names must conform to Java variable name conventions.jrxml file has changed v The .jasper file in the Java Resources\package_name directory that is parallel to EGLSource\package_name. provided that these conditions are true: v The . When you successfully generate your EGL report driver. identifying the type of data to which Field_Name refers Place the fields on the report with a TextFieldExpression tag: <textFieldExpression class="java.class_type"></field> Field_Name A column name in the result set that was created by the query in your EGL report driver.jasper file by selecting Project → Build All or Project → Clean. the product places a linked copy of the . reportLib. HTML. myReport.jasper".connectionName = "customer". myReportData ReportData = new ReportData(). you must use a double backslash in path names. myReport.jrprint".reportExportFile = "C:\\MyReport. end end Because the backslash character (\) is used in escape sequences. The following example shows a report driver program that uses data from a specified database connection: program reportDriverProgram type BasicProgram function main() SQLLib. “Creating reports with JasperReports” on page 532 EGL uses the JasperReports framework to create reports in several formats.reportDestinationFile = "C:\\temp. DataSource. "jdbc:derby:C:\\databases\\CustomerDatabase").example that shows how an XML design document gets a report data record from the report handler. myReport. myReport.exportReport(myReport. Related reference EGL reports EGL library reportLib Writing code to drive a report of type JasperReport A report-driver program is an ordinary EGL program that runs a report using a .sqlStatement). myReport Report = new Report().connect("customer".reportDesignFile = "C:\\Workspace\\MyProject\\bin\\reportModel.sqlStatement = "select * from EGL. ExportFormat.jasper file that is compiled from a report design file. see “Writing code to drive a report of type JasperReport. comma-separated values. and plain text.defineDatabaseAlias("customer". SQLLib. "admin". Related tasks “Creating an EGL JasperReport handler” on page 541 “Writing code to drive a report of type JasperReport” A report-driver program is an ordinary EGL program that runs a report using a . reportLib.pdf).fillReport(myReport. myReportData.reportData = myReportData. 538 EGL Programmer’s Guide .pdf".CUSTOMER order by CUSTOMER_ID desc". including PDF.” Related concepts “Creating reports with EGL” on page 531 EGL offers different ways to create reports. using external engines to generate the report contents. myReportData.jasper file that is compiled from a report design file. "admin"). connect("customer". First. define a record like the following example. myReport. myReportData ReportData = new ReportData().exportReport(myReport. "jdbc:derby:C:\\databases \\CustomerDatabase"). "admin"). title String. recArray myRecord[].fillReport(myReport. write the function to fill and drive the report: //Variable declarations myReport Report = new Report(). SQLLib. myReport Report = new Report(). end Next. description String.reportData = myReportData. myReport.reportDestinationFile = location. DataSource.reportDestinationFile = Creating reports with EGL 539 .reportDesignFile = "c:\\workspace\\report_project\\" :: "bin\\report_package\\myReport.jasper file that is compiled from the report design file Sets the location of a temporary file that is used while processing the report Sets the location of the exported report Sets the database connection that the report uses.defineDatabaseAlias("customer". Explanation Connects to a database and defines an alias for the database using functions in the EGL library SQLLib Creates a new report variable to represent the report Creates a new report data variable to represent the data in the report Sets the location of the .reportDesignFile = location.connectionName = "customer". reportLib.pdf). myReport. somewhere outside the program: Record myRecord type BasicRecord author String.sqlStatement). myReportData. ExportFormat. myReport.reportExportFile = location. myReportData. //Function containing the report driving code function makeReport() //Initialize report file locations myReport. recArrayElement myRecord. myReportData ReportData = new ReportData().The following table explains the code in the previous example: Code SQLLib. in terms of the database alias defined earlier Sets the database access statement that provides the data for the report Associates the report variable with the report data variable Fills the report with data 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.jasper". reportLib. myReport. "admin".sqlStatement = SQL statement. csv For example.reportData = myReportData. DataSource.appendElement(recArrayElement).html ExportFormat. recArray.author = "Gustave Flaubert".ReportExportFile = "c:\\temp\\my_report. ExportFormat.title="Madame Bovary". recArrayElement.description = "British Novel". end Selecting an export format JasperReports saves filled report data as an intermediate destination file (extension .description = "British Novel". //Fill the report with data reportLib.description = "French Novel".text ExportFormat. The reportLib.title="Hero of Our Time".pdf).description = "Russian Novel".exportReport() function in the EGL report-driver program with the report variable and a parameter that indicates the format of the report.author = "Jane Austen". reportLib. recArrayElement.title="Emma". XML. recArray.fillReport(myReport.title="Northanger Abbey".exportReport(myReport. recArrayElement.pdf ExportFormat.pdf". //Get the report data populateReportData(). You can export filled reports as PDF. reportLib.author="Jane Austen".title="Our Mutual Friend". and plain text output. recArrayElement.exportReport(myReport. recArray.author = "M.html).exportReport() function recognizes the following parameters: v v v v v ExportFormat. recArrayElement. recArrayElement.appendElement(recArrayElement). recArrayElement. HTML.xml ExportFormat. from which it can create multiple export files."c:\\temp\\myReport.html". recArrayElement. the following code causes JasperReports to export a report as a PDF file: myReport. use the reportLib.reportData). Lermontov". myReport. recArray. recArrayElement. 540 EGL Programmer’s Guide . recArrayElement. recArrayElement. recArrayElement.appendElement(recArrayElement). To export the report. CSV (comma-separated values that spreadsheet programs can read). recArray.appendElement(recArrayElement). //Export the report in HTML format myReport.reportExportFile = "c:\\temp\\myReport.jrprint). end function populateReportData() recArrayElement. recArrayElement.appendElement(recArrayElement). recArrayElement. ExportFormat.description = "British Novel".author = "Charles Dickens".jrprint". 2. Click Next. you can add this template information to an existing file by following these steps: 1. using external engines to generate the report contents. click File → New → Other. Creating reports with EGL 541 . Create a new EGL source file. you must create one. 2. To create an EGL report handler. you will need to create or modify one. myReportHandler). Identify a project or folder to contain the file. If you do not already have a project or folder.jasper). “Using JasperReport templates” on page 546 Related reference EGL JasperReport Handler EGL library reportLib Creating an EGL JasperReport handler An EGL report handler of type JasperReport provides blocks of code that the JasperReports engine can access at run time. Because the report handler name will be identical to the file name. 4. 5. Alternatively. expand EGL. or the beginning or end of the report itself. Related tasks “Creating an EGL JasperReport handler” “Creating the JasperReport design file” on page 534 The JasperReport design file specifies the layout and appearance of the report. Click Report Handler. In the EGL Source File Name field. Click Finish. Type handler and then press Ctrl+space. If you change the report design or if data changes. Predefined function names tie some of these code blocks to events that occur when JasperReports fills a report. You can call other. custom functions directly from the XML design file source. Unless you import a working design file (with the extension . 6. Related concepts “Creating reports with EGL” on page 531 EGL offers different ways to create reports. 3. You must create the code for these functions. For example. type the name of the report handler source file. the beginning or end of a line item. In the New window. choose a file name that adheres to EGL part name conventions (for example. The New EGL Report Handler wizard will give you a list of function names that correspond to report fill events. do as follows: 1. In the workbench. Select the project or folder that will contain the EGL source file and then select a package. 8. Such events might include the beginning or end of a page. 7.Important: JasperReports does not automatically refresh exported reports. you must refill and re-export the report. JasperReports will invoke ″beforePageInit()″ before entering a page. see the JasperReports documentation. // Constant Declarations) const constantName constantType = literal. 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. For more detail. // 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 542 EGL Programmer’s Guide .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. end end Saving report data in the report handler The following example code shows how to save a customer record under the name ″saveCustomer″ for later access: handler my_report_handler type jasperReport // Data Declarations customer_array customerRecordType[]. end end Getting and setting report variables The following code snippet shows how to get and set report variables in a report handler: handler my_report_handler type jasperReport // Data Declarations item_count int. // Jasper callback function function beforeReportInit() report_title = getReportParameter("ReportTitle"). //create the ReportData object for the Customer subreport Creating reports with EGL 543 . (item_count + 1)). Getting report field values The following example code snippet shows how to get report field values in a report handler: handler my_report_handler type jasperReport // Data Declarations employee_first_name String. // Jasper callback function function beforeColumnInit() employee_first_name = getFieldValue("fName"). // Jasper callback function function beforeReportInit() customer ReportData. c customerRecordType.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 // Data Declarations report_title String. // Jasper callback function function beforeDetailEval() item_count = getReportVariableValue("itemCount"). end end You must match variable types in the report handler with those in your XML source file. end function afterDetailEval() setReportVariableValue("itemCount". lang. customer_array. c.customer_num = getFieldValue("c_customer_num").SubReportHandler) $P{REPORT_SCRIPTLET}). </jasperReport> Invoking a function from the XML design document This report handler has one simple function: to print ″Hello. c.appendElement(c)... customer. addReportData(customer. <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.. c. world!").my_report_handler"> .address2 = getFieldValue("c_address2").fname = getFieldValue("c_fname"). </jasperReport> 544 EGL Programmer’s Guide . c.. c..lname = getFieldValue("c_lname").zipcode = getFieldValue("c_zipcode"). World!″ handler my_report_handler type jasperReport function hello () returns (String) return("Hello. </dataSourceExpression> <subreportExpression class="java. c...getReportData( new String("saveCustomer")))]]>..address1 = getFieldValue("c_address1").. you can retrieve it in the XML source file and pass it to a subreport: <jasperReport name="MasterReport" .hello()]]> </textFieldExpression> </textField> </band> </summary> . </subreportExpression> </subreport> .state = getFieldValue("c_state").city = getFieldValue("c_city").my_report_handler"> .phone = getFieldValue("c_phone").c. "saveCustomer").lang. c..String"> <![CDATA["C:/RAD/workspaces/customer_subreport. c.jasper"]]>. end end Retrieving report data in the XML file After report data is saved in the report handler.company = getFieldValue("c_company").data = customer_array. scriptletClass="subreports. scriptletClass="my_package.. <subreport> <dataSourceExpression> <![CDATA[(JRDataSource)(((subreports..my_report_handler)$P{REPORT_SCRIPTLET}).String"> <![CDATA[((my_package. c. end end Invoke it from the XML design document with this code: <jasperReport name="MasterReport" . One way to do this in the Package Explorer view is to navigate to and right-click the . the JasperReports engine first creates an intermediate destination file (extension .txt. . see “Creating the JasperReport design file” on page 534.csv). 2. Related concepts “Creating reports with EGL” on page 531 EGL offers different ways to create reports. Related tasks “Creating EGL source files” on page 90 The creation process is essentially the same for most EGL source files. v Optionally. To create and fill a report for an EGL project. you can have a report handler (extension . using external engines to generate the report contents. See “Writing code to drive a report of type JasperReport” on page 538.The phrase ″Hello. Then select Run As → Java Application from the menu. you might need to tell EGL where to find the appropriate Java Database Connectivity (JDBC) driver.pdf. v A compiled report design file (extension jasper) somewhere on your system. . For more information. or . you must have the following files in the specified locations: v An EGL project with a build descriptor file. You might need to add an external Java Archive (JAR) file to your project properties. Specify the location of the report design file in the report driver program.html.egl) in the EGLSource folder of the project. “Elements of an EGL JasperReport application” on page 533 The main elements of a JasperReport application in EGL are a program to run Creating reports with EGL 545 . Build the EGL project by clicking Project → Build or Project → Clean. using external engines to generate the report contents. from which it can create multiple export files in different formats (. Related concepts “Creating reports with EGL” on page 531 EGL offers different ways to create reports. follow these steps: 1. . “Using JasperReport templates” on page 546 Related Reference EGL reports Additional JasperReport handler functions EGL library reportLib EGL JasperReport Handler Additional JasperReport handler functions Running a report of type JasperReport To run a report of type JasperReport. world!″ will print at the end of the report.jrprint).java file that contains the code. 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. Run the Java program that contains the generated report driver program.egl) in the EGLSource folder of the project.xml. v A report driver program (extension . When you create a report. v If your report driver program accesses a database. You specify locations for all of these files in the report driver. then press Ctrl+space The editor provides a menu with options for database. Type jas. see Creating an EGL report handler. 5. Expand Editor and select Templates. “Writing code to drive a report of type JasperReport” on page 538 A report-driver program is an ordinary EGL program that runs a report using a .jasper file that is compiled from a report design file. When a list of preferences is displayed. 2. 4. 3.jasper). You can edit the templates themselves by following these steps: 1. For example. For more information. 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. custom. use the Tab key to move to the fields that you need to change. expand EGL. select handler to display the report handler template. a report handler can give you greater control over the data put into the report. Type handler. Related reference EGL reports EGL library reportLib EGL JasperReport Handler Using JasperReport templates EGL provides code that you can add to your program with a few keystrokes. select the appropriate template. Scroll through the list of templates and select a template. 546 EGL Programmer’s Guide . 3. add a report handler template to your source file. add JasperReport code to your source file. Click Window → Preferences. 2. Unless you import a working design file (with the extension . Additionally. then press Ctrl+space 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. or SQL data. Click Edit. The editor will replace the letters ″jas″ with code. To fill and export a report through JasperReports. Related tasks “Creating an EGL JasperReport handler” on page 541 “Creating the JasperReport design file” on page 534 The JasperReport design file specifies the layout and appearance of the report. 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 1. you will need to create or modify one. 4. To 1. 3. follow these steps: Move your cursor to a new line within the main() section of your program.the report and a report design file to control the layout of the report. 2. including code examples. follow these steps: Open a new file in your text editor. Given a report that prints all the customers from the table CUSTOMER. Creating JasperReport subreports In the simplest case. using external engines to generate the report contents. Click Apply and then click OK to save your changes.jasper file that is compiled from a report design file.lang. In some simple cases. In complex cases you might need a report handler to provide data for the subreport. Add subreport code to the design file for the main report.lang. see Creating an EGL report handler. Create one or more design files for the subreport or subreports.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. This is a section of code from the main report design file.CUSTOMER]]></queryString> <field name="CUST_NO" class="java. Related tasks “Creating an EGL JasperReport handler” on page 541 “Writing code to drive a report of type JasperReport” on page 538 A report-driver program is an ordinary EGL program that runs a report using a .String"> <![CDATA[new String("C:\\workspace\\report_project\\bin \\report_package\\my_subreport.6. from another table in the same database. you can add a subreport that shows all invoices for each customer. or from another data source altogether. with the subreport capability of JasperReports you can to print associated data for each line item in a report—from the same table. you can add a subreport in two simple steps: 1. refer to JasperReports documentation for such information. 2. Change the template to meet your needs.Integer"> </field> <field name="CUST_NAME" class="java. drawn from the table ORDERS. Here is an elementary example of how you can create a subreport and add it to your report. More complex cases are beyond the scope of this topic. 1. Add the code shown in bold in the following example: <queryString><![CDATA[SELECT * FROM ADMINISTRATOR. Related concepts “Creating reports with EGL” on page 531 EGL offers different ways to create reports. This code was originally written to print one line for each customer in the table CUSTOMER.jasper")]]> </subreportExpression> </subreport> <textField> <reportElement positionType="Float" x="57" y="11" Creating reports with EGL 547 . 7. The subreport design file is not different in kind from any other . Here you reference the value of CURRENT_CUST as $P{CURRENT_CUST}.jasper design file. you must tell the report what type the parameter is. The field names refer to column names in the ORDERS table.Integer"/> <queryString><![CDATA[SELECT * FROM ADMINISTRATOR. Next comes the query string (JasperReports is very particular about the order of the tags within the file).ORDERS WHERE CUST_NO = $P{CURRENT_CUST}]]></queryString> <field name="CUST_NO" class="java. my_subreport.lang. For example. which you will need in the SQL SELECT statement in the subreport) v Connection information.Integer"> </field> <field name="ORDER_TOTAL" class="java.jasper) 2. These are the only changes that you need to make to add a subreport. using the class= attribute of the <parameter> tag. This would involve adding the information within 548 EGL Programmer’s Guide .width="304" height="20"/> <textElement/> <textFieldExpression class="java.String"> <![CDATA["Invoice # " + $F{INVOICE_NO} + " total: " + $F{ORDER_TOTAL}]]> </textFieldExpression> </textField> </band> </detail> Even though you passed the parameter CURRENT_CUST to the subreport.Integer"> </field> <field name="INVOICE_NO" class="java. you do not need to change any code in the EGL report driver program.lang.lang.lang.lang. If you want to include other sources of data or complex calculations. which you can then reference inside the <textFieldExpression> tag. the number of the current customer. you might call up line items for each invoice from a third table.String"> <![CDATA[$F{CUST_NO} + " " + $F{CUST_NAME}]]> </textFieldExpression> </textField> </band> </detail> The <subreport> tag gives JasperReports the information it needs to run the subreport: v Positioning information (the same parameter that you will find in the main report) v Parameters that you want to pass to the subreport (in this case. because the report driver for this report specifies a data source of DataSource. Include the following essential code in that file: <parameter name="CURRENT_CUST" class="java. You can create nested subreports. however.databaseConnection v The location of a compiled report design file for the subreport (in this case.lang. you must create a report handler (see Creating an EGL report handler).Float"> </field> <detail> <band height="100"> <textField> <reportElement positionType="Float" x="50" y="10" width="300" height="20"/> <textElement/> <textFieldExpression class="java. This page shows settings for the project’s Java compiler. Unless you import a working design file (with the extension . The Properties window opens. Click OK. and there is no need to remove support from a project. If this check box is already selected. 2.jasper). 3. leave it selected. You only need to do this once for each project that uses Jasper reports. Right-click an EGL project and then click Properties. you can enable Jasper report support in a new project. 4. Use a Java compiler with the same version as the version of Java you are using to generate EGL. you must add support for Jasper reports to your project and add a Java compiler to your system’s path variable. not to EGL Web projects. Under EGL Project Features at the right side of the window. click Java Compiler. Adding the Java compiler to the PATH environment variable To compile a report design file. Creating reports with EGL 549 . right-click your EGL project and then click Properties. In the Properties window. and creating a separate design file for the nested subreport (you might call it my_invoice_subreport. 2. click EGL Project Features. the Enable project specific settings check box is cleared and the rest of the fields on the page are disabled. 3.a <subreport> tag to the subreport file my_subreport. There is no limit to the depth to which you can nest subreports. Related Reference EGL JasperReport Handler Adding support for Jasper reports to a project Before you can create reports with EGL and Jasper. you will need to create or modify one. You can add support for Jasper reports only to EGL projects. Follow these steps to tell what level of Java you are using: 1.jasper). Alternately. Adding Jasper report support adds JAR files to your project that enable EGL to compile report design files. Selecting this check box has the same effect as selecting the check box in the Properties window. the version of Java that you are using in this project is shown in the Compiler compliance level field. In the Project Explorer view. EGL needs a Java compiler in your system’s PATH environment variable. Related Tasks “Creating an EGL JasperReport handler” on page 541 “Creating the JasperReport design file” on page 534 The JasperReport design file specifies the layout and appearance of the report.jasper. 1. Select the EGL with Jasper report support check box in the New EGL Project wizard. By default. If the Enable project specific settings check box is selected. select the EGL with Jasper report support check box. In the Properties window. Related concepts “Creating reports with EGL” on page 531 EGL offers different ways to create reports. and the version of Java you are using for all your projects is shown in the Compiler compliance level field. In the Project Explorer view. click Add External JARs.com/ developerworks/java/jdk/. In the Properties window.3. In the JAR Selection window. 6. In your system’s PATH environment variable. Click Run → Run. follow these additional steps after adding support for Jasper reports: 1. add the following code: -user "<location>" In place of <location>.ibm. See your operating system documentation for instructions. From the list of runtime configurations. select the iText-1. Additionally. click Java Build Path. Now the iText-1. IBM offers a Java SDK for download at the following Web site: http://www. 550 EGL Programmer’s Guide . “Elements of an EGL JasperReport application” on page 533 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. click Configure Workspace Settings.3. 4. On the Libraries tab. Click OK. a report handler can give you greater control over the data put into the report. Adding support for PDF reports If you want to export reports in Portable Document Format (PDF).area system property to the location where you want to store reports.jar file that you just downloaded and click Open. 5. 3.jar file is listed under JARs and class folders on the build path.sourceforge. right-click your project and then click Properties. 2. Download the file iText-1. reports will be created in the product installation directory. Obtain and install a Java SDK if you do not already have one. 4.3.4. The Run window opens. 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.net/itext.user. use the directory to which you want to generate the reports. 3.jar from the following Web site:http:// prdownloads. expand Eclipse Application and then click the run configuration for the program. 1. If the Enable project specific settings check box is cleared. Otherwise. The Preferences window opens to the Compiler page. you must set the osgi. 2. On the Arguments tab of the run configuration. add the location of the Java SDK. 2. Click Apply to save changes to the run configuration. using external engines to generate the report contents. Follow these steps to add the Java compiler to your system: 1. EGL support for BIRT is available when you code either JSF handlers or programs generated for Java. Unless you import a working design file (with the extension . Alternatively. You can rely on the cheat sheet and can get a fuller introduction to report design by accessing the tutorial and background detail at the following Web site: http://www. At the Select a Wizard dialog. specifying a data set (for example. The report (hereafter called the design file) is converted to a second file. Click Finish. 6. Click File or right click on the project 2. At the New Report dialog.rptdesign. a JDBC connection). including graphics.“Features and facets of EGL projects” on page 76 EGL projects can have additional abilities. Related tasks “Creating the JasperReport design file” on page 534 The JasperReport design file specifies the layout and appearance of the report. The steps are as follows: 1. You can begin designing your output by opening the Report Design perspective of the Workbench and creating a Report project. and click Next 5. 7. the database columns specified in an SQL SELECT statement). which (in the context of your output-design work) is an XML file whose default extension is . Your subsequent tasks include specifying a data source (for example. “Creating an EGL JasperReport handler” on page 541 “Running a report of type JasperReport” on page 545 Creating reports with BIRT Business Intelligence and Reporting Tools (BIRT) is an Eclipse-based reporting system that allows for sophisticated output in PDF or HTML format. tables.jasper file that is compiled from a report design file. and using a palette to drag and drop elements such as labels and tables. select a template that will be the basis of your report.org/birt Working at the EGL or Web perspective. you can do all your work in an EGL or Web project. you create EGL code that drives output creation.rptdocument and contains data in an intermediate format 2. which has a default extension of . graphs. and charts. and details on report design will be displayed subsequently if you check Show Report Creation Cheat Sheet. choose Business Intelligence and Reporting Tools > Report 4.eclipse. you will need to create or modify one. “Writing code to drive a report of type JasperReport” on page 538 A report-driver program is an ordinary EGL program that runs a report using a . You create a report. The creation can have two steps: 1.jasper). Specify a parent folder and report name. called a document file. Select New > Other 3. added through features and facets. The document file is converted to the PDF or HTML output Creating reports with EGL 551 . Help is available if you press the question icon. Two other choices are possible, to speed processing: v You can skip the creation of a separate document file v You can start the process with an existing document file instead of a design file The basic idea for working with BIRT in EGL is as follows: v You create an EGL BIRT report, which is a variable based on BIRTReport, an external type. You can include various details (name of a design file, for example) when declaring that variable, or you can avoid specifying some or all of the details and add them later by invoking functions or setting fields that are specific to the EGL BIRT report. In either case, you can specify the details at development time, by using literals, or at run time, by using variables. Here’s an example of the syntax that first creates an EGL BIRT report and then specifies the fully qualified name of the design file: myReport BIRTReport { }; myReport.designFile = "C:/MyBIRTReport.rptdesign"; v You invoke a function that creates the output, as in the following example: myReport.createReportFromDesign(); The following creation functions are available: – createReportFromDesign() creates output from a design file, without storing the report data in a document file – createReportFromDocument() creates output from a document file – createDocument() creates a document file from a design file v You can create an EGL report handler of type BIRTHandler. This optional logic part contains functions that act as event handlers, allowing you to customize many details that affect the report output. When EGL is creating a report document (as is possible with createDocument or createReportFromDesign), the EGL runtime code invokes the event handlers in response to the following events, among others: – The opening or closing of a text file or database connection – The opening or closing of a database cursor – The retrieving of a row of database data into report fields – The creation of a report element such as a label or grid An event handler might (for example) accomplish one of the following tasks: – Specify the value of a report parameter that guides some aspect of report processing – Specify a user ID and password for connecting to a database – Set up an SQL SELECT statement to guide data retrieval from the database – Act as an intermediary, receiving displayable data from your EGL program and then providing that data to the report engine at the appropriate time – Change report formatting and text in response to a specific value being placed into the report You can use a cascading style sheet (CSS) to control display characteristics of the report. Related concepts “Creating reports with EGL” on page 531 EGL offers different ways to create reports, using external engines to generate the report contents. Related tasks 552 EGL Programmer’s Guide “Creating an EGL BIRT handler” on page 555 An EGL BIRT handler (that is, an EGL handler of type BIRTHandler) contains functions that are invoked when EGL is creating a report document. The process of creating a BIRT handler is to create a source file and, within that file, to code the handler. For details on what to code, see ″EGL BIRT handler″ in the Reference Guide. “Adding support for BIRT reports to a project” Before your EGL code can create BIRT reports, you must add support to your project. You need to add support only once for each project, and you do not need to remove support if you stop using BIRT reports. During this beta, support is available for General and Plug-in projects. Related reference BIRT Reports Central to EGL’s support for Business Intelligence and Reporting Tools (BIRT) is the external type called BIRTReport. This topic describes how to create a variable of that type and how to use it to create output. EGL BIRT handler An EGL BIRT handler part contains event handlers, which are functions invoked during report creation. For an overview of EGL support for BIRT, see ″Creating reports with BIRT″ in the Programmer’s Guide. Adding support for BIRT reports to a project Before your EGL code can create BIRT reports, you must add support to your project. You need to add support only once for each project, and you do not need to remove support if you stop using BIRT reports. During this beta, support is available for General and Plug-in projects. You can add support for BIRT as you create a project. On the second screen in the New EGL Project wizard, check Show Advanced Settings, and at the next screen, select the EGL with BIRT report support check box. Alternatively, you can add support for an existing project: 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 BIRT report support check box. If this check box is already selected, leave it selected. 4. Click OK. Also, if you need to reference graphics that are stored in the BIRT resource folder, click Windows -> Preferences ->Report Design -> Resource and specify the folder. For additional details on graphics and BIRT, see ″External types in BIRT report-layout event handler″; in particular, the section on ImageInstance. Adding support for PDF reports If you want to export reports in Portable Document Format (PDF), you have an additional step after adding support for BIRT reports. For a General project, do as follows: 1. Download the file iText-1.3.jar from the following Web site:http:// prdownloads.sourceforge.net/itext. Creating reports with EGL 553 In the Project Explorer view, right-click your project and then click Properties. In the Properties window, click Java Build Path. On the Libraries tab, click Add External JARs. 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. 2. 3. 4. 5. For a Plug-in project, do a series of steps outside of the Integrated Development Environment: 1. Download the file iText-1.3.jar from the following Web site:http:// prdownloads.sourceforge.net/itext. 2. Find the product install location for IBM shared code and then the plugins directory; for example: C:\Program Files\IBM\SDP70Shared\plugins 3. In the plugins directory, find the most recent version of the directory for plugin com.lowagie.itext; for example com.lowagie.itext_1.3.0.v20070205-1728 As shown, the name is followed by a version number and timestamp. 4. Ensure that a lib directory is within the directory for plugin com.lowagie.itext. If lib is not there, add it; for example: com.lowagie.itext_1.3.0.v20070205-1728\lib 5. Copy the file iText-1.3.jar into the lib directory. Setting the build descriptor option birtEngineHome Before you can work with BIRT, you need to download BIRT runtime code and set the birtEngineHome build descriptor option, but only if you are working in a General project. Here are the steps: 1. Go to http://www.eclipse.org/birt 2. Access the runtime code of interest. At this writing, the procedure is as follows: a. On the left of the page, click Download b. At the next page, go to the More Downloads section and click Recent Builds Page c. At the next page, go to the Latest Releases section and, in the Build Name column, click 2_3_0 d. At the next page, go to the Report Engine section and click birt-runtime-2.3.0.zip e. At the next page, click a mirror location and follow the displayed instructions to download the code Note: Rational Business Developer 7.5 supports BIRT version 2.3.0 and no others. 3. Unzip the downloaded code into a directory of your choice; for example, C:\birt 4. In the project build descriptor, set the birtEngineHome option to the fully qualified path of the ReportEngine directory; for example, C:\birt\birt-runtime2_3_0\ReportEngine 554 EGL Programmer’s Guide Accessing the non-EGL jar files needed at deployment time To deploy code that runs a BIRT report, ensure that you deploy a set of jar files that are found in the ReportEngine\lib subdirectory of the directory that contains the BIRT runtime code; for example, in C:\birt\birt-runtime-2_3_0\ReportEngine\ lib. The jar files are commons-codec-1.3.jar, coreapi.jar, engineapi.jar, js.jar, modelapi.jar, and scriptapi.jar. For a description of how to deploy them, see the Generation Guide section ″Preparing for Deployment″. Related concepts “Creating reports with BIRT” on page 551 Business Intelligence and Reporting Tools (BIRT) is an Eclipse-based reporting system that allows for sophisticated output in PDF or HTML format, including graphics, tables, graphs, and charts. EGL support for BIRT is available when you code either JSF handlers or programs generated for Java. Related tasks “Creating an EGL BIRT handler” An EGL BIRT handler (that is, an EGL handler of type BIRTHandler) contains functions that are invoked when EGL is creating a report document. The process of creating a BIRT handler is to create a source file and, within that file, to code the handler. For details on what to code, see ″EGL BIRT handler″ in the Reference Guide. Related reference BIRT Reports Central to EGL’s support for Business Intelligence and Reporting Tools (BIRT) is the external type called BIRTReport. This topic describes how to create a variable of that type and how to use it to create output. EGL BIRT handler An EGL BIRT handler part contains event handlers, which are functions invoked during report creation. For an overview of EGL support for BIRT, see ″Creating reports with BIRT″ in the Programmer’s Guide. birtEngineHome External types in a BIRT report-layout event handler This topic reviews the EGL external types that you use when coding a report-layout event handler. For background information, see ″EGL BIRT reports,″ ″BIRT handler″ and ″BIRT report-layout event handlers.″ Creating an EGL BIRT handler An EGL BIRT handler (that is, an EGL handler of type BIRTHandler) contains functions that are invoked when EGL is creating a report document. The process of creating a BIRT handler is to create a source file and, within that file, to code the handler. For details on what to code, see ″EGL BIRT handler″ in the Reference Guide. To create a BIRT handler, do as follows: 1. Identify a project or folder to contain the file. If necessary, create the project or folder. 2. In the workbench, click File -> New -> EGL -> EGL Source File. 3. Select the project or folder that will contain the EGL source file and then select a package. Creating reports with EGL 555 4. In the EGL Source File Name field, type the name of the handler source file. The file name will be identical to the name of the report handler name. 5. Click Finish. 6. The next step works only if the capability ″EGL with BIRT support″ is in effect. To put that capability into effect, click Window->Preferences and, when the Preferences dialog is displayed, highlight EGL and, at the right, select the checkbox for EGL with BIRT report support. 7. In the EGL source editor, type handler with no subsequent space and press Ctrl-Space. At the context menu, select Handler - EGL BIRT Handler. 8. Type the handler name. For an overview of EGL support for BIRT, see ″Creating reports with BIRT.″ Related concepts “Creating reports with BIRT” on page 551 Business Intelligence and Reporting Tools (BIRT) is an Eclipse-based reporting system that allows for sophisticated output in PDF or HTML format, including graphics, tables, graphs, and charts. EGL support for BIRT is available when you code either JSF handlers or programs generated for Java. Related tasks “Creating an EGL BIRT handler” on page 555 An EGL BIRT handler (that is, an EGL handler of type BIRTHandler) contains functions that are invoked when EGL is creating a report document. The process of creating a BIRT handler is to create a source file and, within that file, to code the handler. For details on what to code, see ″EGL BIRT handler″ in the Reference Guide. “Adding support for BIRT reports to a project” on page 553 Before your EGL code can create BIRT reports, you must add support to your project. You need to add support only once for each project, and you do not need to remove support if you stop using BIRT reports. During this beta, support is available for General and Plug-in projects. Related reference BIRT Reports Central to EGL’s support for Business Intelligence and Reporting Tools (BIRT) is the external type called BIRTReport. This topic describes how to create a variable of that type and how to use it to create output. EGL BIRT handler An EGL BIRT handler part contains event handlers, which are functions invoked during report creation. For an overview of EGL support for BIRT, see ″Creating reports with BIRT″ in the Programmer’s Guide. 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. 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 556 EGL Programmer’s Guide 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. 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 558. 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. For more information on converting existing I4GL reports to EGL, refer to the IBM Informix 4GL to EGL Conversion Utility User’s Guide. Related concepts “Creating reports with EGL” on page 531 EGL offers different ways to create reports, using external engines to generate the report contents. “Handler events for a text report” The TextReport external type defines the events that a basic text report handler can react to. “Writing code to print a text report” on page 558 This topic provides a sample text report program and handler. Text report functions 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. For a sample text report program and handler, see “Writing code to print a text report” on page 558. Related concepts Creating reports with EGL 557 “Creating reports with EGL” on page 531 EGL offers different ways to create reports, using external engines to generate the report contents. “Writing code to print a text report” This topic provides a sample text report program and handler. Text report variables The text report engine recognizes a specific set of events during report generation. Each event is represented by a variable in the engine. 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. 558 EGL Programmer’s Guide 14. The onLastRow() function in the handler prints the running total that the handler has been updating. 15. The report engine closes the report file, and control passes back to the handler, and finally to the generator, which terminates the run unit. The customer record The program uses the following record to access the SQL database of customers: record CustomerRecord type SQLRecord {tableNames = [["ADMINISTRATOR.CUSTOMER", "L1"]], keyItems = [customerNumber]} customerNumber STRING customerName STRING customerAddr1 STRING customerAddr2 STRING customerAddr3 STRING customerBalance MONEY end {column="C_NUMBER", maxLen=6}; {column="C_NAME", isSQLNullable=yes, maxLen=25}; {column="C_ADDR1", isSQLNullable=yes, maxLen=25}; {column="C_ADDR2", isSQLNullable=yes, maxLen=25}; {column="C_ADDR3", isSQLNullable=yes, maxLen=25}; {column="C_BALANCE", isSQLNullable=yes}; The report generator Execution begins with the report generator. package com.companyb.customer; program reportGenerator type BasicProgram myCustomer CustomerRecord; myHandler textReportHandler{}; function main() myHandler.start(); // passes control to handler // get customer list from database open myResults scroll for myCustomer; forEach (from myResults) // loop through results myHandler.output(myCustomer.customerName, myCustomer.customerBalance); end // forEach myHandler.finish(); // close report end end The generic handler Both the report generator and the report engine call functions from the handler. package com.companyb.customer; record reportRecord type BasicRecord customerName STRING; customerBalance MONEY; end handler textReportHandler type BasicHandler myReport TextReport{}; // creates instance currentReportRecord reportRecord; runningTotal MONEY = 0; function start() myReport.onEveryRowListener = onEveryRow; myReport.onLastRowListener = onLastRow; // accept defaults on everything but destination file myReport.startReport("D:/temp/customerReport.txt", null,null,null,null,null,null); end Creating reports with EGL 559 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 in) myReport.printText(currentReportRecord.customerName); myReport.column(40); myReport.printText(currentReportRecord.customerBalance); myReport.println(); end function onLastRow(myEvent TextReportEvent in) 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 556 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. 560 EGL Programmer’s Guide Working with Web transaction applications in EGL Web transactions in EGL are a holdover from VisualAge Generator, and offer a very basic Web interface for user I/O. Best practice is to use Web transactions for migration only. New code should use JavaServer Faces (JSF) for a Web interface. The central idea of Web transactions is similar to the one behind Text UI: v A VGWebTransaction program (comparable to a Text UI program) presents a Web page for user input. v The Web page is based on a VGUIRecord (comparable to a Text UI form). EGL transforms fields in the record into controls on the Web page, using field properties to determine the type of control to create. When generating COBOL, EGL simply includes the VGUIRecord in the compiled program. When generating Java, EGL creates the following JSP files: v filename.jsp, for each VGUIRecord file, where filename.egl is the source file name. v EGLWebStartup.jsp, a Web page that displays a list of your VGWebTransaction programs. You select a program and run it from this page rather than running the associated filename.jsp page. v CSOERRORUIR.jsp, the error page that you customize to report on TCP/IP communication problems and on problems internal to a Web transaction. v Vagen1EntryPage.jsp, the default selection list for EGLWebStartup.jsp. v A series of sample files that show how to perform common tasks: – reqPage.jsp – – – – usrMsgPage.jsp Vagen1ErrorPage.jsp Vagen1ExpiredPasswordPage.jsp Vagen1LogonPage.jsp You can customize these JSP files using Page Designer (see “Using EGL with the Eclipse IDE” on page 1). To run Web transactions in EGL, you must perform the following steps: 1. Modify configuration files (see “Web transaction configuration files” on page 563). 2. Get a Web server running in your workspace (see “Adding a Web server” on page 393). 3. Customize Vagen1EntryPage.jsp to list your VGWebTransaction programs (see “Running VGWebTransaction programs” on page 564). 4. Launch your programs through EGLWebStartup.jsp (see “Running VGWebTransaction programs” on page 564). Customizing JSP files EGL does not just allow you to modify the JSP files that it creates from your VGUIRecord files; it takes for granted that you will heavily modify these files. For this reason, EGL does not overwrite an existing name.jsf file (where name is name of your VGUIRecord). Instead, if name.jsf exists, EGL creates (or overwrites) a file © Copyright IBM Corp. 1996, 2008 561 named newname.jsf. You must copy the changed portions of the file to name.jsf yourself. Alternatively, if you want EGL to replace name.jsf, delete the file before generating. Related concepts “Using EGL with the Eclipse IDE” on page 1 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. “Using VGUIRecord properties” on page 564 The relationship between the field properties determines how EGL translates fields from the VGUIRecord into HTML controls on a JSP. “Using JavaServer pages with Web transactions” on page 567 “UI record bean API” on page 570 Related tasks “Web transaction configuration files” on page 563 Before you can run Web transactions in EGL, you must modify at least one configuration file. “Adding a Web server” on page 393 You must have a Web server started and synchronized before you can run Web applications. “Running VGWebTransaction programs” on page 564 To run a Web transaction program, start by running EGLWebStartup.jsp on your Web server. Adding Web transaction support to an EGL Web project Before you can use Web transactions in your EGL project, you must add support for Web transactions to your project. You can do this when you create the project, or add support to an existing project. Add support for Web transactions at the time you create a project: v Create a new EGL Web project and select the Show Advanced Settings check box on the general settings page of the New EGL Project wizard. v Select the EGL support with Legacy Web Transactions check box on the Project Facets page. The Project Facets page is the second page after the general settings page. Add support for Web transactions to an existing EGL Web project: 1. In the Project Explorer view, right-click the EGL Web project and then click Properties. The Properties window opens. 2. In the Properties window, click Project Facets. 3. Click Add/Remove Project Facets. 4. In the Project Facets window, select the EGL support with Legacy Web Transaction check box. 5. Click Finish. 6. Click OK. Adding support for Web transactions makes the following changes to the project: 562 EGL Programmer’s Guide v Jar files are added to the folder WebContent\WEB_INF\lib and to the project’s Java build path. These Jar files constitute the runtime support of a Web application and the EGL gateway servlet. v The following sample and utility files are added to the project’s WebContent folder: – CSOERRORUIR.jsp – EGLWebStartup.jsp – – – – – Vagen1EntryPage.jsp Vagen1ErrorPage.jsp Vagen1ExpiredPasswordPage.jsp Vagen1LogonPage.jsp vawcg-wp.gif – visage.gif v Files that set properties for the gateway servlet and information for linkage between Web transactions are added to the folder JavaResources\JavaSource. See Gateway servlet parameters and Linkage properties. v The gateway servlet is registered in the Web configuration file. You can not remove support for Web transactions from a project. If you want each new EGL Web project created to have support for Web transactions, open the EGL preferences window and select the EGL support with Legacy Web Transactions check box. See Setting EGL preferences. Related tasks “Working with Web transaction applications in EGL” on page 561 “Setting general preferences” on page 173 Related reference Gateway servlet parameters Web transaction linkage properties Web transaction configuration files Before you can run Web transactions in EGL, you must modify at least one configuration file. The gw.properties file in the JavaResources: src folder contains basic configuration information for your Web transaction application. By default, the file names csogw.properties as the hptLinkageProperties file, which resolves locations for your application. You will have to edit the csogw.properties file (or whatever file you use to specify your linkage) before your programs will run properly. The following instructions cover the simplest case; for more complex cases, and for more information, see ″Web transaction linkage properties″ in the EGL Generation Guide. 1. You can configure the file to look for your Web transaction programs in different locations depending on the file name. In this example, assume all your files are located in a single local directory. The asterisk in the following line is a wildcard that represents any character or string of characters: application.*=allfiles 2. You have now associated the name allfiles with any application EGL is looking for. Tell EGL that the files are local with the following line: Working with Web transaction applications in EGL 563 You do not directly run either a VGWebTransaction program or a JSP file based on a VGUIRecord. EGLWebStartup. you must modify at least one configuration file.serverLinkage.jsp. if necessary EGL will start the server for you. Related concepts “Working with Web transaction applications in EGL” on page 561 Web transaction linkage properties Running VGWebTransaction programs To run a Web transaction program.allfiles. Customize this list to include all Web Transaction programs you want to run from this project. start by running EGLWebStartup.jsp displays in a browser in your Web server. Use the name of the VGWebTransaction source program.jsp to work properly. see “Web transaction configuration files” on page 563).commtype=DIRECT 3. By default.jsp (for other options. EGLWebStartup.javaProperty=fileLocation These three lines provide the minimum configuration information for EGLWebStartup. Assign a folder (relative to the current JavaResources: src folder) where your generated programs reside (shown as fileLocation in the following line): serverLinkage. EGLWebStartup. Using VGUIRecord properties The relationship between the field properties determines how EGL translates fields from the VGUIRecord into HTML controls on a JSP. with no extension. Most UI controls involve setting the uiType property to one of the following values: v input v inputOuput v output 564 EGL Programmer’s Guide .jsp on your Web server. The page presents a list of programs for the user to choose from.jsp displays the selection list that it finds in Vagen1EntryPage. and the related bean by means of a Web page. as in the following example: <FORM METHOD=POST ACTION="<%= hptGatewayURL %>"> <BR>Choose a Program to execute below:<BR> <SELECT NAME="hptAppId" SIZE=10> <OPTION VALUE=CPGM01>Customer file maintenance <OPTION VALUE=CPGM02>Process new orders <OPTION VALUE=CPGM03>Print invoices </SELECT> Related concepts “Working with Web transaction applications in EGL” on page 561 “Web transaction configuration files” on page 563 Before you can run Web transactions in EGL.allfiles. that is generated for you automatically when you associate the project with runtime Web server. the JSP. Instead EGL manages the interaction between the program. uiType = input } = [1. HTML controls HTML control Text box Text area Field is array? N N uiType input or inputOutput input or inputOutput Field length <=80 chars > 80 chars selectedIndexItem Field value n/a n/a Initial display Initial display (between <textarea> and </textarea> tags) Not used Radio buttons Check boxes Singleselection combo box Multipleselection combo box Y Y Y input or inputOutput input or inputOutput output n/a n/a n/a Numeric field Numeric array Not used Numeric field Entries in combo box Y output n/a Numeric array Entries in combo box The following code creates a set of three radio buttons: 10 ID INT [3] { displayName = "First option: \nSecond option: \nThird option:" . Because the variable that generates the display has three INT Working with Web transaction applications in EGL 565 . 3]. The displayed control looks like the following example: Note that each radio button label is followed by a text box that contains the value of the corresponding array member. 2.The following table shows how to create each of the specified HTML controls. selectedIndexItem = SELECTEDID. 10 SELECTEDID int { uiType = none }. EGL maintains this behavior for compatibility. These text boxes are an artifact of the VisualAge Generator implementation. Table 56. If SELECTEDID is an array. there is no reason to do so. Here the UI type of programLink causes the contents of the displayName property (″MyLink″) to be displayed as a link. you could. Consider the following example of a field from a VGUIRecord source file: 10 MYLINK char(32) { displayName = "MyLink". EGL will create a combo box rather than radio buttons or check boxes. as in the following code. enter new values for any of those members. the user can select only a single value: 10 ID INT [3] { displayName = "Pick a number:" . uiType = programLink. in theory. newWindow = no. value="ParmData" }. uiRecordName = "DEST_PGE". If you change SELECTEDID to an array. 3]. @programLinkData { programName = "DEST_PGM". That link points to the program in the 566 EGL Programmer’s Guide . as the user is selecting a value from the array rather than from the prompt message. @linkParameter { name = "ID". valueRef=NAME }.members. If SELECTEDID is a single INT. linkParms = [ @linkParameter { name = "PARM". 2. the code will create a Web page with check boxes instead of radio buttons: 10 SELECTEDID int [3] { uiType = none }. Here it makes sense to also change the display name. selectedIndexItem = SELECTEDID. and has a uiType of input. value="107" } ] } }. in practice. The displayed control looks like the following example: Other controls Other values of the uiType property create other HTML artifacts. the user can hold down the Shift key and make multiple selections. 10 SELECTEDID int { uiType = none }. uiType = output } = [1. @linkParameter { name = "NAME". If you take the same code and change the uiType to output. a default JSP file is created.jsp suffix and contain a mixture of HTML tags and JSP syntax. based on the fields in the VGUIRecord part. More information on JSP technology is available atJavaServer Pages (JSP) technology JavaServer Pages (JSP files) are ASCII files that have a . Related concepts “Working with Web transaction applications in EGL” on page 561 Related reference show considerations for Web transactions Using JavaServer pages with Web transactions When you save a VGUIRecord source file.programName property (″DEST_PGM″). When the user submits the form. You can edit this default JSP to change its appearance or the data displayed on it. such as any of the input or output controls shown earlier. For information about how field values are passed to the called program. uiType = submit } = "SUBMIT". see ″show″ in the EGL Language Reference. The names and values in each of the @linkParameter properties are passed in a query string with the URL of the destination program. %> Working with Web transaction applications in EGL 567 . The following code shows a simple scriptlet: <% if (x == 1) {out. uiRecordName = "DEST_PGE". @programLinkData { programName = "DEST_PGM". Scriptlets Pieces of Java code called scriptlets can be inserted into JSP files. uiType = uiForm. Methods specific to UI record beans are covered in “UI record bean API” on page 570. but the Java code itself is not included with the HTML sent to the browser. Substructure fields below MYFORM01 declare fields within the form. Scriptlets can be placed anywhere in the JSP source. linkParms = [ @linkParameter { name = "PARM". value="ParmData" } ] } }. which launches the page in the uiRecordName property (″DEST_PGE″). or the following submit button: 20 BUTTON1 char(8) { displayName = "Submit". A Web application server transforms a JSP file into a Java servlet by a process known as page compilation.println(EMPNO. At run time. The VGWebTransaction program calls the program in the programName property using the show command.getLabel())}. The following example shows a field that generates a <FORM> tag and all associated contents on the browser: 10 MYFORM01 char(60) { displayName = "MyForm01". newWindow = no. the Java code in the scriptlet runs on the server side. In this way. interfaceName A interface implemented by a bean. %> This scriptlet adds the string string_value to the HTML code at the location of the scriptlet and then adds a carriage control character. The out object accepts only strings.print(string_value). Adding the carriage control character starts the next HTML code on the next line. page The bean is stored in the JSP page context. scriptlets let you access data in the VGUIRecord and use that data on the page.lang. Valid values are: session The bean is stored in the HttpSession object. For specific methods for accessing a UI record bean. <% out. see “UI record bean API” on page 570. beanClassName The fully qualified class name of the bean. If you need to print something other than a string type. and it does not have the effect of the HTML <br> tag. This UI record bean gives the scriptlets in the JSP access to the data in the VGUIRecord. This carriage return does not affect the appearance of the HTML in the browser. %>. Other scriptlets in the JSP file can use this bean by referring to its name as defined in the <jsp:useBean> tag. which can increase the readability of the source code. For example. This out object is created and made available to the scriptlet as part of the page compilation process of the JSP.The Java code in a scriptlet can add to the HTML by printing a string to the out PrintWriter object. This attribute is optional. beanScope The scope of the bean.String. <% out. The JSP file references this bean with the <jsp:useBean> tag. There are three ways to print to the out object.println(string_value). request The bean is stored in theHttpServletRequest object. 568 EGL Programmer’s Guide . you must first convert that type to a string. %> This scriptlet adds the string string_value to the HTML code at the location of the scriptlet.print(string_value). Bean tags The JSP file created to go along with the VGUIRecord references a UI record bean. such as java. application The bean is stored in the servlet context. <% string_value %> This scriptlet is equivalent to <% out. the following code references a bean to be used in a JSP file: <jsp:useBean id="referenceName" class="beanClassName" type="interfaceName" scope="beanScope" /> referenceName The name of the bean. jsp is the error page that you customize to report on TCP/IP communication problems and on problems internal to a Web transaction. Do not specify CSOERRORUIR. The following example shows an errorPage directive: <%@ page errorPage="jspName. the JSP specified in the errorPage directive handles the error.uibean. Working with Web transaction applications in EGL 569 . Java import statements are a shorthand to save you from having to type out the fully qualified name of the package everywhere when referring to elements inside it. and it is not possible to send any parameters.VGDataElement" %> The errorPage directive specifies a Web page to forward the browser to in response to an uncaught exception. you must specify which Web transaction or VGWebTransaction that the gateway servlet should load. If you want all errors to be presented by CSOERRORUIR. To forward control from a pageHandler to a VisualAge Generator Web transaction or EGL VGWebTransaction part. but each does so in a different way. These import statements apply to any scriptlet in the JSP.ibm. For example. Add the following import directive to each JSP file created to work with a VGUIRecord: <%@ page import = "com.jsp. This type of forward statement has the following format: forward to URL "URL?hptAppId=linkageID". even though CSOERRORUIR. specify errorPage="vagen1error.jsp in the errorPage directive.jsp". use the EGL forward statement. v The simplest way to forward control to a Web transaction or VGWebTransaction part is to forward control to the gateway servlet instead of the Web transaction or VGWebTransaction part directly. v To forward control directly to a specific VisualAge Generator Web transaction or EGL VGWebTransaction part. and EGL VGWebTransaction parts can forward control and data to each other. if a UI record JSP specifies an incorrect array index in a call to the UI record bean.vgj.Directives The JSP file can also include JSP directives.jsp" %> Related concepts “UI record bean API” on page 570 “Working with Web transaction applications in EGL” on page 561 Transferring control between JSF Handlers and Web transactions EGL JSF Handlers. the forward statement points the browser to the gateway servlet’s introductory page. Two of these directives are significant when working with Web transactions: The import directive lets you add Java import statements. In this case. URL The complete URL of the gateway servlet on which the target Web transaction is located. This type of forward statement has the following format: forward to URL "URL". VisualAge Generator Web transactions. For more information. 570 EGL Programmer’s Guide . Returns the default title of the page from the title property of the VGUIRecord. output. These methods get and change information about the VGUIRecord as a whole. modify the action attribute of that tag to reference the URL of the JSP file associated with the pageHandler. the VGUIRecord part is represented by a UI record bean. String getHelpText().WEBUITRAN=CICS5. The commands listed in the interface below can access this bean from a JSP file.URL The complete URL of the gateway servlet on which the target Web transaction is located. the linkageID parameter in the forward statement is WEBUITRAN. Returns the gateway URL and is used as the ACTION of an HTML form. see ″Web transaction linkage properties″ in the EGL Generation Guide. Web transaction linkage properties UI record bean API At run time. Returns the text from the help property of the VGUIRecord. Related tasks “Web transaction configuration files” on page 563 Before you can run Web transactions in EGL. you must modify at least one configuration file. String getGatewayURL(). v If the JSP file associated with the Web transaction uses a form tag. UI Record Bean Interface The get and set methods implemented for the UI record bean are described in this section. you must modify the JSP file associated with the Web transaction. Set and get methods implemented for variables that are defined with a uiType of none return the appropriate Java class for the variable. To forward control from a VisualAge Generator Web transaction or EGL VGWebTransaction part to an EGL pageHandler part. This parameter is the webtran parameter in the application property that defines this Web transaction in the linkage properties file. String getTitle(). or inputOutput in the Java Bean generated for the UI record. v If the JSP file associated with the Web transaction uses an anchor tag. The String class is used by all get and set methods implemented for variables with a uiType property of input. modify the href attribute of that tag to reference the URL of the JSP file associated with the pageHandler. For example. if a Web transaction is defined in the linkage properties file with the code application. linkageID The linkage ID of the Web transaction or VGWebTransaction part. VGDataElement Interface These methods get or change information about an individual field (a VGDataElement) within the VGUIRecord. Returns the ID that identifies the Web transaction with which the VGUIRecord is associated. Returns the index of the element. Same as getGatewayURL() but uses the HTTPS protocol. returns the same value as the UI record bean version of this method.String getSecureGatewayURL(). Sets the specified field from the VGUIRecord to the specified value. int getIndex(). String getSessionID(). String getSecureGatewayURL(). Enumeration getEditTableValues(). Returns the elements in an edit table associated with an input field. Returns the label UI property of a variable. String getAppID(). If the variable is an element of an array. For variables that do not have a uiType property set to form or programLink. Returns the ID that identifies the current gateway session that processes the submit request. This string is usable as an HREF in an <A> HTML element. Returns the error message associated with the element. String getHelpText(). void setfieldName(String value). String form of the number that uniquely marks the page that is served to the client. Returns the text in the help property for the field. String getPageID(). VGDataElement getfieldName(). String getGatewayURL(). String getLabel(). Returns the gateway URL with the HTTPS protocol and is used as the ACTION of an HTML form. VGDataElement elementNamed(String name). Returns the value of the specified field from the VGUIRecord. For variables that do have a uiType property set to form or programLink. boolean hasInputError(). Indicates whether or not any field in the VGUIRecord is in error. returns the label defined for the index of the VGDataElement instance. returns a URL string that contains all the parameters as defined by the link properties. Working with Web transaction applications in EGL 571 . Returns the element in the UI record bean named name. String getErrorMessage(). The index of each sub-element is that of the VGDataElement instance. Related concepts “Working with Web transaction applications in EGL” on page 561 “Using JavaServer pages with Web transactions” on page 567 572 EGL Programmer’s Guide . v The field is an array. If the target is not an array. boolean hasInputError(). boolean isEmpty(). but the value of the field specified by the numElementsItem property is not zero. boolean isDisplayable(). Returns TRUE only when the field is an array. Returns TRUE if the index of the element is a value in the field specified by the SelectedIndexItem property. Returns Enumeration of VGDataElements that are valid sub-elements (the uiType property is not set to none) of the VGDataElement instance. void setDatetimeFormat(DateFormat_object). You can use this method only on a variable that has been assigned a date or time edit. Returns TRUE if the element has an input error. boolean isSelected(). In any other case the method returns FALSE. the method returns an Enumeration containing the elements of that array.String getTextValue(). Sets a Java DateFormat object to specify the valid format for date/time values that pass between the browser and tier 2 in either direction. but the numElementsItem property has a null value. Only the lowest level sub-elements are returned. Returns a TableModel of all formatted text values for the occurrences and sub-elements of the VGDataElement instance. the method returns an Enumeration with only a single element. Enumeration occurrences(). v The field is an array. If the target VGDataElement is an array. and the value of the field specified by the numElementsItem property is zero. TableModel getTextValuesTable(). The number of elements returned is limited by the value of the field in the numElementsItem property. Returns TRUE if the variable associated with a submit button has a non-blank value. Returns the String value of the element with all output formatting on the data. Enumeration subElements(). The following cases return FALSE: v The field is not an array. – JDBC converts data that is defined on the host as a CHAR. As long as there is only one row that satisfies the criteria you do not notice a difference. You can use the CHAR primitive type. if a problem occurs.sqlData. There is a difference between Debug and generated COBOL programs. With the EGL debugger. debugging an EGL program involves the following: v Selecting 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 selecting Debug EGL Program v Clicking the Step Into button to move through the program Debugging using JDBC for SQL access The debugger uses JDBC for SQL access. and TIMESTAMP primitive types when defining fields for SQL columns that contain these types. but no difference between Debug and generated Java programs: v Be sure to use the DATE. TIME. examine or change variables. 1996. If you have this situation. There are separate calls to the SQL manager and MQ series manager for commit and rollback. See the following sample technique for how you can address this difference if it is important to you. as long as the CHAR variable has the sqlDataCode property set to indicate the type of the SQL column. You can also use CHAR without the © Copyright IBM Corp. DBCHAR. you can set breakpoints (places for execution to pause). which creates the following differences from running on environments where JDBC is not used: v JDBC does not support two-phase commit. Therefore. v JDBC always runs dynamic SQL. it is possible for one resource to commit or rollback without the corresponding commit or rollback for the other resource. You can debug the following code: v JSF Handlers v Programs v Rich UI Handlers. Therefore. or MBCHAR SQL column with the ″FOR BIT DATA″ option. see Rich UI debugging At its simplest. single row select can result in more than one row being returned without setting sysVar. and move through the program one step at a time.sqlCode to -811. set the asBytes property to YES for the field that corresponds to the SQL column that is defined as ″FOR BIT DATA″.Debugging EGL applications Debugging is the process of monitoring the execution of a program to pinpoint the causes of errors. in this case. The following limitations also apply to both Debug and Java programs. 2008 573 . Generated COBOL uses static SQL except when you use the EGL prepare statement or a table name host variable (tableNameVariables property in the SQLRecord definition). there are the following differences: – In dynamic mode. see sqlDataCode v Certain SQL information is not supported by JDBC: – sqlLib. see “EGL debugger commands” on page 580. see “How build descriptor settings affect the EGL debugger” on page 583.systemType is debug) // do nothing else // check for sysVar. database connections. and other concepts. In the EGL program you can include logic such as the following: if (sysVar.sqlData.sqlerrmc – sysVar.sqlDataCode property. Debug environment different from host There is a technique you can use when the debug environment is different from the host environment: In the EGL -> Debug preferences.sqlData. For further information on sqlDataCode.sqlwarn[n] More sophisticated debugging involves launch configurations. you must rely on the JDBC driver to convert the dates to CHAR format. setting variable values. you can start the debug session as described in “Stepping through an application in the EGL debugger” on page 575. breakpoints.sqlData. but when you omit the sqlDataCode. For an overview.sqlCode = -811 end This enables you to include system-specific logic that is only valid on the host system.sqlerrmc – sqlLib. select Set systemType to DEBUG. see the EGL function key mapping table in validationBypassKeys or helpKey.sqlwarn[n] – sysVar. Debugging programs To debug programs that do not run under JEE. For information on EGL debugger commands. “Stepping through an application in the EGL debugger” on page 575 This topic offers guidance on the basic steps of debugging a program in the EGL debugger.sqlData. “Creating a launch configuration in the EGL debugger” on page 588 574 EGL Programmer’s Guide . For more information on how build descriptor settings affect the EGL debugger.sqlData. For information on the keyboard differences. see “Stepping through an application in the EGL debugger” on page 575. Related concepts VisualAge Generator compatibility “Character encoding options for the EGL debugger” on page 603 “EGL debugger commands” on page 580 Rich UI debugging Related tasks “Setting preferences for SQL database connections” on page 219 “Setting preferences for the EGL debugger” on page 604 This topic tells you how to change your preferences for the EGL debugger. The debugger always starts debugging from a program part. such as a library.itemCost=12. If you want to debug another logic part. customerItems items[3]. customerItems[3]. you can use the debugger to step through the code and find the point at which the program fails. you can use the debugger to track the values of variables and find the point at which the output deviates from the expected. customerItems[2]. if your program ends abnormally. customerItems[1].95. Debugging EGL applications 575 . If the program gives unexpected output.itemNumber=1. For example. 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.itemQuantity=10. customerItems[1].itemCost=200.50. you must step into the other logic part from a program. orderTotal float=0.Setting the default build descriptors Related reference helpKey remoteComType in callLink element sqlDB getVAGSysType() systemType sqlDataCode sqlID sqlPassword sqlJNDIName validationBypassKeys 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. customerItems[3]. customerItems[2].itemQuantity=60. customerItems[1].itemCost=49. counter int. customerItems[3]. but in general the heart of the debugging process is identifying the source of a problem in the code.itemNumber=3.itemNumber=2. customerItems[2].itemQuantity=30. 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. SysLib.division by zero discountRate = 1/0. double-click the gray margin to the left of the code in the EGL editor. When the debugger encounters a breakpoint. //Discount 20% for more than 50 items. customerItems[counter]. itemCost float. //Discount 5% for more than 20 items. you might want to add breakpoints throughout the discountPrice function because the error tells you that this 576 EGL Programmer’s Guide . end // function discountPrice end // program record items type BasicRecord itemNumber int. Your first step in identifying the source of the error might be to run the program in the debugger with breakpoints to find where the program fails. they are meaningful only during the debugging process.writeStderr("The total cost for the order is $" + orderTotal). itemQuantity int.getSize() by 1) orderTotal += discountPrice(customerItems[counter]. You then have the option of checking the current values of program variables before telling the debugger how to proceed. the error is easy to see. return (quantCost). In the previous example.itemCost. the number of items. Adding breakpoints You can mark one or more lines of code as breakpoints. quantCost = itemCost*itemQuantity*(1-discountRate). end // for loop //Write the output to the console. //Use the discountPrice function to get the discounted cost of each item. otherwise //bug . In this case. end //Multiply the cost of the item. //Determine the discount for each quantity. quantCost float=0. end // main //Return a total price for a group of items //based on the item price and a quantity discount. //and the discounted price. itemQuantity int in) returns(float) discountRate float=0. but in other cases you might not be able to find the error so easily. -2).itemQuantity). for (counter from 1 to customerItems.round(quantCost. quantCost = MathLib. end If you generate this program and run it. To add a breakpoint. when (itemQuantity > 20 && itemQuantity <= 50) discountRate = 1/20. function discountPrice(itemCost float in. it pauses before running the associated line of code. Breakpoints do not affect the generated source in any way. case when (itemQuantity > 50) discountRate = 1/5.//Calculate the total cost of the items. EGL will return an error pointing to the discountPrice function and the expression 1/0. From this point you can step through or around succeeding lines of code. v A call to a system function or other EGL function. Breakpoints are marked with blue circles in this gray area: You can add a breakpoint at most lines of EGL code that conduct logic. such as: myString = "Hello". v A loop or comparison statement. it has the same effect as setting a breakpoint at the first executable line inside the main() function of the program. including the following examples: v An assignment statement. or that begins with program. However. you cannot add breakpoints at the following lines of code: v A variable declaration that does not include an assignment. For more on the step commands. See “Setting preferences for the EGL debugger” on page 604. such as: if (myInt == 5) However. v A blank line or a line that consists only of a comment. such as: SysLib. You can debug a program without using breakpoints. Debugging EGL applications 577 .writeStderr("Hello"). you can set a preference to have the debugger treat the first line of each program as though it contained a breakpoint. see “Using breakpoints in the EGL debugger” on page 584. v A variable declaration that includes an assignment. package. such as: myInt int = 5.function is where the error occurred. v Any line within a data part. v An end statement. If you check the preference Window → Preferences → EGL → Debug → Stop at first line of a program. execute a single line and pause. that is. or any other line that declares a logic part. v A line of code that begins with function. For more instructions on using breakpoints. see “EGL debugger commands” on page 580. it continues until it encounters a breakpoint. 1. You can also use one of the Step buttons to see the program execute the next line and pause again. v The Variables view shows the value of all the variables in the current logic part. At this point. In the Project Explorer view. See “Creating a launch configuration in the EGL debugger” on page 588 for more information. Related concepts “Debugging EGL applications” on page 573 Rich UI debugging 578 EGL Programmer’s Guide . the debugger pauses and displays the following information: v The EGL editor highlights the line about to be executed. You can switch perspectives manually by clicking Window → Open Perspective → Other → Debug. From this view. When you want the debugger to continue. you can use the automatically created launch configuration. For most programs. v The Breakpoints view lists the breakpoints in the program. You can also change the value of a variable while the debugger is paused at a breakpoint. v The debugger begins running the program. v The Debug view lists the threads running within the current run unit. v Depending on your workbench preferences. this view shows which program or logic part is currently running. There are two ways to create a launch configuration: v Have the debugger to create a launch configuration automatically when you start debugging. After the debugger has started running the program. You can view this configuration by clicking Run → Debug. You can use this view to track the value of a variable through the program. or.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). finds the first line of executable code. the debugger might switch to the Debug perspective automatically or prompt you to do so. 4. The debugger requires a launch configuration to describe how it will run the application. you can run it in the debugger. you can run the program from breakpoint to breakpoint until the debugger reaches the line discountRate = 1/0. 2. The debugger continues to the next breakpoint. In simple terms. The debugger performs the following tasks: v If no launch configuration exists for the program. When you are finished debugging. right-click the EGL source program that you want to debug and then click Debug EGL Program. v Create a launch configuration manually. at which point the debugger returns the same error that you see in the console when running the program. the debugger creates a default launch configuration. click the Terminate button at the top of the Debug view to stop the debugger or allow the program to finish running. you can disable a breakpoint temporarily by clearing its check box. Use this view to resume or stop the debugging process. 3. including the value of system variables. if you have set the preference for it. click the Resume button at the top of the Debug view. In the example program.. You can manage breakpoints inside or outside of an EGL debugging session. see “Setting preferences for SQL database connections” on page 219. Adjust Java property values to conform to differences in accessing a relational database: v For J2EE. 2. Debugging EGL applications 579 . specify a connection URL like jdbc:db2:MyDB. specify a string like jdbc/MyDB. which is the name to which a data source is bound in the JNDI registry. you can use the launch configuration to debug the program in a non-J2EE context. You can specify that string in the following ways: – By setting the sqlDB build descriptor option. “Creating a launch configuration in the EGL debugger” on page 588 “Starting a non-JEE application in the EGL debugger” on page 590 “Using breakpoints in the EGL debugger” on page 584 This topic shows you how to use breakpoints in debugging your programs. Related concepts VisualAge Generator compatibility “Character encoding options for the EGL debugger” on page 603 “EGL debugger commands” on page 580 Related tasks “Setting preferences for SQL database connections” on page 219 “Setting preferences for the EGL debugger” on page 604 This topic tells you how to change your preferences for the EGL debugger. Set the value of the J2EE build descriptor option to NO when you use the launch configuration. see “Setting preferences for SQL database connections” on page 219. “Viewing variables in the EGL debugger” on page 585 This topic shows you how to view variables in your program while your are debugging your programs. in the Connection JNDI Name field. Debugging an EGL batch program If you are working on a batch program that you intend to deploy in a J2EE context. You can specify that string in the following ways: – By setting the sqlJNDIName build descriptor option. for details. see “How build descriptor settings affect the EGL debugger” on page 583. see “Secondary Authentication ID” on page 220.“EGL debugger commands” on page 580 Debugger Related tasks “Setting preferences for the EGL debugger” on page 604 This topic tells you how to change your preferences for the EGL debugger. For details. For more information on how build descriptor settings affect the EGL debugger. For information on Secondary Authentication ID. you need to adjust some values: 1. see “EGL debugger commands” on page 580. or – By placing a value in EGL SQL Database Connections preference page. in the field Connection URL. v For non-J2EE. For information on EGL debugger commands. or – By placing a value in the EGL SQL Database Connections preference page. Although the setup is straightforward. Run Runs the code until the next breakpoint. the function that you are in currently or a function that has called the current function. Run to line Runs all statements up to. 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. the statement on a specified line. You can jump only to a line in a function that is part of the currently active stack. or until the run unit ends. Enable breakpoint Activates a breakpoint that was previously disabled. unless you remove the breakpoint. Breakpoints are carried from one debugging session to the next. the debugger stops at the first statement in the main function. but does not remove it. This command is not available in Rich UI debugging. In any case. as well as the status of files and screens. Remove breakpoint Clears the breakpoint so that processing no longer automatically pauses at the line. This command is not available in Rich UI debugging. Disable breakpoint Inactivates a breakpoint. “Creating a launch configuration in the EGL debugger” on page 588 Setting the default build descriptors Related reference remoteComType in callLink element sqlDB getVAGSysType() systemType sqlID sqlPassword sqlJNDIName EGL debugger commands You can use the following commands to interact with the EGL debugger: Add breakpoint Identifies a line at which processing pauses. The following list indicates what happens if you issue the command step into for a particular statement type: 580 EGL Programmer’s Guide . Step into Runs the next EGL statement and pauses. you can examine variable values. Remove all breakpoints Clears every breakpoint. You cannot set a breakpoint at a blank line or at a comment line. When code execution pauses. that is. but not including.“Secondary Authentication ID” on page 220 “Stepping through an application in the EGL debugger” on page 575 This topic offers guidance on the basic steps of debugging a program in the EGL debugger. unless a breakpoint is in effect. 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). The new program can have a different set of properties from the program that ran previously. Step over Runs the next EGL statement and pauses. but not in a validator function. After either a show statement or a transfer to transaction statement. the debugger stops at the first statement in that program. The EGL debugger searches for the receiving program in every project in the workbench. Debugging EGL applications 581 . but is not generated by EGL. and then stops at the next running statement. The target program is EGL source code that runs in the EGL debugger. That input causes processing to stop at the next running statement. the build descriptor for the previous program remains in use. forward If the code forwards to a JSF Handler. transfer Stops at the first statement of the program that receives control in a transfer. function invocation Stops at the first statement in the function. which might be in a validator function. and the new program cannot have a different set of properties. If the code forwards to a program. forward If the code forwards to a JSF Handler. v In COBOL mode. (if no such build descriptor is in use. the EGL debugger switches to the build descriptor for the new program or. show. Stops at the statement that follows the converse statement. the debugger stops at the first statement in that program. but does not stop within functions that are invoked from the current function. Stops at the next statement in the current program if the called program runs outside of the EGL debugger. the debugger waits for user input and stops at the next running statement. the debugger waits for user input.call Stops at the first statement of a called program if the called program runs in the EGL debugger. If the code forwards to a program. prompts the user for a new build descriptor. converse Waits for user input. The EGL debugger searches for the receiving program in every project in the workbench. which might be in a validator function. the behavior of the EGL debugger depends on the debugger mode: v In Java mode. show. for example. the behavior is identical to that of a step into command. To continue the debug session in this case. the EGL debugger switches to the build descriptor for the new program or. issue another command. but a step into command merely continues to the subsequent statement.startTransaction() You can add a breakpoint at these statements. Related concepts “Debugging EGL applications” on page 573 Rich UI debugging Related tasks “Creating a launch configuration in the EGL debugger” on page 588 “Stepping through an application in the EGL debugger” on page 575 This topic offers guidance on the basic steps of debugging a program in the EGL debugger. or exit stack). 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. and the new program cannot have a different set of properties. v In COBOL mode. the build descriptor for the previous program remains in use. The EGL debugger ignores the following EGL system functions: v sysLib. In that case. The new program can have a different set of properties from the program that ran previously.audit() v sysLib. exit program. transfer Stops at the first statement of the program that receives control. but is not generated by EGL. which primarily means that the EGL debugger runs the next statement and pauses. 582 EGL Programmer’s Guide . The target program is EGL source code that runs in the EGL debugger. “Using breakpoints in the EGL debugger” on page 584 This topic shows you how to use breakpoints in debugging your programs.purge() v vgLib. prompts the user for a new build descriptor. if no such build descriptor is in use. The step return command in a validator function is an exception. Step return Runs the statements needed to return to an invoking program or function. with no other effect. processing pauses in the function itself so that you can review variables that are local to the function. 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. You can manage breakpoints inside or outside of an EGL debugging session. then pauses at the statement that receives control in that program or function. The EGL debugger searches for the receiving program in every project in the workbench. except that if you do not specify a build descriptor. see “Setting preferences for SQL database connections” on page 219. see Setting the default build descriptors.How build descriptor settings affect the EGL debugger A build descriptor helps to determine some aspects of the debugging environment. If you are debugging a program that you intend for use in a text or batch application in a Java environment. The generation-time status of VisualAge compatibility is determined by the value of the vagCompatibility build descriptor option. the build descriptor for the calling program remains in use. if you intend to access a VSAM file from a program that is written for a COBOL environment. For example. Otherwise. the EGL debugger prompts you to select from a list of your build descriptors. The choice of build descriptor is based on the rules described earlier. zOS) and must refer to a file type (for example. The choice of build descriptor is based on the rules that are described earlier. vsamrs) that is appropriate for the target system. 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. if you set the system type to DEBUG. you are likely to reference a resource association part in the build descriptor. NT. JavaScript (for Rich UI). Debugging EGL applications 583 . the system name must reflect another naming convention. see your VSAM support documents. or XP. For details on how to set those preferences. the debugger does not prompt you for a build descriptor when the called program is invoked. v If the build descriptor you specified lacks any required database-connection information. the EGL debugger gets the connection information by reviewing your preferences. The mode controls how the debugger acts in situations where the EGL runtime behavior differs for JavaScript. then the mode is set to Java automatically. 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. For details on how to establish the debug build descriptor. and COBOL output. v If you did not specify a debug build descriptor. v At debug time. Java. for details on that naming convention. The resource association part must refer to the runtime target system (for example. For example. the system build descriptor option determines which mode the EGL debugger will run in. The debugger has three modes. the resource association part indicates the system name of the file that is used in the target environment. the EGL debugger uses a build descriptor that is assigned to the receiving program. 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. 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 the build descriptor that is assigned to the called program. instead. For details on Rich UI. the EGL debugger uses that build descriptor. Java. and COBOL. see Rich UI debugging. If you are debugging a program that is called by another program. as appropriate when you access a remote VSAM file from an EGL-generated Java program on Windows 2000. The debug situation differs from the generation situation as follows: v At generation time. systemType. Also. The value in sysVar. 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.getVAGSysType if you requested development-time compatibility with VisualAge Generator). You can manage breakpoints inside or outside of an EGL debugging session. 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. “Creating a launch configuration in the EGL debugger” on page 588 Setting the default build descriptors Using breakpoints in the EGL debugger This topic shows you how to use breakpoints in debugging your programs. For details.getVAGSysType system function returns the VisualAge Generator equivalent of the value in sysVar. as mentioned in “Setting preferences for the EGL debugger” on page 604. Related concepts VisualAge Generator compatibility “Debugging EGL applications” on page 573 Rich UI debugging Related tasks “Setting preferences for SQL database connections” on page 219 “Setting preferences for the EGL debugger” on page 604 This topic tells you how to change your preferences for the EGL debugger. The vgLib.System type used at debug time In addition to the system build descriptor option. see the table in getVAGSysType(). You can manage breakpoints inside or outside of an EGL debugging session. except that the value is DEBUG in either of two cases: v You select the preference Set systemType to DEBUG. 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.systemType is the same as the value of the system build descriptor option. 584 EGL Programmer’s Guide . or v You specified NONE as the build descriptor to use during the debugging session. regardless of the value of that preference. v The absence of a marker in the left margin indicates that a breakpoint is not set. a second value is available in vgLib. v A white marker in the left margin of the Source view indicates that a breakpoint is set but disabled.systemType. a value for system type can be set in sysVar. 2. Viewing variables in the EGL debugger This topic shows you how to view variables in your program while your are debugging your programs. “Viewing variables in the EGL debugger” This topic shows you how to view variables in your program while your are debugging your programs. 2. Click Remove All. you will probably have the debugger stop or pause at certain points in your program (see “Using breakpoints in the EGL debugger” on page 584 for more information on using breakpoints to make the debugger pause while debugging your program). follow these steps: 1. you can view the current values of the variables in the program. A menu opens. Disabling or enabling a breakpoint To disable or enable a single breakpoint in an EGL source file. Related concepts “Debugging EGL applications” on page 573 Rich UI debugging Related tasks “Creating a launch configuration in the EGL debugger” on page 588 “Starting a non-JEE application in the EGL debugger” on page 590 “Stepping through an application in the EGL debugger” on page 575 This topic offers guidance on the basic steps of debugging a program in the EGL debugger. In the Breakpoint view. Click either Add or Remove (The Remove option is only there if a breakpoint is already set). 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. Whenever a program is paused. Click either Enable or Disable. To display their values. A menu opens. Displaying and changing values You typically use the Variable view to monitor the changing values of your variables. Remove all breakpoints To remove all breakpoints from an EGL source file. follow these steps: 1.v Position the cursor at the breakpoint line in the left margin of the Source view and right-click. right-click on the breakpoint. do one of the following: Debugging EGL applications 585 . Right-click any breakpoint that is displayed in the Breakpoints view. A menu opens. The Variables view will split into two panes. Horizontal View Orientation The detail pane is displayed to the right of the variables. you can request a column that shows the variable type. v Click the Options button at the top of the view (the triangle). For more information. right-click the value and choose the appropriate option from the popup menu. choose Layout → Show Columns → Value. The wording of the option varies depending on the context. and then click Layout and either Horizontal View or Vertical View. [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. The Variables view provides the following buttons: Show Type Names This toggle displays or hides the types on which the variables are based. see ″Buttons in the Variables view″ in this topic. or right-click and choose Change Value to display a window where you can change the value. If you do not see the Value column. 586 EGL Programmer’s Guide . Also on the Options menu. then click Layout → Show Columns. Show Columns This option reformats the view in table form Select Columns This option is only available if you select Show Columns. Value The current value of the variable. one showing the current value of the variable. Buttons in the Variables view In the Variables view. expand the parts in the navigator to see the variables that are associated with them. Show Logical Structure Collapse All This hides all the variable names and shows only the parts in the current program. The following columns are available: Name The name of the variable. In that case. Declared Type The original type of the variable. Click this cell to enter a new value for the variable. To change a value. choose Detail pane.v Click the Options button at the top of the view (the triangle). Variables View Only This option closes the detail pane. This button is not available if you chose to show columns. Related concepts “Debugging EGL applications” on page 573 Rich UI debugging Related tasks “Creating a launch configuration in the EGL debugger” on page 588 “Starting a non-JEE application in the EGL debugger” on page 590 “Configuring a server for EGL Web debugging” on page 592 “Using breakpoints in the EGL debugger” on page 584 This topic shows you how to use breakpoints in debugging your programs.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. 2. and select Assign Value to assign the value to the variable. which means that the debugger processes the code changes that you make as you step through an application. The Preferences page is displayed. “EGL debugger commands” on page 580 Rich UI debugging Related tasks Debugging EGL applications 587 . Making code updates while debugging an application The EGL debugger supports hotswapping. right-click. The Debug dialog box is displayed. Compatibility considerations for hot swapping Platform Rich UI Issue Hot swapping is not supported. Compatibility Table 57. From the main menu. If hotswapping is enabled and you change a function that is on the function stack. To take advantage of this feature. Similarly. You can manage breakpoints inside or outside of an EGL debugging session. Expand EGL and click Debug. the debugging session continues at the first line of the changed function. set the Enable hotswapping EGL debug preference: 1. click Window → Preferences. Click Enable hotswapping. You can type a value for the variable in this pane. the EGL debugger does not respond to changes made to variable values in the Variables view. 3. Show All Jython Variables This option does not apply to EGL. Related concepts “Starting the EGL debugger for EGL projects” on page 588 Start the debugging process by creating a launch configuration. Detail pane This option opens a separate pane in the Variables view to display the details of a highlighted variable. Click OK to save the changes and exit the page. 4. Hotswapping lets you to test and modify your application at the same time. highlight that value. type a name for the launch configuration. follow these steps: 1. By default. The Debug window opens. see “Creating an EGL Listener launch configuration” on page 589. To create a launch configuration yourself. You can create a launch configuration yourself. 588 EGL Programmer’s Guide . see “Creating a launch configuration in the EGL debugger. To create one. select the program that you want to debug. In the EGL program source file field. or Rich UI handler in an EGL debugging session. To start a program using a launch configuration that you create yourself. In relation to automatic configurations. In the Project field of the Load tab. In the left pane of the Debug window. see “Starting a non-JEE application in the EGL debugger” on page 590. the launch configuration has the same name as the program. or you can have the EGL application create one for you automatically. 6. 3. Click the New launch configuration at the top of that same pane. but the EGL debugger creates one automatically if you do not create one. type the name of your project. “Creating a launch configuration in the EGL debugger” Setting the default build descriptors Starting the EGL debugger for EGL projects Start the debugging process by creating a launch configuration. To start the debugging process outside of Rich UI you need a launch configuration. “Stepping through an application in the EGL debugger” on page 575 This topic offers guidance on the basic steps of debugging a program in the EGL debugger. you must create a special kind of launch configuration called an EGL Listener launch configuration. 4. see Starting a non-JEE application in the EGL debugger or Rich UI debugging. unless a configuration already exists for this program. Related concepts Rich UI debugging Related tasks “Starting a non-JEE application in the EGL debugger” on page 590 “Creating a launch configuration in the EGL debugger” “Creating an EGL Listener launch configuration” on page 589 Creating a launch configuration in the EGL debugger To start debugging an EGL text program. A new launch configuration is displayed below the EGL Program heading. To start the EGL debugger and have it create a launch configuration for you. click EGL Program.” If you are debugging an EGL application that is called from an EGL-generated Java application or Java wrapper. Click Run → Debug. In the Name field. you need to establish a launch configuration.“Setting preferences for the EGL debugger” on page 604 This topic tells you how to change your preferences for the EGL debugger. The Launch tab is initially displayed. non-JEE basic program. You can create a launch configuration yourself. 2. 5. “Viewing variables in the EGL debugger” on page 585 This topic shows you how to view variables in your program while your are debugging your programs. in order. otherwise. specify the paths for those classes on the Classpath tab. 7. 13. 12. then click the New launch configuration button. If you do not type a port number. Click the arrow next to the Debug button on the toolbar. Click EGL Listener in the Configurations list. in order. Each EGL Listener requires its own port. 10. type a port number. click the JRE tab and complete the information there. 9. click the Arguments tab. You can manage breakpoints inside or outside of an EGL debugging session. 4. Creating an EGL Listener launch configuration To debug a non-JEE EGL application called from an EGL-generated Java application or wrapper. click the Arguments tab. To set environment variables for the duration of the debug session only. If you need additional Java classes to run the program. the port defaults to 8346. type the new name in the Name field. Click Apply to save the launch configuration settings. List the arguments for the program. If you are debugging a called program that takes arguments. If you are debugging a called program that takes arguments. List the arguments for the program. type the names and values on the Environment tab. clicking Revert will remove all changes that you have made. as you would in a call statement. 11. “Using breakpoints in the EGL debugger” on page 584 This topic shows you how to use breakpoints in debugging your programs. If you need to use a different JRE than the default for this project. do as follows: 1. 3. If you want to change the name of the launch configuration. The Debug dialog box is displayed. Related concepts “Debugging EGL applications” on page 573 Rich UI debugging Related tasks “Starting a non-JEE application in the EGL debugger” on page 590 “Stepping through an application in the EGL debugger” on page 575 This topic offers guidance on the basic steps of debugging a program in the EGL debugger. Debugging EGL applications 589 . as you would in a call statement.7. click the JRE tab and complete the information there. The Listener launch configuration is named New_configuration. 2. To create an EGL Listener launch configuration. If you need to use a different JRE than the default for this project. then click Debug. 8. Click Debug to launch the program in the EGL debugger. an EGL Listener launch configuration is required. or select Debug from the Run menu. 5. Add any needed source files on the Source tab. Note: If you have not yet clicked Apply to save the launch configuration settings. 6. do as follows: 1. A launch configuration specifies the location of a program on disk and specifies how the program must be launched. A menu opens. 2. Click Apply to save the Listener launch configuration. You can manage breakpoints inside or outside of an EGL debugging session. To set environment variables for the duration of the debug session only. “Viewing variables in the EGL debugger” on page 585 This topic shows you how to view variables in your program while your are debugging your programs. you can right-click the program in the Outline view. Note: You can also display the Debug dialog by clicking Run → Debug. right-click the EGL source file that you want to launch. do as follows: 1. 2. To launch a program using an implicitly created launch configuration. Alternatively. “Using breakpoints in the EGL debugger” on page 584 This topic shows you how to use breakpoints in debugging your programs. and the program is launched in the EGL debugger. Starting a non-JEE application in the EGL debugger To start debugging an EGL text program or non-JEE basic program in an EGL debugging session. A pop-up menu displays. To view the implicitly created launch configuration. Add any needed source files on the Source tab. Click Debug. Click the arrow next to the Debug button on the toolbar. Related concepts “Debugging EGL applications” on page 573 Rich UI debugging 590 EGL Programmer’s Guide . specify the paths for those classes on the Classpath tab. The name of the launch configuration is displayed in the Name field.8. In the Project Explorer view. 12. a launch configuration is required. The Debug dialog displays. if the EGL source file is open in the EGL editor. If you need additional Java classes to run the program. Implicitly created launch configurations are named according to the project and source file names. type the names and values on the Environment tab. Click Debug EGL Program. 9. Click Debug to launch the EGL Listener. or you can create one yourself (see “Creating a launch configuration in the EGL debugger” on page 588). 10. A launch configuration is created. You can let the EGL application create the launch configuration (implicit creation). Related concepts “Debugging EGL applications” on page 573 Rich UI debugging Related tasks “Creating a launch configuration in the EGL debugger” on page 588 “Starting a non-JEE application in the EGL debugger” “Stepping through an application in the EGL debugger” on page 575 This topic offers guidance on the basic steps of debugging a program in the EGL debugger. 11. The default port number is 8346. Programs running in JEE To invoke the EGL debugger from an EGL-generated program or wrapper that runs in JEE. Start a listener by using an EGL Listener launch configuration that has only one configurable setting. Invoking the EGL debugger from generated Java code You can invoke the EGL debugger from an EGL-generated Java program or wrapper. including on a remote system. To specify a different port number. you must associate the wrapper with a callLink element. Edit the callLink element to include the remoteComType property. see remoteComType in callLink element. You can manage breakpoints inside or outside of an EGL debugging session. In either case. Start a listener program. Make sure you have added a linkage options part to your build file. “Viewing variables in the EGL debugger” on page 585 This topic shows you how to view variables in your program while your are debugging your programs. If multiple EGL Listeners are running at the same time. follow these steps: 1. For details on setting the remoteComType property. so you can use the EGL debugger when you work on a partly deployed application. 2. 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. the caller of the program might be running anywhere. “Using breakpoints in the EGL debugger” on page 584 This topic shows you how to use breakpoints in debugging your programs. you must specify a different port for each EGL Listener. 3. Add the EGL debugger JAR files to the server. Make sure that the program to be debugged is running in the same server as its caller. 4. To edit the callLink element. the element must specify the remoteComType property as DEBUG. The program needs a call statement that you then associate with the callLink element of a linkage options part. Run the program in the debugger.Related tasks “Creating a launch configuration in the EGL debugger” on page 588 “Stepping through an application in the EGL debugger” on page 575 This topic offers guidance on the basic steps of debugging a program in the EGL debugger. Programs not running in JEE Different rules apply when the called program to be debugged does not run in JEE. When this is the case. Make sure the server is running in debug mode. Similarly. 5. 2. Related tasks Debugging EGL applications 591 . see Adding a linkage options part to an EGL build file. For instructions on how to do this. Follow these steps: 1. see Editing the callLink element of a linkage options part. see “Creating an EGL Listener launch configuration” on page 589. a port number. edit the VM arguments section of the launch configuration (Run → Debug). Do this by passing the property as a VM argument to the server. as in the following figure: 592 EGL Programmer’s Guide . If you want to debug generated Java code instead. right-click the server name and choose Restart → Start. 3. do as follows: 1. make sure that you request EGL debugging support at the time you define the new server to EGL.″ and the server is not running.jsfhandler. If the server is running. Related concepts “Debugging EGL applications” on page 573 Rich UI debugging Related tasks “Configuring a server for EGL Web debugging” “Starting an EGL Web debugging session” on page 594 Configuring a server for EGL Web debugging Before you can debug EGL Web applications. To begin debugging. you must set the egl. This process will restart the server in Debug mode. If you use Tomcat. To configure a server for EGL debugging. On Apache Tomcat. The Status column of the display says ″Debugging″ when the server is running in EGL debug mode. This needs to be done only once. find or open the Server view (Window → Show View → Other → Server → Servers). If you want to debug generated Java code rather than the EGL JSF handler. 2. If Status column does not report ″Debugging. In the Debug perspective. see Starting an EGL Web debugging session. right-click the server name and click Restart → Debug. Before you can debug an EGL Web application. see Configuring a server for EGL debugging. To take the server out of EGL debug mode. you must configure the server for debugging. Debugging Java code EGL assumes that you want the server to debug EGL JSF Handler parts. you must configure the server for EGL debugging. Methods for doing this depend on which server you are running. EGL Debug is the default debugging mode. You need to do this configuration step only once per server.“Creating an EGL Listener launch configuration” on page 589 Debugging Web projects with the EGL debugger Use the EGL debugger to debug Web projects. see ″Debugging Java code″ later in this topic.debug system property to FALSE. right click the server name and choose Debug from the pop-up menu. Right-click the server name in the Server view and choose Run administrative console. version 6.1. and click Application servers. expand Servers.jsfhandler. The console displays a list of servers. On the Configuration tab of the next page.Restart the server for the property to take effect. In the left menu pane of the Integrated Solutions Console. For IBM WebSphere Application Server. Under this heading. On the Debugging Service page. add the following (with a space afterwards) to the beginning of the string in JVM debug arguments: -Degl. the process is more complicated. click yours. click Debugging Service.debug=false That area of the console looks like the following figure: Debugging EGL applications 593 . the last group of options is headed Additional Properties. as explained in “Debugging Web projects with the EGL debugger” on page 592. In the Project Explorer for the EGL perspective. Right-click the JSP file that you 594 EGL Programmer’s Guide . Restart the server for the property to take effect. The console will ask you if you want to Save or Review your changes.Click Apply to save your changes. To start debugging an EGL Web application. click Save. expand the WebContent/WEB-INF folder for your project. and you must have started your server in Debug mode (see “Configuring a server for EGL Web debugging” on page 592). Starting an EGL Web debugging session Before you follow the instructions in this topic. follow these steps: 1. you must have generated each JSF Handler that you want to debug at least once. Related concepts “Debugging EGL applications” on page 573 Rich UI debugging Related tasks “Starting an EGL Web debugging session” “Stepping through an application in the EGL debugger” on page 575 This topic offers guidance on the basic steps of debugging a program in the EGL debugger. 4. Prerequisites You will need an EGL Service part. The easiest way to make the debugger use the updated code is to generate the parts that you have changed. Related concepts “Debugging EGL applications” on page 573 Rich UI debugging Related tasks “Configuring a server for EGL Web debugging” on page 592 “Stepping through an application in the EGL debugger” on page 575 This topic offers guidance on the basic steps of debugging a program in the EGL debugger. The easiest way is to hard code the input values in the service call and write the output values to the console. Create a service client binding in the deployment descriptor as an EGL service (not a Web service) with a ″local″ protocol. Debugging services with the EGL debugger You can debug your local EGL services similarly to the way that you debug other programs. bind the variable to the service with {@BindService{bindingKey = "ServiceClientBindingName"}}. you must generate the service. For an overview of this process. In the main() function of the program. 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. Note that before you can debug a Web service on WebSphere Application Server. and start the application. as well as a requester that has binding information for accessing the service. see “Stepping through an application in the EGL debugger” on page 575. but you can also restart the server or restart the project on the server. 3. EGL will change to the Debug perspective. 3. make at least one call to the service using that variable. See “Calling a local service” on page 483 for instructions. Using the service client binding. You can then pass test values to the service and inspect the results. deploy the application to the server. 2. Perform the following steps: 1. As you find bugs and correct your EGL code. declare a service variable that is based on the Service part that you want to test.want to run and then select Debug As → Debug on Server from the pop-up menu. In the program. Begin debugging the application. Create a new EGL source program. 2. 5. as in the following example: program addTestProgram type BasicProgram myAddingMachine additionService Debugging EGL applications 595 . make sure that the debugger picks up the changes and continues debugging with the updated code. The debugger makes database calls to the host. The debugger pauses at the breakpoints in the service just as in any other logic part. SysLib.7 or higher – Open Database Access (ODBA) v Resource Recovery Services (RRS) v Workload Manager (WLM) The IMS debugger uses ODBA to talk to the database capabilities in IMS. “Stepping through an application in the EGL debugger” on page 575 This topic offers guidance on the basic steps of debugging a program in the EGL debugger. Debugging IMS and DL/I applications Debugging applications that run remote IMS programs or that access data from a DL/I database requires configuration of both the host and the local workspace. Debugging SQL and DL/I programs is available for IMS only. See “Using breakpoints in the EGL debugger” on page 584. At the breakpoint before the service call. step into the service code. Related concepts “Debugging EGL applications” on page 573 Rich UI debugging Related tasks “Calling a local service” on page 483 You can call an EGL or native service that is local to your application without exposing that service as a Web service. 12). You can manage breakpoints inside or outside of an EGL debugging session. For information on starting the debug server. OS/390® Release 3 is the minimum level that can support the ODBA interface. as you would in any logic part.{@BindService {bindingKey = "additionService"}}. sumint = myAddingMachine.7 or higher v IMS v. RRS/MVS (Resource Recovery Services) is required. “Using breakpoints in the EGL debugger” on page 584 This topic shows you how to use breakpoints in debugging your programs. Set a breakpoint at the service call. 8. 7.addInts(5. Set breakpoints in the service. end end 6.writeStdOut("result = " + sumint). 596 EGL Programmer’s Guide . but otherwise interprets the code on the local client system. see “Starting the DLI Debug Server on the z/OS host” on page 601. Prerequisites The following applications are required on the host for debugging: v TCPIP v DB2 v. function main() sumint int. Debug your new EGL source program. V6R0M1. Replace ELA.Host configuration The following areas need to be configured on the host system: v DRA (Database Resource Adapter) Startup Table (ELADRA) v WLM (Workload manager) (ELADBWLM) v DB2 stored procedure (EZESP1CR and EZESP1GR) v Proxy startup JCL (ELADBGPX) v Debug server startup JCL (ELADBGRN) Sample files are provided.SELAJCL and ELA. XXXX represents the DB control id. Table 58.V6ROM1. See IMS 7 Administration Guide System for information on configuring IMS security. The value comes from the JCL that you use to start IMS. (FPBUF+FPBOF)*MAXTHREAD ** FPBUF is the number of buffers to be allocated to each thread for FP use.SDFSRESL MAXTHRD=99 CNBA=0 FPBUF=0 FPBOF=0 TIMEOUT=60 The PDS SDFSRESL for your system. The source files in this section are available as part of the Rational COBOL Runtime for zSeries package. DRA Startup Table The following table lists the changes you need to make to the ELADA. Replace #dbctlid with the DB control id for your database.JCL file. ** FPBOF is the number of buffers and overflow buffers to be allocated to each thread for FP use. The IMS JCL parameter should look like this: IMSID XXXX IMS SUBSYSTEM IDENTIFIER In this example. Changes to ELADRA.SELASAMP. This value also goes into the imsID build descriptor option. AGN=IVP //SYSLMOD DD DSN=ELA.SELADBGL with the PDS where you want the DRA startup to reside.JCL From To Add a jobcard SYSLIB #dbctlid Modify to match your system configuration. Replace 99 with the max number of simultaneous debug sessions (the minimum is 3). All JCL and SQL samples are located in the COBOL runtime in ELA. preferably longer than longest running UOR. respectively.V6R0M1. Replace DFSIVP10 with DFS followed by #dbctlid from above. IMS.SELADBGL NAME DFSIVP10(R) Debugging EGL applications 597 . ** Set the TIMEOUT startup parameter as high as possible. the member names are shown above inside parentheses.V6ROM1. DISP=SHR //SYSUT1 DD UNIT=SYSDA.V6R0M1.400)) //SYSPUNCH DD DSN=&&OBJMOD. // PARM='DECK.. USERID=.DYNAMNBR=10. // DCB=(RECFM=FB.SDSNEXIT // DD DISP=SHR. TIMEOUT=60.NOOBJECT.100)) //SYSPRINT DD SYSOUT=* //SYSIN DD * PZP TITLE 'DATABASE RESOURCE ADAPTER STARTUP PARAMETER TABLE' DFSIVP10 CSECT ********************************************************************** * MODULE NAME: DFSIVP10 * * DESCRIPTIVE NAME: DATABASE RESOURCE ADAPTER (DRA) * * STARTUP PARAMETER TABLE.REGION=&RGN.(400. // SPACE=(400.SPACE=(1700.DISP=SHR // DD DSN=SYS1.TIME=NOLIMIT.SDFSRESL.APPLENV=ELADBWLM. // DD DDNAME=SYSIN //SYSIN DD * NAME DFSIVP10(R) X X X X X X X X X X X X X Workload manager You must create a dedicated WLM for IMS debugging. DDNAME=. MINTHRD=2. SOD=A.400)) //SYSUT2 DD UNIT=SYSDA.ALIGN'.50)) //SYSPRINT DD SYSOUT=* //SYSLMOD DD DSN=ELA. FPBUF=5.SELADBGL.DISP=SHR // DD DSN=IMS.UNIT=SYSDA.&NUMTCB. FPBOF=3.DISP=SHR //SYSLIN DD DISP=(OLD..(100.DB2SSN=#db2ssn.DELETE).' //STEPLIB DD DISP=SHR. // PARM='LIST.DSN=#db2.(100. ETC.LIST.NUMTCB=8 //* //SYMBOLS INCLUDE MEMBER=$INCLUDE //* //IEFPROC EXEC PGM=DSNX9WLM.DSN=#db2.(400. AND LINKEDITED * * INTO THE USER RESLIB AS DFSPZPXX.LET. * * FUNCTION: TO PROVIDE THE VARIOUS DEFINITIONAL PARAMETERS * * FOR THE COORDINATOR CONTROL REGION.MACLIB. // DISP=(. OR ANY OTHER ALPHA..SPACE=(1024.XREF(SHORT). DBCTLIB=#dbctlid. * ********************************************************************** EJECT DFSPRP DSECT=NO. THIS * * MODULE MAY BE ASSEMBLED BY A USER SPECIFYING * * THEIR PARTICULAR NAMES. In the JCL. TIMER=60.SPACE=(1700.OPTIONS.* * NUMERIC CHARACTERS. AGN=IVP END //LNKEDT EXEC PGM=IEWL. CNBA=10.PASS).SDSNLOAD 598 EGL Programmer’s Guide .DSN=&&OBJMOD. MAXTHRD=99.NCAL' //SYSUT1 DD UNIT=SYSDA. DSNAME=IMS.LRECL=80.XREF.400)) //SYSUT3 DD UNIT=SYSDA. change the STEPLIB to match your system configuration: //ELADBWLM PROC RGN=0K.(400.//ASM EXEC PGM=IEV90. // PARM='&DB2SSN..BLKSIZE=400). WHERE XX * * IS EITHER 00 FOR THE DEFAULT.SDFSMAC. // REGION=4096K //SYSLIB DD DSN=IMS.&APPLENV.SPACE=(1700. BELOW)' Change the placeholders to values that are appropriate to your system: schema The schema where the stored procedure is to be installed.sql makes a DL/I database available to the debugger: CREATE PROCEDURE schema.1)) //SYSUT6 DD UNIT=SYSDA.(1. v Make sure you have a functioning default JDBC DB2 connection to the host.SPACE=(CYL.SCEERUN // DD DISP=SHR. INOUT VAR04 VARCHAR(32672) FOR BIT DATA ) EXTERNAL NAME EZESP1 LANGUAGE COBOL PARAMETER STYLE GENERAL NOT DETERMINISTIC COLLID collid WLM ENVIRONMENT eladbwlm RUN OPTIONS 'ALL31(OFF) STACK(.1)) Stored procedure definition You need a SQL stored procedure to access a database on the host for EGL debugging.1)) //SYSUT4 DD UNIT=SYSDA.1)) //SYSUT5 DD UNIT=SYSDA.1)) //SYSUT3 DD UNIT=SYSDA.DSN=#cobol.SPACE=(CYL.SELALMD // DD DISP=SHR.SPACE=(CYL.EZESP1 ( IN VAR01 SMALLINT.SEZATCP. SQL for creating the stored procedure and granting access to all users can be found with the EGL runtime samples PDS.sql grants all users access to EZESP1CR. The actual . The stored procedure EZESP1CR. Debugging EGL applications 599 .SPACE=(CYL.SPACE=(CYL.SPACE=(CYL.1)) //SYSUT7 DD UNIT=SYSDA.(1.EZESP1 TO PUBLIC Local workspace configuration Take the following actions in your local workspace to enable remote debugging: v In Window → Preferences → EGL → Debug.// DD DISP=SHR.V6R0M1.(1.sql: GRANT EXECUTE ON PROCEDURE schema. The stored procedure EZESP1GR.1)) //SYSUT2 DD UNIT=SYSDA.(1. INOUT VAR03 VARCHAR(32672) FOR BIT DATA. eladbwlm The name of the workload manager that you specified earlier.(1. This will force EGL to use the systemType from the build descriptor option.(1. uncheck the option Set systemType to DEBUG. collid The collection ID for your system..DSN=ELA.DSN=&HLQTCP.(1. //ELAPRINT DD SYSOUT=* //SYSTSPRT DD SYSOUT=* //CEEDUMP DD SYSOUT=* //SYSMDUMP DD SYSOUT=* //SYSABEND DD DUMMY //******************************************************************** //* WORKFILES FOR COMPILERS AND BINDER //******************************************************************** //SYSUT1 DD UNIT=SYSDA.DSN=#cee..SIGYCOMP // DD DISP=SHR. the EGL debugger uses this connection to access DL/I.jar files you need depend on the version of JDBC that you are running. IN VAR02 INT. v You must have JDBC on the client system.SPACE=(CYL. expand EGL Developer and select the EGL DLI check box. go to Window → Preferences → General → Capabilities and click Advanced. the Default JDBC connection must be set to NOAUTOCOMMIT. For each called program that performs database access (DL/I or SQL) add an entry and set mapping mode to IMS debug.psbData The default for CICS. ProxyIdleTimeout The amount of time the proxy will sit idle (no DLI activity) before the debugger server tells it to abort. but short enough that you don’t use up all available processes in case the connection drops repeatedly.v If you access a DB2 database in both the debugged code and in a called program. v Make sure you have a preference page for IMS DLI under Window → Preferences → EGL → Debug. ConversionTable Defines the language of the host. v Set the imsID build descriptor option to the CHAR(4) name of your IMS subsystem. The program still uses a DL/I property for transaction commit/rollback determination. This is the same table used in call linkage conversion. HostPort The number of the port where the debugger server is listening. With the ODBA interface. v If you run called programs on the host. Prompt At the start of each debug session. enter the following information StoredProcedureSchema The schema that contains the stored procedure. go to Window → Preferences → EGL → Debug → Debug Behavior Mapping → Called program mapping. v On the IMS DLI debug preferences page (see previous step). the PCB must be named and must match at PCB in the PSB defined either in the program for IMS or in dliLib. PSB Name Three options are available: dliLib. This should be long enough to allow for processing time. If not. or the program name. This is either the value of the alias property (if used). but the PSB name comes from the psbData record in dliLib. This value is folded to upper case. the user is prompted to enter the PSB name used to access DL/I data. Main program The default for IMS.psbData for CICS. In the Advanced window. Related concepts “Debugging EGL applications” on page 573 “How build descriptor settings affect the EGL debugger” on page 583 “Starting the DLI Debug Server on the z/OS host” on page 601 600 EGL Programmer’s Guide . Close and reopen the Preferences window to see the IMS DLI debug page. If the queue is full. //STEPLIB DD DSN=ELA. keyword will //* be replaced by parameters. The default is 1.DYNAMNBR=30. causing unpredictable results. the build server queues any additional requests and submits them on a first come first served basis as builds are completed. -q Specifies the size of the queue (q) for clients.TIME=NOLIMIT. Set n equal to the number of concurrent builds you want to allow. The &PARM. Therefore setting this too high may require more sockets than are available. //jobcard //*-----------------------------------------------------//RUNPGM EXEC PGM=EZEDBPXY. the server ignores them and the build transaction is performed under the access and authority of the user ID assigned to the build server job. If you specify a TSO user ID and password. you can configure the debug server to debug IMS DLI. Syntax You start a debug server by using z/OS JCL commands. The default is 10. -t Starts tracing of this server job and writes output to STDOUT. This parameter is normally used only for debugging. Each queued client uses a TCP/IP socket.DISP=SHR // DD DSN=ELA. However. The syntax for the parameters line is as follows: // PARM = ' -p portno -a -V 0 -n n where -q q -t ' -p Specifies the port number (portno) to which the server listens to communicate with the clients. -V Specifies the verbosity level of the server. The JCL to start a proxy on the host is contained in the file named EZEDBGPX. // PARM='&PARM. You may specify this parameter up to three times (maximum verbosity). -a Specifies authentication mode: 0 Server state: A or U (unauthorized).JCL.' //* Avoid changing the PARM statement.SELADBGL.Starting the DLI Debug Server on the z/OS host On z/OS. Procedure Modify the proxy job JCL to match your system configuration.SELALMD.V6R0M1. You must modify the STEPLIB portion of the JCL to match your system configuration.SDFSRESL Debugging EGL applications 601 . Once there are n number of concurrent builds running. -n Specifies the number of concurrent builds. the build client retries the build in that case. If U. APF-authorized build programs will fail. subsequent clients are rejected by the server.V6R0M1.DISP=SHR // DD DSN=IMS. Add a job card. the build script can specify only non-APF authorized programs as executables.REGION=7400K. 4. (See the parameter list above. complete the following steps with the ELADBGRN. Modify the STEPLIB DD statement to point to the data set that contains the build server load modules. If the server is not started from an APF-authorized library. USA French German ptb chs cht enu fra deu Code 602 EGL Programmer’s Guide . 5. in a multistep JCL script. Note: In this case. Example Following is an example of JCL that starts the debug server as a batch program for IMS debugging: //jobcard //*-----------------------------------------------------//RUNPGM EXEC PGM=ELAMAIN.V6R0M1. Submit the job.DSN=ELA.) 3. 6. Modify the parameter (PARM=) statement as appropriate for your job (see example below).//* //STDOUT //STDERR //CCUBLOG DD SYSOUT=* DD SYSOUT=* DD SYSOUT=* To start a z/OS debug server.JCL: 1. the build script can also specify non-APF authorized programs.V6R0M1. Modify the ELADBGP DD statement to point to the data set that contains the JCL to run an individual debug proxy job. Modify the parameters on the PARM statement of the EXEC card as necessary. This library contains all the load modules that make up the remote build server. Language Brazilian Portugese Chinese.SELAJCL(ELADBGPX) //STDOUT DD SYSOUT=* //STDERR DD SYSOUT=* //CCUBLOG DD SYSOUT=* Special considerations for debugging If you start the server on z/OS from an APF-authorized library (this is optional in mode 0). traditional English. // PARM='-p 5527 -a 0 -n 10 ' //STEPLIB DD DSN=ELA.DISP=SHR //ELADBGP DD DISP=SHR. However. English is the default. 2. an authorized program cannot be executed after an unauthorized program. the build script can specify an APF authorized program as the executable.SELALMD. Setting the language of messages returned from the build server The debug server on z/OS returns messages in any of the languages listed in the next table. 5. simplified Chinese. for example. how it compares character data. The value of CCU_CATALOG is a string like the following (on a single line): shared_resources\eclipse\plugins \com. the components that invoke the build server may need to issue messages if communication with the build server fails.0. use the one with the most recent version number. To change these options. If you installed and kept a previous version of an IBM product containing EGL before installing your current product. and the date and time that the plugin was built. change the setting of the environment variable CCU_CATALOG on the client machine. see Setting preferences for the EGL debugger. unless you have a reason to use an older version. 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). and how it passes parameters to remote programs. for example. files. you may need to specify the shared resources directory that was set up in the earlier install. Character encoding options for the EGL debugger When you use the EGL debugger outside of Rich UI.0.etools. change the setting of environment variable CCU_LANG on the client machine. a string separator.cat. and databases. The variable contains one of the language codes listed in the previous table. To return those messages in a language other than English. including three numbers separated by periods.distributedbuild_version\executables\ccu. Character encoding controls how the debugger represents character and numeric data internally.egl. To return messages in French. xxx The code for the language of interest. you can specify the type of character encoding to use while debugging. such as C:\Program Files\IBM\SDP70Shared on a Windows system or /opt/IBM/SDP70Shared on a Linux system. Also.xxx shared_resources The shared resources directory for your product.Language Italian Japanese Korean Spanish ita jpn kor esp Code To cause debug-server messages to be returned in a language other than English.ibm. 7. If more than one is present. one of the codes listed in the previous table Related tasks “Debugging IMS and DL/I applications” on page 596 Debugging applications that run remote IMS programs or that access data from a DL/I database requires configuration of both the host and the local workspace. version The installed version of the plugin. set CCU_LANG to fra. Debugging EGL applications 603 .RFB_20070120_1300. The default character encoding for the EGL debugger is the same as your local system’s default encoding. 604 EGL Programmer’s Guide . see Rich UI debugging. If you choose to continue debugging. typically ASCII. If you choose this setting and do not specify a conversion table. The program name. the debugger will return to the default encoding type. as described in Debug behavior mapping in this topic. TIME. the debugger represents CHAR. EBCDIC encoding is available in several languages. library name. DBCHAR. Related concepts “Debugging EGL applications” on page 573 Rich UI debugging Related tasks “Setting preferences for the EGL debugger” This topic tells you how to change your preferences for the EGL debugger. and INTERVAL variables with EBCDIC encoding. The only preferences used for debugging Rich UI applications are as follows: v Stop at first line of a program v Set systemType to DEBUG v In the Default behavior mapping dialog box. DATE. Data must be converted to host format when calling remote programs and when accessing remote files and databases. Related reference Data conversion Setting preferences for the EGL debugger This topic tells you how to change your preferences for the EGL debugger. the debugger does not use a conversion table when you call a remote program or access a remote file or database. 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. INTERVAL. DBCHAR. the debugger chooses an appropriate conversion table when you call a remote program or access a remote file or database. You can not change character encoding during a debugging session. NUM and NUMC variables are represented in host numeric format. If your Java Runtime Environment does not support the selected character encoding. you will see a warning message when the debugger starts. There are two pages of preferences for the EGL debugger.v When the default character encoding is selected. the settings in the Service Reference tab For further details on Rich UI. MBCHAR. Comparisons between character variables use the ASCII collating sequence. but data is converted to the appropriate Java or ASCII format when making SQL calls or calls to local C++ routines. v When EBCDIC character encoding is used. You must restart the debugger for a change in character encoding to take effect. NUM. and NUMC variables in the default format. and any passed parameters are encoded according to EBCDIC character encoding. The first contains general preferences. see callConversionTable. and the second contains a list of programs or services that you want to debug in the generated code (Java or COBOL). the debugger represents CHAR. TIME. If you choose EBCDIC character encoding and do not specify a conversion table. MBCHAR. For more information on conversion tables. DATE. click the appropriate button: Add Project. JDBC drivers.userID. the EGL debugger considers the following sources in order: Debugging EGL applications 605 . or Java access functions. 5. each defaults to your user ID on Windows 2000. click OK. To restore the default settings. for example. type the user ID and password to be used for remote calls while debugging. 3. You might need extra classes.systemType to be DEBUG rather than the value of the system build descriptor option. see ″EGL debugger port″ later in this section. or variable. For more information. expand EGL in the tree and then click Debug.terminalID. If you want to make changes to your code as you debug. select it and click Remove. if you are finished setting preferences. modify the class path. To specify external Java classes for use when the debugger runs. 2. The default is the local system’s file encoding. select the entry and click Move Up or Move Down. follow these steps: 1. v To remove an entry. NT. From the main menu. see ″SQL database access″ later in this section. Use the buttons to the right of the Class Path Order section. check Enable hotswapping. check Stop at first line of a program.sessionID. directory. click Window → Preferences. 10. click Apply or. XP. For more information. click the box next to Prompt for SQL user ID and password when needed. JAR file. Select the type of character encoding to use when processing data during a debugging session in the Character encoding field. v To move an entry in a list of two or more entries. see “Character encoding options for the EGL debugger” on page 603. 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. 11. 6. 7. This user ID and password are separate from those that are used to access an SQL database. and Linux. 8. In the Preferences window. v To add a project.General preferences To set general preferences for the EGL debugger. For more information. Add Directory. To save your changes. The default is 8345. Click the check box for Set systemType to DEBUG to cause the value of sysVar. This opens the EGL debugger preferences. Type the initial values for sysVar. SQL database access To determine the user ID and password to use for accessing an SQL database. but you can add to that environment’s classpath by working on the Environment tab of the server configuration. sysVar. to support MQ message queues. Type the port number for the EGL debugger in the EGL Debugger Port value field. 9. The class path additions are not visible to the WebSphere Application Server test environment. In the Remote User and Remote Password fields. 4. click Restore Defaults. 13. or Add Variable. If you do not specify values. and sysVar. 12. Add JARs. If you want to require that a user ID and password be specified for remote calls to an SQL database while debugging. If you want the debugger to treat a program declaration like a breakpoint. The build descriptor used at debug time. 4. In the Preferences window. This is the default. see the earlier instructions for setting preferences in the debugger. To set the user ID and password for remote calls while debugging. generated If you want to debug the generated Java or COBOL code for the called program. This dialog is displayed when you select the check box Prompt for SQL user ID and password when needed. 606 EGL Programmer’s Guide . 3. and click Debug Behavior Mapping. EGL debugger port The EGL debugger uses a port to establish communication with the Eclipse workbench. From the main menu. or if the source file is large and runs slowly in the debugger. as described in “Setting preferences for SQL database connections” on page 219.1. you must edit the server configuration: 1. For calls to programs. expand Debug. you might choose this example if you don’t have the EGL source file in your workspace. An interactive dialog that is displayed at connection time. 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. System Properties section. the debugger can execute either the EGL source code or the generated code for the called program or service. set a different value as described in the earlier instructions for setting preferences in the EGL debugger. The default port number is 8345. specifically. type com. The SQL preferences page. the debugger uses the EGL source code. If another application is using that port or if that port is blocked by a firewall. 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. 2. To use the generated code. add an entry to the ″Debug behavior mapping″ table. In the Name field. expand EGL in the tree.egl. Go to the Environment tab. By default. Debug behavior mapping When you debug a program that calls another program or a service. type the port number. you can also specify other connection information. at that page.ibm. 2. 3. 3. click Window → Preferences. Click Add. For each row of the table. Add entries as follows: 1. 2. the sqlID and sqlPassword build descriptor options. click the Called Programs tab.port.debug. specify the following fields: Mapping mode Select one of the following values: source If you want to debug the EGL source file for the called program. In the Value field. For example. This is the default. 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. For each row of the table. Part mapping The fully qualified name of the program or service that you want the debugger to run when the program in Call target is called. Related concepts “Preferences” on page 172 EGL preferences affect the way the workbench displays and works with EGL. Service binding key The name of the binding key in the deployment descriptor for the service that you are calling. For example. Call target The name of the program that is called from the program that you are debugging. VisualAge Generator compatibility “Debugging EGL applications” on page 573 “Character encoding options for the EGL debugger” on page 603 Rich UI debugging Related tasks “Setting preferences for SQL database connections” on page 219 Related reference sessionID systemType terminalID userID Debugging EGL applications 607 . For calls to services. you might choose this example if you don’t have the EGL source file in your workspace. This setting allows the calls to the host program to participate in the debugger transaction.IMS debug If you are debugging IMS and you have called programs that reside on the host. Do not use an asterisk in this field. You can use an asterisk (*) at the end of the target as a wildcard. generated If you want to debug the generated Java or COBOL code for the service. click the Service References tab. or if the source file is large and runs slowly in the debugger. specify the following fields: Mapping mode Select one of the following values: source If you want to debug the EGL source file for the service. 4. Do not use an asterisk in this field. 608 EGL Programmer’s Guide . therefore. This information could include technical inaccuracies or typographical errors. or service. THE IMPLIED WARRANTIES OF NON-INFRINGEMENT. contact the IBM Intellectual Property Department in your country or send inquiries. IBM may not offer the products. 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. MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. or features discussed in this document in other countries. to: IBM World Trade Asia Corporation Licensing 2-31 Roppongi 3-chome. BUT NOT LIMITED TO. You can send license inquiries. it is the user’s responsibility to evaluate and verify the operation of any non-IBM product. For license inquiries regarding double-byte (DBCS) information. 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. Changes are periodically made to the information herein. program. IBM may have patents or pending patent applications covering subject matter described in this document. 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. NY 10504-1785 U.A. in writing.S. to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk. Any reference to an IBM product. or service is not intended to state or imply that only that IBM product.S. Some states do not allow disclaimer of express or implied warranties in certain transactions. program. program. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created © Copyright IBM Corp. this statement may not apply to you. EITHER EXPRESS OR IMPLIED. services. Consult your local IBM representative for information on the products and services currently available in your area. 1996.Appendix. The furnishing of this document does not grant you any license to these patents. or service may be used. program. INCLUDING. Minato-ku Tokyo 106-0032. However. Notices This information was developed for products and services offered in the U.A. 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. or service that does not infringe any IBM intellectual property right may be used instead. these changes will be incorporated in new editions of the publication. Any functionally equivalent product. in writing. 2008 609 . All statements regarding IBM’s future direction or intent are subject to change or withdrawal without notice. modify. IBM. payment of a fee. companies. These examples have not been thoroughly tested under all conditions. and represent goals and objectives only. IBM International Program License Agreement or any equivalent agreement between us. and distribute these sample programs in any form without payment to IBM. must include a copyright notice as follows: © (your company name) (year). To illustrate them as completely as possible. _enter the year or years_. for Rational Software IBM Corporation 3600 Steeles Avenue East Markham. 610 EGL Programmer’s Guide . Information concerning non-IBM products was obtained from the suppliers of those products. using. cannot guarantee or imply reliability. some measurements may have been estimated through extrapolation. should contact: Intellectual Property Dept. 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. ON Canada L3R 9Z7 Such information may be available. Users of this document should verify the applicable data for their specific environment. Sample Programs. compatibility or any other claims related to non-IBM products. including in some cases. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged. Furthermore. © Copyright IBM Corp. therefore. brands. for the purposes of developing. and products. their published announcements or other publicly available sources. or function of these programs. Each copy or any portion of these sample programs or any derivative work. Therefore. Actual results may vary. marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. which illustrate programming techniques on various operating platforms. This information contains examples of data and reports used in daily business operations. Any performance data contained herein was determined in a controlled environment. COPYRIGHT LICENSE: This information contains sample application programs in source language. subject to appropriate terms and conditions. The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement. You may copy. serviceability. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. the results obtained in other operating environments may vary significantly. the examples include the names of individuals. IBM has not tested those products and cannot confirm the accuracy of performance. Portions of this code are derived from IBM Corp. All rights reserved. Warning: Do not use this diagnosis. the photographs and color illustrations may not appear. Other company.com are trademarks or registered trademarks of International Business Machines Corporation in the United States. UNIX is a registered trademark of The Open Group in the United States and other countries. the IBM logo. Microsoft and Windows are trademarks of Microsoft Corporation in the United States.If you are viewing this information softcopy. this information may also contain diagnosis. Appendix. General-use programming interfaces allow you to write application software that obtain the services of this program’s tools. modification and tuning information is provided to help you debug your application software.com/legal/copytrade. Inc. modification. in the United States. and tuning information as a programming interface because it is subject to change.ibm. or both. Linux is a trademark of Linus Torvalds in the United States. A current list of IBM trademarks is available on the Web at www. modification. Notices 611 . or both.html. or both. Trademarks and service marks IBM. other countries. may be trademarks or service marks of others. These and other IBM trademarked terms are marked on their first occurrence in this information with the appropriate symbol (® or ™). or both. other countries. and tuning information. Diagnosis. other countries. Such trademarks may also be registered or common law trademarks in other countries. product or service names. Programming interface information Programming interface information is intended to help you create application software using this program. other countries. Java and all Java-based trademarks are trademarks of Sun Microsystems. indicating US registered or common law trademarks owned by IBM at the time this information was published. and ibm. However. 612 EGL Programmer’s Guide . 1996. 2008 613 . 579. 587 EGL artifacts 67 EGL cheat sheets 166 EGL Console UI 513. 528 EGL deployment descriptor files 94 argument stack C functions 141 ArrayDictionary EGL data part 102 arrays EGL data parts 103 asynchronous tasks (EGL) 266 build descriptors (continued) runtime SQL database connections 203 build files description 89 EGL 94 build order Eclipse 85 build parts overview 120 build paths editing in EGL 84 overview 83 build projects Java source code 84 button widgets EGL Console UI elements code generation EGL data access 183 debugging 591 JSF data table properties 463 JSF image sizes 461 JSF input functions 462 source code editor 127 SQL statements 190 code snippets inserting 165 overview 164 retrieving row values 417 setting focus 418 testing for session variables 425 updating table rows 423 code templates creating 160 disabling 159 editing 161 enabling 159 exporting 162 importing 162 naming considerations 158 overview 158 removing 163 restoring defaults 163 combination boxes EGL Console UI elements 524 commands EGL debugger 580 COMMAREA pointer parameter format 256 COMMDATA parameter format 257 comments EGL source code code lines 128 COMMPTR parameter format 256 Console UI building EGL applications 513 creating 516 EGL elements 513 elements button widgets 520 check boxes 522 user input 524 modes running EGL applications 529 rich client widgets 519 running EGL applications 528 constant fields creating in EGL Text UI 502 container-managed security 452 content assist EGL overview 157 control transfer JSF Handlers 569 create function add EGL keyword 184 520 C C mapping data to EGL 132 C data types EGL primitive types compared 145 C functions invoking 136 using with EGL 133 C functions in EGL BIGINT 138 DATE 139 DATETIME 139 DECIMAL 140 INTERVAL 139 pop functions 141 return functions 144 calls Java from EGL 128 cancelOnPageTransition EGL property 411 capabilities enabling for EGL 11 catcher program (EGL) 301 character encoding EGL debugger options 603 character types EGL primitives 98 cheat sheets opening in EGL 166 check boxes EGL Console UI elements 522 user input in EGL 404 CICS asynchronous tasks (EGL) 266 RETURN IMMEDIATE 265 START 264 CICSOSLINK (EGL) 258 clients EGL binding 487 COBOL CALLs (EGL) 268 B basic programs in IMS (EGL) 308 BasicLibrary Library stereotype 111 bidirectional language text conversion 245 BIGINT data type C functions 138 binding functions EGL shortcuts 407 bindings JSF controls to EGL elements 394 JSPs 389 variables to services 491 BIRT reports adding support to projects 553 breakpoints EGL debugger 584 build control part description 120 build descriptor options EGL version 7.0 changes 35 EGL version 7.1 changes 16 genReturnImmediate (EGL) 261 IMS generation (EGL) 310 spaADF in IMSADF II (EGL) 293 spaSize (EGL) 276 spaStatusBytePosition (EGL) 276 synchOnPgmTransfer (EGL) 262 build descriptor part description description 120 build descriptors EGL debugger 583 preferences 174 © Copyright IBM Corp.Index A add EGL keyword records 184 Ajax defined 327 AJAX requests EGL Web pages 432 external requests 442 refresh requests 436 submit requests 439 applications debugging in EGL 573. 0 28 EGL version 7. 26 EGL version 7.0 (continued) manual changes after migration 54 migration 42.0 36 overview 148 exporting files Eclipse workbench 81 exporting projects Project Interchange 81 external services exposing 493 providing access 493 ExternalType EGL logic part description 105 ExternalType EGL part 117 F facets adding 76 overview 76 projects 76 FastPath in IMS generating programs for (EGL) 308 features adding 76 overview 76 projects 76 file I/O writing and reading 186 File Search view EGL 168 files build overview 89 comma-separated value files 186 EGL searches 168 source code editor 127 EGL application artifacts 67 sequential files 186 sharing in EGL 79 E editors EGL content assist 157 overview 155 locating source files 172 preferences folding 176 imports 178 setting 175. 177 EGL migration previous version 38 EGL source file creating 90 EGL version 6.0 iFix 001 migration 56 migration tool changes 57 property changes 60 EGL version 7.0 build descriptor option changes exception handling 36 interface updates 37 language changes 19 manual changes 54 35 614 EGL Programmer’s Guide . 579 EGL preferences 604 EGL Web projects 592 hotswapping 587 invoking from EGL generated code 591 preparing servers 592 debugger (continued) starting a Web session 594 starting EGL programs 590 starting in EGL 588 stepping through programs 575 viewing variables in EGL 585 debugging DL/I 596 IMS 596 services 595 DECIMAL data type C functions 140 deferred message switch in IMSADF II (EGL) 293 Delegate parts syntax 117 delete EGL keyword basic I/O functions 184 delete function delete EGL keyword 184 deployment descriptor files adding information 496 EGL applications 94.1 14 data processing tasks overview 183 data table check boxes selecting rows in EGL 404 data tables retrieving row values 417 data types mapping EGL to C 132 database connections preferences 219 SQL changing 205 creating 197 runtime connections 203 database options EGL specifications 189 databases creating EGL data access applications 208 EGL SQL support 200 DataItem parts editing 167 dataItems EGL data parts 97 DataTable EGL data part 102 DATE data type C functions 139 date types EGL primitives 98 DATETIME data type C functions 139 debug servers DLI 601 debugger breakpoints in EGL 584 build descriptors 583 character encoding options in EGL 603 creating a launch configuration 588 creating a Listener launch configuration 589 EGL commands 580 EGL overview 573. 120 EGL Web projects 389 shared protocols 497 design document for reports JasperReports 534 development workbench overview 1 device input format (DIF) estimating size 318 device output format (DOF) estimating size 318 Dictionary EGL data part 102 DL/I basic concepts (EGL) 221 debugging 596 examples (EGL) 227 secondary index (EGL) 230 DLI starting debug servers 601 EGL version 7.1 build descriptor option changes 16 interface updates 17 language changes 14 new features 13 parts 14 eglpath EGL build path 83 ELAISVN (EGL) 301 ELAISVN7 (EGL) 301 ELATSGET (EGL) 292 ELATSPUT (EGL) 292 elements EGL Console UI applications 513 encryption passwords in EGL 146 event handlers JSF controls 460 exceptions handling EGL version 7. 43 migration tool 44 new features 18 parts 28 services 36 validation changes 24.curses mode overview 529 D data forwarding between Web pages 410 data access EGL code 183 data access applications creating with EGL 208 data conversion bidirectional language text 245 data parts EGL arrays 103 EGL miscellaneous 102 EGL overview 97 EGL version 7. 555 Handler parts creating Web pages in EGL handlers EGL logic parts overview 105 392 301 I I/O functions EGL records 184 615 .1 14 language elements EGL external mappings 117 large object types EGL primitives 98 launch configurations explicit 588 Listener 589 viewing implicitly created configurations 590 LDAP EGL support 190 library EGL logic part description 105 Library part overview 110 stereotypes BasicLibrary 111 link edit part description 120 linkage options in transfer of control 251 linkage options part description 120 linkage options parts and IMS transaction codes (EGL) list boxes EGL Console UI elements 524 List view EGL parts 170 local services calling 483 localization resource bundles 430 Web applications 426 logic parts Delegate syntax 117 EGL functions 107 Index J Jasper reports adding support to projects 549 application elements in EGL 533 JasperReports XML design document 534 Java EGL calls 128 ExternalType EGL part 117 JavaScript functions JSF control event handlers 460 JavaServer Faces (JSF) binding buttons to EGL functions 395 binding controls to EGL elements 394 binding single-select controls to EGL variables 401 changing image sizes with EGL code 461 component interface support 464 controls accessing in EGL 454 binding to services in EGL 407 EGL variables 397 event handlers 460 309 H handler parts creating 541.0 19 EGL version 7.folders creating source folders in EGL 87 EGL application artifacts 67 folding preferences 176 fonts preferences 176 form fields setting focus 418 form parts creating 502 editing 500 filtering 509 templates 505 form variables creating with EGL parts Text UI 503 FormGroup EGL data part 102 FormGroup parts editing 500 bidirectional text preferences 511 display options 510 palette preferences 512 preferences 510 forms displaying records in EGL 507 inserting variables with EGL Text UI 503 popup forms in EGL 506 popup menus in EGL 507 functions binding JSF buttons in EGL 395 EGL binding JSF controls 394 commands when pages load 411 overloaded 107 overview 107 G generatable parts EGL description 96 generation eglpath 83 preferences 180 generation process controlling 120 get EGL keyword handling records 184 GSAM files PCB associations (EGL) I4GL data types EGL primitive types compared 145 IFP (IMS FastPath) generating programs for (EGL) 308 immediate message switch in IMSADF II (EGL) 293 import organization EGL editor 178 import statements description 124 importing files Eclipse workbench 81 importing projects Project Interchange 81 IMS BMP program generation (EGL) 309 calling programs in (EGL) 267 debugging 596 FastPath program generation (EGL) 308 MFS message input descriptor (MID) (EGL) 289 MFS message output descriptor (MOD) (EGL) 289 program-to-program message switches (EGL) 275 runtime support (EGL) 307 scratch pad area (SPA) (EGL) 286 IMS Connect (EGL) 301 IMSADF II programs transferring to and from (EGL) 293 interface EGL logic part description 105 Interface part creating from service or external type 116 overview 115 INTERVAL data type C functions 139 JavaServer Faces (JSF) (continued) controls (continued) style changes with EGL code 458 creating Web pages 392 data tables check boxes in EGL 404 properties in EGL code 463 EGL Web pages elements 389 navigation function 408 handler part properties Web page data 410 handler parts forwarding control in EGL 569 Handler parts changing style classes in EGL 459 EGL preferences 465 input functions in EGL code 462 link target changes in EGL 457 JavaServer Pages (JSP) EGL Web applications 389 JSP pages changing JSF image size with EGL code 461 L language changes EGL version 7. 0 44 migration tool changes EGL version 6.0 54 menus creating popups in EGL 507 enabling capabilities in EGL 11 message input descriptor (MID) estimating size 318 format (EGL) 289 message output descriptor (MOD) estimating size 318 format (EGL) 289 message queues print files as (EGL) 322 serial files as (EGL) 320 message switches in IMS/VS (EGL) 275 in IMSADF II (EGL) 293 migrating EGL previous version 38 migrating EGL code version 6.0 43 manual changes after migration 54 migration preferences EGL-to-EGL 42 migration tool EGL version 7.0 28 version 7.logic parts (continued) EGL overview 105 EGL version 7.0 migration 44 moving parts EGL 121 MPP (message processing program) generating programs for (EGL) 307 N navigation rules EGL Web pages 408 null testing for in SQL (EGL) numeric types EGL primitives 98 196 preferences (continued) Rich UI appearance 347 services 498 source styles 179 SQL database connections 219 SQL retrieve 220 text EGL overview 180 Text UI editor 510 editor bidirectional text 511 editor palette 512 primitive types C data types compared 145 mapping EGL to C 132 primitives EGL data parts 97 EGL data types 98 print forms displaying records in EGL 507 procedures calling in EGL 212 Program Communication Block (PCB) in DL/I (EGL) 221 program EGL logic part description 105 program parts Interface 115 service 113 Program Specification Block (PSB) in DL/I (EGL) 221 scheduling (EGL) 301 program-to-program message switches in IMS/VS (EGL) 275 in IMSADF II (EGL) 293 programming tasks completing in EGL 127 programs EGL debugger 575 starting in the EGL debugger 590 Project Explorer view EGL 168 Project Interchange project sharing 81 projects adding BIRT reports support 553 adding Jasper reports support 549 converting to EGL plug-in 74 creating EGL plug-in 74 EGL Web 73 overview 71 debugging in EGL 588 EGL application artifacts 67 EGL database options 189 facets 76 features 76 features and facets 76 linking in the EGL build path 84 new EGL projects 173 overview 70 renaming 75 sharing in EGL overview 79 repositories 82 616 EGL Programmer’s Guide .0 iFix 001 56 version 7.1 14 generatable in EGL description 96 introduction 95 properties introduction 122 references 171 renaming in EGL 120 searching for 168 viewing lists in EGL 170 Parts List view EGL 168 Parts Reference view EGL generatable logic parts 171 searches 168 passwords encryption in EGL 146 pop functions C 141 popup forms creating in EGL 506 popup menus creating in EGL 507 preferences build descriptors 174 EGL debugger 604 setting 173 Web applications 465 EGL editor folding 176 formatter 177 import organization 178 overview 175 fonts 176 generation 180 overview 172 Rich UI 345 M manual changes EGL version 7.0 28 Interface creating from service or external type 116 remote services 115 JSF Handler EGL preferences 465 Library sharing functions 110 service service oriented architecture 113 Service creating from called program 114 creating WSDL from 119 O onConstructionFunction EGL function 411 onPostRenderFunction EGL function 411 onPreRenderFunction EGL function 411 OSLINK parameter format 257 overloaded functions 107 P packages creating 89 import statements 124 overview 87 Page Designer bindings 389 support 389 page lifecyles EGL functions 411 pages commands when pages load 411 parts EGL ExternalType 117 Record parts 100 searches 168 version 7.0 iFix001 57 move statements EGL version 7. 555 subreports 547 report handler EGL logic part 533 reports code for invoking reports 538 creating Jasper reports with EGL creating with EGL 531 exported file formats 538 exporting 538 running 545 templates for 546 writing report-driver code 538 repositories sharing EGL projects 82 resource associations setting up in EGL 186 resource associations part description 120 resource bundles creating 430 locales 431 overview 426 retrieval data processing tasks 183 retrieve feature SQL 205 retrieve preferences SQL 220 return functions C 144 Rich Client Platform (RCP) mode EGL overview 529 rich client widgets EGL Console UI 519 Rich UI applications 357 authentication 353.properties changes in EGL version 6. 373. 373. 368 confidentiality 355 criteria 369. 378. 360. 361.0 iFix 001 migration 60 changing JSF data tables with EGL code 463 EGL cancelOnPageTransition 411 introduction 122 JSF Handler for data transfer 410 PSB scheduling (EGL) 301 R radio button group widget EGL Console UI 524 read function get EGL keyword 184 record arrays binding JSF controls to EGL variables 401 Record EGL part 100 Record parts SQL using (EGL) 193 Record stereotype EGL parts 100 records displaying in EGL forms 507 EGL data parts 97 EGL read/write functions 184 refactoring deleting EGL source files 93 moving EGL parts 121 moving EGL source files 92 renaming EGL parts 120 renaming EGL projects 75 renaming EGL source files 91 remote services calling 486 renaming parts EGL 120 replace EGL keyword 184 report design files compiling in EGL 533 report driver program functions in EGL 533 report handler creating 541. 352 proxy 359. 385. 380. 386 threats 376 Tomcat 373 URL patterns 358 user 364. 372. 366. 376. 369. 378. 366 Web services 361 WebSphere 372. 374. 374 JSF 357. 362 overview 327.0 36 elements 478 exposing 493 overview 475 providing access 493 shared protocols 497 types 481 session objects EGL Web pages 424 session variables detecting 425 EGL Web pages 424 setCursorFocus code snippets 418 shared protocols creating 497 snippets inserting 165 overview 164 retrieving row values 417 setting focus 418 testing for session variables 425 updating table rows 423 SOA overview 475 source assistant JSF controls in EGL 454 overview 167 source code building projects 84 comments 128 source control sharing EGL projects 82 source file EGL creating 90 source files comments 128 content assist 157 deleting 93 description 89 locating in the Project Explorer view 172 moving 92 renaming 91 source folders creating in EGL 87 source style preferences 179 SPA (scratch pad area) (EGL) 286 spaADF in IMSADF II (EGL) 293 Index 617 . 367. 368. 367 authorization 353. 364. 371. 380. 357. 353. 355. 371 EGL preferences 345 errors 374 example 369 IBM Rational AppScan 386 JEE 369. 386 SSL 377. 381. 385. 359. 377. 360 resources 355 security 352. 362. 381. 358. 374 Rich UI appearance EGL preferences 347 right justification variables 146 runtime messages customizing EGL system messages 152 S 532 Search view EGL 168 searches EGL items 168 secondary index in DL/I (EGL) 230 security container managed 452 LDAP 190 Web applications 452 servers EGL Web page previews 448 preparing for debugging 592 service EGL logic part description 105 service oriented architecture EGL logic parts 113 service parts creating from called programs 114 creating WSDL 119 overview 113 services binding from WSDL files 489 binding JSF controls in EGL 407 calling local 483 remote 486 debugging 595 EGL client binding information 487 EGL code 491 EGL version 7. 359. 0 32 EGL version 7.1 updates 17 user interface (UI) parts editing 500 JSF Handler EGL preferences 465 user interfaces EGL console 516 user sessions data storage for EGL Web pages 424 V validation changes in EGL version 7.0 24. 26 validation changes EGL version 7.spaSize (EGL) 276 spaStatusBytePosition (EGL) 276 SQL connection preferences 219 database connections changing 205 creating 197 runtime connections 203 EGL supported database managers 200 explicit 211 explicit statements (EGL) 195 implicit statements description (EGL) 194 null (EGL) 196 Record parts (EGL) 193 retrieve feature 205 retrieve preferences 220 SELECT statements validating 217 statements working with 211 stored procedures in EGL 212 working with data in EGL 190 SQLRecord parts in prepare statements 215 stereotypes EGL Record 100 storage data processing tasks 183 STRING arrays binding JSF controls to EGL variables 401 style classes changing from EGL JSF Handlers 459 styles changing JSF controls with EGL code 458 subreports creating 547 substrings creating 146 Swing mode overview 529 system functions EGL version 7.0 32 system messages EGL runtime customization 152 system variables EGL version 7.0 32 EGL version 7. 26 variable fields creating with EGL parts Text UI 503 variables binding JSF controls to EGL elements 394 binding JSF controls to EGL variables 401 binding to services 491 EGL arrays 103 binding to Web page controls 397 viewing in the EGL debugger 585 VGWebTransactions EGL part forwarding control 569 VisualAge Generator compatibility preferences 173 VisualAge Generator Web transactions forwarding control in EGL 569 W Web applications debugging in EGL 588 EGL debugger 592 EGL elements 389 EGL preferences 465 EGL tasks 391 Page Designer 389 security 452 Web diagrams EGL Web projects 389 Web page controls binding to EGL variables 397 Web pages AJAX requests 432 external requests 442 refresh requests 436 submit requests 439 creating in EGL 392 EGL commands when pages load 411 forwarding data 410 navigation rules in EGL 408 previewing EGL pages 448 session data storage with EGL 424 Web projects EGL elements 389 T templates creating in EGL 160 disabling in EGL 159 editing in EGL 161 EGL naming considerations EGL overview 158 enabling in EGL 159 exporting from EGL 162 importing in EGL 162 U 158 UNIX screen options EGL Console UI 529 UNIX users EGL Console UI screen options update function replace EGL keyword 184 use statements description 124 529 618 EGL Programmer’s Guide .0 migration 44 templates (continued) removing in EGL 163 restoring defaults in EGL 163 text localizing 426 preferences setting in EGL 180 Text Form editor filtering Text UI 509 overview 500 Text UI bidirectional text preferences 511 display options 510 palette preferences 512 preferences 510 text forms displaying records in EGL 507 text strings constant fields in EGL Text UI 502 Text UI editor bidirectional text preferences 511 display options 510 palette preferences 512 preferences 510 Text UI programs in IMS (EGL) 307 time types EGL primitives 98 trademarks 611 transferring control CICS environment using call (EGL) 254 using transfer statement (EGL) 261 IMS BMP environment using transfer statement (EGL) 270 IMS BMP environments using call (EGL) 267 IMS/VS environments using call (EGL) 267 using transfer statement (EGL) 275 in IMS/VS (EGL) 291 in z/OS batch (EGL) 267 iSeries environment (EGL) 299. 300 Java programs (EGL) 300 overview 251 z/OS batch environment using transfer statement (EGL) 270 type-ahead Web applications 413 user interface EGL version 7 updates 37 EGL version 7.0 24.0 migration 44 system libraries EGL version 7. Web projects (continued) JSF component interface support JSF link targets in EGL 457 Web services binding EGL services 487 WSDL 489 calling local 483 remote 486 deployment information 496 EGL code 491 elements 478 exposing 493 providing access 493 shared protocols 497 types 481 Web transaction applications EGL overview 561 work database (EGL) 291 workbench overview 1 WSDL biding 489 WSDL files creating 119 464 X XML report design document creating 534 Index 619 . 620 EGL Programmer’s Guide . . Printed in USA .
Copyright © 2024 DOKUMEN.SITE Inc.