980
Rational Application Developer EGL Reference Guide Version 6 Release 0 SC31-6839-01

EGL Referene Guide

Embed Size (px)

Citation preview

Rational Application Developer

EGL Reference GuideV ersion 6 Release 0

SC31-6839-01

Rational Application Developer

EGL Reference GuideV ersion 6 Release 0

SC31-6839-01

Note Before using this information and the product it supports, read the information in Notices, on page 951.

Third Edition (December 2004) This edition applies to version 6, release 0, modification 0 of Rational Web Developer and Rational Application Developer and to all subsequent releases and modifications until otherwise indicated in new editions. Copyright International Business Machines Corporation 1996, 2004. All rights reserved. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

ContentsOverview . . . . . . . . . . . . . . 1Introduction to EGL . . . . . Whats new in the EGL 6.0 iFix . Whats new in EGL version 6.0 . Development process . . . . Run-time configurations . . . Use of a Java wrapper . . . Valid calls . . . . . . . Valid transfers . . . . . Sources of additional information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 . 1 . 3 . 7 . 7 . 8 . 8 . 10 . 10 Dictionary properties . . . . Dictionary functions . . . . ArrayDictionary . . . . . . . EGL statements . . . . . . . Keywords in alphabetical order . Transfer of control across programs Exception handling . . . . . try blocks . . . . . . . EGL system exceptions . . . Limits of try blocks . . . . Error-related system variables . I/O statements . . . . . . Error identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 . 97 . 99 . 100 . 103 . 105 . 106 . 106 . 107 . 107 . 108 . 109 . 110

. . . . on EGL .

EGL language overview . . . . . . . 11EGL projects, packages, and files . . . . . EGL project . . . . . . . . . . . Package . . . . . . . . . . . . EGL files . . . . . . . . . . . . Recommendations . . . . . . . . . Parts. . . . . . . . . . . . . . . References to parts . . . . . . . . . Fixed structure . . . . . . . . . . Typedef. . . . . . . . . . . . . Import . . . . . . . . . . . . . . Background . . . . . . . . . . . Format of the import statement . . . . . Primitive types . . . . . . . . . . . Primitive types at declaration time . . . Relative efficiency of different numeric types ANY . . . . . . . . . . . . . Character types . . . . . . . . . . DateTime types . . . . . . . . . . LOB types . . . . . . . . . . . . Numeric types . . . . . . . . . . Declaring variables and constants in EGL . . Dynamic and static access . . . . . . . Scoping rules and this in EGL . . . . . References to variables in EGL . . . . . . Bracket syntax for dynamic access . . . . Abbreviated syntax for referencing fixed structures . . . . . . . . . . . . Overview of EGL properties . . . . . . . Field-presentation properties . . . . . Formatting properties . . . . . . . . Page item properties . . . . . . . . SQL item properties . . . . . . . . Validation properties . . . . . . . . Set-value blocks . . . . . . . . . . . Set-value blocks for elementary situations . Set-value blocks for a field of a field . . . Use of this . . . . . . . . . . . Set-value blocks, arrays, and array elements Additional examples . . . . . . . . Arrays . . . . . . . . . . . . . . Dynamic arrays . . . . . . . . . . Structure-field arrays . . . . . . . . Dictionary . . . . . . . . . . . . . Copyright IBM Corp. 1996, 2004

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

11 11 12 12 13 15 18 22 23 28 28 29 29 31 32 33 33 36 43 45 48 49 51 52 54 56 58 60 62 68 73 76 82 82 83 85 85 86 87 88 91 95

Migrating EGL code to the EGL 6.0 iFix . . . . . . . . . . . . . . . . 113EGL-to-EGL migration . . . . . . . Changes to properties during EGL-to-EGL migration . . . . . . . . . . . . Setting EGL-to-EGL migration preferences . . . . . . . . 114 . 117 . 122

Setting up the environment . . . . . 125Setting EGL preferences . . . . . . . Setting preferences for text . . . . . Setting preferences for the EGL debugger Setting the default build descriptors . . Setting preferences for the EGL editor . Setting preferences for source styles . . Setting preferences for templates . . . Setting preferences for SQL database connections . . . . . . . . . . Setting preferences for SQL retrieve . . Enabling EGL capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 125 126 127 127 128 128

. 129 . 131 . 132

Beginning code development . . . . 135Creating a project . . . . . . . . . . . Creating an EGL project . . . . . . . . Creating an EGL Web project . . . . . . Specifying database options at project creation Creating an EGL source folder . . . . . . . Creating an EGL package . . . . . . . . Creating an EGL source file . . . . . . . Using the EGL templates with content assist . . Keyboard shortcuts for EGL . . . . . . . . 135 . 135 . 135 136 . 137 . 137 . 138 . 138 . 139

Developing basic EGL source codeCreating an EGL dataItem part DataItem part . . . . . Creating an EGL record part . Record parts . . . . . . Fixed record parts . . . . Record types and properties Creating an EGL program part Program part . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

141. . . . . . . . 141 141 142 142 143 144 147 148

iii

Creating an EGL function part . . . Function part . . . . . . . Creating an EGL library part . . . Library part of type basicLibrary . Library part of type nativeLibrary Creating an EGL dataTable part . . DataTable . . . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

149 150 150 151 152 154 155

Inserting code snippets into EGL and JSP files . . . . . . . . . . . . . 157Setting the focus to a form field . . . Testing browsers for a session variable . Retrieving the value of a clicked row in a table . . . . . . . . . . . . Updating a row in a relational table . . . . . . data . . . . . . . . . 158 . 158 . 159 . 159

Working with text and print forms . . 161Creating an EGL formGroup part . FormGroup part . . . . . Form part . . . . . . . Creating an EGL print form . Creating an EGL text form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 161 162 163 165

EGL reports overview . . . . . . . . EGL report creation process overview . . . Data sources. . . . . . . . . . . . Data records in the library . . . . . . . EGL report handler . . . . . . . . . Predefined report handler functions . . . . Additional EGL report handler functions . . Data types in XML design documents . . . Sample code for EGL report-driver functions . Adding a design document to a package . . Using report templates . . . . . . . . Creating an EGL report handler . . . . . Creating an EGL report handler manually . . Writing code to drive a report . . . . . . Generating files for and running a report . . Exporting Reports . . . . . . . . . . Report library . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

213 214 216 217 217 218 219 220 222 223 224 225 225 229 231 231 232

Working with files and databases . . . 235SQL support . . . . . . . . . . . . . . EGL statements and SQL . . . . . . . . Result-set processing . . . . . . . . . . SQL records and their uses . . . . . . . . Database access at declaration time . . . . . Dynamic SQL . . . . . . . . . . . . SQL examples . . . . . . . . . . . . Default database . . . . . . . . . . . Informix and EGL . . . . . . . . . . . SQL-specific tasks . . . . . . . . . . . . Retrieving SQL table data . . . . . . . . Creating dataItem parts from an SQL record part (overview) . . . . . . . . . . . . Creating EGL data parts from relational database tables . . . . . . . . . . . . Viewing the SQL SELECT statement for an SQL record . . . . . . . . . . . . . . . Validating the SQL SELECT statement for an SQL record . . . . . . . . . . . . . Constructing an EGL prepare statement . . . Constructing an explicit SQL statement from an implicit one . . . . . . . . . . . . . Resetting an explicit SQL statement . . . . . Removing an SQL statement from an SQL-related EGL statement . . . . . . . . Resolving a reference to display an implicit SQL statement . . . . . . . . . . . . . . Understanding how a standard JDBC connection is made . . . . . . . . . . VSAM support . . . . . . . . . . . . . Access prerequisites . . . . . . . . . . System name . . . . . . . . . . . . MQSeries support . . . . . . . . . . . . Connections . . . . . . . . . . . . . Include message in transaction . . . . . . Customization . . . . . . . . . . . . MQSeries-related EGL keywords . . . . . . Direct MQSeries calls . . . . . . . . . . 235 235 239 241 245 246 246 256 257 257 257 258 259 263 263 264 264 266 266 266 267 268 268 268 269 269 270 270 272 274

Creating a Console User Interface . . 171Console user interface . . . . Creating a Console User Interface Package egl.ui.console . . . . OpenUI statement . . . . . . ConsoleUI record types . . . . Enumerations for ConsoleUI . . ConsoleUI screen options for UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 172 174 175 179 188 190

Creating an EGL Web application . . . 193Web support . . . . . . . . . . . . Creating a single-table EGL Web application . . EGL Data Parts and Pages wizard . . . . Creating a single-table EGL Web application . Defining Web pages in the EGL Data Parts and Pages wizard . . . . . . . . . . . Creating an EGL pageHandler part . . . . . Page Designer support for EGL . . . . . PageHandler part . . . . . . . . . . JavaServer Faces controls and EGL . . . . Creating an EGL data item and associating it with a Faces JSP . . . . . . . . . . Associating an EGL record with a Faces JSP . Binding a JavaServer Faces command component to an EGL page handler . . . . Using the Quick Edit view for page-handler code . . . . . . . . . . . . . . Binding a JavaServer Faces input or output component to an EGL page handler . . . . Binding a JavaServer Faces check box component to an EGL page handler . . . . Binding a JavaServer Faces single-selection component to an EGL page handler . . . . Binding a JavaServer Faces multiple-selection component to an EGL page handler . . . . . . . . . . . . . 193 193 193 194 196 197 198 200 203

. 204 . 205 . 206 . 207 . 207 . 208 . 209 . 210

Maintaining EGL code

. . . . . . . 277. . . . . 277

Creating EGL Reports . . . . . . . . 213 ivEGL Reference Guide

Line commenting EGL source code .

Searching for parts . . . . . . . . . . . Viewing part references . . . . . . . . . . Opening a part in an .egl file . . . . . . . . Locating an EGL source file in the Project Explorer Deleting an EGL file in the Project Explorer . . .

277 278 279 279 280

Debugging EGL code . . . . . . . . 281EGL debugger . . . . . . . . . . . . Debugger commands . . . . . . . . . Use of build descriptors . . . . . . . . SQL-database access . . . . . . . . . call statement . . . . . . . . . . . System type used at debug time . . . . . EGL debugger port . . . . . . . . . Recommendations . . . . . . . . . . Debugging applications other than J2EE . . . Starting a non-J2EE application in the EGL debugger . . . . . . . . . . . . . Creating a launch configuration in the EGL debugger . . . . . . . . . . . . . Creating an EGL Listener launch configuration Debugging J2EE applications . . . . . . . Preparing a server for EGL Web debugging . Starting a server for EGL Web debugging . . Starting an EGL Web debugging session . . Using breakpoints in the EGL debugger . . . Stepping through an application in the EGL debugger . . . . . . . . . . . . . . Viewing variables in the EGL debugger . . . . . . . . . . . . 281 281 284 284 285 285 285 286 287

Generating deployment code for EJB projects Setting the variable EGL_GENERATORS_PLUGINDIR . . . . . Running EGL-generated Java code on the local machine . . . . . . . . . . . . . . . Starting a basic or text user interface Java application on the local machine . . . . . . Starting a Web application on the local machine Build script . . . . . . . . . . . . . . Java build script . . . . . . . . . . . Build server . . . . . . . . . . . . . . Starting a build server on AIX, Linux, or Windows 2000/NT/XP . . . . . . . . .

335 335 336 336 336 338 339 339 339

Deploying EGL-generated Java output 343Java runtime properties . . . . . . . . . . In a J2EE environment . . . . . . . . . In a non-J2EE Java environment . . . . . . Build descriptors and program properties . . . For additional information . . . . . . . . Setting up the non-J2EE runtime environment for EGL-generated code . . . . . . . . . . . Program properties file . . . . . . . . . Deploying Java applications outside of J2EE . . Installing the EGL run-time code for Java . . . Including JAR files in the CLASSPATH of the target machine . . . . . . . . . . . . Setting up the UNIX curses library for EGL run time . . . . . . . . . . . . . . . Setting up the TCP/IP listener for a called non-J2EE application . . . . . . . . . . Setting up the J2EE run-time environment for EGL-generated code . . . . . . . . . . . Eliminating duplicate jar files . . . . . . . Setting deployment-descriptor values . . . . Updating the J2EE environment file . . . . . Updating the deployment descriptor manually Setting the JNDI name for EJB projects . . . . Setting up the J2EE server for CICSJ2C calls . . Setting up the TCP/IP listener for a called appl in a J2EE appl client module . . . . . . . Setting up a J2EE JDBC connection . . . . . Deploying a linkage properties file . . . . . Providing access to non-EGL jar files . . . . 343 343 343 344 345 345 345 346 346 347 347 348 348 349 350 351 352 352 353 353 356 358 359

. 287 . 288 288 . 289 . 289 . 289 . 290 . 291 . 291 . 292

Working with EGL build parts . . . . 295Creating a build file . . . . . . . . . . Setting up general build options . . . . . Setting up external file, printer, and queue associations . . . . . . . . . . . . Setting up call and transfer options . . . . Setting up references to other EGL build files Editing an EGL build path . . . . . . . . . 295 . 295 . 305 . 311 318 . 319

Generating, preparing, and running EGL output . . . . . . . . . . . . 321Generation . . . . . . . . . . . . . . Generation of Java code into a project . . . . Build . . . . . . . . . . . . . . . Building EGL output . . . . . . . . . . Build plan . . . . . . . . . . . . . Java program, page handler, and library . . . Results file . . . . . . . . . . . . . Generating in the workbench . . . . . . . . Generation in the workbench . . . . . . . Generating from the workbench batch interface Generation from the workbench batch interface Generating from the EGL Software Development Kit (SDK) . . . . . . . . . . . . . . . Generation from the EGL Software Development Kit (SDK) . . . . . . . . . . . . . . Invoking a build plan after generation . . . . . Generating Java; miscellaneous topics . . . . . Processing Java code that is generated into a directory . . . . . . . . . . . . . . 321 321 323 325 325 326 326 326 328 329 329 330 330 331 332 332

EGL reference . . . . . . . . . . . 363Assignments. . . . . . . . . . . . . Assignment across numeric types . . . . Other cross-type assignments . . . . . . Padding and truncation with character types Assignment between timestamps . . . . . Assignment to or from substructured items . Assignment of a record . . . . . . . . Association elements . . . . . . . . . . commit . . . . . . . . . . . . . conversionTable . . . . . . . . . . fileType . . . . . . . . . . . . . fileName . . . . . . . . . . . . . formFeedOnClose . . . . . . . . . . replace . . . . . . . . . . . . . . 363 . 364 . 365 366 . 367 . 367 . 368 . 368 . 369 . 369 . 369 . 369 . 369 . 370

Contents

v

system . . . . . . . . . . . . . systemName . . . . . . . . . . . text . . . . . . . . . . . . . . . asynchLink element . . . . . . . . . . package in asynchLink element . . . . . recordName in asynchLink element . . . . Basic record part in EGL source format . . . . Build parts . . . . . . . . . . . . . EGL build-file format . . . . . . . . . Build descriptor options . . . . . . . . Build scripts . . . . . . . . . . . . . Options required in EGL build scripts . . . callLink element . . . . . . . . . . . If callLink type is localCall (the default) . . If callLink type is remoteCall . . . . . . If callLink type is ejbCall . . . . . . . alias in callLink element . . . . . . . . conversionTable in callLink element . . . . ctgKeyStore in callLink element . . . . . ctgKeyStorePassword in callLink element . . ctgLocation in callLink element . . . . . ctgPort in callLink element . . . . . . . JavaWrapper in callLink element . . . . . linkType in callLink element . . . . . . library in callLink element . . . . . . . location in callLink element . . . . . . luwControl in callLink element . . . . . package in callLink element . . . . . . parmForm in callLink element . . . . . . pgmName in callLink element . . . . . . providerURL in callLink element . . . . . refreshScreen in callLink element . . . . . remoteBind in callLink element . . . . . remoteComType in callLink element . . . . remotePgmType in callLink element . . . . serverID in callLink element . . . . . . type in callLink element . . . . . . . . Comments . . . . . . . . . . . . . Compatibility with VisualAge Generator . . . containerContextDependent . . . . . . . Database authorization and table names . . . Data conversion . . . . . . . . . . . Data conversion when the invoker is Java code Conversion algorithm . . . . . . . . Bidirectional language text . . . . . . . Data initialization . . . . . . . . . . . DataItem part in EGL source format . . . . . DataTable part in EGL source format . . . . EGL build path and eglpath . . . . . . . EGLCMD. . . . . . . . . . . . . . Syntax . . . . . . . . . . . . . . Examples . . . . . . . . . . . . . EGL command file . . . . . . . . . . Examples of command files . . . . . . EGL editor . . . . . . . . . . . . . Content assist in EGL . . . . . . . . EGL enumerations . . . . . . . . . . . EGL reserved words . . . . . . . . . . Words that are reserved outside of an SQL statement . . . . . . . . . . . . . EGLSDK . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

370 370 370 371 371 372 372 373 373 374 397 397 398 398 398 399 400 400 401 401 401 402 402 403 403 404 405 406 406 407 408 408 409 410 412 412 413 414 415 416 417 418 419 420 421 422 423 424 427 428 428 430 431 432 433 433 433 435

. 436 . 437

Syntax . . . . . . . . . . . . . . Examples . . . . . . . . . . . . . Format of eglmaster.properties file . . . . EGL source format . . . . . . . . . . EGL system exceptions . . . . . . . . . EGL system limits . . . . . . . . . . . Expressions . . . . . . . . . . . . . Datetime expressions . . . . . . . . . Logical expressions . . . . . . . . . Numeric expressions . . . . . . . . . Text expressions . . . . . . . . . . Format of master build descriptor plugin.xml file FormGroup part in EGL source format . . . . Properties of a screen floating area . . . . Properties of a print floating area . . . . . Form part in EGL source format . . . . . . Text-form properties . . . . . . . . . Print-form properties . . . . . . . . . Form fields . . . . . . . . . . . . Field properties. . . . . . . . . . . Function invocations . . . . . . . . . . Function variables . . . . . . . . . . . Function parameters . . . . . . . . . . Implications of inOut and the related modifiers Function part in EGL source format . . . . . Generated output . . . . . . . . . . . Generated output (reference) . . . . . . . Generation Results view . . . . . . . . . in operator . . . . . . . . . . . . . Examples with a one-dimensional array . . Examples with a multidimension array . . . Indexed record part in EGL source format . . . I/O error values . . . . . . . . . . . duplicate . . . . . . . . . . . . . endOfFile. . . . . . . . . . . . . format . . . . . . . . . . . . . . noRecordFound . . . . . . . . . . unique . . . . . . . . . . . . . isa operator . . . . . . . . . . . . . Java runtime properties (details) . . . . . . Java wrapper classes . . . . . . . . . . Overview of how to use the wrapper classes The program wrapper class. . . . . . . The set of parameter wrapper classes . . . The set of substructured-item-array wrapper classes . . . . . . . . . . . . . . Dynamic array wrapper classes . . . . . Naming conventions for Java wrapper classes Data type cross-reference . . . . . . . JDBC driver requirements in EGL . . . . . Keywords . . . . . . . . . . . . . add. . . . . . . . . . . . . . . call . . . . . . . . . . . . . . . case . . . . . . . . . . . . . . close . . . . . . . . . . . . . . continue . . . . . . . . . . . . . converse . . . . . . . . . . . . . delete . . . . . . . . . . . . . . display . . . . . . . . . . . . . execute . . . . . . . . . . . . . exit . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

437 439 439 440 441 443 444 445 446 453 454 455 456 458 458 459 461 461 462 463 465 467 469 473 474 477 478 479 479 480 481 482 483 484 484 485 485 485 486 487 496 496 498 499

. 500 . 501 503 . 503 . 504 . 505 . 505 . 507 . 510 . 511 . 514 . 514 . 515 . 517 . 517 . 521

vi

EGL Reference Guide

for . . . . . . . . . . . . . . forEach . . . . . . . . . . . . forward . . . . . . . . . . . . freeSQL . . . . . . . . . . . . get . . . . . . . . . . . . . . get absolute . . . . . . . . . . . get current . . . . . . . . . . . get first . . . . . . . . . . . . get last . . . . . . . . . . . . get next . . . . . . . . . . . . get previous . . . . . . . . . . . get relative . . . . . . . . . . . goTo . . . . . . . . . . . . . if, else . . . . . . . . . . . . . move . . . . . . . . . . . . . open . . . . . . . . . . . . . prepare . . . . . . . . . . . . print . . . . . . . . . . . . . replace . . . . . . . . . . . . return . . . . . . . . . . . . . set . . . . . . . . . . . . . . show . . . . . . . . . . . . . transfer . . . . . . . . . . . . try . . . . . . . . . . . . . . while . . . . . . . . . . . . . Library (generated output) . . . . . . . Library part in EGL source format . . . . like operator. . . . . . . . . . . . Linkage properties file (details) . . . . . How the linkage properties file is identified run time . . . . . . . . . . . . Format of the linkage properties file . . . matches operator . . . . . . . . . . Message customization for EGL Java run time MQ record part in EGL source format . . . MQ record properties. . . . . . . . . Queue name. . . . . . . . . . . Include message in transaction . . . . Open input queue for exclusive use . . . Options records for MQ records . . . . Name aliasing . . . . . . . . . . . Changes to EGL identifiers in JSP files and generated Java beans . . . . . . . . How names are aliased . . . . . . . How Java names are aliased . . . . . How Java wrapper names are aliased . . Naming conventions . . . . . . . . . Operators and precedence . . . . . . . Output of Java program generation . . . . Output of Java wrapper generation . . . . Example . . . . . . . . . . . . PageHandler part in EGL source format . . Properties of the page handler . . . . . pfKeyEquate . . . . . . . . . . . Primitive field-level properties. . . . . . Program data other than parameters . . . Program parameters . . . . . . . . . Program part in EGL source format . . . . Basic program in EGL source format . . Text UI program in EGL source format . . Program part properties . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . at . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

524 525 527 528 528 534 536 537 539 540 545 548 550 551 552 558 562 564 564 567 567 577 578 579 579 580 580 586 587 588 588 590 592 593 595 595 595 595 595 597 598 599 599 600 602 603 605 606 607 609 612 614 615 619 622 624 625 627 630

Input form . . . . . . . . . . . . Input record . . . . . . . . . . . . Record and file type cross-reference . . . . . Properties that support variable-length records . Variable-length records with the lengthItem property . . . . . . . . . . . . . Variable-length records with the numElementsItem property . . . . . . . Variable-length records with both lengthItem and numElementsItem properties . . . . . Variable-length records passed on a call or transfer . . . . . . . . . . . . . Relative record part in EGL source format . . . Run unit . . . . . . . . . . . . . . resultSetID . . . . . . . . . . . . . Serial record part in EGL source format . . . SQL data codes and EGL host variables . . . Variable and fixed-length columns . . . . Compatibility of SQL data types and EGL primitive types . . . . . . . . . . . VARCHAR, VARGRAPHIC, and the related LONG data types . . . . . . . . . . DATE, TIME, and TIMESTAMP . . . . . SQL record internals . . . . . . . . . . SQL record part in EGL source format . . . . Structure field in EGL source format. . . . . Substrings . . . . . . . . . . . . . Syntax diagram. . . . . . . . . . . . Using C functions with EGL . . . . . . . BIGINT functions for C . . . . . . . . C data types and EGL primitive types . . . DATE functions for C . . . . . . . . DATETIME and INTERVAL functions for C . DECIMAL functions for C . . . . . . . Invoking a C Function from an EGL Program Receiving values from EGL . . . . . . . Returning values to EGL . . . . . . . Console Library . . . . . . . . . . . ConsoleLib.activateWindow . . . . . . ConsoleLib.activateWindowByName . . . . ConsoleLib.cancelArrayDelete . . . . . . ConsoleLib.cancelArrayInsert . . . . . . ConsoleLib.clearActiveForm . . . . . . ConsoleLib.clearFields . . . . . . . . ConsoleLib.clearWindow . . . . . . . ConsoleLib.clearWindowByName. . . . . ConsoleLib.closeActiveWindow . . . . . ConsoleLib.closeWindow . . . . . . . ConsoleLib.closeWindowByName . . . . ConsoleLib.currentArrayDataLine . . . . ConsoleLib.currentArrayScreenLine . . . . ConsoleLib.displayAtLine . . . . . . . ConsoleLib.displayAtPosition . . . . . . ConsoleLib.displayError . . . . . . . . ConsoleLib.displayFields . . . . . . . ConsoleLib.displayFieldsByName. . . . . ConsoleLib.displayLineMode . . . . . . ConsoleLib.displayMessage . . . . . . . ConsoleLib.drawBox . . . . . . . . . ConsoleLib.drawBoxWithColor . . . . . ConsoleLib.getKey. . . . . . . . . .Contents

. . . .

632 632 633 633

. 633 . 634 . 635 . . . . . . . 635 635 637 637 638 639 639

. 640 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641 641 642 642 645 647 648 650 653 654 655 655 656 657 659 662 663 668 668 668 669 669 669 670 670 670 671 671 671 672 672 672 672 673 673 674 674 674 675 675

vii

ConsoleLib.getKeyCode . . . . . . . ConsoleLib.getKeyName . . . . . . ConsoleLib.gotoField . . . . . . . . ConsoleLib.gotoFieldByName . . . . . ConsoleLib.gotoMenuItem . . . . . . ConsoleLib.gotoMenuItemByName . . . ConsoleLib.hideErrorWindow . . . . . ConsoleLib.hideMenuItem . . . . . . ConsoleLib.hideMenuItemByName . . . ConsoleLib.isCurrentField . . . . . . ConsoleLib.isCurrentFieldByName . . . ConsoleLib.isFieldModified . . . . . . ConsoleLib.isFieldModifiedByName . . . ConsoleLib.lastKeyTyped . . . . . . ConsoleLib.nextField . . . . . . . . ConsoleLib.openWindow . . . . . . ConsoleLib.openWindowByName . . . ConsoleLib.openWindowWithForm . . . ConsoleLib.openWindowWithFormByName ConsoleLib.previousField . . . . . . ConsoleLib.promptLineMode . . . . . ConsoleLib.scrollDownLines . . . . . ConsoleLib.scrollDownPage . . . . . ConsoleLib.scrollUpLines . . . . . . ConsoleLib.scrollUpPage . . . . . . ConsoleLib.setArrayLine . . . . . . ConsoleLib.setCurrentArrayCount . . . ConsoleLib.showHelp . . . . . . . ConsoleLib.showMenuItem . . . . . . ConsoleLib.showMenuItemByName . . . activeForm . . . . . . . . . . . activeWindow . . . . . . . . . . commentLine . . . . . . . . . . currentDisplayAttrs . . . . . . . . cursorWrap . . . . . . . . . . . defaultDisplayAttributes. . . . . . . defaultInputAttributes . . . . . . . deferInterrupt . . . . . . . . . . deferQuit . . . . . . . . . . . . definedFieldOrder . . . . . . . . . errorLine . . . . . . . . . . . . errorWindow . . . . . . . . . . errorWindowVisible . . . . . . . . formLine . . . . . . . . . . . . interruptRequested . . . . . . . . key_accept . . . . . . . . . . . key_deleteLine . . . . . . . . . . key_help . . . . . . . . . . . . ConsoleLib.key_insertLine . . . . . . key_interrupt . . . . . . . . . . key_pageDown . . . . . . . . . . key_pageUp . . . . . . . . . . . key_quit . . . . . . . . . . . . menuLine . . . . . . . . . . . messageLine . . . . . . . . . . . messageResource . . . . . . . . . promptLine . . . . . . . . . . . quitRequested . . . . . . . . . . screen . . . . . . . . . . . . . sqlInterrupt . . . . . . . . . . . currentRowAttrs . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

675 676 676 676 677 677 677 677 678 678 678 679 679 679 680 680 680 680 681 681 681 682 682 682 682 683 683 683 683 684 684 684 684 685 685 685 686 686 686 686 687 687 687 688 688 688 688 689 689 689 689 690 690 690 691 691 691 691 692 692 692

EGL library ConverseLib . . . . . . ConverseLib.clearScreen . . . . . . ConverseLib.displayMsgNum . . . . ConverseLib.fieldInputLength . . . . ConverseLib.pageEject . . . . . . ConverseLib.validationFailed . . . . DATETIMELIB . . . . . . . . . . DateTimeLib.currentDate . . . . . DateTimeLib.currentTime . . . . . DateTimeLib.currentTimeStamp . . . DateTimeLib.dateOf . . . . . . . DateTimeLib.dateValue . . . . . . DateTimeLib.dateValueFromGregorian . DateTimeLib.dateValueFromJulian . . DateTimeLib.dayOf . . . . . . . DateTimeLib.extend . . . . . . . DateTimeLib.intervalValue . . . . . DateTimeLib.intervalValueWithPattern . DateTimeLib.mdy . . . . . . . . DateTimeLib.monthOf . . . . . . DateTimeLib.timeOf . . . . . . . DateTimeLib.timestampFrom . . . . DateTimeLib.timeStampValue . . . . DateTimeLib.timeStampValueWithPattern DateTimeLib.timeValue . . . . . . DateTimeLib.weekdayOf . . . . . DateTimeLib.yearOf . . . . . . . EGL library J2EELib . . . . . . . . J2EELib.clearRequestAttr . . . . . J2EELib.clearSessionAttr . . . . . . J2EELib.getRequestAttr . . . . . . J2EELib.getSessionAttr . . . . . . J2EELib.setRequestAttr . . . . . . J2EELib.setSessionAttr . . . . . . EGL library JavaLib . . . . . . . . Java access functions . . . . . . . JavaLib.getField . . . . . . . . JavaLib.invoke . . . . . . . . . JavaLib.isNull . . . . . . . . . JavaLib.isObjID . . . . . . . . . JavaLib.qualifiedTypeName. . . . . JavaLib.remove . . . . . . . . . JavaLib.removeAll . . . . . . . . JavaLib.setField. . . . . . . . . JavaLib.store . . . . . . . . . JavaLib.storeCopy . . . . . . . . JavaLib.storeField . . . . . . . . JavaLib.storeNew . . . . . . . . LOB Library . . . . . . . . . . . LobLib.attachBlobToFile . . . . . . LobLib.attachBlobToTempFile . . . . LobLib.attachClobToFile . . . . . . LobLib.attachClobToTempFile . . . . LobLib.freeBlob. . . . . . . . . LobLib.freeClob . . . . . . . . LobLib.getBlobLen . . . . . . . LobLib.getClobLen . . . . . . . LobLib.getStrFromClob . . . . . . LobLib.getSubStrFromClob . . . . . LobLib.loadBlobFromFile . . . . . LobLib.loadClobFromFile . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

693 693 693 694 694 695 695 696 697 697 698 698 698 699 699 699 700 700 701 701 702 702 702 703 703 704 704 704 705 705 706 706 707 707 708 708 715 717 720 721 722 723 724 724 726 728 729 730 732 734 734 734 735 735 735 735 736 736 736 737 737

viii

EGL Reference Guide

LobLib.setClobFromString . . . . LobLib.setClobFromStringAtPosition LobLib.truncateBlob . . . . . . LobLib.truncateClob . . . . . . LobLib.updateBlobToFile . . . . LobLib.updateClobToFile . . . . EGL library MathLib . . . . . . . mathLib.abs . . . . . . . . . mathLib.acos . . . . . . . . mathLib.asin . . . . . . . . mathLib.atan . . . . . . . . mathLib.atan2 . . . . . . . . mathLib.ceiling . . . . . . . . mathLib.compareNum . . . . . mathLib.cos . . . . . . . . . mathLib.cosh . . . . . . . . mathLib.exp . . . . . . . . . mathLib.floatingAssign . . . . . mathLib.floatingDifference . . . . mathLib.floatingMod . . . . . . mathLib.floatingProduct . . . . . mathLib.floatingQuotient . . . . mathLib.floatingSum . . . . . . mathLib.floor . . . . . . . . mathLib.frexp . . . . . . . . mathLib.Ldexp . . . . . . . . mathLib.log . . . . . . . . . mathLib.log10 . . . . . . . . mathLib.maximum . . . . . . mathLib.minimum. . . . . . . mathLib.modf . . . . . . . . mathLib.pow . . . . . . . . mathLib.precision . . . . . . . mathLib.round . . . . . . . . mathLib.sin . . . . . . . . . mathLib.sinh . . . . . . . . mathLib.sqrt . . . . . . . . . mathLib.tan . . . . . . . . . mathLib.tanh . . . . . . . . recordName.resourceAssociation . . . Definition considerations . . . . Example . . . . . . . . . . Report library . . . . . . . . . ReportLib.addReportParameter . . ReportLib.resetReportParameters . . ReportLib.fillReport . . . . . . ReportLib.exportReport . . . . . EGL Library StrLib . . . . . . . strLib.characterAsInt . . . . . . strLib.clip . . . . . . . . . strLib.compareStr . . . . . . . strLib.concatenate . . . . . . . strLib.concatenateWithSeparator . . strLib.copyStr . . . . . . . . strLib.findStr . . . . . . . . StrLib.formatDate . . . . . . . strLib.formatNumber . . . . . . StrLib.formatTime . . . . . . . StrLib.formatTimeStamp . . . . . strLib.getNextToken . . . . . . strLib.integerAsChar . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

737 738 738 738 739 739 739 741 742 742 743 743 744 744 745 745 745 746 746 747 747 748 748 749 749 749 750 750 751 751 751 752 752 753 754 754 755 755 755 756 756 757 758 758 759 760 760 761 763 763 764 765 766 766 768 769 769 770 771 771 773

strLib.lowercase . . . . . . strLib.setBlankTerminator . . . strLib.setNullTerminator . . . . strLib.setSubStr . . . . . . . strLib.spaces. . . . . . . . strLib.strLen . . . . . . . . strLib.uppercase . . . . . . EGL library SysLib . . . . . . SysLib.beginDatabaseTransaction . sysLib.bytes . . . . . . . . sysLib.calculateChkDigitMod10 . sysLib.calculateChkDigitMod11 . sysLib.callCmd . . . . . . . sysLib.commit . . . . . . . sysLib.connect . . . . . . . sysLib.convert . . . . . . . SysLib.defineDatabaseAlias . . . sysLib.disconnect . . . . . . sysLib.disconnectAll . . . . . getCmdLineArg . . . . . . getCmdLineArgCount . . . . sysLib.getMessage . . . . . . sysLib.getProperty . . . . . . sysLib.loadTable . . . . . . sysLib.maximumSize . . . . . sysLib.queryCurrentDatabase . . sysLib.rollback . . . . . . . sysLib.setCurrentDatabase . . . sysLib.setError . . . . . . . sysLib.setLocale . . . . . . sysLib.setRemoteUser . . . . sysLib.size . . . . . . . . sysLib.startCmd . . . . . . sysLib.startTransaction . . . . sysLib.unloadTable . . . . . sysLib.verifyChkDigitMod10 . . sysLib.verifyChkDigitMod11 . . sysLib.wait . . . . . . . . EGL library VGLib . . . . . . VGLib.connectionService . . . VGLib.getVAGSysType . . . . System variables . . . . . . . ConverseVar.commitOnConverse . ConverseVar.eventKey . . . . ConverseVar.printerAssociation . ConverseVar.segmentedMode . . ConverseVar.validationMsgNum . sysVar.arrayIndex . . . . . . sysVar.callConversionTable . . . sysVar.errorCode . . . . . . sysVar.formConversionTable . . sysVar.overflowIndicator . . . sysVar.returnCode . . . . . . sysVar.sessionID . . . . . . sysVar.sqlca . . . . . . . . sysVar.sqlcode . . . . . . . sysVar.sqlState . . . . . . . sysVar.systemType . . . . . . sysVar.terminalID . . . . . . sysVar.transactionID . . . . . sysVar.transferName . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

773 774 774 774 775 776 776 776 778 779 779 780 781 782 783 786 787 788 789 789 790 790 791 791 792 792 793 793 794 795 796 796 797 798 798 799 800 801 802 802 805 807 811 811 812 814 815 815 816 818 818 819 820 820 821 822 823 823 824 825 825

Contents

ix

sysVar.userID . . . . . . . . . . VGVar.currentFormattedGregorianDate . . VGVar.currentFormattedJulianDate . . . VGVar.currentFormattedTime . . . . . VGVar.currentGregorianDate . . . . . VGVar.currentJulianDate. . . . . . . VGVar.currentShortGregorianDate . . . VGVar.currentShortJulianDate . . . . . VGVar.handleHardIOErrors . . . . . VGVar.handleOverflow . . . . . . . VGVar.handleSysLibraryErrors . . . . VGVar.mqConditionCode . . . . . . VGVar.sqlerrd . . . . . . . . . . VGVar.sqlerrmc. . . . . . . . . . VGVar.sqlIsolationLevel . . . . . . . VGVar.sqlWarn . . . . . . . . . . transferToTransaction element . . . . . . alias in transfer-related linkage elements . externallyDefined in transferToTransaction element . . . . . . . . . . . . Use declaration . . . . . . . . . . . Background . . . . . . . . . . . In a program or library part . . . . . In a formGroup part . . . . . . . . In a pageHandler part . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . .

826 826 827 828 829 829 830 830 831 831 832 833 834 834 835 836 837 837 838 838 838 839 841 841

EGL Java runtime error codes . . . . 843EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code CSO7000E CSO7015E CSO7016E CSO7020E CSO7021E CSO7022E CSO7023E CSO7024E CSO7026E CSO7045E CSO7050E CSO7060E CSO7080E CSO7160E CSO7161E CSO7162E CSO7163E CSO7164E CSO7165E CSO7166E CSO7360E CSO7361E CSO7488E CSO7489E CSO7610E CSO7620E CSO7630E CSO7640E CSO7650E CSO7651E CSO7652E CSO7653E CSO7654E CSO7655E . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 844 845 845 845 845 846 846 846 846 847 847 847 847 848 848 848 848 849 849 849 849 850 850 851 851 851 851 852 852 852 853 853 854 855

EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java

run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time

error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error

code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code

CSO7656E CSO7657E CSO7658E CSO7659E CSO7669E CSO7670E CSO7671E CSO7816E CSO7819E CSO7831E CSO7836E CSO7840E CSO7885E CSO7886E CSO7955E CSO7957E CSO7958E CSO7966E CSO7968E CSO7970E CSO7975E CSO7976E CSO7977E CSO7978E CSO7979E CSO8000E CSO8001E CSO8002E CSO8003E CSO8004E CSO8005E CSO8100E CSO8101E CSO8102E CSO8103E CSO8104E CSO8105E CSO8106E CSO8107E CSO8108E CSO8109E CSO8110E CSO8180E CSO8181E CSO8182E CSO8200E CSO8201E CSO8202E CSO8203E CSO8204E EGL0650E EGL0651E EGL0652E EGL0653E EGL0654E EGL0655E EGL0656E EGL0657E VGJ0001E VGJ0002E VGJ0003E

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

855 856 856 857 857 857 858 858 858 858 859 859 859 860 860 860 861 861 861 862 862 862 862 863 863 863 863 864 864 864 864 865 865 865 866 866 866 867 867 867 868 868 868 868 869 869 869 869 870 870 870 870 871 871 871 871 872 872 872 872 873

x

EGL Reference Guide

EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java

run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time

error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error

code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code

VGJ0004I VGJ0005I VGJ0006E VGJ0007E VGJ0008E VGJ0009E VGJ0010E VGJ0011E VGJ0012E VGJ0013E VGJ0014E VGJ0015E VGJ0016E VGJ0017E VGJ0018E VGJ0019E VGJ0020E VGJ0021E VGJ0050E VGJ0055E VGJ0056E VGJ0057E VGJ0058E VGJ0060E VGJ0062E VGJ0064E VGJ0100E VGJ0104E VGJ0105E VGJ0106E VGJ0108E VGJ0109E VGJ0110E VGJ0111E VGJ0112E VGJ0113E VGJ0114E VGJ0115E VGJ0116E VGJ0117E VGJ0118E VGJ0119E VGJ0120E VGJ0121E VGJ0122E VGJ0123E VGJ0124E VGJ0125E VGJ0126E VGJ0127E VGJ0140E VGJ0141E VGJ0142E VGJ0143E VGJ0144E VGJ0145E VGJ0146E VGJ0147E VGJ0160E VGJ0161E VGJ0162E

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

873 874 874 874 875 875 875 875 876 876 876 876 876 877 877 877 877 878 878 878 878 879 879 879 879 880 880 880 880 881 881 881 881 882 882 882 882 883 883 883 884 884 884 884 884 885 885 885 885 886 886 886 886 886 887 887 887 887 888 888 888

EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java

run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time

error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error

code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code

VGJ0163E VGJ0164E VGJ0165E VGJ0166E VGJ0167E VGJ0168E VGJ0200E VGJ0201E VGJ0202E VGJ0203E VGJ0204E VGJ0215E VGJ0216E VGJ0217E VGJ0218E VGJ0250E VGJ0300E VGJ0301E VGJ0302E VGJ0303E VGJ0304E VGJ0305E VGJ0306E VGJ0307E VGJ0308E VGJ0315E VGJ0320E VGJ0330E VGJ0331E VGJ0350E VGJ0351E VGJ0352E VGJ0400E VGJ0401E VGJ0402E VGJ0403E VGJ0416E VGJ0450E VGJ0500E VGJ0502E VGJ0503E VGJ0504E VGJ0505E VGJ0506E VGJ0507E VGJ0508E VGJ0510E VGJ0511E VGJ0512E VGJ1234E VGJ1234E VGJ0516E VGJ0517E VGJ0600E VGJ0601E VGJ0603E VGJ0604E VGJ0607E VGJ0608E VGJ0609I VGJ0610I

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

889 889 889 889 890 890 890 891 891 891 892 892 892 893 893 893 894 895 895 896 897 897 898 899 899 900 900 901 901 901 902 902 902 902 902 903 903 904 904 904 904 905 905 905 905 906 906 906 906 907 907 907 907 908 908 908 909 909 909 910 910

Contents

xi

EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java

run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time

error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error

code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code

VGJ0611E VGJ0612I VGJ0614E VGJ0615E VGJ0616E VGJ0617E VGJ0700E VGJ0701E VGJ0702E VGJ0703E VGJ0705E VGJ0706E VGJ0707E VGJ0708E VGJ0709E VGJ0710E VGJ0711E VGJ0712E VGJ0713E VGJ0750E VGJ0751E VGJ0752E VGJ0754E VGJ0755E VGJ0770E VGJ0800E VGJ0801E VGJ0802E VGJ0901E VGJ0902E VGJ0903E VGJ0904E VGJ0905E VGJ0906E VGJ0907E VGJ0908E VGJ0909E VGJ0910E VGJ0911E VGJ0912E VGJ0913E VGJ0914E VGJ0915E VGJ0916E VGJ0917E VGJ0918E VGJ0920E VGJ0921E VGJ0922E VGJ0923E VGJ0924E VGJ0925E VGJ0926E VGJ0927E VGJ0928E VGJ0929E VGJ0930E VGJ0931E VGJ0932E VGJ0933E VGJ1000E

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

910 910 911 911 911 912 912 912 912 913 913 913 914 914 914 914 915 915 915 915 916 916 917 917 918 918 918 918 919 919 919 919 920 920 920 920 921 921 921 921 921 922 922 922 922 923 923 923 923 923 924 924 924 924 925 925 925 925 926 926 926

EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java

run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time

error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error error

code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code code

VGJ1001E VGJ1002E VGJ1003E VGJ1004E VGJ1005E VGJ1006E VGJ1007E VGJ1008E VGJ1009E VGJ1148E VGJ1149E VGJ1150E VGJ1151E VGJ1152E VGJ1153E VGJ1154E VGJ1155E VGJ1156E VGJ1157E VGJ1158E VGJ1159E VGJ1160E VGJ1161E VGJ1162E VGJ1163E VGJ1164E VGJ1165E VGJ1166E VGJ1167E VGJ1168E VGJ1169E VGJ1170E VGJ1171E VGJ1172E VGJ1173E VGJ1174E VGJ1175E VGJ1176E VGJ1177E VGJ1178E VGJ1179E VGJ1180E VGJ1181E VGJ1182E VGJ1183E VGJ1184E VGJ1185E VGJ1186E VGJ1187E VGJ1188E VGJ1189E VGJ1190E VGJ1191E VGJ1192E VGJ1193E VGJ1194E VGJ1195E VGJ1196E VGJ1197E VGJ1198E VGJ1199E

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

926 927 927 927 928 928 928 929 929 929 929 930 930 930 930 931 931 931 931 931 932 932 932 932 933 933 933 933 933 934 934 934 934 934 935 935 935 935 936 936 936 936 937 937 937 937 937 938 938 938 938 938 939 939 939 939 940 940 940 940 940

xii

EGL Reference Guide

EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java

run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time

error error error error error error error error error error error error error error error error error error error error error error error error

code code code code code code code code code code code code code code code code code code code code code code code code

VGJ1200E VGJ1201E VGJ1202E VGJ1203E VGJ1204E VGJ1205E VGJ1206E VGJ1207E VGJ1208E VGJ1209E VGJ1210E VGJ1211E VGJ1212E VGJ1213E VGJ1214E VGJ1215E VGJ1216E VGJ1217W VGJ1218W VGJ1290E VGJ1301E VGJ1302E VGJ1303E VGJ1304E

. . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . .

941 941 941 941 942 942 942 942 942 943 943 943 943 943 944 944 944 944 945 945 945 945 946 946

EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java EGL Java

run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time run-time

error error error error error error error error error error error error error error error error

code code code code code code code code code code code code code code code code

VGJ1305E VGJ1306E VGJ1401E VGJ1402E VGJ1403E VGJ1404E VGJ1405E VGJ1406E VGJ1407E VGJ1408E VGJ1409E VGJ1410E VGJ1411E VGJ1412E VGJ9900E VGJ9901E

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

946 946 947 947 947 947 947 948 948 948 948 948 949 949 949 950

Appendix. Notices . . . . . . . . . 951Programming interface information . Trademarks and service marks . . . . . . . . . . . 953 . 953

Index . . . . . . . . . . . . . . . 955

Contents

xiii

xiv

EGL Reference Guide

OverviewIntroduction to EGLEnterprise Generation Language (EGL) is a development environment and programming language that lets you write full-function applications quickly, freeing you to focus on the business problem your code is addressing rather than on software technologies. You can use similar I/O statements to access different types of external data stores, for example, whether those data stores are files, relational databases, or message queues. The details of Java and J2EE are hidden from you, too, so you can deliver enterprise data to browsers even if you have minimal experience with Web technologies. After you code an EGL program, you generate it to create Java source; then EGL prepares the output to produce executable objects. EGL also can provide these services: v Places the source on a deployment platform outside of the development platform v Prepares the source on the deployment platform v Sends status information from the deployment platform to the development platform, so you can check the results EGL even produces output that facilitates the final deployment of the executable objects. An EGL program written for one target platform can be converted easily for use on another. The benefit is that you can code in response to current platform requirements, and many details of any future migration are handled for you. EGL also can produce multiple parts of an application system from the same source. Related concepts Development process on page 7 EGL projects, packages, and files on page 11 Generated output on page 477 Parts on page 15 Run-time configurations on page 7 Related tasks Creating an EGL Web project on page 135 Related reference EGL editor on page 433 EGL source format on page 440

Whats new in the EGL 6.0 iFixNote: EGL provides services to help you convert old code to code that works with the EGL 6.0 iFix: v If you used a pre-6.0 version of EGL to create a Web application that is based on JavaServer Faces, do as follows in the workbench-1. Click Help > Rational Help Copyright IBM Corp. 1996, 2004

1

2. In the Search text box of the help system, type at least the initial characters in this string: Migrating JavaServer Faces resources in a Web project 3. Click GO 4. Click Migrating JavaServer Faces resources in a Web project and follow the directions in that topic v For other details on migrating code from EGL 6.0 or from an earlier version, see Migrating EGL code to the EGL 6.0 iFix. v If you are migrating code from Informix 4GL or from VisualAge Generator, see Sources of additional information on EGL. The version 6.0 iFix represents a significant upgrade to the EGL language: v Introduces the EGL report handler, which contains customized functions that are invoked at different times during execution of a JasperReports design file. The data returned from each function is included in your output report, which can be rendered in PDF, XML, text, or HTML format. The technology is an improvement on the reporting capability that was available in Informix 4GL. v Introduces the EGL console UI, which is a technology for creating a character-based interface that allows an immediate, keystroke-driven interaction between the user and an EGL-generated Java program. The technology is an improvement on the dynamic user interface that was available in Informix 4GL. v Provides new flexibility for code development- Allows you to declare new types of variables: - A reference variable, which does not contain business data but points to such data. - A variable that contains or refers to a large quantity of data; specifically, to a binary large object (BLOB) or a character large object (CLOB). - A string variable, which refers to a Unicode string whose length varies at run time. - An ANY-typed variable, which can contain business data of any primitive type. Allows you to include function invocations in expressions. Allows you to reference a record without having development-time knowledge of the size or other characteristics of the record or of the fields in that record. Each field can itself refer to a record. Expands support for dynamic arrays, which can now have multiple dimensions. Introduces two new kinds of data collections: - A dictionary, which is composed of a set of key-and-value entries. You can add, delete, and retrieve entries at runtime, and the value in a given entry can be of any type. - An arrayDictionary, which is composed of a set of one-dimensional arrays, each of any type. You access the content of an arrayDictionary by retrieving the same-numbered elements across all the arrays. Expands the number of system functions for various purposes: - To improve datetime processing, runtime message handling, and retrieval of user-defined Java runtime properties. - To support the new functionality related to reports, console UI, BLOB, and CLOB.

2

EGL Reference Guide

Provides better support for exception handling, for data initialization, and for DLL access. v Provides a new wizard to create EGL report handlers. v Allows you to customize a Web-page template for use with the Data Parts and Pages wizard, which quickly provides a Web application for accessing a single relational database. v Allows you to create code that reflects the runtime behavior of Informix 4GL in relation to null processing and database commits. Related concepts EGL-to-EGL migration on page 114 Sources of additional information on EGL on page 10 Whats new in EGL version 6.0

Whats new in EGL version 6.0Note: If you used an earlier version of EGL to create a Web application that is based on JavaServer Faces, do as follows in the workbench: 1. Click Help > Rational Help 2. In the Search text box of the help system, type at least the initial characters in this string: Migrating JavaServer Faces resources in a Web project 3. Click GO 4. Click Migrating JavaServer Faces resources in a Web project and follow the directions in that topic Version 6.0 increases the power of the EGL language: v Processing of relational databases has improved- New wizards let you quickly do as follows: - Create data parts directly from relational database tables - Create Web applications that create, read, update, and delete table rows from such tables New system functions are available: - sysLib.loadTable loads information from a file and inserts it into a relational database table. - sysLib.unloadTable unloads information from a relational database table and inserts it into a file. If you are generating Java code, you can access SQL database rows in a cursor by navigating to the next row (as was always true); by navigating to the first, last, previous, or current row; or by specifying an absolute or relative position in the cursor. The forEach statement allows you to loop easily through the rows of an SQL result set. The freeSQL statement frees any resources associated with a dynamically prepared SQL statement, closing any open cursor associated with that SQL statement. v String processing has improved- You can specify substrings in a text expression, as in the following example:

Overview

3

myItem01 = "1234567890"; // myItem02 = "567" myItem02 = myItem01[5:7];

You can specify a back space, form feed, or tab in a text literal You can compare strings against either of two pattern types: - An SQL-type pattern, which includes the LIKE keyword. An example is as follows:// variable myVar01 is the string expression // whose contents will be compared to a like criterion myVar01 = "abcdef"; // the next logical expression evaluates to "true" if (myVar01 like "a_c%") ; end

- A regular-expression pattern. An example is as follows:// variable myVar01 is the string expression // whose contents will be compared to a match criterion myVar01 = "abcdef"; // the next logical expression evaluates to "true" if (myVar01 matches "a?c*") ; end

You can use these text-formatting system functions: strLib.characterAsInt Converts a character string into an integer string strLib.clip Deletes trailing blank spaces and nulls from the end of returned character strings strLib.formatNumber Returns a number as a formatted string strLib.integerAsChar Converts an integer string into a character string strLib.lowercase Converts all uppercase values in a character string to lowercase values strLib.spaces Returns a string of a specified length. strLib.upperCase Converts all lowercase values in a character string to uppercase values. v You can declare variables and structure items of new types. The new numeric types are as follows-FLOAT Concerns an 8-byte area that stores a double-precision floating-point numbers with as many as 16 significant digits MONEY Concerns a currency amount that is stored as a fixed-point decimal number up to as many as 32 significant digits

4

EGL Reference Guide

SMALLFLOAT Concerns a 4-byte area that stores a single-precision floating-point number with as many as 8 significant digits The new datetime types are as follows-DATE Concerns a specific calendar date, as represented in 8 single-byte digits INTERVAL Concerns a span of time that is represented in 1 to 21 single-byte digits and is associated with a mask such as hhmmss for hours, minutes, and seconds TIME Concerns an instance in time, as represented in 6 single-byte digits TIMESTAMP Concerns an instance in time that is represented in 1 to 20 single-byte digits and is associated with a mask such as yyyyMMddhh for year, month, day, and hour v The syntax provides additional options- You could always reference an element of a structure-item array as follows, but in light of iFix changes, you are asked to avoid this syntax:mySuperItem.mySubItem.mySubmostItem[4,3,1]

The following syntax is strongly recommended-mySuperItem[4].mySubItem[3].mySubmostItem[1]

You can use a comma-delineated list of identifiers when you declare parameters, use-statement entries, set-statement entries, or variables, as in this example:myVariable01, myVariable02 myPart;

In a numeric expression, you can now specify an exponent by preceding a value with a double asterisk (**), so that (for example) 8 cubed is 8**3 You can now specify expressions that each resolve to a date, time, timestamp, or interval; and date arithmetic lets you do various tasks such as calculating the number of minutes between two dates The following additions also allow for date and time processing: - DateTimeLib.currentTime and DateTimeLib.currentTimeStamp are system variables that reflect the current time - New formatting functions are available for dates (StrLib.formatDate), times (StrLib.formatTime), and timestamps (sysLib.TimeStamp) - Each of the following functions let you convert a series of characters to an item of a datetime type so that the item can be used in a datetime expression: v DateTimeLib.dateValue returns a date v DateTimeLib.timeValue returns a time v DateTimeLib.timeStampValue returns a timestamp associated with a particular mask such as yyyyMMdd v DateTimeLib.intervalValue returns an interval associated with a particular mask such as yyyyMMdd v DateTimeLib.extendDateTimeValue accepts a date, time, or timestamp and extends it to an item associated with a particular mask such as yyyyMMddmmss You can use these new, general statements:Overview

5

- The for statement includes a statement block that runs in a loop for as many times as a test evaluates to true. The test is conducted at the beginning of the loop and indicates whether the value of a counter is within a specified range. - The continue statement transfers control to the end of a for, forEach, or while statement that itself contains the continue statement. Execution of the containing statement continues or ends depending on the logical test that is conducted at the start of the containing statement. You can run a system command synchronously (by issuing the function sysLib.callCmd) or asynchronously (by issuing the function sysLib.startCmd). You can use two new functions that let you access command-line arguments in a loop - sysLib.callCmdLineArgCount returns the number of arguments - sysLib.callCmdLineArg returns the argument that resides in a specified position in the list of arguments You can now specify a case statement in which each clause is associated with a different logical expression. If you use this new syntax, the EGL run time executes the statements that are associated with the first true expression:case when (myVar01 conclusion when (myVar01 conclusion otherwise conclusion end == myVar02) = "okay"; == myVar03) = "need to investigate"; = "not okay";

You can control whether a function parameter is used only for input, only for output, or for both; and you can avoid the choice by accepting the default setting, which is the unrestricted for both. You can now specify a datetime, text, or numeric expression that is more complex than a single item or constant, in these cases: - When you specify the value that is provided to the operating system by a return statement - When you specify an argument that is passed in either a function invocation or a program call; however, the characteristics of the receiving parameter must be known at generation time You can now specify a complex numeric expression when exiting from the program The development environment has improved as well: v Two new features give you the ability to access parts quickly, even as your code grows in complexity- The Parts Reference view lets you display a hierarchical list of the EGL parts that are referenced by a program, library, or page handler; and from that list, you can access any of the referenced parts The EGL search mechanism lets you specify a search criterion to access a set of parts or variables in your workspace or in a subset of your projects v Finally, the EGL Web perspective has been eliminated in favor of the widely used Web perspective. Related concepts EGL-to-EGL migration on page 114

6

EGL Reference Guide

Sources of additional information on EGL on page 10 Whats new in the EGL 6.0 iFix on page 1

Development processYour work with EGL includes the following steps: Setup You set up a work environment; for example, you set preferences and create projects. Create and open EGL files You begin to create the source code. Declaration You create and specify the details of your code. Validation At various times (such as when you save a file), EGL reviews your declarations and indicates whether they are syntactically correct and (to some extent) whether they are internally consistent. Debugging You can interact with a built-in debugger to ensure that your code fulfills your requirements. Generation EGL validates your declarations and creates output, including source code. Preparation EGL prepares the source code to produce executable objects. In some cases this step places the source code on a deployment platform outside of the development platform, prepares the source code on the deployment platform, and sends a results file from the deployment platform to the development platform. Deployment EGL produces output that makes deployment of the executable objects easier. Related concepts EGL debugger on page 281 Generation of Java code into a project on page 321 Introduction to EGL on page 1 Related tasks Processing Java code that is generated into a directory on page 332 Setting up the J2EE run-time environment for EGL-generated code on page 348 Related reference EGL editor on page 433 EGL source format on page 440

Run-time configurationsEGL allows you to generate a Java program for any of several supported platforms. You can deploy the program outside of J2EE or in the context of any of the following J2EE containers-v J2EE application client v J2EE Web applicationOverview

7

v EJB container; in this case, you also generate an EJB session bean In addition, EGL provides a way to define a Web application that has the following characteristics: v Delivers graphical pages to Web browsers v Is able to store and retrieve data for a potentially large number of users v Is embedded in a Java-based framework called JavaServer Faces For details on this specialized support for Web applications, see PageHandler part. Finally, you can use EGL to generate a Java wrapper, as described in the next section.

Use of a Java wrapperThe EGL-generated Java wrapper is a set of classes that let you invoke an EGL-generated program from non-EGL-generated Java code; for example, from an action class in a Struts- or JSF-based J2EE web application or from a non-J2EE Java program. The Java-to-EGL integration task is as follows: 1. Generate Java wrapper classes, which are specific to a generated program 2. Incorporate those wrapper classes into the non-generated Java code 3. From the non-generated Java code, invoke the wrapper-class methods to make the actual call and to convert data between these two formats: v The data-type formats used by Java v The primitive-type formats required when passing data to and from the EGL-generated program

Valid callsThe next table shows the valid calls to or from the EGL-generated code.Calling object An EGL-generated Java wrapper in a Java class that is outside of J2EE Called object An EGL-generated Java program (non-J2EE) An EGL-generated Java program in a J2EE application client An EGL-generated EJB session bean A CICS COBOL program that was generated by VisualAge Generator An EGL-generated Java wrapper in a J2EE application client An EGL-generated Java program (non-J2EE) An EGL-generated Java program in a J2EE application client An EGL-generated EJB session bean A CICS COBOL program that was generated by VisualAge Generator

8

EGL Reference Guide

Calling object An EGL-generated Java wrapper in a J2EE Web application

Called object An EGL-generated Java program (non-J2EE) An EGL-generated Java program in a J2EE application client An EGL-generated Java program in the same J2EE Web application An EGL-generated EJB session bean A CICS COBOL program that was generated by VisualAge Generator

An EGL-generated Java program that is outside of J2EE

An EGL-generated Java program (non-J2EE) An EGL-generated Java program in a J2EE application client An EGL-generated EJB session bean A CICS COBOL program that was generated by VisualAge Generator A non-EGL-generated program that was written in C or C++ A non-generated program that was written in any language and runs under CICS

An EGL-generated Java program that is in a J2EE application client

An EGL-generated Java program (non-J2EE) An EGL-generated Java program in a J2EE application client An EGL-generated EJB session bean An EGL-generated CICS COBOL program A non-generated program that was written in any language and runs under CICS A non-generated program that was written in C or C++

An EGL-generated Java program in a J2EE Web application

An EGL-generated Java program (non-J2EE) An EGL-generated Java program in a J2EE application client An EGL-generated Java program in the same J2EE Web application An EGL-generated EJB session bean A CICS COBOL program that was generated in VisualAge Generator A non-generated program written in C or C++

An EGL-generated EJB session bean

An EGL-generated Java program (non-J2EE) An EGL-generated Java program in a J2EE application client An EGL-generated EJB session bean A CICS COBOL program that was generated by VisualAge Generator A non-generated program written in C or C++

Overview

9

Valid transfersThe next table shows the valid transfers to or from EGL-generated code.Transferring object An EGL-generated Java program that is outside of J2EE An EGL-generated Java program that is in a J2EE application client An EGL-generated Java program in a J2EE Web application Receiving object An EGL-generated Java program (non-J2EE) An EGL-generated Java program in the same J2EE application client An EGL-generated Java program in the same J2EE Web application

Related concepts Generated output on page 477 Introduction to EGL on page 1 Java program, page handler, and library on page 326 Java wrapper on page 302 PageHandler part on page 200 Related tasks Setting up the J2EE run-time environment for EGL-generated code on page 348

Sources of additional information on EGLThe most recent copy of this document is at the following Web site:http://www.ibm.com/developerworks/rational/library/egldoc.html

For details on migrating source code written in VisualAge Generator, see the VisualAge Generator to EGL Migration Guide (file vagenmig.pdf), which is on the Web site mentioned earlier and in the help system section called Installing and migrating.) Related concepts Introduction to EGL on page 1

10

EGL Reference Guide

EGL language overviewEGL projects, packages, and filesAn EGL project includes zero to many source folders, each of which includes zero to many packages, each of which includes zero to many files. Each file contains zero to many parts.

EGL projectAn EGL project is characterized by a set of properties, which are described later. In the context of an EGL project, EGL automatically performs validation and resolves part references when you perform certain tasks; for example, when you save an EGL file or build file. In addition, if you are working with page handler parts (the output of which is used to debug Web applications in the Websphere test environment), EGL automatically generates output, but only in this case: v You have set the automatic build process after selecting these options: Window > Preferences > Workbench > Perform build automatically on resource modification v You have established a default build descriptor as a preference or property An EGL project is formed by selecting EGL or EGL Web as the project type when you create a new project. You assign properties while working through the steps of project creation. To begin modifying your choices after you have completed those steps, right-click the project name and when a context menu is displayed, click Properties. The EGL properties are as follows: EGL source folder One or more project folders that are the roots for the projects packages, each of which is a set of subdirectories. A source folder is useful for keeping EGL source separate from Java files and for keeping EGL source files out of the Web deployment directories. It is recommended that you specify EGL source folders in all cases; but if a source folder is not specified, the only source folder is the project directory. The value of this property is stored in a file named .eglpath in the project directory and is saved in the repository (if any) that you use to store EGL files. The EGL project wizards each create one source folder named EGLSource. EGL build path The list of projects that are searched for any part that is not found in the current project. The value of this property is stored in a file named .eglpath in the project directory and is saved in the repository (if any) that you use to store EGL files. In the following example of an .eglpath file, EGLSource is a source folder in the current project, and AnotherProject is a project in the EGL path:

Copyright IBM Corp. 1996, 2004

11

The source folders for AnotherProject are determined from the .eglpath file in that project. Default build descriptors The build descriptors that allow you to generate output quickly, as described in Generation in the workbench.

PackageA package is a named collection of related source parts. No package is in use when you create build parts. By convention, you achieve uniqueness in package names by making the initial part of the package name an inversion of your organizations Internet domain name. For example, the IBM domain name is ibm.com, and the EGL packages begin with com.ibm. By using this convention, you gain some assurance that the names of Web programs developed by your organization will not duplicate the names of programs developed by another organization and can be installed on the same server without possibility of a name collision. The folders of a given package are identified by the package name, which is a sequence of identifiers separated by periods (.), as in this example:com.mycom.mypack

Each identifier corresponds to a subfolder under an EGL source folder. The directory structure for com.mycom.mypack, for example, is \com\mycom\mypack, and the source files are stored in the bottom-most folder; in this case, in mypack. If the workspace is c:\myWorkspace, if the project is new.project, and if the source folder is EGLSource, the path for that package is as follows:c:\myWorkspace\new.project\EGLSource\com\mycom\mypack

The parts in an EGL file all belong to the same package. The files package statement, if any, specifies the name of that package. If you do not specify a package statement, the parts are stored directly in the source folder and are said to be in the default package. It is recommended that you always specify a package statement because files in the default package cannot be shared by parts in other packages or projects. Two parts with the same identifier may not be defined in the same package. It is strongly recommended that you avoid using the same package name under different projects or different folders. The package for generated Java output is the same as the EGL file package.

EGL filesEach EGL file belongs to one of these categories: Source file An EGL source file (extension .egl) contains logic, data, and user interface parts and is written in EGL source format. Each of the following generatable parts can be transformed into a compilable unit: v DataTable v FormGroup

12

EGL Reference Guide

v v v v

Handler (the basis of a report handler) Library PageHandler Program

Other parts are called subparts. An EGL source file can include zero to many subparts but can include no more than one generatable part. The generatable part (if any) must be at the top level of the file and must have the same name as the file. Build file An EGL build file (extension .eglbld) contains any number of build parts and is written in Extensible Markup Language (XML), in EGL build-file format. You can review the related DTD, which is in the following directory:installationDir\egl\eclipse\plugins\ com.ibm.etools.egl_version

installationDir The product installation directory, such as C:\Program Files\IBM\Rational\SPD\6.0. If you installed and kept a Rational Developer product before installing the product that you are using now, you may need to specify the directory that was used in the earlier install. version The installed version of the plugin; for example, 6.0.0 The file name (like egl_wssd_6_0.dtd) begins with the letters egl and an underscore. The characters wssd refer to Rational Web Developer and Rational Application Developer; the characters wsed refer to Rational Application Developer for z/OS; and the characters wdsc refer to Rational Application Developer for iSeries. After you add parts to files, you can use a repository to maintain a history of changes.

RecommendationsThis section gives recommendations for setting up your development projects.

For build descriptorsTeam projects should appoint one person as a build-descriptor developer. The tasks for that person are as follows: v Create the build descriptors for the source-code developers v Put those build descriptors in a project separate from the source code projects; and make that separate project available in the repository or by some other means v Ask the source-code developers to set the property default build descriptors in their projects, so that the property references the appropriate build descriptors v If a small subset of the build descriptor options (such as for user ID and password) varies from one source-code developer to the next, ask each source-code developer to do as follows: Code a personal build descriptor that uses the option nextBuildDescriptor to point to a group build descriptorEGL language overview

13

Ask the source-code developers to set the property default build descriptors in their files, folders, or packages, so that the property references the personal build descriptor. They do not specify the property at the project level because the project-level property is under repository control, along with other project information. For additional information, see Build descriptor part.

For packagesFor packages, recommendations are as follows: v Do not use the same package name in different projects or source directories v Do not use the default package

Part assignmentFor parts, many of the recommendations refer to good practices, not hard requirements. Fulfill even the optional recommendations unless you have good reason to do otherwise: v A requirement is that you put JSPs in the same project as their associated page handlers. v If a subpart (like a record part) is used only by one program, library, or page handler, place the subpart in the same file as the using part. v If a part is referenced from different files in the same package, put that part in a separate file in the package. v If a part is shared across packages in a single project, place that part in a separate package in that project. v Put code for completely unrelated applications in different projects. The project is the unit for transferring code between your local directory structure and the repository. Design project structure so that developers can minimize the amount of code they have to have loaded into their development system. v Name projects, packages, and files in a way that reflects the use of the parts they contain. v If your process emphasizes code ownership by a developer, do not assign parts for different owners to the same file. v Assign parts to packages with a clear understanding of the purpose of the package; and group those parts by the closeness of the relationship between them. The following distinction is important: Moving a part from file to file in the same package does not require that you change import statements in other files. Moving a part from one package to another may require an import statement to be added or changed in every file that references the moved part. Related concepts Build descriptor part on page 295 Generation in the workbench on page 328 References to parts on page 18 Import on page 28 Introduction to EGL on page 1 Parts on page 15 Related reference

14

EGL Reference Guide

EGL build-file format on page 373 EGL source format on page 440 EGL statements on page 100

PartsAn EGL