Rational Business Developer - IBM · PDF fileIdentifying the programs, files, or records that ... are called IR files because they provide an intermediate representation of the

Rational Business Developer

EGL Generation GuideVersion 7 Release 5.1

��

Rational Business Developer

EGL Generation GuideVersion 7 Release 5.1

��

NoteBefore using this information and the product it supports, read the information in “Notices,” on page 421.

This edition applies to version 7.1 of Rational Business Developer and to all subsequent releases and modificationsuntil 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 Contractwith IBM Corp.

Contents

Introduction to EGL generation. . . . . 1Generatable parts . . . . . . . . . . . . . 2Build descriptor and other build parts . . . . . . 3Preparation of the generated output . . . . . . 5Methods of initiating and controlling the generationprocess . . . . . . . . . . . . . . . . 8

Generation using the Eclipseworkbench . . . . . . . . . . . . . 11Setting the variableEGL_GENERATORS_PLUGINDIR . . . . . . . 13

Generation using the EGL softwaredevelopment kit (SDK) . . . . . . . . 15EGL command file . . . . . . . . . . . . 16EGLSDK . . . . . . . . . . . . . . . 18Using eglpath with the EGL SDK . . . . . . . 22EGLPREP batch command utility . . . . . . . 22The EGL maintenance tool, EGLMAINT . . . . . 24

EGL Generation Results view . . . . . 27

Creating and maintaining a build file 29EGL build-file format . . . . . . . . . . . 30Adding an import statement to an EGL build file. . 31Editing an import statement in an EGL build file . . 32Removing an import statement from an EGL buildfile . . . . . . . . . . . . . . . . . 32

Build descriptor part . . . . . . . . . 33Master build descriptors and build descriptor chains 33Precedence of options . . . . . . . . . . . 33Setting the master build descriptor . . . . . . 36

Format of the eglmaster.properties file . . . . 37Setting the default build descriptors . . . . . . 38Adding a build descriptor part to an EGL build file 38Removing a build descriptor part from an EGLbuild file . . . . . . . . . . . . . . . 39

Build descriptor options . . . . . . . 41Editing build descriptor options in the builddescriptor part . . . . . . . . . . . . . 58Editing symbolic parameters in the build descriptorpart . . . . . . . . . . . . . . . . . 59Editing mfsDevice options in a build descriptor part 60

Linkage options part . . . . . . . . . 61Specifying when linkage options are final . . . . 61Elements of a linkage options part. . . . . . . 61Identifying the programs, files, or records thatelements reference . . . . . . . . . . . . 62Adding a linkage options part to an EGL build file 63

Removing a linkage options part from an EGL buildfile . . . . . . . . . . . . . . . . . 64

Resource associations part . . . . . . 65File types . . . . . . . . . . . . . . . 66Adding a resource associations part to an EGL buildfile . . . . . . . . . . . . . . . . . 69Editing a resource associations part in an EGL buildfile . . . . . . . . . . . . . . . . . 69Removing a resource associations part from an EGLbuild file . . . . . . . . . . . . . . . 71Association elements . . . . . . . . . . . 71

commit . . . . . . . . . . . . . . . 72conversionTable . . . . . . . . . . . . 72duplicates . . . . . . . . . . . . . . 72fileName . . . . . . . . . . . . . . 72fileType. . . . . . . . . . . . . . . 73formFeedOnClose . . . . . . . . . . . 73pcbName . . . . . . . . . . . . . . 73replace . . . . . . . . . . . . . . . 73system . . . . . . . . . . . . . . . 74systemName . . . . . . . . . . . . . 74text . . . . . . . . . . . . . . . . 77

Overview of EGL deploymentdescriptor file . . . . . . . . . . . . 79

Overview of .ir files . . . . . . . . . 81

VSAM support . . . . . . . . . . . 83

Data conversion. . . . . . . . . . . 85Data conversion when you generate a COBOLprogram . . . . . . . . . . . . . . . 86Data conversion at run time in a generated COBOLprogram . . . . . . . . . . . . . . . 87Data conversion at run time in a generated Javaprogram . . . . . . . . . . . . . . . 87Conversion algorithm . . . . . . . . . . . 88

Generation output and associated files 91

Name aliasing. . . . . . . . . . . . 97How Java names are aliased . . . . . . . . . 97How Java wrapper names are aliased. . . . . . 98

Program wrapper class . . . . . . . . . 98Record wrapper class . . . . . . . . . . 99Substructured array field class . . . . . . . 99Example . . . . . . . . . . . . . . 99Generated output . . . . . . . . . . . 100

How COBOL names are aliased . . . . . . . 100

Build plan . . . . . . . . . . . . . 103

© Copyright IBM Corp. 1996, 2008 iii

Using a build plan after generation . . . . . . 103

Build scripts . . . . . . . . . . . . 105COBOL build script for iSeries . . . . . . . 105COBOL build scripts for z/OS. . . . . . . . 105Java build script . . . . . . . . . . . . 105

Build server . . . . . . . . . . . . 107Starting a build server on AIX, Linux, or Windows2000/NT/XP . . . . . . . . . . . . . 107

Setting the language of messages returned fromthe build server . . . . . . . . . . . 108Security Manager . . . . . . . . . . . 108

Starting a build server on z/OS . . . . . . . 109Syntax. . . . . . . . . . . . . . . 109Procedure . . . . . . . . . . . . . 110Example . . . . . . . . . . . . . . 111Special considerations for z/OS builds . . . . 111Setting the language of messages returned fromthe build server. . . . . . . . . . . . 111Additional details on build-server configuration 113

Starting a build server on iSeries . . . . . . . 113Verifying the iSeries Remote Build Server . . . 113Setting the language of messages returned fromthe build server. . . . . . . . . . . . 114Security Manager . . . . . . . . . . . 114

Generating EGL and Web services 117Using the deployment descriptor with services . . 118

Deployment descriptor options for services . . 121Deployment descriptor options for serviceclients . . . . . . . . . . . . . . . 122

Generating and deploying a Web service to CICS 124Deploying a Web service requester to CICS . . . 126Special considerations for generating EGL or Webservices in z/OS CICS environments . . . . . 128Special considerations for generating EGL or Webservices in iSeries environments . . . . . . . 129

Generating Web transactions . . . . 131Gateway servlet parameters . . . . . . . . 131Web transaction linkage properties . . . . . . 135

Overview of Java generation . . . . . 141Inputs to Java generation . . . . . . . . . 143

Build descriptor options used with Java . . . 144Choosing build descriptor options for Javageneration . . . . . . . . . . . . . 152Overview of Java runtime properties . . . . 153Editing Java runtime properties in the EGLBuild Parts Editor . . . . . . . . . . . 157Description of Java runtime properties . . . . 159Symbolic parameters in Java generation . . . 170Linkage options part in Java generation . . . 170Resource associations in Java generation . . . 171

Overview of Java output . . . . . . . . . 172Output of Java program generation . . . . . 172JEE environment file . . . . . . . . . . 173JEE deployment descriptor . . . . . . . . 175Setting JEE deployment descriptor values . . . 176

Program properties file . . . . . . . . . 177Alternatives for the Java preparation phase . . . 178

Generating Java code into a project . . . . . 178Processing Java code that is generated into adirectory . . . . . . . . . . . . . . 180

Preparing for deployment . . . . . . . . . 182Linkage properties file . . . . . . . . . 182Deploying to a JEE environment . . . . . . 186Deploying to a non-JEE environment . . . . 194

Generating Java wrappers . . . . . . . . . 199Java wrapper classes . . . . . . . . . . 199Output of Java wrapper generation . . . . . 208

Overview of EGL Rich UI generationand deployment . . . . . . . . . . 213Deploying a Rich UI application to WebSphereApplication Server . . . . . . . . . . . 215Deploying a Rich UI application to Apache Tomcat 217Deploying a Rich UI application to a localdirectory . . . . . . . . . . . . . . . 218Build descriptor options used with JavaScript . . 220

defaultDateFormat (build descriptor option) . . 221defaultServiceTimeout . . . . . . . . . 222defaultSessionCookieID . . . . . . . . . 222defaultTimeFormat (build descriptor option) . . 223defaultTimeStampFormat (build descriptoroption) . . . . . . . . . . . . . . 224deploymentDescriptor . . . . . . . . . 224eliminateSystemDependentCode . . . . . . 225nextBuildDescriptor . . . . . . . . . . 226system . . . . . . . . . . . . . . 226

Overview of COBOL generation . . . 229COBOL program restrictions . . . . . . . . 231Inputs to COBOL generation . . . . . . . . 233

Build descriptor options used with COBOL . . 234Choosing build descriptor options for COBOLgeneration . . . . . . . . . . . . . 245Symbolic parameters used with COBOLgeneration . . . . . . . . . . . . . 246Linkage options part in COBOL generation . . 257Resource associations part in COBOL generation 258COBOL reserved-word file . . . . . . . . 258Runtime JCL templates for z/OS . . . . . . 259Runtime CL templates for iSeries . . . . . . 263Bind control part . . . . . . . . . . . 264Link edit part . . . . . . . . . . . . 269

Output of COBOL program generation . . . . . 275Location of output. . . . . . . . . . . 280CICS table files . . . . . . . . . . . . 281Results file . . . . . . . . . . . . . 281

Modifying EGL build scripts for z/OS . . . . . 282Examples of modifying EGL build scripts . . . 283Options required in EGL build scripts . . . . 283COBOL compiler options not found in buildscripts for z/OS . . . . . . . . . . . 285COBOL compiler options that are not supported 286Build scripts delivered with EGL . . . . . . 286Pseudo-JCL syntax . . . . . . . . . . 287CALL statement . . . . . . . . . . . 288

iv EGL Generation Guide

DD statement . . . . . . . . . . . . 290EXEC statement . . . . . . . . . . . 294IF statement . . . . . . . . . . . . . 296VARS statement . . . . . . . . . . . 297

Modifying EGL build scripts for iSeries. . . . . 298Preparing for deployment . . . . . . . . . 298

Build descriptor options. . . . . . . 299bidiConversionTable . . . . . . . . . . . 299bidiRuntime . . . . . . . . . . . . . . 299bind . . . . . . . . . . . . . . . . 300birtEngineHome . . . . . . . . . . . . 301buildPlan. . . . . . . . . . . . . . . 301cancelAfterTransfer . . . . . . . . . . . 302checkIndices. . . . . . . . . . . . . . 302checkNumericOverflow . . . . . . . . . . 303checkToTransaction . . . . . . . . . . . 303checkType . . . . . . . . . . . . . . 304cicsEntries . . . . . . . . . . . . . . 304cicsj2cTimeout . . . . . . . . . . . . . 305clientCodeSet . . . . . . . . . . . . . 306commentLevel . . . . . . . . . . . . . 306currencyLocation . . . . . . . . . . . . 307currencySymbol . . . . . . . . . . . . 307data . . . . . . . . . . . . . . . . 308dbContentSeparator . . . . . . . . . . . 308dbms . . . . . . . . . . . . . . . . 309debugTrace . . . . . . . . . . . . . . 309decimalSymbol . . . . . . . . . . . . . 310defaultDateFormat (build descriptor option) . . . 310defaultMoneyFormat (build descriptor option) . . 311defaultNumericFormat (build descriptor option) 312defaultServiceTimeout . . . . . . . . . . 312defaultSessionCookieID . . . . . . . . . . 313defaultTimeFormat (build descriptor option) . . . 313defaultTimeStampFormat (build descriptor option) 314deploymentDescriptor . . . . . . . . . . 315destDirectory . . . . . . . . . . . . . 315destHost . . . . . . . . . . . . . . . 316destLibrary . . . . . . . . . . . . . . 317destPassword . . . . . . . . . . . . . 317destPort . . . . . . . . . . . . . . . 318destUserID . . . . . . . . . . . . . . 318eliminateSystemDependentCode . . . . . . . 319enableJavaWrapperGen . . . . . . . . . . 320endCommArea . . . . . . . . . . . . . 320errorDestination . . . . . . . . . . . . 321fillWithNulls . . . . . . . . . . . . . 321formServicePgmType . . . . . . . . . . . 322genDataTables . . . . . . . . . . . . . 322genDDSFile . . . . . . . . . . . . . . 323genDirectory . . . . . . . . . . . . . 323genFormGroup . . . . . . . . . . . . . 324genHelpFormGroup . . . . . . . . . . . 324genProject . . . . . . . . . . . . . . 325genProperties . . . . . . . . . . . . . 326genResourceBundle . . . . . . . . . . . 328genReturnImmediate . . . . . . . . . . . 329genRunFile . . . . . . . . . . . . . . 329genVGUIRecords . . . . . . . . . . . . 330imsFastPath . . . . . . . . . . . . . . 330

imsID . . . . . . . . . . . . . . . . 331imsLogID . . . . . . . . . . . . . . 331includeLineNumbers . . . . . . . . . . . 331initIORecordsOnCall . . . . . . . . . . . 332

Compatibility . . . . . . . . . . . . 332initNonIODataOnCall . . . . . . . . . . 332

Compatibility . . . . . . . . . . . . 333j2ee. . . . . . . . . . . . . . . . . 333j2eeLevel . . . . . . . . . . . . . . . 333leftAlign . . . . . . . . . . . . . . . 334linkage . . . . . . . . . . . . . . . 335linkEdit . . . . . . . . . . . . . . . 335math . . . . . . . . . . . . . . . . 336maxNumericDigits . . . . . . . . . . . 337mfsDevice . . . . . . . . . . . . . . 337mfsExtendedAttr . . . . . . . . . . . . 338mfsIgnore . . . . . . . . . . . . . . 339mfsUseTestLibrary. . . . . . . . . . . . 339msgTablePrefix . . . . . . . . . . . . . 339nextBuildDescriptor . . . . . . . . . . . 340oneFormItemCopybook . . . . . . . . . . 340positiveSignIndicator . . . . . . . . . . . 341prep . . . . . . . . . . . . . . . . 342printDestination . . . . . . . . . . . . 343programPackageName . . . . . . . . . . 344projectID . . . . . . . . . . . . . . . 344reservedWord . . . . . . . . . . . . . 345resourceAssociations . . . . . . . . . . . 345resourceBundleLocale . . . . . . . . . . 345restartTransactionID . . . . . . . . . . . 346restoreCurrentMsgOnError . . . . . . . . . 346returnTransaction . . . . . . . . . . . . 347secondaryTargetBuildDescriptor . . . . . . . 347separatorSymbol . . . . . . . . . . . . 348serverCodeSet . . . . . . . . . . . . . 349serverType . . . . . . . . . . . . . . 349sessionBeanID . . . . . . . . . . . . . 350setFormItemFull . . . . . . . . . . . . 352spaADF . . . . . . . . . . . . . . . 352spaSize . . . . . . . . . . . . . . . 352spaStatusBytePosition . . . . . . . . . . 353spacesZero . . . . . . . . . . . . . . 353sqlCommitControl . . . . . . . . . . . . 354sqlDB . . . . . . . . . . . . . . . . 355sqlErrorTrace . . . . . . . . . . . . . 356sqlID . . . . . . . . . . . . . . . . 356sqlIOTrace . . . . . . . . . . . . . . 357sqlJDBCDriverClass . . . . . . . . . . . 357sqlJNDIName . . . . . . . . . . . . . 359sqlPassword . . . . . . . . . . . . . . 360sqlSchema . . . . . . . . . . . . . . 360sqlValidationConnectionURL . . . . . . . . 360startTransactionID . . . . . . . . . . . . 361statementTrace . . . . . . . . . . . . . 361synchOnPgmTransfer . . . . . . . . . . . 362synchOnTrxTransfer . . . . . . . . . . . 363sysCodes . . . . . . . . . . . . . . . 363system . . . . . . . . . . . . . . . 364targetNLS . . . . . . . . . . . . . . 365tempDirectory . . . . . . . . . . . . . 366

Web transactions . . . . . . . . . . . 366

Contents v

templateDir . . . . . . . . . . . . . . 367transferErrorTransaction . . . . . . . . . . 368truncateExtraDecimals . . . . . . . . . . 368twaOffset. . . . . . . . . . . . . . . 368useCurrentSchema. . . . . . . . . . . . 369userMessageFile . . . . . . . . . . . . 369useXctlForTransfer. . . . . . . . . . . . 370vagCompatibility . . . . . . . . . . . . 370validateMixedItems . . . . . . . . . . . 371validateOnlyIfModified . . . . . . . . . . 371validateSQLStatements . . . . . . . . . . 372workDBType . . . . . . . . . . . . . 373wrapperCompatibility . . . . . . . . . . 373wrapperJNDIPrefix . . . . . . . . . . . 374wrapperPackageName . . . . . . . . . . 374

Linkage options part . . . . . . . . 375asynchLink element . . . . . . . . . . . 375

Editing the asynchLink element of a linkageoptions part . . . . . . . . . . . . . 376conversionTable in asynchLink element. . . . 377locationSpec in asynchLink element . . . . . 378package in asynchLink element . . . . . . 379recordName in asynchLink element . . . . . 379type in asynchLink element . . . . . . . 379

callLink element . . . . . . . . . . . . 380Choosing the correct callLink type . . . . . 380If callLink type is localCall . . . . . . . . 382If callLink type is remoteCall . . . . . . . 383If callLink type is ejbCall . . . . . . . . 386Editing the callLink element of a linkageoptions part . . . . . . . . . . . . . 387csouidpwd.properties file for remote calls . . . 388alias in callLink element . . . . . . . . . 389conversionTable in callLink element . . . . . 389ctgKeyStore in callLink element . . . . . . 390ctgKeyStorePassword in callLink element . . . 390ctgLocation in callLink element . . . . . . 391ctgPort in callLink element . . . . . . . . 391library in callLink element . . . . . . . . 391linkType in callLink element . . . . . . . 392location in callLink element . . . . . . . 393

luwControl in callLink element . . . . . . 395package in callLink element . . . . . . . 396parmForm in callLink element. . . . . . . 396pgmName in callLink element. . . . . . . 398pgmType in callLink element . . . . . . . 398providerURL in callLink element . . . . . . 399refreshScreen in callLink element . . . . . . 400remoteBind in callLink element . . . . . . 400remoteComType in callLink element. . . . . 401remotePgmType in callLink element . . . . . 404serverID in callLink element . . . . . . . 405type in callLink element . . . . . . . . . 405

fileLink element . . . . . . . . . . . . 407Editing the fileLink element of a linkage optionspart . . . . . . . . . . . . . . . 407conversionTable in fileLink element . . . . . 408fileName in fileLink element . . . . . . . 409locationSpec in fileLink element . . . . . . 409type in fileLink element . . . . . . . . . 410

transferToProgram element . . . . . . . . . 410Editing the transferToProgram element of alinkage options part . . . . . . . . . . 411alias in transferToProgram element . . . . . 413fromPgm in transferToProgram element . . . 413linkType in transferToProgram element . . . . 414packageName in transferToProgram element 415toPgm in transferToProgram element . . . . 415

transferToTransaction element . . . . . . . . 416Editing the transferToTransaction element of alinkage options part . . . . . . . . . . 416alias in transferToTransaction element . . . . 417externallyDefined in transferToTransactionelement . . . . . . . . . . . . . . 418packageName in transferToTransaction element 419toPgm in transferToTransaction element . . . 419

Appendix. Notices . . . . . . . . . 421Programming interface information . . . . . . 423Trademarks and service marks . . . . . . . 423

Index . . . . . . . . . . . . . . . 425

vi EGL Generation Guide

Introduction to EGL generation

After you redeploy write EGL source code, you generate Java™, JavaScript™, orCOBOL code for one or another target platform. You can generate in theWorkbench , as described here, or in the EGL software development kit (SDK), asdescribed in Generation using the EGL Software Development Kit (SDK). You thenprepare the generated output for use on a target platform, as described inPreparation of the generated output.

EGL compilation

As you develop EGL source code in the Workbench, the interface responds to yourchanges. For example, the EGL editor signals an error if you write an invalidfunction. After you fix the error, the name of the function is immediately displayedin the Outline view.

How does the Workbench respond to your code, signaling errors in the EGL editorand suddenly displaying data in a different view? Those behaviors are madepossible by hidden EGL compilations, which convert your source code to aninternal format of a kind later used as input to the EGL generator.

Each compilation validates whether the syntax of the source code is correct. Thevalidation lets the Workbench respond interactively to syntax errors but does notcatch errors that are specific to a target platform.

The EGL compiler is the system code that compiles your source code.

EGL build

An EGL build is a process that compiles your EGL source-code files and stores theoutput in a set of files that are used for debugging and generation. The built filesare called IR files because they provide an intermediate representation of thegenerated output.

By default, the Workbench performs an EGL build automatically each time yousave your EGL source code. We suggest you accept the default behavior. If youdon’t recreate the IR files each time you save the EGL files, you may accidentallyuse old EGL source code when debugging the code or when generating output.

Most builds are incremental, adding content to existing IR files. The Workbenchalso provides the Clean option, which removes and rebuilds the IR files.

EGL generation

An EGL generation is a process that requires not only IR files, but a set of rules thatare specific to the target platform. Before generation, you provide those rules byspecifying a set of definitions that are called build parts. The build parts affect howoutput is generated, as well as how output is built at deployment time. The mostimportant build part is the build descriptor, which identifies the target platform andthat references other build parts as appropriate.

© Copyright IBM Corp. 1996, 2008 1

EGL generation includes a second validation step to ensure that the input togeneration is appropriate to the target platform. This validation step is the sourceof most messages from the EGL generator.

In regard to EGL generation, we suggest that you accept the default behavior,which is to avoid the automatic generation of output after each build. In mostcases, your development task is to repeatedly write, build, and debug, leavinggeneration for later in the process. Note that the default behavior includes someexceptions; for example, for JSF handler development. The exceptions are in effectwhen the debugging environment requires not only IR files and a build descriptor,but the generated output.

Related concepts

“Preparation of the generated output” on page 5“Overview of Java generation” on page 141“Overview of EGL Rich UI generation and deployment” on page 213“Overview of COBOL generation” on page 229Related tasks

“Generating EGL and Web services” on page 117“Generating Web transactions” on page 131Use EGL Web transactions to migrate VisualAge® Generator Web transactions toEGL.“Generation using the EGL software development kit (SDK)” on page 15Related reference

“Build descriptor part” on page 33“Build descriptor options” on page 41

Generatable parts

A generatable part is one for which you can request a generation step; for example,by right-clicking the file in the Workbench and selecting Generate. A generatablepart is always in a file that is named for the part.

The generatable part types are as follows:v Programv Libraryv Servicev DataTablev EGL deployment descriptor

For Java generation, the following part types are also generatable:v JSF handlerv Report handlerv Record part for which the stereotype is ConsoleForm

For JavaScript generation, an added generatable part type is the Rich UI handler;that is, a Handler part for which the stereotype is RUIHandler.

The output for a generatable part is a standalone unit such as a program.Related concepts

“Build descriptor and other build parts” on page 3

2 EGL Generation Guide

“Generation output and associated files” on page 91“Overview of EGL Rich UI generation and deployment” on page 213“Methods of initiating and controlling the generation process” on page 8“Preparation of the generated output” on page 5

Build descriptor and other build parts

When you generate your EGL source code, you use the Workbench to specifycertain kinds of build parts that help control the generation process. Many of thesebuild parts are similar to the options and settings you use during the debuggingprocess. However, when you are generating (as opposed to debugging) there aremore options and other information to specify, and the values you set need toreflect your target runtime environment. Generally, you define thisgeneration-specific information once for each type of target runtime environmentthat you have, and then you use the same information whenever you generateEGL source for that target runtime environment.

When you generate EGL source, you specify a part called a build descriptor part,which provides build descriptor options that control the generation process. Thesebuild descriptor options fall into a number of general categories, including thefollowing:

Target runtime environmentThis is specified by the system build descriptor option.

Location of generated outputThe genProject build descriptor option provides the name of a projectwithin the workspace to use as the location for the generated Java output.The genDirectory build descriptor option indicates a directory outside theworkspace to use as the location for the generated output. ThegenDirectory build descriptor option is always used for generated COBOLoutput and can optionally be used for generated Java output.

Location for preparation phaseIf you are generating Java code, usually you will use the genProject builddescriptor option to generate to a project within the workspace; in whichcase, the preparation phase occurs in the workspace. However, if you aregenerating COBOL code (which is always prepared on a remote system) orgenerating Java code that you want to prepare on a remote system, thedestHost option and related options provide the name and accessinformation (such as user ID and password) for that remote system.

Additional information to be generatedBuild options can cause additional information to be created duringgeneration. For example, when you generate a program for Javaenvironments, setting the genProperties option creates Java runtimeproperties that are based on the settings in other options. These Javaruntime properties are written to one of three different types of files,depending on whether you are generating to a J2EE runtime environmentor not. As another example, when you generate a program for the z/OS®

Batch environment, setting the genRunFile option generates sampleruntime JCL.

Additional information used at generation timeSome build descriptor options point to other build parts, which provideadditional information at generation time:

Introduction to EGL generation 3

v The linkage option points to the linkage options part, which providesinformation on how to implement certain statements such as call,transfer, vgLib.startTransaction, and certain kinds of file I/O statementsfor your target runtime environment.

v The resourceAssociation option points to the resource associations part,which provides information on how to implement I/O statements forserial, indexed, MQ, or relative records, as well as print output.

v The linkEdit option points to a program-specific link edit part, which isused if multiple programs must be linked together for a z/OS runtimeenvironment.

v The bind option points to a bind control template, or a program-specificbind control part which is used to create the DB2® bind commandsrequired for SQL databases in a z/OS runtime environment.

v The deploymentDescriptor option points to the EGL deploymentdescriptor, which is a separate file that provides information about howan EGL service part is exposed to other applications, or how an externalservice is used in an EGL application.

In addition to the build descriptor options mentioned above, for COBOLgeneration there are some build descriptor options that point to additionalinformation outside the workspace:v The templateDir option points to the location of customized templates

which control the creation of sample runtime JCL for the z/OS batchenvironment, and the creation of sample runtime Control Language, orCL, for the iSeries® runtime environment.

v The reservedWord option points to a file of additional COBOL, SQL, orCICS® reserved words; if your part or variable names match one of thesereserved words the COBOL generation process will assign aliases forthem.

Generating additional partsWhen you generate a program, you can set some options to cause otherparts to generate at the same time you generate the program. For example,the genDataTables build descriptor option indicates that you want togenerate all the DataTables that are used by the generated program.

Additional validation checksSome build descriptor options can be set to perform additional validationchecks before the generation process actually creates the Java or COBOLcode. For instance, the validateSQLStatements option causes thegeneration process to check the validity of the SQL statements in yourprogram. If you use that option, you might need to set additional builddescriptor options, such as sqlID and sqlPassword, to provide informationrequired to access your runtime database.

Additional logic included in generated codeIf you generate a program for a z/OS COBOL environment, thestatementTrace build descriptor option adds logic to your program whichprovides information you can use to trace a subset of runtime behavior. Ifyou generate a program for a Java environment, the j2ee option indicateswhether the program being generated will run in a J2EE environment; ifthe j2ee build descriptor option is set to YES, the j2eeLevel builddescriptor option specifies what level of J2EE you want the program tosupport.


In addition to the build descriptor options, the build descriptor part provides away for you to set symbolic parameters. These can be predefined symbolicparameters, or symbolic parameters you create yourself. These provide substitutionvalues that can be used during the generation and preparation process. Forexample, you can use the COBCOMP symbolic parameter to provide the locationof your COBOL compiler library.

When you generate, the specific build descriptor options and symbolic parametersyou need to use depend on the type of part you are generating, and the targetruntime environment you are using. Some options are used with all targetenvironments. Some are specific to Java environments, others to COBOLenvironments. Some options are specific to just one runtime environment.

There are other build parts needed at various points during generation, such aslinkage options parts, resource associations parts, link edit parts, or bind controlparts. For information on these parts, see the related topics at the end of this topic.

Related concepts

“Introduction to EGL generation” on page 1“Bind control part” on page 264“Build descriptor part” on page 33“Generatable parts” on page 2“Linkage options part” on page 61“Link edit part” on page 269“Methods of initiating and controlling the generation process” on page 8“Overview of EGL deployment descriptor file” on page 79“Preparation of the generated output”“Resource associations part” on page 65Related tasks

“Adding a build descriptor part to an EGL build file” on page 38“Adding a linkage options part to an EGL build file” on page 63“Adding a resource associations part to an EGL build file” on page 69“Creating and maintaining a build file” on page 29“Editing build descriptor options in the build descriptor part” on page 58“Editing symbolic parameters in the build descriptor part” on page 59“Removing a build descriptor part from an EGL build file” on page 39“Removing a linkage options part from an EGL build file” on page 64“Removing a resource associations part from an EGL build file” on page 71“Setting the default build descriptors” on page 38“Setting the master build descriptor” on page 36Related reference

“Build descriptor options” on page 41

Preparation of the generated output

EGL generation creates the following output:v Generated Java, JavaScript, or COBOL code.v For COBOL and Java, a build plan that controls a subsequent phase. (The build is

wholly separate from the Eclipse-related EGL build, which is described inIntroduction to EGL generation.)


v Other output that varies based on the specific type of part being generated, thetarget runtime environment, and some settings in build descriptor options.

After generating code, the EGL technology prepares the generated output (or helpsyou to prepare that output) for use on the target platform. The subsequent phase isnamed deployment for JavaScript, and we describe the technology in Overview ofRich UI generation and deployment. However, in relation to COBOL and Java, thephase after generation is named preparation. Our subsequent comments in thecurrent topic concern preparation, which produces the following output:v For COBOL, an executable modulev For Java, a collection of class files

The preparation phase is controlled by the build plan that EGL created duringgeneration. The preparation phase can include steps to do some or all of thefollowing actions:v Use TCP/IP to transfer the generation output to your build server.v Run the build scripts on the build server, in order to compile and link the

generation output. Depending on the target runtime environment and yourdatabase type, the build scripts might also include steps for a CICS translationor steps for a DB2 precompile and bind.

v Transfer the results of the preparation phase back to the generating workstationor workspace.

The build plan controls the order of output as it is sent to the build server. Thebuild plan also controls which build scripts are run on the build server. Usually,EGL starts the build plan automatically. However, if you have set the prep builddescriptor option to NO, EGL will create the build plan but not start it. You canstart that build plan at a later time. You can find more information in the topic″Using a build plan after generation″.

For COBOL generation, all three of the above preparation actions are always used.The output of the production phase must be placed outside the workspace usingthe genDirectory build descriptor option. In the preparation phase EGL transfersthe generation output to the host system; then uses the build server to compile andlink the output; finally, it transfers the results of the process back to theworkstation that was used to generate the output. The preparation phase forCOBOL has the following requirements:v The build server must be running in your target runtime environment at

generation time.v The system administrator must customize the build scripts so that they are

appropriate for your site.– You can find information about modifying z/OS build scripts in the topic

″Modifying EGL build scripts for z/OS″ and the IBM® Rational® COBOLRuntime Guide for zSeries®. This guide also has information on starting andcustomizing the build server.

– If you are generating to an iSeries environment, you can find informationabout customizing build scripts in the IBM Rational Business Developer EGLServer Guide for IBM i. This guide also has information about starting thebuild server.

For Java generation, the preparation phase can occur in several different waysdepending on where you place the output of generation. You specify whichmethod to use by setting certain build descriptor options as follows:


v Generate within your workspace, and place the output of the production phaseinto an existing project, using the genProject build descriptor option. In thisscenario, EGL does not create the build plan, and the build server and transfersteps are not used. If you have the workbench preference Build Automaticallyturned on, the preparation step (compiling the Java code and any other outputof generation) occurs automatically; if that preference is not turned on, you canbuild the project at a later time.

v Place the output of generation into a directory on the same workstation, butoutside the workspace. This is done by setting the genDirectory option, but notsetting the destHost option. In this scenario, EGL creates a build plan which inturn starts the Java compiler on the local workstation; however, EGL does notuse the build server, and EGL does not use the transfer step.

v Place the output of generation into a directory outside the workspace, thentransfer the output to a remote system for preparation. This uses the destHost,destDirectory, and related build descriptor options. In this scenario, EGL createsa build plan to control the order of output that is sent to the remote system. Thebuild plan also controls the build scripts that are run on the remote system.

After the preparation phase, your program is ready to deploy for the runtimeenvironment as follows:v For COBOL programs generated for IBM i, see the IBM Rational Business

Developer EGL Server Guide for IBM i. .v For COBOL programs generated for zSeries, see the IBM Rational COBOL

Runtime Guide for zSeries.v For Java programs generated for a non-J2EE environment, see “Program

properties file” on page 177 and “Deploying to a non-JEE environment” on page194.

v For Java programs generated for a J2EE environment, see “Setting JEEdeployment descriptor values” on page 176 and “Deploying to a JEEenvironment” on page 186.Related concepts

“Build plan” on page 103“EGL Generation Results view” on page 27“Generation output and associated files” on page 91“Introduction to EGL generation” on page 1“Generatable parts” on page 2“Build descriptor and other build parts” on page 3“Methods of initiating and controlling the generation process” on page 8Related tasks

“Creating and maintaining a build file” on page 29Related reference

“destDirectory” on page 315“destHost” on page 316“EGL build-file format” on page 30“genDirectory” on page 323“genProject” on page 325“linkage” on page 335“prep” on page 342“resourceAssociations” on page 345


“system” on page 226“validateSQLStatements” on page 372

Methods of initiating and controlling the generation process

EGL has a number of preferences that control the generation process. There arealso several methods for initiating generation. You can generate within the Eclipseworkbench, using one of the following methods:v Generating automatically, by configuring EGL to generate whenever a part is

builtv Generating manually, by using the generation wizard or the Generate menu

item.

You can also generate using the EGL Software Development Kit (EGL SDK). TheEGL SDK provides a batch interface for file-based generation, and is independentof the workbench. For more information about generating using the EGL SDK,refer to the topic “Generation using the EGL software development kit (SDK)” onpage 15.

Controlling the generation process

When you generate within the workbench, there are a number of preferences thatcontrol the generation process:v The Target system build descriptor. For more information about setting this and

the default build descriptor, see “Setting the default build descriptors” on page38.

v The Build automatically setting. You can find this setting by following thesesteps:1. Click Window → Preferences to open the Preferences window.2. At the left side of the Preferences window, expand General and click

Workspace.3. Under Workspace, select the Build automatically check box if you want EGL

to build your files automatically. When you select this preference, EGLperforms a build whenever you save a file. This means that EGL validatesany parts in the file that have changed and any other parts in the workspacethat reference the changed part. Validation is done without using a builddescriptor part.

v The Build before generate (if necessary) setting. You can find this setting byfollowing these steps:1. Click Window → Preferences to open the Preferences window.2. At the left side of the Preferences window, expand EGL and click

Generation.3. At the top, select the Build before generate (if necessary) check box. This

setting tells EGL what to do if you try to generate files that have not beenbuilt. If you select this setting, EGL will automatically build files beforeperforming generation. But if you have selected the Build automaticallypreference above, this setting is irrelevant, as all files will be built when yousave them.

v The Auto generate setting. You can find this setting by following the same stepslisted above, for the Build before generate (if necessary) setting. Below thatcheck box is a section labeled Auto generate. In this section you can select thetypes of parts, if any, you want to be automatically generated after they arebuilt. This automatic generation uses the default build descriptor part.


Initiating generation automatically

If you select the Auto generate preference as described in the previous section,generation is done automatically whenever a generatable file is built. If you selectthe Build automatically preference, then a build occurs whenever you save a file.

In addition to using the Preferences window to configure EGL to build filesautomatically, you can use the Project menu in the workbench to initiate a build.The Project menu has the following menu options:v Build Automatically. This menu option is the same as the EGL Preferences

setting mentioned in the previous section. If you have set this preference usingthose instructions, there will be a check next to this menu option, and some ofthe other menu options will be unavailable.

v Build Project. This menu option is only available if the Build automaticallyoption is not selected. Choose this menu option to manually initiate a build. Ifyou chose this menu option, the following events occur:1. EGL checks to see if any files in the project have been changed since the last

build. EGL validates any changed files, and also validates any parts in theworkspace that depend on those changed files. This validation is performedwithout using a build descriptor part.

2. If you selected Auto generate for any part types, EGL generates those partsif they have been changed. This generation is performed using the defaultbuild descriptor.

3. If any Java classes are generated into the workspace, they are compiled, butonly if Build automatically is selected.

v Build All. This option is only available if the Build Automatically option is notselected. Choose this option to perform the same actions as Build Project onevery project in your workspace.

v Clean. Choose this option to build all parts in all files, regardless of whetherthey have been changed. You can select which projects to include in this build.

Manually initiating the generation process

When you select a project, package, or file that contains generatable parts, you canright-click and choose one of the following from the pop-up menu:v Generate With Wizard. This menu option shows a list of parts that will be

generated, and shows the default build descriptor that will be used for eachgeneratable part. You can use the wizard to change the build descriptor. You canalso change the target system, and other frequently modified build descriptoroptions.

v Generate. This option starts the generation process, and uses the default builddescriptor you specified for the file, package, folder, project, or for the entireworkbench.Related concepts

“Build descriptor and other build parts” on page 3“Generatable parts” on page 2“Generation output and associated files” on page 91“Preparation of the generated output” on page 5“Introduction to EGL generation” on page 1Related tasks

“Generation using the Eclipse workbench” on page 11


“Generation using the EGL software development kit (SDK)” on page 15“Setting the default build descriptors” on page 38“Setting the master build descriptor” on page 36


Generation using the Eclipse workbench

Generation in the workbench is accomplished with either the Generation wizard orthe Generate pop-up menu option. When you select the pop-up menu option, EGLuses the default build descriptor. If you have not selected a default builddescriptor, or if you want to choose a different build descriptor, you can use theGeneration wizard.

When you are working in the Eclipse workbench and want to generate your EGLsource code, there are several different ways you can choose to start.v You can use the pop-up menu option Generate by right-clicking on the name of

the generatable part either in the EGL editor, in the Outline view, or in theProject Explorer view. If you choose this option, you should have a default builddescriptor set.

v You can use the pop-up menu option Generate With Wizard by right-clickingon the name of the generatable part in the Project Explorer view or the Outlineview.

v You can also enable the Auto generate function, by going to the EGL Generationpreferences page. You can find more information on setting this preference in“Methods of initiating and controlling the generation process” on page 8.

There are several steps involved in the generation process:1. First, select the parts that you want to generate. If you select an EGL container

such as a folder, package, or project, EGL will generate output for each EGLgeneratable part in the container.

2. Next, initiate the generation process.3. Finally, monitor your progress.

To make generation easier, first select a default build descriptor. You can select atarget system build descriptor, such as you would use for generating anddeploying in a runtime environment; or you can select a debug build descriptor,such as you would use when using the EGL Debugger. You can identify either typeof build descriptor as an Eclipse workbench preference, or as a property at the file,package, folder, and project levels. For more information about setting defaultbuild descriptors, see “Setting the master build descriptor” on page 36.

Build descriptors may be chained using the nextBuildDescriptor build descriptoroption. This option specifies the next ″link″ in the chain of build descriptors.Chaining build descriptors allows you to reuse build descriptors that contain builddescriptor options you will use many times, while still being able to override thosesettings if you have smaller groups of parts or individual parts that need to usemore specific build descriptor options. A master build descriptor may be identified,which is the first build descriptor in a chain. This master build descriptor containsany options that apply globally and that you do not want overridden by otherbuild descriptors in the chain. For more information about setting a master builddescriptor, see “Setting the master build descriptor” on page 36.

When you generate a VGWebTransaction program and want to generate aVGUIRecord with a different set of options, set thesecondaryTargetBuildDescriptor build descriptor option.


Generating using the Generation wizard

To generate in the workbench using the Generation wizard, follow these steps:1. Right-click on the name of a project, folder, package, or file in the Project

Explorer. To select multiple resource names, hold down the Ctrl key as youclick.

2. Select the Generate With Wizard option.3. The Parts page of the wizard displays a list of parts that can be generated,

based on the selection that you made to start the generation process. Select atleast one part from the list in order to continue to the next page of the wizard.You can select or deselect all the parts in the list using the buttons in theinterface.

4. On the Build Descriptors page you can choose one of the two following modesfor assigning a build descriptor part to the selected parts to be generated:v Choose a build descriptor part from a drop-down list of the build descriptors

that are in the workspace, and use that build descriptor for all of the partsyou want to generate.or

v Select a build descriptor for each of the generatable parts selected on the firstpage. Use the table on this page to select the build descriptor. The firstcolumn of the table displays the generatable part names; click on the secondcolumn, in the field next to a generatable part name, to display a drop-downlist of build descriptors. Each row of the table has its own list of builddescriptors. This allows you to choose a separate build descriptor for eachpart.

5. On the Generation Options page of the wizard you can set or override builddescriptor options that can vary depending on your circumstances. Forexample, you might want to set user IDs and passwords on this page ratherthan in the build descriptor to avoid keeping sensitive information in persistentstorage. The build descriptor options are in the following categories:v General Options. With this group of build descriptor options, you can set

the target system, provide information about remote build servers, and set alocation for placement of generation output.

v SQL Options. With this group of build descriptor options, you can provideinformation that EGL uses to validate SQL statements at generation time. Ifyou generate Java code, some of this information is also stored in Javaruntime properties, which are placed in a file for use at runtime.

v Java Options. With this group of build descriptor options, you can specifyinformation that is used only when generating Java code.

v JavaScript Options. With this group of build descriptor options, you canspecify information that is used only for Rich UI.

v COBOL Options. With this group of build descriptor options, you canspecify information that is used only when generating COBOL code.

You might want to set user IDs and passwords on this page rather than in thebuild descriptor to avoid keeping sensitive information in persistent storage.

6. On the Command File page of the wizard you can create a command file. Youcan use a command file to generate an EGL program outside of the workbench.You can reference the command file in the EGL Software Development Kit(SDK) by using the command java EGLSDK. To create a command file, do thefollowing:a. Select the Create a command file check box.


b. Specify the name of the output file, either by typing the fully qualified pathor by clicking Browse and using the standard Windows® procedure forselecting a file.

c. Select or clear the Automatically insert EGL path (eglpath) check box tospecify whether you want to include the EGL project path in the commandfile, as the initial value for eglpath; for details, see “EGL command file” onpage 16.

d. Select a radio button to indicate whether to avoid generating output whencreating the command file.

7. Once you have gone through all the pages, click Finish.

Generating using the pop-up menu option

To generate in the workbench using the Generate menu item, follow these steps:1. Set a default build descriptor for each resource you are going to generate. You

can set a default build descriptor at the file, package, folder, project, orworkbench level.

2. Select the name of a project, package, folder, or file in the Project Explorer. Toselect multiple resource names, hold down the Ctrl key as you click.

3. Right-click, then select the Generate menu option.

If you are generating a file, you can follow these steps:1. Double-click on the file name in the Project Explorer view. The file opens in the

appropriate EGL editor.2. Right-click inside the editor pane, then select Generate.

Related concepts

“Build descriptor part” on page 33“Generatable parts” on page 2“Overview of EGL Rich UI generation and deployment” on page 213“EGL Generation Results view” on page 27Related tasks

“Setting the default build descriptors” on page 38“Setting the master build descriptor” on page 36Related reference

“Build descriptor options” on page 41“EGL command file” on page 16“Generation output and associated files” on page 91

Setting the variable EGL_GENERATORS_PLUGINDIR

The workbench classpath variable EGL_GENERATORS_PLUGINDIR contains thefully qualified path to the EGL plugin in the workbench. The variable is used inthe Java build path when you generate an EGL program into a Java project,Enterprise Java Bean (EJB) project, or application client project.

Usually the variable will be set automatically if you create EGL source code inyour own workspace, or if you generate EGL source code in your workspace (evenif you got that source code from somewhere else, such as a repository). If youencounter a classpath error that refers to EGL_GENERATORS_PLUGINDIR, thevariable may not be set yet. For example, this problem can occur if you check out

Generation using the Eclipse workbench 13

an EGL project from a software configuration management system like ConcurrentVersions System (CVS) before you ever work with an EGL part.

You can set the variable by following these steps:1. Select Window → Preferences.2. On the Preferences page, expand Java → Build Path, and then select Classpath

Variables.3. Select New.4. At the New Variable Entry page, type EGL_GENERATORS_PLUGINDIR and specify

the following directory:shared_resources\plugins\com.ibm.etools.egl.java.runtime_version

shared_resourcesThe shared resources directory for your product, such as C:\ProgramFiles\IBM\SDP70Shared on a Windows system or /opt/IBM/SDP70Shared ona Linux® system. If you installed and kept a previous version of an IBMproduct containing EGL before installing your current product, you mayneed to specify the shared resources directory that was set up in the earlierinstall.

versionThe installed version of the plugin, including three numbers separated byperiods, a string separator, and the date and time that the plugin was built;for example, 7.0.0.RFB_20070120_1300. If more than one is present, use theone with the most recent version number, unless you have a reason to usean older version.

After you set the variable, build the project.Related tasks

“Generating Java code into a project” on page 178Related reference

“genProperties” on page 326


Generation using the EGL software development kit (SDK)

The EGL software development kit (SDK) is a feature that lets you generate outputin a batch environment, even when you lack access to the graphical user interfaceof your development environment, or lack access to details on how projects areorganized, or both. For example, if you store EGL files in a software configurationmanagement (SCM) tool, you can create a batch job that extracts the files from theSCM tool (perhaps after working hours) and then uses the EGL SDK to triggergeneration.

Note: You can generate JavaScript and JSF handlers only in the Workbench, not inthe EGL SDK.

To use the EGL SDK, you enter the java EGLSDK command in a batch file or at acommand prompt. The command statement itself can take either of two forms:v It can specify a single EGL file and a single EGL build descriptor part. In this

case, if you want to generate multiple files, you must write multiple commands.Here is an example of this command, which should be written on one line:java EGLSDK generate -eglpath "c:\myGroup;h:\myCorp"

-generateFile "c:\myProg.egl"-buildDescriptorFile "c:\myBuild.eglbld"-buildDescriptorName myBuildDescriptor

v It can specify an EGL command file that includes the information necessary forgenerating one or more EGL files:java EGLSDK "commandfile.xml"

When generating with the EGL SDK, you must specify some information indifferent ways than when you generate in the workbench:v When generating in the workbench, the .eglPath file specifies the EGL build

path, which is a list of directories that are searched to resolve part references.However, when generating with the EGL SDK, you specify the build path in oneof two ways:– If you generate without a command file, you specify the value of eglpath as an

argument in the java EGLSDK.– If you generate with a command file, you specify the value of eglpath in that

file.

See “Using eglpath with the EGL SDK” on page 22.v You must specify the genDirectory build descriptor option instead of genProject

to specify where EGL will place the generated code.

Prerequisitesv Make sure that Java 1.5 (or a higher level) is on the system where you will

generate code. An appropriate level of Java code is installed automatically on thesystem where you install EGL. The Java levels on the generation and targetsystems must be compatible.

v Make sure that eglbatchgen.jar is in both your PATH and CLASSPATH systemvariables. The JAR file is in the following directory:shared_resources\plugins\com.ibm.etools.egl.batchgeneration_version\runtime

shared_resourcesThe shared resources directory for your product, such as C:\Program


Files\IBM\SDP70Shared on a Windows system or /opt/IBM/SDP70Shared on aLinux system. If you installed and kept a previous version of an IBMproduct containing EGL before installing your current product, you mayneed to specify the shared resources directory that was set up in the earlierinstall.


v Make sure that the EGL SDK can access the EGL files that are required forgeneration.

v Optionally, develop an EGL command file.

Once you have satisfied the prerequisites, you can issue java EGLSDK commands asexplained in “EGLSDK” on page 18.

Related tasks

“Using eglpath with the EGL SDK” on page 22Related reference

“EGLSDK” on page 18

EGL command file

An EGL command file lists the EGL files to generate and which build descriptorsto use when you generate output outside of the workbench. You can create the filein either of two ways:v By hand, according to the rules described later in this topic.v By using the EGL Generation wizard, as described in “Generation using the

Eclipse workbench” on page 11.

Once you have created the command file, you can pass it to the EGLSDKcommand to begin generating:java EGLSDK "commandFile.xml"

For more information on the EGLSDK command, see “EGLSDK” on page 18.

This is an example of an EGL command file:<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE EGLCOMMANDS PUBLIC "-//IBM//DTD EGLCOMMANDS 5.1//EN" "">

<EGLCOMMANDSeglpath="EGLSource"><generate

file="EGLSource\libraries\calculatorLib.egl"><buildDescriptor name="SDKTestProjectJavaBuildOptions"

file="EGLSource\SDKTestProject.eglbld"></buildDescriptor>

</generate><generate

file="EGLSource\programs\SDKTestProgram.egl"><buildDescriptor name="SDKTestProjectJavaBuildOptions"


file="EGLSource\SDKTestProject.eglbld"></buildDescriptor>

</generate></EGLCOMMANDS>

This command file specifies that the parts in the files calculatorLib.egl andSDKTestProgram.egl are to be generated, each using the build descriptorSDKTestProjectJavaBuildOptions in the build file SDKTestProject.eglbld.

The command file is an XML file, and the file name must have the extension .xml,in any combination of uppercase and lowercase letters. The file content mustconform to the following document type definition (DTD):shared_resources\plugins\com.ibm.etools.edt.common\dtd\eglcommands_6_0.dtd

shared_resourcesThe shared resources directory for your product, such as C:\ProgramFiles\IBM\SDP70Shared on a Windows system or /opt/IBM/SDP70Shared on aLinux system. If you installed and kept a previous version of an IBM productcontaining EGL before installing your current product, you may need tospecify the shared resources directory that was set up in the earlier install.

versionThe installed version of the plugin, including three numbers separated byperiods, a string separator, and the date and time that the plugin was built; forexample, 7.0.0.RFB_20070120_1300. If more than one is present, use the onewith the most recent version number, unless you have a reason to use an olderversion.

The location of this DTD file should be all on one line.

The following table shows the elements and attributes supported by the DTD. Theelement and attribute names are case sensitive.

Element Attribute Attribute value

EGLCOMMANDS(required)

eglpath As described in “Using eglpath with the EGL SDK” onpage 22 the eglpath attribute identifies directories tosearch when EGL uses an import statement to resolvethe name of a part. The attribute is optional and ifpresent, references a quoted string that has one ormore directory names, each separated from the nextby a semicolon.

EGL uses the eglpath attribute to resolve referencesfrom within build files and generatable part filesnamed by ″file″ attributes in the generation commandfile. eglpath does not resolve relative paths used in the″file″ attributes themselves.

Use this attribute only if you are using the EGL SDKto reference the command file.

Generation using the EGL software development kit (SDK) 17

Element Attribute Attribute value

buildDescriptor(optional; you canavoid specifyingthis value if you areusing a masterbuild descriptor, asdescribed in “Builddescriptor part” onpage 33)

name The name of a build descriptor part that guidesgeneration. The build descriptor must be in an EGLbuild (.eglbld) file.

Build descriptor options that you specify when usingthe command java EGLSDK take precedence overoptions in the build descriptor part (if any) that islisted in the EGL command file.

file The absolute or relative path of the EGL file thatcontains the build descriptor. Relative paths specifiedfor the command java EGLSDK are relative to thedirectory in which you run the command.

The path must be in double quotes if the pathincludes a space.

generate (optional) file The absolute or relative path of the EGL file thatcontains the part you want to generate. Relative pathsspecified for the command java EGLSDK are relative tothe directory in which you run the command.

The path must be in double quotes if the pathincludes a space.

If you omit the file attribute, no generation occurs.

Related concepts

“Build descriptor part” on page 33Related tasks

“Generation using the Eclipse workbench” on page 11“Generation using the EGL software development kit (SDK)” on page 15“Using eglpath with the EGL SDK” on page 22Related reference

“EGLSDK”

EGLSDK

The command java EGLSDK gives you access to the EGL Software Development Kit(EGL SDK). You must satisfy the prerequisites listed in “Generation using the EGLsoftware development kit (SDK)” on page 15 before generating with the EGL SDK.

Syntax

The syntax for using the command java EGLSDK is as follows:


generateThis indicates that the command itself references the EGL source file and builddescriptor part that are used to generate output. In this case, the commandjava EGLSDK does not reference a command file.

cmdFileThis specifies the absolute or relative path of the file. Relative paths are relativeto the directory in which you run the command.

Enclose the path in double quotes.

–eglpath eglpathThe eglpath option identifies directories to search when EGL uses an importstatement to resolve the name of a part. You specify a quoted string that hasone or more directory names, each separated from the next by a semicolon.

- bdFilebuildDescriptorFile - bdNamebuildDescriptorName

java EGLSDK

- eglpath eglpath

- system sysName

- destHost hostName

- destPort portName

- genDirectory genDirName

- sqlJNDIName jndiName

- destDirectory destDirName

- sqlDB dbName

generate - generateFile genFile

- eglpath eglpath

cmdFile

- tempDirectory tempDirName

- templateDirectory templateDirName

- reservedWord wordFileName

- projectID projectID

- destLibrary libraryName

buildOpts

options

options

buildOpts

options

- destPassword destPW

- destUserID destID

- sqlPassword sqlPW

- sqlIDsqlID

- clean


–generateFile genFileThis is the absolute or relative path of the EGL file that contains the part youwant to process. Relative paths are relative to the directory in which you runthe command.


–buildDescriptorFile bdFileThis is the absolute or relative path of the build file that contains the builddescriptor. Relative paths are relative to the directory in which you run thecommand.


Note: The eglpath option is not used to find the build descriptor, so the bdFileparameter must specify the correct file.

–buildDescriptorName bdNameThis is the name of a build descriptor part that guides generation.

–sqlID sqlIDThis sets the value of the sqlID build descriptor option.

–sqlPassword sqlPWThis sets the value of the sqlPassword build descriptor option.

–destUserID destIDThis sets the value of the destUserID build descriptor option.

–destPassword destPWThis sets the value of the destPassword build descriptor option.

–cleanIf this option is specified, the IR files in the EGLBin directory will be removedbefore a build or generate process is run and after generation is complete.

–destDirectory destDirNameThis sets the value of the destDirectory build descriptor option.

–destHost hostNameThis sets the value of the destHost build descriptor option.

–destLibrary libraryNameThis sets the value of the destLibrary build descriptor option.

–destPort portNameThis sets the value of the destPort build descriptor option.

–genDirectory genDirNameThis sets the value of the genDirectory build descriptor option.

–reservedWord wordFileNameThis sets the value of the reservedWord build descriptor option.

–projectID projectIDThis sets the value of the projectID build descriptor option.

–sqlDB dbNameThis sets the value of the sqlDB build descriptor option.

–sqlJNDIName jndiNameThis sets the value of the sqlJNDIName build descriptor option.

–system sysNameThis sets the value of the system build descriptor option.


–tempDirectory tempDirNameThis sets the value of the tempDirectory build descriptor option.

–templateDirectory templateDirNameThis sets the value of the templateDir build descriptor option.

The eglpath value that you specify when using the command java EGLSDK takesprecedence over any eglpath value entered into the Generation wizard, which takesprecedence over any eglpath value in the build descriptor part. Similarly, builddescriptor options that you specify when invoking the command take precedenceover options in any build descriptor part that is listed in an EGL command file.

Examples

The first example shows an alternate way to assign eglbatchgen.jar to yourclasspath; if you are generating output to multiple target systems, you must set thePATH for each (the example should be typed all on one line):set CLASSPATH="shared_resources\plugins\com.ibm.etools.egl.batchgeneration_version\runtime\eglbatchgen.jar"



In the commands that follow, each multiline example belongs on a single line:java EGLSDK "commandfile.xml"

java EGLSDK "commandfile.xml" -eglpath "c:\myGroup;h:\myCorp"

java EGLSDK generate -eglpath "c:\myGroup;h:\myCorp" -generateFile "c:\myProg.egl"-buildDescriptorFile "c:\myBuild.eglbld" -buildDescriptorName myBuildDescriptor

java EGLSDK "myCommand.xml" -sqlID myID -sqlPassword myPW -destUserID myUserID-destPassword myPass

The above examples assume that you are starting the command java EGLSDK in thesame directory as the indicated command file. If your command file is in anotherdirectory, you must add the path to the command file name.

Related concepts

“Build descriptor part” on page 33“Setting the master build descriptor” on page 36Related tasks

“Generation using the EGL software development kit (SDK)” on page 15“Using eglpath with the EGL SDK” on page 22Related reference

“destPassword” on page 317


“destUserID” on page 318“EGL command file” on page 16“sqlID” on page 356“sqlPassword” on page 360

Using eglpath with the EGL SDK

When you develop your EGL source code in the workbench, each EGL project andEGL Web project is associated with an EGL build path so that the project canreference parts in other projects. For details on when the EGL build path is usedand on why the order of build-path entries is important, see the topic ″Scope″ inthe EGL Language Reference. This topic describes how the eglpath argument affectsthe EGL build path when you generate with the java EGLSDK command.

If you generate in the EGL SDK and not in the workbench, the situation is asfollows:v Project information is not available.v The command-line option eglpath replaces the functionality of the EGL build

path.v The rules for when to use eglpath are equivalent to the rules for when to use the

EGL build path.

The eglpath option specifies a list of root directories, separated by semicolons.These are root directories that contain EGL file within an EGL package structure.

For example, suppose you have files belonging to Projects A and B, on your Cdrive, and each of those projects has two packages: Project A has myPackage1 andmyPackage2, and Project B has myPackageX and myPackageY.

In this example, you would set the eglpath argument to:C:\ProjectA\EGLSource;C:\ProjectB\EGLSource

Note: The EGL package structure must be maintained under the specified rootdirectories, so that the generator can resolve references to parts correctly.

Related concepts

“EGL command file” on page 16Related tasks

“Generation using the EGL software development kit (SDK)” on page 15Related reference


EGLPREP batch command utility

Use the EGLPREP command outside of the Eclipse IDE to prepare multiplegenerated COBOL programs on the host. The utility monitors a specified folder forbuildplan files created by the EGL COBOL generation process. When EGLPREPfinds a new buildplan file, it starts a new thread and launches the buildplan. Youmay set an optional parameter to limit the number of threads to be started.


As each build plan finishes, EGLPREP updates a history file namedbatchBuild.html in the same folder where the utility looks for buildplan files. Thisfile shows the results of each completed build plan.

If you compile COBOL programs within the IDE, EGL waits for each compile tofinish before generating the next program. By setting the prep build descriptoroption to NO, you shift responsibility for compilation to the EGLPREP utility,which takes advantage of the ability of the z/OS and iSeries to run multiplecompilations at the same time.

Prerequisitesv Make sure that eglbatchgen.jar is in both your PATH and CLASSPATH system

variables. The JAR file is in the following directory:shared_resources\plugins\com.ibm.etools.egl.batchgeneration_version\runtime

shared_resourcesThe shared resources directory for your product, such as C:\ProgramFiles\IBM\SDP70Shared on a Windows system or /opt/IBM/SDP70Shared on aLinux system. If you installed and kept a previous version of an IBMproduct containing EGL before installing your current product, you mayneed to specify the shared resources directory that was set up in the earlierinstall.


v Set up the Security Manager to handle user IDs and passwords. The build plancontains a host machine name and user ID, but not a password. EGLPREPqueries the Security Manager when it launches a build plan to retrieve theappropriate password for the host and user ID.Before running EGLPREP, run the following command to start and populate theSecurity Manager:java com.ibm.etools.egl.distributedbuild.security.CCUconfig

The Security Manager displays a dialog. You can use the Client items tab to addhost/user/password combinations.Alternatively, you can run a preliminary build from the IDE with the prep builddescriptor option set to YES. The Security Manager will start automatically (ifnot already running) and will store host/user/password information from thebuild file.If you have already stored password information, you can run a build client jobfrom the command line to automatically start the Security Manager.

Syntax

Enter the following command at the command prompt, on a single line:java EGLPREP foldername [-searchSubfolders]

[-maxThreads n][-clearHistory]

foldernameThe name of the folder that EGLPREP should monitor for new build plans.


-searchSubfoldersTells EGLPREP to search subfolders under foldername for new build plans.

-maxThreads nTells EGLPREP to limit the threads to the specified number. The default is1.

-clearHistoryTells EGLPREP to delete the contents of the batchBuild.html file beforelogging subsequent history.

Related tasks

“Using eglpath with the EGL SDK” on page 22Related reference


The EGL maintenance tool, EGLMAINT

EGLMAINT is a program that should be run after applying a fix for a defect in theproduct. It ensures that the java EGLSDK command continues to work properly. Youdo not need to run EGLMAINT after installing an iFix.

Running EGLMAINT changes the contents of a JAR file, eglbatchgen.jar. It alsoupdates the EGL system libraries. Both of these are in the plugincom.ibm.etools.egl.batchgeneration. The original versions of the JAR file and thelibraries are preserved in case of error. They are renamed, using a time stamp thatindicates when EGLMAINT was used. For example, eglbatchgen.jar might berenamed to eglbatchgen.2007-Jan-02_03-53-59PM.jar

Running the EGL maintenance tool in version 7.0

To run the EGLMAINT program, follow these steps:1. Exit the EGL product.2. Make sure that your Java classpath provides access to the following:

v startup.jar, which is in the product installation directory, in the /eclipsesubdirectory.

v the plugin com.ibm.etools.edt.core.ide_version, where version is thecurrent version of the product; the plugin can be found in your product’sshared resources directory.

3. Enter the command for the EGLMAINT program at the command line:java EGLMAINT

.4. The EGLMAINT program creates a new version of the eglbatchgen.jar file and

the EGL system libraries in the following plugin:com.ibm.etools.edt.core.ide_version (where version is the current version ofthe product). The new version of the JAR file and system libraries must becopied to your installation directory. Follow these steps:a. Copy the new eglbatchgen.jar file, and paste it into the

installationDir\bin\EGLSDK\runtime directory (where installationDir is theinstallation directory for your product, such as C:\ProgramFiles\IBM\SDP70).

b. Copy the contents of the /lib subdirectory in the following location:


shared_resources\eclipse\plugins\com.ibm.etools.edt.core.ide_version

shared_resourcesThe shared resources directory for your product, such as C:\ProgramFiles\IBM\SDP70Shared on a Windows system or /opt/IBM/SDP70Sharedon a Linux system. If you installed and kept a previous version of anIBM product containing EGL before installing your current product, youmay need to specify the shared resources directory that was set up inthe earlier install.

versionThe installed version of the plugin, including three numbers separatedby periods, a string separator, and the date and time that the pluginwas built; for example, 7.0.0.RFB_20070120_1300. If more than one ispresent, use the one with the most recent version number, unless youhave a reason to use an older version.

c. Paste the contents of the /lib subdirectory into the installationDir\bin\EGLSDK\lib directory (where installationDir is the installation directory foryour product).

Related concepts

“Generation using the EGL software development kit (SDK)” on page 15



EGL Generation Results view

The EGL Generation Results view displays code-preparation messages that are theresult of generation performed in the workbench. These messages may be errors,warnings, or informational messages. This view is available only when generatingfrom the workbench. The format is as follows:msgid messagemsgid

Is the message identifier.message

Is the text of the message.

Generation results are displayed in the view in a table format. On the left is thegenerated part, on the right is the result that relates to that part. The resultmessages can be a combination of validation, production, and preparation results.You can open this view at any time, but it displays data only after you generateoutput.

If you want to remove a part from the EGL Generation Results view, click the partname on the left side of the view, and then click one of the following options:v Remove Item

v Remove All Items

v Remove Items Without Errors

Related concepts

“Generation output and associated files” on page 91“Introduction to EGL generation” on page 1



Creating and maintaining a build file

An EGL build file (extension EGLBLD) contains any number of build parts and iswritten in Extensible Markup Language (XML). The build file has a specific format;see “EGL build-file format” on page 30.

When you create a new EGL project, EGL Web project, or EGL Plug-in project inthe workbench, the New Project wizards provide an option to ″Create new projectbuild descriptor(s) automatically.″ This default option does the following:v Creates the basic build descriptor parts you need to generate code based on

whether you select Java or COBOL under ″Target Runtime Platform″. However,in most cases you must modify the build descriptor parts according to yourparticular needs. For example, you might need to set the system build descriptoroption to specify the ZOSBATCH runtime environment.

v Sets the Debug build descriptor and Target system build descriptor propertiesin the EGL Default Build Descriptor category of the project properties. You canreview or change the default build descriptors as described in “Setting thedefault build descriptors” on page 38. In addition, if you use the menu optionGenerate With Wizard when you generate your parts, you have the opportunityto override the default build descriptor.

If you do not select the option to Create new project build descriptor(s)automatically, you can create your own build file manually or specify your defaultbuild descriptors manually at a later time.

Note: EGL build parts are written in XML. Therefore, you have the choice of usingthe graphical EGL Build Parts Editor, or using a text editor to edit the XML.

To create a build file manually, follow these steps:1. Identify a project or folder to contain the file. You must create a project or

folder if you do not already have one. The project should be an EGL project,EGL Web project or EGL Plug-in project.

2. In the workbench, click File → New → EGL Build File.3. Select the project or folder that will contain the EGL build file. In the File name

field, type the name of the EGL build file, for example MyEGLbuildParts. Theextension .eglbld is required for the file name. An extension is automaticallyappended to the end of the file name if no extension is specified; if theextension is invalid an error message is generated and the file is not created.

4. Click Finish to create the build file with no EGL build part declaration. Thebuild file appears in the Project Explorer view and automatically opens in theEGL Build Parts Editor.

5. To add an EGL build part before creating the build file, click Next. Select thetype of build part to add, then click Next. Type a name and a description forthe build part, then click Finish. The build file appears in the Project Explorerview and automatically opens in the EGL Build Parts Editor.Related tasks

“Adding a bind control part to an EGL build file” on page 268“Adding a build descriptor part to an EGL build file” on page 38“Adding a linkage options part to an EGL build file” on page 63“Adding a link edit part to an EGL build file” on page 273


“Adding a resource associations part to an EGL build file” on page 69“Adding an import statement to an EGL build file” on page 31“Editing a bind control part in an EGL build file” on page 269“Editing a link edit part in an EGL build file” on page 274“Editing an import statement in an EGL build file” on page 32“Editing a resource associations part in an EGL build file” on page 69Related reference

“EGL build-file format”

EGL build-file format

The structure of a .eglbld file is as follows:<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE EGL PUBLIC "-//IBM Corporation, Inc.//DTD EGL Build Parts 6.0//EN" ""><EGL>



</EGL>

Specify <import> statements to enable the current build file to refer to parts inother build files. For example, if the next build descriptor in a chain, or anotherbuild part that is referred to by a build descriptor option, is in a different buildfile, you must include an <import> statement to point to the other build file. Anexample of an <import> statement is as follows:

<import file="myBldFile.eglbld"/>

You declare parts from this list:v <BindControl>

v <BuildDescriptor>

v <LinkEdit>

v <LinkageOptions>

v <ResourceAssociations>

The following is a simple example:<EGL>

<import file="myBldFile.eglbld"/><BuildDescriptor name="myBuildDescriptor"

genProject="myNextProject"system="WIN"J2EE="NO"genProperties="GLOBAL"genDataTables="YES"dbms="DB2"sqlValidationConnectionURL="jdbc:db2:SAMPLE"sqlJDBCDriverClass="COM.ibm.db2.jdbc.app.DB2Driver"sqlDB="jdbc:db2:SAMPLE"

</BuildDescriptor></EGL>

You can review the build file DTD, which is at the following location:shared_resources\plugins\com.ibm.etools.edt.common_version\dtd\egl_6_0.dtd

shared_resourcesThe shared resources directory for your product, such as C:\Program


Files\IBM\SDP70Shared on a Windows system or /opt/IBM/SDP70Shared on aLinux system. If you installed and kept a previous version of an IBM productcontaining EGL before installing your current product, you may need tospecify the shared resources directory that was set up in the earlier install.


The location of this DTD file should be all on one line.Related tasks

“Adding a bind control part to an EGL build file” on page 268“Adding a build descriptor part to an EGL build file” on page 38“Adding a linkage options part to an EGL build file” on page 63“Adding a link edit part to an EGL build file” on page 273“Adding a resource associations part to an EGL build file” on page 69“Adding an import statement to an EGL build file”“Creating and maintaining a build file” on page 29“Editing a bind control part in an EGL build file” on page 269“Editing a link edit part in an EGL build file” on page 274“Editing an import statement in an EGL build file” on page 32“Editing a resource associations part in an EGL build file” on page 69“Removing an import statement from an EGL build file” on page 32

Adding an import statement to an EGL build file

Import statements allow EGL build files to reference parts in other build files.

To add an import statement to an EGL build file, follow these steps:1. Open an EGL build file with the EGL Build Parts Editor. If you do not have a

file open, do this in the Project Explorer:a. Right-click on the build file in the Project Explorer.b. Select Open With → EGL Build Parts Editor.

2. Click the Imports tab in the build parts editor.3. Click the Add button.4. Type or select the name of the file or folder to import, then click OK.

Note: If the imported file or folder is in a different project from your current one,then the imported file or folder’s project must be included in the EGL buildpath for the current project.

Related tasks

“Creating and maintaining a build file” on page 29“Editing an import statement in an EGL build file” on page 32“Removing an import statement from an EGL build file” on page 32

Creating and maintaining a build file 31

Editing an import statement in an EGL build file


To edit an import statement in an EGL build file, do the following:1. Open the EGL build file with the EGL Build Parts Editor. If you do not have a

file open, go to the Project Explorer and perform these steps:a. Right-click on the build file in the Project Explorer.b. Select Open With → EGL Build Parts Editor.

2. Click the Imports tab in the build parts editor. The import statements aredisplayed.

3. Select the import statement you want to change; then click Edit.4. Type or select the name of the file or folder to import, then click OK.

Related tasks

“Adding an import statement to an EGL build file” on page 31“Creating and maintaining a build file” on page 29“Removing an import statement from an EGL build file”

Removing an import statement from an EGL build file


To remove an import statement in an EGL build file, follow these steps:1. Open the EGL build file with the EGL Build Parts Editor. If you do not have a

file open, do the following in the Project Explorer:a. Right-click on the build file in the Project Explorer.b. Select Open With → EGL Build Parts Editor.

2. Click the Imports tab in the build parts editor. The import statements aredisplayed.

3. Select the import statement you want to remove, then click Remove.Related tasks

“Adding an import statement to an EGL build file” on page 31“Creating and maintaining a build file” on page 29“Editing an import statement in an EGL build file”


Build descriptor part

A build descriptor part controls the generation process. The build descriptor partcontains the following information:

Build descriptor optionsThese specify how to generate and prepare EGL output, and a subset ofthe build descriptor options can cause other build parts to be included inthe generation process. Some build descriptor options include settings thatare stored as Java runtime properties.

Symbolic parametersA symbolic parameter is a variable that is used to affect placement andpreparation of generated output. Symbolic parameters are only used whenyou are generating a COBOL program.

Java run-time propertiesThe Java run-time properties enable you to set information to be includedin a Java run-time properties file. You can specify properties that deal withdatabase connections and date formats.

In the EGL Build Parts Editor, you can select and edit build descriptor options,symbolic parameters, and Java run-time properties.

Master build descriptors and build descriptor chainsYour system administrator may require that you use a master build descriptor tospecify information that cannot be overridden and that is in effect for everygeneration that occurs in your installation of EGL. The system administratoridentifies that part by name, along with the EGL build file that contains the part.

If the information in the master build descriptor is not sufficient for a particulargeneration process or if no master build descriptor is identified, you can specify abuild descriptor at generation time, along with the EGL build file that contains thebuild descriptor part.

You can create a chain of build descriptors from the generation-specific builddescriptor, so that the first in the chain is processed before the second, and thesecond before the third. When you define a given build descriptor, you begin achain (or continue one) by assigning a value to the nextBuildDescriptor builddescriptor option. Your system administrator can use the same technique to createa chain from the master build descriptor. The implication of chaining informationis described later.

Any build part referenced by a build descriptor must be visible to the referencingbuild descriptor. For example, the build part can be a linkage options part or aresource associations part, or the next build descriptor.

Precedence of optionsFor a given build descriptor option, the value that is initially processed atgeneration time stays in effect. The following list shows the overall order ofprecedence:1. The master build descriptor


2. Certain build descriptor options containing override values that are specified atgeneration time, if you use the Generate With Wizard menu option; however,these options cannot override values set in the master build descriptor.

3. The generation-specific build descriptor, followed by the chain that extendsfrom it

4. The chain that extends from the master build descriptor

The benefit of this scheme is convenience:v The system administrator can specify unchanging values by setting up a master

build descriptor.v You can use a generation-specific build descriptor to assign values that are

specific to a particular generation.v A project manager can specify a set of defaults by customizing one or more

build descriptors. In most of these cases, the generation-specific build descriptorpoints to the first build descriptor in a chain that was developed by the projectmanager. Default options can be useful when your organization develops a setof programs that must be generated or prepared similarly.

v The system administrator can create a set of general defaults by establishing achain that extends from the master build descriptor. It is unusual to use thisfeature.

v If you need to override certain build descriptor options, such as the destinationuser ID or password, you can do it without having to set up a different builddescriptor part.

If a given build descriptor is used more than once, only the first access of thatbuild descriptor has an effect. Also, only the first specification of a particularoption has an effect.

Example

As an example, assume that the master build descriptor contains these hypotheticaloption-and-value pairs:

OptionX 02OptionY 05

In this example, the generation-specific build descriptor (called myGen) containsthese option-and-value pairs.

OptionA 20OptionB 30OptionC 40OptionX 50

As identified in myGen, the next build descriptor is myNext01, which containsthese:

OptionA 120OptionD 150

As identified in myNext01, the next build descriptor is myNext02, which containsthese:

OptionB 220OptionD 260OptionE 270

As identified in the master build descriptor, the next build descriptor is myNext99,which contains this:


OptionW myUserIDOptionZ 99

EGL accepts option values in the following order:1. Values for options in the master build descriptor:

OptionX 02OptionY 05

Those options override all others.2. Values in the generation-specific build descriptor myGen:

OptionA 20OptionB 30OptionC 40

The value for OptionX in myGen was ignored.3. Values for other options in myNext01and myNext02:

OptionD 150OptionE 270

The value for OptionA in myNext01 was ignored, as were the values forOptionB and OptionD in myNext02.

4. Values for other options in myNext99:OptionW myUserIDOptionZ 99

5. In addition, if you use the generation wizard, you can choose to overridecertain build descriptor options, such as the destination user ID and password,for the system where the generation output is going to be prepared fordeployment. For example, if OptionW in myNext99 is the destUserID builddescriptor option, and you use the generation wizard, you have theopportunity to set or change the value of OptionW at generation time.Related concepts

“Overview of Java runtime properties” on page 153“Symbolic parameters used with COBOL generation” on page 246Related tasks

“Adding a bind control part to an EGL build file” on page 268“Adding a build descriptor part to an EGL build file” on page 38“Adding a linkage options part to an EGL build file” on page 63“Adding a link edit part to an EGL build file” on page 273“Adding a resource associations part to an EGL build file” on page 69“Editing a bind control part in an EGL build file” on page 269“Editing a link edit part in an EGL build file” on page 274“Editing a resource associations part in an EGL build file” on page 69“Editing build descriptor options in the build descriptor part” on page 58“Editing Java runtime properties in the EGL Build Parts Editor” on page 157“Editing symbolic parameters in the build descriptor part” on page 59“Setting the master build descriptor” on page 36Related reference

“Build descriptor options” on page 41“Description of Java runtime properties” on page 159

Build descriptor part 35

Setting the master build descriptor

The master build descriptor plugin.xml file is an XML file that the workbench usesto specify the name and file path name of the master build descriptor. You needthis only if you need a master build descriptor to enforce certain options to beused for generation and you are generating from the workbench. You can use theworkbench to create this file by following these steps:1. In the workbench, click File → New → Project.2. Click Plug-in Project, and click Next.3. Create a name for your project, and click Next.4. Click Finish. The workbench opens a dialog asking if you want to open the

associated perspective. Click Yes. The MANIFEST.MF file for the project opensin an editor.

5. Click the Dependencies tab at the bottom of the editor.6. Under the Required Plug-ins section, click the Add button on the right.7. In the list of plug-ins, locate and double-click com.ibm.etools.edt.core.ide.8. Click the Extensions tab at the bottom of the editor.9. Under All Extensions, click the Add button on the right. The New Extension

window opens.10. From the list, locate and click com.ibm.etools.edt.core.masterBuildDescriptor.11. Click Finish.12. Click the plugin.xml tab at the bottom of the editor. This opens the XML file

in a text editor. Your plugin.xml file should look like this:<?xml version="1.0" encoding="UTF-8" ?><?eclipse version="3.2"?><plugin>

<extensionpoint="com.ibm.etools.edt.core.ide.masterBuildDescriptor">

</extension>

</plugin>

13. Add a blank line after this line:point="com.ibm.etools.edt.core.ide.masterBuildDescriptor">

14. In the blank line, enter (or copy and paste) this line of XML code:<masterBuildDescriptor file="myProject/myDirectory/myBuildFile"

name="myMasterBuildDescriptor"/>

15. Your completed plugin.xml file should look like the following example:<?xml version="1.0" encoding="UTF-8" ?><?eclipse version="3.2"?><plugin>

<extensionpoint="com.ibm.etools.edt.core.ide.masterBuildDescriptor"><masterBuildDescriptor file="myProject/myDirectory/myBuildFile"

name="myMasterBuildDescriptor"/></extension>

</plugin>

If you are using the EGL Software Developer’s Kit (SDK), you declare the nameand file path name of the master build descriptor in a file namedeglmaster.properties. This file must be in a directory that is listed in theCLASSPATH environment variable. The format of the eglmaster.properties file isdiscussed in the next section.


Format of the eglmaster.properties fileThe eglmaster.properties file is a Java properties file that the EGL SDK uses tospecify the name and file path name of the master build descriptor. This propertiesfile must be contained in a directory that is specified in the CLASSPATH variableof the process that invokes the EGLSDK command. The format of theeglmaster.properties file is as follows:masterBuildDescriptorName=descmasterBuildDescriptorFile=path

where:desc

The name of the master build descriptorpath

The fully qualified path name of the EGL file in which the master builddescriptor used by the EGL SDK is declared

The content of this file must follow the rules of a Java properties file. You can useeither a slash (/) or two backslashes (\\) to separate directory or file names withina path name.

You must specify both the masterBuildDescriptorName andmasterBuildDescriptorFile keywords in the properties file. Otherwise theeglmaster.properties file is ignored.

Following is an example of the contents of an eglmaster.properties file:# Specify the name of the master build descriptor:masterBuildDescriptorName=MYBUILDDESCRIPTOR# Specify the file that contains the master build descriptor:masterBuildDescriptorFile=d:/egl/builddescriptors/master.egl

As mentioned above, the above example could also have been written as:# Specify the name of the master build descriptor:masterBuildDescriptorName=MYBUILDDESCRIPTOR# Specify the file that contains the master build descriptor:masterBuildDescriptorFile=d:\\egl\\builddescriptors\\master.egl

Related topics

“Build descriptor part” on page 33“Build plan” on page 103“Introduction to EGL generation” on page 1“Choosing build descriptor options for COBOL generation” on page 245“Choosing build descriptor options for Java generation” on page 152Related tasks

“Adding a build descriptor part to an EGL build file” on page 38“Generation using the Eclipse workbench” on page 11“Generation using the EGL software development kit (SDK)” on page 15“Setting the default build descriptors” on page 38Related reference

“Build descriptor options” on page 41“EGLSDK” on page 18


Setting the default build descriptors

This topic gives instructions for setting the default build descriptors for yourprojects.

You can set the default build descriptor in one of two ways:v You can set the default build descriptor in the workbench preferences. To specify

a preference for build descriptors at the workbench level, follow these steps:1. Click Window → Preferences.2. When a list is displayed, expand EGL and click Default Build Descriptor.3. Select the Debug build descriptor and the Target system build descriptor.4. Click Apply; then click OK.

v You can specify a preference for build descriptors at the project, folder, package,or file level:1. Right-click on the project, folder, package, or file in the Project Explorer view;

from the pop-up menu, click Properties.2. Select EGL Default Build Descriptors.3. Select the Debug build descriptor and the Target system build descriptor.4. Click OK.

When you generate a part, EGL starts at the file level, and works out to theworkbench level to find the first place that you have specified a default builddescriptor. EGL uses the first specified build descriptor as the default forgenerating that part.

Related concepts

“Build descriptor part” on page 33“Setting the master build descriptor” on page 36Related tasks

“Generation using the Eclipse workbench” on page 11Setting build descriptor preferences

Adding a build descriptor part to an EGL build file

A build descriptor part controls the generation process. It contains option namesand their related values, and those option-and-value pairs specify how to generateand prepare EGL output. Some options specify other build parts, such as aresource association part, that are used in the generation process.

To add a build descriptor part, follow these steps:1. Open an EGL build file with the EGL Build Parts Editor, by going to the

Project Explorer and performing these steps:a. Right-click on the EGL build file. This will usually be found in the

EGLSource folder of your project.b. Select Open With → EGL Build Parts Editor.

2. If you are in the EGL perspective and the Outline view is not open, selectWindow → Show View → Other. The Show View window opens. ExpandGeneral and click Outline.

3. In the Outline view, right-click on the build file, then click Add Part.4. Click the Build Descriptor radio button, then click Next.


5. Choose a name for your build descriptor that adheres to EGL part nameconventions. In the Name field, type the name of your build descriptor.

6. In the Description field, type a description of your build part.7. Click Finish. The build descriptor is declared in the EGL build file and the

General Options page is displayed in the EGL Build Parts Editor.8. You can use the Build option filter to limit the displayed options to only

debug options, or to only options usable with a particular target system. Youcan also select the Show only specified options check box to reduce thedisplay to options you have previously specified.

9. Just below the Build option filter is a drop-down list labeled Load DBoptions using connection. Optionally, you can click this list to select adatabase connection. The EGL Build Parts Editor then uses that databaseconnection to automatically set values for the SQL-related build descriptoroptions.

10. Optionally, you can create a chain of build descriptors, so that the first in thechain is processed before the second, and the second before the third. If youwant to begin or continue a chain of build descriptors, specify the next builddescriptor in the nextBuildDescriptor option field of the Options list. Topopulate the nextBuildDescriptor option field, follow these steps:a. If the other build descriptor you need is in another file, add an import

statement for that file to your build file. See the topic ″Adding an importstatement to an EGL build file.″

b. Using the scroll bar on the Options list, scroll down until thenextBuildDescriptor option is in view.

c. If the nextBuildDescriptor row is not highlighted, click once to select therow.

d. Click the Value field once to put the field into edit mode.e. You can type the name of the next build descriptor in the Value field or

select an existing build descriptor from the drop-down list.Related concepts


“Adding an import statement to an EGL build file” on page 31“Editing build descriptor options in the build descriptor part” on page 58“Editing Java runtime properties in the EGL Build Parts Editor” on page 157“Removing a build descriptor part from an EGL build file”Related reference

“EGL build-file format” on page 30

Removing a build descriptor part from an EGL build file

To remove a build descriptor part from an EGL build file, follow these steps:1. Open an EGL build file with the EGL Build Parts Editor, by going to the Project

Explorer and following these steps:a. Right-click on the EGL build file.b. Select Open With → EGL Build Parts Editor.

2. If you are in the EGL perspective and the Outline view is not open, selectWindow → Show View → Other. The Show View window opens. ExpandGeneral and click Outline.


3. In the Outline view, right-click on the build descriptor part; then selectRemove.Related concepts


“Adding a build descriptor part to an EGL build file” on page 38“Editing build descriptor options in the build descriptor part” on page 58“Editing Java runtime properties in the EGL Build Parts Editor” on page 157


Build descriptor options

A build descriptor part controls the generation process. Build descriptor optionsare one of several types of information in a build descriptor part. Build descriptoroptions specify how to generate and prepare the output for your generatable parts,and subset of the build descriptor options can cause other build parts to be usedduring the generation process, or additional output files to be created during thegeneration process.

The next two tables list all the build descriptor options that can be used. The firsttable shows whether the option can be used to guide Java, JavaScript, or COBOLgeneration. The second table lists each option, a description of the option’sfunction, and the default value.

Because these tables list all available options, they are very long. For this reasonyou may want to refer to a shorter, more specific list:v “Build descriptor options used with Java” on page 144v “Build descriptor options used with JavaScript” on page 220v “Build descriptor options used with COBOL” on page 234

Table 1. Build descriptor option platform dependencies

Build descriptor option JavaJavaiSeries

Java-Script

iSeries(COBOL)

z/OSbatch

CICSforz/OS

IMSBMP

IMS/VS

“bidiConversionTable” onpage 299

Yes Yes No Yes Yes Yes Yes Yes

“bidiRuntime” on page 299 Yes No No No No No No No

“bind” on page 300 No No No No Yes Yes Yes Yes

“birtEngineHome” on page301

Yes Yes No No No No No No

“buildPlan” on page 301 Yes Yes No Yes Yes Yes Yes Yes

“cancelAfterTransfer” onpage 302

No No No No Yes No Yes Yes

“checkIndices” on page 302 No No No Yes Yes Yes Yes Yes

“checkNumericOverflow”on page 303

No No No Yes Yes Yes Yes Yes

“checkToTransaction” onpage 303

No No No No No Yes No No

“checkType” on page 304 No No No Yes Yes Yes Yes Yes

“cicsEntries” on page 304 No No No No No Yes No No

“cicsj2cTimeout” on page305


“clientCodeSet” on page306


“commentLevel” on page306


“currencyLocation” onpage 307



Table 1. Build descriptor option platform dependencies (continued)


Java-Script

iSeries(COBOL)

z/OSbatch

CICSforz/OS

IMSBMP

IMS/VS

“currencySymbol” on page307


“data” on page 308 No No No No Yes Yes Yes Yes

“dbContentSeparator” onpage 308


“dbms” on page 309 Yes Yes No No No No No No

“debugTrace” on page 309 No No No Yes Yes Yes Yes Yes

“decimalSymbol” on page310


defaultDateFormat Yes Yes No Yes Yes Yes Yes Yes

defaultMoneyFormat Yes Yes No Yes Yes Yes Yes Yes

defaultNumericFormat Yes Yes No Yes Yes Yes Yes Yes

“defaultSessionCookieID”on page 222

No No Yes No No No No No

“defaultServiceTimeout” onpage 222

No No Yes No No No No No

defaultTimeFormat Yes Yes No Yes Yes Yes Yes Yes

defaultTimeStampFormat Yes Yes No Yes Yes Yes Yes Yes

“deploymentDescriptor” onpage 224

Yes Yes Yes Yes Yes Yes No No

“destDirectory” on page315


“destHost” on page 316 Yes Yes No Yes Yes Yes Yes Yes

“destLibrary” on page 317 No No No Yes No No No No

“destPassword” on page317


“destPort” on page 318 Yes Yes No Yes Yes Yes Yes Yes

“destUserID” on page 318 Yes Yes No Yes Yes Yes Yes Yes

“eliminateSystemDependentCode”on page 225

Yes Yes Yes Yes Yes Yes Yes Yes

“enableJavaWrapperGen”on page 320

Yes Yes No Yes No Yes No Yes

“endCommArea” on page320


“errorDestination” on page321

No No No No No No Yes Yes

“fillWithNulls” on page321


“formServicePgmType” onpage 322

No No No No Yes No Yes No

“genDataTables” on page322


“genDDSFile” on page 323 No No No Yes No No No No




Java-Script

iSeries(COBOL)

z/OSbatch

CICSforz/OS

IMSBMP

IMS/VS

“genDirectory” on page323


“genFormGroup” on page324

Yes No No Yes Yes Yes Yes Yes

“genHelpFormGroup” onpage 324

Yes No No Yes No Yes No Yes

“genProject” on page 325 Yes Yes No Yes No Yes No Yes

“genProperties” on page326


“genResourceBundle” onpage 328


“genReturnImmediate” onpage 329


“genRunFile” on page 329 No No No No Yes No Yes No

“genVGUIRecords” onpage 330


“imsFastPath” on page 330 No No No No No No No Yes

“imsID” on page 331 No No No No No No Yes Yes

“imsLogID” on page 331 No No No No No No Yes Yes

“includeLineNumbers” onpage 331


“initIORecordsOnCall” onpage 332


“initNonIODataOnCall” onpage 332


“j2ee” on page 333 Yes Yes No No No No No No

“j2eeLevel” on page 333 Yes Yes No No No No No No

“leftAlign” on page 334 No No No Yes Yes Yes Yes Yes

“linkage” on page 335 Yes Yes No Yes Yes Yes Yes Yes

“linkEdit” on page 335 No No No No Yes Yes Yes Yes

“math” on page 336 No No No Yes Yes Yes Yes Yes

“maxNumericDigits” onpage 337


“mfsDevice” on page 337 No No No No No No Yes Yes

“mfsExtendedAttr” onpage 338


“mfsIgnore” on page 339 No No No No No No Yes Yes

“mfsUseTestLibrary” onpage 339


“msgTablePrefix” on page339


“nextBuildDescriptor” onpage 226

Yes Yes Yes Yes Yes Yes Yes Yes

Build descriptor options 43



Java-Script

iSeries(COBOL)

z/OSbatch

CICSforz/OS

IMSBMP

IMS/VS

“positiveSignIndicator” onpage 341

No No No Yes No No No No

“prep” on page 342 Yes Yes No Yes Yes Yes Yes Yes

“printDestination” on page343


“programPackageName”on page 344


“projectID” on page 344 No No No No Yes Yes Yes Yes

“reservedWord” on page345


“resourceAssociations” onpage 345


“resourceBundleLocale” onpage 345


“restartTransactionID” onpage 346


“restoreCurrentMsgOnError”on page 346

No No No No No No Yes No

“returnTransaction” onpage 347

No No No No No Yes No Yes

“secondaryTargetBuildDescriptor”on page 347


“separatorSymbol” on page348


“serverCodeSet” on page349


“serverType” on page 349 Yes Yes No No No No No No

“sessionBeanID” on page350


“setFormItemFull” on page352


“spaADF” on page 352 No No No No No No No Yes

“spaSize” on page 352 No No No No No No No Yes

“spaStatusBytePosition” onpage 353

No No No No No No No Yes

“spacesZero” on page 353 Yes Yes No Yes Yes Yes Yes Yes

“sqlCommitControl” onpage 354


“sqlDB” on page 355 Yes Yes No Yes Yes Yes Yes Yes

“sqlErrorTrace” on page356

No No No No Yes Yes Yes Yes

“sqlID” on page 356 Yes Yes No Yes Yes Yes Yes Yes

“sqlIOTrace” on page 357 No No No No Yes Yes Yes Yes




Java-Script

iSeries(COBOL)

z/OSbatch

CICSforz/OS

IMSBMP

IMS/VS

“sqlJDBCDriverClass” onpage 357

Yes Yes No Yes No No No No

“sqlJNDIName” on page359


“sqlPassword” on page 360 Yes Yes No Yes Yes Yes Yes Yes

“sqlSchema” on page 360 Yes Yes No No No No No No

“sqlValidationConnectionURL”on page 360


“startTransactionID” onpage 361


“statementTrace” on page361

No No No No Yes Yes Yes Yes

“synchOnPgmTransfer” onpage 362


“synchOnTrxTransfer” onpage 363

Yes Yes No No Yes No Yes No

“sysCodes” on page 363 No No No Yes Yes Yes Yes Yes

“system” on page 226 Yes Yes Yes Yes Yes Yes Yes Yes

“targetNLS” on page 365 Yes Yes No Yes Yes Yes Yes Yes

“tempDirectory” on page366


“templateDir” on page 367 No No No Yes Yes No Yes No

“transferErrorTransaction”on page 368


“truncateExtraDecimals”on page 368


“twaOffset” on page 368 No No No No No Yes No No

“useCurrentSchema” onpage 369


“userMessageFile” on page369


“useXctlForTransfer” onpage 370

No No No No Yes No Yes No

“vagCompatibility” onpage 370


“validateMixedItems” onpage 371


“validateOnlyIfModified”on page 371

No No No Yes No Yes No Yes

“validateSQLStatements”on page 372


“workDBType” on page373

No No No No No Yes No Yes




Java-Script

iSeries(COBOL)

z/OSbatch

CICSforz/OS

IMSBMP

IMS/VS

“wrapperCompatibility” onpage 373

Yes Yes No No No Yes No Yes

“wrapperJNDIPrefix” onpage 374


“wrapperPackageName”on page 374


Table 2. Build descriptor option descriptions and default values

Build descriptor option Default value Description

“bidiConversionTable” on page 299 No default value Identifies a bidirectionalconversion table, which isneeded to handle literals thatcontain Arabic or Hebrewcharacters.

“bidiRuntime” on page 299 No default value Identifies a bidirectional runtimefile, which contains options thatcontrol the bidirectionalbehavior for the fields in theform groups associated with anapplication.

“bind” on page 300 No default value Identifies the bind control part,which is meaningful only whenyou generate a COBOL programthat runs on z/OS and thataccesses SQL tables on DB2.

“birtEngineHome” on page 301 No default value Identifies the location of theBusiness Intelligence andReporting Tools (BIRT) reportengine.

“buildPlan” on page 301 YES Specifies whether a build plan iscreated.

“cancelAfterTransfer” on page 302 NO Indicates whether a generatedCOBOL program is removedfrom memory when (a) theprogram issues a transfer toprogram statement; and (b) adynamic linkage is involved.

“checkIndices” on page 302 YES Specifies whether to supportindex range and null valuechecking.

“checkNumericOverflow” on page303

YES Specifies whether to supportnumeric overflow checking in agenerated COBOL program.

“checkToTransaction” on page 303 YES Indicates whether a specialcheck is included in a generatedCICS program that issues atransfer to program statement.


Table 2. Build descriptor option descriptions and default values (continued)


“checkType” on page 304 NONE Specifies the degree to whichEGL checks at validation timefor primitive-type conflictswithin structures and records.

“cicsEntries” on page 304 NONE Specifies whether to produceCICS program and transactiondefinitions; and if so, in whatformat.

“cicsj2cTimeout” on page 305 30000 Assigns a value to thecso.cicsj2c.timeout Java runtimeproperty, which specifies thenumber of milliseconds before atimeout occurs during a call thatuses protocol CICSJ2C.

“clientCodeSet” on page 306 IBM-850 Specifies the name of the codedcharacter set that is in effect onthe workstation.

“commentLevel” on page 306 1 Specifies the extent to whichEGL system comments areincluded in output source code.

“currencyLocation” on page 307 NONE Specifies the location of acurrency symbol in a stringrepresenting a monetary value.

For Java, also assigns acharacter to thevgj.nls.currency.location Javaruntime property.

“currencySymbol” on page 307 For COBOL,determined by thelanguage code ofthe runtimesystem.

For Java,determined by thelocale of thevgj.nls.coderuntime property.

Specifies a currency symbol thatis composed of one to threecharacters.

For Java, also assigns acharacter to the vgj.nls.currencyJava runtime property.

“data” on page 308 31 Specifies whether to use theDATA(24) or DATA(31) compileoption to prepare a generatedCOBOL program.

“dbContentSeparator” on page 308 | Specifies the character used todelineate fields in a file which isused to load or unload datafrom the table of a relationaldatabase.

“dbms” on page 309 DB2 Specifies the type of databaseaccessed by the generatedprogram.




“debugTrace” on page 309 NO Indicates whether EGL embedstrace information within agenerated COBOL program.

“decimalSymbol” on page 310 For COBOL,determined by thelanguage code ofthe runtimesystem.


Specifies the symbol to use asthe decimal indicator.

For Java, also assigns acharacter to thevgj.nls.number.decimal Javaruntime property.

defaultDateFormat For COBOL,determined by thelanguage code ofthe runtimesystem.

For Java, nodefault value.

Controls the initial runtimevalue ofstrLib.defaultDateFormat.

For Java, controls the value ofstrLib.defaultDateFormatindirectly by setting thevgj.default.dateFormat Javaruntime property.

defaultMoneyFormat No default value Controls the initial runtimevalue of thestrLib.defaultMoneyFormatsystem variable.

For Java, controls the value ofstrLib.defaultMoneyFormatindirectly by setting thevgj.default.moneyFormat Javaruntime property.

defaultNumericFormat No default value Controls the initial runtimevalue of thestrLib.defaultNumericFormatsystem variable.

For Java, controls the value ofstrLib.defaultNumericFormatindirectly by setting thestrLib.defaultNumericFormatJava runtime property.

“defaultSessionCookieID” on page222

JSESSIONID Identifies the session cookieprovided to the EGL Rich UIProxy from a service.

“defaultServiceTimeout” on page222

100,000 Specifies the maximum validnumber of milliseconds thatelapse between the followingevents: when the EGL Rich UIProxy (on the Web server)invokes a service and when theProxy receives a response.




defaultTimeFormat For Java, nodefault value.

For COBOL, thedefault value isHH:mm:ss.

Controls the initial runtimevalue of thestrLib.defaultTimeFormatsystem variable.

For Java, controls the value ofstrLib.defaultTimeFormatindirectly by setting thevgj.default.timeFormat Javaruntime property.

defaultTimeStampFormat For COBOL, thedefault value isyyy.MM.ddHH:mm:ss:SSSSSS.

For Java, nodefault value.

Controls the initial runtimevalue of thestrLib.defaultTimeStampFormatsystem variable.

For Java, controls the value ofstrLib.defaultTimeStampFormatindirectly by setting thevgj.default.timestampFormatJava runtime property.

“deploymentDescriptor” on page224

No default value Contains the name of the EGLservices deployment descriptorfile; this is created to provideservice binding information forprograms, libraries, handlers,and other services that invokeservice functions.

“destDirectory” on page 315 If destHost isspecified, thedefault directory isthe same as wherethe build serverwas started; ifdestHost is notspecified, thedefault isdetermined by thegenDirectory builddescriptor option.

Specifies the name of thedirectory that stores the outputof preparation.

“destHost” on page 316 No default value Specifies the name or numericTCP/IP address of the targetsystem where the build serverresides.

“destLibrary” on page 317 QGPL Specifies the 1- to 10-charactername of the iSeries library thatreceives the objects createdduring generation and containsthe objects used at run time.

“destPassword” on page 317 No default value Specifies the password that EGLuses to log on to the systemwhere preparation occurs.

“destPort” on page 318 No default value Specifies the port on which aremote build server is listeningfor build requests.




“destUserID” on page 318 No default value Specifies the user ID that EGLuses to log on to the systemwhere preparation occurs.


YES Indicates whether the EGLgenerator ignores code that willnever run in the target system.

“enableJavaWrapperGen” on page320

YES (allow all) Specifies whether all or onlysome of the followingcomponents can be generatedwhen you attempt to generatethe program: the program, Javawrapper classes, and related EJBsession bean.

“endCommArea” on page 320 NO Indicates whether to add fourbytes of hexadecimal F values tothe end of the COMMAREA oncalls from EGL-generated CICSCOBOL programs.

“errorDestination” on page 321 ELAPRINT (forIMS™ BMP); orELADIAG (forIMS/VS)

Specifies the destination ofdiagnostic messages.

“fillWithNulls” on page 321 YES Indicates whether to fillprint-form fields with nullcharacters.

“formServicePgmType” on page 322 ALL Specifies the type of printservices programs to generate.

“genDataTables” on page 322 YES Specifies whether you want togenerate the data tables that arereferenced in the program youare generating.

“genDDSFile” on page 323 NO Indicates whether you want tocreate iSeries data descriptionspecification (DDS) files fromthe record declarations withwhich your program does inputor output.

“genDirectory” on page 323 No default value Specifies the fully qualified pathof the directory into which EGLplaces generated output andpreparation-status files.

“genFormGroup” on page 324 YES Indicates whether to generatethe form group that isreferenced in the use declarationof the program being generated.

“genHelpFormGroup” on page 324 YES Indicates whether to generatethe help form group that isreferenced in the use declarationof the program being generated.




“genProject” on page 325 No default value Places the output of Javageneration into a workbenchproject and automates tasks thatare required for Java runtimesetup.

“genProperties” on page 326 NO Specifies what kind of Javaruntime properties to generate(if any) and, in some cases,whether to generate a linkageproperties file.

“genResourceBundle” on page 328 YES Specifies whether to generate aJava resource bundle.

“genReturnImmediate” on page 329 NO Specifies whether the generatedCICS COBOL program exitswith a CICS RETURNIMMEDIATE statement.

“genRunFile” on page 329 YES Indicates whether to producesample runtime JCL for a z/OSbatch program that you aregenerating .

“genVGUIRecords” on page 330 YES Indicates whether to generatethe VGUI records that arereferenced in converse or showstatements of a Web transaction.

“imsFastPath” on page 330 NO Specifies whether the programcan run as an IMS fast-pathprogram.

“imsID” on page 331 No default value Specifies the IMS DB control IDfor your database; the value isused when you debug IMS codethat accesses DL/I.

“imsLogID” on page 331 No default value Specifies an identifier that willbe included in records writtento the IMS log.

“includeLineNumbers” on page 331 NO Specifies whether or not Javaruntime error messages containthe line number of the error.

“initIORecordsOnCall” on page 332 YES Specifies when called programIO records are initialized.

“initNonIODataOnCall” on page332

YES Specifies when called programnon-IO-record and primitivevariables are initialized.

“j2ee” on page 333 NO Specifies whether a Javaprogram is generated to run in aJ2EE environment.

“j2eeLevel” on page 333 No default value Specifies the J2EE level of theWeb application server to whichan EGL-generated Web serviceor service-binding library willbe deployed.




“leftAlign” on page 334 YES Indicates whether to left-justifythe output data on someprint-form fields.

“linkage” on page 335 No default value Contains the name of thelinkage options part that guidesaspects of generation.

“linkEdit” on page 335 No default value Identifies a link edit part, whichis meaningful only when yougenerate a COBOL program forz/OS.

“math” on page 336 COBOL Specifies whether to doarithmetic calculations based onCSP math, which is used insome COBOL programs thatwere written either with IBMCross System Product (CSP) orwith VisualAge Generator.

“maxNumericDigits” on page 337 31 Specifies the size of numericfields. This applies only toCOBOL generation.

“mfsDevice” on page 337 No default value Specifies information to includein the EGL-generated DEV andDFLD statements, forform-group generation targetedto IMS.

“mfsExtendedAttr” on page 338 YES Indicates a default value forwhether the devices supportextended attributes and forwhether a color default (CD)extended attribute is generatedfor form fields that are definedwith color = default color.

“mfsIgnore” on page 339 NO Indicates whether to includeIGNORE in the SOR parameterof the MSG statement for theEGL-generated MID and MOD.

“mfsUseTestLibrary” on page 339 NO Specifies whether the buildscript will cause the build serverto place the MFS control blocksin a test library.

“msgTablePrefix” on page 339 No default value If you generate a VGUI recordbean alone, specifies themessage-table prefix that isstored in the VGUI record bean.

“nextBuildDescriptor” on page 226 No default value Identifies the next builddescriptor in the chain.

“positiveSignIndicator” on page 341 F Specifies the character that theiSeries-based ILE COBOLcompiler uses as the positivesign for numeric data of typesDECIMAL, MONEY, NUM,NUMC, and PACF.




“prep” on page 342 YES Specifies whether EGL beginspreparation when generationcompletes successfully.

“printDestination” on page 343 PROGRAMCONTROLLED

Specifies the destination ofprinted output for basicprograms generated for CICS.

“programPackageName” on page344

No default value Names the Java package thatreceives EGL-generated outputduring program generation.

“projectID” on page 344 No default value Assigns a value to the EZEPIDsymbolic parameter, which isused in build scripts that run onz/OS.

“reservedWord” on page 345 No default value Specifies a fully qualified pathname for a text file that containsreserved words other than theEGL reserved words.

“resourceAssociations” on page 345 No default value Contains the name of a resourceassociations part, which relatesrecord parts to files and queueson the target platforms.

“resourceBundleLocale” on page345

No default value Specifies a Java locale to beincluded in the name of aresource bundle that isgenerated for a VGUI record orfor a message table, either ofwhich is used in a Webtransaction.

“restartTransactionID” on page 346 A blank Indicates the transaction IDused to restart a programgenerated for CICS for z/OS.

“restoreCurrentMsgOnError” onpage 346

YES fortransaction-oriented BMPs;else, NO

Specifies whether, if an IMSBMP ends because of an error, amessage that is being read by anEGL statement is reinserted onthe IMS message queue.

“returnTransaction” on page 347 No default value Identifies the CICS transactionthat starts when the transactionassociated with the generatedprogram ends without atransfer.


No default value Specifies a build descriptor thatguides the generation of codebeing deployed to a Webapplication server, while othercode (which is targeted for otherenvironments) is beinggenerated in the samegeneration request.




“separatorSymbol” on page 348 For COBOL,determined by thelanguage code ofthe runtimesystem.


Specifies the symbol forseparating the thousands andhundreds in a numeric value.

For Java, also assigns acharacter to thevgj.nls.number.separator Javaruntime property.

“serverCodeSet” on page 349 IBM-037 Specifies the name of the codedcharacter set that is used by thez/OS or iSeries build server.

“serverType” on page 349 No default value Identifies the type of Web serverin which your output will bedeployed.

“sessionBeanID” on page 350 No default value Identifies the name of a sessionelement in the J2EE deploymentdescriptor.

“setFormItemFull” on page 352 YES Indicates whether to displayasterisks (*) in every emptyprint-form field for which youspecified a set statement of theform set field full.

“spaADF” on page 352 NO Specifies whether the IMS/VSprogram being generatedtransfers to or from an IMSADFII program.

“spaSize” on page 352 0 Specifies the number of bytes inthe IMS scratch-pad area.

“spaStatusBytePosition” on page353

No default value Specifies the position of asegmentation status byte in theIMS scratch pad area.

“spacesZero” on page 353 NO Specifies whether a generatedprogram includes extra code toprocess numeric fields that arefilled with spaces.

“sqlCommitControl” on page 354 No default value Assigns a value to thevgj.jdbc.default.database.commitControlJava runtime property, whichspecifies whether a commitoccurs after every change to thedefault database.

“sqlDB” on page 355 No default value Specifies the default databaseused by a generated program.

“sqlErrorTrace” on page 356 NO Specifies whether a generatedCOBOL program includes thecode necessary to trace errorsthat occur during I/Ooperations against a relationaldatabase.




“sqlID” on page 356 No default value Specifies a user ID that is usedto connect to a database duringgeneration-time validation ofSQL statements, or for a Javaprogram at run time.

“sqlIOTrace” on page 357 NO Specifies whether a generatedCOBOL program includes thecode necessary to trace the I/Ooperations done against arelational database.

“sqlJDBCDriverClass” on page 357 No default value Specifies a driver class that isused to connect to a databaseduring generation-timevalidation of SQL statements orfor Java runtime in a non-J2EEenvironment.

“sqlJNDIName” on page 359 No default value Specifies the default databaseused by a generated Javaprogram that runs in J2EE.

“sqlPassword” on page 360 No default value Specifies a password that isused to connect to a databaseduring generation-timevalidation of SQL statements orin a Java program at run time.

“sqlSchema” on page 360 No default value Sets the vgj.jdbc.schema Javaruntime property.

“sqlValidationConnectionURL” onpage 360

No default value Specifies a URL that is used toconnect to a database duringgeneration-time validation ofSQL statements.

“startTransactionID” on page 361 No default value Indicates the transaction IDused to start a program that isgenerated for CICS.

“statementTrace” on page 361 NO Specifies whether a generatedCOBOL program includes thecode necessary to trace anon-SQL statement.

“synchOnPgmTransfer” on page 362 YES Specifies whether to set acommit point in CICS in a waythat minimizes the differencebetween processing on CICSand IMS.




“synchOnTrxTransfer” on page 363 NO Specifies whether a commitpoint occurs when one thefollowing kinds of programsruns a transfer to transactionstatement:

v A main program in a Javaenvironment

v A main program that isgenerated for z/OS batch

v A main program that isgenerated for IMS BMP, asdescribed in ″Runtimeconfigurations″

“sysCodes” on page 363 NO Determines the source of thereturn code that is placed in thesystem variablesysVar.errorCode in response toa file I/O error in a COBOLprogram.

“system” on page 226 No default value Specifies the target runtimeenvironment of the generatedcode. This option is required.

“targetNLS” on page 365 Based on the localeof the workstationthat doesgeneration.

Specifies the target nationallanguage code used to identifyruntime messages.

“tempDirectory” on page 366 No default value Specifies the location whereEGL places two kinds of files:the Intermediate Representation(IR) files that are created whenusing the EGLSDK, and the JSPfiles created when generating aVGWebTransaction program orVGUIRecord.

“templateDir” on page 367 None Specifies the directory thatcontains templates used toproduce runtime JCL for z/OSor runtime CL for iSeries.

“transferErrorTransaction” on page368

No default value Specifies the name of a CICStransaction that receives controlwhen a transfer statementresults in an error.

“truncateExtraDecimals” on page368

YES Specifies whether the additionaldigits after the decimal point ina numeric value will bedropped, or rounded off.

“twaOffset” on page 368 0 Specifies how many bytes in thetransaction work area (TWA) arereserved for use by non-EGLprograms in the same CICS rununit.




“useCurrentSchema” on page 369 NO If YES, EGL will prepend thecontents of thesqlLib.currentSchema systemvariable to all SQL table namesat runtime.

“userMessageFile” on page 369 No default value Specifies the generated value forthe vgj.messages.file Javaruntime property, whichspecifies a properties file thatincludes messages you create orcustomize.

“useXctlForTransfer” on page 370 NO Indicates whether to use anXCTL command to implement atransfer to program statement.

“vagCompatibility” on page 370 NO Indicates whether the generationprocess allows use of specialprogram syntax.

“validateMixedItems” on page 371 YES Specifies whether a generatedCOBOL program validates fieldsthat are of type MBCHAR.

“validateOnlyIfModified” on page371

NO Specifies whether to validateonly those text-form fields forwhich the modified data tag isset.

“validateSQLStatements” on page372

NO Indicates whether SQLstatements are validated againsta database at generation time.

“workDBType” on page 373 AUX, for CICS;DLI, for IMS

Specifies the type of workdatabase to use at run time.

“wrapperCompatibility” on page373

CURRENT Indicates how to regeneratewrappers that you intend to usewith handwritten Java codewhen the wrappers wereoriginally generated byVisualAge Generator 4.5, EGL5.x, or EGL 6.x.

“wrapperJNDIPrefix” on page 374 No default value Specifies a prefix to be added toall JNDI names for generatedsession beans.

“wrapperPackageName” on page374

No default value Specifies the package togenerate Java wrappers into.

Related concepts

“Build descriptor part” on page 33“Overview of Java runtime properties” on page 153Related tasks

“Adding a build descriptor part to an EGL build file” on page 38“Editing build descriptor options in the build descriptor part” on page 58Related reference

“Build descriptor options used with Java” on page 144


“Build descriptor options used with JavaScript” on page 220This topic lists the build descriptor options used with JavaScript, which is thegenerated language for EGL Rich UI.“Build descriptor options used with COBOL” on page 234

Editing build descriptor options in the build descriptor part

The build descriptor options you set in the build descriptor part control thedebugging and generation processes. You can specify build descriptor options byfollowing these steps:1. Locate the EGL build file you want to work with in the Project Explorer view.

To find it, open the EGL Source folder, and look for a file with the extension″eglbld″. Right-click on the build file to open the pop-up menu.

2. From the pop-up menu, select Open With → EGL Build Parts Editor. The BuildParts Editor opens the build descriptor part automatically; the default view isthe General Options view.

3. If you have the Outline view open, you will see the build descriptor part listedunder the name of your build file; double click the part to open it. If you donot have the Outline view open and want to open it, select Window → ShowView → Other; in the Show View dialog box, click to expand General and selectOutline.

4. In the General Options view of the Build Parts Editor, there is a table on theleft listing the available build descriptor options. By default, the check box nextto ″Show only specified options″ is selected. This limits the number of optionsshown. You can also limit which options are shown by choosing a targetsystem, or ″Debug,″ from the drop-down list next to ″Build option filter″. If youwant to see all available build descriptor options, clear the check box next to″Show only specified options and choose ″All″ from the ″Build option filter″list.

5. To edit the build descriptor option values, click once to select an option. Click asecond time to make the Value field editable. For options that have specificvalue settings, the second click will activate a drop-down list of availablevalues. For build descriptor options that require a string value, the second clickallows you to enter the value. Some options allow you to enter a symbolicparameter instead of an actual value.

6. Optionally, you can create a chain of different build descriptor parts, so thatthey are processed in sequence. This allows you to set some build descriptoroptions that are valid for many tasks, while leaving some that can be set forspecific tasks or environments. If you want to create or continue a chain ofbuild descriptors, specify the name of the next build descriptor in the chain inthe Value field for the nextBuildDescriptor build descriptor option. Once youhave activated the Value field, you can either choose a build descriptor fromthe drop-down list or type in the name of the build descriptor part.Related concepts

“Build descriptor part” on page 33“Symbolic parameters used with COBOL generation” on page 246Related tasks

“Adding a build descriptor part to an EGL build file” on page 38“Editing symbolic parameters in the build descriptor part” on page 59“Editing Java runtime properties in the EGL Build Parts Editor” on page 157“Editing mfsDevice options in a build descriptor part” on page 60


“Removing a build descriptor part from an EGL build file” on page 39Related reference

“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“Build descriptor options used with Java” on page 144

Editing symbolic parameters in the build descriptor part

Symbolic parameters can be used to substitute for actual values. They can bedefined in a build descriptor part and used in place of actual value settings forsome build descriptor options. They can also be passed as environmental variablesto a build script for a zSeries or iSeries build server.

To set a symbolic parameter or set of symbolic parameters for use in a builddescriptor part, follow these steps:1. First, choose an EGL build file to work with. In the Project Explorer view,

right-click on the build file to open the pop-up menu.2. In the pop-up menu, select Open With → EGL Build Parts Editor. The Build

Parts Editor opens the build descriptor part automatically; the default view isthe General Options view.

3. If you have the Outline view open, you will see the build descriptor part listedunder the name of your build file; double click the part to open it. If you donot have the Outline view open and want to open it, select Window → ShowView → Other; in the Show View dialog box, click to expand General and selectOutline.

4. On the right side of the editor is a table in which you can enter symbolicparameters. To add a new symbolic parameter, click the Add buttonunderneath the table.

5. A default name appears in the Name field. Click the field once to edit the nameof your symbolic parameter.

6. Click the Value field once to make it editable. When you have activated thefield, enter the value for your symbolic parameter.

7. Once you have symbolic parameters defined, you might want to remove someof them. To remove a symbolic parameter from the list, select the symbolicparameter and then click the Remove button underneath the table.Related concepts

“Build descriptor part” on page 33“Symbolic parameters used with COBOL generation” on page 246Related tasks

“Adding a build descriptor part to an EGL build file” on page 38“Editing mfsDevice options in a build descriptor part” on page 60“Removing a build descriptor part from an EGL build file” on page 39Related reference



Editing mfsDevice options in a build descriptor part

To edit the mfsDevice build descriptor option in a build descriptor part, do thefollowing:1. Right-click on the EGL build file.2. Select Open With → EGL Build Parts Editor.3. If the Outline view is not displayed, open that view by selecting Show View →

Outline from the Window menu.4. In the Outline view, right-click on a build descriptor and select Open. The EGL

Build Parts Editor displays the general build descriptor options for the currentpart definition.

5. At the top right-hand corner of the EGL Build Parts Editor, click the ShowMFS Devices Properties button. The build parts editor displays a table ofmfsDevice options.

6. To add a new mfsDevice option, click Add and enter values in the Height,Width, Device Statement Parameters, and Extended Attributes attributes. Forinformation on these attributes, see “mfsDevice” on page 337.Related concepts


“Adding a build descriptor part to an EGL build file” on page 38“Editing Java runtime properties in the EGL Build Parts Editor” on page 157“Removing a build descriptor part from an EGL build file” on page 39Related reference

“Build descriptor options” on page 41“mfsDevice” on page 337“mfsExtendedAttr” on page 338“mfsIgnore” on page 339


Linkage options part

A linkage options part specifies details on the following issues:v How a generated Java program or wrapper calls other generated codev How a generated COBOL program calls and is called by other generated codev How a generated Java or COBOL program starts another program

asynchronouslyv How a generated Java or COBOL program transfers control and ends processing.v How a generated CICS COBOL program accesses files on remote CICS regions

Specifying when linkage options are finalFor a generated COBOL program, the linkage options specified at generation timeare in effect at run time. For generated Java code, you can choose between thefollowing two alternatives:v The linkage options specified at generation time are in effect at run time; orv If you are using the callLink element, the linkage options specified in a linkage

properties file at deployment time are in effect at run time. Although you canwrite that file by hand, EGL generates it in this situation:– You set the linkage options callLink element remoteBind property to

RUNTIME; and– You generate a Java program or wrapper with the genProperties build

descriptor option set to GLOBAL or PROGRAM.For details on using the file, see “Linkage properties file” on page 182.

Elements of a linkage options partThe linkage options part is composed of a set of elements, each of which has a setof properties and values. The following types of elements are available:v A callLink element specifies the linkage conventions that EGL uses for a given

call.– If you are generating a COBOL program, the following relationships are in

effect:- If the callLink element refers to the generated program, that element

determines aspects of the program’s own parameters; for example, whetherthe program expects pointers to data or expects the data itself. Also, thatelement helps determine whether to generate a Java wrapper that allowsaccess to the COBOL code from native Java code; for an overview, see thetopic ″Generating a Java wrapper″.

- If the callLink element refers to a program being called by the generatedprogram, that element specifies how the call is implemented; for example,whether the call is local or remote.

– If you are generating a Java program that calls another program, and thecallLink element refers to the called program, the callLink element specifieshow the call is implemented; for example, whether the call is local or remote.If you indicate that the calling Java program makes the call through an EJBsession bean, the callLink element causes generation of an EJB session bean.


v An asynchLink element specifies how a generated Java or COBOL programstarts another program asynchronously. This occurs when the transferringprogram invokes the vgLib.startTransaction system function.

v A transferToProgram element specifies how a generated COBOL programtransfers control to a program and ends processing. This element is meaningfulonly for a main program that issues a transfer to program statement.

v A transferToTransaction element specifies how a generated program transferscontrol to a transaction and ends processing. This element is meaningful only fora main program that issues a transfer to transaction statement.

v A fileLink element specifies how a CICS COBOL program accesses a particularVSAM file or transient data queue.

Identifying the programs, files, or records that elements referenceIn each element of a linkage options part, a property (for example, pgmName)identifies the programs, files or records that the element references; and unlessotherwise stated, the value of that property can be a valid name, an asterisk, or thebeginning of a valid name followed by an asterisk. The asterisk is the wildcardequivalent of one or more characters and provides a way to identify a set ofnames.

Consider a callLink element that includes the following value for the pgmNameproperty:

myProg*

That element pertains to any EGL program part that begins with the lettersmyProg.

If multiple elements are valid, EGL uses the first element that applies. A series ofcallLink elements, for example, might be characterized by these pgmName values,in order:

YourProgramYourProg**

Consider the element associated with the last value, where the value of pgmNameis only an asterisk. Such an element could apply to any program; but in relation toa particular program, the last element applies only if the previous elements do not.For example, if your program calls YourProgram01, the linkage specified in thesecond element (YourProg*) supersedes the third element (*) to define how EGLhandles the call.

In most cases, elements with more specific names should precede those with moregeneral names. In the previous example, the element with the asterisk isappropriately positioned to provide the default linkage specifications.

Consider another example, where fileLink elements are characterized by thesefileName values, in order:

File01File**


When your program accesses a file named File01, the first element identifies howCICS accesses that file. However, when your program accesses a file namedPersonnel, the last element applies and provides the default information for how tohandle the file.

Related concepts

“Generating Java wrappers” on page 199“Linkage properties file” on page 182Related tasks

“Adding a linkage options part to an EGL build file”“Editing the asynchLink element of a linkage options part” on page 376“Editing the callLink element of a linkage options part” on page 387“Editing the fileLink element of a linkage options part” on page 407“Editing the transferToProgram element of a linkage options part” on page 411“Editing the transferToTransaction element of a linkage options part” on page416Related reference

“asynchLink element” on page 375“callLink element” on page 380“fileLink element” on page 407“linkage” on page 335“transferToProgram element” on page 410“transferToTransaction element” on page 416

Adding a linkage options part to an EGL build file

A linkage options part describes how a generated EGL program implements callsand transfers, and how the program accesses files. To add this type of part, followthese steps:1. Locate the EGL build file you want to work with in the Project Explorer view.


2. In the pop-up menu, select Open With → EGL Build Parts Editor. The BuildParts Editor opens the build descriptor part automatically; the default view isthe General Options view.

3. If you have the Outline view open, you will see the build parts listed under thename of your build file. If you do not have the Outline view open and want toopen it, select Window → Show View → Other; in the Show View dialog box,click to expand General and select Outline.

4. In the Outline view, right-click on the build file, then click Add Part.5. Click the radio button next to Linkage Options, then click Next.6. Choose a name for your linkage options part that adheres to EGL part name

conventions. In the Name field, type the name of your linkage options part.7. In the Description field, type a description of your part.8. Click Finish. The linkage options part is added to the EGL file and the linkage

options part page is opened in the EGL build parts editor.Related concepts

“Linkage options part” on page 61Related tasks

Linkage options part 63

“Editing the asynchLink element of a linkage options part” on page 376“Editing the callLink element of a linkage options part” on page 387“Editing the fileLink element of a linkage options part” on page 407“Editing the transferToProgram element of a linkage options part” on page 411“Editing the transferToTransaction element of a linkage options part” on page416“Removing a linkage options part from an EGL build file”Related reference


Removing a linkage options part from an EGL build file

To remove a linkage options part from an EGL build file, do the following:1. Locate the EGL build file you want to work with in the Project Explorer view.




4. In the Outline view, right-click on the linkage options part, then click Remove.Related concepts


“Adding a linkage options part to an EGL build file” on page 63“Editing the asynchLink element of a linkage options part” on page 376“Editing the callLink element of a linkage options part” on page 387“Editing the fileLink element of a linkage options part” on page 407“Editing the transferToProgram element of a linkage options part” on page 411“Editing the transferToTransaction element of a linkage options part” on page416


Resource associations part

The resource associations part is a set of association elements, each of which hasthese characteristics:v It is specific to a logical file or queue name; andv It has a set of entries, each specific to a target system. Each entry identifies the

file type on the target platform, along with the system name and in some casesadditional information.

You can think of an association element as a set of properties and values in ahierarchical relationship, as in the following example:

// an association elementproperty: fileNamevalue: myFile01

// an entry, with multiple propertiesproperty: systemvalue: aixproperty: fileTypevalue: spoolproperty: systemNamevalue: employee

// a second entryproperty: systemvalue: winproperty: fileTypevalue: seqwsproperty: systemNamevalue: c:\myProduct\myFile.txt

In this example, the logical file name myFile01 is related to these physical files:v employee on AIX®

v myFile.txt on Windows 2000/NT/XP

The file name must be a valid name, an asterisk, or the beginning of a valid namefollowed by an asterisk. The asterisk is the wildcard equivalent of one or morecharacters and provides a way to identify a set of names. For example, anassociation element that includes the following value for a file name pertains toany file name that begins with the letters myFile:

myFile*

If multiple elements are valid for a file name used in your program, EGL uses thefirst element that applies. For example, a series of association elements might becharacterized by the following values for a file name, in order:

myFilemyFile**

Consider the element associated with the last value, where the value of the filename is only an asterisk. Such an element could apply to any file; but in relation toa particular file, the last element applies only if the previous elements do not. Forexample, if your program references myFile01, the linkage specified in the secondelement supersedes the third element to define how the reference is handled.


At generation time, EGL selects a particular association element, along with thefirst entry that is appropriate. An entry is appropriate in either of two cases:v If a match exists between the target system for which you are generating, on the

one hand, and the system property, on the other; orv If the system property has the following value:

any

For example, if you are generating for AIX, EGL uses the first entry that refers toaix or to any.

File typesA file type determines what properties are necessary for a given entry in anassociation element. The next table describes the EGL file types.

File type Description

gsam A serial or print file that is associated with a GSAM database.

ibmcobol A serial, indexed, or relative file. ibmcobol is supported by the EGLdebugger when running on Windows or for Java code generated forWindows to provide access to remote VSAM files located on z/OS.ibmcobol is also supported by Java code generated for AIX to provideaccess to local files. ibmcobol is not supported by the EGL debuggerwhen running on Linux, nor for Java code generated for any runtimeenvironment other than Windows or AIX.

mmsgq A serial file associated with a multi-segment message queue.

mq An MQ message queue; for details on how to work with such aqueue, see your MQ documentation.

seq A serial file accessed by a COBOL program that runs on z/OS underthe control of JCL (not under CICS) or runs on iSeries. This type offile is accessed by COBOL READ/WRITE statements. On z/OS,access of the data set is faster than if you specify seqrs as the filetype. When seq is specified, however, these restrictions are in effect:

v The system name must be a DD name that matches a DD name inthe JCL

v Your code cannot change the system name at run time

seqrs A serial file accessed by a COBOL program that runs on z/OS underthe control of JCL (not under CICS). This type of file is accessed bythe EGL runtime. File access is slower than if you specify seq as thefile type, but you have greater flexibility:

v When you specify the system name, you can specify either a DDname or a data set name; for details, see the topic ″Associationelements″

v You can override the system name at runtime by changing thevalue in the record-specific variable resourceAssociation (for files)or in the system variable converseVar.printerAssociation (for printoutput).

seqws A serial file accessed by an EGL-generated Java program.

smsgq A serial or print file associated with a single-segment message queue.

spool A spool file on AIX, CICS, or Linux.

tempaux A CICS auxiliary temporary storage queue.

tempmain A CICS main temporary storage queue.

transient A CICS transient data queue.


File type Description

vsam On iSeries, this is an emulated VSAM file accessed by anEGL-generated COBOL program.

On z/OS Batch, this is a VSAM data set accessed by anEGL-generated COBOL program. This type of data set is accessed byCOBOL READ/WRITE statements, and access of the data set is fasterthan if you specify vsamrs as the file type. When vsam is specified,however, these restrictions are in effect:

v The system name must be a DD name that matches a DD name inthe JCL

v Your code cannot change the system name at run time

v A indexed record associated with the file name cannot be used in aget previous statement

On CICS, this is a VSAM data set accessed by an EGL-generatedCOBOL program. This type of data set is accessed by EXEC CICScommands. On CICS you can do the following:

v When you specify the system name, you specify the CICS FCTname.

v You can override the system name at run time by changing thevalue in the record-specific variable resourceAssociation.

v An indexed record associated with the file name can be used in aget previous statement.

vsamrs For z/OS Batch, a VSAM data set accessed by an EGL-generatedCOBOL program. This type of file is accessed by the EGL runtime.File access is slower than if you specify vsam as the file type, but youhave greater flexibility:

v When you specify the system name, you can specify either a DDname or a data set name; for details, see the topic ″Associationelements″.

v You can override the system name at run time by changing thevalue in the record-specific variable resourceAssociation (for files).

v An indexed record associated with the file name can be used in aget previous statement.

Valid file types of target runtime environment

The following table describes the valid file types available based on your targetruntime environment. It also shows the default file types according to targetruntime environment and record type.

Target runtimeenvironment IndexedRecord RelativeRecord SerialRecord

Java generation v ibmcobol * (2) v ibmcobol * (2) v seqws*

v ibmcobol * (2)

IMS/VS n/a n/a v smsgq*

v mmsgq

Resource associations part 67

Target runtimeenvironment IndexedRecord RelativeRecord SerialRecord

IMS BMP v vsam

v vsamrs*

v vsam

v vsamrs*

v seq

v seqrs*

v vsam

v vsamrs

v gsam

v smsgq

v mmsgq

iSeries COBOL v vsam* v vsam* v seq*

v vsam

z/OS Batch v vsam

v vsamrs*

v vsam

v vsamrs*

v seq

v seqrs*

v vsam

v vsamrs

z/OS CICS v vsam* v tempaux

v tempmain

v vsam*

v spool

v tempaux

v tempmain

v transient

v vsam*

Debug v ibmcobol* (1) v ibmcobol* (1) v ibmcobol (1)

v seqws

The following are some notes for the above table:

* Indicates the default file type.

(1) The ibmcobol file type is supported only by the EGL debugger whenrunning on Windows. It is only used to provide remote access from thedebugger to VSAM files on a z/OS system. The ibmcobol file type is notsupported by the EGL debugger when running on Linux.

(2) ibmcobol is supported for Java code generated for Windows to provideremote access to VSAM files on a z/OS system. ibmcobol is also supportedfor Java code generated for AIX to provide access to local files. Theibmcobol file type is not supported for Java code generated for any otherenvironment.

For further details

For information on parts, records, database support and other details specific to theEGL language, see the following topics in the EGL Language Reference:v ″Data access technologies″

v ″EGL projects, packages, and files″

v ″Naming, parts and scope″

v ″Record part″v ″File I/O″

Related tasks

“Adding a resource associations part to an EGL build file” on page 69


“Editing a resource associations part in an EGL build file”“Removing a resource associations part from an EGL build file” on page 71Related reference

“Association elements” on page 71“resourceAssociations” on page 345“system” on page 226

Adding a resource associations part to an EGL build file

A resource associations part relates a logical file name to a system resource nameon the target platform where you intend to deploy the generated code.

To add a resource associations part, follow these steps:1. Locate the EGL build file you want to work with in the Project Explorer view.




4. In the Outline view, right-click on the build file, then click Add Part.5. Click Resource Associations, then click Next.6. Choose a name for your resource associations part that conforms to EGL part

name conventions. In the Name field, type the name of your resourceassociations part.

7. In the Description field, type a description of your part.8. Click Finish. The resource associations part is added to the EGL build file and

the resource associations part page is opened in the EGL Build Parts Editor.Related concepts

“Resource associations part” on page 65Related tasks

“Editing a resource associations part in an EGL build file”“Removing a resource associations part from an EGL build file” on page 71Related reference


Editing a resource associations part in an EGL build file

A resource associations part relates a logical file name to a system resource nameon the target platform where you intend to deploy the generated code.

To edit a resource associations part, follow these steps:1. Locate the EGL build file you want to work with in the Project Explorer view.

To find it, open the EGL Source folder, and look for a file with the extensionEGLBLD. Right-click on the build file to open the pop-up menu.




4. In the Outline view, right-click a resource associations part and click Open. Theeditor displays the current part definition.

5. To add a new Association element to the part, click Add Association or pressthe Insert key, and type the logical file name. The logical file name must matchone of the following:v The fileName property for a serial, indexed, or relative record.v The queueName property for an MQ series recordv printer, if you want to define how print forms are to be implemented.

6. To create an entry to specify how your logical file is to be implemented for aparticular target system, select the row in the Association elements list thatcorresponds to your logical file name, then click Add System. To select yourtarget system, you can perform one of the following actions:v Select the corresponding row in the Association elements list, then click the

name once to put the field into edit mode. Select the new system name fromthe System drop-down list.

v In the Properties of selected system entries list, click the system propertyonce to put the Value field associated with that property into edit mode.Select the new system name from the Value drop-down list.

7. To change the default file type associated with your logical file name, you caneither:v Select the row in the Association elements list that corresponds to your

logical file name, then click the name once to put the field into edit mode.Select the new file type from the File Type drop-down list.

v Select the row in the Association elements list that corresponds to yourlogical file name. In the Properties of selected system entries list, click thefileType property once to put the Value field associated with that propertyinto edit mode. Select the file type from the Value drop-down list.

8. Modify the resource associations as needed.v To associate more than one system and set of related properties with a logical

file name, select the row in the Association elements list that corresponds toyour logical file name. At the bottom of the Association elements list, clickAdd System. The added row is now selected and available for editing.

v To remove a system and related properties from an associated logical filename, select the row in the Association elements list that corresponds to thesystem you want to remove for your logical file name. At the bottom of theAssociation elements list, click Remove or press the Delete key.

v To remove a logical file name and all associated systems, select the row inthe Association elements list that corresponds to your logical file name. Atthe bottom of the Association elements list, click Remove or press the Deletekey.

Related concepts


“Adding a resource associations part to an EGL build file” on page 69


“Removing a resource associations part from an EGL build file”Related reference


Removing a resource associations part from an EGL build file

To remove a resource associations part from an EGL build file, follow these steps:1. Locate the EGL build file you want to work with in the Project Explorer view.




4. In the Outline view, right-click on the resource associations part, then clickRemove.Related concepts


“Adding a resource associations part to an EGL build file” on page 69“Editing a resource associations part in an EGL build file” on page 69

Association elements

As described in the topic ″Resource associations part,″ the resource associationspart is composed of association elements. Each element is specific to a file name(identified by the “fileName” on page 72 property) and contains a set of entries,each with the following properties:v system

v fileType

The values of the system and fileType properties determine what additionalproperties are available to you from the following list:v commit

v conversionTable

v duplicates

v formFeedOnClose

v pcbName

v replace

v systemName

v text

You can find more information on cross-referencing record and file types in thetopic “File types” on page 66.


commitIndicates (for an EGL-generated COBOL program on iSeries) whether to enablecommitment control.

Select one of these values:

NO (the default)Use of sysLib.commit or sysLib.rollback has no effect.

YES You can use sysLib.commit and sysLib.rollback to define the end of alogical unit of work.

conversionTableSpecifies the name of the conversion table used by a generated Java programduring access of an MQ message queue.

duplicatesSpecifies (for an EGL-generated COBOL program on iSeries) whether an accessedVSAM file is allowed to contain duplicate keys.


NO (the default)No duplicate keys are allowed.

YES The VSAM file is allowed to contain duplicate keys.

The value of duplicates must be consistent with the use of the keyword UNIQUEin the data description specification (DDS) that describes the physical file oniSeries. If the value of duplicates is YES, for example, you must not specifyUNIQUE.

The next table shows the consequence of an inconsistency in the two values.

DDS keyword Value ofduplicates inthe associationelement

COBOL returncode after a fileopen

EGL return codeafter a file open

EGL I/O errorvalue

UNIQUE YES 95 00000220 invalidFormat

no UNIQUE NO 95 00000220 invalidFormat

fileNameRefers to a logical file name, as specified in one or more records. You are creatingan association element that relates this name to a physical resource on one or moretarget systems. For print output, specify the value printer.

You can use an asterisk (*) as a global substitution character in a logical file name;however, that character is valid only as the last character. See “Resourceassociations part” on page 65 for more details on using the asterisk as a wild card.


fileTypeSpecifies the file organization on the target system. You can select an explicit typelike seqws. Alternatively, you can select the value default, which is itself the defaultvalue of the fileType property. Use of the default means that a file type is selectedautomatically:v For a particular combination of target system and EGL record type.v For print output, when the file name is printer.

To find information on fileType values, along with defaults, refer to the table inthe section ″Valid file types of target runtime environment″ of the topic “Resourceassociations part” on page 65.

formFeedOnCloseIndicates whether a form feed is issued when the output of a print form ends. (Aprint form is produced when your code issues a print statement.)

This property is available only if the fileName value is printer in one of thefollowing cases:v The system value is aix, iSeriesj, or linux, and the fileType value is seqws or spool;

orv The system value is win, and the fileType value is seqws.


YES A form feed occurs (the default).

NO A form feed does not occur.

pcbNameSpecifies the name of the PCB record that is used to access an IMS message queueor GSAM database. The entry is used only in these cases:v You are generating COBOL code; andv The target system is one of these:

– imsvs (in which case the PCB record may be of type IO_PCBRecord orALT_PCBRecord)

– imsbmp (in which case the PCB record may be of type IO_PCBRecord,ALT_PCBRecord, or GSAM_PCBRecord)

– zosbatch (in which case the PCB record must be of type GSAM_PCBRecord)

replaceSpecifies whether adding a record to the file replaces the file rather thanappending to the file. This entry is used only in these cases:v You are generating Java code; andv The file is of fileType seqws.


NO (the default)Append to the file.

YES Replace the file. The first add statement for the serial file in the program,or the first add statement for the serial file after a close statement, adds thedata to the beginning of the serial file, replacing all the previous contents.


systemSpecifies the target platform. Select one of the following values:

aixAIX

imsbmpIMS BMP

imsvsIMS/VS

hpuxHP-UX

iseriesciSeries COBOL

iseriesjiSeries Java

linuxLinux

solarisSolaris

ussz/OS UNIX® System Services

winWindows 2000/NT/XP

zosbatchz/OS batch

zoscicsCICS for z/OS

anyAny target platform

systemNameSpecifies the system resource name of the file or data set associated with the filename. Enclose the value in single or double quote marks if a space or any of thefollowing characters is in the value:

% = , ( ) /

When you generate a program, the meaning of the system resource name varies bytarget system and by file type.

systemName for Java

Java programs only support the fileType seqws. The systemName is the path to thefile. The EGL debugger, when running on Windows (but not Linux), also supportsthe fileType ibmcobol. In this case the systemName is a UNC (Universal NamingConvention) path to the file.

systemName for CICS for z/OS

When the target system is CICS for z/OS, the following statements apply:


spool The system resource name is the name of a serial or print file associatedwith a JES SPOOL file. For serial files, the default name is the EGL filename. For print output, the default is printer.

Input file name: userid.classThe userid parameter is a 4- to 8-character external writer name, or anasterisk (*). If an external writer name is used, CICS requires that thefirst four characters of the external writer name be the same as the firstfour characters of the CICS APPLID used to identify the CICS region toACF/VTAM. The class parameter is a one character spool class. Theclass parameter is optional and defaults to ″A″. The maximum namesize is 10 bytes. Refer to the CICS customization manual for moreinformation.

Output file name: nodeid.userid.classThe nodeid parameter is either a 1- to 8-character system node ID, or anasterisk (*). The userid parameter is a 1- to 8-character system user ID,or an asterisk (*). The class parameter is a 1-character spool class. Theclass parameter is optional and defaults to ″A″. If class is not specified,userid is also optional, and defaults to the CICS user ID (the samevalue stored in sysVar.userID). The maximum name size is 19bytes.Multiple printer files can be open simultaneously, but multipleserial files cannot be. Refer to the CICS customization manual for moreinformation.

mq The system resource name is the name of an MQ message queue. Thedefault is the EGL queue name.

tempmainThe value is an 8-byte queue name for a main temporary storage queueassociated with a relative or serial file. The default is the EGL file name.Some queue names are reserved for use by EGL and are prefixed by theletters ″EZE″.

tempauxTEMPAUX is like TEMPMAIN, except that it is for an auxiliary temporarystorage queue.

transientThe value is a 4-byte DCT name for a transient data queue associated witha serial file or with printer output. The default is the EGL file name. Forprint output, the default is printer. The transient data queue name must bedefined to CICS.Multiple printer files can be open simultaneously, butmultiple serial files cannot be.

vsam The value is an 8-byte file control table (FCT) name for a VSAM fileassociated with an indexed, relative, or serial file.

systemName for z/OS batch

When the target system is z/OS batch, the following statements apply:v If the value of fileType is mq, the system resource name is the MQ message

queue name.v Other than that, the rules are as follows:

– If the number of characters in the system resource name is 8 or less andcontains no parentheses or periods, the systemName is considered a DDname, and an attempt is made to associate the record with that DD name. Ifthe association is not possible, the result depends on the file type:


- If the value of fileType is vsam or seq, and the data set is not found, the jobends with an error.

- If the value of fileType is vsamrs or seqrs, an attempt is made to associatethe record with a data set whose name is the system resource name. If thatassociation is not possible, the job ends with an error.

– If the number of characters in the system resource name is greater than 8 or ifthe name includes parentheses or periods, the fileName is used as the DDname, and the systemName is used as the DSNAME in the sample runtimeJCL. If the association is not possible, the result also depends on the file type:- If the value of fileType is vsam or seq, the job ends with an error.- If the value of fileType is vsamrs or seqrs, an attempt is made to associate

the record with a data set whose name is the system resource name. If thatassociation is not possible, the job ends with an error.

For serial, indexed, or relative files, the default systemName is the EGL filename. For print output, the default is printer.

systemName for iSeries COBOL

When the target system is iSeries COBOL, the following statements apply:

mqThe system resource name is the name of an MQ Series queue. The default isthe EGL queue name.

seqFor serial files, a file associated with a system sequential file, which is aphysical or logical file in *arrival sequence* organization. The systemNameproperty must be an unqualified file name, with a maximum size of 10 bytes.The runtime library list (*LIBL) and the first member in the physical or logicalfile are used to complete qualification of the file name. Override Database Filecommands can be used prior to run time to alter the resolution to the file. Atrun time, you can use the record-specific recordName.resourceAssociationsystem variable to alter the resolution to the file. The default systemName isthe EGL file name. For print output, the value is the same as spool, except thatthe seq fileType inserts a page eject at the end of the print stream when the fileis closed.

spoolA printer file object (*PRTF) such a QVGNPRTF, which is shipped with theEGL runtime product for iSeries.Output is sent to the job’s output queue as aspooled file. The systemName association element must be an unqualified filename, with a maximum size of 10 bytes. The runtime library list (*LIBL) isused to complete qualification of the file name. Override Printer Filecommands can be used prior to run time to alter the resolution to the file. Atrun time, you can used the converse.Var.printerAssocation system variable toalter the resolution to the file. The default systemName is QVGNPRTF.

Note: For printer files, seq and spool differ in that seq inserts a page eject at theend of the print stream when the file is closed.

vsamFor serial files, a file associated with a system sequential file, which is aphysical or logical file in *arrival sequence* organization. For indexed files, afile associated with a system indexed file in indexed organization. For serial,indexed, and relative files, the requirements, processing, and defaults are thesame as those for the seq fileType.


textSpecifies whether to cause a generated Java program to do the following whenaccessing a file by way of a serial record:v Append end-of-line characters during the add operation. On non-UNIX

platforms, those characters are a carriage return and linefeed; on UNIXplatforms, the only character is a linefeed.

v Remove end-of-line characters during the get next operation.


NO (the default)Do not append or remove the end-of-line characters.

YES Make the changes, as is useful if the generated program is exchanging datawith products that expect records to end with the end-of-line characters.

Related concepts


“Adding a resource associations part to an EGL build file” on page 69“Editing a resource associations part in an EGL build file” on page 69“Removing a resource associations part from an EGL build file” on page 71



Overview of EGL deployment descriptor file

An EGL service part acts much like a library in that it contains functions that canbe called by programs. However, unlike a library part, the EGL service can beexposed to non-EGL programs through the use of Web services. When a Webservice layer is created for an EGL service, external programs can call functions inthat service.

When you create a Web service, you also need to create an EGL deploymentdescriptor file. This deployment descriptor file contains information about how theEGL service part in your application is exposed to other applications. It alsocontains information about how an external service can be called by yourapplication. Thus, you create a deployment descriptor in both of the followingcases:v You want to expose an EGL service part you have written to non-EGL programs;v You are writing a program or other part that is calling a service, whether an

EGL service or an external service.

For a more detailed explanation of the deployment descriptor and how it is usedwith EGL and Web services, see “Using the deployment descriptor with services”on page 118. You can also find information on creating and using services in theEGL Programmer’s Guide, and about how service parts fit into the EGL language inthe EGL Language Reference.

Related tasks

“Using the deployment descriptor with services” on page 118Related reference

“deploymentDescriptor” on page 224“Special considerations for generating EGL or Web services in z/OS CICSenvironments” on page 128“Special considerations for generating EGL or Web services in iSeriesenvironments” on page 129



Overview of .ir files

In version 7.0 of EGL, the EGLBin directory stores a special type of file: .ir files.These are required by the EGL Builder, the EGL generator, and the EGL Debugger.For most uses, the EGLBin directory, and the .bin or .ir files in the directory, can beignored. The EGL Builder and the EGL generator take the EGL code you havewritten and create these .ir files; when Java or COBOL code is created, it is actuallycreated from the .ir files.

The contents of the EGLBin directory are more like the .class files created in the/bin directory of a Java project. The EGLBin directory should not be committed toa source code repository because the directory and its files will be recreatedwhenever the EGL Project is checked out of the repository. The files also getrewritten every time you build or generate the project.

Note: Because the EGL Builder, Generator and Debugger now act on the .ir files,your Java or COBOL code cannot be generated without these files. Thismeans you must perform a build before you generate. In version 7.0, there isa preference that is set, by default, to automatically build before generationoccurs. If you choose to turn this preference off, you must manually buildyour project before generating or you will receive an IR Not Found error.



VSAM support

Indexed, relative, and serial records can be used to access a VSAM data set, butonly if the file type in the resource association element for the record is vsam,vsamrs, or ibmcobol. The three record stereotypes correspond to VSAM files asfollows:v An indexed record corresponds to a VSAM data set that is a Key Sequenced

Data Set with a primary or alternate index.v A relative record corresponds to a VSAM data set that is a Relative Record Data

Set.v A serial record corresponds to a VSAM data set that is an Entry Sequenced Data

Set.

The resource association file types that provide VSAM access are as follows:v vsam is supported for all COBOL generation environments except IMS/VSv vsamrs is supported for COBOL generation for the z/OS Batch and IMS BMP

environmentsv ibmcobol is supported by the EGL debugger when running on Windows or for

Java code generated for Windows to provide access to remote VSAM fileslocated on z/OS. ibmcobol is also supported by Java code generated for AIX toprovide access to local files. ibmcobol is not supported by the EGL debuggerwhen running on Linux, nor for Java code generated for any runtimeenvironment other than Windows or AIX.

Remote VSAM support

To access remote VSAM files on z/OS when you debug EGL programs onWindows, you must do the following:v Satisfy the access prerequisitesv Provide resource association information and reference the resource association

part from the build descriptor that you use for debugging your program

Access prerequisites

Access requires that you first define the VSAM file on the system where you wantthe file to reside.

Remote access from the EGL debugger running on Windows 2000/NT/XP alsorequires that you install Distributed File Manager (DFM) on the workstation asfollows:1. Locate the following file in your product’s installation directory:

<installDir>\bin\vsamwin.zip

where <installdir> is the installation directory for your product.2. Unzip the file into a new directory and follow the directions in the

INSTALL.README file.


Resource Association

When you create the resource association part to use when you debug your EGLprogram on Windows, specify the file type and systemName as follows:

File typeSet the file type to ibmcobol.

systemNameSpecify the system name in the following way:

\\systemName\qualifier.fileName

machineNameThe SNA LU alias name as specified in the SNA configuration

qualifier.fileNameThe VSAM data set name, including a qualifier

The naming convention is similar to the Universal Naming Convention (UNC)format. For details on UNC format, refer to the Distributed FileManager User’sGuide, which is included in the vsamwin.zip file.

For more information about VSAM data access, see the topic ″VSAM file access″ inthe EGL Language Reference.

Related concepts

“Resource associations part” on page 65


Data conversion

Because of differences in how data is interpreted in different runtimeenvironments, your program may need to convert the data that passes from oneenvironment to another. Data moving from Java environments to COBOLenvironments, and from COBOL to Java, always need data conversion. Dataconversion occurs at COBOL preparation time and at COBOL or Java run time.

Programs supporting bidirectional languages such as Arabic or Hebrew can usebidi conversion tables to specify the reordering of text data in addition to codepage conversion. See the topic ″Bidirectional language text″ for information oncreating bidi conversion tables.

The COBOL preparation process converts file content, file-path information, andvalues of environment variables when transferring workstation-based files to abuild server. For this situation, the steps needed to establish a data conversiontable are described later in this topic.

Your program also uses a conversion table in the following run time situations:v Your generated Java code calls a program on another system that uses a

different code page (for example, a Java program calls a program on z/OS).In this case, you can specify the conversion table in a callLink element thatrefers to the called program. Alternatively, you can indicate (in that callLinkelement) that the sysVar.callConversionTable system variable identifies theconversion table at run time.

v Your generated Java code invokes a service using an EGL remote binding.In this case, you can specify the conversion table in an EGL binding, in the EGLdeployment descriptor (.egldd) file. You specify the conversion table by settingthe conversionTable property for any protocol other than local.

v Your generated COBOL program calls a program residing on a remote platformthat supports the ASCII character set.In this case, you can specify the conversion table in a callLink element thatrefers to the called program. Alternatively, you can indicate (in that callLinkelement) that the sysVar.callConversionTable system variable identifies theconversion table at run time.

v Your generated CICS COBOL program (on a platform that supports the EBCDICcharacter set) starts a program asynchronously on a platform that supports theASCII character set, as might occur when a program invokes thevgLib.startTransaction system function.In this case, you can specify the conversion table in an asynchLink element thatrefers to the record used in the vgLib.startTransaction system function.Alternatively, you can indicate (in that asynchLink element) that thesysVar.callConversionTable system variable identifies the conversion table atrun time.This is not possible for Java programs, because the vgLib.startTransactionfunction for Java can only start programs that are on the local system; becauseall programs are local, no conversion is needed.

v Your generated CICS COBOL program accesses a VSAM file or CICS transientdata queue on a platform that supports the ASCII character set.


In this case, you can specify the conversion table in a fileLink element thatrefers to the file or data queue. Alternatively, you can indicate (in that fileLinkelement) that the sysVar.callConversionTable system variable identifies theconversion table at run time.

v Your generated Java program shows a text or print form that includes series ofArabic or Hebrew characters; or presents a text form that accepts a series of suchcharacters from the user. In these cases, you specify the bidirectional conversiontable in the sysVar.formConversionTable system variable.

You might use runtime conversion in the following situations:v You do not know the runtime language and therefore do not know which

conversion table to specify at generation time. In this case, do the following:1. Set the conversionTable property in the callLink, asynchLink, or fileLink

element to specify PROGRAMCONTROLLED.2. In your program, set the value of the sysVar.callConversionTable system

variable at runtime based on input from the user.v Your program passes a record to another program, but other record variables

redefine the record that is being passed. The record and its redefinitions all referto the same area of memory, but the actual structure and types of data in therecord vary depending on which redefinition you are actually using for the call.Therefore, the requirements of data conversion also vary at runtime based on theredefinition that is being used. In this case, do the following:1. Set the conversionTable property in the callLink, asynchLink or fileLink

element to specify PROGRAMCONTROLLED.2. In your program, set the value of the sysVar.callConversionTable system

variable to blanks to indicate that automatic conversion should not be done.3. In your program, invoke the sysLib.convert system function to convert the

record variable that corresponds to the record structure that you require. ThesysLib.convert function also enables you to specify the conversion table thatyou need based on input from the user.

The next sections provide the following details:v “Data conversion when you generate a COBOL program”v “Data conversion at run time in a generated COBOL program” on page 87v “Data conversion at run time in a generated Java program” on page 87v “Conversion algorithm” on page 88

Data conversion when you generate a COBOL programWhen COBOL is generated on a workstation and prepared on a z/OS or an iSeriesbuild server, conversion is handled on the build server in accordance with yourspecification in the clientCodeSet and serverCodeSet build descriptor options.Each of those build descriptor options must identify a code set that is defined tothe ICONV conversion service on z/OS and iSeries, and default settings are usedin the absence of a specification.

Programs that support bidirectional languages like Arabic or Hebrew may alsorequire reordering of text literals in addition to code page conversion. For moreinformation, see the topic ″Bidirectional language text.″


Data conversion at run time in a generated COBOL programWhen a generated COBOL program accesses a program or file on a remote CICSregion that supports the ASCII character set, a conversion occurs in the caller, inaccordance with a conversion table. The conversion table in this case is a loadmodule that contains information on code page translation.

The next table lists the conversion tables that are shipped with EGL and can beaccessed by a generated COBOL program at run time. These conversion tablesconvert data between EBCDIC format and the Windows 2000/NT/XP ASCII codepages.

Language Table name

Brazilian Portugese ELACNPTB

Chinese, simplified ELACNCHS

Chinese, traditional ELACNCHT

English, uppercase ELACNENP

English, USA ELACNENU

French ELACNFRA

German ELACNDEU

Italian ELACNITA

Japanese, Katakana (single-byte character set) ELACNJPN

Korean ELACNKOR

Spanish ELACNESP

Swiss German ELACNDES

Data conversion at run time in a generated Java programThe following rules pertain to Java code:v When a generated Java program or wrapper calls a generated Java program,

conversion occurs in the calling program, in accordance with a set of EGLclasses initiated at run time. In most cases no conversion at all is needed, even ifthe caller is accessing a remote platform that uses a code page that is differentfrom the code page used by the invoker. However, you must specify aconversion table in the following situation:– The calling program is Java code and is on a system that supports one code

page– The called program is a non-Java program and is on a system that supports

another code pageThe table name in this case is a symbol that indicates the kind of conversion thatis required at run time.

v When a generated Java program accesses a remote MQ message queue,conversion occurs in the caller, in accordance with a set of EGL classes started atrun time. If the caller is accessing a remote platform that uses a code page thatis different from the code page used by the invoker, specify a conversion table inthe association element that refers to the MQ message queue.

The next table lists the conversion tables that generated Java code can access at runtime. Each name has the format CSOcx. Variables are explained in the followinglist:

Data conversion 87

c This variable represents the character set supported on the called program’splatform. Select one of these:v J for Java (if the called program is an EGL-generated Java program)v E for EBCDIC (if the called program is an EGL-generated COBOL program)

x This variable represents the code page number for the specified language onthe remote program’s platform. Each number is specified in the Character DataRepresentation Architecture Reference and Registry, SC09-2190. The registryidentifies the coded character sets supported by the conversion tables.

Remote Platforms

Language Linux UNIXWindows

2000/NT/XP

z/OS UNIXSystem

Services oriSeries Java

z/OS oriSeries

COBOL

Arabic CSOJ1046 CSOJ1046 CSOJ1256 CSOJ420 CSOE420

Chinese,simplified

CSOJ1381 CSOJ1381 CSOJ1386 CSOJ1388 CSOE1388

Chinese,traditional


Cyrillic CSOJ866 CSOJ866 CSOJ1251 CSOJ1025 CSOE1025

Danish CSOJ850 CSOJ850 CSOJ850 CSOJ277 CSOE277

EasternEuropean


English (UK) CSOJ850 CSOJ850 CSOJ1252 CSOJ285 CSOE285

English (US) CSOJ850 CSOJ850 CSOJ1252 CSOJ037 CSOE037

French CSOJ850 CSOJ850 CSOJ1252 CSOJ297 CSOE297

German CSOJ850 CSOJ850 CSOJ1252 CSOJ273 CSOE273

Hebrew CSOJ856 CSOJ856 CSOJ1255 CSOJ424 CSOE424

Japanese CSOJ943 CSOJ943 CSOJ943 CSOJ1390(Katakana

SBCS),CSOJ1399

(Latin SBCS)

CSOE1390(Katakana

SBCS),CSOE1399

(Latin SBCS)

Korean CSOJ1363 CSOJ1363 CSOJ1363 CSOJ1364 CSOE1364

Portuguese CSOJ850 CSOJ850 CSOJ1252 CSOJ037 CSOE037

Spanish CSOJ850 CSOJ850 CSOJ1252 CSOJ284 CSOE284

Swedish CSOJ850 CSOJ850 CSOJ1252 CSOJ278 CSOE278

Swiss German CSOJ850 CSOJ850 CSOJ1252 CSOJ500 CSOE500

Turkish CSOJ920 CSOJ920 CSOJ1254 CSOJ1026 CSOE1026

When you are calling a program from Java, if you do not specify a value for theconversion table in the linkage options part, the default conversion tables are thosefor English (US).

Conversion algorithmData conversion of records and structures is based on the declarations of thestructure fields that do not have a substructure.


No conversion is performed for variables that have no name (indicated by anasterisk in a structured record), or for variables of type BIN, BIGINT, BOOLEAN,INT, SMALLINT, DECIMAL, MONEY, PACF, HEX, STRING, or UNICODE.However, if you are using a bidirectional conversion table, UNICODE and STRINGvariables will be reversed as defined in the table. For more information, seeWorking with bidirectional data.

Data of type CHAR, DBCHAR, or MBCHAR is converted in accordance with theCOBOL or Java conversion tables.

For variables of type FLOAT and SMALLFLOAT, the conversion routine convertsfrom Java to zSeries COBOL and back using the IEEE 754 format for Java and theIBM 370 format for zSeries COBOL. No conversion is necessary for FLOAT andSMALLFLOAT variables between Java and iSeries COBOL.

On EBCDIC-to-ASCII conversion for MBCHAR data, the conversion routine deletesshift-out/shift-in (SO/SI) characters and inserts an equivalent number of blanks atthe end of the variable. On ASCII-to-EBCDIC conversion, the conversion routineinserts SO/SI characters around double-byte strings and truncates the value at thelast valid character that can fit in the field. If the MBCHAR field is in a variablelength record and the current record end is in the MBCHAR field, the recordlength is adjusted to reflect the insertion or deletion of SO/SI characters. Therecord length indicates where the current record ends.

For variables of type NUM or NUMC items, the conversion routine converts allbut the last byte using the CHAR algorithm. The sign half-byte, which is the firsthalf-byte of the last byte in the field, is converted according to the hexadecimalvalues shown in the next table.

Table 3. Conversion for NUM and NUMC variables

EBCDIC for type NUM EBCDIC for type NUMC ASCII

F (positive sign) C 3

D (negative sign) D 7

For variables of type DATE, INTERVAL, TIME, or TIMESTAMP, EGL converts thevalues using the CHAR algorithm and the string form of the variable.

You can find more information on the sysLib.convert() system function and thesysVar.callConversionTable system variable in the topics ″convert()″ and″callConversionTable″ in the EGL Language Reference.

Related concepts

Working with bidirectional dataRelated reference

“Association elements” on page 71“asynchLink element” on page 375“bidiConversionTable” on page 299“callLink element” on page 380“clientCodeSet” on page 306“fileLink element” on page 407“serverCodeSet” on page 349

Data conversion 89


Generation output and associated files

There are many types of generatable parts in the EGL language. In addition to theCOBOL or Java output resulting from generation, there are other files that resultfrom generation process. Most of these associated files are control files that affectthe preparation or deployment of the generated code.

The following table lists the generatable parts and whether the parts are associatedwith COBOL generation or Java generation.

Table 4. Generation output for generatable parts

Generatable part Generation type Description

DataTable generated asCOBOL

In zSeries platforms, creates a COBOLprogram that contains the data tablecontents; in iSeries platforms, creates abinary file which contains the data tablecontents.

generated as Java Creates a Java class that contains the datatable contents.

EGL deploymentdescriptor

generated asCOBOL

Creates a service binding program usedby service clients to locate and callservices. See the table below for moredetail.

generated as Java Creates a service binding XML file usedby service clients to locate and callservices. See the table below for moredetail.

JSF Handler generated as Java Creates output that controls a user’sruntime interaction with a Web page.

Library generated asCOBOL

Creates a COBOL program and providesfunctions and values for use by othergenerated COBOL programs.

generated as Java Creates a Java class and providesfunctions and values for use by othergenerated Java programs.

Program generated asCOBOL

Creates a COBOL program that can berun in the target runtime environment(z/OS batch, z/OS CICS, or iSeries).

generated as Java Creates a Java program that can be runoutside of J2EE or in the context of a J2EEclient application, Web application or EJBcontainer.

generated as Javawrapper

Creates Java source code that can be usedin a non-EGL Java program to invoke anEGL-generated program.

Report Handler generated as Java Creates a Java class that can make aJasper report.

Record with the stereotypeConsoleForm

generated as Java Creates a Java class that contains theConsoleForm.

Service generated asCOBOL

Creates a COBOL program that acts as aservice.


Table 4. Generation output for generatable parts (continued)

Generatable part Generation type Description

generated as Java Creates a Java class that acts as a service.

In addition to your Java or COBOL output, additional files are created during thegeneration process. The following table lists these other files and their file names.

The file names of these other files depend on the alias property, if any, that isspecified in the generatable part. If the alias property is not specified, the name ofthe generatable part is used but it is truncated, if necessary, to the maximumnumber of characters allowed in the runtime environment. Other characteristics ofthe alias variable in the file name are determined by the kind of output:v If you are generating a COBOL program and related output, all letters of alias

are uppercase.v If you are generating a Java program, the case of each letter in alias is taken

without change from the source code.v If you are generating a Java wrapper, the rules for naming the wrapper and EJB

session bean are as follows:– The first letter in alias is uppercase.– Every subsequent letter is lower case, with this exception: any underscore or

hyphen is eliminated, and the subsequent letter is uppercase.

Table 5. Additional files created during generation

File type Generation type Description

Bind control file COBOL for z/OSwhen the programuses SQL

This file contains the bind command thatis used in preparing an SQL program forz/OS. The file name is alias.bnd.

Build plan COBOL, and forJava when thedestDirectorybuild descriptoroption is set

This file lists the code-preparation stepsthat will occur in the target runtimeenvironment. The file name isalias_BuildPlan_timestamp.xml.

CICS table files COBOL for CICS This file specifies the CICS program andtransaction definitions that are needed fora generated COBOL program, form group,data table, or library. The file name isalias.ppt for PPT entries or RDOPROGRAM, or alias.pct for PCT entries orRDO TRANSACTION.

Data definitionspecification (DDS) files

COBOL for iSerieswhen thegenDDSFile builddescriptor is set toYES

This file contains the data descriptionspecification (DDS) files based on therecord declarations used for input oroutput in the program. The file name isalias.dds.

J2EE environment file Java, when thegenPropertiesbuild descriptoroption is set toGLOBAL orPROGRAM

This file provides entries for insertion intothe J2EE deployment descriptor. The filename is alias-env.txt.


Table 5. Additional files created during generation (continued)

File type Generation type Description

Linkage properties file Java This file guides how calls are made fromgenerated Java code, but only if decisionsare final at runtime rather than generationtime. The file name islinkageOptionsPart.properties, wherelinkageOptionsPart is the name of thelinkage options part specified in the builddescriptor.

Link edit file COBOL for z/OS There are two possible files:

v An initial link edit file generated byEGL. The file name is alias.led.

v A link edit file that provides a re-link ofthe program. This file is created only ifthere is a link edit part for the programbeing generated. The file name isalias.lkg.

Program properties file Java, when thegenPropertiesbuild descriptoroption is set toGLOBAL orPROGRAM

This file contains Java runtime propertiesin a format that is accessible only whenyou are running or debugging a Javaprogram outside of J2EE. The file name isalias.properties, or rununit.properties on aVGWebTransaction if genProperties is setto GLOBAL.

Results file COBOL, and forJava when thedestDirectorybuild descriptoroption is set

This file gives status information on thecode-preparation steps that occurred onthe target platform. The file name isalias_Results_timestamp.xml.

Sample runtime CL COBOL for iSeries This file contains sample Control Logic(CL) used to run an iSeries program. Thefile name is alias.clr.

Sample runtime JCL COBOL for z/OSBatch when thegenRunFile builddescriptor optionis set to YES

This file contains sample JCL used to runa z/OS Batch program. The file name isalias.jcx.

Enterprise JavaBean (EJB)session bean

Java wrapper This file runs in an EJB container. The filename is aliasEJBHome.java for the homeinterface, aliasEJB.java for the remote beaninterface, and aliasEJBBean.java for thebean implementation.

Services in EGL act a bit differently from other generatable parts. When yougenerate the EGL deployment descriptor, which contains binding information foryour EGL services, EGL generates the service parts and also creates other filesneeded to deploy your services. The following table shows the files created, sortedaccording to whether you are generating COBOL or Java and also according toyour target runtime environment.


Table 6. Generation output for EGL deployment descriptors

Deployment descriptorpart

Target runtimeenvironment

Resulting files

Web service entry z/OS CICSCOBOL

Generation produces the following:

v A COBOL Web service wrapperprogram used by CICS to start an EGLWeb service

v A WSDL file that is used to describe theWeb service

v A CICS Web service binding file usedby CICS to convert SOAP messages toand from COBOL data

v A CICS Web service log file used to logevents when creating the Web servicebinding file

iSeries COBOL Generation produces the following:

v A Java Web service wrapper generatedto a designated Web project. Thiswrapper provides access to the COBOLservice through a layer of Java code.


v A collection of Java classes used in Webservice data conversion

Java (allenvironments)


v A Java Web service wrapper generatedto a designated Web project


v A collection of Java classes used in Webservice data conversion

Web service client proxy z/OS CICSCOBOL


v A COBOL Web service proxy programused by EGL COBOL clients to call Webservices

v A WSDL file that is used to describe theremote Web service

v A CICS Web service binding file that isused by CICS to convert SOAPmessages to and from COBOL data

v A CICS Web service log file that is usedto log events when creating the Webservice binding file

iSeries COBOL A COBOL Web service proxy programused by EGL COBOL clients to call Webservices.

Related concepts

“Build plan” on page 103“CICS table files” on page 281“JEE environment file” on page 173“Introduction to EGL generation” on page 1


“Program properties file” on page 177Related reference

“How COBOL names are aliased” on page 100“How Java names are aliased” on page 97“How Java wrapper names are aliased” on page 98“Output of COBOL program generation” on page 275“Output of Java program generation” on page 172“Output of Java wrapper generation” on page 208



Name aliasing

If you use a name that is not valid for use in the language that you are generating,the EGL generator creates and uses an alias for the invalid name in the generatedcode. This can happen for any of these reasons:v The name uses identifier characters that are not allowed.v The name does not comply with length limitations.v The name does not comply with support for uppercase and lowercase

characters.v The name uses a word that is a reserved word in the generated language.v The name uses a word that clashes with the name alias syntax.

An alias may be generated by substituting a valid character, or set of characters,for an invalid character; by truncating names that are too long; by adding a prefixor suffix to a name; or by producing a completely different name, such asEZE00123.

You can find more information on aliases and naming conventions in the topic″Naming conventions″ in the EGL Language Reference.

Related reference

“COBOL reserved-word file” on page 258“How COBOL names are aliased” on page 100“How Java names are aliased”“How Java wrapper names are aliased” on page 98

How Java names are aliased

When you give a part a name, that name must be a valid Java identifier, exceptthat if you are using VisualAge Generator compatibility mode, you can use ahyphen (-), a number sign (#), or an at sign (@) in a part name, as long as it is notthe first character in a part name.

If you choose a name for your part that is the same as a Java keyword, or a namethat contains a dollar sign ($), hyphen, number sign, at sign, or underscore, thepart name you have chosen will not match the name used in the generated output.This is because Java reserves the use of these symbols for its own use. An aliasingmechanism in EGL automatically appends an underscore to each part name that isthe same as a Java keyword. If you specify a name that contains one or moredollar signs, hyphens, number signs, at signs, or underscores, the aliasingmechanism replaces each symbol with a numeric string representing the Unicodevalue of the replaced symbol, as follows:$ _0024- _002d@ _0040# _0023_ _005f

For example, if you named a variable class, it would be changed to the aliasclass_; and a variable named class_ would be changed to the alias class_005f.


The case you use to declare a part name is preserved. Programs XYZ and xyz aregenerated as XYZ.java and xyz.java respectively.

Note: On Windows 2000/NT/XP, if you generate parts with upper case namesinto a directory, and later generate parts with the same name in lower caseand place them in that same directory, Windows will overwrite the olderfiles.

EGL package names are always converted to lower case Java package names.

Finally, if the name of a generated Java class matches the name of a class from theJava system package java.lang, an underscore is appended to the class name:Object becomes Object_, Error becomes Error_, and so on.

Related concepts

“How COBOL names are aliased” on page 100“Name aliasing” on page 97

How Java wrapper names are aliased

The EGL generator applies the following rules to alias Java wrapper names:1. If the EGL name is all uppercase, convert it to lowercase.2. If the name is a class name or a method name, make the first character

uppercase. (For example, the getter method for x is getX() not getx().)3. Delete every underscore (_) and hyphen (-). (Hyphens are valid in EGL names

if you use VisualAge Generator compatibility mode.) If a letter follows theunderscore or hyphen, change that character to uppercase.

4. If the name is a qualified name that uses a period (.) as a separator, replaceevery period with an underscore, and add an underscore at the beginning ofthe name.

5. If the name contains a dollar sign ($), replace the dollar sign with twounderscores and add an underscore at the beginning of the name.

6. If a name is a Java keyword, add an underscore at the beginning of the name.7. If the name is * (an asterisk, which represents a filler field), rename the first

asterisk Filler1, the second asterisk Filler2, and so forth.

In addition, special rules apply to Java wrapper class names for programwrappers, record wrappers, and substructured array fields. The remaining sectionsdiscuss these rules and give an example. In general, if naming conflicts existbetween fields within a generated wrapper class, the qualified name is used todetermine the class and variable names. If the conflict is still not resolved, anexception is thrown at generation time.

Program wrapper classRecord parameter wrappers are named by using the above rules applied to thetype definition name. If the record wrapper class name conflicts with the programclass name or the program wrapper class name, Record is added at the end of therecord wrapper class name.

The rules for variable names are as follows:1. The record parameter variable is named using above rules applied to the

parameter name. Therefore, the get() and set() methods contain these namesrather than the class name.


2. The get and set methods are named get or set followed by the parameter namewith the above rules applied.

Record wrapper classThe rules for substructured array fields class names are as follows:1. The substructured array field becomes an inner class of the record wrapper

class, and the class name is derived by applying the above rules to the fieldname. If this class name conflicts with the containing record class name,Structure is appended to the field class name.

2. If any field class names conflict with each other, the qualified field names areused.

The rules for get and set method names are as follows:1. The methods are named get or set followed by the field name with the above

rules applied.2. If any field names conflict with each other, the qualified field names are used.

Substructured array field classThe rules for substructured array field class names are as follows:1. The substructured array field becomes an inner class of the wrapper class

generated for the containing substructured array field , and the class name isderived by applying the above rules to the field name.

2. If this class name conflicts with the containing substructured array field classname, Structure is appended to the field class name.

The rules for get and set method names are as follows:1. The methods are named get or set followed by the field name with the above

rules applied.2. If any field names conflict with each other, the qualified field names are used.

ExampleThe following sample program and generated output show what should beexpected during wrapper generation:

Sample programProgram WrapperAlias(param1 RecordA)

end

Record RecordA type basicRecord10 fieldA CHAR(10)[1];10 field_b CHAR(10)[1];10 field$C CHAR(10)[1];10 static CHAR(10)[1];10 fieldC CHAR(20)[1];15 field CHAR(10)[1];15 fieldD CHAR(10)[1];10 arrayField CHAR(20)[5];15 innerField1 CHAR(10)[1];15 innerField2 CHAR(10)[1];

end

Name aliasing 99

Generated outputNames of generated output

Output Name

Programwrapper class

WrapperaliasWrapper, containing a field param1, which is an instance ofthe record wrapper class RecordA

Parameterwrapper classes

RecordA, accessible through the following methods:

v getFieldA (from fieldA)

v getFieldB (from the first field-b)

v get_Field__C (from field$C)

v get_Static (from static)

v get_FieldC_itemB (from fieldB in fieldC)

v getFieldD (from fieldD)

v getArrayField (from arrayField)

ArrayField is an inner class of RecordA that contains fields that can beaccessed through getInnerField1 and getInnerField2.

Related topics

“Generating Java wrappers” on page 199“Java wrapper classes” on page 199“Name aliasing” on page 97“Output of Java wrapper generation” on page 208

How COBOL names are aliased

A COBOL name begins with a letter and is composed of one to 30 characters fromthe following set: letters A-Z, digits 0-9, and the hyphen or minus sign (-).

An EGL part name is aliased if that part name demonstrates one of the followingcharacteristics:v Invalid COBOL charactersv Lowercase lettersv Is longer than a maximum lengthv Is not unique in the programv Is a COBOL reserved word.

In all cases, characters in the alias are all upper case.

For certain parts, such as programs, data tables, services, forms, form groups, orlibraries, you can specify an alias by assigning a value to the alias property; and ifthat value is too long or has characters that are not valid in COBOL, an erroroccurs. If you did not specify a value for the property and if the value of the partname is too long, the part name is truncated to the maximum, which varies bypart type:v For data tables, 7v For forms, 8v For form groups, 6v For libraries, 8v For z/OS programs, 8


v For iSeries main programs, 7v For iSeries called programs, 8v For services, 7

EGL always aliases function names to En, where n is a one-to-five-digit numberthat is unique within the program.

EGL aliases variable names as follows:v Each character that is not valid in COBOL is replaced with an X, except that

each underscore is replaced with a hyphen (-). For example, TEMP_VARbecomes TEMP-VAR.

v If the name begins with a hyphen, the first character is changed to an X. Forexample, _TEMP_VAR2 becomes XTEMP-VAR2.

v If necessary, the name is truncated as follows:– Record names are truncated to a maximum of 10 characters.– Field names and other variable names are truncated to a maximum of 18

characters.v A hyphen is appended to the name and then followed by a one-to-five-digit

number that is unique within the program. For example,MY_CUSTOMER_RECORD becomes MY-CUSTOME-12345.Related reference

“COBOL reserved-word file” on page 258Related concepts

“How Java names are aliased” on page 97“Name aliasing” on page 97

Name aliasing 101


Build plan

The build plan is an XML file that makes the following details available atpreparation time:v The files that need to be processed on the build systemv The build scripts that are needed to process themv The location where the output will be placed

The build plan resides on the development platform and informs the build clientof all the build steps. For each step a request is made of the build server.

Unless you set the buildPlan build descriptor option to NO, EGL produces a buildplan in the following situations:v Whenever you generate a COBOL programv Whenever you generate a Java program or Java wrapper and place the output of

generation outside the workspace by setting the genDirectory build descriptoroption.

You can also create a build plan and invoke it at a later time. For details on how todo this, see “Using a build plan after generation.”

For details on the name of the build plan, see “Generation output and associatedfiles” on page 91.

Related concepts

“Build scripts” on page 105“Introduction to EGL generation” on page 1Related tasks

“Using a build plan after generation”Related reference

“Build descriptor options” on page 41“buildPlan” on page 301“Generation output and associated files” on page 91

Using a build plan after generation

You may wish to create a build plan and to use that plan at a later time. This casemight occur, for example, if a network failure prevents you from preparing codeon a remote system at generation time.

To use a build plan in this case, complete the following steps:1. Make sure that eglbatchgen.jar is in your Java classpath, as happens

automatically on the system where you install EGL. The jar file is in thefollowing directory:shared_resources\plugins\com.ibm.etools.egl.batchgeneration_version\runtime

shared_resourcesThe shared resources directory for your product, such as C:\ProgramFiles\IBM\SDP70Shared on a Windows system or /opt/IBM/SDP70Shared ona Linux system. If you installed and kept a previous version of an IBM


product containing EGL before installing your current product, you mayneed to specify the shared resources directory that was set up in the earlierinstall.


2. Similarly, make sure that your PATH variable includes that directory.3. From a command line, enter the following command:

java com.ibm.etools.egl.distributedbuild.BuildPlanLauncher bp

bp The fully qualified path of the build plan file.Related concept

“Build plan” on page 103“Generation output and associated files” on page 91“Introduction to EGL generation” on page 1Related reference



Build scripts

A build script is a file that is started by a build plan. The build script preparesoutput from generated files. The following list shows some examples of how thisworks:v A build script written in pseudo-JCL transforms a COBOL source file into an

object file, and in some cases the build script transforms one or more object filesinto a load module. This build script is used by the z/OS build server.

v A Java compiler or other .exe (binary) file or a .bat (text) file is available to abuild server on the development system or is sent to a build server on a remoteWindows 2000/NT/XP.

v A script (.scr file) or some binary code is sent to a USS build server.

You can specify the address of a remote build server by setting the destHost builddescriptor option.

COBOL build script for iSeriesThe build script for iSeries is a REXX™ program named FDAPREP and is describedin the IBM Rational Business Developer EGL Server Guide for IBM i, which isavailable in the help system.

COBOL build scripts for z/OSWhen generating COBOL for a z/OS environment, you can use build scripts tostart the z/OS COBOL compiler and the z/OS linker. If a generated program istargeted for a CICS environment, you can use a build script that calls the CICStranslator as well. If the generated program contains SQL, the build script startsthe DB2 preprocessor and starts a DB2 database bind.

The z/OS build scripts that allow you to perform all these tasks are shipped withthe z/OS build component and are installed in the z/OS build server’s pseudo-JCLPROCLIB library.

You need to customize these scripts for your working environment. For details, see“Modifying EGL build scripts for z/OS” on page 282.

Java build scriptTo prepare Java code for execution, EGL puts the javac (Java compiler) commandand its parameters in the build plan. The build plan then sends the javaccommand to the build server, along with the input required by the command.

Related concepts

“Build plan” on page 103“Build server” on page 107“Methods of initiating and controlling the generation process” on page 8“Introduction to EGL generation” on page 1Related tasks

“Modifying EGL build scripts for z/OS” on page 282Related reference


“Build descriptor options” on page 41“Build scripts delivered with EGL” on page 286“destDirectory” on page 315“destHost” on page 316“destPassword” on page 317“destUserID” on page 318“Output of COBOL program generation” on page 275“Output of Java program generation” on page 172“Output of Java wrapper generation” on page 208


Build server

A build server receives source code from a client and uses it to create executablefiles. You must start a build server prior to starting the generation process.Typically, a build server handles requests from multiple clients. If the build serverreceives several build requests at one time, the build server may start multiplethreads.

When you are generating code, you start a build server on the system which is thetarget for your generation process. For example, your target system might rununder z/OS or Windows 2000. The system initiating the generation processproduces COBOL or Java source code. If you are using the z/OS environment onyour target system, COBOL source code is sent to a specified z/OS build serverwhere a customized build script performs compiling and linking. If you aregenerating Java code, it is sent to a specified build server where the Java compileris invoked.

If you are generating Java code for Windows, you can have the Java sourcecompiled on the same system you use to perform the generation process. This iscalled a local build. In this case, you do not have to start a build server. If youwant to perform a local build, omit the destHost option from the build descriptorpart.

Related concepts

“Build scripts” on page 105“Introduction to EGL generation” on page 1Related reference

“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“Build descriptor options used with Java” on page 144“destHost” on page 316

Starting a build server on AIX, Linux, or Windows 2000/NT/XPTo start a remote build server on AIX, Linux, or Windows 2000/NT/XP, enter theccublds command in a Command Prompt window. The syntax is as follows:where

-p Specifies the port number (portno) that the server listens to, to communicatewith the clients.

-V Specifies the verbosity level of the server. You may specify this parameter upto three times (maximum verbosity).

-a Specifies the authentication mode:0 The server performs builds requested by any client. This mode is

recommended only in an environment where security is not a concern.2 The server requires the client to provide a valid user ID and password

before accepting a build. The user ID and password are first configured

ccublds -p portno

20

-V-a


by the owner of the host machine where the build server runs. You dothe configuration by using the Security Manager described below.

Setting the language of messages returned from the buildserver

The build server on Windows returns messages in any of the languages listed inthe next table, and the default is English.

Language Code

Brazilian Portugese ptb

Chinese, simplified chs

Chinese, traditional cht

English, USA enu

French fra

German deu

Italian ita

Japanese jpn

Korean kor

Spanish esp

To specify a language other than English, make sure that before you start the buildserver, the environment variable CCU_CATALOG is set to a non-English messagecatalog. The needed value is in the following format (on a single line):

shared_resources\eclipse\plugins\com.ibm.etools.egl.distributedbuild_version\executables\ccu.cat.xxx



xxxThe code for the language of interest; one of the codes listed in the previoustable

Security ManagerThe Security Manager is a server program that the build server uses toauthenticate clients that send build requests.

Setting the environment for the Security ManagerThe Security Manager uses the following Windows environment variables:


CCUSEC_PORTSets the number of the port to which the Security Manager listens. Thedefault value is 22825.

CCUSEC_CONFIGSets the path name of the file in which configuration data is saved. Thedefault is C:\temp\ccuconfig.bin. If this file is not found, the SecurityManager creates it.

CCU_TRACEInitiates tracing of the Security Manager for diagnostics purposes, if thisvariable is set to *.

Starting the Security ManagerTo start the Security Manager, issue the following command:java com.ibm.etools.egl.distributedbuild.security.CcuSecManager

Configuring the Security ManagerTo configure the Security Manager, use the Configuration Tool, which has agraphical interface. You can run the tool by issuing the following command:java com.ibm.etools.egl.distributedbuild.security.CCUconfig

When Configuration Tool is running, select the Server Items tab. Using the button’Add...’, To add the user that you want the build server to support, click the Add... button. You must define a password for the user ID. You can define thefollowing restrictions and privileges for the user:v The locations, that is, the values of the -la parameter to ccubldc command, that

this user can specify. Different locations are separated by semicolons.v The name of the build script that this user can specify. (The EGL build plan only

uses the javac command as a build script.)v Whether or not this user can send build scripts from client, that is, use the -ft

parameter of ccubldc command. (The EGL generator does not use the -ftparameter. You would specify this parameter if they were using the build forpurposes other than preparing Java-generation output.)

These definitions are kept in persistent storage, in the file specified byCCUSEC_CONFIG, and are remembered across sessions.

Related concepts

“Build server” on page 107Related tasks

“Starting a build server on z/OS”

Starting a build server on z/OSOn z/OS, you can configure the build server to perform z/OS or USS builds. Ifyou need both builds, then you need to start two servers, each listening on aunique TCP/IP port for each type.

SyntaxYou start a build server by using z/OS JCL commands. The syntax for theparameters line is as follows:

Build server 109

where

-p Specifies the port number (portno) to which the server listens to communicatewith the clients.

-V Specifies the verbosity level of the server. You may specify this parameter upto three times (maximum verbosity).

-a Specifies authentication mode:2 Server state: A (authorized). The server code was installed in an

APF-authorized library. When you initiate a build by using the remotebuild client, you must specify the build descriptor option destUserIDwith a valid TSO user ID and destPassword with a valid TSOpassword. The server performs the build transaction under the accessand authority of this user ID. Mode 2 is the default.

1 Server state: A. You can provide a valid TSO user ID and password.The server performs the build transaction under the access andauthority of this user. If you do not provide a user ID and password,the build transaction is performed under the access and authority ofthe user ID assigned to the build server job.

0 Server state: A or U (unauthorized). If U, APF-authorized buildprograms will fail. If you specify a TSO user ID and password, theserver ignores them and the build transaction is performed under theaccess and authority of the user ID assigned to the build server job.

You can use modes 1 and 2 only if the server load modules are run from anAPF-authorized library.

-n Specifies the number of concurrent builds. The default is 1. Set n equal to thenumber of concurrent builds you want to allow. Once there are n number ofconcurrent builds running, the build server queues any additional requests andsubmits them on a first come first served basis as builds are completed.

-q Specifies the size of the queue (q) for clients. The default is 10. Each queuedclient uses a TCP/IP socket. Therefore setting this too high may require moresockets than are available, causing unpredictable results. If the queue is full,subsequent clients are rejected by the server. However, the build client retriesthe build in that case.

-t Starts tracing of this server job and writes output to STDOUT. This parameteris normally used only for debugging.

ProcedureTo start a z/OS build server, complete the following steps with the CCURUN.JCL(for z/OS) or CCURUNU.JCL (for USS):1. Add a job card.2. Modify the parameters on the PARM statement of the EXEC card as necessary.

(See the parameter list above.)

// PARM ' -p portno=

-V-a 1

2

0

-n -q -tn q'


3. Modify the STEPLIB DD statement to point to the data set that contains thebuild server load modules. This library contains all the load modules that makeup the remote build server.

4. Modify the CCUWJCL DD statement to point to the data set that contains theJCL to run an individual build job. This should be a modified version of theCCUMVS.JCL (for z/OS builds) or CCUUSS.JCL (for USS builds).

5. Specify CCUBLOG as a sequential data set. This is where the log of the buildserver is written.

6. Modify the parameter (PARM=) statement as appropriate for your job (seeexample below).

7. Submit the job.

ExampleFollowing is an example of JCL that starts the build server as a batch program forz/OS builds://jobcard//*------------------------------------------------------//RUNPGM EXEC PGM=CCUMAIN,DYNAMNBR=30,REGION=7400K,TIME=NOLIMIT,// PARM='-p 2604 -a 2 -n 3 -q 20'//STEPLIB DD DSN=CCUBLD.LOADLIB,DISP=SHR//CCUWJCL DD DISP=SHR,DSN=CCUBLD.JCL(CCUMVS) for z/OS builds//*CCUWJCL DD DISP=SHR,DSN=CCUBLD.JCL(CCUUSS) for USS builds//STDOUT DD SYSOUT=*//STDERR DD SYSOUT=*//CCUBLOG DD SYSOUT=*

To modify the JCL for USS builds, move the comment indicator (* in //*CCUWJCL)after // on the previous line.

Special considerations for z/OS buildsIf you start the server on z/OS from an APF-authorized library (this is required inmodes 1 and 2 but is optional in mode 0), the build script can specify an APFauthorized program as the executable.

Note: In this case, the build script can also specify non-APF authorized programs.However, in a multistep JCL script, an authorized program cannot beexecuted after an unauthorized program.

If the server is not started from an APF-authorized library, the build script canspecify only non-APF authorized programs as executables.


The build server on z/OS returns messages in any of the languages listed in thenext table. English is the default.

Language Code




English, USA enu

French fra

Build server 111

Language Code

German deu

Italian ita

Japanese jpn

Korean kor

Spanish esp

To cause build-server messages to be returned in a language other than English,change the setting of environment variable CCU_LANG on the client machine. Thevariable contains one of the language codes listed in the previous table. To returnmessages in French, for example, set CCU_LANG to fra.

Also, the components that invoke the build server may need to issue messages ifcommunication with the build server fails. To return those messages in a languageother than English, change the setting of the environment variableCCU_CATALOG on the client machine. The value of CCU_CATALOG is a stringlike the following (on a single line):





Finally, if the build server runs under USS and you want to return messages in alanguage other than English, you also need to change the content of the shell scriptccubldw.sh. That script is customized when the USS build-server component isinstalled.

To support more than one language on USS, start a different USS build-servercomponent for each language, with each component listening on a different portand using a different version of the script.

To set the USS shell script ccubldw.sh to a specific language, add a statement likethe following (on a single line):

export CCU_CATALOG=/installationDir/usr/lpp/EnterpriseDeveloper/BuildServer/ccu.cat.xxx

installationDirDirectory in which the USS build-server component is installed


xxxThe code for the language that is supported by the script; one of the lower-casecodes listed in the previous table

Additional details on build-server configurationFor additional details on how to configure a build server, see the IBM RationalCOBOL Runtime for z/Series program directory (GI10-3242).

Related concepts


“Starting a build server on AIX, Linux, or Windows 2000/NT/XP” on page 107

Starting a build server on iSeriesThe Remote Build Server is a program, named CCUBLDS, that runs as a job on theiSeries. It listens on a tcp/ip port. Once started, it runs continuously until the job iscanceled. The following command is an example of the command to start the buildserver job:SBMJOB CMD(CALL PGM(*LIBL/CCUBLDS) PARM('-p' '2600')) JOB(CCUBLDS) JOBQ(QSYS/QSYSNOMAX)

Here the server port is 2600, but any available port number can be used. The buildserver must be invoked by an administrator userid that is authorized to access userprofiles.

Verifying the iSeries Remote Build ServerAfter the build server has started, you should verify that it is running properly. Atthe Windows workstation where the prep step will be run, do as follows:1. In the plugin named com.ibm.etools.egl.distributedbuild, locate the directory

containing the program ccubldc.exe. Add this directory to the PATHenvironment variable.

2. Run the following command from the command line:ccubldc -h host@port -au userId -ap password -b id -r 37 -k 1252

hostIP address of the iSeries host machine

portPort number of the build server

userIDUserid that the prep client uses

passwordLogin password for the userid on the iSeries host

The following is an example of the expected response:05/03/09 14:58:56 (c) Copyright, IBM Corp. 2001 Copyright (c) 2002 Rational Software Corporation05/03/09 14:58:57 *** Success ***05/03/09 14:58:57 Command: id****************** Build Script Output Follows *****************uid=926(USERID) gid=102(GROUPID) groups=102(GROUPID)****************** End Of Build Script Output ******************05/03/09 14:58:58 *--------------------------------------------------------

Build server 113


The build server on Windows returns messages in any of the languages listed inthe next table, and the default is English.

Language Code




English, USA enu

French fra

German deu

Italian ita

Japanese jpn

Korean kor

Spanish esp

To specify a language other than English, make sure that before you start the buildserver, the environment variable CCU_CATALOG is set to a non-English messagecatalog. The needed value is in the following format (on a single line):





Security ManagerThe Security Manager is a server program that the build server uses toauthenticate clients that send build requests.

Setting the environment for the Security ManagerThe Security Manager uses the following Windows environment variables:

CCUSEC_PORTSets the number of the port to which the Security Manager listens. Thedefault value is 22825.


CCUSEC_CONFIGSets the path name of the file in which configuration data is saved. Thedefault is C:\temp\ccuconfig.bin. If this file is not found, the SecurityManager creates it.

CCU_TRACEInitiates tracing of the Security Manager for diagnostics purposes, if thisvariable is set to *.

Starting the Security ManagerTo start the Security Manager, issue the following command:java com.ibm.etools.egl.distributedbuild.security.CcuSecManager

Configuring the Security ManagerTo configure the Security Manager, use the Configuration Tool, which has agraphical interface. You can run the tool by issuing the following command:java com.ibm.etools.egl.distributedbuild.security.CCUconfig

When Configuration Tool is running, select the Server Items tab. Using the button’Add...’, To add the user that you want the build server to support, click the Add... button. You must define a password for the user ID. You can define thefollowing restrictions and privileges for the user:v The locations, that is, the values of the -la parameter to ccubldc command, that

this user can specify. Different locations are separated by semicolons.v The name of the build script that this user can specify. (The EGL build plan only

uses the javac command as a build script.)v Whether or not this user can send build scripts from client, that is, use the -ft

parameter of ccubldc command. (The EGL generator does not use the -ftparameter. You would specify this parameter if they were using the build forpurposes other than preparing Java-generation output.)

These definitions are kept in persistent storage, in the file specified byCCUSEC_CONFIG, and are remembered across sessions.

Related concepts


“Starting a build server on z/OS” on page 109

Build server 115


Generating EGL and Web services

An EGL Service part, like a Library part, consists of a group of functions.Generating a service has some similarities to generating any other generatable part,but there are some unique aspects to generating services. This section covers topicsrelated to generating EGL and Web services, including the following:v A description of the EGL deployment descriptor and how it is usedv How to create and edit the EGL deployment descriptorv Issues relevant to generating services to particular environments

You can create several different kinds of EGL services, depending on your targetsystem and EGL deployment descriptor settings. For an EGL Service, either Java orCOBOL, generate the service part with the system build descriptor option set tothe appropriate target system. To deploy an EGL Service as a Web Service, add aWebService entry for an existing EGL Service part to the EGL deploymentdescriptor and generate the deployment descriptor.

The following table summarizes the kinds of EGL services available:

Table 7. Kinds of EGL services

″system″ builddescriptor option

″serverType″ builddescriptor option

Add to EGLdeploymentdescriptor? Service type

aix | hpux | iseriesj| linux | solaris |uss | win

n/a N EGL Java service

aix | hpux | iseriesc| iseriesj | linux |solaris | uss | win

WebSphere6.x |Tomcat5.x

Y JAX-RPC Web service

iseriesc | zosbatch |zoscics

n/a N EGL COBOL service

zoscics CICS3.1 Y CICS Web Service

Related reference

“Using the deployment descriptor with services” on page 118“Generating and deploying a Web service to CICS” on page 124This topic describes how to generate and deploy a Web service to z/OS CICS.Aside from setting up the relevant EGL build parts, you must set the followingCICS definitions: TRANSACTION, TCPIPSERVICE, and PIPELINE.“Special considerations for generating EGL or Web services in z/OS CICSenvironments” on page 128“Special considerations for generating EGL or Web services in iSeriesenvironments” on page 129


Using the deployment descriptor with services

When you write a service or service client in EGL, you must create an EGLdeployment descriptor to accompany it. The deployment descriptor file containsboth the information describing how your logic parts call services, and informationdescribing how your EGL services are wrapped with a Web service and exposed toexternal applications.

When used with Java generation, the generating EGL deployment descriptor filesresult in a runtime binding file (using the naming convention ddname-bind.xml).When used with COBOL generation, a binding program is generated instead. Thistopic includes information about the EGL deployment descriptor editor, thedifferent types of information included in the EGL deployment descriptor, andwhat happens when you generate the EGL deployment descriptor.

Overview

An EGL service application consists of four possible elements (as described in thetopic ″Elements of a service application″ in the EGL Programmer’s Guide):v Service partv Interface partv EGL deployment descriptorv WSDL file

EGL does not create these parts and files automatically. The deployment descriptorassociated must be created explicitly and added to the deploymentDescriptorbuild descriptor option. For instructions on creating a deployment descriptor, seethe topic ″Creating a deployment descriptor file″ in the EGL Programmer’s Guide.

After you create the EGL deployment descriptor for your service application, youcan add binding information to it with the EGL Deployment Descriptor Editor.

The remainder of this topic deals with the EGL Deployment Descriptor Editor.However, in the sections that describe the information contained in the deploymentdescriptor file, there are samples which show the actual XML code that matchesthe selections you make in the graphical editor. You can see this XML in your owndeployment descriptor file by opening it in a text editor.

Overview of the EGL Deployment Descriptor Editor

When the EGL Deployment Descriptor Editor opens, you see the following pages:v Overviewv Service Client Bindingsv Web Service Deployment

The following sections will give you more detailed information about the actionsyou can perform on each page of the editor.

Overview page

The Overview page is where you enter the alias for your EGL deploymentdescriptor, if you must designate one. You also have the choice of either copyingsettings from another deployment descriptor file, or including another deploymentdescriptor file in the file you are creating.


Clicking Copy from another EGL deployment descriptor opens the Copy fromanother egldd file window. Here, you can enter the name of another EGLdeployment descriptor file, or click the Browse button to navigate to it. When youchoose a file, the window displays a list of settings in the window for you tochoose from.

Below the Copy from another EGL deployment descriptor link is a section labeledIncludes and a table labeled EGL Deployment Descriptor (egldd) File Location.You can click the Add button to open the Include Another EGL DeploymentDescriptor File window.

The difference between including another deployment descriptor file and copyingone is that when you include one EGL deployment descriptor in another, if theoriginal deployment descriptor is changed and generated, the new file is updatedautomatically. When you copy information from another deployment descriptorinto your new file, if the original is changed, you will have to update your newfile manually.

Service Client Bindings page

A binding is information that describes the location of the service that a client isusing, and indicates a protocol for communicating with the service. Go to theService Client Bindings page of the EGL Deployment Descriptor Editor to addthis binding information.

To add a new service client binding, see the topic ″Adding service client bindinginformation for an EGL service″ in the EGL Programmer’s Guide.

After you add a binding to the list, you can change the protocol used in thebinding or the attribute values for that protocol. You can also click SharedProtocols at the bottom of the page and define a communications protocol that willbe used by more than one service binding. When you have a shared protocoldefined, that sharable protocol will be added to list of available protocol choices onthe page. The choices on this page depend on the type of service and the protocolused to access the service; see “Deployment descriptor options for service clients”on page 122 for more information.

The following example shows a sample EGL deployment descriptor, including twobindings to Web services, one binding to an EGL service, and a shared protocolbeing used to contact the EGL service:<deployment>

<bindings><webBinding interface="sample.ConvertTemperature" name="ConvertTemperature"

uri="" wsdlLocation="ConvertTemperature.wsdl" wsdlPort="ConvertTemperature"wsdlService="ConvertTemperatureService"/>

<webBinding interface="sample.ConvertTemperature"name="ConvertTemperatureWithSharedProtocol" uri=""wsdlLocation="ConvertTemperature.wsdl" wsdlPort="ConvertTemperature"wsdlService="ConvertTemperatureService"/>

<eglBinding alias="" name="myEGLBinding" serviceName="services.myEGLService"><egl:protocol.ref ref="mySharedProtocol"/>

</eglBinding></bindings><protocols>

<egl:protocol.cicsssl name="mySharedProtocol" conversionTable="conversionTable"location="location"/>

</protocols></deployment>

Generating EGL and Web services 119

Web Service Deployment page

EGL logic parts can call an EGL service even if that service is on a remote system.However, if you want to make your EGL services available to non-EGL programsand services, you must generate the service as a Web service. The Web ServiceDeployment page shows the Service parts that you are deploying as Web services.To add a new Web service deployment to your EGL deployment descriptor file, seethe topic ″Adding Web service deployment information to the deploymentdescriptor″ in the EGL Programmer’s Guide. That topic describes the different fieldson the page and what values to enter. For a description of each field and whichapply to which type of service, see “Deployment descriptor options for services”on page 121.

The following example shows the actual XML code for including a Web service inyour EGL deployment descriptor. The example includes the XML from theprevious example:<deployment>

<bindings><webBinding interface="sample.ConvertTemperature" name="ConvertTemperature"

uri="" wsdlLocation="ConvertTemperature.wsdl" wsdlPort="ConvertTemperature"wsdlService="ConvertTemperatureService"/>

<webBinding interface="sample.ConvertTemperature"name="ConvertTemperatureWithSharedProtocol" uri=""wsdlLocation="ConvertTemperature.wsdl" wsdlPort="ConvertTemperature"wsdlService="ConvertTemperatureService"/>

<eglBinding alias="" name="myEGLBinding" serviceName="services.myEGLService"><egl:protocol.ref ref="mySharedProtocol"/>

</eglBinding></bindings><protocols>

<egl:protocol.cicsssl name="mySharedProtocol" conversionTable="conversionTable"location="location"/>

</protocols><webservices>

<webservice enableGeneration="true" implementation="services.calculatorService"location="myLocation" style="document-wrapped"/>

</webservices></deployment>

Related concepts

“Overview of EGL deployment descriptor file” on page 79“Overview of .ir files” on page 81Related tasks

Adding service client binding information for an EGL serviceService client binding information tells how the EGL runtime connects to aservice being invoked by your EGL code. This topic concerns EGL serviceinvocation, not Web service invocation.Adding service client binding information from a WSDL fileService client binding information tells how the EGL runtime connects to aservice being invoked by your EGL code. This topic concerns SOAP (Web)service invocation.Creating a deployment descriptorThe EGL deployment descriptor provides service-binding detail when you aregenerating a service, as well as service-binding detail when you are generatinga logical unit (program, library, handler, or service) that invokes a service.Elements of a service-oriented applicationThe major elements of an EGL service-oriented application are the service part,


interface part, and deployment descriptor file. In general, each of these files andparts has a role in both services and service requesters.Related reference

“Special considerations for generating EGL or Web services in iSeriesenvironments” on page 129“Special considerations for generating EGL or Web services in z/OS CICSenvironments” on page 128

Deployment descriptor options for servicesThis topic describes the options you must set in the EGL deployment descriptorfile to deploy a Web service.

When you select a Service part to be generated as a Web service, the Web ServiceDeployment page of the EGL Deployment Descriptor editor prompts you for thefollowing options:

ImplementationThe Service part to generate as a Web service.

GenerateWhether to generate the Web service access layer for the service when yougenerate the deployment descriptor. You must generate the Web serviceaccess layer at least once so EGL will create the code necessary for clientsto access the service, but once you have generated that code, you do notneed to generate it again unless you change the other fields. Generatingthe Web service access layer can be time-consuming, so you may want toclear this check box to save time.

Style The method through which the service and client will assemble the SOAPmessages that they use to communicate with each other. Usedocument-wrapped (the default) unless the clients require rpc.

If you are generating the service to iSeries using the JAVA400 protocol, you canselect a shared protocol from the Protocol list. The shared protocols are specifiedon the Service Client Bindings page of the EGL deployment descriptor editor.

If you are generating the service to CICS, the following fields apply:

transactionThe name of the transaction you create as a copy of the CPIH transactionwith an increased Transaction Work Area size, as explained in “Specialconsiderations for generating EGL or Web services in z/OS CICSenvironments” on page 128.

uri The relative location of the service, after the host name and port number.The default is /services/serviceName, where serviceName is the name ofthe service.

userIDA user ID for the system, if you want to run the transaction as a specificuser.

Related reference

“Generating EGL and Web services” on page 117“Deployment descriptor options for service clients” on page 122The options you must set to create a service client binding in the EGLdeployment descriptor file differ depending on the type of service yourapplication is using.


Deployment descriptor options for service clientsThe options you must set to create a service client binding in the EGL deploymentdescriptor file differ depending on the type of service your application is using.

Web services

When using a Web service, you ordinarily use information from a WSDL file thatdescribes that service. When you create a service client binding in the deploymentdescriptor editor based on a WSDL file, EGL fills in default values for thefollowing options:

Name A mnemonic for the binding.

InterfaceThe fully qualified name of a Service part or Interface part in the clientapplication. This part represents the service in logic parts within the client.

WSDL FileThe name of the WSDL file representing the service.

WSDL PortThe name of the port used by the binding. Services can have multipleports, in order to provide different services to different clients, but aservice client binding can reference only one port in the service.

WSDL ServiceThe name of the service as listed in the WSDL file.

WSDL URIIf specified, the value of this option overrides the URL in the WSDL file. Ifyou know that the service is available at a location other than the locationspecified in the WSDL file, such as a different version of the service usedfor production or testing, you can enter that location here and use thatversion of the service instead. By default, this value is null.

Enable GenerateFor clients being generated to COBOL, this option specifies whether togenerate the Web service access layer when you generate the deploymentdescriptor. You must generate the Web service access layer at least once soEGL will create the code necessary to access the service, but once you havegenerated it, you do not need to generate it again unless you change theinformation in the service client binding. Generating the Web service accesslayer can be time-consuming, so you may want to clear this check box tosave time.

For clients being generated to Java, this option specifies whether to addbinding information to the binding file in the generated output. Thisinformation is required, so you must select this option for clients beinggenerated to Java.

EGL and native services

EGL and native services do not publish information about themselves with WSDLfiles as Web services do. Therefore, when you create a service client binding to anEGL or native service, you must enter information about how to access the service.The information necessary depends on the type of connection you are using toaccess the service.

EGL supports the following types of connections from a client to an EGL service:


Local For a client accessing a service in the same run unit. This type ofconnection is appropriate for services and clients generated to Java orCOBOL.

CICSJ2CFor a Java client accessing a COBOL service through a J2C connector forthe CICS Transaction Gateway.

JAVA400For a Java client accessing a COBOL service that is on iSeries.

CICSECIFor a Java client accessing a COBOL service through the CICS TransactionGateway (CTG) ECI interface.

CICSSSLFor a Java client accessing a COBOL service through the Secure SocketLayer (SSL) features of CICS Transaction Gateway (CTG).

TCPIP For a Java client accessing a Java service through the TCP/IP protocol.

EGL supports the following types of connections from a client to a native service:

SYSTEM-I.LOCALFor a COBOL client accessing a COBOL service that is on the same iSeriesmachine.

JAVA400For a Java client accessing a COBOL service that is on iSeries.

The following options apply to all types of connections:

Name The name used to access the binding; essentially, a key.

Service nameThe name of the service.

Alias A substitute name for the service if the service name is not legal in thetarget environment.

Depending on the type of connection, the deployment descriptor editor willprompt you for some of the following options:

bindDirFor a SYSTEM-I.LOCAL connection, a fully qualified binding directorysuch as LIBNAME/BIND_DIR_NAME, as used to access the serviceprogram

conversionTableThe name of the conversion table that is used to convert data on a call tothe service. Conversion is necessary when the code page that is used forencoding text on the service is different from the encoding that is used onthe client. See “Data conversion” on page 85 for information on conversiontables.

ctgKeyStoreThe name of the key store generated with the CICS Transaction Gatewaytool IKEYMAN.

ctgKeyStorePasswordThe password used when generating the key store.


ctgLocationThe URL for accessing the service through a CICS Transaction Gateway(CTG) server. Specify the related port with the ctgPort option.

ctgPortThe port through which to access a service through a CICS TransactionGateway (CTG) server.

libraryFor a JAVA400 or SYSTEM-I.LOCAL connection, the name of the library inwhich the service is located on the iSeries system.

locationFor a TCPIP connection, the TCPIP host name or address. For a JAVA400connection, the server and path on which the service is located, such asmyServer.myCompany.com/myService. For a CICSECI or CICSSSL connection,the CICS system identifier. For a CICSJ2C connection, the JNDI name ofthe ConnectionFactory object that you establish for the CICS transactionstarted by the call.

passwordThe password for the iSeries system. Specify the user ID with the userIDoption.

serverIDFor a TCPIP connection, the port number of the service’s listener. For aCICSJ2C, CICSSSL, or CICSECI connection, the ID of a CICS transactionbeing called. The default is the CICS server system mirror transaction(CPMI).

userIDThe user ID for the iSeries system.

Related reference

“Generating EGL and Web services” on page 117“Deployment descriptor options for services” on page 121This topic describes the options you must set in the EGL deployment descriptorfile to deploy a Web service.

Generating and deploying a Web service to CICSThis topic describes how to generate and deploy a Web service to z/OS CICS.Aside from setting up the relevant EGL build parts, you must set the followingCICS definitions: TRANSACTION, TCPIPSERVICE, and PIPELINE.

For details about requirements for EGL or Web services on z/OS CICS, see“Special considerations for generating EGL or Web services in z/OS CICSenvironments” on page 128.

Follow these steps to generate and deploy a Web service to z/OS CICS:1. Create an EGL Service part.2. In an EGL deployment descriptor, add a shared protocol of the type CICSWS.

See Creating and using a shared protocol.3. Set the following attributes in the shared protocol:

transactionThe name of a transaction for the Web service to run under, with aminimum Transaction Work Area (TWA) of 1032 bytes. You will create thistransaction later by copying the CPIH transaction and setting its TWA to


1024 bytes. See “Special considerations for generating EGL or Web servicesin z/OS CICS environments” on page 128 for requirements for thistransaction.

userIDThe user ID the Web service will run under (optional).

4. On the Web Service Deployment page of the EGL Deployment Descriptoreditor, add the Service part to generate it as a Web service. See Adding Webservice deployment information to the deployment descriptor.

5. Set the Protocol field in the deployment descriptor to the CICSWS sharedprotocol.

6. Set the URI field in the deployment descriptor to the relative path to whichyou want to deploy the service. The default is /services/ServicePartName,where ServicePartName is the name of the Service part.

7. In the project’s build descriptor, set the following build descriptor options:

deploymentDescriptorThe name of the EGL deployment descriptor to which you added theshared protocol and the Service part.

destDirectoryThe root HFS directory containing folders that will receive the generatedWeb services binding file and WSDL file. An example destDirectory valueis /u/username/clients. CICS must have permission to read and write tothis directory.

The Web services binding file is necessary to convert SOAP messages toCOBOL at run time.

prepSet prep to YES.

serverTypeSet serverType to CICS3.1.

systemSet system to ZOSCICS.

8. Generate both the Service part and the deployment descriptor.9. On the CICS system, define a Web service TRANSACTION with the name

you specified in the CICSWS shared protocol:a. Make a copy of the CPIH transaction with a command like the following:

CEDA COPY TRANSACTION(CPIH) GROUP(DFHPIPE) AS(newName) TO(group)

Use the name of the transaction for newName and the name of the groupfor group.

b. Edit the copy of the transaction and set the TWA size to 1024 bytes.10. Define a TCPIPSERVICE:

a. Create a new TCPIPSERVICE with a command like the following:CEDA DEF TCPIPSERVICE(name) GROUP(group)

Use the name of the new TCPIPSERVICE for name and the name of thegroup for group.

b. Set the Portnumber field to a number between 2001 and 65535.11. Define a Web service PIPELINE:

a. If you need to create a new PIPELINE for services, use the followingcommand:


CEDA DEF PIPELINE(name) GROUP(group)

Use the name of the new PIPELINE for name and the name of the groupfor group.

b. Set the Configfile field to /u/cicsts31/pipelines/basicsoap11provider.xml.

c. Set the Shelf field to destDirectory/provider/shelf, where destDirectory isthe value you used for the destDirectory build descriptor option.

d. Set the Wsdir field to destDirectory/provider, where destDirectory is thevalue you used for the destDirectory build descriptor option.

12. Install the group with the following command:CEDA INSTALL GROUP(group)

Use the name of the group for group.Related tasks

Adding Web service deployment information to the deployment descriptorAfter 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 togenerate the necessary Web service wrapper.Creating and using a shared protocolShared protocols are reusable definitions of a service connection that you canapply to one or more of the entries in an EGL deployment descriptor file.Related reference

“Special considerations for generating EGL or Web services in z/OS CICSenvironments” on page 128“Deployment descriptor options for services” on page 121This topic describes the options you must set in the EGL deployment descriptorfile to deploy a Web service.“Deploying a Web service requester to CICS”This topic describes how to generate and deploy a logic part that runs on z/OSCICS and accesses a Web service.

Deploying a Web service requester to CICSThis topic describes how to generate and deploy a logic part that runs on z/OSCICS and accesses a Web service.

Prerequisitesv An EGL projectv An EGL deployment descriptorv A Web Services Description Language (WSDL) file that describes the service you

want to use, located somewhere in your workspace.1. Add Web service client binding information by importing a WSDL file and

creating a Web binding in an EGL deployment descriptor. See Adding serviceclient binding information from a WSDL file.

2. Create a Program part that uses the Web service. See Creating a service-accessvariable and binding it to a service.

3. In the project’s build descriptor, set the following build descriptor options:

deploymentDescriptorThe name of the EGL deployment descriptor to which you added thebinding information.


destDirectoryThe root HFS directory containing folders that will receive the generatedWeb services binding file and WSDL file. An example destDirectory valueis /u/myname/requesters. CICS must have permission to read and write tothis directory.

The Web services binding file is necessary to convert SOAP messages toCOBOL at run time.

serverTypeSet serverType to CICS3.1.

systemSet system to ZOSCICS.

4. Generate the program and the deployment descriptor.5. Define a Web service PIPELINE:

a. If you need to create a new PIPELINE for requesters, use the followingcommand:CEDA DEF PIPELINE(name) GROUP(group)

Use the name of the new PIPELINE for name and the name of the group forgroup.

b. Set the Configfile field to /u/cicsts31/pipelines/basicsoap11requester.xml.

c. Set the Shelf field to destDirectory/requester/shelf, where destDirectory isthe value you used for the destDirectory build descriptor option.

d. Set the Wsdir field to destDirectory/requester, where destDirectory is thevalue you used for the destDirectory build descriptor option.

6. Create a PROGRAM for the requester. Use the following command:CEDA DEFINE PROGRAM(name) GROUP(group) LANGUAGE(COBOL)

Use the program name for name and the group name for group.7. Create a TRANSACTION for the requester. Use the following command:

CEDA DEFINE TRANSACTION(name) GROUP(group) PROGRAM(programName) TWASIZE(1024)

Use the transaction name for name, the group name for group, and the programname for programName.

8. Install the group with the following command:CEDA INSTALL GROUP(group)

Use the name of the group for group.9. Run the transaction.

Related tasks

Adding service client binding information from a WSDL fileService client binding information tells how the EGL runtime connects to aservice being invoked by your EGL code. This topic concerns SOAP (Web)service invocation.Creating a service-access variable and binding it to a serviceAfter you have created binding information for a service, you can use theservice in an EGL logic part with a variable that represents the service.Related reference


“Deployment descriptor options for service clients” on page 122The options you must set to create a service client binding in the EGLdeployment descriptor file differ depending on the type of service yourapplication is using.“Generating EGL and Web services” on page 117“Generating and deploying a Web service to CICS” on page 124This topic describes how to generate and deploy a Web service to z/OS CICS.Aside from setting up the relevant EGL build parts, you must set the followingCICS definitions: TRANSACTION, TCPIPSERVICE, and PIPELINE.

Special considerations for generating EGL or Web services in z/OSCICS environments

Generating an EGL or Web service to a z/OS CICS environment involves certainsystem requirements. Consider the following requirements when preparing yourcode:v Generation of services in CICS requires CICS TS for z/OS 3.1, with APARS

PK15904 and PK23547 applied.v Generation of services requires access to Hierarchical File System (HFS) on

z/OS:– The destDirectory build descriptor option will indicate the base directory on

the HFS to use for deployment of a CICS Web service and of requesters.– For Web service deployment, a subdirectory will be added to the directory

named in the destDirectory build descriptor option; this subdirectory will belabeled ″Provider″, and a .wsdl file and a .wsbind file will be uploaded to theProvider subdirectory at preparation time. CICS must have read and writeaccess to this directory.

– For Web service client deployment, a subdirectory will be added to thedirectory named in the destDirectory build descriptor option; thissubdirectory will be labeled ″Requester″, and a .wsdl file and a .wsbind filewill be uploaded to the Provider subdirectory at preparation time.

The default transaction provided for CICS Web services is CPIH, which uses aTransaction Work Area (TWA) of 0 bytes. EGL applications require a minimumTWA size of 1032 bytes. To deploy your EGL-created applications, you must copyyour CPIH transaction and modify the TWA size to 1032 bytes. Then the newcopied transaction must be specified in the Transaction field of the Web serviceentry of the EGL deployment descriptor.

You can indicate the URI path portion that the Web service is deployed to. Forexample, take the following Web service location:http://www.example.com/banking/BankService

The URI path refers to /banking/BankService. By default, the path is set to/services/webservicename, where webservicename is the name given to the servicein the EGL deployment descriptor; or, if no annotation is set, then webservicename isthe name of the service part. You can set the URI path in the Web service entry byusing the URI field in the EGL deployment descriptor.

Restrictions

The following restrictions apply when developing services that will be deployed ina CICS environment:


v Third party WSDL files containing ″use=encoded″ SOAP bindings are notsupported and cannot be used to create CICS Web service clients.

v Parameters of type ″dbchar″ are not supported in CICS Web services.v Function overloading is not supported in CICS Web services.

Related concepts

“Overview of EGL deployment descriptor file” on page 79Related tasks


“deploymentDescriptor” on page 224“Generating and deploying a Web service to CICS” on page 124This topic describes how to generate and deploy a Web service to z/OS CICS.Aside from setting up the relevant EGL build parts, you must set the followingCICS definitions: TRANSACTION, TCPIPSERVICE, and PIPELINE.“Deploying a Web service requester to CICS” on page 126This topic describes how to generate and deploy a logic part that runs on z/OSCICS and accesses a Web service.

Special considerations for generating EGL or Web services in iSeriesenvironments

Generating an EGL or Web service to an iSeries environment involves certainsystem requirements, and there are some issues involved that you must be awareof when you write your service and get ready to generate. For COBOL code thatcalls a Web service, it is actually a Java wrapper that is used to make the call. TheCOBOL code calls the Java wrapper, then the Java wrapper in turn calls the Webservice.

To integrate COBOL and Java, your iSeries system must fulfill the followingprerequisites:v Running version 5 release 3 or laterv Must be configured to use JNI.v You must know how to use XML on your iSeries system. Information on this

topic can be found at http://publib.boulder.ibm.com/infocenter/iseries/v5r3/index.jsp?topic=/rzakl/rzaklmain.htm and http://publib.boulder.ibm.com/infocenter/iseries/v5r3/index.jsp?topic=/rzakl/rzakljavaapi.htm.

v You must have the Java classpath set up correctly. Information about the Javaclasspath can be found at http://publib.boulder.ibm.com/infocenter/iseries/v5r4/index.jsp?topic=/rzaha/classpth.htm and http://publib.boulder.ibm.com/infocenter/iseries/v5r4/index.jsp?topic=/rzaha/sdpropf.htm.

When you generate the EGL deployment descriptor, EGL creates an ant scriptcalled CopyiSeriesJNILibs.xml and places the ant script into the directory specifiedin the genDirectory build descriptor option. This ant script will copy the EGLruntime JAR files, and the required WSDL files, to a directory you choose; thenthey will be copied to the iSeries system. If the directory specified inthegenDirectory build descriptor option is a mapped drive from the iSeries system,the JAR files will be copied directly to the iSeries system.

It is easiest to initiate this from within the workbench by following these steps:1. In the workbench, locate the ant script (CopyiSeriesJNILibs.xml).


http://publib.boulder.ibm.com/infocenter/iseries/v5r3/index.jsp?topic=/rzakl/rzaklmain.htm

http://publib.boulder.ibm.com/infocenter/iseries/v5r3/index.jsp?topic=/rzakl/rzaklmain.htm

http://publib.boulder.ibm.com/infocenter/iseries/v5r3/index.jsp?topic=/rzakl/rzakljavaapi.htm

http://publib.boulder.ibm.com/infocenter/iseries/v5r3/index.jsp?topic=/rzakl/rzakljavaapi.htm

http://publib.boulder.ibm.com/infocenter/iseries/v5r4/index.jsp?topic=/rzaha/classpth.htm

http://publib.boulder.ibm.com/infocenter/iseries/v5r4/index.jsp?topic=/rzaha/classpth.htm

http://publib.boulder.ibm.com/infocenter/iseries/v5r4/index.jsp?topic=/rzaha/sdpropf.htm

http://publib.boulder.ibm.com/infocenter/iseries/v5r4/index.jsp?topic=/rzaha/sdpropf.htm

2. Right-click the file and then click Run As → External Tools. You can use thisscript to enter the required argument for Target directory. The script will acceptthe following 3 arguments:

-DtargetDir=d:\localiseriesThis is the target directory. There is no default for this argument. The antscript will not run without this argument.

-DprocessJars=trueThis argument causes the script to copy the JAR files. Without thisargument the JAR files will not be copied. When you use this argument,the JAR files will be copied once and you will save time by not processingthem over and over again. If the target directory is an iSeries mappeddrive, you do not have to modify this argument, because the ant script willcopy only files that have changed. This means the JAR files will always bekept up-to-date.

-DskipWsdl=trueThis argument causes the script to skip copying the WSDL files. Withoutthis argument, the WSDL files are copied just like the JAR files.

When you generate your EGL deployment descriptor, EGL also creates aSystemDefault.properties file. This file is intended to act as a template for you touse in modifying the main SystemDefault.properties file in the /QIBM/UserData/Java400 directory on your iSeries system. You must change the setting forJAR_HOME_DIR to match the target directory you specified in the ant script. TheSystemDefault.properties file contains the following two properties:v java.class.path=JAR_HOME_DIR:JAR_HOME_DIR/lib/

axis.jar:JAR_HOME_DIR/lib/axis-ant.jar:JAR_HOME_DIR/lib/commons-discovery-0.2.jar:JAR_HOME_DIR/lib/jaxrpc.jar:JAR_HOME_DIR/lib/saaj.jar:JAR_HOME_DIR/lib/wsdl4j-1.5.1.jar:JAR_HOME_DIR/lib/commons-logging-1.0.4.jar:JAR_HOME_DIR/libfda7.jar:JAR_HOME_DIR/lib/eglwsdl.jar

v user.timezone=EDTRelated concepts

“Overview of EGL deployment descriptor file” on page 79Related tasks


“deploymentDescriptor” on page 224“Special considerations for generating EGL or Web services in z/OS CICSenvironments” on page 128


Generating Web transactions

Use EGL Web transactions to migrate VisualAge Generator Web transactions toEGL.

The Web transaction user interface is intended for migration from VisualAgeGenerator only. It is possible to write new code using Web transactions, but thiscode is not efficient.

EGL Web transactions use two configuration files:v The gateway properties file, gw.properties by default; see “Gateway servlet

parameters.”v The linkage properties file, csogw.properties by default; see “Web transaction

linkage properties” on page 135.

Web transaction applications involve two kinds of EGL parts:v EGL records with the VGUIRecord stereotypev EGL programs with the VGWebTransaction stereotype

EGL treats the VGUIRecord differently depending on whether you are generatingcode for Java or COBOL. When you generate a VGWebTransaction program forCOBOL, the program automatically includes the information in the associatedVGUIRecord, and displays the record as it would a form in Text UI. In Javageneration, the VGUIRecord generates a .jsp file that becomes the user interface forthe customer; that .jsp file is used to generate a java bean on the server. Therefore,Web transactions produce an actual Web interface in Java, but not in COBOL.

Related reference

“Gateway servlet parameters”“Web transaction linkage properties” on page 135

Gateway servlet parametersBy default, the gateway servlet has only one parameter defined: the parameterhptGatewayProperties. This parameter specifies a gateway properties file. Thegateway properties file sets the remaining parameters for the gateway servlet. Bydefault, the gateway properties file is gw.properties in the Java Resources folder.Comments in this file begin with the pound symbol (#).

Alternately, you can set the gateway servlet parameters in the same place that youspecify the hptGatewayProperties parameter. However, it is better practice to setthe parameters in the gateway properties file. The parameters in the gatewayproperties file override those you specify in the Web application server.

Linkage properties are set in the linkage properties file. This file is specified in thehptLinkageProperties gateway servlet parameter. See “Web transaction linkageproperties” on page 135.


Table 8. Gateway servlet parameters

Servlet Parameter Parameter Value Notes

hptDateMask yyyy/dd/mm Required if any UI recordshave non-numeric datefields. For those fields, thedatetime values that passbetween tier 2 and tier 3 ineither direction mustcorrespond internally to along Gregorian format fordate and time. ParameterhptDateMask specifies thatformat. For Web transactionsgenerated as C++ programs,the format must match thatspecified in environmentvariable EZERGRGL. ForWeb transactions generatedas COBOL programs, theformat in hptDateMask mustmatch the datetime formatspecified during the serverinstallation.

hptEntryApp web_transaction Specifies a Web transactionthat provides an entry page.The program name mustcorrespond to a name (suchas a CICS definition) in thetier 3 environment. Also, anentry for the program namemust be in the file to whichparameterhptLinkageProperties refers.

Either hptEntryPage orhptEntryApp is required. Ifboth are specified,hptEntryPage is used.


Table 8. Gateway servlet parameters (continued)


hptEntryPage /entry_page_jsp Specifies the entry page JSP,relative to the documentroot.

Either hptEntryPage orhptEntryApp is required. Ifboth are specified,hptEntryPage is used.

In the HTML output of theentry page JSP, the name ofthe Web transaction invokedby the user must be assignedto hptAppId. Also, theSUBMIT button that invokesthe Web transaction musthave the name hptExec, andthe SUBMIT button that endsthe Web application serversession must have the namehptLogout.

Vagen1EntryPage.jsp isprovided as a workingexample. There, each Webtransaction name is includedin a VALUE clause of a<SELECT> structure, and theNAME clause of thatstructure refers to hptAppId.

hptErrorLog gateway_servlet_log_file Optional. Specifies the fullyqualified path of a log file. Ifthis parameter is specified,the gateway servlet providesa trace of events and errors,and you can use the log todiagnose problems.Removing hptErrorLog turnsoff tracing.

Generating Web transactions 133



hptExpiredPasswordPage /expired_password_page _jsp Optional. Specifies theexpired password page JSP,relative to the documentroot.

In the HTML output of theexpired password page JSP,the userid input field musthave the name hptUserid, theold-password input fieldmust have the namehptPassword, thenew-password input fieldmust have the namehptNewPassword, thenew-password inputconfirmation field must havethe namehptConfirmNewPassword, andthe SUBMIT button musthave the namehptExpiredPasswordPageLogin.

ExpiredPasswordPage.jsp isprovided as a workingexample of the JSP.

The parameterhptExpiredPasswordPage hasan effect only ifhptLogonCheck is alsospecified.

hptGatewayProperties gateway_properties_file Optional. Specifies the fullyqualified path of a file thatcontains the other gatewayservlet parameters.

hptIDManageHost host_name Optional. Specifies theTCP/IP host name for themachine where the SessionID Manager runs. Thedefault is localhost.

hptLinkageProperties linkage_properties_file Required. Specifies the fullyqualified name of the linkageproperties file, whichestablishes a connectionbetween the gateway servletand each Web transaction.See “Web transaction linkageproperties” on page 135.




hptLogonCheck fully_qualified_class_name Optional. Specifies alogon-check class to handleuser authentication.

RACFValidateLogin isprovided as a workingsample. To use that sample,specify the following:hptLogonCheck=com.ibm.hpt.gateway.RACFValidateLogin

hptLogonPage /logon_page_jsp Optional. Specifies the logonpage JSP, relative to thedocument root. If thisparameter is omitted or ifhptPublicPassword andhptPublicUserid are present,no logon page is displayed.

In the HTML output of thelogon page JSP, the useridinput field must have thename hptUserid, thepassword input field musthave the name hptPassword,and the SUBMIT buttonmust have the namehptLogin.

Vagen1LogonPage.jsp isprovided as a workingexample of the JSP.

The following code shows an example of a gateway properties file:hptLogonPage=/Vagen1LogonPage.jsphptEntryPage=/Vagen1EntryPage.jsp#hptEntryApp=WEBTXN1hptErrorLog=c:/traces/Vagen1Gateway.loghptLinkageProperties=c:/linktabs/csogwLinkage.properties# use the following property if using Websphere 2.0,# which uses JSP 0.91 and Servlet 2.0 support#hptServletVersion=2.0

Related reference

“Web transaction linkage properties”

Web transaction linkage propertiesThe linkage properties file tells the gateway servlet where to find the Webtransactions and how to communicate with the Web transactions. The functionprovided by the file is similar to the function provided by the linkage table inVisualAge Generator Client/Server programs. This file is specified by thehptLinkageProperties parameter in the gateway servlet parameters. By default, thelinkage properties are stored in the csogw.properties file in the Java Resourcesfolder.


The linkage properties file contains three types of entries: application,serverLinkage, and options. Each application entry identifies one or more Webtransactions and is related to serverLinkage entries that indicate how to connect tothose Web transactions.

Following is an example of a linkage properties file:application.WEBUITRAN=CICS5application.WEBUI*=CICS5application.STF*=idahoapplication.MATT*=IMSCapplication.BASIC*=rtpas400application.Z*=remoteC

serverLinkage.CICS5.commtype=CICSECIserverLinkage.CICS5.contable=CSOE037serverLinkage.CICS5.location=nracics5serverLinkage.CICS5.serverid=CPMIserverLinkage.CICS5.javaProperty=my.pkg

serverLinkage.idaho.commtype=TCPIPserverLinkage.idaho.contable=CSOX437serverLinkage.idaho.location=machine01serverLinkage.idaho.serverid=9877serverLinkage.idaho.javaProperty=my.pak

serverLinkage.IMSC.commtype=TCPIMSserverLinkage.IMSC.contable=CSOE037serverLinkage.IMSC.location=carimscserverLinkage.IMSC.tcpport=4000serverLinkage.IMSC.javaProperty=my.pakserverLinkage.IMSC.imsgroupid=mygroupserverLinkage.IMSC.imsdestid=IMSCserverLinkage.IMSC.serverid=*

serverLinkage.rtpas400.commtype=as400serverLinkage.rtpas400.contable=CSOE037serverLinkage.rtpas400.location=rtpas400serverLinkage.rtpas400.javaProperty=my.pagserverLinkage.rtpas400.library=sdearth

serverLinkage.remoteC.commtype=cicseciserverLinkage.remoteC.contable=CSOI1252serverLinkage.remoteC.location=CSONT2serverLinkage.remoteC.serverid=CPMIserverLinkage.remoteC.ctgLocation=ctghostnameserverLinkage.remoteC.ctgPort=2006serverLinkage.remoteC.javaProperty=my.cicspkg

Application entries

Each application entry has the following format:application.webtran=servername

webtranThe name of the Web transaction.

The final character can be the wildcard character (*). The entryapplication.webui*=CICS5, for example, is used for all Web transactions thatstart with the characters webui.

If multiple application entries match a Web transaction name, the most specificentry takes precedence. For example, a gateway servlet tries to access Webtransaction webuitran when the linkage properties file contains the followingentries:


application.webui*=abcapplication.webuit*=def

In this case, the second statement is used

servernameAn arbitrary name that you assign to an application entry and to a related setof serverLinkage entries for a particular Web transaction. Consider thefollowing application entry, for example:application.SERVER1=CICS5

To access a Web transaction called SERVER1, the gateway servlet refers to theserverLinkage entries that are identified by CICS5.

ServerLinkage entries

Each serverLinkage entry has the following format:serverLinkage.servername.parameter=value

servername

An arbitrary name that you assign to a set of serverLinkage entries for aparticular Web transaction. The name must be present in an application entry.

parameterOne of the following:

commtypeSpecifies the type of communications used to access the Webtransaction. The valid values are as follows

AS400 For use when the Web transaction resides on OS/400®.

CICSECIFor use when the Web transaction resides on CICS (CICS forAIX, CICS for MVS™, CICS for Solaris, or CICS for VSE).

DIRECTFor use when the Web transaction is a Java program, tier 2 andtier 3 are the same Windows 2000 or Windows NT® machine,and you want the Web transaction to run in a thread of theJava Virtual Machine in which the gateway servlet is running.

TCPIMSFor use when the Web transaction resides on an IMS system.

TCPIP For use when the Web transaction resides on a native Windows2000, Windows NT, OS/2®, AIX, HP-UX or Solaris system. Ifthe tier 2 and tier 3 environments are the same Windows 2000or Windows NT machine, consider using commtype DIRECTinstead of TCPIP.

contableSpecifies the conversion table used on the tier 2 platform. The format isas follows:CSOzxxxx;

z One of the following binary formats, which refers to the tier 3platform:v I (for Intel®)v E (for EBCDIC)


v J (for Java Unicode)v X (for UNIX)

xxxx The code page used for conversion.

The SUN Java conversion routines convert the data inaccordance with the data definitions in the UI record. For moreinformation on conversion tables for different languages andplatforms, see the VisualAge Generator Client/ServerCommunications Guide.

ctgLocationOptional. Specifies the machine where the CICS Transaction Gatewayresides. If you do not specify ctgLocation and ctgPort whencommtype=CICSECI, the CICS Transaction Gateway is assumed to belocal.

ctgPortOptional. Specifies the port on which where the remote CICSTransaction Gateway listens. If you do not specify ctgLocation andctgPort when commtype=CICSECI, the CICS Transaction Gateway isassumed to be local.

Note: The procedure for setting the port number of the CICSTransaction Gateway listener depends on the version of thatproduct:for version 3.01, use the ctgStart -port command; forversion 3.03, use the JGate -port command; for other versions,see the CICS Transaction Gateway configuration manual. Thedefault port number is 2006.

locationFor commtype=CICSECI, specifies the CICS system identifier thatcorresponds to the server name in the CICSCLI.INI file of the CICSClient. For commtype=TCPIMS, commtype=TCPIP, orcommtype=AS400, specifies the TCP/IP host name of the machinewhere the Web transaction resides.

remoteapptypeIf the Web transaction is a Java program and commtype=TCPIP, specifythe value VGJAVA; otherwise, do not include this parameter.

serveridFor commtype=CICSECI, specifies the CICS trans-id for the catcher. Inmost cases, the following is true:v The value of serverid is CPMI, which causes invocation of program

DFHMIRS.v If you specify a trans-id other than CPMI, CICS starts CPMI, which

switches control to the CICS transaction you specify, which in turnswitches control to program DFHMIRS.

To avoid starting CPMI when the trans-id is not CPMI, prepend tpn_to the trans_id. If the trans-id is WEBT, for example, specifytpn_WEBT; but if the trans-id is CPMI, specify only CPMI. If youspecify WEBT without tpn_, CICS starts CPMI, which in turn switchescontrol to WEBT.

Note: In relation to OS/390®, serverid is ignored and the CICStransaction always runs as CPMI unless the following is true:v CICS TS V1.3 is installed with PTF UQ47399.


v CICS Transaction Gateway is at or aboveV3.1.2.

For commtype=TCPIP, serverid specifies the port number of thelistening socket on the machine where the Web transaction resides.

For commtype=TCPIMS, serverid specifies the IMS transaction code. Ifyou set serverid=*, the value of servername is used as the transactioncode.

For commtype=AS/400, serverid is not used.

tcpportFor commtype=TCPIMS, specifies the port number of the listeningsocket on the machine where the Web transaction resides. The listeningsocket is configured in the IMS TCPIP Open Transaction ManagerAccess connection (ITOC).

javaPropertySpecifies the Java package where the UI record object and UI recordbean for the Web transaction are located. This entry is case sensitive.

imsgroupidSpecifies a RACF® group to which the user must be connected forauthentication. This entry is valid only for TCPIMS connections.

imsdestidSpecifies the IMS system in which the Web transaction runs, as thatsystem is defined by the ITOC configuration. This entry is valid onlyfor TCPIMS connections.

librarySpecifies the name of the library on the OS/400 system where the Webtransaction resides. If the tier 3 platform is OS/400 and you omit thisentry or leave it blank, VisualAge Generator searches for the Webtransaction in the QVGEN library, then in the library list specified byOS/400 variable QUSRLIBL.

valueThe value to which the parameter is set.

Options entries

The following options entries are valid:v hptGateway.propertiesRefreshInterval=n

n Specifies the number of minutes that pass between inspections of thelinkage properties file by the gateway servlet.

This entry lets you dynamically put into effect any changes made to the linkageproperties file, without your being required to stop and start the Webapplication server. Web transactions initiated after the inspection are invokedwith the new values. A value of 0 indicates that the gateway servlet reviews thelinkage properties file only at startup.

v application.webtran.traceFlag=n

webtranThe name of the Web transaction, the same as the same-namedparameter in application entries.

n Indicates whether the gateway servlet is to provide internal,communications layer tracing, which is useful only if you are in contactwith IBM support. Alternatives are 1 (for tracing) or 0 (for none, as is


the default). A communications layer trace requires the presence of thegateway servlet parameter hptErrorLog, which is usually in the gatewayproperties file.

Related tasks

“Generating Web transactions” on page 131Use EGL Web transactions to migrate VisualAge Generator Web transactions toEGL.Adding Web transaction support to an EGL Web projectRelated reference

“Gateway servlet parameters” on page 131


Overview of Java generation

This section provides Java-specific information related to generating Java for any ofthe Java environments, including iSeries. This topic includes an overview of Javageneration; other topics in this section include the following information:v Inputs to Java generationv Outputs of Java generationv Alternative choices for the Java preparation phasev Deploying Java outputv Generating Java wrappers

The process for generating Java code and other output from EGL source actuallyconsists of several phases. The phases were covered briefly in the topic ″Overviewof EGL generation″ which is listed in the related links at the end of this topic.However, there are some specific differences between the generation process forJava and the process for COBOL. This topic gives a high level overview of theprocess for Java generation specifically.

Here are the phases included in the generation process, along with the partsrequired for each phase:

Validation for the target runtime environmentThe validation phase comes first. Here are the required input parts for thevalidation phase:v The generatable part, such as program, library, or JSF handler.v The build descriptor part, which provides the following:

– The target runtime environment, which is specified in the systembuild descriptor option.

– The name of the linkage options part, if any, as specified in thelinkage build descriptor option

– The name of the resource associations part, if any, as specified in theresourceAssociation build descriptor option

– A subset of build descriptor options that are used during thevalidation phase, such as the validateSQLStatements build descriptoroption.

The validation done at generation time is specific to the target runtimeenvironment. EGL performs the following actions during this validation:v Verifying that the source code is compatible with the target runtime

environment.v Verifying that the entries in the linkage options part and the resource

associations part are correct based on the target runtime environment.v Performing any special validation required, such as that requested with

the validateSQLStatements build descriptor option.

ProductionDuring this phase, the EGL generatable parts are generated into Javasource code. This phase requires the following inputs:v Validated EGL source code.v All build descriptor options, including those validated in validation

phase.


v Linkage options partsv Resource association partsv Other information such as the Java runtime properties set in the build

descriptor part.

After generation, the output resulting from this phase consists of thefollowing:v Java source codev A build plan that controls the preparation phase for Java, if you do not

generate to a project in the workspace. The build plan is based on whichbuild descriptor options were set.

v Additional output based on the type of part being generated and thespecific build descriptor options that are set.

Any error messages are shown in the EGL Generation Results view.

PreparationIn the third phase of the generation process, EGL prepares your output fordeployment in your target runtime environment. For Java generation, thepreparation phase can occur in several different ways depending on whereyou place the output of generation. You specify which method to use bysetting certain build descriptor options as follows:v Generate within your workspace, and place the output of the production

phase into an existing project, using the genProject build descriptoroption. In this case, EGL does not create the build plan, and the buildserver and transfer steps are not used. If you have the workbenchpreference Build Automatically turned on, the preparation step(compiling the Java code and any other output of generation) occursautomatically; if that preference is not turned on, you can build theproject at a later time.

v Place the output of generation into a directory on the same workstation,but outside the workspace. This is done by setting the genDirectoryoption, but not setting the destHost option. In this scenario, EGL createsa build plan, which in turn starts the Java compiler on the localworkstation; however, EGL does not use the build server or the transferstep.

v Place the output of generation into a directory outside the workspace,then transfer the output to a remote system for preparation. This usesthe destHost, destDirectory, and related build descriptor options. In thisscenario, EGL creates a build plan to control the order of output that issent to the remote system. The build plan also controls the build scriptsthat are run on the remote system.

Related concepts

“Inputs to Java generation” on page 143“Linkage options part” on page 61“Alternatives for the Java preparation phase” on page 178“Output of Java program generation” on page 172“Preparation of the generated output” on page 5“Resource associations part” on page 65Related tasks

“Choosing build descriptor options for Java generation” on page 152“Generating Java code into a project” on page 178“Processing Java code that is generated into a directory” on page 180


Related reference

“Build descriptor options used with Java” on page 144“destDirectory” on page 315“destHost” on page 316“genDirectory” on page 323“genProject” on page 325“system” on page 226“validateSQLStatements” on page 372

Inputs to Java generation

This section contains topics about input files used in Java generation. There aretopics on build descriptor options, linkage options parts, resource associationsparts, how to generate into a project or directory, and topics concerning Javaruntime properties that are linked to build descriptor option settings.

Java generation uses some or all of the following inputs for generation:v Generatable partsv Build descriptor part, which includes the following:

– Build descriptor options– Settings in the build descriptor part which are stored in Java runtime

properties– Symbolic parameters set in the build descriptor part

v Linkage options partv Resource associations partv EGL deployment descriptor (.egldd) file

Only the generatable part and the build descriptor part are required; not allsettings in the build descriptor part are required.

Related concepts

“Generatable parts” on page 2“Overview of EGL deployment descriptor file” on page 79“Overview of Java runtime properties” on page 153Related tasks

“Choosing build descriptor options for Java generation” on page 152“Generating Java code into a project” on page 178“Processing Java code that is generated into a directory” on page 180Related reference

“Build descriptor options used with Java” on page 144“Description of Java runtime properties” on page 159“Linkage options part in Java generation” on page 170“Resource associations in Java generation” on page 171

Overview of Java generation 143

Build descriptor options used with Java

A build descriptor part controls the generation process. Build descriptor optionsspecify how to generate and prepare EGL output, and a subset of the builddescriptor options can cause other build parts to be included in the generationprocess.

The next two tables list all the build descriptor options that you can use with Java:v The first table shows which platform each option can be used with.v The second table lists the options, a description of each option’s function, and its

default value, if any.

These tables are restricted to those build descriptor options that are used in Javageneration. For a list of all available options, see “Build descriptor options” onpage 41. For options used in COBOL generation, see “Build descriptor optionsused with COBOL” on page 234.

Table 9. Build descriptor option platform dependencies

Build descriptor option Used with JavaUsed with JavaiSeries

“bidiConversionTable” on page 299 Yes Yes

“bidiRuntime” on page 299 Yes No

“birtEngineHome” on page 301 Yes Yes

“buildPlan” on page 301 Yes Yes

“cicsj2cTimeout” on page 305 Yes Yes

“commentLevel” on page 306 Yes Yes

“currencyLocation” on page 307 Yes Yes

“currencySymbol” on page 307 Yes Yes

“dbContentSeparator” on page 308 Yes Yes

“dbms” on page 309 Yes Yes

“decimalSymbol” on page 310 Yes Yes

defaultDateFormat Yes Yes

defaultMoneyFormat Yes Yes

defaultNumericFormat Yes Yes

defaultTimeFormat Yes Yes

defaultTimeStampFormat Yes Yes

“deploymentDescriptor” on page 224 Yes Yes

“destDirectory” on page 315 Yes Yes

“destHost” on page 316 Yes Yes

“destPassword” on page 317 Yes Yes

“destPort” on page 318 Yes Yes

“destUserID” on page 318 Yes Yes

“eliminateSystemDependentCode” on page 225 Yes Yes

“enableJavaWrapperGen” on page 320 Yes Yes

“genDataTables” on page 322 Yes Yes

“genDirectory” on page 323 Yes Yes




“genFormGroup” on page 324 Yes No

“genHelpFormGroup” on page 324 Yes No

“genProject” on page 325 Yes Yes

“genProperties” on page 326 Yes Yes

“genResourceBundle” on page 328 Yes Yes

“genVGUIRecords” on page 330 Yes Yes

“includeLineNumbers” on page 331 Yes Yes

“j2ee” on page 333 Yes Yes

“j2eeLevel” on page 333 Yes Yes

“linkage” on page 335 Yes Yes

“msgTablePrefix” on page 339 Yes Yes

“nextBuildDescriptor” on page 226 Yes Yes

“prep” on page 342 Yes Yes

“programPackageName” on page 344 Yes Yes

“resourceAssociations” on page 345 Yes Yes

“resourceBundleLocale” on page 345 Yes Yes

“secondaryTargetBuildDescriptor” on page 347 Yes Yes

“separatorSymbol” on page 348 Yes Yes

“serverType” on page 349 Yes Yes

“sessionBeanID” on page 350 Yes Yes

“spacesZero” on page 353 Yes Yes

“sqlCommitControl” on page 354 Yes Yes

“sqlDB” on page 355 Yes Yes

“sqlID” on page 356 Yes Yes

“sqlJDBCDriverClass” on page 357 Yes Yes

“sqlJNDIName” on page 359 Yes Yes

“sqlPassword” on page 360 Yes Yes

“sqlSchema” on page 360 Yes Yes

“sqlValidationConnectionURL” on page 360 Yes Yes

“synchOnTrxTransfer” on page 363 Yes Yes

“system” on page 226 Yes Yes

“targetNLS” on page 365 Yes Yes

“tempDirectory” on page 366 Yes Yes

“truncateExtraDecimals” on page 368 Yes Yes

“useCurrentSchema” on page 369 Yes Yes

“userMessageFile” on page 369 Yes Yes

“vagCompatibility” on page 370 Yes Yes

“validateSQLStatements” on page 372 Yes Yes

“wrapperCompatibility” on page 373 Yes Yes




“wrapperJNDIPrefix” on page 374 Yes Yes

“wrapperPackageName” on page 374 Yes Yes



“bidiConversionTable” on page 299 No defaultvalue

Identifies a bidirectional conversiontable, which is needed to handleliterals that contain Arabic orHebrew characters.

“bidiRuntime” on page 299 No defaultvalue

Identifies a bidirectional runtimefile, which contains options thatcontrol the bidirectional behaviorfor the fields in the form groupsassociated with an application.

“birtEngineHome” on page 301 No defaultvalue

Identifies the location of theBusiness Intelligence and ReportingTools (BIRT) report engine.

“buildPlan” on page 301 YES Specifies whether a build plan iscreated during the generationprocess.

“cicsj2cTimeout” on page 305 30000 Assigns a value to thecso.cicsj2c.timeout Java runtimeproperty, which specifies thenumber of milliseconds before atimeout occurs during a call thatuses protocol CICSJ2C.

“commentLevel” on page 306 1 Specifies the extent to which EGLsystem comments are included inoutput source code.

“currencyLocation” on page 307 NONE Specifies the location of a currencysymbol in a string representing amonetary value.

For Java, also assigns a character tothe vgj.nls.currency.location Javaruntime property.

“currencySymbol” on page 307 Determined bythe localeassociated withthe vgj.nls.codeJava runtimeproperty

Specifies a currency symbol that iscomposed of one to threecharacters.

For Java, also assigns a character tothe vgj.nls.currency Java runtimeproperty.

“dbContentSeparator” on page 308 | Specifies the character used todelineate fields in a file which isused to load or unload data fromthe table of a relational database.

“dbms” on page 309 DB2 Specifies the type of databaseaccessed by the generated program.




“decimalSymbol” on page 310 Determined bythe localeassociated withthe vgj.nls.codeJava runtimeproperty

Specifies the symbol to use as thedecimal indicator.

For Java, also assigns a character tothe vgj.nls.number.decimal Javaruntime property.

defaultDateFormat No defaultvalue

Controls the initial runtime value ofstrLib.defaultDateFormat.

For Java, controls the value ofstrLib.defaultDateFormat indirectlyby setting thevgj.default.dateFormat Javaruntime property.

defaultMoneyFormat No defaultvalue

Controls the initial runtime value ofthe strLib.defaultMoneyFormatsystem variable.

For Java, controls the value ofstrLib.defaultMoneyFormatindirectly by setting thevgj.default.moneyFormat Javaruntime property.

defaultNumericFormat No defaultvalue

Controls the initial runtime value ofthe strLib.defaultNumericFormatsystem variable.

For Java, controls the value ofstrLib.defaultNumericFormatindirectly by setting thestrLib.defaultNumericFormat Javaruntime property.

defaultTimeFormat No defaultvalue

Controls the initial runtime value ofthe strLib.defaultTimeFormatsystem variable.

For Java, controls the value ofstrLib.defaultTimeFormat indirectlyby setting thevgj.default.timeFormat Javaruntime property.

defaultTimeStampFormat No defaultvalue

Controls the initial runtime value ofthestrLib.defaultTimeStampFormatsystem variable.

For Java, controls the value ofstrLib.defaultTimeStampFormatindirectly by setting thevgj.default.timestampFormat Javaruntime property.





No defaultvalue

Contains the name of the EGLdeployment descriptor. Thatdescriptor provides service-bindingdetail when you are generating aservice, as well as service-bindingdetail when you are generating alogical unit (program, library,handler, or service) that invokes aservice.

“destDirectory” on page 315 If destHost isspecified,defaultdirectory is thesame as wherethe build serverwas started; ifdestHost is notspecified, thedefault isdetermined bythegenDirectoryoption.

Specifies the name of the directorythat stores the output ofpreparation.

“destHost” on page 316 No defaultvalue

Specifies the name or numericTCP/IP address of the targetsystem where the build serverresides.

“destPassword” on page 317 No defaultvalue

Specifies the password that EGLuses to log on to the system wherepreparation occurs.

“destPort” on page 318 No defaultvalue

Specifies the port on which aremote build server is listening forbuild requests.

“destUserID” on page 318 No defaultvalue

Specifies the user ID that EGL usesto log on to the system wherepreparation occurs.




YES (allow all) Specifies whether all or only someof the following components can begenerated when you attempt togenerate the program: the program,Java wrapper classes, and relatedEJB session bean.

“genDataTables” on page 322 YES Specifies whether you want togenerate the data tables that arereferenced in the program you aregenerating.

“genDirectory” on page 323 No defaultvalue

Specifies the fully qualified path ofthe directory into which EGL placesgenerated output andpreparation-status files.




“genFormGroup” on page 324 YES Indicates whether to generate theform group that is referenced in theuse declaration of the programbeing generated.

“genHelpFormGroup” on page 324 YES Indicates whether to generate thehelp form group that is referencedin the use declaration of theprogram being generated.

“genProject” on page 325 No defaultvalue

Places the output of Java generationinto a workbench project andautomates tasks that are requiredfor Java runtime setup.

“genProperties” on page 326 NO Specifies what kind of Java runtimeproperties to generate (if any) and,in some cases, whether to generatea linkage properties file.

“genResourceBundle” on page 328 YES Specifies whether to generate a Javaresource bundle.

“genVGUIRecords” on page 330 YES Indicates whether to generate theVGUI records that are referenced inconverse or show statements of aWeb transaction.

“includeLineNumbers” on page 331 NO Specifies whether or not Javaruntime error messages contain theline number of the error.

“j2ee” on page 333 NO Specifies whether a Java program isgenerated to run in a J2EEenvironment.

“j2eeLevel” on page 333 No defaultvalue

Specifies the J2EE level of the Webapplication server to which anEGL-generated Web service orservice-binding library will bedeployed.

“linkage” on page 335 No defaultvalue

Contains the name of the linkageoptions part that guides aspects ofgeneration.

“msgTablePrefix” on page 339 No defaultvalue

If you generate a VGUI record beanalone, specifies the message-tableprefix that is stored in the VGUIrecord bean.

“nextBuildDescriptor” on page 226 No defaultvalue

Identifies the next build descriptorin the chain.


“programPackageName” on page344

No defaultvalue

Names the Java package thatreceives EGL-generated outputduring program generation.




“resourceAssociations” on page 345 No defaultvalue

Contains the name of a resourceassociations part, which relatesrecord parts to files and queues onthe target platforms.

“resourceBundleLocale” on page345

No defaultvalue

Specifies a Java locale to beincluded in the name of a resourcebundle that is generated for a VGUIrecord or for a message table, eitherof which is used in a Webtransaction.


No defaultvalue

Specifies a build descriptor thatguides the generation of code beingdeployed to a Web applicationserver, while other code (which istargeted for other environments) isbeing generated in the samegeneration request.

“separatorSymbol” on page 348 Determined bythe localeassociated withthe vgj.nls.codeJava runtimeproperty

Specifies the character used forseparating the thousands andhundreds in a numeric value.

For Java generation, this specifiesthe generated value for thevgj.nls.number.separator Javaruntime property.

“serverType” on page 349 No defaultvalue

Identifies the type of Web server inwhich your output will bedeployed.

“sessionBeanID” on page 350 No defaultvalue

Identifies the name of a sessionelement in the J2EE deploymentdescriptor.

“spacesZero” on page 353 NO Specifies whether a generatedprogram includes extra code toprocess numeric fields that arefilled with spaces.

“sqlCommitControl” on page 354 No defaultvalue

Assigns a value to thevgj.jdbc.default.database.commitControl Java runtimeproperty, which specifies whether acommit occurs after every changeto the default database.

“sqlDB” on page 355 No defaultvalue

Specifies the default database usedby a generated program.

“sqlID” on page 356 No defaultvalue

Specifies a user ID that is used toconnect to a database duringgeneration-time validation of SQLstatements, or for Java runtime.

“sqlJDBCDriverClass” on page 357 No defaultvalue

Specifies a driver class that is usedto connect to a database duringgeneration-time validation of SQLstatements or for Java runtime in anon-J2EE environment.




“sqlJNDIName” on page 359 No defaultvalue

Specifies the default database usedby a generated Java program thatruns in J2EE.

“sqlPassword” on page 360 No defaultvalue

Specifies a password that is used toconnect to a database duringgeneration-time validation of SQLstatements or for Java runtime.

“sqlSchema” on page 360 No defaultvalue

Sets the vgj.jdbc.schema Javaruntime property.


No defaultvalue

Specifies a URL that is used toconnect to a database duringgeneration-time validation of SQLstatements.

“synchOnTrxTransfer” on page 363 NO Specifies whether a commit pointoccurs when one the followingkinds of programs runs a transferto transaction statement:

v A main program in a Javaenvironment

system No defaultvalue

Specifies the target platform forgeneration. This option is required.

“targetNLS” on page 365 Based on thelocale of theworkstationthat doesgeneration.

Specifies the national language codeused to identify runtime messages.

“tempDirectory” on page 366 No defaultvalue

Specifies the location where EGLplaces two kinds of files: theIntermediate Representation (IR)files that are created when usingthe EGLSDK, and the JSP filescreated when generating aVGWebTransaction program orVGUIRecord.

“truncateExtraDecimals” on page368

YES Specifies whether the additionaldigits after the decimal point in anumeric value will be dropped, orrounded off.

“useCurrentSchema” on page 369 NO Enables prepend of contents ofsqlLib.currentSchema to SQL tablenames.

“userMessageFile” on page 369 No defaultvalue

Specifies the generated value forthe vgj.messages.file Java runtimeproperty, which specifies aproperties file that includesmessages you create or customize.

“vagCompatibility” on page 370 NO Indicates whether the generationprocess allows use of specialprogram syntax.


NO Indicates whether SQL statementsare validated against a database atgeneration time.





CURRENT Indicates how to regeneratewrappers that you intend to usewith handwritten Java code whenthe wrappers were originallygenerated by VisualAge Generator4.5, EGL 5.x, or EGL 6.x.

“wrapperJNDIPrefix” on page 374 No defaultvalue

Specifies a prefix to be added to allJNDI names for generated sessionbeans.


No defaultvalue

Specifies the package to generateJava wrappers into.

Related concepts


“Adding a build descriptor part to an EGL build file” on page 38“Editing build descriptor options in the build descriptor part” on page 58“Editing Java runtime properties in the EGL Build Parts Editor” on page 157“Editing symbolic parameters in the build descriptor part” on page 59“Removing a build descriptor part from an EGL build file” on page 39Related reference

“Build descriptor options” on page 41“Build descriptor options used with JavaScript” on page 220This topic lists the build descriptor options used with JavaScript, which is thegenerated language for EGL Rich UI.“Build descriptor options used with COBOL” on page 234

Choosing build descriptor options for Java generation

Build descriptor options are set in a build descriptor part. To choose builddescriptor options for Java generation, follow these steps:1. In the EGL Source folder of your project, right-click on the build file that you

want to use.2. In the pop-up menu, choose Open With → EGL Build Parts Editor. The EGL

Build Parts Editor opens to the General Options view.3. On the left side of the view, there is a table that displays build descriptor

options. You can either show all available options, or filter the list of builddescriptor options.v To see all available build descriptor options, follow these steps:

a. Clear the check box next to Show only specified options.b. In the drop-down list next to Build option filter, select All.

v To filter the list of build descriptor options, follow these steps:a. Select the check box next to Show only specified options.b. Alternatively, you can choose an environment-specific filter in the Build

option filter list. Filters with the word ″Basic″ after the name of the targetenvironment list only the build descriptor options that are used mostfrequently; filters with the word ″All″ contain all options available forthat environment.


4. Once you have selected the options that you want to view, you can edit theirvalues by clicking once on an option to select it, then clicking again in theValue field to make it editable.

5. You can enter symbolic parameters on the right side of this view. Click the Addbutton at the bottom of the table to add a symbolic parameter. To edit the newsymbolic parameter, click once in the field you want to edit. This will make thefield editable. Once you have entered symbolic parameters, you can click theRemove button to delete them.

Two build descriptor options, genDirectory and destDirectory, let you use asymbolic parameter for the value or a portion of the value. For example, for thevalue of genDirectory you can specify C:\genout\%EZEENV%. Then, if you generatefor a Windows environment, the actual generation directory is C:\genout\WIN.

If you do not specify a value for a build descriptor option, the default for theoption is used when the option is applicable in the generation context.

If you have specified a master build descriptor, the option values in that builddescriptor override the values in all other build descriptors. When you generate,the master and generation build descriptors can connect to other build descriptorsin a chain.

Related concepts

“Build descriptor part” on page 33“Master build descriptors and build descriptor chains” on page 33Related tasks

“Editing build descriptor options in the build descriptor part” on page 58“Editing symbolic parameters in the build descriptor part” on page 59“Setting the master build descriptor” on page 36Related reference

“Build descriptor options” on page 41“Build descriptor options used with Java” on page 144“destDirectory” on page 315“genDirectory” on page 323

Overview of Java runtime properties

An EGL-generated Java program uses a set of properties that provide informationat runtime. Most of these Java runtime properties are set using build descriptoroptions, that you assign values to by editing the build descriptor part in the EGLBuild Parts Editor.

During generation, the build descriptor options’ values are stored in thecorresponding Java runtime properties, which are then listed in one of thefollowing files:v If you are deploying your output in a J2EE environment, the properties are

stored in the J2EE deployment descriptor.v If you are deploying your output in a non-J2EE environment, the properties are

stored in a program properties file. Note that VGWebTransactions always run ina non-J2EE environment.

v If you have set the j2ee build descriptor option to YES, and have specified adirectory for the genDirectory build descriptor option, then the Java runtimeproperties are stored in a J2EE environment file. A J2EE environment file is also


created if you have set the j2ee build descriptor option to YES and have set thegenProject build descriptor option to a non-J2EE project.

You can then go into either the J2EE deployment descriptor or the Java propertiesfile, and edit any of the values of the runtime properties without having togenerate your code again.

In order for EGL to use build descriptor options to create runtime properties, youmust set the genProperties build descriptor option to either PROGRAM orGLOBAL.

Build descriptors and program properties

If you are generating Java runtime properties, they will be created and storedaccording to one of the following scenarios:1. To generate Java runtime properties to the J2EE deployment descriptor, follow

these steps:a. Set the j2ee build descriptor option to YES.b. Set the genProperties build descriptor option to PROGRAM or GLOBAL.c. Generate your code into a J2EE project.

2. To generate properties into a J2EE environment file, follow these steps:a. Set the j2ee build descriptor option to YES.b. Set the genProperties build descriptor option to PROGRAM or GLOBAL.c. Do either one of the following:

v Generate into a directory, in which case you use the genDirectory builddescriptor option rather than genProject; or

v Generate into a non-J2EE project.

Note that the properties stored in the J2EE environment file will not beautomatically updated when you generate.

3. To generate a program properties file, with the same name as the programbeing generated, follow these steps:a. Set the j2ee build descriptor option to NO.b. Set the genProperties build descriptor option to PROGRAM.c. Do either one of the following:


v Generate into a non-J2EE project.4. To generate a program properties file named rununit.properties, follow these

steps:a. Set the j2ee build descriptor option to NO.b. Set the genProperties build descriptor option to GLOBAL.c. Do either one of the following:


v Generate into a non-J2EE project.5. To avoid generating properties, set genProperties to NO.


In a J2EE environment

If you are generating a Java program that will run in a J2EE environment, the Javaruntime properties can be created in one of the following ways:v You can follow the steps in the first scenario in the previous section, to generate

the Java runtime properties directly into a J2EE deployment descriptor. In thiscase, EGL overwrites properties that already exist and appends properties thatdo not exist. The generated Java program accesses the J2EE deploymentdescriptor at run time.

v Alternatively, you can follow the steps in the second scenario of the previoussection, to generate the runtime properties into a J2EE environment file. You cancustomize the properties in that file, then copy them into the J2EE deploymentdescriptor.

v You can also follow the fifth scenario from the previous section, and set thegenProperties build descriptor option to NO, to avoid generating the runtimeproperties at all. In this case, you must write any needed Java runtimeproperties by hand.

In a J2EE module, every program has the same runtime properties because all codein the module shares the same J2EE deployment descriptor.

For J2EE servers, properties are specified as env-entry tags in the web.xml file thatis associated with the Web project, as in these examples:

<env-entry><env-entry-name>vgj.nls.code</env-entry-name><env-entry-value>ENU</env-entry-value><env-entry-type>java.lang.String</env-entry-type>

</env-entry>

<env-entry><env-entry-name>vgj.nls.number.decimal</env-entry-name><env-entry-value>.</env-entry-value><env-entry-type>java.lang.String</env-entry-type>

</env-entry>

In a non-J2EE environment

If you are generating a Java program that will run outside of a J2EE environment,you can set the genProperties build descriptor option to either PROGRAM orGLOBAL, which causes EGL to generate the runtime properties into a programproperties file; or you can code the program properties file by hand. The programproperties file provides the kind of information that is available in the deploymentdescriptor, but the format of the properties is different.

In a non-J2EE Java environment, runtime properties can be specified in any ofseveral properties files, which are searched in this order:1. user.properties

2. A file named as follows:programName.properties

where programName is the first program in the run unit.3. rununit.properties

Using user.properties is appropriate when you specify properties that are specificto a user. EGL does not generate content for this file.


Using rununit.properties is especially appropriate when the first program of a rununit does not access a file or database, but calls programs that do. For example:v When generating the calling program, you can generate a program properties

file named for the generated program, and the content might include nodatabase- or file-related properties.

v When you generate the called program, you can generate rununit.properties,and the content would be available for both programs.

None of the properties files are mandatory, and simple programs do not need any.

Rules for deploying non-J2EE or VGWebTransaction

At deployment time, the following rules apply:v The user properties file (user.properties, if present) is in the user home directory,

as determined by the user.home Java system property.v The location of a program properties file (if present) depends on whether the

program is in a package. The rules are best illustrated by example:– If program P is in package x.y.z and is deployed to MyProject/src, the

program properties file must be in MyProject/src/x/y/z– If program P is not in a package and is deployed to MyProject/src, the

program properties file (like the global properties file) must be inMyProject/src

In either case, MyProject/src must be in the classpath.v The global properties file (rununit.properties, if present) must be with the

program, in a directory that is specified in the classpath.

If you generate output to a Java project, EGL places the properties files (other thanuser.properties) in the appropriate folders.

For details on accessing runtime properties in your EGL code, see the topics″getProperty()″ and ″Run unit″ in the EGL Language Reference.

Related concepts

“JEE deployment descriptor” on page 175“JEE environment file” on page 173“Program properties file” on page 177Related tasks

“Generating Java code into a project” on page 178“Processing Java code that is generated into a directory” on page 180“Setting up the JEE runtime environment for EGL-generated code” on page 186“Setting JEE deployment descriptor values” on page 176Related reference

“Description of Java runtime properties” on page 159“genDirectory” on page 323“genProject” on page 325“genProperties” on page 326“j2ee” on page 333


Editing Java runtime properties in the EGL Build Parts Editor

When you are editing a build descriptor part in the EGL Build Parts Editor, thereare two views available. One is a view where you can choose and set builddescriptor options that affect generation. The second is a view where you canassign values to the following Java runtime properties:v vgj.jdbc.database.SN

v vgj.datemask.gregorian.long.locale

v vgj.datemask.gregorian.short.locale

v vgj.datemask.julian.long.locale

v vgj.datemask.julian.short.locale

Your assignments are used only if you generate Java code. If you assign values tothese properties in the build descriptor part, and you have set the build descriptoroption genProperties to GLOBAL or PROGRAM, the values you set are then storedin the corresponding Java properties and listed in the J2EE deployment descriptor(if you are deploying to a J2EE environment) or a Java properties file (if you aredeploying to a non-J2EE environment). If you want to edit these settings at a latertime, you can edit them in the J2EE deployment descriptor or Java properties file,without having to generate your Java code again.

To edit the properties in the build descriptor part, follow these steps:1. Locate the EGL build file you want to work with in the Project Explorer view.



3. If you have the Outline view open, you will see the build descriptor part listedunder the name of your build file. If you do not have the Outline view openand want to open it, select Window → Show View → Other; in the Show Viewdialog box, click to expand General and select Outline.

4. In the Outline view, right-click on a build descriptor part, and select Open. TheEGL Build Parts Editor default view displays a table of build descriptor optionson the left, and a table of symbolic parameters on the right.

5. Click the Show Java runtime Properties button

on the editor toolbar. located at the top right corner of the Build Parts Editor.6. To add the vgj.jdbc.database.SN Java runtime property, do the following:

a. On the left is a table titled ″Database mappings for connect″; underneath thetable, click theAdd button.

b. Type a ″Server name″ that you use when coding the system wordvgLib.connectionService; this value is substituted for SN in the name of thegenerated property.

c. If the row in the Database mappings for connect list is not highlighted, clickonce to select the row, then click the JNDI name or URL field once to putthe field into edit mode. Type in a value (the value for J2EE connections willbe different than non-J2EE connections):


v For J2EE connections (as is needed in a production environment), thevalue is the name to which the data source is bound in the JNDI registry;for example, jdbc/MyDB.

v For a standard JDBC connection (as may be used for debugging), thevalue is the connection URL; for example, jdbc:db2:MyDB.

7. To assign the date masks used when you code eithervgVar.currentFormattedGregorianDate (for a Gregorian date) orvgVar.currentFormattedJulianDate (for a Julian date); or to ensure EGLvalidates a page field or a text-form field that has a length of 10 or more and adateFormat property of systemGregorianDateFormat or systemJulianDateFormat, dothe following:a. On the right is a table titled ″Date Masks″; underneath the table, click the

Add button. A default selection will appear on the first line.b. In the first column (″Locale″), click once on the line. A drop down box

appears; select one of the codes in the list box. The selected value issubstituted for locale in the date-mask properties listed earlier. Only one ofyour entries is used at run time; it is the one where the value of localematches the value of the vgj.nls.code Java runtime property.

c. Click the second column (″Long Gregorian Mask″) once to make the fieldeditable. Either select a mask from the list box or type a mask; charactersother than D, Y, or digits can be used as separators, and the default value isspecific to the locale.

d. If you are selecting the Long Julian Mask, follow the instructions in theprevious step, substituting ″Long Julian Mask″ for ″Long Gregorian Mask.″

8. To assign the date masks used when EGL validates a page field or a text-formfield that has a length less than 10 and a dateFormat property ofsystemGregorianDateFormat or systemJulianDateFormat, do the following:a. On the right is a table titled ″Date Masks″; underneath the table, click the

Add button.b. In the first column (″Locale″), click once on the line. A drop down box

appears; select one of the codes in the list box. The selected value issubstituted for locale in the date-mask properties listed earlier. Only one ofyour entries is used at run time; it is the one where the value of localematches the value of the vgj.nls.code Java runtime property.

c. Click the fourth column (″Short Gregorian Mask″) once to make the fieldeditable. Either select a mask from the list box or type a mask; charactersother than D, Y, or digits can be used as separators, and the default value isspecific to the locale.

d. If you are selecting the Short Julian Mask, follow the instructions in theprevious step, substituting ″Short Julian Mask″ for ″Short Gregorian Mask.″

9. To remove an assignment, click on it, then click the Remove button.Related topics


“Adding a build descriptor part to an EGL build file” on page 38“Editing build descriptor options in the build descriptor part” on page 58“Removing a build descriptor part from an EGL build file” on page 39Related reference



“Description of Java runtime properties”

Description of Java runtime properties

The next table describes the properties that can be included in the deploymentdescriptor or program properties file, as well as the source of the value generatedinto the J2EE environment file, if any. The Java type for each property isjava.lang.String unless the description column says otherwise.

Runtime property Description Source of the generatedvalue

cso.cicsj2c.timeout Specifies the number ofmilliseconds before a timeoutoccurs during a call that usesprotocol CICSJ2C. Thedefault value is 30000, whichrepresents 30 seconds. If thevalue is set to 0, no timeoutoccurs. The value must begreater than or equal to 0.

The Java type in this case isjava.lang.integer.

The cso.cicsj2c.timeout Javaruntime property has aneffect on calls only when thecalling program is deployedto a J2EE environment andthe called program isdeployed to a CICSenvironment. For details, see“Setting up the J2EE serverfor CICSJ2C calls” on page189.

cicsj2cTimeout builddescriptor option

cso.linkageOptions.LO Specifies the name of alinkage properties file thatguides how the generatedprogram or wrapper callsother programs. LO is thename of the linkage optionspart used at generation.

LO is from the linkage builddescriptor option; and thedefault value is the name ofthe linkage options partfollowed by the extension.properties.



vgj.datemask.gregorian.long.locale

Contains the date mask usedin either of two cases:

v The Java code generatedfor the

vgVar.currentFormattedGregorianDatesystem variable is invoked;or

v EGL validates a page fieldor text-form field that hasa length of 10 or more, ifthe dateFormat fieldproperty is set tosystemGregorianDateFormat.

locale is the code specified inthe vgj.nls.code property.You can change thedate-mask property in use bycalling the sysLib.setLocalefunction.

The value of this propertycan either be a date mask, asdescribed in thedocumentation; or it can beone of the following words:

v short

v medium

v long

These are values found inthe Java DateFormat class,and when you use them Javafills in the short, medium, orlong format that matchesyour locale.

vgj.datemask.gregorian.short.locale

Contains the date mask usedwhen EGL validates a pagefield or text-form field thathas a length of less than 10,if the dateFormat itemproperty is set tosystemGregorianDateFormat.

locale is the code specified inthe vgj.nls.code property. InWeb applications, you maychange the date-maskproperty in use by assigninga different value tosysLib.setLocale.

Build descriptor value for theshort Gregorian date mask;the default value is specificto the locale



vgj.datemask.julian.long.locale Contains the date mask usedin either of two cases:

v The Java code generatedfor the

vgVar.currentFormattedGregorianDatesystem variable is invoked;or

v EGL validates a page fieldor text-form field that hasa length of 10 or more, ifthe dateFormat fieldproperty is set tosystemJulianDateFormat.


The value of this propertycan either be a date mask, asdescribed in thedocumentation; or it can beone of the following words:

v short

v medium

v long

These are values found inthe Java DateFormat class,and when you use them Javafills in the short, medium, orlong format that matchesyour locale.

vgj.datemask.julian.short.locale

Contains the date mask usedwhen EGL validates a pagefield or text-form field thathas a length of less than 10,if the dateFormat itemproperty is set tosystemJulianDateFormat.


Build descriptor value for theshort Julian date mask; thedefault value is specific tothe locale

vgj.default.databaseDelimiter Specifies the symbol used toseparate one value from thenext in the sqlLib.loadTableand sqlLib.unLoadTablesystem functions. The defaultvalue is a pipe (|).

dbContentSeparator builddescriptor option

vgj.default.dateFormat Sets the initial value of thestrLib. defaultDateFormatsystem variable.

defaultDateFormat builddescriptor option



vgj.default.I4GLNativeLibrary

Specifies the DLL nameaccessed by an EGLstereotype NativeLibrary. Theproperty is required if youdid not specify the dllNamelibrary property.Note: This is a Java systemproperty. It does not comefrom usual programproperties file or J2EEdeployment descriptor.

To set a system property, usethe -D option when startingJava. For example:java-Dprop=value where prop isthe property name and valueis the value you areassigning.

vgj.default.moneyFormat Sets the initial value of thestrLib. defaultMoneyFormatsystem variable.

defaultMoneyFormat builddescriptor option

vgj.default.numericFormat Sets the initial value of thestrLib.defaultNumericFormatsystem variable.

defaultNumericFormat builddescriptor option

vgj.default.timeFormat Sets the initial value of thestrLib. defaultTimeFormatsystem variable.

defaultTimeFormat builddescriptor option

vgj.default.timestampFormat Sets the initial value of thestrLib.defaultTimestampFormatsystem variable.

defaultTimestampFormatbuild descriptor option

vgj.java.command The command used byvgLib.startTransaction tostart a new Java VirtualMachine. The default is″java″.

None



vgj.jdbc.database.SN This is optional. If you makea database connection byusing the sysLib.connect orvgLib.connectionServicesystem function, thisproperty specifies the JDBCdatabase name that is used.

The meaning of the value isdifferent for J2EE connectionsas compared with standard(non-J2EE) connections:

v In relation to J2EEconnections (as is neededin a productionenvironment), the value isthe name to which thedatasource is bound in theJNDI registry; for example,jdbc/MyDB.

v In relation to a standardJDBC connection (as maybe used for debugging),the value is the connectionURL; for example,jdbc:db2:MyDB.

You must customize thename of the property itselfwhen you specify asubstitution value for SN, atdeployment time. Thesubstitution value in turnmust match either the servername that is included in theinvocation ofvgLib.connectionService orthe database name that isincluded in the invocation ofsysLib.connect.

Build descriptor value for thedatabase name that you wantto associate with thespecified ″server name″

vgj.jdbc.default.database Specified the name of thedefault database.

sqlDB or sqlJNDINamebuild descriptor options

vgj.jdbc.default.database.commitControl

Specifies whether a commitoccurs after every change tothe default database. Validvalues are AUTOCOMMIT,NOAUTOCOMMIT, andNOCOMMIT, as described“sqlCommitControl” on page354.

sqlCommitControl builddescriptor option



vgj.jdbc.default.database.programName

Specifies the default databasename that is used for an SQLI/O operation if no priordatabase connection exists.EGL includes the programname (or program alias, ifany) as a substitution valuefor programName so that eachprogram has its own defaultdatabase. The program nameis optional, however, and aproperty namedvgj.jdbc.default.database isused as a default for anyprogram that is notreferenced in aprogram-specific property ofthis kind.

The meaning of the value inthe property itself is differentfor J2EE connections ascompared with non-J2EEconnections:

v In relation to J2EEconnections, the value isthe name to which thedatasource is bound in theJNDI registry; for example,jdbc/MyDB.

v In relation to a standardJDBC connection, thevalue is the connectionURL; for example,jdbc:db2:MyDB.

Depends on the connectiontype:

v For J2EE connections, thesqlJNDIName builddescriptor option

v For non-J2EE connections,the sqlDB build descriptoroption

vgj.jdbc.default.database.password

Specifies the password foraccessing the databaseconnection identified invgj.jdbc.default.database.

sqlPassword build descriptoroption

vgj.jdbc.default.database.userid

Specifies the user ID foraccessing the databaseconnection identified invgj.jdbc.default.database.

sqlID build descriptor option

vgj.jdbc.drivers Specifies the driver class foraccessing the databaseconnection identified invgj.jdbc.default.database. Ifthere is more than one driverclass, separate the classnames with semicolons. Thisproperty is not present in thedeployment descriptor orJ2EE environment file and isused only for a standard(non-J2EE) JDBC connection.

sqlJDBCDriverClass builddescriptor option



vgj.messages.file Specifies a properties file thatincludes messages you createor customize. The file issearched in these cases:

v The EGL runtime needs toload an error message. Inthis case, you can use theproperty to customizeEGL’s messages.

v The EGL runtime respondsto the invocation of thesysLib.getMessage systemfunction, which returns amessage that you created.

v The EGL runtime ishandling a consoleUIapplication and attemptsto present help orcomment text from a fileidentified in theconsoleLib.messageResource systemvariable, but that variablehas no value.

userMessageFile builddescriptor option

vgj.nls.code Specifies the three-letter NLScode of the program.

If the property is not set,these rules apply:

v The value defaults to theNLS code that correspondsto the default Java locale.

v The value is ENU if thedefault Java locale doesnot correspond to any ofthe NLS codes supportedby EGL.

v The NLS code can bechanged by calling thesysLib.setLocale systemfunction.

targetNLS build descriptoroption

vgj.nls.currency Specifies the character usedas a currency symbol. Thedefault is determined by thelocale associated withvgj.nls.code.

currencySymbol builddescriptor option

vgj.nls.currency.location Specifies whether thecurrency symbol is placed atthe front or back of thenumber, or whether nosymbol location isdesignated.

currencyLocation builddescriptor option



vgj.nls.number.decimal Specifies the character usedas a decimal symbol. Thedefault is determined by thelocale associated withvgj.nls.code.

decimalSymbol builddescriptor option

vgj.nls.number.separator Specifies a symbol forseparating the thousands andhundreds in a numeric value.

seaparatorSymbol builddescriptor option

vgj.ra.FN.fileType Specifies the type of fileassociated with FN, which isa file identified in the recordpart. The property value isseqws or mq.

You must specify thisdeployment descriptorproperty for each logical filethat your program uses.

fileType build descriptoroption

vgj.ra.FN.replace Specifies the effect of an addstatement on a recordassociated with FN, which isa file name identified in arecord. Select one of twovalues:

v 1 if the statement replacesthe file record

v 0 (the default) if thestatement appends arecord to the file


replace resource associationsproperty

vgj.ra.FN.systemName Specifies the name of thephysical file or messagequeue associated with FN,which is a file or queuename identified in the recordpart.

You must specify thisdeployment descriptorproperty for each logical filethat your program uses.

systemName resourceassociations property



vgj.ra.FN.text Specifies whether to cause agenerated Java program todo the following whenaccessing a file by way of aserial record:

v Append end-of-linecharacters during the addoperation. On non-UNIXplatforms, those charactersare a carriage return andlinefeed; on UNIXplatforms, the onlycharacter is a linefeed.

v Remove end-of-linecharacters during the getnext operation.

FN is the file nameassociated with the serialrecord.


v 1 for make the changes

v 0 (the default) for refrainfrom making the changes


text resource associationsproperty

vgj.trace.device.option Destination of trace data, ifany. Select one of thesevalues:

v 0 for write to System.out

v 1 for write to System.err

v 2 (the default) for write tothe file specified invgj.trace.device.spec withthis exception: for VSAMI/O traces, write tovsam.out


The generated value, if any,is 2

vgj.trace.device.spec Specifies the name of theoutput file ifvgj.trace.device.option is setto 2. An exception is thatVSAM I/O traces are writtento vsam.out

The generated value, if any,is vgjtrace.out; this is thedefault value



vgj.trace.type Specifies the runtime tracesetting. Sum the values ofinterest to get the tracing youwant:

v -1 for trace all

v 0 for no trace (the default)

v 1 for general trace,including functioninvocations and callstatements

v 2 for system functions thathandle math

v 4 for system functions thathandle strings

v 16 for data passed on acall statement

v 32 for the linkage optionsused on a call

v 128 for jdbc I/O

v 256 for file I/O

v 512 for all the propertiesexceptvgj.jdbc.default.password


The generated value, if any,is 0

The following table lists properties from the TCPIPListener program properties file.


tcpiplistener.port Specifies the number of theport on which an EGLTCP/IP listener (of classTcpipListener orTcpipListenerJ2EE) listens.No default exists. For details,see “Setting up a TCP/IPlistener for J2EE calledapplications” on page 193 or“Setting up the TCP/IPlistener for a called non-J2EEapplication” on page 198.

The Java type in this case isJava.lang.Integer.

Not generated



tcpiplistener.trace.file Specifies the name of the filein which to record theactivity of one or more EGLTCP/IP listeners (each is ofclass TcpipListener orTcpipListenerJ2EE). Thedefault file istcpiplistener.out.

Not generated; tracing isonly for use by IBM

tcpiplistener.trace.flag Specifies whether to trace theactivity of one or more EGLTCP/IP listeners (each ofclass TcpipListener orTcpipListenerJ2EE). Selectone of these:

v 1 for recording the activityinto the file identified inpropertytcpiplistener.trace.flag

v 0 (the default value) fornot recording the activity

The Java type in this case isJava.lang.Integer.For details,see “Setting up a TCP/IPlistener for J2EE calledapplications” on page 193 or“Setting up the TCP/IPlistener for a called non-J2EEapplication” on page 198.

Not generated; tracing isonly for use by IBM

You can find more information in the following topics in the EGL LanguageReference:v ″connect()″v ″Date/time masks and format specifiers″v ″decimals()″v ″defaultDateFormat (EGL system variable)″v ″defaultMoneyFormat (EGL system variable)″v ″defaultNumericFormat (EGL system variable)″v ″defaultTimeFormat (EGL system variable)″v ″defaultTimestampFormat (EGL system variable)″v ″formatNumber()″v ″getMessage()″v ″Library part″v ″loadTable()″v ″setLocale()″v ″unloadTable()″

Related topics

“Overview of Java runtime properties” on page 153“Linkage properties file” on page 182Related tasks

“Setting up a J2EE JDBC connection” on page 192“Setting up the JEE runtime environment for EGL-generated code” on page 186“Setting up the J2EE server for CICSJ2C calls” on page 189


“Setting up the TCP/IP listener for a called non-J2EE application” on page 198“Setting up a TCP/IP listener for J2EE called applications” on page 193“Understanding how a standard JDBC connection is made” on page 190Related reference

“callLink element” on page 380“cicsj2cTimeout” on page 305“linkage” on page 335“sqlCommitControl” on page 354“sqlDB” on page 355“sqlID” on page 356“sqlJDBCDriverClass” on page 357“sqlJNDIName” on page 359“sqlPassword” on page 360“targetNLS” on page 365

Symbolic parameters in Java generation

You can use symbolic parameters in Java generation, but in a much more limitedway than in COBOL generation. For Java generation, symbolic parameters are onlyused in the genDirectory or destDirectory build descriptor options. For example,for the value of genDirectory, you can specify C:\genout\%EZEENV%. Then if yougenerate for a Windows environment, the actual generation output directory wouldbe C:\genout\WIN. You can also define your own symbolic parameters for use inspecifying values for the genDirectory or destDirectory build descriptor options.

For information on how symbolic parameters are used in COBOL, see “Symbolicparameters used with COBOL generation” on page 246. You can find a list ofpredefined symbolic parameters used in EGL in “Predefined symbolic parametersthat are set automatically” on page 250.

Related concepts

“Build descriptor part” on page 33“Symbolic parameters used with COBOL generation” on page 246“Predefined symbolic parameters that are set automatically” on page 250Related tasks

“Editing symbolic parameters in the build descriptor part” on page 59Related reference

“Build descriptor options” on page 41“Build descriptor options used with Java” on page 144

Linkage options part in Java generation

A linkage options part provides the various elements that enable you to specifydetails of how you want certain statements to be implemented in your generatedJava code. It contains some or all of the following elements:v The asynchLink element provides details on how a generated program starts a

particular program or transaction asynchronously using thevgLib.startTransaction system function.


v The callLink element provides details on how a call statement is to beimplemented when calling a particular program, or how a particular calledprogram will be called.

v The transferToProgram element provides details on how a transfer to programstatement is implemented when transferring to a particular program.

v The transferToTransaction element provides details on how a transfer totransaction statement is implemented when transferring to a particulartransaction (or program in non-transactional environments).

Specifying when linkage options are finalFor generated Java code, you can choose between two alternatives:v The linkage options specified at generation time are in effect at run time; orv The linkage options specified in a linkage properties file at deployment time are

in effect at run time. Although you can write that file by hand, EGL generates itin this situation:– You set the remoteBind linkage options property to RUNTIME; and– You generate a Java program or wrapper with the genProperties build

descriptor option set to GLOBAL or PROGRAM.Related concepts

“Generating Java wrappers” on page 199“Linkage options part” on page 61“Linkage properties file” on page 182Related tasks

“Adding a linkage options part to an EGL build file” on page 63“Setting up the JEE runtime environment for EGL-generated code” on page 186Related reference

“asynchLink element” on page 375“callLink element” on page 380“transferToProgram element” on page 410“transferToTransaction element” on page 416

Resource associations in Java generation

An EGL fixed record that accesses an external file, printer, or queue has a logicalfile or queue name. In the case of a printer, the logical file name is printer for mostruntime systems. The name can be no more than 8 characters and is meaningfulonly as a way of relating the record to a system name, which the target system usesto access a physical file, printer, or queue.

In relation to files or queues, the file or queue name, or a substring derived fromthat name, is a default for the system name. In relation to printers, a default existsonly for COBOL output and therefore is not used in Java generation.

Instead of accepting a default, you can take one or both of the following actions:v At generation time, you control the generation process with a build descriptor

that in turn references a specific resource associations part. The resourceassociations part relates the file name to a system name on the target platformwhere you intend to deploy the generated code.

v At run time (in most cases) you can change the value in the record-specificvariable resourceAssociation (for files or queues) or in the


ConverseVar.printerAssociation system variable (for print output). Your purposeis to override the system name that you specified either by default or byspecifying a resource associations part.

The resource associations part applies to these record stereotypes:v SerialRecordv IndexedRecordv RelativeRecordv MQRecord

Related reference

“Association elements” on page 71“resourceAssociations” on page 345“system” on page 226

Overview of Java output

When you generate Java source code, EGL produces a class and a file for each ofthe following generatable parts:v The program part, handler part, or library partv The Java wrapperv Each record declared either in that part itself or in any function that is invoked

directly or indirectly by that partv Each data table that is usedv Each form or form group that is usedv Delegates and services

When you generate a library part, the output is a Java class. The name of the classis the part alias, or the part name if no alias is specified, but EGL makes charactersubstitutions as described in the topic ″How Java names are aliased.″

For more information on JSF handlers or other handler parts, see the topic ″JSFhandler″ and other related topics in the EGL Language Reference.

Related concepts

“Generation output and associated files” on page 91“Generating Java wrappers” on page 199Related tasks

“Setting up the JEE runtime environment for EGL-generated code” on page 186Related reference

“How COBOL names are aliased” on page 100“How Java names are aliased” on page 97“Output of Java program generation”“Output of Java wrapper generation” on page 208“Java wrapper classes” on page 199

Output of Java program generation

Java program generation produces the following output:v A build plan, if the genProject build descriptor option is not set


v Java source codev Related objects needed to prepare and run your programv J2EE environment file or program properties file, if certain conditions are metv A results file, if genProject is omitted

You can use the EGL generator to generate entire Java programs. Programs andrecords are generated as separate Java classes. Functions are generated as methodsin the program. Variables and structure fields are generated as fields of the recordor program class to which they belong.

The following table shows the names of the various types of generated Java parts:

Table 11. Names of generated Java parts

Part type and name What is generated

Program named P A class named P in P.java

Record named R A class named R in R.java

Linkage options part named L Linkage properties file named L.properties

Library named LibA A class named LibA in LibA_Lib.java

DataTable named DT A class named DT in DT.java

Related concepts

“Build plan” on page 103“JEE environment file”“Overview of Java output” on page 172“Linkage properties file” on page 182“Program properties file” on page 177“Results file” on page 281Related reference

“callLink element” on page 380

JEE environment file

In addition to the properties associated with EGL parts, there are a number of Javaruntime properties that control access to databases, files, and other resources. Tohelp distinguish them from EGL properties, and to emphasize the fact that they arenot properties under JEE, this documentation may refer to these Java runtimeproperties as settings.

When you generate Java code, and you have the genProperties build descriptoroption set to GLOBAL or PROGRAM, the settings in various build descriptoroptions are stored as Java runtime properties, and are written to one of threelocations:v a program properties file;v the JEE deployment descriptor for the project; orv a JEE environment file.

A JEE environment file is a text file that contains property-and-value pairs that arederived from information that you specify in the build descriptor part, by settingcertain build descriptor options. Other sources of information are the resourceassociations part, and the linkage options part, which are other build parts.


The JEE environment file is created when you have set the j2ee build descriptoroption to YES, and you have set the genDirectory build descriptor option insteadof the genProject build descriptor option. Alternatively, a JEE environment file isalso created when you have set the j2ee build descriptor option to YES, and youhave set the genProject build descriptor option to a non-JEE project.

Note: The JEE environment file contains XML tags that would normally have beenwritten to the JEE deployment descriptor, if you had chosen to generate to avalid JEE project. This file will not be automatically updated the next timeyou generate. If you are generating code to an outside directory for importinto another project later, remember that you must manually copy the XMLtags from the JEE environment file, and paste into the JEE deploymentdescriptor for your project.

Updating the JEE environment file

The JEE environment file contains a series of entries like the following example:<env-entry>

<env-entry-name>vgj.nls.code</env-entry-name><env-entry-type>java.lang.String</env-entry-type><env-entry-value>ENU</env-entry-value>

</env-entry>

The order of sub-elements is determined by the j2eeLevel build descriptor option.The example above uses the order name-type-value, which is consistent with JEE1.4 and above; if the j2eeLevel build descriptor option is set to 1.3, the order ofsub-elements is name-value-type. For the example above, a setting of JEE 1.3would change the order of the sub-elements to:

<env-entry><env-entry-name>vgj.nls.code</env-entry-name><env-entry-value>ENU</env-entry-value><env-entry-type>java.lang.String</env-entry-type>

</env-entry>

The name-type-value order is needed for all web projects, EJB and applicationclient projects that run in JEE 1.4 and above. For web projects that run in JEE 1.3,the order name-value-type is used instead.

This step can be avoided if you generate directly into a project instead of into adirectory. When you generate into a project, EGL can determine the type of projectyou are using and generate the environment entries in the appropriate order. Also,the serverType build descriptor option can affect the default level of the j2eeLevelbuild descriptor option.

Related concepts

“Generation output and associated files” on page 91“JEE deployment descriptor” on page 175“Program properties file” on page 177Related tasks

“Setting JEE deployment descriptor values” on page 176“Setting up the JEE runtime environment for EGL-generated code” on page 186Related reference

“genDirectory” on page 323“genProject” on page 325“genProperties” on page 326


“j2ee” on page 333“j2eeLevel” on page 333“serverType” on page 349

JEE deployment descriptor

In addition to the properties associated with EGL parts, there are a number of Javaruntime properties that control access to databases, files, and other resources. Tohelp distinguish them from EGL properties, and to emphasize the fact that they arenot properties under JEE, this documentation may refer to these Java runtimeproperties as settings.

When you generate Java code, and you have the genProperties build descriptoroption set to GLOBAL or PROGRAM, the settings in various build descriptoroptions are stored as Java runtime properties, and are written to one of threelocations:v a program properties file;v the JEE deployment descriptor for the project; orv a JEE environment file.

The JEE deployment descriptor is not created by EGL. However, if the followingconditions apply, EGL will update the JEE deployment descriptor:v the j2ee build descriptor option to YES;v the genProject build descriptor option is set to a JEE project.

If the above conditions do not apply, Java runtime properties will either be storedin a program properties file, or a JEE environment file.

Updating the JEE deployment descriptor manually

If you are updating a deployment descriptor from a generated JEE environmentfile, follow these steps:1. Read the overview information in “Setting JEE deployment descriptor values”

on page 176.2. If you worked on an application client or EJB project, you must make sure that

the order of the sub-elements in the generated environment entries is correct, asdescribed in “JEE environment file” on page 173.

3. Copy the environment entries into your project’s deployment descriptor asfollows:a. Make a backup copy of the deployment descriptor.b. Open the JEE environment file, which is called programName-env.txt file.

Copy the environment entries into the clipboard.c. Double-click on the deployment descriptor.d. Click on the Source tab.e. Paste the entries at a proper location.Related concepts

“Generation output and associated files” on page 91Related tasks

“Setting JEE deployment descriptor values” on page 176“Setting up the JEE runtime environment for EGL-generated code” on page 186Related reference


“genProject” on page 325“genProperties” on page 326“j2ee” on page 333

Setting JEE deployment descriptor values

An important task is to place runtime values, which are similar toenvironment-variable values, into the deployment descriptor of your JEE module.For example, you can interact with a workbench editor listed in the table below.

Project type Name of deploymentdescriptor

How to assign values

application client application-client.xml Use the XML editor, Designtab

EJB ejb-jar.xml Use the EJB editor, Beanstab

JEE Web web.xml Use the web.xml editor,Environment tab

The recommended way to update the deployment descriptor is to add contentautomatically, as happens if all of the following conditions apply:v You are generating a Java program or wrapperv You set the genProperties build descriptor option to GLOBAL or PROGRAMv You are generating for a JEE run time by setting j2ee to YESv You set the genProject build descriptor option to a valid JEE project

EGL never deletes a property from an existing deployment descriptor, but does thefollowing actions:v Overwrites properties that already existv Appends properties that do not exist

Another method of updating the deployment descriptor is to copy and pastevalues from the JEE environment file, which is created during generation if all ofthe following conditions apply:v You are generating a Java programv You set the genProperties build descriptor option to GLOBAL or PROGRAMv You are generating for a JEE run time by setting J2EE to YESv You do not set genProject to a valid JEE project, as when you generate into a

directory instead

Before you paste entries from a JEE environment file into the deploymentdescriptor of an application client or EJB project, you need to change the order ofentries in the file, as described in “JEE environment file” on page 173. You do notneed to change the order of entries if you are working with a JEE Web project.

Related concepts

“JEE deployment descriptor” on page 175“JEE environment file” on page 173“Description of Java runtime properties” on page 159“Program properties file” on page 177Related tasks


“Generating Java code into a project” on page 178“Processing Java code that is generated into a directory” on page 180“Setting up the JEE runtime environment for EGL-generated code” on page 186Related reference

“genDirectory” on page 323“genProperties” on page 326“j2ee” on page 333

Program properties file

In addition to the properties associated with EGL parts, there are a number of Javaruntime properties that control access to databases, files, and other resources. Tohelp distinguish them from EGL properties, and to emphasize the fact that they arenot properties under J2EE, this documentation may refer to these Java runtimeproperties as settings.

When you generate Java code, and you have the genProperties build descriptoroption set to GLOBAL or PROGRAM, the settings in various build descriptoroptions are stored as Java runtime properties, and are written to one of threelocations:v a program properties file;v the J2EE deployment descriptor for the project; orv a J2EE environment file.

In general, if one of the following is true:v the generatable part is a JSF Handler part; orv the generatable part is a VGWebTransaction, orv the j2ee build descriptor option is set to YES;

and if the genProperties build descriptor option is set to GLOBAL or PROGRAM,then the values of some build descriptor options that are used at Java run time getstored in a file.

If you are generating in a non-J2EE environment, EGL stores these settings in aprogram properties file. This is one of three different possible files, which aresearched in the following order:

user.propertiesEGL does not create this file; you must create it yourself in your homedirectory (for example, C:\Documents and Settings\Administrator).

programName.propertiesEGL creates this file in the appropriate package in the Java Resourcesdirectory (for example, src/com/companyb/customerpackage) if thegenProperties build descriptor option is set to PROGRAM.

rununit.propertiesEGL creates this file in the Java Resources directory if the genPropertiesbuild descriptor option is set to GLOBAL.

All three are plain text files with entries in the form:setting = value

This example shows what part of a properties file might look like:


# This file contains properties for generated# Java programs that are being debugged in a# non-J2EE Java project

vgj.nls.code = ENUvgj.datemask.gregorian.long.ENU = MM/dd/yyyy

Related concepts

“Generation output and associated files” on page 91“Overview of Java runtime properties” on page 153Related reference

“Description of Java runtime properties” on page 159“genProperties” on page 326“j2ee” on page 333

Alternatives for the Java preparation phase

When you are generating Java code, you have several ways you can proceed withthe generation process. These methods differ mainly in the way your output isprepared for deployment. Depending on which build descriptor options you set,the following situations are possible:v If you set the genProject build descriptor option, your output is placed into the

Java source folder of your current project, in your Eclipse workspace. This is thepreferred method. For details, see “Generating Java code into a project.”

v If you set the genDirectory build descriptor option, your output is placed intothe directory you place in the value field for that build descriptor option. Fordetails, see “Processing Java code that is generated into a directory” on page180.Related tasks

“Generating Java code into a project”“Processing Java code that is generated into a directory” on page 180

Generating Java code into a project

If you are generating a Java program or wrapper, it is recommended, and in somecases required, that you set the genProject build descriptor option. This generatesoutput into a project in your workspace.

EGL provides various services for you when you generate into a project. Theservices vary by project type, as do your next tasks. See the sections below to findthe particular type of project you want to use. Each section has the steps you willneed to follow to generate into that type of project.

Application client project

When you generate into an application client project, EGL providespreparation-time access to the EGL JAR file (fda7.jar) by adding the following filesto the project’s Java build path:

EGL_GENERATORS_PLUGINDIR/fda7.jar

EGL also provides runtime access to the EGL JAR files by importing them intoeach enterprise application project that references the application client project.EGL then updates the manifest in the application client project, so that the JARfiles in an application client project are available. EGL also puts runtime values


into the J2EE deployment descriptor. This is so you can avoid cutting and pastingentries from a generated J2EE environment file.

To generate Java into this type of project, do the following:1. If you are calling the generated program by way of TCP/IP, provide runtime

access to a listener. This is described in “Setting up a TCP/IP listener for J2EEcalled applications” on page 193 and “Setting up the TCP/IP listener for acalled non-J2EE application” on page 198.

2. Provide access to non-EGL JAR files, as described in the topic ″Providing accessto non-EGL JAR files″.

3. Once you have placed output files in a project, continue setting up the J2EEruntime environment.

J2EE Web project

When you generate into an application client project, EGL providespreparation-time access to the EGL JAR file (fda7.jar) by adding them into theproject’s Web Content/WEB-INF/lib folder. EGL also puts runtime values into theJ2EE deployment descriptor. This is so you can avoid cutting and pasting entriesfrom a generated J2EE environment file.

To generate Java into this type of project, do the following:1. Provide access to non-EGL JAR files, as detailed in “Providing access to

non-EGL JAR files” on page 187.2. Generate the code.3. Once you have placed output files in a project, continue as described in the

topic “Setting up the JEE runtime environment for EGL-generated code” onpage 186.

Java project

When you generate into a non-J2EE Java project for debugging or productionpurposes, EGL provides preparation-time access to the EGL JAR file (fda7.jar) byadding the following files to the project’s Java build path:

EGL_GENERATORS_PLUGINDIR/fda7.jar

EGL will generate a properties file under the following conditions:v genProperties is set to GLOBAL or PROGRAM; andv J2EE is set to NO.

If you set genProperties to GLOBAL (rununit.properties), EGL places that file inthe Java source folder (the folder that contains the Java packages). The Java sourcefolder may be either a folder within the project or the project itself. If you setgenProperties to PROGRAM instead, EGL places the program properties file intothe folder that contains the program.

To generate Java into this type of project, do the following:1. If your program accesses a relational database, make sure that your Java build

path includes the directory where the driver is installed. For DB2, for example,specify the directory that contains db2java.zip.

2. If your code accesses MQ message queues, provide access to non-EGL jar files,as detailed in “Providing access to non-EGL JAR files” on page 187.

3. Place a linkage properties file in the module.


Related tasks

“Providing access to non-EGL JAR files” on page 187“Setting JEE deployment descriptor values” on page 176“Setting the variable EGL_GENERATORS_PLUGINDIR” on page 13“Setting up the JEE runtime environment for EGL-generated code” on page 186“Setting up the TCP/IP listener for a called non-J2EE application” on page 198“Setting up a TCP/IP listener for J2EE called applications” on page 193Related reference

“Build descriptor options” on page 41“Build descriptor options used with Java” on page 144“genDirectory” on page 323“genProject” on page 325“sessionBeanID” on page 350

Processing Java code that is generated into a directory

This topic describes how to process Java code that is generated into a directory. Itis recommended, however, that you avoid generating Java code into a directory;for details, see “Generating Java code into a project” on page 178.

To generate Java code into a directory, specify the genDirectory build descriptoroption and avoid specifying the genProject build descriptor option.

Your next tasks depend on the project type:

Application client projectFor an application client project, follow these steps:1. Provide runtime access to fda7.jar by following these steps:

a. Access the JAR files from the following directory:shared_resources\plugins\com.ibm.etools.egl.java.runtime_version

shared_resourcesThe shared resources directory for your product, such as C:\ProgramFiles\IBM\SDP70Shared on a Windows system or/opt/IBM/SDP70Shared on a Linux system. If you installed and kepta previous version of an IBM product containing EGL beforeinstalling your current product, you may need to specify the sharedresources directory that was set up in the earlier install.

versionThe installed version of the plugin, including three numbersseparated by periods, a string separator, and the date and time thatthe plugin was built; for example, 7.0.0.RFB_20070120_1300. If morethan one is present, use the one with the most recent versionnumber, unless you have a reason to use an older version.

b. Copy the file into each enterprise application project that references theapplication client project.

c. Update the manifest in the application client project so that the jar files(as stored in an enterprise application project) are available.

2. Provide access to non-EGL JAR files (an optional task).3. Import your generated output into the project, in keeping with these rules:


v The folder appClientModule must include the top-level folder of thepackage that contains your generated output.

v The hierarchy of folder names beneath appClientModule must match thename of your Java package.

If you are importing generated output from package my.trial.package, forexample, you must import that output into a folder that resides in thefollowing location:

appClientModule/my/trial/package

4. If you generated a J2EE environment file, use that to update the J2EEdeployment descriptor.

5. Now that you have placed output files in a project, continue setting up theJ2EE runtime environment.

J2EE Web projectFor a Web project, follow these steps:1. Provide access to the EGL JAR file by copying fda7.jar into your Web

project folder. To do so, import the external JARs found in the followingdirectory:shared_resources\plugins\com.ibm.etools.egl.java.runtime_version

shared_resourcesThe shared resources directory for your product, such as C:\ProgramFiles\IBM\SDP70Shared on a Windows system or /opt/IBM/SDP70Sharedon a Linux system. If you installed and kept a previous version of anIBM product containing EGL before installing your current product,you may need to specify the shared resources directory that was set upin the earlier install.

versionThe installed version of the plugin, including three numbers separatedby periods, a string separator, and the date and time that the pluginwas built; for example, 7.0.0.RFB_20070120_1300. If more than one ispresent, use the one with the most recent version number, unless youhave a reason to use an older version.

The destination for the files is the following project folder:WebContent/WEB-INF/lib

2. Provide access to non-EGL JAR files (an option)3. Import your generated output into the project, in keeping with these rules:

v The folder WebContent must include the top-level folder of the packagethat contains your generated output.

v The hierarchy of folder names beneath WebContent must match the nameof your Java package.

If you are importing generated output from package my.trial.package, forexample, you must import that output into a folder that resides in thefollowing location:WebContent/my/trial/package

4. Update the J2EE deployment descriptor.5. Now that you have placed output files in a project, continue setting up the

J2EE runtime environment.

Java projectIf you are generating code for use in a non-J2EE environment, you generate aproperties file if you use the following combination of build descriptor options:


v genProperties is set to GLOBAL or PROGRAM; andv J2EE is set to NO.

For a Java project, you have the following tasks:1. Provide access to the EGL JAR file by adding the following entry to the

project’s Java build path:EGL_GENERATORS_PLUGINDIR/fda7.jar

For details on the variable at the beginning of each entry, see “Setting thevariable EGL_GENERATORS_PLUGINDIR” on page 13.

2. If your program accesses a relational database, make sure that your Javabuild path includes the directory where the driver is installed. For DB2, forexample, specify the directory that contains db2jcc.jar. If your generatedcode accesses MQ message queues, provide access to non-EGL jar files

3. Make sure that the global properties file (rununit.properties, if present) isin the top-level project folder and that the program properties file (ifpresent) is either in the folder that corresponds to the last qualifier in thepackage name or in the top-level project folder. The top-level folder is usedif the package name is not specified in the EGL source file.

4. Place a linkage properties file in the project (an optional task).Related topics

“Generating Java code into a project” on page 178Related tasks

“Providing access to non-EGL JAR files” on page 187“Setting JEE deployment descriptor values” on page 176“Setting the JNDI name for EJB projects” on page 189“Setting the variable EGL_GENERATORS_PLUGINDIR” on page 13“Setting up the JEE runtime environment for EGL-generated code” on page 186“Understanding how a standard JDBC connection is made” on page 190Related reference

“genDirectory” on page 323“genProject” on page 325

Preparing for deployment

This section contains topics on preparing to deploy your generated Java code.There is information on the following:v Linkage properties filesv Tasks related to deploying in a JEE environmentv Tasks related to deploying in a non-JEE environment

Related concepts

“Linkage properties file”“Deploying to a JEE environment” on page 186“Deploying to a non-JEE environment” on page 194

Linkage properties file

A linkage properties file file is a text file that is used at Java run time to give detailson how to call a remote program.


When you generate a calling Java program or wrapper, you can specify thatlinkage information is required at run time. You make that specification by settingthe linkage-option values for the called program as follows:v The value of the callLink element type property is remoteCall or ejbCall; andv The value of the callLink element remoteBind property is runtime.

A linkage properties file may be handwritten, but EGL generates a file if (inaddition to the settings described earlier) you generate a Java program or wrapperwith the genProperties build descriptor option set to GLOBAL or PROGRAM.

How the linkage properties file is identified at run time

If the callLink element remoteBind property for a called program was set toruntime in the linkage options part, EGL looks for the linkage properties file at runtime; the source of the file name is determined in the following ways:v A Java program checks the cso.linkageOptions.LO Java runtime property, where

LO is the name of the linkage options part used for generation. If the property isnot present, the EGL runtime code seeks a linkage properties file namedLO.properties. Again, LO is the name of the linkage options part used forgeneration.In this case, if the EGL runtime code seeks a linkage properties file but is unableto find that file, an error occurs on the first call statement that requires use ofthat file. For details on the result, see Exception handling.

v The Java wrapper stores the name of the linkage properties file in the programobject variable callOptions, which is of type CSOCallOptions. The generatedname of the file is LO.properties, where LO is the name of the linkage optionspart used for generation.In this case, if the Java Virtual Machine seeks a linkage properties file but isunable to find that file, the program object throws an exception of typeCSOException.

Deploying a linkage properties file

The linkage properties file must be in the same project as the Java program thatuses the file. If the file is in the top-level directory of the application, set thecso.linkageOptions.LO Java runtime property to the file name, without pathinformation. If the file is under the top-level directory of the application, use apath that starts at the top-level directory and includes a forward slash (/) for eachlevel, even if the application is running on a Windows platform.

When you are developing a J2EE project, the top-level directory corresponds to theappClientModule, ejbModule, or Web Content directory of the project in which themodule resides. When you are developing a Java project, the top-level directory isthe project directory.

Format of the linkage properties file

As used during run time, the linkage properties file includes a series of entries tohandle each call from the generated Java program or wrapper that you aredeploying.

The primary entry is of type cso.serverLinkage and can include anyproperty-and-value pair that you can set in a callLink element of the linkageoptions part, with the following exceptions:


v The remoteBind property is necessarily runtime and is ignored.v The type property cannot belocalCall, because linkage for local calls must be

established at generation time.

cso.serverLinkage entries

In the most elementary case, each entry in the linkage properties file is of typecso.serverLinkage. The format of the entry is as follows:

cso.serverLinkage.programName.property=value

programNameThe name of the called program. If the called program is generated by EGL,the name you specify is that of a program part.

propertyAny of the properties appropriate for a Java program, except for propertiesremoteBind and pgmName. For details, see callLink element. Use externalNamefor the alias property, not alias.

valueA value that is valid for the specified property.

An example for called program Xyz is as follows, where xxx refers to acase-sensitive string:cso.serverLinkage.Xyz.type=remoteCallcso.serverLinkage.Xyz.remoteComType=TCPIPcso.serverLinkage.Xyz.remotePgmType=EGLcso.serverLinkage.Xyz.externalName=xxxcso.serverLinkage.Xyz.package=xxxcso.serverLinkage.Xyz.conversionTable=xxxcso.serverLinkage.Xyz.location=xxxcso.serverLinkage.Xyz.serverID=xxxcso.serverLinkage.Xyz.parmForm=COMMDATAcso.serverLinkage.Xyz.providerURL=xxxcso.serverLinkage.Xyz.luwControl=CLIENT

The literal values TCPIP, EGL, and so on are not case sensitive and are examples ofvalid data.

cso.application entries

If you wish to create a series of cso.serverLinkage entries that refer to any ofseveral called programs, precede those entries with one or more entries of typecso.application. Your purpose in this case is to equate a single application name tomultiple program names. In the subsequent cso.serverLinkage entries, you use theapplication name instead of programName; then, at Java run time, thosecso.serverLinkage entries handle calls to any of several programs.

The format of a cso.application entry is as follows:cso.application.wildProgramName=appName

wildProgramNameA valid program name, an asterisk, or the beginning of a valid program namefollowed by an asterisk. The asterisk is the wild card equivalent of one or morecharacters and provides a way to identify a set of names.

If wildProgramName refers to a program that is generated by EGL, any programname included in wildProgramName is the name of a program part.


appNameA series of characters that conforms to the EGL naming conventions. The valueof appName is used in subsequent cso.serverLinkage entries.

The following example show use of an asterisk as a wild card character. Thecso.serverLinkage entries in this example handle any call to a program whosename begins with Xyz:

cso.application.Xyz*=myAppcso.serverLinkage.myApp.type=remoteCallcso.serverLinkage.myApp.remoteComType=TCPIPcso.serverLinkage.myApp.remotePgmType=EGLcso.serverLinkage.myApp.externalName=xxxcso.serverLinkage.myApp.package=xxxcso.serverLinkage.myApp.conversionTable=xxxcso.serverLinkage.myApp.location=xxxcso.serverLinkage.myApp.serverID=xxxcso.serverLinkage.myApp.parmForm=COMMDATAcso.serverLinkage.myApp.luwControl=CLIENT

The following example shows use of the same cso.serverLinkage entries to handlecalls to any of several programs, even though the names of those programs do notbegin with the same characters:

cso.application.Abc=myAppcso.application.Def=myAppcso.application.Xyz=myAppcso.serverLinkage.myApp.type=remoteCallcso.serverLinkage.myApp.remoteComType=TCPIPcso.serverLinkage.myApp.remotePgmType=EGLcso.serverLinkage.myApp.externalName=xxxcso.serverLinkage.myApp.package=xxxcso.serverLinkage.myApp.conversionTable=xxxcso.serverLinkage.myApp.location=xxxcso.serverLinkage.myApp.serverID=xxxcso.serverLinkage.myApp.parmForm=COMMDATAcso.serverLinkage.myApp.luwControl=CLIENT

If multiple cso.application entries are valid for a program, EGL uses the first entrythat applies.

You can find more information in the topics ″Naming conventions″ and ″Exceptionhandling″ in the EGL Language Reference.

Related concepts

“Linkage options part” on page 61“Overview of Java runtime properties” on page 153Related tasks

“Editing the callLink element of a linkage options part” on page 387“Editing the fileLink element of a linkage options part” on page 407“Setting JEE deployment descriptor values” on page 176“Setting up the JEE runtime environment for EGL-generated code” on page 186Related reference

“callLink element” on page 380“Description of Java runtime properties” on page 159


Deploying to a JEE environment

This section gives information specific to deploying to a JEE environment. Itincludes topics on the following:v Setting up the J2EE runtime environmentv Working with Enterprise JavaBeans™ (EJB)v Connectivity in a J2EE environment, including understanding and working with

JDBC drivers and the TCP/IP listener application.Related concepts

“Enterprise JavaBean (EJB) session bean” on page 188“Understanding how a standard JDBC connection is made” on page 190Related tasks

“Eliminating duplicate jar files” on page 187“Providing access to non-EGL JAR files” on page 187“Setting the JNDI name for EJB projects” on page 189“Setting up a TCP/IP listener for J2EE called applications” on page 193“Setting up the JEE runtime environment for EGL-generated code”“Setting up the J2EE server for CICSJ2C calls” on page 189“Setting up the J2EE server for IMSJ2C calls” on page 190Related reference

“JDBC driver requirements in EGL” on page 191

Setting up the JEE runtime environment for EGL-generated code

EGL-generated Java programs and Java wrappers run on a JEE server, such asWebSphere® Application Server.

When embedding generated Java classes into a JEE module, follow these steps:1. Place output files in a project, in either of two ways:

v Generate into a project, the preferred technique;v Generate into a directory, then import files into a project.

2. Place a linkage properties file in the module. This may be done by EGLautomatically during generation. For more information, see “Linkage propertiesfile” on page 182.

3. Eliminate duplicate JAR files.4. Export an enterprise archive (EAR) file, which may include Web application

archive (WAR) files and other EAR files; for details on the procedure, see thetopics on exporting files in the EGL Programmer’s Guide.

5. Import the EAR file into the JEE server that will host your application; fordetails on the procedure, see the documentation for your JEE server.Related concepts

“Linkage properties file” on page 182Related tasks

“Setting up a J2EE JDBC connection” on page 192“Setting up the J2EE server for CICSJ2C calls” on page 189“Setting up the J2EE server for IMSJ2C calls” on page 190“Setting up the TCP/IP listener for a called non-J2EE application” on page 198“Setting up a TCP/IP listener for J2EE called applications” on page 193


Eliminating duplicate jar files

This task is optional in setting up your J2EE runtime environment. The advantageto doing this task is that you will save space. If you place multiple J2EE modulesinto a single EAR project, eliminate the duplicate JAR files as follows:1. Move a copy of each duplicate JAR file to the top level of the EAR project.2. Delete the duplicate JAR files from the J2EE modules.3. Make the JAR files accessible to all modules in the EAR by doing as follows:

a. Right-click on the EAR project in the Project Explorer.b. Select J2EE Module Dependencies from the context menu.c. Click Add JARs and select the JAR files. Click OK to finish.

4. Ensure that the build path for each of the affected J2EE modules points to theJAR files in the EAR; specifically, follow these steps for each of those J2EEmodules:a. Right-click on the module in the Project Explorer.b. Select J2EE Module Dependencies.c. When the Module Dependencies dialog is displayed, select the JAR files to

access from the top level of the EAR, then click OK.Related tasks

“Setting up the JEE runtime environment for EGL-generated code” on page 186

Providing access to non-EGL JAR files

You may need to provide access to non-EGL JAR files to debug and run yourEGL-generated Java code. The process for providing access to those files varies byproject type:

Application client project

Before running your code perform the following steps:1. For each enterprise application project that references the application client

project, import JAR files of interest from a directory in the file system:a. In the Project Explorer view, right-click an enterprise application project

and click Import.b. At the Select page, click File System.c. At the File System page, specify the directory in which the JAR files

reside.d. At the right of the page, select the JAR files of interest.e. Click Finish.

2. Ensure that the build path for each of the affected modules points to theJAR files in the EAR:a. Right-click on the EAR project in the Project Explorer.b. Select J2EE Module Dependencies from the context menu.c. Click Add JARs and select the JAR files. Click OK to finish.

EJB project

Before running your code (with or without the EGL Java debugger), do asfollows:1. For each enterprise application project that references the EJB project,

import JAR files of interest from a directory in the file system:


a. In the Project Explorer view, right-click an enterprise application projectand click Import.

b. At the Select page, click File System.c. At the File System page, specify the directory in which the JAR files

reside.d. At the right of the page, select the JAR files of interest.e. Click Finish.

2. Update the manifest in the EJB project so that the JAR files in the enterpriseapplication project are available at run time:a. In the Project Explorer view, right-click your EJB project and click

Properties.b. At the left of the Properties page, click Java JAR Dependencies.c. When the section called Java JAR Dependencies is displayed at the right

of the page, set each check box that corresponds to a JAR file of interest.d. Click OK.

J2EE Web project

Before running your code (with or without the EGL Java debugger), import theJAR files from the file system to the following Web project folder:

Web Content/WEB-INF/lib

The import process is as follows for a set of jar files in a directory:1. In the Project Explorer view, expand the Web project, expand Web Content,

expand WEB-INF, right-click lib, and click Import.2. At the Select page, click File System.3. At the File System page, specify the directory in which the JAR files reside.4. At the right of the page, select the JAR files of interest.5. Click Finish.

Related tasks


Enterprise JavaBean (EJB) session bean

An EJB session bean comprises the following components:v Home interface, which gives a client access to the EJB session bean at run timev Remote bean interface, which lists the methods that are directly available to that

clientv Bean implementation, which contains the logic that is indirectly available to that

client

An EJB session bean is an intermediary between one program and another orbetween an EGL Java wrapper and a program. Generation of the EJB session beanlargely depends on settings in the linkage options part that is used at generationtime.

For details on the output file names, see “Generation output and associated files”on page 91.

Related concepts

“Generation output and associated files” on page 91“Linkage options part” on page 61Related reference


“wrapperJNDIPrefix” on page 374

Setting the JNDI name for EJB projects

To set the JNDI name for an EJB project, do as follows:1. Right click on ejb-jar.xml (the deployment descriptor) to open the context

menu.2. Use the EJB Editor to open the following file in the project:

\ejbModule\META-INF\ejb-jar.xml

3. Click on the Beans tab.4. On the list, click on the name of the EJB you just generated.5. Enter the JNDI name under WebSphere Bindings. The JNDI name must be as

follows for use by the EGL runtime code:v First character of the program name, in upper casev Subsequent characters of the program name, in lower casev The letters EJB in upper case.Related tasks


“wrapperJNDIPrefix” on page 374

Setting up the J2EE server for CICSJ2C calls

You must set up a Java ConnectionFactory in the J2EE server for each CICStransaction accessed through protocol CICSJ2C.

If a generated Java wrapper is making the CICSJ2C call, you can handle security inany of the following ways (where a wrapper-specified value overrides that of theJ2EE server):v Set the userid and password in the wrapper’s CSOCallOptions objectv Set the userid and password in the ConnectionFactory configuration in the J2EE

serverv Set up the CICS region so that user authentication is not required.

When calling a program from WebSphere Application Server for z/OS, thefollowing restrictions apply:v If the luwControl property of the callLink element is set to client, the call fails.

The WebSphere Application Server for z/OS connect implementation does notsupport an extended unit of work.

v The setting of the cso.cicsj2c.timeout deployment descriptor property has noeffect.By default, timeout never occurs. In the EXCI options table generated by themacro DFHXCOPT, however, you can set the parameter TIMEOUT, which letsyou specify the time that EXCI will wait for a DPL command (an ECI request) tocomplete. A setting of 0 means to wait indefinitely.

For details, see Java Connectors for CICS: Featuring the J2EE Connector Architecture(SG24-6401-00), which is available from web site http://www.redbooks.ibm.com.

Related tasks



“Build descriptor options” on page 41“Build descriptor options used with Java” on page 144“cicsj2cTimeout” on page 305

Setting up the J2EE server for IMSJ2C calls

You must set up a ConnectionFactory in the J2EE server for each IMS transactionaccessed through protocol IMSJ2C.

If a generated Java wrapper is making the IMSJ2C call, you can handle security inany of the following ways (where a wrapper-specified value overrides that of theJ2EE server):v Set the userid and password in the wrapper’s CSOCallOptions object; orv Set the userid and password in the ConnectionFactory configuration in the J2EE

server; orv Set up the IMS region so that user authentication is not required.

If the luwControl callLink element property is set to CLIENT when you are callinga program from WebSphere 390, the call fails. The WebSphere 390 connectimplementation does not support an extended unit of work.

For other details, see e-business Cookbook for z/OS Volume II: Infrastructure(SG24-5981-01), which is available from Web site http://www.redbooks.ibm.com.

Related tasks


Understanding how a standard JDBC connection is made

A standard JDBC connection is created for you at run time if you are debugging agenerated Java program and if the program properties file includes the necessaryvalues.

The JDBC connection is based on the following kinds of information:

Connection URLIf your code tries to access a database before invoking the sysLib.connect orvgLib.connectionService system function, the connection URL is the value ofthe vgj.jdbc.default.database property.

If your code tries to access a database in response to an invocation of thesysLib.connect or vgLib.connectionService system function, the connectionURL is the value of the vgj.jdbc.databaseSN property.

For details on the format of a connection URL, see sqlValidationConnectionURL.

User IDIf your code tries to access a database before invoking the sysLib.connect orvgLib.connectionService system function, the user ID is the value of thevgj.jdbc.default.userid property.

If your code tries to access a database in response to an invocation of one ofthose system functions, the user ID is a value specified in the invocation.

PasswordIf your code tries to access a database before invoking the sysLib.connect orvgLib.connectionService system function, the password is the value of thevgj.jdbc.default.password property.


If your code tries to access a database in response to an invocation of one ofthose system functions, the password is a value specified in the invocation.You can use a system function to avoid exposing the password in the programproperties file.

JDBC driver classThe JDBC driver class is the value of the vgj.jdbc.drivers property.

Related concepts

“Program properties file” on page 177Related tasks

“Setting up a J2EE JDBC connection” on page 192“Setting up the JEE runtime environment for EGL-generated code” on page 186Related reference

“genProperties” on page 326“Description of Java runtime properties” on page 159“JDBC driver requirements in EGL”“sqlDB” on page 355“sqlID” on page 356“sqlJDBCDriverClass” on page 357“sqlPassword” on page 360“sqlValidationConnectionURL” on page 360connect()

JDBC driver requirements in EGL

The JDBC driver requirements vary by database management system, whether forEGL debug time or run time. The following rules apply to any JDBC driver usedwith EGL:v The driver must support JDBC 2.0 or higherv The value java.sql.ResultSet.CONCUR_UPDATABLE must be allowed in these

contexts:– As the second argument to java.sql.Connection.createStatement(int,int)– As the third argument to java.sql.Connection.prepareStatement(String,int,int)

and java.sql.Connection.prepareCall(String,int,int)v If you wish to support the hold option in the EGL open statement, the driver

must support JDBC 3.0, and the valuejava.sql.ResultSet.HOLD_CURSORS_OVER_COMMIT must be allowed in thesecontexts:– As the third argument to java.sql.Connection.createStatement(int,int,int)– As the fourth argument to

java.sql.Connection.prepareStatement(String,int,int,int) andjava.sql.Connection.prepareCall(String,int,int,int)

Following are requirements for JDBC drivers used with specific databases:

DB2 UDB

The DB2 Universal driver is compatible with EGL, but the related App driveris not compatible; specifically, the App driver cannot process an EGL open orget statement that includes the option forUpdate.

IBM recommends that you not use the Net driver at all.


If you are running J2EE applications in WebSphere Application Server v6.x,you need DB2 version 8.1.6 or higher. If you are running those applicationsinWebSphere Application Server v5.x Test Environment, you need DB2 version8.1.3 or higher.

Informix®

The minimum acceptable Informix JDBC driver is 2.21.JC6. This driver leveldoes not comply with JDBC 3.0 and therefore does not support the hold optionin the EGL open statement.

OracleThe JDBC driver that is packaged with Oracle 10i is acceptable.

Microsoft® SQL ServerEGL supports the JDBC drivers from WebSphere, Microsoft, and DataDirect foruse with Microsoft SQL Server.

For any database management system, JDBC drivers from third- or fourth-partyvendors are acceptable.

Related tasks

“Setting up a J2EE JDBC connection”“Understanding how a standard JDBC connection is made” on page 190

Setting up a J2EE JDBC connection

If you are connecting to a relational database at run time, you need to define adata source for use with your program. If you are using WebSphere ApplicationServer, the directions are in the help system of the administrative console. If youare using another supported J2EE server, check the documentation for your serverfor instructions on defining the data source.

When you define a data source, assign values to the following properties:

JNDI nameSpecify a value that matches the name to which the database is bound in theJNDI registry:v If you are defining a data source which connects to a database that your

J2EE module uses by default, make sure that the JNDI name specified in thedata source definition matches the value of the vgj.jdbc.default.databaseproperty in the J2EE deployment descriptor used at run time

v If you are defining a data source that will be accessed when the systemfunction vgLib.connectionService runs, make sure that the JNDI namespecified in the data source definition matches the value of the appropriatevgj.jdbc.database.SN property in the J2EE deployment descriptor used atrun time

Database nameSpecify the name of your database, as known to the database managementsystem

User IDSpecify the user name for connecting to the database.

If the data source definition refers to the default database, the value youspecify in the User ID field is overridden by any value set in thevgj.jdbc.default.userid property of the J2EE deployment descriptor used at runtime, but only if you have specified values for both vgj.jdbc.default.userid andvgj.jdbc.default.password. Similarly, if the data source definition refers to a


database that is accessed by way of the sysLib.connect orvgLib.connectionService system functions, the value you specify in the UserID field is overridden by any user ID that you specify in the call to that systemfunction, but only if the call passes both a user ID and password.

You specify the name when setting up the authentication alias. To reach thedisplay where you can define that alias, follow this sequence in theAdministrative Console:Security → GlobalSecurity → Authentication → JAASConfiguration → J2C Authentication Data.

PasswordSpecify the password for connecting to the database. If the data sourcedefinition refers to the default database, the value you specify in the Passwordfield is overridden by any value set in the vgj.jdbc.default.password propertyof the J2EE deployment descriptor used at run time, but only you havespecified values for both vgj.jdbc.default.userid andvgj.jdbc.default.password. Similarly, if the data source definition refers to adatabase that is accessed by way of the vgLib.connectionService systemfunction, the value you specify in the Password field is overridden by anypassword that you specify in the call to that system function, but only if thecall passes both a user ID and password.

You specify the password when setting up the authentication alias. To reachthe display where you can define that alias, follow this sequence in theAdministrative Console: Security → GlobalSecurity → Authentication → JAASConfiguration → J2C Authentication Data.

You may define multiple data sources, in which case you use the system functionvgLib.connectionService to switch between them.

Related tasks

“Setting up the JEE runtime environment for EGL-generated code” on page 186“Understanding how a standard JDBC connection is made” on page 190Related reference

“Description of Java runtime properties” on page 159“JDBC driver requirements in EGL” on page 191

Setting up a TCP/IP listener for J2EE called applications

If you want a calling program to use TCP/IP to start a called program in a J2EEapplication client module, you must set up a TCP/IP listener for the calledprogram.

You must meet the following requirements:v The called program must be generated to or copied to a J2EE application client

module.v The main class of the application client module is the EGL TCP/IP listener.v A port is assigned to the listener.

Setting the main class of an application client

To set the main class of an application client, follow these steps:1. Edit the project’s Deployment Descriptor (application-client.xml) or manifest

file (MANIFEST.MF).2. Under the heading Main Class, enter:

com.ibm.javart.calls.listener.TcpipListenerJ2EE.


Assigning a port to the listener

To assign the listener’s port, follow these steps:1. Open the project’s Deployment Descriptor (application-client.xml).2. Under the heading Environment Variables, click Add.3. In the name field, enter tcpiplistener.port.4. In the type field, enter java.lang.Integer.5. In the value field, type a port number. This should be the same value given in

the serverID field of the calling program’s linkage options part.

Running the application client

An application client can be started in either of two ways; the options available toyou depend on which J2EE server you use:v If you use the WebSphere Application Server, you can start the application client

from the workbench by using the launch configuration. Follow these steps:1. Locate the Run menu item in the workbench. Click Run → Run.2. Click the type of launch configuration appropriate for your server. For

example, for WebSphere Application Server it is WebSphere v6.1 ApplicationClient.

3. Select an existing configuration. Alternatively, you can click New to create anew configuration. You must enter the names of the application client and itsenterprise application (EAR) in the appropriate fields.

v Start the application client from the command line. The command will varydepending on your J2EE server, so consult your server’s documentation. ForWebSphere Application Server, you can use launchClient.bat, which is in theWebSphere Application Server installation directory, in the bin subdirectory. Youcan start launchClient.bat by entering the following at the command prompt:launchClient myCode.ear -CCjar=myJar.jar

myCodeThe name of your enterprise archive (EAR).

myJarThe name of the application client JAR file.

The name of the JAR file is only necessary if you have multiple client JAR filesin your EAR file. You can find more information on launchClient.bat in thedocumentation for WebSphere Application Server.Related tasks

“Providing access to non-EGL JAR files” on page 187“Setting up the JEE runtime environment for EGL-generated code” on page 186

Deploying to a non-JEE environment

This section contains information about deploying Java to a non-J2EE environment.It has topics on the following:v Deploying applications outside of JEEv Installing EGL runtimes in a non-JEE environmentv Setting up the UNIX curses library for use with EGLv Connectivity in a non-JEE environment

Related tasks


“Deploying Java applications outside of JEE”“Installing the EGL runtime code for Java”“Setting up the UNIX curses library for the EGL runtime” on page 197“Setting up the TCP/IP listener for a called non-J2EE application” on page 198

Deploying Java applications outside of JEE

To deploy a Java application outside of JEE, follow these steps:1. Follow the procedure detailed in “Installing the EGL runtime code for Java.”2. Export the generated code into JAR files, remembering to include generated

output files that have extensions other than .java; for example, jasper andproperties files.

3. Export any manually written Java code into JAR files.4. Include the exported files in the classpath of the target system.

Providing access to non-EGL JAR files

Before deploying your code, add entries for non-EGL JAR files to the project’s Javabuild path:1. In the Project Explorer view, right-click your Java project and click Properties.2. At the left of the Properties page, click Java Build Path.3. When the section called Java Build Path is displayed at the right of the page,

click the Libraries tab.4. For each jar file to be added, click Add External Jars and use the Browse

mechanism to select the file.5. To close the Properties page, click OK.

Related tasks

“Installing the EGL runtime code for Java”

Installing the EGL runtime code for Java

The EGL runtime code for generated Java applications is in the Rational BusinessDeveloper plugins directory. The plugins directory is located in the product sharedresources directory.

The runtime code is located in the following plugin JAR file:com.ibm.etools.egl.java.binaries_version.jar

versionCurrent version of the product.

The supported distributed platforms are as follows:v AIXv HP-UXv Linux (Intel)v iSeriesv Solarisv USSv Windows 2000/NT/XP

See product prerequisites for supported versions. EGL provides 32- and 64-bitsupport for AIX, HP-UX, and Solaris.


The runtime code includes the following:v JAR files which contain Java code that is common to all supported distributed

platformsv Platform-specific code

Do as follows:1. Extract the files to each system on which deployed EGL applications are to be

run.2. Include the JAR files in the CLASSPATH of the deployment systems. Here are

the files:v fda7.jar is required for all uses and is in

com.ibm.etools.egl.java.runtime_version, where version is the productversion.

v fda6wrappers.jar is needed if you used Java wrappers in EGL version 6.x, areregenerating the wrappers in EGL 7.x, and wish to avoid updating the nativeJava code that invokes the wrappers. In this case, set the build descriptoroption wrapperCompatibility to V6 at generation time, as noted in the helptopic for that option.The file fda6wrappers.jar is in the same location as fda7.jar.

v hpt.jar is needed in two cases:– You are running Web transactions; or– You used Java wrappers in VisualAge Generator version 4.x or 5.x, are

regenerating the wrappers in EGL 7.x, and wish to avoid updating thenative Java code that invokes the wrappers. In this case, set the builddescriptor option wrapperCompatibility to V4 or V5, as appropriate. Fordetails, see the help topic for that option.

The file hpt.jar is in com.ibm.etools.egl.java.runtime_version\webtrans,where version is the product version.

v hpt.gateway is also needed if you are running Web transactions. The file is inthe same location as hpt.jar.

v vgjwgs.jar is needed if you are running Web transactions that were generatedwith VisualAge Generator 4.x.

3. Copy any platform-specific code to a directory on each deployment system;and set environment variables for each of those systems as appropriate:

For AIX (32- or 64-bit support)The files of interest are in the directory Aix or (for 64-bit support) Aix64.Change the PATH and LIBPATH environment variables so they referencethe directory that contains the platform-specific code you copied from theWeb site.

For HP-UX (32- or 64-bit support)The files of interest are in one of the following four directories:v For ITanium processors:

– HPUXItanium– HPUX64Itanium (for 64-bit support)

v For RISC processors:– HPUXRisc– HPUX64Risc (for 64-bit support)


Change the PATH and LD_LIBRARY_PATH environment variables so theyreference the directory that contains the platform-specific code you copiedfrom the Web site.

For iSeriesThe files of interest are in the directory iSeries. In qshell, change to thedirectory you just uploaded the files to and run the setup.sh script with the″install″ option:

> setup.sh install

In addition, some other environment variables must be set. For informationon how to set these environment variables, run the script with the″envinfo″ option:

> setup.sh envinfo

If for some reason you delete a symlink that is created for you duringinstall, you can recreate it with the ″link″ option:

> setup.sh linkYou also need to set the LIBPATH environment variable.

For LinuxThe files of interest are in the directory Linux. Change the PATH andLD_LIBRARY_PATH environment variables so they reference the directorythat contains the platform-specific code you copied from the Web site.

For Solaris (32- or 64-bit support)The files of interest are in the directory Solaris or (for 64-bit support)Solaris64. Change the PATH and LD_LIBRARY_PATH environmentvariables so they reference the directory that contains the platform-specificcode you copied from the Web site.

For USSThe files of interest are in the directory USS. Change the PATH andLIBPATH environment variables so they reference the directory thatcontains the platform-specific code you copied from the Web site.

For supported Windows platformsThe files of interest are in the directory Win32. Change the PATHenvironment variable so it references the directory that contains theplatform-specific code you copied from the Web site.

Related tasks

“Deploying Java applications outside of JEE” on page 195“Setting up the UNIX curses library for the EGL runtime”Related reference

“wrapperCompatibility” on page 373

Setting up the UNIX curses library for the EGL runtime

Note: Performing the tasks in this topic requires that you have installed the EGLruntime code, as described in the task topic ″Installing the EGL runtimecode for Java.″

When you deploy an EGL text program on AIX,HP-UX, Solaris, or Linux, the EGLruntime tries to use the UNIX curses library. If the environment is not set up forthe UNIX curses library or if that library is not supported, the EGL runtime tries touse the Java Swing technology; and if that technology is also not available, theprogram fails.


The UNIX curses library is required when the user runs an EGL program from aterminal emulator window or a character terminal.

To enable the EGL runtime to access the UNIX curses terminal library onAIX,HP-UX, Solaris, or Linux, you must fulfill several steps in the UNIX shellenvironment. In each of the first two steps, installDir refers to the directory whereyou installed the EGL runtime files:1. Modify the LD_LIBRARY_PATH environment variable to include the shared

object libCursesCanvas7.so, which is provided in the runtime installationlibrary:

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/installDir/bin

2. Set the TERM environment variable to the appropriate terminal setting, as inthe following example:

export TERM=vt100

If terminal exceptions occur, try various terminal settings such as xterm,dtterm, or vt220.

3. Run your EGL Java program from the UNIX shell, as in the following example:java myProgram

Make sure that the CLASSPATH environment variable identifies the directoryin which your program resides.

For additional details on using the Curses library on UNIX, refer to the UNIX manpages.

Setting up the TCP/IP listener for a called non-J2EE application

If you are using TCP/IP to communicate with a called non-J2EE Java program, youmust configure a standalone Java program called TcpipListener for that program.Specifically, you must follow these steps:v Make sure that the classpath used when running TcpipListener contains fda7.jar,

and the directories or archives that contain the called programs; andv Set the tcpiplistener.port to the port number where TcpipListener receives data.

You can start the standalone TCP/IP listener in either of two ways:v To start the listener from the command line, run the program as follows:

java com.ibm.javart.calls.listener.TcpipListener propertiesFile

propertiesFileThe fully qualified path to the properties file used by the TCP/IP listener. Ifyou do not specify a properties file, the listener attempts to open thefollowing file in the current directory:

tcpiplistener.properties

v To start the listener from the workbench, use the launch configuration for a Javaapplication. In this case, you can specify the name of the properties file in theprogram arguments of the launch configuration. Alternatively, if you are usingthe filetcpiplistener.properties as a default, that file should not be in a folder,but should be directly under the project that you specified when you created thelaunch configuration.Related tasks

“Providing access to non-EGL JAR files” on page 187“Setting up a TCP/IP listener for J2EE called applications” on page 193


Generating Java wrappers

The EGL Java wrapper is a set of classes that lets you invoke an EGL programfrom non-EGL Java code; for example, from an action class in a Struts- orJSF-based J2EE web application or from a non-J2EE Java program. You cangenerate Java wrapper classes when you generate the related program.

A Java wrapper consists of a set of classes. Those classes act as an interfacebetween a servlet or a non-EGL generated Java program, on the one hand, and agenerated program or EJB session bean, on the other.

You generate the Java wrapper classes if you use a build descriptor that has thesecharacteristics:v The enableJavaWrapperGen build descriptor option is set to yes or only.v The linkage build descriptor option references a linkage options part that

includes a callLink element to guide the call from wrapper to program.v One of two statements apply:

– The call from wrapper to program is by way of an EJB session bean (in whichcase the type property of the callLink element is set to ejbCall).

– The call from wrapper to program is remote (in which case the callLinkelement, type property is set to remoteCall); also, the callLink element,javaWrapper property is set to yes.

For further details on using the classes, see Java wrapper classes. For details on theclass names, see Generated output (reference).

To use a Java wrapper perform the following steps:1. Generate Java wrapper classes, which are specific to a generated program2. Incorporate those wrapper classes into the non-generated Java code3. 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 Javav The primitive-type formats required when passing data to and from the

EGL-generated programRelated concepts

“Generation output and associated files” on page 91“Overview of Java output” on page 172“Generating Java wrappers”Related reference

“Java wrapper classes”“Output of Java wrapper generation” on page 208

Java wrapper classes

When you request that a program part be generated as a Java wrapper, EGLproduces a wrapper class for each of the following:v The generated programv Each record or form that is declared as a parameter in that programv Each record or dynamic array that is directly contained by a flexible record


v Each dynamic array that is declared as a parameter; and if the dynamic array isarray of structured records, the class for the dynamic array class is in addition tothe class for the structured record itself

v Each structure field that has these characteristics:– Is in one of the structured records or forms for which a wrapper class is

generated– Has at least one subordinate structure field; in other words, is substructured– Is an array; in this case, a substructured arrayAn example of a structured record part with a substructured array is as follows:

Record myPart type basicRecord10 MyTopStructure CHAR(20)[5];

20 MyStructureField01 CHAR(10);20 MyStructureField02 CHAR(10);

end

Later descriptions refer to the wrapper classes for a given program as the programwrapper class, the parameter wrapper classes, the dynamic array wrapper classes, and thesubstructured-field-array wrapper classes.

EGL generates a BeanInfo class for each parameter wrapper class, dynamic arraywrapper class, or substructured-field-array wrapper class. The BeanInfo classallows the related wrapper class to be used as a Java-compliant Java bean. Youprobably will not interact with the BeanInfo class.

When you generate a wrapper, the parameter list of the called program cannotinclude parameters of type BLOB, CLOB, Dictionary, ArrayDictionary, ornon-structured record.

Overview of how to use the wrapper classesTo use the wrapper classes to communicate with a program generated withVisualAge Generator or EGL, do as follows in the native Java program:v Instantiate a class (a subclass of PowerServer) to provide middleware services

such as converting data between native Java code and a generated program:import com.ibm.javart.JavartException;import com.ibm.javart.calls.*;

public class MyNativeClass{

/* declare a variable for middleware */PowerServer powerServer = null;PowerServer = new PowerServerImpl();

}

v Instantiate a program wrapper class to do as follows:– Allocate data structures, including dynamic arrays, if any– Provide access to methods that in turn access the generated programThe call to the constructor includes the middleware object:

myProgram = new MyprogramWrapper(powerServer);

v Declare variables that are based on the parameter wrapper classes:Mypart myParm = myProgram.getMyParm();Mypart2 myParm2 = myProgram.getMyParm2();

If your program has parameters that are dynamic arrays, declare additionalvariables that are each based on a dynamic array wrapper class:

myRecArrayVar myParm3 = myProgram.getMyParm3();


For details on interacting with dynamic arrays, see “Dynamic array wrapperclasses” on page 205.

v In most cases (as in the previous step), use the parameter variables to referenceand change memory that was allocated in the program wrapper object

v Set a userid and password, but only in these cases:– The Java wrapper accesses an iSeries-based program by way of the iSeries

Toolbox for Java; or– The generated program runs on a CICS for z/OS region that authenticates

remote access.The userid and password are not used for database access.You set and review the userid and password by using the callOptions variable ofthe program object, as in this example:

myProgram.callOptions.setUserID("myID");myProgram.callOptions.setPassword("myWord");myUserID = myProgram.callOptions.getUserID();myPassword = myProgram.callOptions.getPassword();

v Access the generated program, in most cases by invoking the execute method ofthe program wrapper object:

myProgram.execute();

v Use the middleware object to establish database transaction control, but only inthe following situation:– The program wrapper object either is accessing a generated program on CICS

for z/OS or is accessing an iSeries-based COBOL program by way of the IBMToolbox for Java. In the latter case, the value of remoteComType for the callis JAVA400.

– In the linkage options part used to generate the wrapper classes, youspecified that the database unit of work is under client (in this case, wrapper)control; for details, see the reference to luwControl in “callLink element” onpage 380.

If the database unit of work is under client control, processing includes use ofcommit and rollback methods of the middleware object:powerServer.commit();powerServer.rollBack();

v Close the middleware object and allow for garbage collection:if ( powerServer != null ){

try{

powerServer.close();powerServer = null;

}catch ( JavartException error ){

System.out.println( "Error closing middleware"+ error.getMessage() );

System.exit( 8 );}

}

The program wrapper classThe program wrapper class includes a private instance variable for each parameterin the generated program. If the parameter is a record or form, the variable refersto an instance of the related parameter wrapper class. If the parameter is based ona DataItem part, the variable has a primitive Java type.


A table at the end of this help page describes the conversions between EGL andJava types.

A program wrapper object includes the following public methods:v get and set methods for each parameter, where the format of the name is as

follows:purposeParmname()

purposeThe word get or set

ParmnameName of the data item, record, or form; the first letter is upper case, andaspects of the other letters are determined by the naming conventiondescribed in “Naming conventions for Java wrapper classes” on page 206

v An execute method for calling the program; you use this method if the data thatwill be passed as arguments on the call is in the memory allocated for theprogram wrapper object

Instead of assigning values to the instance variables, you can do as follows:v Allocate memory for parameter wrapper objects, dynamic array wrapper objects,

and primitive typesv Assign values to the memory you allocatedv Pass those values to the program by invoking the call method of the program

wrapper object rather than the execute method

The program wrapper object also includes the callOptions variable, which has thefollowing purposes:v If you generated the Java wrapper so that linkage options for the call are set at

generation time, the callOptions variable contains the linkage information. Fordetails on when the linkage options are set, see remoteBind in “callLinkelement” on page 380.

v If you generated the Java wrapper so that linkage options for the call are set atrun time, the callOptions variable contains the name of the linkage properties file.The file name is LO.properties, where LO is the name of the linkage options partused for generation.

v In either case, the callOptions variable provides the following methods for settingor getting a userid and password:

setPassword(passWord)setUserid(userid)getPassword()getUserid()

The userid and password are used when you set the remoteComType propertyof the callLink element to one of the following values:– CICSECI– CICSJ2C– JAVA400

Password information can also be stored in the csouidpwd.properties file. See“csouidpwd.properties file for remote calls” on page 388.

Finally, consider the following situation: your native Java code requires notificationwhen a change is made to a parameter of primitive type. To make such anotification possible, the native code registers as a listener by invoking theaddPropertyChangeListener method of the program wrapper object. In this case,


either of the following situations triggers the PropertyChange event that causes thenative code to receive notification at run time:v Your native code invokes a set method on a parameter of primitive typev The generated program returns changed data to a parameter of primitive type

The PropertyChange event is described in the JavaBean specification of SunMicrosystems, Inc.

The set of parameter wrapper classesA parameter wrapper class is produced for each record that is declared as aparameter in the generated program. In the usual case, you use a parameterwrapper class only to declare a variable that references the parameter, as in thefollowing example:

Mypart myRecWrapperObject = myProgram.getMyrecord();

In this case, you are using the memory allocated by the program wrapper object.

You also can use the parameter wrapper class to declare memory, as is necessary ifyou invoke the call method (rather than the execute method) of the programobject.

The parameter wrapper class includes a set of private instance variables, asfollows:v One variable of a Java primitive type for each of the parameter’s low-level

structure fields, but only for a structure field that is neither an array nor withina substructured array

v One array of a Java primitive type for each EGL structure field that is an arrayand is not substructured

v An object of an inner, array class for each substructured array that is not itselfwithin a substructured array; the inner class can have nested inner classes torepresent subordinate substructured arrays

The parameter wrapper class includes several public methods:v A set of get and set methods allows you to get and set each instance variable.

The format of each method name is as follows:purposesiName()

purposeThe word get or set.

siNameName of the structure field. The first letter is upper case, and aspects of theother letters are determined by the naming convention described in“Naming conventions for Java wrapper classes” on page 206.

Note: Structure fields that you declared as fillers are included in theprogram call; but the array wrapper classes do not include public getor set methods for those structure fields.

v The method equals allow you to determine whether the values stored in anotherobject of the same class are identical to the values stored in the parameterwrapper object. The method returns true only if the classes and values areidentical.

v The method addPropertyChangeListener is invoked if your program requiresnotification of a change in a variable of a Java primitive type.


v A second set of get and set methods allow you to get and set the null indicatorsfor each structure field in an SQL record parameter. The format of each of thesemethod names is as follows:

purposesiNameNullIndicator()

purposeThe word get or set.

siNameName of the structure field. The first letter is upper case, and aspects of theother letters are determined by the naming convention described in“Naming conventions for Java wrapper classes” on page 206.

The set of substructured-field-array wrapper classesA substructured-field-array wrapper class is an inner class of a parameter class andrepresents a substructured array in the related parameter. Thesubstructured-field-array wrapper class includes a set of private instance variablesthat refer to the structure fields at and below the array itself:v One variable of a Java primitive type for each of the array’s low-level structure

fields, but only for a structure field that is neither an array nor within asubstructured array

v One array of a Java primitive type for each EGL structure field that is an arrayand is not substructured

v An object of an inner, substructured-field-array wrapper class for eachsubstructured array that is not itself within a substructured array; the inner classcan have nested inner classes to represent subordinate substructured arrays

The substructured-field-array wrapper class includes the following methods:v A set of get and set methods for each instance variable

Note: Structure field that you declared as nameless fillers are used in theprogram call; but the substructured-field-array wrapper classes do notinclude public get or set methods for those structure fields.

v The method equals allows you to determine whether the values stored inanother object of the same class are identical to the values stored in thesubstructured-field-array wrapper object. The method returns true only if theclasses and values are identical.

v The method addPropertyChangeListener, for use if your program requiresnotification of a change in a variable of a Java primitive type

In most cases, the name of the top-most substructured-field-array wrapper class ina parameter wrapper class is of the following form:

ParameterClassname.ArrayClassName

Consider the following record, for example:Record CompanyPart type basicRecord10 Departments CHAR(20)[5];

20 CountryCode CHAR(10);20 FunctionCode CHAR(10)[3];

30 FunctionCategory CHAR(4);30 FunctionDetail CHAR(6);

end

If the parameter Company is based on CompanyPart, you use the stringCompanyPart.Departments as the name of the inner class.


An inner class of an inner class extends use of a dotted syntax. In this example,you use the symbol CompanyPart.Departments.Functioncode as the name of theinner class of Departments.

For additional details on how the substructured-field-array wrapper classes arenamed, see Output of Java wrapper generation.

Dynamic array wrapper classesA dynamic array wrapper class is produced for each dynamic array that isdeclared as a parameter in the generated program. Consider the following EGLprogram signature:

Program myProgram(intParms int[], recParms MyRec[])

The name of the dynamic array wrapper classes are IntParmsArray andMyRecArray.

You use a dynamic array wrapper class to declare a variable that references thedynamic array, as in the following examples:

IntParmsArray myIntArrayVar = myProgram.getIntParms();MyRecArray myRecArrayVar = myProgram.getRecParms();

After declaring the variables for each dynamic array, you might add elements:// adding to an array of Java primitives// is a one-step processmyIntArrayVar.add(new Integer(5));

// adding to an array of records or forms// requires multiple steps; in this case,// begin by allocating a new record objectMyRec myLocalRec = (MyRec)myRecArrayVar.makeNewElement();

// the steps to assign values are not shown// in this example; but after you assign values,// add the record to the arraymyRecArrayVar.add(myLocalRec);

// next, run the programmyProgram.execute();

// when the program returns, you can determine// the number of elements in the arrayint myIntArrayVarSize = myIntArrayVar.size();

// get the first element of the integer array// and cast it to an Integer objectInteger firstIntElement = (Integer)myIntArrayVar.get(0);

// get the second element of the record array// and cast it to a MyRec objectMyRec secondRecElement = (MyRec)myRecArrayVar.get(1);

As suggested by that example, EGL provides several methods for manipulating thevariables that you declared.

Method of the dynamic arrayclass

Purpose

add(int, Object) To insert an object at the position specified by int and toshift the current and subsequent elements to the right.

add(Object) To append an object to the end of the dynamic array.


Method of the dynamic arrayclass

Purpose

addAll(ArrayList) To append an ArrayList to the end of the dynamic array.

get() To retrieve the ArrayList object that contains all elementsin the array

get(int) To retrieve the element that is in the position specified byint

makeNewElement() To allocate a new element of the array-specific type and toretrieve that element, without adding that element to thedynamic array.

maxSize() To retrieve an integer that indicates the maximum (butnot actual) number of elements in the dynamic array

remove(int) To remove the element that is in the position specified byint

set(ArrayList) To use the specified ArrayList as a replacement for thedynamic array

set(int, Object) To use the specified object as a replacement for theelement that is in the position specified by int

size() To retrieve the number of elements that are in thedynamic array

Exceptions occur in the following cases, among others:v If you specify an invalid index in the get or set methodv If you try to add (or set) an element that is of a class incompatible with the class

of each element in the arrayv If you try to add elements to a dynamic array when the maximum size of the

array cannot support the increase; and if the method addAll fails for this reason,the method adds no elements

Naming conventions for Java wrapper classesEGL creates a name in accordance with these rules:v If the name is all upper case, lower case all letters.v If the name is a keyword, precede it with an underlinev If a hyphen or underline is in the name, remove that character and upper case

the next letterv If a dollar sign ($), at sign (@), or pound sign (#) is in the name, replace each of

those characters with a double underscore (__) and precede the name with anunderscore (_).

v If the name is used as a class name, upper case the first letter.

The following rules apply to dynamic array wrapper classes:v In most cases, the name of a class is based on the name of the part declaration

(data item, form, or record) that is the basis of each element in the array. Forexample, if a record part is called MyRec and the array declaration is recParmsmyRec[], the related dynamic array wrapper class is called MyRecArray.

v If the array is based on a declaration that has no related part declaration, thename of the dynamic array class is based on the array name. For example, if thearray declaration is intParms int[], the related dynamic array wrapper class iscalled IntParmsArray.


Data type cross-referenceThe next table indicates the relationship of EGL primitive types in the generatedprogram and the Java data types in the generated wrapper.

EGL primitivetype

Length inchars ordigits

Length inbytes Decimals

Java datatype

Maximumprecision inJava

CHAR 1-32767 2-32766 NA String NA

DBCHAR 1-16383 1-32767 NA String NA

MBCHAR 1-32767 1-32767 NA String NA

STRING 1-16383 2-32766 NA String NA

UNICODE 1-16383 2-32766 NA String NA

HEX 2-75534 1-32767 NA byte[] NA

BIN, SMALLINT 4 2 0 short 4

BIN, INT 9 4 0 int 9

BIN, BIGINT 18 8 0 long 18

BIN 4 2 >0 float 4

BIN 9 4 >0 double 15

BIN 18 8 >0 double 15

DECIMAL, PACF,MONEY

1-3 1-2 0 short 4

DECIMAL, PACF,MONEY

4-9 3-5 0 int 9

DECIMAL, PACF,MONEY

10-18 6-10 0 long 18

DECIMAL, PACF,MONEY

1-5 1-3 >0 float 6

DECIMAL, PACF,MONEY

7-18 4-10 >0 double 15

NUM, NUMC 1-4 1-4 0 short 4

NUM, NUMC 5-9 5-9 0 int 9

NUM, NUMC 10-18 10-18 0 long 18

NUM, NUMC 1-6 1-6 >0 float 6

NUM, NUMC 7-18 7-18 >0 double 15

FLOAT 18 8 >0 double 15

SMALLFLOAT 9 4 >0 float 6

DATE 8 8 0 java.sql.Date NA

TIME 6 6 0 java.sql.Time NA

TIMESTAMP 1-20 1-20 0 java.sql.Timestamp

NA

INTERVAL(month-span)

1-21 2-22 0 String NA

INTERVAL(second-span)

1-21 2-22 0 String NA

BOOLEAN 1 1 NA Boolean NA

Related concepts


“Generating Java wrappers” on page 199“Linkage properties file” on page 182Related reference

“callLink element” on page 380“How Java wrapper names are aliased” on page 98“Output of Java wrapper generation”“remoteBind in callLink element” on page 400

Output of Java wrapper generation

The output of Java wrapper generation is as follows:v A build plan, if the genProject build descriptor option is omittedv JavaBeans for wrapping calls to a Java server program (see Java wrapper)

v EJB session beans under certain circumstances; for details, see the explanation ofthe callLink element in Linkage options part

v A results file, if genProject is omitted

You can use the generated beans to wrap calls to server programs from non-EGLJava classes such as servlets, EJBs, or Java applications. The following types ofclasses are generated:v Beans for serversv Beans for record parametersv Beans for record array rows

The following table shows the names of the various types of generated Javawrapper parts:

Table 12. Names of generated Java wrapper parts

Part type and name What is generated

Program named P A class named PWrapper in PWrapper.java

Record named R used as aparameter

A class named R in R.java

Substructured area S in record Rused as a parameter

A class named R.S in R.java

Linkage options part named L Linkage properties file named L.properties

1. For the indicated part types, it is possible that two or more parts may existwith the same name. In that event the name of the second one will have anadditional suffix, $v2. The name of the third will have a $v3 suffix, the fourthwill have $v4, etc.

When you request that a program part be generated as a Java wrapper, EGLproduces Java class for each of the following executables:v The program partv Each record that is declared as a program parameterv A session bean, if you specify a linkage options part and a the callLink element

for the generated program has a link type of ejbCall

In addition, the class generated for each record includes an inner class (or a classwithin an inner class) for each structure field that has these characteristics:


v Is in the internal structure of one of those recordsv Has at least one subordinate structure field; in other words, is substructuredv Is an array; in this case, a substructured array

Each generated class is stored in a file. The EGL generator creates names used inJava wrappers as follows:v The name is converted to lowercase.v Each hyphen or minus (-) or underscore (_) is deleted. A character that follows a

hyphen or underscore is changed to uppercase.v When the name is used as a class name or within a method name, the first

character is translated back to uppercase.

If one of the parameters to the program is a record, EGL generates a wrapper classfor that variable as well. If program Prog has a record parameter with a typeDefnamed Rec, the wrapper class for the parameter will be called Rec. If the typeDefof a parameter has the same name as the program, the wrapper class for theparameter will have a ″Record″ suffix.

The generator also produces a wrapper if a record parameter has an array fieldand the field has other field under it. This substructured array wrapper becomesan inner class of the record wrapper. In most cases, a substructured array fieldcalled AField in Rec will be wrapped by a class called Rec.AField. The record maycontain two substructured array fields with the same name, in which case the fieldwrappers are named by using the qualified names of the fields. If the qualifiedname of the first AField is Top1.AField and the qualified name of the second isTop2.Middle2.AField, the classes will be named Rec.Top1$_aField andRec.Top2$_middle2$_aField. If the name of a substructured array is the same as thename of the program, the wrapper class for substructured array will have aStructure suffix.

Methods to set and get the value of low-level fields are generated into each recordwrapper and substructured array wrapper. If two low-level fields in the record orsubstructured array have the same name, the generator uses the qualified-namescheme described in the previous paragraph.

Additional methods are generated into wrappers for SQL record. For each field inthe record, the generator creates methods to get and set its null indicator value andmethods to get and set its SQL length indicator.

You can use the Javadoc tool to build a classname.html file once the the class hasbeen compiled. The HTML file describes the public interfaces for the class. If youuse HTML files created by Javadoc, be sure that it is an EGL Java wrapper. HTMLfiles generated from a VisualAge Generator Java wrapper are different from thosegenerated from an EGL Java wrapper.

ExampleAn example of a record part with a substructured array is as follows:

Record myRecord type basicRecord10 MyTopStructure[3];

15 MyStructureField01 CHAR(3);15 MyStructureField02 CHAR(3);

end

In relation to the program part, the output file is named as follows:aliasWrapper.java


wherealias

Is the alias name, if any, that is specified in the program part. If the externalname is not specified, the name of the program part is used.

In relation to each record declared as a program parameter, the output file isnamed as follows:recordName.java

whererecordName

Is the name of the record part

In relation to a substructured array, the name and position of the inner classdepends on whether the array name is unique in the record:v If the array name is unique in the record, the inner class is within the record

class and is named as follows:recordName.siName

whererecordName

Is the name of the record partsiName

Is the name of the arrayv If the array name is not unique in the record, the name of the inner class is

based on the fully qualified name of the array, with one qualifier separated fromthe next by a combination of dollar sign ($) and underscore (_). For example, ifthe array is at the third level of the record, the generated class is an inner classof the record class and is named as follows:Topname$_Secondname$_Siname

whereTopname

Is the name of the top-level structure fieldSecondname

Is the name of the second-level structure fieldSiname

Is the name of the substructured-array fieldIf another, same-named array is immediately subordinate to the highest level ofthe record, the inner class is also within the record class and is named asfollows:Topname$_Siname

whereTopname

Is the name of the highest-level structure fieldSiname

Is the name of the substructured-array fieldFinally, consider the following case: a substructured array has a name that is notunique in the record, and the array is subordinate to another substructured arraywhose name is not unique in the record. The class for the subordinate array isgenerated as an inner class of an inner class.


When you generate a Java wrapper, you also generate a Java properties file and alinkage properties file if you request that linkage options be set at run time.

Related concepts

“Build plan” on page 103“Enterprise JavaBean (EJB) session bean” on page 188“Generating Java wrappers” on page 199“Linkage options part” on page 61“Linkage properties file” on page 182“Results file” on page 281Related reference

“callLink element” on page 380“Java wrapper classes” on page 199



Overview of EGL Rich UI generation and deployment

This topic reviews the ideas behind generation and deployment and describes thesteps necessary to prepare for the deployment task.

Generating a handler or library in Rich UI

When you generate an EGL Rich UI handler or library, the output is a JavaScriptfile with no embedding HTML. Two generation modes are available, as specified inthe preferences for Rich UI:

Development modeThe output has information required by the EGL debugger and the EGL RichUI editor.

Deployment modeThe output lacks the extra information but is smaller and more efficient.Deployment mode is appropriate immediately before you add fully tested codeto a production environment.

The Workbench automatically generates individual Rich UI handlers and libraries.You can also generate an EGL file as follows:1. In the Project Explorer, right click on the EGL file or on an icon that represents

a higher level of organization that includes the file: a package, folder, or project.A dropdown menu is displayed.

2. Click Generate.

You must generate a handler part before you can use it as the basis of anembedded handler.

Generation is guided by the presence of a build descriptor in your project. TheWorkbench provides a default build descriptor, which you can customize. Fordetails on options and values, see Build descriptor options in Rich UI,

You can generate JavaScript only in the Workbench, not in the EGL SDK.

Deploying a Rich UI application

In relation to EGL Rich UI, the word deploy refers primarily to the creation of anHTML file that embeds previously generated JavaScript output. The Rich UIdeployment step is available only in the Workbench and precedes adding theHTML file to a target environment such as WebSphere Application Server.

Rich UI supports the following target environments:v WebSphere Application Serverv Apache Tomcatv Local directory

If you target WebSphere Application Server:v The Rich UI deployment wizard writes the generated HTML file and all

supporting files (such as graphics and properties files) to the WebContent folderof a Web project. The supporting files include graphics and properties files, as


well as the EGL Rich UI Proxy. The files in the WebContent folder can beincorporated into a WAR file for installation on a Web server.For details on the EGL Rich UI Proxy, see Accessing a service in EGL Rich UI.

v The wizard also creates an Enterprise Application project, which is installable asan Enterprise Archive (EAR) file. The EAR file acts as a container for the WARfile.

v The HTML file is stored in a WebContent subfolder that corresponds to thename of the package where the Rich UI handler is stored. If the package namein the Rich UI project has multiple qualifiers (for example,com.example.myPackage), the subfolder is a hierarchy of folders (for example,/com/example/myPackage).

If you target Apache Tomcat:v The Rich UI deployment wizard writes the generated HTML file and all

supporting files (such as graphics and properties files) to the WebContent folderof a Web project. The supporting files include graphics and properties files, aswell as the EGL Rich UI Proxy. The files in the WebContent folder can beincorporated into a WAR file for installation on a Web server.For details on the EGL Rich UI Proxy, see Accessing a service in Rich UI.

v An Enterprise Archive (EAR) file is not provided for Apache Tomcat becausethat Web server does not support the use of EAR files.

v The HTML file is stored in a WebContent subfolder that corresponds to thename of the package where the Rich UI handler is stored. If the package namein the Rich UI project has multiple qualifiers (for example,com.example.myPackage), the subfolder is a hierarchy of folders (for example,/com/example/myPackage).

If you target a local directory:v The Rich UI deployment wizard writes the generated HTML file and all

supporting WebContent files to a directory.v The likely production environment—an HTTP server such as the Apache HTTP

server—does not support EAR or WAR files.v EGL Rich UI does not provide a proxy and does not support service access.v The HTML file is stored in a directory subfolder that corresponds to the name of

the package where the Rich UI handler is stored. If the package name in theRich UI project has multiple qualifiers (for example, com.example.myPackage), thesubfolder is a hierarchy of folders (for example, /com/example/myPackage).

In each case, the Rich UI deployment wizard supports globalization, as noted inUse of properties files for displayable text. When you specify a name for the HTMLfile, the deployment wizard adds locale detail to the name, along with the fileextension .html. For example, if you specify myFile.htm and request an output thatuses runtime messages in English, the wizard creates the file namedmyFile.htm_en_US.html.

You can deploy a Rich UI application by running the Rich UI Deployment wizardin the Workbench, but cannot deploy an application in the EGL SDK.

Preparing to use the Rich UI deployment wizard

To prepare to use the Rich UI deployment wizard, do as follows:1. Click Window -> Preferences. The Preferences dialog is displayed.2. Click Rich UI


3. Set the dropdown list to the value of interest:v Development, to include the extra information required by the EGL

debugger and the EGL Rich UI editor; orv Deployment, to exclude that information

4. Click OK. A message is displayed to indicate that a regeneration is required.5. Click OK. The effect is that all the generated JavaScript in your workspace will

be available for the same purpose, whether for use in the Workbench(Development mode) or for distribution (Deployment mode).Related concepts

Overview of service accessOverview of EGL Rich UISecuring a Rich UI applicationRelated tasks

“Deploying a Rich UI application to WebSphere Application Server”“Deploying a Rich UI application to a local directory” on page 218“Deploying a Rich UI application to Apache Tomcat” on page 217Related reference

Use of properties files for displayable text“Build descriptor options used with JavaScript” on page 220This topic lists the build descriptor options used with JavaScript, which is thegenerated language for EGL Rich UI.

Deploying a Rich UI application to WebSphere Application ServerThis topic describes how to prepare to deploy a Rich UI application, when thedeployment target is WebSphere Application Server.

Setting the deployment target

To begin the process:1. In the Project Explorer, right click on the EGL file that contains the Rich UI

handler, or right click on a higher level of organization that includes the file:the package, folder, or project. A dropdown menu is displayed.

2. Click Deploy Rich UI application. The first wizard dialog is displayed.3. If you originally selected a higher level of organization such as a project, select

an Rich UI handler.4. Select the deployment target WebSphere Application Server.5. If you wish to retain the details you will specify. select the Save deployment

configuration checkbox. If you save a deployment configuration, you can usethe Redeploy Rich UI application option later, to quickly deploy the same RichUI application in a way that reflects the most recently saved configuration.

6. Click Next. The Deployment Details dialog is displayed.

Setting deployment details

To set the deployment details:1. Specify the name of the HTML file you are deploying.

Overview of EGL Rich UI generation and deployment 215

The deployment wizard adds locale detail to the name, along with the fileextension .html. For example, if you specify myFile.htm and, as described later,you request an output for the English locale, the wizard creates the file namedmyFile.htm_en_US.html.

2. Specify one of the following options:v An existing Web project that is configured for use with WebSphere

Application Server; orv A new Web project. In this case, you specify the project name and click the

New button to display the New Server Runtime Environment dialog, whereyou expand IBM and select the version of WebSphere Application Serverthat is used to configure the new project. If you need to identify a previouslyunspecified installation of WebSphere Application Server, click Create a newlocal server and, at the next page, use the Browse mechanism to select thedirectory in which WebSphere Application Server is installed.

3. Under Globalization settings, select all the locales that you are supporting. Youcan select from the list of generally available locales. In addition, you canspecify new locales. To understand the distinction, see Use of properties files fordisplayable text.To select a generally available locale, select the locale in the left box and clickthe double right arrows (>>). To remove a generally available locale that waspreviously chosen, select the locale in the right box and click the double leftarrows (<<)To select a new locale, click the New Locale button. The Create a new localedialog is displayed. There, do as follows:a. Specify a locale code and description, as well as a locale for runtime

messages other than those that can be included in a properties file that youprovide.

b. Click OK. The new entry is added to the Rich UI locale list in theWorkbench preferences. For details, see Setting preferences for Rich UI.

4. Click Next to specify the subset of workspace files that you wish to include inyour output. The Additional Artifacts dialog is displayed.

Selecting additional artifacts

Your last tasks in the Rich UI deployment wizard are as follows:1. To select files or groups of files that are to be made available to the user, select

check boxes. To deselect files or groups of files that are not to be madeavailable to the user, clear check boxes. Expand or contract projects, folders,and packages, as needed to access file entries.

2. Click Finish.Related concepts

Overview of service access“Overview of EGL Rich UI generation and deployment” on page 213Overview of EGL Rich UISecuring a Rich UI applicationRelated tasks

“Deploying a Rich UI application to Apache Tomcat” on page 217“Deploying a Rich UI application to a local directory” on page 218Related reference

Use of properties files for displayable text


“Build descriptor options used with JavaScript” on page 220This topic lists the build descriptor options used with JavaScript, which is thegenerated language for EGL Rich UI.

Deploying a Rich UI application to Apache TomcatThis topic describes how to prepare to deploy a Rich UI application, when thedeployment target is Apache Tomcat.





a Rich UI handler.4. Select the deployment target Apache Tomcat.5. If you wish to retain the details you will specify. select the Save deployment




To set the deployment details:1. Specify the name of the HTML file you are deploying.


2. Specify an existing Web project that is configured for use with Apache Tomcat;or create a new Web project.If you are creating a new Web project, do as follows:a. Specify the project name.b. If you wish to select a Tomcat server that you already defined in the

Workbench, choose from a dropdown list and continue working at step 3. Ifyou wish to define a new Tomcat server, click the New button to displaythe New Server Runtime Environment dialog.

c. Expand Apache and select the Apache Tomcat version that is used toconfigure the new project.

d. Click Next. The Tomcat Server dialog is displayed.e. To select a directory where the specified Apache Tomcat version is already

installed, specify the directory name or use the Browse mechanism.Alternatively, to install a new version from the Apache Web site, do asfollows: (i) click Download and Install, displaying the Feature Licensedialog; (ii) select I accept the terms of the licensing agreement; (iii) clickFinish, displaying the Browse for folder dialog; (iv) select a folder in whichto install the new version; and (v) click OK.


f. Specify the Java Runtime edition (JRE) to use with Apache Tomcat, either byselecting a specific JRE or by selecting the Workbench default. To change theWorkbench default, click Installed JRE and, at the Installed JREs dialog,select, add, or search for a different JRE and click OK.

g. Click Finish.3. Under Globalization settings, select all the locales that you are supporting. You

can select from the list of generally available locales. In addition, you canspecify new locales. To understand the distinction, see Use of properties files fordisplayable text.To select a generally available locale, select the locale in the left box and clickthe double right arrows (>>). To remove a generally available locale that waspreviously chosen, select the locale in the right box and click the double leftarrows (<<)To specify a new locale, click the New Locale button. The Create a new localedialog is displayed. There, do as follows:a. Specify a locale code and description, as well as a locale for EGL runtime

messages, which are messages other than those included in a properties filethat you provide.




Your last tasks in the Rich UI deployment wizard are as follows:1. To select files or groups of files that are to be made available to the user, select

check boxes. To deselect files or groups of files that are not to be madeavailable to the user, clear check boxes. Expand or contract projects, folders,and packages, as needed to access file entries.



“Deploying a Rich UI application to a local directory”“Deploying a Rich UI application to Apache Tomcat” on page 217Related reference

Use of properties files for displayable text“Build descriptor options used with JavaScript” on page 220This topic lists the build descriptor options used with JavaScript, which is thegenerated language for EGL Rich UI.

Deploying a Rich UI application to a local directoryThis topic describes how to prepare to deploy a Rich UI application, when thedeployment target is a local directory, as is especially useful when you intend toinstall the application on a simple HTTP server.






an Rich UI handler.4. Select the deployment target Local Directory.5. If you wish to retain the details you will specify. select the Save deployment




To set the deployment details:1. Specify a directory name in Deployment Directory or use the Browse

mechanism.2. Specify the name of the HTML file you are deploying.


3. Specify the application context root, which is the second qualifier used in theWeb address used to access the Rich UI application. For example, if the domainname is www.example.com and the application context root is myApplication, theWeb address is as follows:www.example.com/myApplication

4. Under Globalization settings, select all the locales that you are supporting. Youcan select from the list of generally available locales. In addition, you canspecify new locales. To understand the distinction, see Use of properties files fordisplayable text.To select a generally available locale, select the locale in the left box and clickthe double right arrows (>>). To remove a generally available locale that waspreviously chosen, select the locale in the right box and click the double leftarrows (<<)To specify a new locale, click the New Locale button. The Create a new localedialog is displayed. There, do as follows:a. Specify a locale code and description, as well as a locale for EGL runtime

messages, which are messages other than those included in a properties filethat you provide.




Your last tasks in the Rich UI deployment wizard are as follows:


1. To select files or groups of files that are to be made available to the user, selectcheck boxes. To deselect files or groups of files that are not to be madeavailable to the user, clear check boxes. Expand or contract projects, folders,and packages, as needed to access file entries.



“Deploying a Rich UI application to WebSphere Application Server” on page215“Deploying a Rich UI application to Apache Tomcat” on page 217Related reference

Use of properties files for displayable text“Build descriptor options used with JavaScript”This topic lists the build descriptor options used with JavaScript, which is thegenerated language for EGL Rich UI.

Build descriptor options used with JavaScriptThis topic lists the build descriptor options used with JavaScript, which is thegenerated language for EGL Rich UI.



defaultDateFormat MM/dd/yyyy Controls the initial runtime value ofthe strLib.defaultDateFormatsystem variable.

defaultServiceTimeout 100,000 Specifies the maximum validnumber of milliseconds that elapsebetween the following events: whenthe EGL Rich UI Proxy (on the Webserver) invokes a service and whenthe Proxy receives a response.

defaultSessionCookieID JSESSIONID Identifies the session cookieprovided to the EGL Rich UI Proxyfrom a service.

defaultTimeFormat HH:mm:ss Controls the initial runtime value ofthe strLib.defaultTimeFormatsystem variable.

defaultTimeStampFormat An emptystring

Controls the initial runtime value ofthestrLib.defaultTimeStampFormatsystem variable.




deploymentDescriptor No defaultvalue


eliminateSystemDependentCode YES Indicates whether, at generationtime, EGL ignores code that willnever run in the target system.

nextBuildDescriptor No defaultvalue


system No defaultvalue

Specifies the target runtimeenvironment of the generated code.For Rich UI, JavaScript is specifiedautomatically in the Workbench.

Related concepts


“Adding a build descriptor part to an EGL build file” on page 38“Editing build descriptor options in the build descriptor part” on page 58Related reference

“Build descriptor options” on page 41“Build descriptor options used with Java” on page 144“Build descriptor options used with COBOL” on page 234

defaultDateFormat (build descriptor option)

The defaultDateFormat build descriptor option controls the initial runtime value ofthe strLib.defaultDateFormat system variable, which contains one of the masksthat can be used to create the string returned by the strLib.formatDate systemfunction. Other details depend on the target language:v When you are generating a COBOL program, if you do not specify the

defaultDateFormat build descriptor option, the default value for thestrLib.defaultDateFormat system variable is set by the ″Long Gregorian dateformat″ specified in the language-dependent options module specified for yourruntime installation. For z/OS, refer to the program directory for your runtimeproduct for details.

v When you are generating Java code, the defaultDateFormat build descriptoroption specifies the generated value for the vgj.default.dateFormat Java runtimeproperty (if you have set the genProperties build descriptor option to GLOBALor PROGRAM). That property then sets the initial runtime value of thestrLib.defaultDateFormat system variable.

v When you are generating JavaScript code, the default value of thedefaultDateFormat build descriptor option is MM/dd/yyyy.


For further details on system variables and functions, see the EGL LanguageReference.

Related concepts

“Build descriptor part” on page 33“Overview of Java runtime properties” on page 153Related reference

“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“Build descriptor options used with Java” on page 144“Build descriptor options used with JavaScript” on page 220This topic lists the build descriptor options used with JavaScript, which is thegenerated language for EGL Rich UI.“genProperties” on page 326Rich UI date and time support

defaultServiceTimeout

The defaultServiceTimeout build descriptor option specifies the maximum validnumber of milliseconds that elapse between the following events: when the EGLRich UI Proxy (on the Web server) invokes a service and when the Proxy receives aresponse. If more time elapses, the EGL Runtime throws aServiceInvocationException.

You can override this value by setting the timeout property on the call statementthat invokes a given service.

The default is 100,000 (100 seconds). An infinite wait is not possible.Related concepts


Coding a call statement and callback functions for service accessRelated reference

“Build descriptor options” on page 41“Build descriptor options used with JavaScript” on page 220This topic lists the build descriptor options used with JavaScript, which is thegenerated language for EGL Rich UI.

defaultSessionCookieID

The defaultSessionCookieID build descriptor option identifies the session cookieprovided to the EGL Rich UI Proxy from a service. The service logic in this case isstateful, which means that the user and logic can participate in a multistepconversation. This setting is meaningful only if the service is an EGL external typethat makes an IBM i called program or service program available as an EGL RESTservice. For background information, see Accessing IBM i programs as Web services.

The default value is JSESSIONID, which is always the session ID, regardless of anysetting in EGL, when your application runs on Apache Tomcat.

Depending on how your code is accessing the service, you can override the valueof the build descriptor option defaultSessionCookieID in one of two ways:


v When you declare a variable based on an Interface part; orv When you configure the deployment descriptor for the requester.

For details on that choice, see Declaring an interface to access a REST service.Related concepts


Accessing IBM i programs as Web servicesDeclaring an interface to access a REST serviceRelated reference


defaultTimeFormat (build descriptor option)

The defaultTimeFormat build descriptor option controls the initial runtime valueof the strLib.defaultTimeFormat system variable, which contains one of the masksthat can be used to create the string returned by the strLib.formatTime systemfunction. Other details depend on the target language:v When you are generating a COBOL program, if you do not specify the

defaultTimeFormat build descriptor option, the default value for thestrLib.defaultTimeFormat system variable is ″HH:mm:ss″.

v When you are generating Java code, the defaultTimeFormat build descriptoroption specifies the generated value for the vgj.default.timeFormat Java runtimeproperty (if you have set the genProperties build descriptor option to GLOBALor PROGRAM). That property then sets the initial runtime value of thestrLib.defaultTimeFormat system variable.

v When you are generating JavaScript code, the default value ofdefaultTimeFormat build descriptor option is HH:mm:ss.


Related concepts




defaultTimeStampFormat (build descriptor option)

The defaultTimeStampFormat build descriptor option controls the initial runtimevalue of the strLib.defaultTimeStampFormat system variable, which contains oneof the masks that can be used to create the string returned by thestrLib.formatTimeStamp system function. Additional details depend on the targetlanguage:v When you are generating a COBOL program, if you do not specify the

defaultTimeStampFormat build descriptor option, the default value for thestrLib.defaultTimeStampFormat system variable is ″yyyy-MM-ddHH:mm:ss:SSSSSS″.

v When you are generating Java code, the defaultTimeStampFormat builddescriptor option specifies the generated value for thevgj.default.timestampFormat Java runtime property (if you have set thegenProperties build descriptor option to GLOBAL or PROGRAM). That propertythen sets the initial runtime value of the strLib.defaultTimeStampFormat systemvariable.

v When you are generating JavaScript code, the default value of thedefaultTimeStampFormat build descriptor option is an empty string.


Related concepts



deploymentDescriptor

The deploymentDescriptor build descriptor option contains the name of the EGLdeployment descriptor. That descriptor provides service-binding detail when youare generating a service, as well as service-binding detail when you are generatinga logical unit (program, library, handler, or service) that invokes a service. The EGLdeployment descriptor is distinct from non-EGL JEE deployment descriptors.

The deploymentDescriptor option has no default value.

For an overview of services, along with keystroke details, see Overview ofservice-oriented architecture (SOA) and subsequent sections in the Programmer’sGuide. For language details, see Service part.

Related concepts

“Build descriptor part” on page 33“Overview of EGL deployment descriptor file” on page 79


Overview of service-oriented architecture (SOA)Related tasks


“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“Build descriptor options used with Java” on page 144“Build descriptor options used with JavaScript” on page 220This topic lists the build descriptor options used with JavaScript, which is thegenerated language for EGL Rich UI.Service partService parts provide requesters with access to the functions in the service. Arequester can be a local or remote program, handler, library, or other service.“Special considerations for generating EGL or Web services in z/OS CICSenvironments” on page 128“Special considerations for generating EGL or Web services in iSeriesenvironments” on page 129

eliminateSystemDependentCode

The eliminateSystemDependentCode build descriptor option indicates whetherthe EGL generator ignores code that will never run in the target system.

The eliminateSystemDependentCode build descriptor option is meaningful onlyin relation to the sysVar.systemType system variable. For example, the EGLgenerator does not process the following add statement if you are generating forWindows:

if (sysVar.systemType IS AIX)add myRecord;

end

To avoid generating code that will never run in the target system, take either of thefollowing actions:v Set the eliminateSystemDependentCode build descriptor option to YES. In the

current example, the add statement is not generated if you set theeliminateSystemDependentCode build descriptor option to YES and set thesystem build descriptor option to something other than AIX. Be aware, however,that the EGL generator can eliminate system-dependent code only if the logicalexpression (in this case, sysVar.systemType IS AIX) is simple enough to evaluateat generation time.

v Move the statements that you do not want to generate to a second program;then, let the original program call the new program conditionally, as in thisexample:

if (sysVar.systemType IS AIX)call myAddProgram (myRecord);

end

Values

NO Specifies that EGL generates code that does not run in the target system.Specify NO only if the output of the current generation will run inmultiple systems.


YES (the default value)Specifies that EGL only generates code that runs in the target system.

Related concepts

“Build descriptor part” on page 33Related reference

“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“Build descriptor options used with Java” on page 144“Build descriptor options used with JavaScript” on page 220This topic lists the build descriptor options used with JavaScript, which is thegenerated language for EGL Rich UI.

nextBuildDescriptor

The nextBuildDescriptor build descriptor option initiates a chain of builddescriptors by specifying the next build descriptor to be read in the generationprocess. This option can be used to create a chain of build descriptor parts.

There is no default value.Related concepts



system

The system build descriptor option specifies the target platform for generation.This option is required. There is no default value.

Values

AIX Indicates that generation produces a Java program that can run on AIX.

HPUX Indicates that generation produces a Java program that can run on HP-UX.

IMSBMPIndicates that generation produces a COBOL program that can run in anIMS batch message processing (BMP) region.

IMSVSIndicates that generation produces a COBOL program that can run as anIMS message processing program (MPP).

ISERIESCIndicates that generation produces a COBOL program that can run oniSeries.

ISERIESJIndicates that generation produces a Java program that can run on iSeries


JAVASCRIPTIndicates that generation produces a Rich UI application: HTML-embeddedJavaScript, for transmission to browsers

LINUXIndicates that generation produces a Java program that can run on Linux(with an Intel processor).

SOLARISIndicates that generation produces a Java program that can run on Solaris.

USS Indicates that generation produces a Java program that can run on z/OSUNIX System Services.

WIN Indicates that generation produces a Java program that can run onWindows 2000/NT/XP.

ZOSBATCHIndicates that generation produces a COBOL program that can run onz/OS under the control of JCL.

ZOSCICSIndicates that generation produces a COBOL program that can run onCICS for z/OS.

Related concepts

“Build descriptor part” on page 33“Generation output and associated files” on page 91Related reference

“Build descriptor options” on page 41“Build descriptor options used with Java” on page 144“Build descriptor options used with COBOL” on page 234“Build descriptor options used with JavaScript” on page 220This topic lists the build descriptor options used with JavaScript, which is thegenerated language for EGL Rich UI.



Overview of COBOL generation

This section provides COBOL-specific information related to generating COBOL forthe z/OS and iSeries environments, including the following topics:v An overview of COBOL generation (this topic)v COBOL program restrictionsv Inputs to COBOL generationv Output of COBOL generationv Modifying build scripts for z/OSv Modifying build scripts for iSeriesv Preparing output for deployment

Overview of COBOL generation

This is an overview illustrating the different phases of the generation process as itapplies to COBOL generation.

The process for generating COBOL code and other output from EGL sourceactually consists of several phases. The phases were covered briefly in the topic″Overview of EGL generation″. However, there are some specific differencesbetween the generation process for COBOL and the process for Java. This topicgives a high level overview of the COBOL generation process, focusing particularlyon the details specific to COBOL.

Here are the phases included in the generation process, along with the partsrequired for each phase:

Validation for the target runtime environmentThe first phase is the validation phase. The inputs required for this phaseare:v The generatable part, such as a program, library, and so on.v The build descriptor part, which includes some or all of the following

information:– The target runtime environment, specified in the system build

descriptor option.– The name of the linkage options part, if any. This is specified by the

linkage build descriptor option.– The name of the resource associations part, if any. This is specified by

the resourceAssociation build descriptor option.– A subset of the build descriptor options that are used during the

validation phase, such as the validateSQLStatements build descriptoroption.

The validation phase of generation is specific to the target runtimeenvironment. It does the following:v Validates that the source code is compatible with the target runtime

environment. For example, certain statements, such as sysLib.purge, canonly be used in specific environments.

v Validates that the entries in the linkage options part and resourceassociations part are correct based on the target runtime environment.


v Validates according to any special requests, such as those associated withthe validateSQLStatements build descriptor option.

Production phaseThis second phase of the generation process includes the generation of theactual COBOL code. The inputs for this phase are the following artifacts:v Validated EGL source codev All the build descriptor options, including those validated in validation

phasev Linkage options partv Resource associations partv Runtime JCL templates for z/OS or runtime CL templates for iSeriesv COBOL reserved words filev If your target environment is z/OS, these additional inputs:

– Link edit part– Bind control part

After generation, the output resulting from this phase consists of thefollowing artifacts:v COBOL source codev A build plan that controls the preparation phase for COBOL; the build

plan is based on which build descriptors and symbolic parameters wereset

v Additional output based on the specific part being generated, the targetruntime environment, and the specific build descriptor options that wereset for your generation

Any error messages are shown in the EGL Generation Results view.

Preparation phaseThe third phase of the generation process involves preparing the output ofgeneration to run in your target runtime environment. In general, thepreparation process is controlled by the build plan that is created in theproduction phase and which can include the following steps:v Transfer of the output of generation to your build server system using

TCP/IP.v Running the build scripts on the build server system, in order to

compile and link the output of generation; for CICS, the build scriptsinclude a CICS translate step. For z/OS, if the program uses SQL, thebuild scripts include steps for a DB2 precompile and bind.

v Transferring the results of the preparation phase back to the workstationusing TCP/IP.

The build plan controls the order in which output are sent to the remotebuild server and also controls which scripts are run on the build server.

Related concepts

“Bind control part” on page 264“Build descriptor part” on page 33“COBOL program restrictions” on page 231“Generatable parts” on page 2“Inputs to COBOL generation” on page 233“Linkage options part in COBOL generation” on page 257“Link edit part” on page 269


“Resource associations part in COBOL generation” on page 258“Output of COBOL program generation” on page 275Related tasks

“Modifying EGL build scripts for z/OS” on page 282“Modifying EGL build scripts for iSeries” on page 298“Modifying the runtime CL templates for iSeries” on page 264“Modifying the runtime JCL templates for z/OS” on page 262“Preparing for deployment” on page 298Related reference

“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“COBOL reserved-word file” on page 258“destHost” on page 316“genDirectory” on page 323“Runtime CL templates for iSeries” on page 263“Runtime JCL templates for z/OS” on page 259

COBOL program restrictions

When generating COBOL code using EGL there are some restrictions on what youcan do.

If you are generating COBOL code, the following restrictions are in effect:v A CICS application can only call a common batch application if the following

conditions are met:– The CICS application does not initiate file I/O;– The batch application is called using the DYNAMIC and OSLINK linkage

option settings;– The called application must be generated for batch (not CICS).

v Set-value blocks are supported only for setting property values in partdefinitions and variable declarations and for initializing field values in variabledeclarations.

v The validValues property supports only a single range of numbers.v For both text and print forms:

– Do not include the following field types:- HEX- FLOAT- SMALLFLOAT- TIME- TIMESTAMP

– If you are using a field as a date, you specify a date-format string or constantin the dateFormat field property, and these restrictions are in effect:- If you specify the form field as type DATE, NUM(8) or NUM(10) and

intend to present a date in Gregorian format, you must specify the fieldlength as 10 and may use your own 8 or 10-character format (either″yy/MM/dd″ or ″yyyy/MM/dd″, with a separator of your choice and with theyears, months, and days in any order); or any of the following dateformats:

Overview of COBOL generation 231

v usaDateFormat

v eurDateFormat

v isoDateFormat

v jisDateFormat

v systemGregorianDateFormat

- If you specify the form field as type NUM(8) and intend to present a datein Julian format, you must specify the field length as 8 and can use eitherthe Julian format ″yy/ddd″ or ″yyyy/ddd″ (with a separator of your choice) orthe date format systemJulianDateFormat

- If you specify the form field as type NUM(6) and intend to present a datein Julian format, you must specify the field length as 6 and can use eitherthe Julian format ″yy/ddd″ (with a separator of your choice) or the dateformat systemJulianDateFormat

- If you specify the form field as type CHAR(8), you must specify the fieldlength as 8 and may use either the Gregorian format ″yy/MM/dd″ (with aseparator of your choice and with the years, months, and days in anyorder) or either of the following date formats:v systemGregorianDateFormat

v systemJulianDateFormat

- If you specify the form field as type CHAR(10), you must specify the fieldlength as 10 and may use your own 8 or 10-character format (either″yy/MM/dd″ or ″yyyy/MM/dd″, with a separator of your choice and with theyears, months, and days in any order); or any of the following dateformats:v usaDateFormat

v eurDateFormat

v isoDateFormat

v jisDateFormat

v systemGregorianDateFormat

v systemJulianDateFormat

v The following capabilities are not supported:– ArrayDictionaries, Dictionaries, Delegates, report processing, and consoleUI– The sysVar.currentException system variable; you cannot identify which

exception was thrown most recently in the run unit, although use of theOnException block is supported

– Multidimensional arrays or the array-specific functions resizeAll andsetMaxSizes. However, multidimensional structured field arrays aresupported.

– The primitive types CLOB and BLOB (but literals and the substring syntaxare supported)

– Conversion of text to SMALLFLOAT or FLOAT (but conversion of FLOAT orSMALLFLOAT to text is permitted)

v The following system functions are not supported:– Functions in the system libraries consoleLib, javaLib, and lobLib

– The following functions in sysLib:- callCmd

- errorLog

- getCmdLineArg

- getCmdLineArgCount


- getMessage

- getProperty

- setError

- setErrorForComponentID

- setLocale

- setRemoteUser

- startCmd

- startLog

v The type property in the callLink element of the linkage options part does notsupport the use of remoteCall on the iSeries platform

Language Considerations

When you generate COBOL on a Windows machine running in the Turkish locale,no output is created. You can develop EGL applications that run in Turkish byfollowing these steps:1. Set your Windows locale to English.2. Set file encoding to Turkish by starting the Eclipse IDE with the following VM

arguments:v VMArgs=-Dfile.encoding=Cp1254v VMArgs=-Dibm.system.encoding=Cp1254

You can set these values in the rationalsdp.ini file found in the productinstallation directory.Related concepts

“Generation output and associated files” on page 91“Generating Java wrappers” on page 199“Output of COBOL program generation” on page 275

Inputs to COBOL generation

COBOL generation uses the following inputs for generation:v EGL generatable part or parts (for a list, see “Generatable parts” on page 2)v A build descriptor part, which includes all or some of the following information:

– Build descriptor options– Symbolic parameters specified in the build descriptor part

v Linkage options partv Resource associations partv EGL deployment descriptor (.egldd) filev COBOL reserved words filev Runtime JCL templates for z/OS or runtime CL templates for iSeriesv For z/OS the following additional parts are used for generation:

– Link edit part– Bind control part

Only the generatable part and the build descriptor part are required.Related concepts

“Bind control part” on page 264“Build descriptor part” on page 33


“Generatable parts” on page 2“Linkage options part” on page 61“Linkage options part in COBOL generation” on page 257“Link edit part” on page 269“Resource associations part” on page 65“Resource associations part in COBOL generation” on page 258Related tasks

“Editing build descriptor options in the build descriptor part” on page 58“Editing symbolic parameters in the build descriptor part” on page 59Related reference

“Build descriptor options” on page 41“Build descriptor options used with COBOL”“COBOL reserved-word file” on page 258“Runtime CL templates for iSeries” on page 263“Runtime JCL templates for z/OS” on page 259

Build descriptor options used with COBOL

A build descriptor part controls the generation process. Build descriptor optionsare one of several types of information in a build descriptor part. Build descriptoroptions specify how to generate and prepare EGL output, and a subset of the builddescriptor options can cause other build parts to be included in the generationprocess.

The next two tables list all the build descriptor options that can be used withCOBOL.v The first table shows which platform each option can be used with.v The second table lists the options, a description of each option’s function, and its

default value, if any.

These tables are restricted to those build descriptor options that are used inCOBOL generation. For a list of all available options, see “Build descriptoroptions” on page 41. For options used in Java generation, see “Build descriptoroptions used with Java” on page 144.

Table 14. Build descriptor option platform compatibility

Build descriptor optioniSeries(COBOL)

z/OSbatch

CICSforz/OS

IMSBMP IMS/VS

“bidiConversionTable” on page 299 Yes Yes Yes Yes Yes

“bind” on page 300 No Yes Yes Yes Yes

“buildPlan” on page 301 Yes Yes Yes Yes Yes

“cancelAfterTransfer” on page 302 No Yes No Yes Yes

“checkIndices” on page 302 Yes Yes Yes Yes Yes

“checkNumericOverflow” on page 303 Yes Yes Yes Yes Yes

“checkToTransaction” on page 303 No No Yes No No

“checkType” on page 304 Yes Yes Yes Yes Yes

“cicsEntries” on page 304 No No Yes No No


Table 14. Build descriptor option platform compatibility (continued)


z/OSbatch

CICSforz/OS

IMSBMP IMS/VS

“clientCodeSet” on page 306 Yes Yes Yes Yes Yes

“commentLevel” on page 306 Yes Yes Yes Yes Yes

“currencySymbol” on page 307 Yes Yes Yes Yes Yes

“data” on page 308 No Yes Yes Yes Yes

“debugTrace” on page 309 Yes Yes Yes Yes Yes

“decimalSymbol” on page 310 Yes Yes Yes Yes Yes

defaultDateFormat Yes Yes Yes Yes Yes

defaultMoneyFormat Yes Yes Yes Yes Yes

defaultNumericFormat Yes Yes Yes Yes Yes

defaultTimeFormat Yes Yes Yes Yes Yes

defaultTimeStampFormat Yes Yes Yes Yes Yes

“deploymentDescriptor” on page 224 Yes Yes Yes No No

“destHost” on page 316 Yes Yes Yes Yes Yes

“destLibrary” on page 317 Yes No No No No

“destPassword” on page 317 Yes Yes Yes Yes Yes

“destPort” on page 318 Yes Yes Yes Yes Yes

“destUserID” on page 318 Yes Yes Yes Yes Yes

“eliminateSystemDependentCode” onpage 225

Yes Yes Yes Yes Yes

“enableJavaWrapperGen” on page 320 Yes No Yes No Yes

“endCommArea” on page 320 No No Yes No No

“errorDestination” on page 321 No No No Yes Yes

“fillWithNulls” on page 321 Yes Yes Yes Yes Yes

“formServicePgmType” on page 322 No Yes No Yes No

“genDataTables” on page 322 Yes Yes Yes Yes Yes

“genDDSFile” on page 323 Yes No No No No

“genDirectory” on page 323 Yes Yes Yes Yes Yes

“genFormGroup” on page 324 Yes Yes Yes Yes Yes

“genHelpFormGroup” on page 324 Yes No Yes No Yes

“genProject” on page 325 Yes No Yes No Yes

“genReturnImmediate” on page 329 No No Yes No No

“genRunFile” on page 329 No Yes No Yes No

“genVGUIRecords” on page 330 Yes No Yes No Yes

“imsFastPath” on page 330 No No No No Yes

“imsID” on page 331 No No No Yes Yes

“imsLogID” on page 331 No No No Yes Yes

“initIORecordsOnCall” on page 332 Yes Yes Yes Yes Yes

“initNonIODataOnCall” on page 332 Yes Yes Yes Yes Yes

“leftAlign” on page 334 Yes Yes Yes Yes Yes




z/OSbatch

CICSforz/OS

IMSBMP IMS/VS

“linkage” on page 335 Yes Yes Yes Yes Yes

“linkEdit” on page 335 No Yes Yes Yes Yes

“math” on page 336 Yes Yes Yes Yes Yes

“maxNumericDigits” on page 337 Yes Yes Yes Yes Yes

“mfsDevice” on page 337 No No No Yes Yes

“mfsExtendedAttr” on page 338 No No No Yes Yes

“mfsIgnore” on page 339 No No No Yes Yes

“mfsUseTestLibrary” on page 339 No No No Yes Yes

“nextBuildDescriptor” on page 226 Yes Yes Yes Yes Yes

“positiveSignIndicator” on page 341 Yes No No No No

“prep” on page 342 Yes Yes Yes Yes Yes

“printDestination” on page 343 No No Yes No No

“projectID” on page 344 No Yes Yes Yes Yes

“reservedWord” on page 345 Yes Yes Yes Yes Yes

“resourceAssociations” on page 345 Yes Yes Yes Yes Yes

“restartTransactionID” on page 346 No No Yes No No

“restoreCurrentMsgOnError” on page346

No No No Yes No

“returnTransaction” on page 347 No No Yes No Yes

“secondaryTargetBuildDescriptor” onpage 347

Yes No Yes No Yes

“separatorSymbol” on page 348 Yes Yes Yes Yes Yes

“serverCodeSet” on page 349 Yes Yes Yes Yes Yes

“setFormItemFull” on page 352 Yes Yes Yes Yes Yes

“spaADF” on page 352 No No No No Yes

“spaSize” on page 352 No No No No Yes

“spaStatusBytePosition” on page 353 No No No No Yes

“spacesZero” on page 353 Yes Yes Yes Yes Yes

“sqlDB” on page 355 Yes Yes Yes Yes Yes

“sqlErrorTrace” on page 356 No Yes Yes Yes Yes

“sqlID” on page 356 Yes Yes Yes Yes Yes

“sqlIOTrace” on page 357 No Yes Yes Yes Yes

“sqlJDBCDriverClass” on page 357 Yes No No No No

“sqlPassword” on page 360 Yes Yes Yes Yes Yes

“sqlValidationConnectionURL” on page360

Yes Yes Yes Yes Yes

“startTransactionID” on page 361 No No Yes No No

“statementTrace” on page 361 No Yes Yes Yes Yes

“synchOnPgmTransfer” on page 362 No No Yes No No




z/OSbatch

CICSforz/OS

IMSBMP IMS/VS

“synchOnTrxTransfer” on page 363 No Yes No Yes No

“sysCodes” on page 363 Yes Yes Yes Yes Yes

“system” on page 226 Yes Yes Yes Yes Yes

“targetNLS” on page 365 Yes Yes Yes Yes Yes

“tempDirectory” on page 366 Yes Yes Yes Yes Yes

“templateDir” on page 367 Yes Yes No Yes No

“transferErrorTransaction” on page 368 No No Yes No No

“twaOffset” on page 368 No No Yes No No

“useXctlForTransfer” on page 370 No Yes No Yes No

“vagCompatibility” on page 370 Yes Yes Yes Yes Yes

“validateMixedItems” on page 371 Yes Yes Yes Yes Yes

“validateOnlyIfModified” on page 371 Yes No Yes No Yes

“validateSQLStatements” on page 372 Yes Yes Yes Yes Yes

“workDBType” on page 373 No No Yes No Yes

“wrapperCompatibility” on page 373 No No Yes No Yes

“wrapperJNDIPrefix” on page 374 No No Yes No Yes



“bidiConversionTable” on page 299 No defaultvalue

Identifies a conversion table, butonly when you generate a COBOLprogram that contains literals withArabic or Hebrew characters.

“bind” on page 300 No defaultvalue

Identifies the bind control part,which is meaningful only when yougenerate a COBOL program thatruns on z/OS and accesses SQLtables on DB2.

“buildPlan” on page 301 YES Specifies whether a build plan iscreated during the generationprocess.

“cancelAfterTransfer” on page 302 NO Indicates whether a generatedCOBOL program is removed frommemory when the program issues atransfer to program statement anda dynamic linkage is involved.

“checkIndices” on page 302 YES Specifies whether to support indexrange and null value checking.

“checkNumericOverflow” on page303

YES Specifies whether to supportnumeric overflow checking in agenerated COBOL program.




“checkToTransaction” on page 303 YES Indicates whether a special check isincluded in a generated CICSprogram that issues a transfer totransaction statement.

“checkType” on page 304 NONE Specifies the degree to which EGLchecks at validation time forprimitive-type conflicts withinstructures and records.

“cicsEntries” on page 304 NONE Specifies whether to produce CICSprogram and transactiondefinitions, and if so, in whatformat.

“clientCodeSet” on page 306 IBM-850 Specifies the name of the codedcharacter set that is in effect on thesystem.

“commentLevel” on page 306 1 Specifies the extent to which EGLsystem comments are included inoutput source code.

“currencySymbol” on page 307 For COBOL,determined bythe languagecode of theruntime system

Specifies a currency symbol that iscomposed of one to threecharacters.

“data” on page 308 31 Specifies whether to use theDATA(24) or DATA(31) compileoption to prepare a generatedCOBOL program.

“debugTrace” on page 309 NO Indicates whether EGL embedstrace information within agenerated COBOL program.

“decimalSymbol” on page 310 For COBOL,determined bythe languagecode of theruntime system

Specifies the symbol to be used asthe decimal indicator.

defaultDateFormat For COBOL, ifthis option isnot specified,the associatedsystem variabledefaults to theLong Gregoriandate formatspecified in thelanguage-dependentoptions modulefor yourruntimeinstallation.

Controls the initial runtime value ofthe strLib.defaultDateFormatsystem variable

defaultMoneyFormat No defaultvalue

Controls the initial runtime value ofthe strLib.defaultMoneyFormatsystem variable




defaultNumericFormat No defaultvalue

Controls the initial runtime value ofthe strLib.defaultNumericFormatsystem variable

defaultTimeFormat For COBOL,the defaultvalue isHH:mm:ss

Controls the initial runtime value ofthe strLib.defaultTimeFormatsystem variable

defaultTimeStampFormat For COBOL,the defaultvalue isyyy.MM.ddHH:mm:ss:SSSSSS

Controls the initial runtime value ofthestrLib.defaultTimeStampFormatsystem variable


No defaultvalue


“destHost” on page 316 No defaultvalue

Specifies the name or numericTCP/IP address of the targetsystem where the build serverresides.

“destLibrary” on page 317 QGPL Specifies the 1- to 10-charactername of the iSeries library thatreceives the objects created duringgeneration and contains the objectsused at run time.

“destPassword” on page 317 No defaultvalue

Specifies the password that EGLuses to log on to the system wherepreparation occurs.

“destPort” on page 318 No defaultvalue

Specifies the port on which aremote build server is listening forbuild requests.

“destUserID” on page 318 No defaultvalue

Specifies the user ID that EGL usesto log on to the system wherepreparation occurs.




YES (allow all) Specifies whether all or only someof the following components can begenerated when you attempt togenerate the program: the program,Java wrapper classes, and relatedEJB session bean.

“endCommArea” on page 320 NO Indicates whether to add four bytesof hexadecimal F values to the endof the COMMAREA on calls fromEGL-generated CICS COBOLprograms.




“errorDestination” on page 321 ELAPRINT (forIMS BMP); orELADIAG (forIMS/VS)

Specifies the destination ofdiagnostic messages.

“fillWithNulls” on page 321 YES Indicates whether to fill print-formfields with null characters.

“genDataTables” on page 322 YES Specifies whether you want togenerate the data tables that arereferenced in the program you aregenerating.

“genDDSFile” on page 323 NO Indicates whether you want tocreate iSeries data descriptionspecification (DDS) files from therecord declarations with whichyour program does input or output.

“genDirectory” on page 323 No defaultvalue

Specifies the fully qualified path ofthe directory into which EGL placesgenerated output andpreparation-status files.

“genFormGroup” on page 324 YES Indicates whether to generate theform group that is referenced in theuse declaration of the programbeing generated.

“genHelpFormGroup” on page 324 YES Indicates whether to generate thehelp form group that is referencedin the use declaration of theprogram being generated.

“genProject” on page 325 No defaultvalue

Used in COBOL generation whenthe project has associated Javaobjects. Places the output of Javageneration into a workbench projectand automates tasks that arerequired for Java runtime setup.

“genReturnImmediate” on page 329 NO Specifies whether the generatedCICS COBOL program exits with aCICS RETURN IMMEDIATEstatement.

“genRunFile” on page 329 YES Indicates whether to producesample runtime JCL for a z/OSbatch program that you aregenerating.

“genVGUIRecords” on page 330 YES Indicates whether to generate theVGUI records that are referenced inconverse or show statements of aWeb transaction.

“imsFastPath” on page 330 NO Specifies whether the program canrun as an IMS fast-path program.

“imsID” on page 331 No defaultvalue

Specifies the IMS DB control ID foryour database; the value is usedwhen you debug IMS code thataccesses DL/I.




“imsLogID” on page 331 No defaultvalue

Specifies an identifier that will beincluded in records written to theIMS log.

“initIORecordsOnCall” on page 332 YES Specifies when called program IOrecords are initialized.

“initNonIODataOnCall” on page332

YES Specifies when called programnon-IO-record and primitivevariables are initialized.

“leftAlign” on page 334 YES Indicates whether to left-justify theoutput data on some print-formfields.

“linkage” on page 335 No defaultvalue

Contains the name of the linkageoptions part that guides aspects ofgeneration.

“linkEdit” on page 335 No defaultvalue

Identifies a link edit part, which ismeaningful only when you generatea COBOL program for z/OSenvironments.

“math” on page 336 COBOL Specifies whether to do arithmeticcalculations based on CSP math,which is used in some COBOLprograms that were written eitherwith IBM Cross System Product(CSP) or with VisualAge Generator.

“maxNumericDigits” on page 337 31 Specifies the size of numeric fields.This applies only to COBOLgeneration.

“mfsDevice” on page 337 No defaultvalue

Specifies information to include inthe EGL-generated DEV and DFLDstatements, for form-groupgeneration targeted to IMS.

“mfsExtendedAttr” on page 338 YES Indicates a default value forwhether the devices supportextended attributes and for whethera color default (CD) extendedattribute is generated for formfields that are defined with color =default color.

“mfsIgnore” on page 339 NO Indicates whether to includeIGNORE in the SOR parameter ofthe MSG statement for theEGL-generated MID and MOD.

“mfsUseTestLibrary” on page 339 NO Specifies whether the build scriptwill cause the build server to placethe MFS control blocks in a testlibrary.

“nextBuildDescriptor” on page 226 No defaultvalue





“positiveSignIndicator” on page 341 F Specifies the character that theiSeries-based ILE COBOL compileruses as the positive sign fornumeric data of types DECIMAL,MONEY, NUM, NUMC, and PACF.


“printDestination” on page 343 PROGRAMCONTROLLED

Specifies the destination of printedoutput for basic programsgenerated for CICS.

“projectID” on page 344 No defaultvalue

Assigns a value to the EZEPIDsymbolic parameter, which is usedin build scripts that run on z/OS.

“reservedWord” on page 345 No defaultvalue

Specifies a fully qualified pathname for a text file that containsreserved words other than the EGLreserved words.

“resourceAssociations” on page 345 No defaultvalue

Contains the name of a resourceassociations part, which relatesrecord parts to files and queues onthe target platforms.

“restartTransactionID” on page 346 A blank Indicates the transaction ID used torestart a program generated forCICS for z/OS.

“restoreCurrentMsgOnError” onpage 346

YES fortransaction-oriented BMPs;else, NO

Specifies whether, if an IMS BMPends because of an error, a messagethat is being read by an EGLstatement is reinserted on the IMSmessage queue.

“returnTransaction” on page 347 No defaultvalue

Identifies the CICS transaction thatstarts when the transactionassociated with the generatedprogram ends without a transfer.


No defaultvalue

Specifies a build descriptor thatguides the generation of code beingdeployed to a Web applicationserver, while other code (which istargeted for other environments) isbeing generated in the samegeneration request.

“separatorSymbol” on page 348 For COBOL,determined bythe language ofthe runtimesystem

Specifies the symbol used forseparating the thousands andhundreds in a numeric value.

“serverCodeSet” on page 349 IBM-037 Specifies the name of the codedcharacter set that is used by thez/OS or iSeries build server.




“setFormItemFull” on page 352 YES Indicates whether to displayasterisks (*) in every emptyprint-form field for which youspecified a set statement of theform set field full.

“spaADF” on page 352 NO Specifies whether the IMS/VSprogram being generated transfersto or from an IMSADF II program.

“spaSize” on page 352 0 Specifies the number of bytes in theIMS scratch-pad area.

“spaStatusBytePosition” on page353

No defaultvalue

Specifies the position of asegmentation status byte in the IMSscratch pad area.

“spacesZero” on page 353 NO Specifies whether a generatedCOBOL program includes extracode to process numeric fields thatare filled with spaces.

“sqlDB” on page 355 No defaultvalue

Specifies the default database usedby a generated program.

“sqlErrorTrace” on page 356 NO Specifies whether a generatedCOBOL program includes the codenecessary to trace errors that occurduring I/O operations against arelational database.

“sqlID” on page 356 No defaultvalue

Specifies a user ID that is used toconnect to a database duringgeneration-time validation of SQLstatements.

“sqlIOTrace” on page 357 NO Specifies whether a generatedCOBOL program includes the codenecessary to trace the I/Ooperations done against a relationaldatabase.

“sqlJDBCDriverClass” on page 357 No defaultvalue

Specifies a driver class that is usedto connect to a database duringgeneration-time validation of SQLstatements.

“sqlPassword” on page 360 No defaultvalue

Specifies a password that is used toconnect to a database duringgeneration-time validation of SQLstatements.


No defaultvalue

Specifies a URL for connecting tothe database during generation-timevalidation of SQL statements.

“startTransactionID” on page 361 No defaultvalue

Indicates the transaction ID used tostart a program that is generatedfor CICS.

“statementTrace” on page 361 NO Specifies whether a generatedCOBOL program includes the codenecessary to trace non-SQLstatements.




“synchOnPgmTransfer” on page 362 YES Specifies whether to set a commitpoint in CICS in a way thatminimizes the difference betweenprocessing on CICS and IMS.

“synchOnTrxTransfer” on page 363 NO Specifies whether a commit pointoccurs when a main program that isgenerated for z/OS batch or IMSBMP runs a transfer to transactionstatement.

“sysCodes” on page 363 NO Determines the source of the returncode that is placed in thesysVar.errorCode system variable inresponse to a file I/O error in aCOBOL program.

“system” on page 226 No defaultvalue

Specifies the target runtimeenvironment of the generated code.This option is required.

“targetNLS” on page 365 No defaultvalue

Specifies the national language codeused to identify runtime messages.

“tempDirectory” on page 366 No defaultvalue

Specifies the location where EGLplaces two kinds of files: theIntermediate Representation (IR)files that are created when usingthe EGLSDK, and the JSP filescreated when generating aVGWebTransaction program orVGUIRecord.

“templateDir” on page 367 None Specifies the directory that containstemplates used to produce runtimeJCL for z/OS or runtime CL foriSeries.

“transferErrorTransaction” on page368

No defaultvalue

Specifies the name of a CICStransaction that receives controlwhen a transfer statement results inan error.

“twaOffset” on page 368 0 Specifies how many bytes in thetransaction work area (TWA) arereserved for use by non-EGLprograms in the same CICS rununit.

“useXctlForTransfer” on page 370 NO Indicates whether to use an XCTLcommand to implement anytransfer to program statement.

“vagCompatibility” on page 370 NO Indicates whether the generationprocess permits the use of specialprogram syntax.

“validateMixedItems” on page 371 YES Specifies whether a generatedCOBOL program validates fieldsthat are of type MBCHAR.

“validateOnlyIfModified” on page371

NO Specifies whether to validate onlythose text-form fields for which themodified data tag is set.





NO Indicates whether SQL statementsare validated against a database atgeneration time.

“workDBType” on page 373 AUX, for CICS;DLI, for IMS

Specifies the type of work databaseto use at run time.


CURRENT Indicates how to regeneratewrappers that you intend to usewith handwritten Java code whenthe wrappers were originallygenerated by VisualAge Generator4.5, EGL 5.x, or EGL 6.x.

“wrapperJNDIPrefix” on page 374 No defaultvalue

Specifies a prefix to be added to allJNDI names for generated sessionbeans.


No defaultvalue

Specifies the package to generateJava wrappers into.

Related concepts


“Adding a build descriptor part to an EGL build file” on page 38“Editing build descriptor options in the build descriptor part” on page 58“Editing symbolic parameters in the build descriptor part” on page 59“Removing a build descriptor part from an EGL build file” on page 39Related reference

“Build descriptor options” on page 41“Build descriptor options used with JavaScript” on page 220This topic lists the build descriptor options used with JavaScript, which is thegenerated language for EGL Rich UI.“Build descriptor options used with Java” on page 144

Choosing build descriptor options for COBOL generation

Build descriptor options are set in a build descriptor part. To choose builddescriptor options for COBOL generation, follow these steps:1. In the EGL Source folder of your project, right-click the build file that you want

to work with and then click Open With → EGL Build Parts Editor. The EGLBuild Parts Editor opens to the General Options view.

2. On the left side of the view, there is a table that displays build descriptoroptions. You can either show all available options, or filter the list of builddescriptor options.v To see all available build descriptor options, follow these steps:

a. Clear the Show only specified options check box.b. In the Build option filter list, select All.

v To filter the list of build descriptor options, follow these steps:a. Select the Show only specified options check box.b. Alternatively, you can choose an environment-specific filter in the Build

option filter list. Filters with the word ″Basic″ after the name of the target


environment list only the build descriptor options that are used mostfrequently; filters with the word ″All″ contain all options available forthat environment.

3. After you select your options, you can edit the values of those options byclicking once on an option to select it, then clicking again in the Value field tomake it editable.

4. You can also enter symbolic parameters on the left side of this view. To add asymbolic parameter, click Add at the bottom of the table. To edit the newsymbolic parameter, click once in the field you want to edit to make the fieldeditable. Once you have entered symbolic parameters, you can click Remove todelete them.

Two build descriptor options, genDirectory and destDirectory, permit the use of asymbolic parameter for the value or a portion of the value. For example, for thevalue of genDirectory, you can specify C:\genout\%EZEENV%. Then if you generatefor a Windows environment, the actual generation directory is C:\genout\WIN. Ifyou generate for ZOSCICS, the actual generation directory is C:\genout\ZOSCICS.

You do not need to specify all the options listed. If you do not specify a value for abuild descriptor option, the default for the option is used when the option isapplicable in the generation context.

If you have specified a master build descriptor, the option values in that builddescriptor override the values in all other build descriptors. For details on masterbuild descriptors, see “Build descriptor part” on page 33. When you generate, themaster and generation build descriptors can connect to other build descriptors in achain, as described in “Build descriptor part” on page 33.

Related concepts


“Editing build descriptor options in the build descriptor part” on page 58“Editing symbolic parameters in the build descriptor part” on page 59“Setting the master build descriptor” on page 36Related reference

“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“destDirectory” on page 315“genDirectory” on page 323

Symbolic parameters used with COBOL generation

Symbolic parameters are variables that are replaced with values at generation time.They can be used in the following places:v Certain build descriptor optionsv Build scripts for iSeries and z/OSv Runtime JCL or CL templatesv Link edit partsv Bind control parts

There are three types of symbolic parameters:


Predefined symbolic parameters that are set automaticallyThese are substitution values for predefined symbols which areautomatically set at generation, based on the part that is being generatedor other information available during the generation process. The value forthese symbols cannot be changed.

Predefined symbolic parameters that can be set by the userThere are certain predefined symbols that are used in the build scripts andtemplates, and you can set these at generation time. In addition, there are afew predefined symbols that you can set that affect the generated COBOLcode. These symbolic parameters are used for information that is requiredfor most customers, but that generally has a unique value for eachcustomer. For example, the name of the data set that contains the COBOLcompiler generally varies for each customer. For information about thesetypes of parameters, see “Predefined symbolic parameters that can be setby the user” on page 252.

User-defined symbolic parametersYou might need to customize any of the following for your target runtimeenvironment:v EGL-provided build scriptsv EGL-provided runtime JCL templates for z/OS or runtime CL templates

for iSeriesv Bind control part to be used as a template for binding packagesv Link edit part to be used as a template

When you customize any of the above, you might need to add additionalsteps or processing. Some of your additions might require variables thatcan be modified at generation time. To do this, you can create or modifyuser-defined symbolic parameters, by using the EGL Build Parts Editor tospecify values for the symbolic parameters in your build descriptor. Thenyou can refer to these user-defined symbolic parameters in your buildscripts or templates

Both predefined and user-defined symbolic parameters are available as substitutionvariables in the build scripts used to prepare COBOL output. At COBOL buildtime, EGL passes all symbolic parameters to the build server. The passed valuesprovide the values for build-script substitution variables of the same name,overriding the default values (if any) for those substitution variables. For details,see “Modifying EGL build scripts for z/OS” on page 282, and the IBM RationalBusiness Developer EGL Server Guide for IBM i.

You can specify the values for some predefined symbolic parameters. You can alsodefine your own symbolic parameters, in addition to the predefined symbolicparameters, and for each such parameter you define, you assign a value. Forexample, the MYDIR symbolic parameter might contain the name of a directory.You cannot define the same symbolic parameter (like MYDIR) twice in the samebuild descriptor.

If the build descriptor you are using for generation uses the nextBuildDescriptoroption to chain multiple build descriptors, and you define the same-namedsymbolic parameter in multiple build descriptors that are chained together, thevalue in use at generation time is determined by the precedence rules described in“Build descriptor part” on page 33. The value assigned to the MYDIR symbolicparameter in the master build descriptor, for example, takes precedence over thevalue assigned to MYDIR in any other build descriptor.


Setting a language code page for your zSeries COBOLenvironmentYou can use EGL build descriptor symbolic parameters to set your language codepage for the zSeries.

In addition to the STRING and UNICODE data types that you can define in EGL,the language has internal literals defined as STRING. All of these STRING andUNICODE values are implemented in COBOL as PIC N, with the USAGENATIONAL qualifier. In order for the COBOL compiler to correctly translate thesePIC N values to Unicode values, it must know the codepage to use for thetransformation. If your system programmers have not configured the CODEPAGEoption for the COBOL compiler, or if the wrong page is specified, you may need toset the correct value yourself.

To do this in EGL, locate and open the build plan you use for COBOL generation.On the right hand side of the panel, you can enter generation-specific symbolicparameters that are passed to the build server. Add CODEPAGE(####) to anypreexisting values for the COBLISTPARMS parameter, as in the following example:COBLISTPARMS LIST,NOOPT,CODEPAGE(1147)

Refer to your COBOL manuals for the correct value for the CODEPAGE parameter.The following table contains a partial list:

Table 16. Sample CODEPAGE values for zSeries COBOL

Value Language

420 Arabic

274 Belgium (old)

275 Brazilian Portugese

935 Chinese (Simplified)

1371, 937 Chinese (Traditional)

277 Danish

437 English (Australian)

1146, 285 English (UK)

1140, 437 English (US)

278 Finnish

1147, 297 French

273 German

875 Greek

424, 803 Hebrew

1149, 871 Icelandic

1144, 280 Italian

1390, 290, 930, 939 Japanese

1364, 933 Korean

1153, 870, 1148, 500 Latin

277 Norwegian

1156 Russian (Baltic)

1025, 1158 Russian (Cyrillic)

1122, 1157 Russian (Estonian)


Table 16. Sample CODEPAGE values for zSeries COBOL (continued)

Value Language

1112 Russian (Latvian)

1112 Russian (Lithuanian)

1123, 1158 Russian (Ukranian)

1145, 284 Spanish

278 Swedish

838 Thai

1026 or 1155 Turkish

ExamplesYou can use symbolic parameters in the values for the genDirectory and thedestDirectory build descriptor options, in build scripts, in templates, or in the linkedit or bind control parts.

When using symbolic parameters in the genDirectory and destDirectory builddescriptor options, reference the value of a symbolic parameter by delimiting theparameter name with percentage signs (%). For example, if you want to refer tothe time at which generation occurs, use the following code:%EZEGTIME%

You can also use more than one symbolic parameter to assign a value. Forexample, the following symbols represent date and time, separated by a space:

%EZEGDATE% %EZEGTIME%

For example, if genDirectory is set to C:\MyProject\%EZEENV%, and the systembuild descriptor option is set to ZOSCICS, then generation output will be writtento C:\MyProject\ZOSCICS.

When using symbolic parameters in build scripts, reference the value by precedingthe symbolic parameter name with an ampersand (&) and appending a period (.)to the parameter name:

&EZEGDATE.

For example, consider the situation in which a build script includes the followingline://EZESRC DD DSN=&MYHLQ..;&SYSTEM..EZESRC;,DISP=SHR

If you set the system build descriptor option to ZOSCICS and set the MYHQLuser-defined symbolic parameter to the value MYQUAL, then the resulting line inthe build script is the following://EZESRC DD DSN=MYQUAL.ZOSCICS.EZESRC,DISP=SHR

Related concepts



“Build descriptor options” on page 41“Predefined symbolic parameters that are set automatically” on page 250“Predefined symbolic parameters that can be set by the user” on page 252


Predefined symbolic parameters that are set automatically

The first table below lists the predefined symbolic parameters that are setautomatically, based on the generated part. The second table below lists thepredefined symbolic parameters that are related to serial, indexed, and relativerecords, or to print output. These symbolic parameters are used to generate DDstatements for program files in runtime JCL for zSeries environments, or runtimeCL for iSeries. Some parameters are only available on zSeries, some only on iSeries,and some on both platforms.

Table 17. Predefined symbolic parameters

Name Description Platform

ARITH A symbolic parameter used to set the ARITH COBOLcompiler option. The value is set to COMPAT if themaxNumericDigits build descriptor option is set to 18;otherwise it is set to EXTEND.

iSeries,zSeries

CGHLQ The high-level qualifier for user data sets. This symbolicparameter is equivalent to EZEPID.

zSeries

DATA A symbolic parameter set either to 24 or 31, specifying thesize (in bits) of the addresses used to allocate workingstorage. This value is used to set the DATA COBOLcompiler option. The parameter value is taken from the databuild descriptor option.

zSeries

EZEALIAS The member name used to store the currently generatedmember in its associated PDS. If an alias property wasspecified for the currently generated part, the value of thatproperty, truncated to 8 characters if necessary, is used. Ifthe alias property is not specified, then the part name,truncated to 8 characters if necessary, is used. When a formgroup is the current member, and the form group has printforms included, the format module name is truncated to 6characters rather than 8, and the characters FM areappended. The symbolic parameters EZEALIAS and MBRare equivalent.

iSeries,zSeries

EZEDLI A symbolic parameter set to YES if the program, library, orservice uses DL/I; otherwise it is not included in the buildplan.

zSeries

EZEENV The target system for which the EGL part was generated;for example, IMSBMP, IMSVS, ISERIESC, ZOSBATCH, orZOSCICS. The value is set from the system build descriptoroption.

iSeries,zSeries

EZEEXTNM The external name, if any, that is specified in the programpart’s alias property; if necessary, this is truncated to 8characters. This symbolic parameter is available only duringgeneration of bind control and link edit files. It is notavailable when build scripts are being executed. If theexternal name is not specified, the name of the part is usedbut is truncated, if necessary, to 8 characters.

zSeries


Table 17. Predefined symbolic parameters (continued)


EZEGDATE The date on which a program is generated. The format is

mm/dd/yy

mm Two-digit format for month.

dd Two-digit day of the month.

yy Two-digit format for the year.

If EZEGDATE is used in the genDirectory or destDirectorybuild descriptor options, the format is yyyy-mm-dd.

iSeries,zSeries

EZEGMBR A symbolic parameter equivalent to EZEALIAS. iSeries,zSeries

EZEGTIME The time at which a program is generated. The format is

hh:mm:ss

hh Hour

mm Minutes

ss Seconds

If EZEGTIME is used in the genDirectory or destDirectorybuild descriptor options, the format is hh.mm.ss.

iSeries,zSeries

EZELMBR The long name of the currently generated part. iSeries,zSeries

EZEMBR A symbolic parameter equivalent to EZEALIAS. iSeries,zSeries

EZENLS The value specified in the targetNLS build descriptoroption.

iSeries,zSeries

EZEPID The high-level qualifier that is used for the PDSs thatreceive the generated and built output. The parameter’svalue is taken from the projectID build descriptor option.

zSeries

EZEPSB The value is the PSB name that is specified for the programbeing generated. The value is only set when generatingprograms. The maximum length for the symbolic parametervalue is 8.

zSeries

EZESQL A symbolic parameter set to YES if the program, library, orservice being generated uses SQL; otherwise, it is set to N.

iSeries,zSeries

EZETRAN A symbolic parameter containing the transaction ID forCICS and IMS. For CICS, the value is set based on thestartTransactionID build descriptor option, if specified;otherwise, the value is the first 4 characters of the programalias property or the first 4 characters of the program name,if the alias property is not specified.

zSeries

EZEXAPP A symbolic parameter used to indicate comment in sampleruntime JCL. It contains the name of a called ortransferred-to program as a reminder that you need to addDD statements for files or databases used in the called ortransferred-to program.

zSeries

MBR A symbolic parameter equivalent to EZEALIAS. iSeries,zSeries

SYSTEM A symbolic parameter equivalent to EZEENV. iSeries,zSeries


Table 18. Predefined symbolic parameters that are set automatically based on fileinformation

Name Description

EZEBLK The file block size. For a fixed-length record, it is set to therecord length. For a variable-length record, it is set to therecord length plus 8 bytes. The value is set for the followingtypes: seq, seqrs, and gsam.

zSeries

EZEDBD Set from the pcbName property from the EGL PSB. Thisvalue is set for DL/I records.

zSeries

EZEDD The DD name set from the fileName property in the recorddefinition. The value is set for the following file types: seq,seqrs, gsam, vsam and vsamrs.

zSeries

EZEDSN The value is the z/OS data set name from the systemNameproperty of the resource association entry that corresponds tothe fileName property of the record. The value is set for thefollowing file types: seq, seqrs, gsam, vsam and vsamrs.

zSeries

EZELRECL The file logical record length. For a fixed-length record, it isset to the record length. For a variable-length record, it is setto the record length plus 4 bytes. The value is set for thefollowing file types: seq, seqrs, and gsam.

zSeries

EZERECFM The file record format. For a fixed-length record, it is set toFB. For a variable-length record, it is set to VB. The value isset for the following file types: seq, seqrs, and gsam.

zSeries

Related concepts

“Bind control part” on page 264“Link edit part” on page 269“Symbolic parameters used with COBOL generation” on page 246Related tasks


“Predefined symbolic parameters that can be set by the user”“Runtime CL templates for iSeries” on page 263“Runtime JCL templates for z/OS” on page 259

Predefined symbolic parameters that can be set by the user

The tables in this topic show the predefined symbolic parameters that you can setif you are generating COBOL code. In addition to the parameters shown below, theuser can create additional custom parameters for either the iSeries or zSeriesenvironment. The first table shows symbolic parameters that are used in the EGLbuild scripts and in EGL templates.

Do not override any of the pseudo-JCL variables set by the build server.

Table 19. Predefined symbolic parameters that can be set by the user

Name Description Default value Platform

AMODE Value of the AMODE forthe module. Possiblevalues are 24 and 31.

31 zSeries


Table 19. Predefined symbolic parameters that can be set by the user (continued)


BUILD_SCRIPT_LIBRARY Allows the name of thePDS from which thebuild server reads thebuild scripts to beoverridden.

This symbolic parameteris useful when exceptionbuild processing isneeded. For example,you can use a separatebuild script PDS if aspecial test system isneeded with a separatedatabase, COBOLlibraries, or CICSlibraries. The buildscripts could havedifferent defaultsubstitution variables ordifferent compileoptions.

An alternative approachis to start a build serveron a different port andto allocate a differentbuild script PDS.

zSeries

CCUEXTB The build server DDstatement extension fordatabase bind printoutsreturned to the buildclient1

NORETURN zSeries

CCUEXTC The build server DDstatement extension forcompiler printoutsreturned to the buildclient1

NORETURN zSeries

CCUEXTL The build server DDstatement extension forlinkage editor printoutsreturned to the buildclient1

NORETURN zSeries

CCUEXTP The build server DDstatement extension forSQL preprocessorprintouts returned to thebuild client.1

NORETURN zSeries

CCUEXTS1 The build server DDstatement extension forIMS MFS processinglisting step 1 returned tothe build client.1

NORETURN zSeries




CCUEXTS2 The build server DDstatement extension forIMS MFS processinglisting step 2 returned tothe build client.1

NORETURN zSeries

CCUEXTT The build server DDstatement extension forCICS translator printoutsreturned to the buildclient1

NORETURN zSeries

COBCICS The name of the LECICS runtime library.

SYS1.SCEECICS zSeries

COBCOMP The name of the COBOLcompiler library.

SYS1.IGY.SIGYCOMP zSeries

COBLIB The name of the LElink-edit library

SYS1.SCEELKED zSeries

COBLISTPARMS Listing options forCOBOL compiler

NOLIST zSeries

DEBUG To compile the programfor use with thedebugger, set the valueof this parameter to YESon iSeries or TEST onzSeries.

, (comma) iSeries,zSeries

DFHLOAD The name of the CICSload library

CICS.CICS410.PD09850.SDFHLOAD2

zSeries

DSN The name of the DB2subsystem

DSN82 zSeries

DSNCLI The name of the moduleto include in thegenerated link editcontrol files for programsthat use DB2 but notDL/I. Using the defaultvalue of DSNCLI, thegenerated statementwould be: include syslib(DFHEAI, DSNCLI)

DSNCLI zSeries

DSNEXIT The name of the DB2DSNEXIT library

DSN8.DSNEXIT2 zSeries

DSNHLI The name of the moduleto include in thegenerated link editcontrol files for programsthat use both DB2 andDL/I. Using the defaultvalue of DSNHLI, thegenerated statementwould be: include syslib(DFHEAI, DSNHLI)

DSNHLI zSeries

DSNLOAD The name of the DB2DSNLOAD library

DSN8.DSNLOAD2 zSeries




DSYS The name of the DB2subsystem

DSN82 zSeries

ELA IBM Rational COBOLRuntime Server forzSeries high-levelqualifier

ELA.V6R0M1 zSeries

LECOMPLIANT Specify YES if you wishto link zOS batch orIMSBMP generatedprograms with an LEcompliant EGL runtimestub. The LE compliantruntime stub does notalter any execution, butallows the user to utilizemainframe debuggers (orother programs) thatrequire LE compliance.

NO zSeries

RESLIB The value of IMSRESLIB.

SYS1.SDFSRESL zSeries

RETAINTEMPORARYFILES If set to NO (the default),this parameter causes theiSeries system to deletetemporary files as wellas COBOL source filesafter compilation. If youset DEBUG to YES,RETAINTEMPORARYFILESwill automatically be setto YES.

NO iSeries

RGN Region size 4096K zSeries

RMODE Value of the RMODE forthe module. Possiblevalues are 24 and ANY.

ANY zSeries

SDFHEXCI Location of CICSSDFHEXCI library.

CICSTS.V3R1M0.CICS.SDFHEXCI

zSeries

SOUT SYSOUT assignment * zSeries

SUFF CICS program namesuffix

1$ zSeries

SYS2 High level qualifier forIMS MFS preparation

IMSC710 zSeries

SYSCMDS CICS/ESA® systemprogramming translatoroption

&COMMA.SP2 zSeries

WSPC Primary and secondaryspace allocation

2500 zSeries




Notes:1. Valid values are as follows:

CCUOUTReturn to the client as a file namedexternal_name.step_name.DD_name

CCUSTDReturn to client as a file with the name shown above, and asStandard Output.

CCUERRReturn to client as a file with the name shown above, and asStandard Error.

NORETURNDo not return to the client.

2. These default values are realistic, but are placeholders only. You will needto set your own default values appropriate to your system in your buildscript.

The following table shows symbolic parameters that you can set to affect generatedCOBOL code; these can also be used in the EGL build scripts and in EGLtemplates.

Table 20. Predefined symbolic parameters that can be set by the user to affect generatedCOBOL code


EZUAUTH This symbolic parameter sets the value for theCOBOL program AUTHOR statement. Themaximum length for the symbolic parameter valueis 60 characters.

zSeries

EZUINST This symbolic parameter sets the value for theCOBOL program INSTALLATION statement. Themaximum length for the symbolic parameter valueis 60 characters.

zSeries

HANDLEOVERFLOW Changes the default value (0) of thevgVar.handleOverflow system variable. Thefollowing values are allowed:

0 (the default)Maintain the default value.

1 Throw a RuntimeException in case ofoverflow.

2 Set the sysVar.overflowIndicator systemvariable and continue.

This parameter has no effect unless you arerunning in V6 exception mode.

iSeries,zSeries


Table 20. Predefined symbolic parameters that can be set by the user to affect generatedCOBOL code (continued)


HEAPSIZE This alters the default heap memory block sizefrom 8192 to the specified value. This is onlyeffective on the main EGL program and is not usedby called programs or libraries. If you get anunusual runtime error, you can set the heapmemory block size to a value other than 8192 (forexample, 16384), and then rerun your application.If the failure is different or does not occur, thispoints to a garbage collection problem. If thefailure is the same, the problem is not in garbagecollection. This kind of information can helpdevelopers determine the cause of some errors.

zSeries

STDOUT This can be set to UPON CONSOLE if you wantthe writeStdout text written to the JESMSGLG andconsole files. This applies to z/OS Batch only.

zSeries

Related concepts

“Build scripts” on page 105“Build server” on page 107“Symbolic parameters used with COBOL generation” on page 246Related tasks


“Predefined symbolic parameters that are set automatically” on page 250

Linkage options part in COBOL generation

A linkage options part provides the various elements that you can use to specify thedetails of how you want certain statements to be implemented in your generatedCOBOL code. It contains some or all of the following elements:

asynchLinkProvides details on how a generated program starts a particular programor transaction asynchronously by using the vgLib.startTransaction systemfunction.

callLinkProvides details on how a call statement is to be implemented whencalling a particular program, or how a particular called program will becalled.

fileLinkProvides details on whether to use remote file I/O for a particular file inthe CICS environment.

transferToProgramProvides details on how a transfer to program statement is implementedwhen transferring to a particular program.

transferToTransactionProvides details on how a transfer to transaction statement is implementedwhen transferring to a particular transaction (or program innon-transactional environments).


For COBOL generation, the options you specify at generation time cannot bechanged at runtime. For more information, see “Linkage options part” on page 61.

Related concepts


“Adding a linkage options part to an EGL build file” on page 63Related reference

“asynchLink element” on page 375“callLink element” on page 380“fileLink element” on page 407“transferToProgram element” on page 410“transferToTransaction element” on page 416

Resource associations part in COBOL generation

An EGL serial, indexed, MQ , or relative record that accesses an external file,printer, or queue has a logical file or queue name. In the case of a printer, thelogical file name is printer for most COBOL runtime systems. The name can be nomore than 8 characters and is meaningful only as a way of relating the record to asystem name, which the target system uses to access a physical file, printer, orqueue.

In relation to files or queues, the file or queue name (or a substring derived fromthat name) is a default for the system name. In relation to printers, a default existsonly for COBOL output.

Instead of accepting a default, you can take one or both of these actions:v At generation time, you can control the generation process by using the

resourceAssociations build descriptor option that references a specific resourceassociations part. The resource associations part relates the logical file or queuename to a system name on the target platform where you intend to deploy thegenerated code.

v At run time, depending on the file type you specify in the resource associationspart, you can change the value in the record-specific variablerecordName.resourceAssociation (for files or queues) or in theConverseVar.printerAssociation system variable (for print output). This enablesyou to override the system name that you specified, either by default or byspecifying a resource associations part.Related reference

“Association elements” on page 71“resourceAssociations” on page 345“Resource associations part” on page 65“system” on page 226

COBOL reserved-word file

For COBOL generation, EGL maintains a predefined (built-in) list of COBOL, SQL,and CICS reserved words that must not be used as names within a COBOLprogram. If the alias name of a generatable part (or the name of the part itself,truncated to 8 characters, if the alias property is not specified) conflicts with aword in the reserved words list, the EGL generator exits with an error. For


non-generatable parts, if EGL finds a conflict between the part name and a word inthe reserved words list, the EGL generator creates an alias for the part name.

In general, you do not need to supplement the predefined list of reserved words.However, in the following situations, you might need to define a reserved wordsfile to provide additional reserved words that the EGL generator should avoid. Youmight need an additional reserved words file under the following conditions:v You are using a newer version of COBOL, DB2, or CICS than the version of EGL

you own was developed to handle, and a new keyword is introduced by thatnewer product.

v There are certain words you do not want used as COBOL variable names.

If necessary, your system administrator can create a reserved words file to provideadditions to the predefined list of reserved words. The format of the reservedwords file contains two types of records:

Comment statementA statement with an asterisk (*) in column one.

Reserved word statementA statement with a word starting in column one. The word extends to thefirst blank. In addition to specific reserved words, you can use the asterisk(*) as a wild card at the end of a word, as in the following examples:v CICS*v SQL*v XYZ*

When the reserved word ends in an asterisk, any name whose initialcharacters match the string preceding the asterisk are treated as thoughthey matched a word in the list.

If you create a reserved-word file, set the reservedWord build descriptor option tothe fully qualified path name of that file. For more information about EGL reservedwords, see the EGL Language Reference.

Related concepts

“How COBOL names are aliased” on page 100Related reference

“reservedWord” on page 345

Runtime JCL templates for z/OS

If you set the genRunFile build descriptor option to YES for z/OS Batch and IMSBMP environments, EGL creates sample runtime JCL for running the program. Thefile name is alias.jcx, where alias is set by the alias property for the program, and istruncated to 8 characters; or if the alias property is not specified, it is the programname, truncated to 8 characters. You can tailor the sample runtime JCL after it istransferred to the z/OS host. Alternatively, before you generate the output code,you can customize the templates that EGL uses to provide the basic pattern for thesample runtime JCL as described in “Modifying the runtime JCL templates forz/OS” on page 262.

The name and type of file generated depends on the target system:v For MVS batch or IMS BMP the generation function creates sample JCL for

running the program. The file name is alias.jcx.


The templates used for creating the sample runtime JCL are selected according tothe following criteria:v The target runtime environmentv Whether the program is a main or called programv The use of DB2 in the programv The use of DL/I in the program

Runtime JCL templates

The following table shows the JCL templates and procedures used for runningz/OS batch programs.

Table 21. Templates used for running MVS batch programs

Environ-ment Program SQL DL/I

Calls CICSEXCI? Template

Procedurecalled bytemplate

z/OS batch Main Yes Yes n/a fda2mebb DLIBATCH

z/OS batch Main No Yes n/a fda2mebc DLIBATCH

z/OS batch Main Yes No No fda2mebd

z/OS batch Main Yes No Yes fda2mesx

z/OS batch Main No No No fda2mebe

z/OS batch Main No No Yes fda2mebx

z/OS batch Called The use of thetemplate is notaffected bySQL or DL/Iusage.

* * fda2meba

Each of the JCL templates contains a ?DD? line that starts in column one. This lineindicates where the generation function is to insert the DD statements for files anddatabases used by the program. Move this line within the JCL template to controlwhere the DD statements are placed. If you remove the line that contains ?DD?,the DD statements are not included in the generated JCL.

An exception to the above is the fda2meba template. For called programs, librariesand services the fda2meba template only includes the DD statements. You canincorporate these DD statements into the sample runtime JCL of any main programthat calls the generated program, or uses the library or service.

More about DL/I use for z/OS batch

DL/I usage is indicated if the program includes at least one of the followingattributes or functions:v The PSBRecord used by the program includes a database other than ELAWORK.v The program’s PSB is passed on a call statement.v The program receives the PSB or a PCB from the PSBRecord as a parameter.v The program uses the dliLib.AIBTDLI, dliLib.EGLTDLI, or vgLib.VGTDLI

system functions.v The program uses sysLib.audit and a PSBRecord is used in the program.v The program references any PCB from the PSBRecord in any statement.v The program associates a serial file with GSAM.


Runtime JCL templates for IMS BMP

The next table shows the JCL templates and procedures used for running IMS BMPprograms.

Note: DL/I is always present in the IMS BMP environment.

Table 22. Templates used for running IMS BMP

Environment Program SQL TemplateProcedure calledby template

IMS BMP Main Yes fda2meia IMSBATCH

IMS BMP Main No fda2meib IMSBATCH

IMS BMP Called * fda2meba

Note: * The use of the template is not affected by SQL usage.

Each of the JCL templates contains a ?DD? line that starts in column one. This lineindicates where the generation function is to insert the DD statements for files anddatabases used by the program. Move this line within the JCL template to controlwhere the DD statements are placed. If you remove the line that contains ?DD?,the DD statements are not included in the generated JCL.

File and database allocation templates

For called programs, libraries and services, the fda2meba template only includesthe DD statements. You can incorporate these DD statements into the sampleruntime JCL of any main program that calls the generated program or uses thelibrary or service.

Some of the files or databases used by a program require file or database templatesfor generating file allocation statements. The following table shows the templateselected based on the following information:v The type of recordv Whether the record is input or outputv The file type specified in the resource associations part

Table 23. Templates for generating file allocation statements

Record type Input or output Associated file typeJCL template forz/OS Batch

DL/I segment Input or output fda2mdli

Indexed RelativeSerial

Input VSAM, VSAMRS fda2mvsi

Indexed RelativeSerial

Output VSAM, VSAMRS fda2mvso

Serial Input SEQ, SEQRS fda2msdi

Serial Output SEQ, SEQRS fda2msdo

Serial Input GSAM fda2mgsi, fda2mims

Serial Output GSAM fda2mgso, fda2mims

Note: The statements generated from file and database templates are included atpoints marked by the ?DD? line in the program template.


fda2mimsThe fda2mims template is an extra template for GSAM. For IMS BMP jobs,if any of the serial files, or the printer, is associated with a GSAM file, thetemplate fda2mims is also included.

fda2mdliThe fda2mdli template is only included if the target environment is z/OSBatch. For the IMS BMP target environment, the database should alreadybe allocated to the IMS control region. This template has the DD statementcommented out. EGL does not collect the resource association informationneeded to build this statement. You must provide the final tailoring ofthese DD statements in the sample runtime JCL after the program has beengenerated.

File and database allocation placeholder templates

The generated sample runtime JCL for a program must be modified to include DDstatements for files referenced using the record-specific variablerecord-name.resourceAssociation or the converseVar.printerAssociation systemvariable, or for files and databases used by programs that are called ortransferred-to from the initial program in the run unit.

The following table shows the templates that generate comments in the sampleruntime JCL to indicate the place where DD statements can be included.

Table 24. Templates that generate comments in sample run-time files

Program function JCL template for MVS batch or IMS BMP

Program uses sysVar.transferName or avariable name as the target program in acall, transfer to program, or transfer totransaction statement

fda2meza

Program uses a specific program name asthe target program in a call, transfer toprogram, or transfer to transactionstatement

fda2mcal

Program sets the record-specific variablerecord-name.resourceAssociation or theconverseVar.printerAssociation systemvariable

fda2mezd

Related topics

“Build descriptor part” on page 33“templateDir” on page 367Related tasks

“Modifying the runtime JCL templates for z/OS”Related reference

“genRunFile” on page 329

Modifying the runtime JCL templates for z/OS

You can modify the templates to meet your installation requirements for preparingand running programs. These modifications are usually done by a systemadministrator or project leader. To modify the templates, create a new directoryand copy all the templates from the default directory. Make your changes to thecopies of the templates and not the original templates.


The runtime templates for z/OS are located in the following default directory:shared_resources\plugins\com.ibm.etools.egl.generators.cobol_version\MVStemplates



The file type extension for the templates is always .tpl.

Because different projects can require different templates, it is important to haveseparate directories for each project. Each directory must contain copies of all thetemplates. Use the templateDir build descriptor option to specify the directorycontaining the templates to be used. If this option is not specified the templates inthe default directory will be used.

Reasons to modify templates

You might need to modify templates for the following reasons:v Implementing installation data set naming conventionsv Changing the name of the cataloged procedure being calledv Assigning parameter valuesv Adding DD statements to the STEPLIB concatenationv Overriding DD statementsv Adding or changing the REGION parameter for a step

Related topics

“Runtime JCL templates for z/OS” on page 259“Build descriptor part” on page 33“templateDir” on page 367Related reference

“templateDir” on page 367

Runtime CL templates for iSeries

EGL creates sample control language (CL) for running a called program on iSeries.The file name is alias.clr, where alias is set by the alias property for the program,truncated to 8 characters; or if the alias property is not specified, the programname, truncated to 8 characters. During the preparation phase of generation, thesample runtime CL is copied to the QVGNCLS file in the destination library withthe name alias_R. It is then compiled. You can tailor the sample runtime CL after itis transferred to the iSeries host. Alternatively, before you generate output code,you can customize the template that EGL uses to provide the basic pattern for thesample runtime CL.


These templates are used by EGL to create sample runtime CL for the iSeriesenvironment:

fda24ebcProvides the CL to add libraries to the client/server job and to startcommitment control if this is the first server program called by a client.You can customize this template to add any libraries that the serverprogram needs for data or programs.

fda24eecProvides an epilogue to the runtime CL to handle errors that occur. Do notcustomize this template.

Modifying the runtime CL templates for iSeries

Templates can be modified to meet installation requirements for preparing andrunning programs. These modifications are usually done by a system administratoror project leader. To modify the templates, create a new directory and copy all ofthe templates into that new directory from the default location. Make your changesto the copies, not to the original templates.

The runtime templates for iSeries are located in the following default directory:shared_resources\plugins\com.ibm.etools.egl.generators.cobol_version\iSeriestemplates



The file type extension for the templates is always .tpl.

Because different projects can require different templates, it is important to haveseparate directories for each project. Each directory must contain copies of all thetemplates. Use the templateDir build descriptor option to specify the directorycontaining the templates to be used. If this option is not specified the templates inthe default directory will be used.

Related topics

“Runtime CL templates for iSeries” on page 263“Build descriptor part” on page 33Related reference

“templateDir” on page 367

Bind control part

For z/OS, if you generate a program, library, or service that accesses an SQL table,EGL includes the following steps in the build plan:


v A DB2 precompile step to create a database request module (DBRM)v A DB2 bind step to bind a DB2 plan, possibly by combining that DBRM with the

DBRMs of other programs that are intended for the same transaction or batchjob step.

Bind control parts are used only for DB2 programs generated for z/OS systems.The purpose of the bind control is to ensure that the program and DB2 are thesame level. The information in the bind control part is used to create the bindcontrol file that is passed to the DB2 processor. The bind control file specifies whatdatabase request modules (DBRMs) are included in the DB2 plan that is created atpreparation time.

Multiple bind control parts can be defined. The bind build descriptor optionindicates which bind control part is to be included in the generation output.

Using the default bind control partEGL generates a bind control file to use in the DB2 bind step. By default, EGLbinds a plan that only includes the DBRM for the program, library, or service thatis being generated, plus any EGL-provided DBRMs that are required based on theruntime environment. EGL uses the following built-in template to create the bindcommand:TSOLIB ACTIVATE DA('%DSNLOAD%')ALLOC FI(DBRMLIB) SHR DA('%EZEPID%.%SYSTEM%.DBRMLIB')CONCATD FI(DBRMLIB) SHR DA('%ELA%.SELADBRM')DSN SYSTEM($DSYS%)BIND PLAN(%EZEALIAS%) -

MEMBER(%EZEALIAS%) -ACT(REP) -RETAIN -VALIDATE(BIND) -ISOLATION(CS)

* OWNER(OWNERGRP)

The built-in template uses symbolic parameters (for example, %SYSTEM%) to helpgenerate the actual bind command. For example, if you generate the MAILORDRprogram and specify the following settings:v The system build descriptor option is set to ZOSBATCHv The projectID build descriptor option is set to ORDERSYSv The DSNLOAD predefined symbolic parameter is set to DSN8HLQ.DSNLOADv The ELA predefined symbolic parameter is set to ELAHLQ.V5R0M0v The DSYS predefined symbolic parameter is set to DSN8

Then this is the resulting bind command EGL creates:TSOLIB ACTIVATE DA('DSN8HLQ.DSNLOAD')ALLOC FI(DBRMLIB) SHR DA('ORDERSYS.ZOSBATCH.DBRMLIB')CONCATD FI(DBRMLIB) SHR DA('ELAHLQ.V5R0M0.SELADBRM')DSN SYSTEM(DSN8)BIND PLAN(MAILORDR)

MEMBER(MAILORDR, ELADBRM4) -ACT(REP) -RETAIN -VALIDATE(BIND) -ISOLATION(CS)

* OWNER(OWNERGRP)

ELADBRM4 is an EGL-supplied DBRM that is used in the z/OS Batchenvironment.


Establishing a bind control part to use as a template

You might prefer to bind packages into an existing plan. To do this you mustcreate an EGL bind control part that contains a template to use for all the bindsused in a particular environment, and store this part in your workspace.

For example, you might create a bind control part named BIND_TEMPLATE thatlooks like this:TSOLIB ACTIVATE DA('%DSNLOAD%')ALLOC FI(DBRMLIB) SHR DA('%EZEPID%.%SYSTEM%.DBRMLIB')CONCATD FI(DBRMLIB) SHR DA('%ELA%.SELADBRM')DSN SYSTEM(%DSYS%)BIND PACKAGE(%MYCOLLECTIONNAME%) -

MEMBER(%EZEALIAS%) -ACT(REP) -RETAIN -VALIDATE(BIND) -ISOLATION(CS)

* OWNER(OWNERGRP)

In the previous example, MYCOLLECTIONNAME is a user-defined symbolicparameter, which you can create and set the value for in your build descriptorpart. The other symbolic parameters are the same ones used in the EGL built-intemplate.

In addition to creating the EGL bind control part to serve as a template, you mustalso perform the following actions:v Modify your build descriptor part. You need to set the bind build descriptor

option to point to your bind control part (BIND_TEMPLATE).v Bind a package for the EGL-provided DBRMs into each DB2 plan in the

following situation:– If your runtime environment is z/OS Batch with DB2 only, the EGL-provided

DBRM is ELADBRM4– If your runtime environment is IMS/VS with a DB2 work database, the

EGL-provided DBRM is ELADBRM3

Establishing a program-specific bind control part

If you bind plans, then each program frequently requires a different bindcommand. This is because all the programs for a single run unit (for example, aCICS or IMS transaction, or a single batch job step) must be bound together with asingle bind command. You can achieve this by creating a program-specific bindcontrol part to bind a plan for the program with all the other programs that are inthe same run unit. There are two techniques for doing this:1. Create a program-specific bind control part with the same name as the

program, library, or service. By default, EGL looks for a bind control part withthe same name as the part being generated.

2. Create a program-specific bind control part with a different name from theprogram, library, or service. In this case, you must set the bind build descriptoroption to the name of the bind control part whenever you generate theprogram, library, or service.

For example, if ProgramA calls ProgramB and both programs use SQL, then tobind a DB2 plan that includes the DBRMs for both programs and that can be usedfor z/OS Batch, you need a program-specific bind control part such as this:


TSOLIB ACTIVATE DA('DSN8HLQ.DSNLOAD')ALLOC FI(DBRMLIB) SHR DA('ORDERSYS.ZOSBATCH.DBRMLIB')CONCATD FI(DBRMLIB) SHR DA('ELAHLQ.V5R0M0.SELADBRM')DSN SYSTEM(DSN8)BIND PLAN(MYABPLAN) -

MEMBER(PROGRAMA,PROGRAMB,ELADBRM4) -ACT(REP) -RETAIN -VALIDATE(BIND) -ISOLATION(CS) -

* OWNER(OWNERGRP)

ELADBRM4 is the EGL-provided DBRM that is required for the z/OS Batchenvironment whenever DB2 is used.

You can create a bind control part named ProgramA and an identical bind controlpart named ProgramB, so that EGL automatically finds the program-specific bindcontrol part. Alternatively, you might create a single bind control part namedMYABPLAN and set the bind build descriptor option to point to MYABPLANwhenever you generate either ProgramA or ProgramB.

For information about accessing data in SQL databases with EGL, see the topic″SQL data access″ and related topics in the EGL Language Reference.

Related concepts

“Symbolic parameters used with COBOL generation” on page 246Related tasks

“Adding a bind control part to an EGL build file” on page 268“Editing a bind control part in an EGL build file” on page 269“Removing a bind control part from an EGL build file” on page 269Related reference

“bind” on page 300“Build descriptor options” on page 41“Predefined symbolic parameters that are set automatically” on page 250“Predefined symbolic parameters that can be set by the user” on page 252

Bind control file

If you generate a COBOL program that accesses an SQL table, EGL alwaysproduces a bind control file. A bind control file is meaningful only if you aregenerating a COBOL program that runs on z/OS and that accesses SQL tables onDB2. The file is equivalent to the bind control file that you would create if youaccessed DB2 from a native COBOL program. In the context of EGL, the bindcontrol file is created when you are preparing the generated source fordeployment.

When source code that accesses DB2 is prepared for z/OS, the following stepshandle SQL statements that are in the code:1. A DB2 precompilation step uses the SQL statements to create a database

request module (DBRM).2. A bind step creates a DB2 plan, possibly by combining that DBRM with the

DBRMs of other programs that are intended for the same CICS transaction orjob step.


The bind control file specifies what DBRMs are included in the DB2 plancreated by the bind step, and the plan in turn makes DB2 access possible foreach program that contributed a DBRM.Related concepts

“Bind control part” on page 264Related tasks

“Adding a bind control part to an EGL build file”“Editing a bind control part in an EGL build file” on page 269“Removing a bind control part from an EGL build file” on page 269Related reference

“bind” on page 300“Build descriptor options” on page 41

Adding a bind control part to an EGL build file

If you are developing COBOL programs that run on z/OS, the bind control partprovides a way to create information for a bind control file. You can add a bindcontrol part to an EGL build file. To add a bind control part, complete these steps:1. In the Project Explorer view, locate the EGL build file you want to work with

by opening the EGL Source folder and looking for a file with an .eglbldextension.

2. Right-click the build file and select Open With → EGL Build Parts Editor. TheBuild Parts Editor opens the build descriptor part to the General Options view.

3. If you have the Outline view open, you will see the build parts listed under thename of your build file. If you do not have the Outline view open and want toopen it, select Window → Show View → Other; in the Show View window,expand the General node and select Outline.

4. In the Outline view, right-click the build file, and then click Add Part.5. Click Bind Control, and then click Next.6. In the Name field, type the name of your bind control part. Choose a name for

your bind control part that adheres to EGL part name conventions. For detailson how to select a bind control part name, see “bind” on page 300.

7. In the Description field, type a description of your part.8. Click Finish. The bind control part is added to the EGL file and the bind

control part page is opened in the EGL build parts editor. Type your bindcommands in the editor.

For information on bind commands and the format of a bind control part, see“Bind control part” on page 264.

Related concepts

“Bind control part” on page 264“Bind control file” on page 267Related tasks

“Editing a bind control part in an EGL build file” on page 269“Removing a bind control part from an EGL build file” on page 269Related reference

“bind” on page 300“EGL build-file format” on page 30


Editing a bind control part in an EGL build file

To edit a bind control part:1. In the Project Explorer view, open an EGL build file by doing the following:

a. Right-click on the EGL file.b. Click Open With → EGL Build Parts Editor.

2. If you have the Outline view open, you will see the build descriptor part listedunder the name of your build file. If you do not have the Outline view open,select Window → Show View → Other; in the Show View window, expandGeneral and select Outline.

3. In the Outline view, right-click the bind control part and select Open.4. Edit the bind commands in the bind control part.5. Save the build file when you are finished editing.

Related concepts


“Adding a bind control part to an EGL build file” on page 268“Removing a bind control part from an EGL build file”

Removing a bind control part from an EGL build file

To remove a bind control part from an EGL build file, follow these steps:1. In the Project Explorer view, open an EGL build file by doing the following:

v Right-click the EGL file.v Click Open With → EGL Build Parts Editor.

2. If you have the Outline view open, you will see the build parts listed under thename of your build file. If you do not have the Outline view open, selectWindow → Show View → Other; in the Show View dialog box, expand Generaland select Outline.

3. In the Outline view, right-click the bind control part, then click Remove.Related concepts


“Adding a bind control part to an EGL build file” on page 268“Editing a bind control part in an EGL build file”

Link edit part

If you are developing COBOL programs that run on z/OS, the link edit partprovides a way to create the information for a link edit file, which in turn specifieshow to combine COBOL programs into a load module.

You define a link edit part in either of two cases:v A generated COBOL program includes static COBOL calls to other programsv A generated COBOL program is called statically by another program, whether

generated or not


You can also supply your own link edit part if you want to specify linkage editorcontrol statements that are not provided in the default link edit file produced bythe COBOL generator.

Link edit fileThe link edit file specifies to the z/OS linkage editor how to create a load modulefrom object and load modules. The file is equivalent to the link edit file that youwould create if you wrote the COBOL directly.

In the context of EGL, the link edit file is an input to the distributed buildfunction, which prepares the generated source for execution.

EGL always produces a default link edit file (with the suffix led) that is used tolinkedit the single program, library, or service into a load module, including anyrequired EGL runtime modules that must be statically linked. The build serveralways runs a link edit step using the default link edit file.

You can also supply a link edit part, either by specifying the linkEdit builddescriptor option or by naming the link edit part with the same name as thecorresponding program, library, or service. In this case, EGL generates anadditional link edit file (with the suffix lkg). If this additional link edit file iscreated, the build server runs an additional link edit step using this (lkg) link editfile. This enables you to link edit any additional modules that must be staticallylinked with the program, library, or service that you are generating. The modulesthat you combine with the module produced by default link edit do not have to beprepared by EGL or even produced by a COBOL compiler.

For details, see the topic about the linkEdit build descriptor option, which controlsthe output.

Related concepts

“Generation output and associated files” on page 91“Link edit part” on page 269Related tasks

“Adding a link edit part to an EGL build file” on page 273Related reference

“Link edit part examples”“linkEdit” on page 335

Link edit part examples

Link edit parts are used for the z/OS environments. In general, EGL automaticallygenerates the linkage editor control statements. However, in some situations, suchas those where you have a static link, you must provide a link edit part.

It is best to define the program’s link edit part in the same project as the programso that it is available whenever the program is available. The link edit part mustcontain linkage editor control statements for linking every load module thatcontains the program.

Syntax and format rules: The control statements in the link edit part must followthese linkage editor syntax and format rules:v Statements cannot start in column one.v No blank lines are allowed between statements.


For more information about writing linkage editor control statements, refer to thelinkage editor document for your host system.

zSeries program with static calls to other programs: A link edit part containinglinkage editor control statements must be defined for each generated program thatcontains static COBOL calls. The linkage editor control statements consist ofENTRY and NAME statements for the load module and INCLUDE statements foreach statically called program and the base program. Your COBOL runtime (IBMRational COBOL Runtime Server for zSeries) entry stub program (ELARMAIN)must also be included in the z/OS batch and IMS BMP environments. OtherCOBOL runtime and database stubs are included along with the programs fromthe original link edit step produced during the generation process.

The following table shows sample control statements when program BASEPGMstatically calls both a generated COBOL program EGLAPP1 and a PL/I programPLIAPP1. In the example, the object decks for PL/I programs have been written todata set NONEGLL.OBJ.LIBRARY, which is referenced by the DD statementNONEGLL. All the INCLUDE statements for the called programs precede theINCLUDE for the calling program.

Table 25. Sample control statements

Environment Base program type Control statements in BASEPG

CICS for z/OSIMS/VS

Main or called INCLUDE SYSLMOD(EGLAPP1)INCLUDE NONEGLL(PLIAPP1) (See note 1.)INCLUDE SYSLMOD(BASEPGM)ENTRY BASEPGMNAME BASEPGM(R)

IMS BMPz/OS batch

Main only CHANGE ELAAPPL(BASEPGM)INCLUDE SELALMD(ELARMAIN)INCLUDE SYSLMOD(EGLAPP1)INCLUDE NONEGLL(PLIAPP1)INCLUDE SYSLMOD(BASEPGM)ENTRY ELARMAINNAME BASEPGM(R)

IMS BMPz/OS batch

Called only INCLUDE SYSLMOD(EGLAPP1)INCLUDE NONEGLL(PLIAPP1)INCLUDE SYSLMOD(BASEPGM)ENTRY BASEPGMNAME BASEPGM(R)

1. PL/I programs cannot be statically linked for CICS for z/OS. For CICS forz/OS, this link would be to a statically linked non-EGL COBOL program.

To make the NONEGLL library available for the relink step, you must to add a DDstatement to the build scripts. For this example, find the following line in the code://* Add your DD statements here if you supply your own link edit parts

Then add a new line similar to this below it://* Add your DD statements here if you supply your own link edit parts//NONEGLL DD DSN=NONEGLL.OBJ.LIBRARY,DISP=SHR

zSeries programs that are statically called by other programs: A link edit partthat contains link edit statements must also be defined for each EGL program thatis the target of a static COBOL call from another program. Include statements to


link every load module that calls the EGL program in the link edit part so thateach load module is automatically linked again whenever the called EGL programis generated.

For example, if the COBOL generated program EGLAPP1 is statically called byBASEPGM and by BASEPG2, define the link edit part for EGLAPP1 so that itcontains the set of statements for the runtime environment from the previous tabletwice: once referencing BASEPGM and once referencing BASEPG2. This ensuresthat both BASEPGM and BASEPG2 are relinked whenever you generate EGLAPP1.

Modifying the EGL build scripts: If a program is both the target of a staticCOBOL call and also includes a static COBOL call to other programs, you mustfurther tailor any EGL build scripts to use different load libraries as the includeand output libraries for generated program load modules.

The following example shows a SYSLMOD DD statement before modifications.//SYSLMOD DD DISP=SHR,DSN=&CGHLQ..&ENV..LOAD

The next example shows the replacement DD statements for the SYSLMOD DDstatement.//EGLINCL DD DISP=SHR,DSN=&CGHLQ..&ENV..LOAD//SYSLMOD DD DISP=SHR,DSN=&CGHLQ..&ENV..RELINK.LOAD

Then define all link edit parts containing link edit statements to use the EGLINCLlibrary as the include library for generated programs. Setting up the libraries thisway has the following effects:v The initial link edit step in the preparation procedures links the generated

program with COBOL runtime and database stub programs into the EGLINCLlibrary.

v Statically called programs are not linked together in the EGLINCL library toavoid the same program being included multiple times on the relink step.

v The relink step combines all statically linked programs into the appropriate loadmodules and stores the load modules in the SYSLMOD library.

Specifying the control statements: The following table shows how to specify thecontrol statements for linking the program BASEPGM if the statically calledprogram EGLAPP1 in turn statically called program EGLAPP2. The controlstatements for linking program BASEPGM should also be added to the EGLAPP1and EGLAPP2 link edit parts so that program BASEPGM is linked again wheneither program EGLAPP1 or EGLAPP2 is generated.

Table 26. Sample control statements


CICS for z/OSIMS/VS

Main or called INCLUDE EGLINCL(EGLAPP1)INCLUDE EGLINCL(EGLAPP2)INCLUDE NONEGLL(PLIAPP1) (See note 1.)INCLUDE EGLINCL(BASEPGM)ENTRY BASEPGMNAME BASEPGM(R)


Table 26. Sample control statements (continued)


IMS BMPz/OS batch

Main only CHANGE ELAAPPL(BASEPGM)INCLUDE SELALMD(ELARMAIN)INCLUDE EGLINCL(EGLAPP1)INCLUDE EGLINCL(EGLAPP2)INCLUDE NONEGLL(PLIAPP1)INCLUDE EGLINCL(BASEPGM)ENTRY ELARMAINNAME BASEPGM(R)

IMS BMPz/OS batch

Called only INCLUDE EGLINCL(EGLAPP1)INCLUDE EGLINCL(EGLAPP2)INCLUDE NONEGLL(PLIAPP1)INCLUDE EGLINCL(BASEPGM)ENTRY BASEPGMNAME BASEPGM(R)

1. PL/I programs cannot be statically linked for CICS for z/OS. For CICS forz/OS, this link would be to a statically linked non-EGL COBOL program.

The relink load library and the original load libraries are required when runningprograms. The relink library is required for statically linked modules. The originallibrary is required for modules that did not have to be statically linked. Thefollowing example shows how to customize the run time JCL file and the IMS andCICS region JCL file to include the load libraries in the correct order in theSTEPLIB statement.// DD DISP=SHR,DSN=chglq.system.RELINK.LOAD// DD DISP=SHR,DSN=chglq.system.LOAD

The variables chglq and system represent the values that were substituted for theCGHLQ and ENV parameters in the build script.

Related concepts

“Link edit part” on page 269Related tasks

“Adding a link edit part to an EGL build file”“Editing a link edit part in an EGL build file” on page 274“Removing a link edit part from an EGL build file” on page 275Related reference

“Build descriptor options used with COBOL” on page 234“linkEdit” on page 335

Adding a link edit part to an EGL build file

If you are developing COBOL programs that run on z/OS, the link edit partprovides a way to create information for a link edit file. You can add a link editpart to an EGL build file. To add a link edit part, follow these steps:1. In the Project Explorer view, locate the EGL build file you want to work with

by opening the EGL Source folder and looking for a file with an .eglbldextension.

2. Right-click the build file and select Open With → EGL Build Parts Editor. TheBuild Parts Editor opens the build descriptor part to the General Options view.

3. If you have the Outline view open, you will see the build parts listed under thename of your build file. If you do not have the Outline view open and want to


open it, select Window → Show View → Other; in the Show View window,expand the General node and select Outline.

4. In the Outline view, right-click the build file, and then click Add Part.5. Click Link Edit, then click Next.6. In the Name field, type the name for your link edit part. Choose a name that

conforms to EGL part name conventions. For information about how to select alink edit part name, see “linkEdit” on page 335.

7. In the Description field, type a description of your part.8. Click Finish. The link edit part is added to the EGL build file and the link edit

part page is opened in the EGL build parts editor. Type in your link editcommands.

You can find more information about link edit commands in “Link edit partexamples” on page 270.

Related concepts


“Editing a link edit part in an EGL build file”“Removing a link edit part from an EGL build file” on page 275Related reference

“EGL build-file format” on page 30“linkEdit” on page 335“Link edit part examples” on page 270

Editing a link edit part in an EGL build file

To edit a link edit part:1. In the Project Explorer view, open an EGL build file by doing the following:



3. In the Outline view, right-click on the build file, then click Open. The link editpart page is opened. Make your changes to the link edit commands. You canfind more information about link edit commands in “Link edit part examples”on page 270.

4. Save the build file when you are finished editing your link edit part.Related concepts


“Adding a link edit part to an EGL build file” on page 273“Removing a link edit part from an EGL build file” on page 275Related reference



Removing a link edit part from an EGL build file

To remove a link edit part from an EGL build file, follow these steps:1. In the Project Explorer view, open an EGL build file by doing the following:



3. In the Outline view, right-click on the link edit part, and then click Remove.Related concepts


“Adding a link edit part to an EGL build file” on page 273“Editing a link edit part in an EGL build file” on page 274Related reference


Output of COBOL program generation

The following table shows the output of the production and generation phase, thegeneratable part for which the output is produced, the file name of the outputtype, the target environment for which the output is produced, and any builddescriptor options that control the generation of the output type.

Table 27. Output of the production and generation phase

Output type File nameGeneratablepart


Build descriptoroptions

COBOL program alias.cbl Program partLibrary partService partDataTable part

All ThegenDataTablesoption controlsthe generation ofany DataTableparts used by ageneratedprogram, library,or service.

Build plan aliasBuildPlan.xml

Program partLibrary partService partDataTable part

All buildPlan


Table 27. Output of the production and generation phase (continued)




Link edit file alias.ledalias.lkg Program partLibrary partService partDataTable part

All z/OSenvironments

EGL alwayscreates the LEDlink edit file.EGL creates theLKG file if thelinkEdit builddescriptor optionspecifies aparticular linkedit part; or, ifthe linkEditbuild descriptoroption is notspecified, butthere is a linkedit part withthe same nameas the program,library, orservice partbeing generated.

Bind control file alias.bnd Program partLibrary partService part

All z/OSenvironments

For a program,library, orservice, the bindbuild descriptoroption canspecify aparticular bindcontrol part. Ifthe bind optionis not specified,the default is forEGL to use abind control partthat matches thename of theprogram, library,or service beinggenerated. Ifthere is no bindcontrol part,then EGLautomaticallycreates the bindcontrol file.

CICS entries alias.pctalias.ppt Program z/OS CICS cicsEntries






COBOLcopybook

formgroupalias.CPY

FormGroup part IMS/VS EGL uses thegenFormGroupandgenHelpFormGroupbuild descriptoroptions todeterminewhether togenerate theFormGroup andhelp form groupwhen generatingthe EGLapplication.

MFS Source formgroupalias.MFS

FormGroup partHelp form group

part

IMS/VSIMS BMP

EGL creates theMFS Source filefor IMS BMP ifformServicePgmTypeis set to ALL orMFS. EGL usesthegenFormGroupandgenHelpFormGroupbuild descriptoroptions todeterminewhether togenerate theFormGroup andhelp form groupwhen generatingthe EGLapplication.

FormGroupformat module

formgroupaliasFM.FMT

FormGroup partHelp form group

part

CICSiSeriesIMS/VS

EGL uses thegenFormGroupandgenHelpFormGroupbuild descriptoroptions todeterminewhether togenerate theFormGroup andhelp form groupwhen generatingthe EGLapplication.






Form Groupprint servicesprogram

formgroupaliasP1.CBL

FormGroup part z/OS BatchIMS BMP


Form Grouponline printservices program

formgroupalias.CBL

FormGroup part z/OS CICSIMS/VS


Sample runtimeJCL

alias.jcx Program partLibrary partService part

z/OS BatchIMS BMP

The genRunFilebuild descriptoroption controlswhether the fileis generated ornot. ThetemplateDirbuild descriptoroption controlswhere thetemplates arelocated.

Sample runtimeCL

alias.clr Program partLibrary partService part

iSeries The templateDirbuild descriptoroption controlswhere thetemplates arelocated.

Table binaryimage

alias.tab DataTable iSeries ThegenDataTablesoption controlsthe generation ofany DataTableparts used by ageneratedprogram, library,or service.






Message file alias.msg A DataTable oftype msgTable

iSeries ThegenDataTablesoption controlsthe generation ofany DataTableparts used by ageneratedprogram, library,or service.

Data definitionspecification

alias.dds Program partLibrary partService part

iSeries genDDSFile

At the end of the preparation phase, an overall results file contains the statusinformation on the preparation steps that were completed on the build serverrunning in your target runtime environment. There are also results files for eachstep of preparation. You will receive these results only if EGL attempts to preparegenerated output. Preparation occurs automatically when you generate source codeinto a directory and set the following build descriptor options:v The prep build descriptor option is set to YESv The buildPlan build descriptor option is set to YES

For iSeries, there is one file that contains all of the results of the compilation andlinking of the generated COBOL. The name of the file is alias.BUILD.LISTING

For z/OS, the following table shows the results files that are produced by thepreparation phase. The file names contain the following variables:

aliasThe property, if any, that is specified for the generatable part, truncated to 8characters. If the alias is not specified, the program name is used, truncated to8 characters.

ddnameThe data definition name of the output.

Table 28. File names for the results of code preparation on z/OS

Preparation step Results file name on the build client

DB2 preprocessor alias.P.ddname

CICS translator alias.T.ddname

COBOL compiler alias.C.ddname

Linkage editor alias.L.ddname

DB2 bind alias.B.ddname

Overall results of preparation alias_cbl_Results.xml

For more information about various types of parts that can be generated in thetopic ″Generatable parts″ or the sections on parts in the EGL Programmer’s Guideand the EGL Language Reference.

Related concepts

“Bind control part” on page 264


“Build plan” on page 103“Generatable parts” on page 2“Generation output and associated files” on page 91“Link edit part” on page 269Related reference

“bind” on page 300“buildPlan” on page 301“cicsEntries” on page 304“CICS table files” on page 281“genDataTables” on page 322“genDDSFile” on page 323“genRunFile” on page 329“linkEdit” on page 335“Location of output”“Output of Java wrapper generation” on page 208“Output of Java program generation” on page 172“templateDir” on page 367

Location of output

The location of the generated output depends on the target platform and builddescriptor options.

z/OS

When the generation process is complete, the following naming scheme is used todetermine the location of the output on the z/OS server. The output goes to apartitioned data set (PDS) whose name is in the following format:projectID.system.type

projectIDThe value of the projectID build descriptor option.

system The value of the system build descriptor option.

type The type of PDS files such as load or object.

The following table shows the preset variables and their corresponding outputtypes.

Table 29. Preset variables and their corresponding output types

Type Output of COBOL generation

DBRMLIB DBRMs created for COBOL programs that use DB2

EZEBIND Bind control file

EZECOPY COBOL copybook that corresponds to the MFS source for textforms

EZEFOBJ FormGroup format module (object code)

EZEJCLX Sample runtime JCL

EZELINK Link edit file (.led)

EZELKG User-defined link edit file (.lkg)


Table 29. Preset variables and their corresponding output types (continued)

Type Output of COBOL generation

EZEMFS MFS source for a FormGroup

EZEPCT CICS program definitions

EZEPPT CICS transaction definitions

EZESRC COBOL source code for program, library, service or DataTable

LOAD load modules

OBJECT object modules

iSeries

For the iSeries server, the destLibrary build descriptor option specifies the iSerieslibrary into which the code is placed.

Related concepts

“Bind control part” on page 264“Introduction to EGL generation” on page 1“Link edit part” on page 269Related reference

“Output of COBOL program generation” on page 275“destLibrary” on page 317“projectID” on page 344“system” on page 226

CICS table files

EGL produces CICS table files when you are generating a COBOL program, butonly if you request them when you set the cicsEntries build descriptor option.Output can be in either of the following forms, depending on the value youspecify for the cicsEntries build descriptor option:v CICS program properties table (PPT) and program control table (PCT)v CICS RDO PROGRAM and RDO TRANSACTION entries

You must review the information generated in each table file, possibly makechanges, and add the information to the appropriate CICS table on the targetplatform.

Related concepts

“Output of COBOL program generation” on page 275Related reference

“cicsEntries” on page 304“Results file”

Results file

The results file contains status information on the code-preparation steps that weredone on the target environment. You receive the file only if EGL attempts toprepare generated output. If you are preparing a COBOL program, you alsoreceive a file for each step in the preparation process.


Preparation occurs automatically when you generate source code into a directoryand use the following build descriptor options:v prep is set to YESv buildPlan is set to YES

For information about the name of the results file and the additional files providedto you after a COBOL program is prepared, see “Output of COBOL programgeneration” on page 275.

Related concepts

“Build descriptor part” on page 33“Output of COBOL program generation” on page 275Related reference

“buildPlan” on page 301“prep” on page 342

Modifying EGL build scripts for z/OS

EGL uses build scripts to manage the preparation process for z/OS. The buildscripts perform the following tasksv Compile and link for a COBOL program, including the code generated from an

EGL program, library, service, FormGroup,or DataTable part.v DB2 precompile and bind if a program, library or service performs SQL I/O.v CICS translation if a program, library or service is generated for the z/OS CICS

environment.

These build scripts are developed using pseudo-JCL, a form of JCL with somerestrictions and a few extensions, as described in “Pseudo-JCL syntax” on page287.

The build server reads the pseudo-JCL and processes it to invoke the buildprogram against the data sets specified in the program. Because the build scriptsreference data sets that contain the location of the DB2 preprocessor, the CICStranslator, the COBOL compiler, and the z/OS linkage editor, you need to modifythe shipped build scripts to at least specify the actual locations of thesecode-preparation components.

To modify EGL build scripts for z/OS:1. Open the PROCLIB on the System 390 build server. (For information about

installing the z/OS build server, see the IBM Rational COBOL Runtime Guidefor zSeries.)

2. Select the member (build script) that you want to edit.3. Edit the member. For information about the predefined symbolic parameters

that are always passed as environment variables when you build output forz/OS environments, see “Predefined symbolic parameters that are setautomatically” on page 250. For a list of substitution variables defined withinEGL build scripts, see “Predefined symbolic parameters that can be set by theuser” on page 252.

4. Save the member.


Examples of modifying EGL build scriptsThe following examples show common modifications that you can make to EGLbuild scripts.

Modifying location of build components used by EGL buildscripts

It is likely that the PDS naming conventions for the compiler, linkage editor, anddatabase libraries are not the same as those used in the EGL build scripts. Tochange the default values, you must modify the VARS statement in the EGL buildscripts. The following example shows the VARS statement for the default CICS andCOBOL compiler libraries://DEFAULTS VARS EZEPID=USER,// COBCICS=SYS1.SCEECICS,// COBCOMP=SYS1.IGY.SIGYCOMP,// COBLIB=SYS1.SCEELKED,...

To change the high level qualifier for these libraries to MYSYS, you would use thefollowing syntax to change the VARS statement://DEFAULTS VARS EZEPID=USER,// COBCICS=MYSYS.SCEECICS,// COBCOMP=MYSYS.IGY.SIGYCOMP,// COBLIB=MYSYS.SCEELKED,...

Alternatively, you can leave the values of COBCICS, COBCOMP, and COBLIB setto the defaults in the build scripts and set the corresponding predefined symbolicparameters COBCICS, COBCOMP, and COBLIB in the EGL build descriptor partsto the values you need.

You can make similar updates for the EGL libraries (ELA substitution variable) andthe database libraries (DSNEXIT and DSNLOAD substitution variables) either inthe build scripts or by setting the corresponding predefined symbolic parametersin the EGL build descriptor parts.

Modifying EGL build scripts to save generated COBOL source

By default, the FDABCL, FDABPTCL, FDABTCL, FDACL, FDAPCL, FDAPTCL,and FDATCL build scripts do not save the generated source code on the buildserver. If you want to save the source code, you can uncomment statements in theUPLOAD step of these build scripts to cause the COBOL source to be saved in theuser EZESRC data set. For example, consider the following statements in theFDACL build script ://*UPLOAD EXEC PGM=IEFBR14//*EZESRC DD DSN=&EZEPID..&SYSTEM..EZESRC,DISP=SHR,CCUEXT=CBL

Uncomment the statements as follows://UPLOAD EXEC PGM=IEFBR14//EZESRC DD DSN=&EZEPID..&SYSTEM..EZESRC,DISP=SHR,CCUEXT=CBL

Options required in EGL build scriptsIn EGL build scripts, certain preparation options are required if you are using DB2UDB, the CICS translator, or the COBOL compiler for z/OS.


Required options for DB2 precompiler

The following options are required for DB2 usage and are included in the FDAPCLand FDAPTCL build scripts:v HOST(COB2)v APOSTSQLv QUOTE

Required options for CICS translator

The following options are required for CICS usage and are included in theFDAPTCL and FDATCL build scripts:v COBOL2v NOSEQv QUOTEv SP

The DBCS option is required for the CICS translator when DBCHAR or MBCHARvariables or literals are used. The build scripts automatically include this optionbased on the setting of the predefined symbolic parameter EZEDBCS, which inturn is set based on the use of DBCHAR or MBCHAR

Required options for COBOL compiler for z/OS

The following options are required for the z/OS COBOL compiler and areincluded in the FDABCL, FDABPTCL, FDABTCL, FDACL, FDAPCL, FDAPTCL,and FDATCL build scripts:v LIBv NODYNAM (as further described later)v NUMPROC(NOPFD)v NOSEQv QUOTEv RENTv TRUNC(BIN)

Also, the DBCS option is required for the COBOL compiler when DBCHAR orMBCHAR variables or literals are used. The build scripts automatically include thisoption based on the setting of the predefined symbolic parameter EZEDBCS, whichin turn is set based on the use of DBCHAR or MBCHAR.

The NODYNAM compiler option enables static linking of the IBM RationalCOBOL Runtime for zSeries stub program with the generated COBOL program.Calls to other programs can be dynamic depending on whether the COBOL call isgenerated as a CALL IDENTIFIER or CALL LITERAL:v CALL IDENTIFIER is always a dynamic call. EGL generates this type of call for

a call or transfer to program statement when you use the default linkage in anon-CICS environment. EGL also uses CALL IDENTIFIER for calls to DataTableprograms and FormGroup print services programs. This usage lets you togenerate Data Tables and FormGroups containing print forms independently ofthe programs that use them.

v CALL LITERAL is either a dynamic or static call based on the compiler option.EGL generates this type of call for a call or transfer to program statement when


you request static linkage. EGL also generates this type of call for calls to IBMRational COBOL Runtime for zSeries modules. The following IBM RationalCOBOL Runtime for zSeries modules are statically linked:– A few modules that are used frequently– A stub module that dynamically links to the major runtime functionsEGL requires the NODYNAM compiler option so that all CALL LITERALstatements are treated as static calls.

Compiler options controlled by build descriptor options

The following COBOL compiler options are included in the build scripts. You canchange their values by setting build descriptor options:v The ARITH compiler option specifies the size of numeric fields. You can control

the setting for the ARITH compiler option by setting the maxNumericDigitsbuild descriptor option to 31 for ARITH(EXTEND), or to 18 for ARITH(COMPAT). EXTEND increases the maximum number of digits for numericitems from 18 to 31 and also affects how intermediate results are computed. Thedefault for the build descriptor option is 31.

v The DATA compiler option specifies the whether data areas are acquired aboveor below the 16 MB boundary. You can control the setting for the DATAcompiler option by setting the data build descriptor option to 24 for DATA(24),or to 31 for DATA(31). The default for the build descriptor option is 31.

Other COBOL compiler options in build scripts for z/OS

The following compiler option is included in the build scripts, and you can removethe option:v The OPTIMIZE compiler option provides faster runtime performance, but can

significantly increase the compile time. Consider using the NOOPTIMIZE optionduring testing and the OPTIMIZE option when moving the program toproduction.

COBOL compiler options not found in build scripts for z/OSThe following compiler options are not included in the build scripts, but youmight find them to be useful:v Listing Options. You can set the COBLISTPARMS predefined symbolic

parameter to specify the combination of LIST, MAP, and OFFSET that yourequire. The build scripts default COBLISTPARMS to NOLIST.– LIST

Produces an assembler language expansion of the COBOL source code.– MAP

Produces a listing of information from the COBOL DATA DIVISION,including a DATA DIVISION map, global tables, literal pools, nested programstructure map, and program attributes.

– OFFSETProduces a cross-reference listing of the hexadecimal offsets in the moduleand the corresponding COBOL statement number. This is recommended tohelp you while you are debugging your program in the runtime environment.

v SSRANGEProvides runtime subscript checking. NOSSRANGE eliminates runtime subscriptchecking. Because using NOSSRANGE can result in better performance, specifyNOSSRANGE when you move the program to production.


v TESTProduces object code that enables Debug Tool to perform batch and interactivedebugging in your runtime environment.

For details on COBOL compiler options, refer to your compiler documentation.

COBOL compiler options that are not supportedThe COBOL compiler option NAME is not supported.

Related concepts

“Build scripts” on page 105Related reference

“Build scripts delivered with EGL”“data” on page 308“maxNumericDigits” on page 337“Predefined symbolic parameters that can be set by the user” on page 252“Predefined symbolic parameters that are set automatically” on page 250“Pseudo-JCL syntax” on page 287

Build scripts delivered with EGL

The following EGL build scripts are placed in the PROCLIB library of a z/OS buildserver (allocated by DDNAME CCUPROC) when the EGL build server is installed.

FDABCLInvokes the COBOL compiler and the z/OS linkage editor to prepare z/OSBatch, IMSVS, and IMSBMP output when the DB2 preprocessor is notrequired.

FDABINDBinds a generated program to a database. This build script is used inconjunction with FDAPTCL for EGL-generated source code that runs in aCICS environment and that performs SQL I/O or with FDAPCL forEGL-generated source code that runs in z/OS Batch and that performsSQL I/O.

A build server cannot first run a non-authorized program (such as acompiler) and then switch to an authorized program (such as TSO). Thedatabase bind runs in a TSO environment. Therefore, the bind build scriptis run as a separate (but dependent) build request from the compile andlink edit request.

FDABPTCLInvokes the DB2 preprocessor, the CICS translator, the COBOL compiler,and the z/OS linkage editor for generated z/OS batch programs makingCICS EXCI calls.

FDABTCLInvokes the CICS translator, the COBOL compiler, and the z/OS linkageeditor for generated z/OS batch programs making CICS EXCI calls.

FDACLInvokes the COBOL compiler and the z/OS linkage editor for generatedCOBOL source code that does not require the CICS translator or the DB2preprocessor, such as a generated DataTable or a generated print servicesprogram for a FormGroup.


FDALINKInvokes the z/OS linkage editor for a format module.

FDAMFSInvokes the MFS compiler for FormGroups generated for IMS/VS or onIMS BMP if the formServicePgmType build descriptor option is set to ALLor MFS.

FDAPCLInvokes the DB2 preprocessor, the COBOL compiler and the z/OS linkageeditor to prepare z/OS Batch output when the DB2 preprocessor isrequired.

FDAPTCLInvokes the DB2 preprocessor, the CICS translator, the COBOL compiler,and the z/OS linkage editor for EGL-generated source code that runs in aCICS environment and that performs SQL I/O.

FDATCLInvokes the CICS translator, the COBOL compiler, and the z/OS linkageeditor for source code generated from an EGL program part that runs in aCICS environment and that does not perform SQL I/O.

On iSeries, the EGL build server invokes the FDAPREP build script. The scriptnormally resides in the QEGL/REXSRC file but can be copied to another locationand customized.

Related concepts

“Build scripts” on page 105Related tasks


“projectID” on page 344

Pseudo-JCL syntaxThe build scripts for z/OS contain pseudo-JCL.

Pseudo-JCL used by the z/OS build server is similar to standard JCL inappearance, with some extensions and restrictions. In this topic, a line of script (aline of pseudo-JCL) is referred to as a card.

These are the major differences between the pseudo-JCL that is used in z/OS buildscripts and the JCL that is used to submit an z/OS job:v Pseudo-JCL has no job card.v All cards must start with two forward slashes (//), except for in-stream data.v You can map a data set to input files that are sent from a build client or to files

that are to be returned to a build client as output files. (The keyword CCUEXTis an extension for DD statements that supports this mapping.)

v You can use the ENQ extension on a DD card to enqueue on the name of thedata set allocated by the DD card.

v You can supply default values for substitution variables that are used within thebuild script. (The VARS statement supports this.) Thus you can write a genericscript and modify it for a particular build by setting the substitution variables.


v You have more flexibility in specifying conditions for running a job. Forexample, the method of specifying multiple conditions on which a step is to berun is different from that of actual JCL.

v The build script contains one or more job steps. The execution of a job step canbe dependent on the result of a prior step, using the COND parameter as instandard JCL with one difference: In pseudo-JCL, if you want to specifyconditions on more than one step of the job, you specify a COND= keyword foreach condition.

The following types of cards are supported:

CALL Defines a new job step and specify an external JCL job to run.

EXEC Defines a new job step and the name of the program to run.

DD Defines the definitions for input and output files.

IF, ELSE, ENDIFControls statements that are included.

IF Specifies the condition and is the start of the conditionalstatements.

ELSE Specifies what is done, if the condition is not true.

ENDIFIndicates the end of the conditional statements.

VARS Specifies default values for substitution values.Related concepts

“Build scripts” on page 105Related tasks

“Modifying EGL build scripts for z/OS” on page 282Related tasks

“CALL statement”“DD statement” on page 290“EXEC statement” on page 294“IF statement” on page 296“VARS statement” on page 297

CALL statementDefines a new job step and specifies the external JCL job to run.

Syntax

/ / CALL MEMBER=jcllabel

,WAIT=YES

COND ( code opstep

),,

=

,WAIT=NO

,


Parameters

labelThe step name.

MEMBERThe external JCL file to run. Specify either a fully qualified sequential data setor a member of a PDS specified in the DD statement labeled CCUPROC.

WAITSpecifies whether the build server should wait for the completion of this stepbefore executing the next step.

yes

no (the default value)

COND

code The value to test against the return code in a prior step.

op The comparison operator.

step The name of the step that issues the return code.

Consider the following issues when calling external JCL from pseudo-JCL:v If WAIT=NO is specified (or is implied by default) the build continues with any

following step, with the return condition of the called JCL assumed to be 0. Inthis case the called JCL job completes independently and the build server isunaware of that execution.

v If WAIT=YES is specified, there must be a variable defined, with the followinginformation defined in the VARS card:

CCULIB=buildServerLoadLibrary

buildServerLoadLibraryThe build server load library.

v For WAIT=YES, the JCL to be submitted is modified by the build server, whichadds a step at the end to capture the job termination. This step writes a value toa temporary data set based on the return code of the last step in the submittedjob. The build server uses this value for the return code of the step.Only the following return codes are possible:0, 4, 8, 12, 16, 20

The job must end normally for the return code to be available. If the job endswith a return code other than one of those previously mentioned, the code is setto 20. The build server waits for up to 2 minutes for the job to complete, afterwhich the build server assumes that the job completed with return code 20.

v The content of the JCL file is expected to be a standalone job stream, with anappropriate job card.

v The specified JCL is submitted for execution after being modified to substituteany variables known to the pseudo-JCL.

Example

The following example shows a pseudo-JCL file that uses the CALL statement:


//V VARS CCULIB=SYS1.SCCULOAD//T0 EXEC PGM=IEFBR14//T1 CALL MEMBER=MISC.JCL(COBCOMP),WAIT=YES,COND=(0,EQ,T0)

//T2 EXEC PGM=IEFBR14,COND=(0,EQ,T1)//

Related concepts

“Pseudo-JCL syntax” on page 287“Build scripts” on page 105Related tasks


“DD statement”“EXEC statement” on page 294“IF statement” on page 296“VARS statement” on page 297

DD statementDefines the data definition for any input or output files. The file can be any one ofthe following:v In-stream data which follows a DD * statement and is terminated by /*

v An MVS data setv A file on the HFS file system, using the HFSPATH keyword. If you use the

HFSPATH keyword, the only other allowed keyword is CCUEXT.


Syntax

/ /

DD

DD

VIO

DSN

,DCB LRECL

,DSORG

,VOL

,CCUEXT

CCUOUT

,ENQNOYES

CCUSTD

CCUERR

,UNIT

BLKSIZE RECFMrlen

SER

dataSetOrganization

volume

extension

unitType

extension

unit prisec dir RLSE CONTIG

bsize rfmt

DISP

DSN

label

SYSIN

dsn,stat

statndisp

adispDSNAME

DSNAME

==

( )

) )

,,

(

(

(

)

)

( ,, ,

,

, ,

, ,=

=

=

=

=

=

=

,SPACE =

= =

=

dsn=

*

HFSPATH = hfsPathName

Parameters

labelThe DD name.

DSN or DSNAMEThe name of the data set. You can either choose this parameter, or choose theHFSPATH parameter, but not both.

HFSPATH = hfsPathNameThe path to the HFS directory. Only the CCUEXT parameter can be used withHFSPATH.

DISP

statThe status: NEW (the default), OLD, SHR (shared), or MOD (modified).


ndispThe normal dispositions: DELETE, KEEP (the default), CATLG (catalog),or UNCATLG (uncatalog).

adispThe abnormal dispositions: DELETE, KEEP (the default), CATLG (catalog),or UNCATLG (uncatalog).

DCB

LRECLThe record length in bytes.

BLKSIZEThe block size in bytes.

RECFMThe record format.

DSORG = dataSetOrganizationSpecifies the data set organization. The following values are valid:

PS The sequential data set.

PO The partitioned data set.

UNIT = unitTypeThe type of media for the output. Valid values are:

VIO Virtual I/O

unitTypeThe name of a device on the system

SPACE = unitTypeThe unit type. The following values are valid:

unitThe allocation unit: TRK, CYL, or a number equal to the block size.

pri The primary number of allocation units.

sec The secondary number of allocation units.

dir The number of directory blocks for PDS allocations.

RLSESpecifies that unused space should be released when the data set is closed.

CONTIGSpecifies that the space allocated should contiguous.

VOL = SER = volumeSpecifies the volume where you want the data set allocated. When DSNspecifies a permanent data set name and DISP specifies NEW, the systemassigned volume is used by default.

CCUEXTSpecifies a file name extension and is used to map the input, output, andmessage file names to the target DDNAME. For example://USERLIB DD DSN=MY.HEADERS,DISP=SHR,CCUEXT=(H,HPP)

extensionSpecifies that all input files with h and .hpp extensions (not case sensitive),will be placed in the data set allocated to DDNAME USERLIB. The sameextension can appear only once in the pseudo-JCL script.


CCUOUTSpecifies that the corresponding DDNAME is a sequential data set ormember of a partitioned data set (typically containing message listings)which needs to be returned to the build client. For example://COMPILE EXEC PGM=CBCDRVR,..//SYSIN ..//SYSOUT DD CCUEXT=CCUOUT,DISP=(NEW,DELETE),SPACE=(32000,(30,30)),// DCB=(RECFM=VB,LRECL=137,BLKSIZE=882)

After the program CBCDRVR is executed, the contents of SYSOUT will beread and returned to the client as the COMPILE.SYSOUT file in the client’sfile system.

CCUSTDSpecifies that DDNAMEs designated with this value will be written toSTDOUT on the build client. For example://COMPILE EXEC PGM=CBCDRVR,..//SYSIN ..//SYSOUT DD CCUEXT=CCUSTD,DISP=(NEW,DELETE),SPACE=(32000,(30,30)),// DCB=(RECFM=VB,LRECL=137,BLKSIZE=882)

After the program CBCDRVR is executed, the contents of SYSOUT will beread, placed on STDOUT and returned to the client as theCOMPILE.SYSOUT file in the client’s file system

CCUERRSpecifies that DDNAMEs designated with this value will be placed on theSTDERR by the ccubldc client. For example://COMPILE EXEC PGM=CBCDRVR,..//SYSIN ..//SYSOUT DD CCUEXT=CCUERR,DISP=(NEW,DELETE),SPACE=(32000,(30,30)),// DCB=(RECFM=VB,LRECL=137,BLKSIZE=882)

After the program CBCDRVR is executed, the contents of SYSOUT will beread, placed on STDERR, and returned to the client as theCOMPILE.SYSOUT file in the client’s file system.

ENQIf set to YES, tells the build server to enqueue on the name of the data set theDD card allocates. This is sometimes necessary when the build script writes toa partitioned data set that can be accessed concurrently by more than one buildrequest. If a build script enqueues on a data set name that was previouslyenqueued by a build script that is still active, the build script is placed on aqueue and retried periodically. This can possibly cause a time-out of the buildrequest if a large number of concurrent build requests are enqueing on thesame data set name.

Examples

Here is an example of a DD statement used with a temporary MVS dataset, withno DSN://* MVS Dataset, temporary with no DSN//SYSIN DD CCUEXT=(C,CPP),DISP=(NEW,DELETE),// UNIT=VIO,SPACE=(TRK,(10,5)),// DCB+(RECFM=VB,LRECL=256,BLKSIZE=2560)

Here is an example of a DD statement used with an already existing MVS data set://* MVS Dataset, already existing//STEPLIB DD DSNAME=CEE.SCEERUN,DISP=SHR


Here is an example of a DD statement that is using the HFS file system://* HFS file. The input files with extension=WSDL will be written to//* this directory. The output files with extension=WSDL will be copied//* from this directory.//MYXML DD HFSPATH=&EZEDESTDIR,CCUEXT=(WSDL)

Related concepts



“CALL statement” on page 288“EXEC statement”“IF statement” on page 296“VARS statement” on page 297

EXEC statementDefines a new job step and specifies the name of the program to run.

Syntax

/ / EXEC PGMlabel program

script name

=

,PARM, ,

parameter string=

,COND ( code opstep

),,

=

,AUTH

NO

= YES

,IGNORERC

NO

YES=

Parameters

labelThe step name.

PGMSpecifies the name of an executable load module.


script nameSpecifies the name of an existing pseudo-JCL script in the PDS allocated bydata definition name (DDNAME) CCUPROC when the build server is started.

PARMSpecifies a parameter string that can contain embedded spaces and quotationmarks. If you want to embed a quotation mark in the string, enter it betweenapostrophes ('"') or as two quotation marks (""). If you want to embed anapostrophe in the string, enter it as two apostrophes. For example, if the valueof the substitution variable X is it and your pseudo-JCL has the fieldPARM='&X''s', the field in your pseudo-JCL acquires the following value:PARM='it's'

AUTHIndicates that the program to be executed is an APF authorized program.

YES (the default value)The program is an APF authorized program.

NOThe program is not an APF authorized program.

CONDThe following values apply:

codeThe value to test against the return code in a specified prior step.

op The comparison operator.

stepThe name of the step that issues the return code.

IGNORERCThe following values are available:

YESTells the build server to ignore the return code from this step of the buildscript.

NO (the default value)Tells the build server not to ignore the return code from the build script.The return code of the last step without IGNORERC=YES is the returncode of the build.

For example, you might wish to have a final step in your build script, such asa cleanup of allocated temporary datasets, that takes place whether the buildwas successful or not. If so, the build server should not use the return codefrom this step to determine whether the build succeeded.

You can use substitution variables to modify the cards.Related concepts



“CALL statement” on page 288“DD statement” on page 290


“IF statement”“VARS statement” on page 297

IF statementAllows conditional inclusion of pseudo-JCL statements. When using the IFstatement, consider the following limitations:v Nesting is not supported.v The IF cards are processed statically before the steps are executed.v Only strings can be compared.

Syntax

Parameters

labelIs ignored, but must be present.

op1, op2Variable names or strings.

codeOne of the following values:v EQ

v NE

pseudo-JCLOne or more pseudo-JCL statements (except IF statements) to be executed ifthe stated conditions are met.

Example:


//SYSLIB DD DISP=SHR,DSN=&COBLIB//X IF &SYSTEM..EQ.IMSVS// DD DISP=SHR,DSN=&RESLIB//X ENDIF

Related concepts



“CALL statement” on page 288“DD statement” on page 290“EXEC statement” on page 294“VARS statement”

VARS statementSpecifies default values for substitution variables.

Syntax

/ / VARS name

,

label value=

Parameters

labelThe step name.

nameThe name of a substitution variable.

valueThe value of the substitution variable specified for the name parameter. Thevalue must be a string.

Example//DEFAULTS VARS EZEPID=USER,// SYSTEM=ZOSCICS

Related concepts



“CALL statement” on page 288“DD statement” on page 290“EXEC statement” on page 294“IF statement” on page 296


Modifying EGL build scripts for iSeries

EGL uses a build script to manage the preparation process for iSeries. The buildscript is named FDAPREP and resides in the iSeries library QEGL/QREXSRC. Asystem administrator must customize the build script, as described in the IBMRational Business Developer EGL Server Guide for IBM i.

Preparing for deployment

After you have generated and prepared your programs, there are additionalactivities involved in setting up the runtime environment. These activities includethe following:v Defining programs and transactions for CICSv Defining files, temporary storage queues, and transient data queues for CICSv Defining applications and transactions for IMSv Customizing the sample runtime JCL for z/OS Batch and IMS BMP.v Customizing the sample runtime CL for iSeries.

For more information about these topics, please consult the following documents:v For z/OS, if you are using the IBM Rational COBOL Runtime for zSeries

product, see the IBM Rational COBOL Runtime Guide for zSeries. This bookdescribes how to set up build servers and build scripts, as well as otherreference material for creating your runtime environment. The equivalent booksfor WebSphere Application Server are the WebSphere Developer for zSeries HostConfiguration Guide and the IBM Rational COBOL Runtime Guide for zSeries.

v For iSeries, see the IBM Rational Business Developer EGL Server Guide for IBMi.


Build descriptor options

This section contains topics that describe the build descriptor options that are usedwith Java and COBOL generation. For a list of all of these options, along with theirdefault settings and target platforms, see “Build descriptor options” on page 41.The topics in this section give details about what each option does, the settingsavailable for that option, and what the default setting is, if the option has adefault.

For a list specific to Java generation, see “Build descriptor options used with Java”on page 144.

For a list specific to COBOL generation, see “Build descriptor options used withCOBOL” on page 234.

bidiConversionTable

The bidiConversionTable build descriptor option identifies a bidirectionalconversion table, which is needed to handle literals that contain Arabic or Hebrewcharacters. Set this option in the following cases:v You generate a COBOL program that contains those literals; orv You generate Java code that requires those literals to be in visual rather than

logical order, as is the case when the code accesses files or databases that storethose literals in visual order.

For more information, see Working with bidirectional data.Related concepts

Working with bidirectional data“Build descriptor part” on page 33“Data conversion” on page 85Related reference

“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234

bidiRuntime

The bidiRuntime build descriptor option identifies a bidirectional runtime file,which contains options that control the bidirectional behavior for the fields in theform groups associated with an application. Use this option in preference to settingindividual properties to control bidi behavior.

The value of this option is a path name to the runtime file.

For more information, see Working with bidirectional data. For information on thecontents and the creation process of the bidirectional runtime file, see Creating abidirectional runtime file.

Related concepts

Working with bidirectional data“Build descriptor part” on page 33


“Data conversion” on page 85Related tasks

Creating a bidirectional runtime fileYou can use an EGL wizard to create a bidirectional runtime file.Related reference


bind

When you generate a COBOL program for z/OS, the bind build descriptor optionidentifies the bind control part for a program on z/OS that accesses SQL tables onDB2.v If a value is specified for this option, EGL searches for a bind control part with a

name matching that value. Depending on the results of the search, one of thefollowing events occurs:– If the bind control part is found, its contents are used to create a bind control

file that is used in preparation of the program. EGL replaces any symbolicparameters in the bind control file with the appropriate values, as describedin “Symbolic parameters used with COBOL generation” on page 246.

– If the bind control part is not found, a generation error occurs.v If a value is not specified for this option, EGL searches for a bind control part

with the same name as the program being generated. Depending on the resultsof the search, one of the following occurs:– If a bind control part is found with the same name as the program, its

contents are used to create a bind control file that is used in preparation ofthe program. EGL replaces any symbolic parameters in the bind control filewith the appropriate values, as described in “Symbolic parameters used withCOBOL generation” on page 246.

– If a bind control part is not found with the same name as the program, EGLgenerates a bind control file that references the DBRM of the program beinggenerated and any other DBRM that is needed by the EGL runtime.

You can use your own symbolic parameters or any predefined symbolicparameters in the bind control part.

Related concepts

“Bind control part” on page 264“Build descriptor part” on page 33“Generation output and associated files” on page 91“Symbolic parameters used with COBOL generation” on page 246Related tasks

“Adding a bind control part to an EGL build file” on page 268Related reference

“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“Predefined symbolic parameters that are set automatically” on page 250“Predefined symbolic parameters that can be set by the user” on page 252


birtEngineHome

The birtEngineHome build descriptor option identifies the location of the BusinessIntelligence and Reporting Tools (BIRT) report engine. You must set this optionbefore you can work with BIRT in a General project. The requirement does notapply to a Plug-in project.

The value of the birtEngineHome option is the fully qualified path of theReportEngine subdirectory in the directory that contains the BIRT runtime code.An example is C:\birt\birt-runtime-2_3_0\ReportEngine. The option has nodefault.

Note: Rational Business Developer 7.5 supports BIRT version 2.3.0 and no others.

For details on installing the BIRT runtime code and on other setup issues, see″Adding support for BIRT reports to a project″ in the Programmer’s Guide.

Related concepts

“Build descriptor part” on page 33Creating reports with BIRTBusiness Intelligence and Reporting Tools (BIRT) is an Eclipse-based reportingsystem that allows for sophisticated output in PDF or HTML format, includinggraphics, tables, graphs, and charts. EGL support for BIRT is available whenyou code either JSF handlers or programs generated for Java.Related tasks

Adding support for BIRT reports to a projectBefore your EGL code can create BIRT reports, you must add support to yourproject. You need to add support only once for each project, and you do notneed to remove support if you stop using BIRT reports. During this beta,support is available for General and Plug-in projects.Related reference


buildPlan

The buildPlan build descriptor option specifies whether a build plan is createdduring the generation process. The build plan is placed in the directory identifiedby genDirectory build descriptor option.

If you are generating Java code into a project, no build plan is created, regardlessof whether the buildPlan build descriptor option is YES or NO, but preparationoccurs in either of two situations:v Whenever you build the project.v Whenever you generate the source files; but only if you selected the workbench

preference Build automatically. To set this preference:1. Click Window → Preferences to open the Preferences window.2. At the left side of the Preferences window, expand General and click

Workspace.3. Select the Build automatically check box if you want EGL to build your files

automatically. When you select this preference, EGL performs a buildwhenever you save a file. This means that EGL validates any parts of the file


that have changed, and any other parts in the project that are called by thechanged part. Validation is done without using a build descriptor part.

You can create a build plan and invoke the plan at a later time. For details, see“Using a build plan after generation” on page 103.

Values

YES (the default value)Creates a build plan based on the build descriptor options.

NO No build plan is created.Related concepts

“Build descriptor part” on page 33“Build plan” on page 103Related tasks

“Using a build plan after generation” on page 103Related reference


cancelAfterTransfer

When you generate a COBOL program for z/OS, the cancelAfterTransfer builddescriptor option indicates whether an EGL-generated program is removed frommemory when both of the following occur:v The program issues a transfer to program statement.v A dynamic linkage is involved; in particular, the build descriptor identifies a

linkage options part in which a transferToProgram element is in effect for thetransfer, and the linkType property for that element is set to DYNAMIC.

Values

YES Places a COBOL CANCEL in the transferring program.

NO (the default value)Does not place a COBOL CANCEL in the transferring program.

Related concepts



checkIndices

The checkIndices build descriptor option specifies whether to include thefollowing checks in generated COBOL programs:v Check array and substring indexes to ensure they are in the range that is valid

for the variable. If not, EGL throws an IndexOutOfBoundsException.v Check dynamic array variables to ensure they have been initialized. If not, EGL

throws a NullValueException.


Setting this option to not support these checks might result in smaller programswith better performance.

Values

YES (the default value)Specifies that the generated EGL COBOL program should include checksfor index range and null values in array variables.

NO Specifies that index range and null value checking is not included in thegenerated program. If you specify NO, you must be sure not to use anyindexes outside the defined range for the array, and take care that youinitialize dynamic arrays before using them. If you fail to do so, the resultsare unpredictable.

Related concepts



checkNumericOverflow

When you generate a COBOL program, the checkNumericOverflow builddescriptor option specifies whether to support numeric overflow checking in thegenerated program.

Setting this option to not support overflow checking might result in smallerprograms with better performance.

Values

YES (the default value)Specifies that numeric overflow checking is supported.

NO Specifies that numeric overflow checking is not supported. If you specifyNO, the vgVar.handleOverflow system variable is ignored. Division byzero results in an abend with a message. In other overflow conditions, theresult is truncated, causing the significant digits to be lost, but thegenerated program gives no indication that truncation has occurred.Design your program such that numeric overflow does not occur.

Related concepts



checkToTransaction

When you generate a COBOL program, the checkToTransaction build descriptoroption indicates whether a special check is included in an EGL-generated CICSprogram that issues a transfer to transaction statement. The check uses the CICSsystem programming command INQUIRE to determine whether the destinationtransaction is defined to the system.


Values

YES (the default value)The program checks for the transaction definition. If the definition isabsent, the program ends immediately, without an abend.

NO The program does not check for the transaction definition. If the definitionis absent, the program will stop.

Specify NO only if your organization does not allow use of programs thatissue CICS system programming commands.

Related concepts



checkType

When you generate a COBOL program, the checkType build descriptor specifiesthe degree to which EGL checks at validation time for primitive-type conflictswithin records. For example, EGL issues an information message if a structure fieldthat is of type CHAR is substructured with structure items of type DECIMAL.Such conflicts can cause runtime errors.

Note: Specifying a value other than NONE increases both the time needed forvalidation and the number of messages issued.

Values

NONE (the default value)Specify NONE if you do not want to check for potential conflicts in theprimitive types of substructured fields.

LOW Checks for conflicting primitive types only in the fields that aresubordinate to the highest level of the structure.

Using the example below, if you specify LOW, EGL does not compareFieldA to FieldB, but does compare FieldB to FieldC, and FieldC to FieldD.10 FieldA

15 FieldB20 FieldC

30 FieldD

ALL Checks for conflicting primitive types in all levels of a substructured field.Related concepts



cicsEntries

When you generate a COBOL program for CICS, the cicsEntries build descriptoroption specifies whether to produce CICS program and transaction definitions; andif so, in what format. EGL might produce definitions for these CICS transactions:


v The value of startTransactionID identifies the transaction ID, which by default isthe first four characters of the program alias or, in the absence of an alias, thefirst four characters of the program name.

v For a program that runs in a Text UI or Web Transaction program, EGL producesdefinitions for a restart transaction, as described in restartTransactionID.

Values

NONE (the default value)Does not generate CICS definitions.

RDO Generates resource definition online (RDO) program and transactiondefinitions.

MACROGenerates CICS DFHPPT statements for the program properties table andDFHPCT statements for the program control table.

Related concepts


“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“CICS table files” on page 281

cicsj2cTimeout

When you generate Java code, the cicsj2cTimeout build descriptor option assigns avalue to the cso.cicsj2c.timeout Java runtime property, but only if thegenProperties build descriptor option is set to GLOBAL or LOCAL. That propertyspecifies the number of milliseconds before a timeout occurs during a call that usesthe CICSJ2C protocol.

The default value of the runtime property is 30000, which represents 30 seconds. Ifthe value is set to 0, no timeout occurs. The value must be greater than or equal to0.

The cso.cicsj2c.timeout property has an effect on calls only when the callingprogram is deployed to a J2EE environment and the called program is deployed toa CICS environment.

Related concepts


“Setting up the J2EE server for CICSJ2C calls” on page 189Related reference

“Build descriptor options” on page 41“Build descriptor options used with Java” on page 144“genProperties” on page 326


clientCodeSet

When you generate a COBOL program, the clientCodeSet build descriptor optionspecifies the name of the coded character set that is in effect on the workstation.This option, along with the serverCodeSet build descriptor option, causes aparticular data conversion to occur when file content, file-path information, andenvironment variables are transferred from the workstation to a z/OS or an iSeriesbuild server.

The coded character set specified for clientCodeSet must be the one defined to theICONV conversion service on the system where the build server is started. Thedefault is IBM-850, which is a standard character set for Latin-1 countries. Fordetails, see “Data conversion” on page 85.

Related concepts


“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“serverCodeSet” on page 349“Data conversion” on page 85

commentLevel

The commentLevel build descriptor option specifies the extent to which EGLsystem comments are included in output source code.

Raising the comment level has no effect on the size or performance of the preparedcode, but increases the size of the output and the time needed to generate, transfer,and prepare the output.

Values

0 Minimal comments are in the output, which includes comments on anyname aliases that EGL generates (this is only in effect for COBOLgeneration, not for Java).

1 (the default value)In addition to the comments included with level 0, scripting statements areplaced immediately before the code that is generated to implement thosestatements.

Related concepts




currencyLocation

When you generate Java code, the currencyLocation build descriptor option isused when you need to determine the location of a currency symbol in a stringrepresenting a monetary value. This option determines whether the currencysymbol is placed at the front, back, or whether there is no symbol locationdesignated.

The currencyLocation build descriptor option assigns a character to thevgj.nls.currency.location Java runtime property, but only if the genProperties builddescriptor option is set to GLOBAL or PROGRAM.

Values

NONE (the default value)No symbol location is designated.

FRONTThe currency symbol is placed at the front of the numeric string.

BACK The currency symbol is placed at the end of the numeric string.Related concepts



currencySymbol

The currencySymbol build descriptor option specifies a currency symbol that iscomposed of one to three characters. If you do not specify this option, the defaultvalue is derived from the locale of your system.

When you generate a COBOL program, the currencySymbol build descriptoroption is limited to 1 character. If you do not specify the currencySymbol builddescriptor option, the value is set by the currency symbol specified in thelanguage-dependent options module specified for your runtime installation. Forz/OS, refer to the program directory for your runtime product for details.

When you generate Java code, the currencySymbol build descriptor option assignsthe value to the vgj.nls.currency Java runtime property, but only if thegenProperties build descriptor option is set to GLOBAL or PROGRAM. If you donot specify the currencySymbol build descriptor option, the Java runtime propertyvalue is determined by the locale associated with the vgj.nls.code Java runtimeproperty.

The currencySymbol build descriptor option does not affect numbers in JSFhandlers. By default, JSF handlers use the client’s locale to determine theappropriate currency symbol. You can override the default locale with thesysLib.setLocale() system function. For more information about system functions,see the EGL Language Reference.


To specify a character that is not on your keyboard, hold down the Alt key anduse the numeric key pad to type the character’s decimal code. The decimal codefor the Euro, for example, is 0128 on Windows 2000/NT/XP.

Related concepts


“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“Build descriptor options used with Java” on page 144“genProperties” on page 326

data

When you generate a COBOL program for z/OS, the data build descriptor optionspecifies whether to use the DATA(24) or DATA(31) compile option to prepare agenerated COBOL program.

Values

31 (the default value)Specifies that the DATA(31) compile option is to be used.

24 Specifies that the DATA(24) compile option is to be used. You must specify24 for any program that is linked AMODE(24) or that is in the same rununit as another program that is linked AMODE(24).

For CICS for z/OS, you can specify 24–bit addressing only if the dynamicstorage required by the generated COBOL program, library, service, formservices program, or DataTable program is less than 64KB.

Related concepts



dbContentSeparator

When you generate Java code, the dbContentSeparator build descriptor optionspecifies the symbol used to separate one value from the next in thesqlLib.loadTable and sqlLib.unLoadTable system functions.

The value is copied to the vgj.default.databaseDelimiter Java runtime property. Ifno value is specified in that property at run time, the default value is a vertical bar(|).

Related concepts




dbms

When you generate Java code, the dbms build descriptor option specifies the typeof database that is accessed by the generated program.

Values

DB2 (the default value)For a DB2 database.

INFORMIXThis value is valid only for Java generation.

ORACLEThis value is valid only for Java generation.

SQLSERVERThis option is valid only if the target environment is Windows.

CLOUDSCAPEThis value is valid only for Java generation.

DERBYThis value is valid only for Java generation.

Related concepts



debugTrace

When you generate a COBOL program, the debugTrace build descriptor optionindicates whether or not to enable tracing of the generation process. Thegeneration trace information is embedded within the generated COBOL program.

You should use this option only when you are providing debugging information toIBM service personnel. Choosing the YES value for this option results in a large filecontaining very detailed information, which IBM developers can use in debuggingand resolving generation problems. However, you can also leave this option set toNO, and get partial debug tracing by performing the following actions:1. Find the section you want to debug.2. Place this line of code before that section: EZE("debugstart").3. Place this line of code after that section: EZE("debugstop").4. Generate the code

Values

YES Trace information is added to the COBOL source file.

NO (the default value)Trace information is not added to the COBOL source file.

Related concepts




decimalSymbol

The decimalSymbol build descriptor option specifies a character to be used as thedecimal symbol at runtime.

When you are generating a COBOL program, if you do not specify thedecimalSymbol build descriptor option, the value is set by the decimal pointcharacter specified in the language-dependent options module specified for yourruntime installation. For z/OS, refer to the program directory for your runtimeproduct for details.

When you are generating Java code, the decimalSymbol build descriptor optionassigns a character to the vgj.nls.number.decimal Java runtime property if thegenProperties build descriptor option is set to GLOBAL or PROGRAM. If you donot specify the decimalSymbol build descriptor option, the character is determinedby the locale associated with the vgj.nls.code Java runtime property.

The decimalSymbol build descriptor option does not affect numbers in JSFhandlers. By default, JSF handlers use the client’s locale to determine theappropriate decimal symbol. You can override the default locale with thesysLib.setLocale() system function. You can find more information on this andother system functions in the EGL Language Reference.

The value can be no more than one character.Related concepts



defaultDateFormat (build descriptor option)

The defaultDateFormat build descriptor option controls the initial runtime value ofthe strLib.defaultDateFormat system variable, which contains one of the masksthat can be used to create the string returned by the strLib.formatDate systemfunction. Other details depend on the target language:v When you are generating a COBOL program, if you do not specify the

defaultDateFormat build descriptor option, the default value for thestrLib.defaultDateFormat system variable is set by the ″Long Gregorian dateformat″ specified in the language-dependent options module specified for yourruntime installation. For z/OS, refer to the program directory for your runtimeproduct for details.

v When you are generating Java code, the defaultDateFormat build descriptoroption specifies the generated value for the vgj.default.dateFormat Java runtimeproperty (if you have set the genProperties build descriptor option to GLOBAL


or PROGRAM). That property then sets the initial runtime value of thestrLib.defaultDateFormat system variable.

v When you are generating JavaScript code, the default value of thedefaultDateFormat build descriptor option is MM/dd/yyyy.


Related concepts



defaultMoneyFormat (build descriptor option)

The defaultMoneyFormat build descriptor option controls the initial runtime valueof the strLib.defaultMoneyFormat system variable, which contains one of themasks that can be used to create the string returned by the strLib.formatNumbersystem function.

When you are generating a COBOL program, if you do not specify thedefaultMoneyFormat build descriptor option, the strLib.defaultMoneyFormatsystem variable does not have a default value.

When you are generating Java code, the defaultMoneyFormat build descriptoroption specifies the generated value for the vgj.default.moneyFormat Java runtimeproperty (if you have set the genProperties build descriptor option to GLOBAL orPROGRAM). That property then sets the initial runtime value of thestrLib.defaultMoneyFormat system variable.

You can find more information on system variables and system functions in theEGL Language Reference.

Related concepts




defaultNumericFormat (build descriptor option)

The defaultNumericFormat build descriptor option controls the initial runtimevalue of the strLib.defaultNumericFormat system variable, which contains one ofthe masks that can be used to create the string returned by thestrLib.formatNumber system function.

When you are generating a COBOL program, if you do not specify thedefaultNumericFormat build descriptor option, the strLib.defaultNumericFormatsystem variable does not have a default value.

When you are generating Java code, the defaultNumericFormat build descriptoroption specifies the generated value for the vgj.default.numericFormat Javaruntime property (if you have set the genProperties build descriptor option toGLOBAL or PROGRAM). That property then sets the initial runtime value of thestrLib.defaultNumericFormat system variable.

You can find more information on system variables and system functions in theEGL Language Reference.

Related concepts



defaultServiceTimeout

The defaultServiceTimeout build descriptor option specifies the maximum validnumber of milliseconds that elapse between the following events: when the EGLRich UI Proxy (on the Web server) invokes a service and when the Proxy receives aresponse. If more time elapses, the EGL Runtime throws aServiceInvocationException.

You can override this value by setting the timeout property on the call statementthat invokes a given service.

The default is 100,000 (100 seconds). An infinite wait is not possible.Related concepts


Coding a call statement and callback functions for service accessRelated reference



defaultSessionCookieID

The defaultSessionCookieID build descriptor option identifies the session cookieprovided to the EGL Rich UI Proxy from a service. The service logic in this case isstateful, which means that the user and logic can participate in a multistepconversation. This setting is meaningful only if the service is an EGL external typethat makes an IBM i called program or service program available as an EGL RESTservice. For background information, see Accessing IBM i programs as Web services.

The default value is JSESSIONID, which is always the session ID, regardless of anysetting in EGL, when your application runs on Apache Tomcat.

Depending on how your code is accessing the service, you can override the valueof the build descriptor option defaultSessionCookieID in one of two ways:v When you declare a variable based on an Interface part; orv When you configure the deployment descriptor for the requester.

For details on that choice, see Declaring an interface to access a REST service.Related concepts


Accessing IBM i programs as Web servicesDeclaring an interface to access a REST serviceRelated reference


defaultTimeFormat (build descriptor option)

The defaultTimeFormat build descriptor option controls the initial runtime valueof the strLib.defaultTimeFormat system variable, which contains one of the masksthat can be used to create the string returned by the strLib.formatTime systemfunction. Other details depend on the target language:v When you are generating a COBOL program, if you do not specify the

defaultTimeFormat build descriptor option, the default value for thestrLib.defaultTimeFormat system variable is ″HH:mm:ss″.

v When you are generating Java code, the defaultTimeFormat build descriptoroption specifies the generated value for the vgj.default.timeFormat Java runtimeproperty (if you have set the genProperties build descriptor option to GLOBALor PROGRAM). That property then sets the initial runtime value of thestrLib.defaultTimeFormat system variable.

v When you are generating JavaScript code, the default value ofdefaultTimeFormat build descriptor option is HH:mm:ss.


Related concepts

“Build descriptor part” on page 33“Overview of Java runtime properties” on page 153


Related reference


defaultTimeStampFormat (build descriptor option)

The defaultTimeStampFormat build descriptor option controls the initial runtimevalue of the strLib.defaultTimeStampFormat system variable, which contains oneof the masks that can be used to create the string returned by thestrLib.formatTimeStamp system function. Additional details depend on the targetlanguage:v When you are generating a COBOL program, if you do not specify the

defaultTimeStampFormat build descriptor option, the default value for thestrLib.defaultTimeStampFormat system variable is ″yyyy-MM-ddHH:mm:ss:SSSSSS″.

v When you are generating Java code, the defaultTimeStampFormat builddescriptor option specifies the generated value for thevgj.default.timestampFormat Java runtime property (if you have set thegenProperties build descriptor option to GLOBAL or PROGRAM). That propertythen sets the initial runtime value of the strLib.defaultTimeStampFormat systemvariable.

v When you are generating JavaScript code, the default value of thedefaultTimeStampFormat build descriptor option is an empty string.


Related concepts




deploymentDescriptor

The deploymentDescriptor build descriptor option contains the name of the EGLdeployment descriptor. That descriptor provides service-binding detail when youare generating a service, as well as service-binding detail when you are generatinga logical unit (program, library, handler, or service) that invokes a service. The EGLdeployment descriptor is distinct from non-EGL JEE deployment descriptors.

The deploymentDescriptor option has no default value.

For an overview of services, along with keystroke details, see Overview ofservice-oriented architecture (SOA) and subsequent sections in the Programmer’sGuide. For language details, see Service part.

Related concepts

“Build descriptor part” on page 33“Overview of EGL deployment descriptor file” on page 79Overview of service-oriented architecture (SOA)Related tasks


“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“Build descriptor options used with Java” on page 144“Build descriptor options used with JavaScript” on page 220This topic lists the build descriptor options used with JavaScript, which is thegenerated language for EGL Rich UI.Service partService parts provide requesters with access to the functions in the service. Arequester can be a local or remote program, handler, library, or other service.“Special considerations for generating EGL or Web services in z/OS CICSenvironments” on page 128“Special considerations for generating EGL or Web services in iSeriesenvironments” on page 129

destDirectory

The destDirectory build descriptor option specifies the directory that stores theoutput of preparation. This option is meaningful only when you generate into adirectory rather than into a project.

When you specify a fully qualified file path, all but the last directory must exist.For example, if you specify C:\buildout on Windows 2000, EGL creates thebuildout directory if it does not exist. However, if you specify C:\interim\buildoutand the interim directory does not exist, preparation fails.

If you specify a relative directory (such as myid/mysource on USS), the output isplaced in the bottom-most directory. This is relative to the default directory, asdescribed next.

The default value of destDirectory is affected by the status of the destHost builddescriptor option as in the following situations:


v If destHost is specified, the default value of destDirectory is the directory inwhich the build server is started.

v If destHost is not specified, preparation occurs on the system where generationoccurs. In this case, the default value of destDirectory is given by thegenDirectory build descriptor option.

The user ID specified by the destUserID build descriptor option must have theauthority to write to the directory that receives the output of preparation.

You cannot use a UNIX variable (for example, $HOME) to identify part of adirectory structure on USS.

Related concepts


“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“Build descriptor options used with Java” on page 144“destHost”“genDirectory” on page 323

destHost

The destHost build descriptor option specifies the name or numeric TCP/IPaddress of the target system where the build server resides. No default is available.

If you are preparing a generated COBOL program, the following statements apply:v destHost is required.v A build server must be started on the remote system before generation begins.v For z/OS, you can use the projectID build descriptor option to specify the

high-level qualifier of the data sets in which EGL places the source andpreparation output.

v For iSeries, you can use the destLibrary build descriptor option to specify thelibrary where EGL places the source and preparation output.

If you are preparing Java output, the following statements apply:v destHost is optional.v destHost is meaningful only if you generate into a directory rather than into a

project.v If you specify destHost without specifying destDirectory, the directory in which

the build server was started is the one that receives the source and preparationoutput.

v If you do not specify destHost, preparation occurs on the system wheregeneration occurs; and if destDirectory is not specified, the directory that isspecified by the genDirectory build descriptor option is the one that receives thesource and preparation output

v The UNIX environments are case-sensitive

You can type up to 64 characters for the name or TCP/IP address. If you aredeveloping on Windows NT, you must specify a name rather than a TCP/IPaddress.


No default value is available for this option.

Examples

The following examples show values for destHost:abc.def.ghi.com

9.99.999.99

Related concepts


“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“Build descriptor options used with Java” on page 144“destDirectory” on page 315“destLibrary”“projectID” on page 344“genProperties” on page 326

destLibrary

When you generate a COBOL program for iSeries, the destLibrary build descriptoroption specifies the 1- to 10-character name of the iSeries library that receives theobjects created during generation and contains the objects used at run time.

The default is QGPL.Related concepts



destPassword

The destPassword build descriptor option specifies the password that EGL uses tolog on to the remote build server where your output will be prepared fordeployment.

This option is meaningful if one of the following situations applies to you:v You are generating COBOL code;v You are generating Java code to a directory rather than a project (by setting a

value for the destDirectory build descriptor option), and you specify a value forthe destHost build descriptor option.

The password provides access for the user ID specified in the destUserID builddescriptor option. The value of the password might be case-sensitive, dependingon your target system.

No default is available.


Using the destPassword build descriptor option means that a password is storedin an EGL build file. You can avoid the security risk by not setting this builddescriptor option. When you start generation, you can set the password in aninteractive generation dialog or on the command line.

Related concepts


“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“Build descriptor options used with Java” on page 144“destDirectory” on page 315“destHost” on page 316“destUserID”

destPort

The destPort build descriptor option specifies the port on which a remote buildserver is listening for build requests.



No default value is available.Related concepts


“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“Build descriptor options used with Java” on page 144“destDirectory” on page 315“destHost” on page 316

destUserID

The destUserID build descriptor option specifies the user ID that EGL uses to logon to the remote build server where preparation occurs.



The user specified by destUserID must have the authority to write to thefollowing:


v The directory specified by the destDirectory build descriptor option, if you aregenerating Java code.

v The data sets specified by the projectID high-level qualifier, if you aregenerating COBOL for z/OS.

v The library specified by destLibrary if you are generating COBOL for iSeries.

The option value can be case-sensitive, depending on your target system. Nodefault is available.

Related concepts


“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“Build descriptor options used with Java” on page 144“destDirectory” on page 315“destHost” on page 316“destLibrary” on page 317“destPassword” on page 317“projectID” on page 344

eliminateSystemDependentCode

The eliminateSystemDependentCode build descriptor option indicates whetherthe EGL generator ignores code that will never run in the target system.

The eliminateSystemDependentCode build descriptor option is meaningful onlyin relation to the sysVar.systemType system variable. For example, the EGLgenerator does not process the following add statement if you are generating forWindows:

if (sysVar.systemType IS AIX)add myRecord;

end

To avoid generating code that will never run in the target system, take either of thefollowing actions:v Set the eliminateSystemDependentCode build descriptor option to YES. In the

current example, the add statement is not generated if you set theeliminateSystemDependentCode build descriptor option to YES and set thesystem build descriptor option to something other than AIX. Be aware, however,that the EGL generator can eliminate system-dependent code only if the logicalexpression (in this case, sysVar.systemType IS AIX) is simple enough to evaluateat generation time.

v Move the statements that you do not want to generate to a second program;then, let the original program call the new program conditionally, as in thisexample:

if (sysVar.systemType IS AIX)call myAddProgram (myRecord);

end


Values

NO Specifies that EGL generates code that does not run in the target system.Specify NO only if the output of the current generation will run inmultiple systems.

YES (the default value)Specifies that EGL only generates code that runs in the target system.

Related concepts



enableJavaWrapperGen

When you issue the commands to generate a program, the enableJavaWrapperGenbuild descriptor option specifies whether all or only some of the followingcomponents can be generated: the program, Java wrapper classes, and the relatedEJB session bean.

Actual generation of the Java wrapper classes and EJB session bean requiresappropriate settings in the linkage options part that is used at generation time.

Values

NO Generate the program, but not the Java wrapper classes or the related EJBsession bean, if any.

ONLY Do not generate the program, but allow generation of the related Javawrapper classes and (if appropriate) the related EJB session bean

YES (the default value)Generate the program and allow generation of the related Java wrapperclasses and (if appropriate) the related EJB session bean.

Related concepts

“Build descriptor part” on page 33“Generating Java wrappers” on page 199Related reference

“Build descriptor options” on page 41“Java wrapper classes” on page 199

endCommArea

When you generate a COBOL program for a CICS environment, theendCommArea build descriptor option indicates whether to add a full wordcontaining the hexadecimal ″FFFFFFFF″ to the end of the COMMAREA on callsfrom EGL-generated CICS COBOL programs.


Values

YES Adds the hexadecimal ″FFFFFFFF″ to the end of the COMMAREA.

NO (the default value)Does not add the hexadecimal ″FFFFFFFF″ to the end of the COMMAREA.

Related concepts

“Build descriptor part” on page 33“Linkage options part” on page 61Related reference

“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“callLink element” on page 380

errorDestination

The errorDestination build descriptor option specifies the destination of thediagnostic messages in the IMS/VS and IMS BMP environments.

The error destination is specified as one of the following:v The IMS transaction code associated with a BMP program that lists error

diagnostics associated with runtime errors.v The logical terminal identifier associated with the printer where the diagnostics

are sent. This option is effective at run time only if the option is specified for thefirst program in the run unit.– The default for IMS/VS is ELADIAG, a transaction code for a BMP utility

provided with IBM Rational COBOL Runtime Server for zSeries that printsthe diagnostics.

– The default for IMS BMP is to write the messages to the file ELAPRINTinstead of to a message queue.

For details on the format of the error record, see the documentation for RationalCOBOL Runtime for zSeries, which is on a Web site referenced in Sources ofadditional information on EGL.

Related reference


fillWithNulls

When you generate a COBOL program, the fillWithNulls build descriptor optionis used when you generate a form group that includes print forms. This optionindicates whether to fill print-form fields with null characters. The affected fieldshave these characteristics:v The fillCharacter field property is set to an empty stringv The field is of one of these types: CHAR, DBCHAR, MBCHAR, or NUM

Values

YES (the default value)Fill the print-form fields with null characters.

NO Do not fill the print-form fields with null characters.Related concept




formServicePgmType

The formServicePgmType build descriptor option specifies the type of printservices programs to generate for IMS BMP or z/OS batch. You can specify one ormore entries. When specifying multiple entries, use a comma between the entries,for example:

GSAM,SEQ,MFS

Values

ALL (the default value)Generate all the mapping services programs that apply to the targetsystem, for example:v GSAM, MFS, and SEQ is generated for IMS BMPv GSAM and SEQ is generate for z/OS batch

If you specify ALL with any other entry, the effect is the same as onlyspecifying ALL.

SEQ Generate a batch mapping services program that supports writing to aprinter or to a QSAM file. This value is valid for z/OS batch or IMS BMP.

This is the default value for z/OS batch.

GSAMGenerate a batch mapping services program that supports writing to a GSAMfile. This value is valid for z/OS batch or IMS BMP.

MFSGenerate a message format service (MFS) print mapping services program andthe MFS source definitions. If the form group contains text forms, also generatea form group format module, as well as the COBOL copybooks for MFS. Thisvalue is valid only for IMS BMP.

Related reference

“Build descriptor options” on page 41Related reference


genDataTables

The genDataTables build descriptor option indicates whether you want to generatethe data tables that are referenced in the program you are generating. Thereferences are in the program’s use declaration and in the msgTablePrefix programproperty .

For other details, see the topic ″DataTable part″ in the EGL Language Reference.


Values

NO Set the value to NO in the following case:v The data tables referenced in the program were previously generatedv Those tables have not changed since they were last generated

YES (the default value)Specifies that the data tables should be generated.

Related concepts



genDDSFile

When you generate a COBOL program for iSeries, the genDDSFile builddescriptor option indicates whether you want to create iSeries data descriptionspecification (DDS) files from the record declarations with which your programdoes input or output.

Values

YES Generate iSeries DDS files.

If you are creating DDS files and the prep build descriptor option is set toYES, the DDS files are uploaded to the host system.

NO (the default value)Do not generate iSeries DDS files.

Related concepts


“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“prep” on page 342

genDirectory

The genDirectory build descriptor option specifies the fully qualified path of thedirectory into which EGL places generated output, control files, and results files.

When you are generating in the workbench, these rules apply:

Java generationYou can specify either genProject or genDirectory. If both are specified,genProject is used. If neither is specified, the default action is for the output tobe placed in the same project as the EGL source file being generated.

COBOL generationYou must specify genDirectory, and in most cases EGL ignores any setting forgenProject.


If the COBOL program is of type VGWebTransaction, however, thesestatements apply:v You may specify genProject, which indicates a location for the Java-based

objects that run in the Web application serverv If you do not specify genProject, all output is placed in the location

identified in genDirectory

If you are generating from the EGL SDK, genDirectory is required.

For details on deploying COBOL code, see the documentation for your COBOLruntime product.

Related concepts


“Generation using the Eclipse workbench” on page 11“Generation using the EGL software development kit (SDK)” on page 15“Processing Java code that is generated into a directory” on page 180Related reference

“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“Build descriptor options used with Java” on page 144“genProject” on page 325

genFormGroup

The genFormGroup build descriptor option indicates whether to generate the formgroup that is referenced in the use declaration of the program being generated.

The help form group, if any, is not affected by this option, but by thegenHelpFormGroup build descriptor option.

Values

NO Do not generate the form group.

YES (the default value)Generate the form group.

Related concepts

“Build descriptor part” on page 33

Related reference

“Build descriptor options” on page 41“genHelpFormGroup”

genHelpFormGroup

The genHelpFormGroup build descriptor option indicates whether to generate thehelp form group that is referenced in the use declaration of the program beinggenerated.


The main form group is not affected by this option, but by the genFormGroupbuild descriptor option.

Values

NO Do not generate the help form group.

YES (the default value)Generate the help form group.

Related concepts


“Build descriptor options” on page 41“genFormGroup” on page 324

genProject

The genProject build descriptor option places the output of Java generation into aWorkbench project and automates tasks that are required for Java runtime setup.For details on that setup and on the benefits of using genProject, see “GeneratingJava code into a project” on page 178.

To use genProject, specify the project name. EGL then ignores the buildPlan,genDirectory, and prep build descriptor options, and preparation occurs in eitherof two cases:v Whenever you build the project.v Whenever you generate the source files; but only if you selected the workbench

preference Build automatically. To set this preference:1. Click Window → Preferences to open the Preferences window.2. At the left side of the Preferences window, expand General and click

Workspace.3. Select the Build automatically check box if you want EGL to build your files

automatically. When you select this preference, EGL performs a buildwhenever you save a file. This means that EGL validates any parts of the filethat have changed, and any other parts in the project that are called by thechanged part. Validation is done without using a build descriptor part.

If you set the genProject build descriptor option to the name of a project that doesnot exist in the workbench, EGL uses the name to create a Java project, exceptwhen one of the following situations occurs:v If you are generating a JSF Handler, it is always generated into the project

containing the related JSP file, regardless of the genProject build descriptoroption setting.

v A second exception concerns EJB processing and occurs if you are generating aJava wrapper when the linkage options part callLink element type property isejbCall (for the call from the wrapper to the EGL-generated program). In thatcase, EGL uses the value of genProject to create an EJB project and creates anew enterprise application project (if necessary) with a name that is the same asthe EJB project name plus the letters EAR.

In addition to creating a project, EGL does as follows:v EGL creates folders in the project. The package structure begins within the

project’s Java Resources folder.


When you are generating in the workbench, the following rules apply:

For Java generationYou are not required to specify either genProject or genDirectory. If neither isspecified, Java output is placed in the project that contains the EGL source filebeing generated.

For COBOL generationYou must specify genDirectory, and in most cases EGL ignores any setting forgenProject.

If the COBOL program of type VGWebTransaction presents a Web page,however, these statements apply:v You may specify genProject, which indicates a location for the associated

Java-based objects that run in the Web application serverv If you do not specify genProject, all output is placed in the location

identified in genDirectory

If you are generating from the EGL SDK, you may not use genProject. UsegenDirectory instead.

Related concepts

“Build descriptor part” on page 33“Build plan” on page 103Related tasks

“Generating Java code into a project” on page 178“Generation using the Eclipse workbench” on page 11“Generation using the EGL software development kit (SDK)” on page 15Related reference

“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“Build descriptor options used with Java” on page 144“buildPlan” on page 301“genDirectory” on page 323“prep” on page 342

genProperties

When you generate Java code, the genProperties build descriptor option specifieswhere to generate Java runtime properties (if any) and, in some cases, whether togenerate a linkage properties file. This build descriptor option is meaningful onlywhen you are generating a Java program (which can use either kind of output) ora Java wrapper (which can use only the linkage properties file). The effect of thisbuild descriptor option depends on the value of the j2ee, genProject, andgenDirectory build descriptor options.

When you generate with the genProperties build descriptor option set to eitherPROGRAM or GLOBAL, then the values of certain other build descriptor optionsare stored as Java runtime properties in one of three possible locations, as in thesesituations:v If you have set the j2ee build descriptor option to NO, then EGL generation

creates a properties file, and the Java runtime properties are stored in that file.The ″Values″ section below describes how the value of the genProperties builddesriptor option affects this properties file.


v If you have set the j2ee build descriptor option to YES and you have set thegenProject build descriptor option to the location of a J2EE project, EGLgeneration adds the Java runtime properties to the J2EE deployment descriptorin that project.

v If you have set the j2ee build descriptor option to YES, but you have set thegenDirectory build descriptor option instead of the genProject build descriptoroption, EGL generation creates a J2EE environment file in the folder specified bygenDirectory, and the Java runtime properties are stored in that file.

Note: If you choose to generate to a directory in this manner, the Java runtimeproperties in the J2EE environment file will not be automatically updatedthe next time you generate. The J2EE environment file contains the XMLcode that would have been added to the J2EE deployment descriptor ifyou had chosen to generate to a J2EE project. When you import your codeinto a J2EE project, you must manually copy the XML code from the J2EEenvironment file and paste it into the J2EE deployment descriptor. TheJ2EE environment file is named pgmAlias-env.txt, where pgmAlias is thename of the program or other logic part.

v If you are generating a VGWebTransaction, the properties are always stored inthe rununit.properties file on the alias.properties file depending on thegenProperties build description option.

v If you have set the j2ee build descriptor option to YES and you have set thegenProject build descriptor option to the location of a non-J2EE project, thenEGL creates a J2EE environment file in the same way as if you had set thegenDirectory build descriptor option. See the note in the previous list item forinformation about the J2EE environment file.

Values

NO (the default value)EGL does not generate runtime or linkage properties.

PROGRAMThe effects of this setting are as follows:v If you are generating a program or other logic part to run outside of

J2EE, or if you are generating a VGWebTransaction program, EGLgenerates a properties file that is specific to the program or other logicpart being generated. The name of that file is:

pgmAlias.properties

where pgmAlias is the name of the program or other logic part atruntime. This properties file is generated to the same place as the rest ofthe generated output, as specified by genProject or genDirectory. Theproperties file is updated when you generate different output later.

v If you are generating a program or other logic part to run within J2EE,EGL adds the Java runtime properties to the J2EE deployment descriptoror environment file, as explained earlier in this topic.

GLOBALThe effects of this setting are as follows:v If you are generating a program or other logic part to run outside of

J2EE, or if you are generating a VGWebTransaction program, EGLgenerates a properties file that is used throughout the run unit, but isnot named for the initial program in the run unit. The name of thatproperties file is rununit.properties. This properties file is generated to


the same place as the rest of the generated output, as specified bygenProject or genDirectory. The properties file is updated when yougenerate different output later.This option is especially useful when the first program of a run unitdoes not access a file or database but calls programs or other logic partsin the same run unit that do.When generating the caller, you can generate a properties file named forthe program, and the content might include no database-relatedproperties. When you generate the called program, you can generaterununit.properties, and the content would be available for bothprograms.

v If you are generating a program or other logic part to run within J2EE,EGL adds the Java runtime properties to the J2EE deployment descriptoror environment file, as explained earlier in this topic.

Whether you specify PROGRAM or GLOBAL, if you are generating a Javawrapper or calling program, EGL may generate a linkage properties file. Fordetails on the situation in which this file is generated, see the topic ″Linkageproperties file.″

For further details on Java runtime properties, see the topics ″Overview of Javaruntime properties″ and ″Linkage properties file.″

Related concepts

“Build descriptor part” on page 33“Overview of Java runtime properties” on page 153“Linkage properties file” on page 182Related reference

“Build descriptor options” on page 41“Build descriptor options used with Java” on page 144“genDirectory” on page 323“genProject” on page 325“j2ee” on page 333

genResourceBundle

When you are generating a VGWebTransaction program, a VGUI record, or aDataTable (type msgTable), the genResourceBundle build descriptor optionspecifies whether to generate a Java resource bundle, which is a Java object thatcontains strings to be presented at runtime. The content of a resource bundlegenerated for a VGUI record includes the Web-page title, labels, and help text; andthe content of a resource bundle generated for a message table includes a set ofmessages.

When you are generating a VGWebTransaction program and have specified a valuefor the msgTablePrefix program property, EGL produces a message resourcebundle regardless of the value of genResourceBundle.

If you want to specify a Java locale for the generated resource bundle, set theresourceBundleLocale build descriptor option.


Values

NO

YES (the default)

Set the option to YES in any of these cases:v You are generating a VGWebTransaction program and want a resource

bundle for each VGUI record presented to the userv You are generating only a VGUI record and want a resource bundle for

itv You are generating a DataTable that contains messages for presentation

by a VGWebTransaction programRelated concepts


“Build descriptor options” on page 41“resourceBundleLocale” on page 345

genReturnImmediate

When you generate a CICS COBOL program, the genReturnImmediate builddescriptor option specifies whether the generated program exits with a CICSRETURN IMMEDIATE statement when the program issues a transfer totransaction transfer statement. The CICS RETURN IMMEDIATE instead of a CICSSTART command uses fewer CICS resources.

Values

YES Generate the RETURN IMMEDIATE statement after a transfer totransaction statement.

NO (the default value)Generate a CICS START statement after a transfer to transaction statement.

Related reference



genRunFile

When you generate a COBOL program for z/OS batch, the genRunFile builddescriptor option indicates whether to produce sample runtime JCL for theprogram being generated.

Values

YES (the default value)Generates the sample runtime JCL.

NO Does not generate the sample runtime JCL.Related concepts



“Generation output and associated files” on page 91Related reference


genVGUIRecords

When you are generating a VGWebTransaction program, the genVGUIRecordsbuild descriptor option indicates whether to generate the VGUI records that arereferenced in converse orshow statements.

For other details, see VGUIRecord part.

Values

YES (the default)Generate the VGUI records.

NO Do not generate the VGUI records. Use this setting only if the VGUIrecords referenced in the VGWebTransaction program were previouslygenerated and have not changed since they were last generated.

Related concepts



imsFastPath

The imsFastPath build descriptor option specifies whether the program can run asan IMS fast-path program. The option is effective only if used for the first programin the run unit.

Values

YES The program’s use of IMS functions is limited to what is permitted in afast-path program.

This choice restricts the amount and type of diagnostic data that isprovided when an error occurs in the generated program. Also, if the rununit does not end successfully, Rational COBOL Runtime for zSeries issuesa 1602 abend.

NO (the default value)The program cannot run as an IMS fast-path program. If the run unit doesnot end successfully, Rational COBOL Runtime for zSeries issues an IMSrollback (ROLL) request.

Related reference



imsID

The build descriptor option imsID specifies the IMS DB control ID for yourdatabase. This value is used when you debug IMS code that accesses DL/I. Thevalue is of type CHAR(4).

The value comes from the JCL that you use to start IMS. The IMS JCL parametershould look like this:IMSID XXXX IMS SUBSYSTEM IDENTIFIER

In this example, XXXX represents the subsystem type and is the value you assignto the imsID build descriptor option.

Related concepts

“Bind control part” on page 264“Build descriptor part” on page 33Related reference


imsLogID

The imsLogID build descriptor option specifies an identifier that will be includedin records written to the IMS log. The identifier is a 2-digit hexadecimal numberfrom A0 to FF.

The record is written in response to errors that occur in the run unit. For details onthe format of the log record, see the documentation for Rational COBOL Runtimefor zSeries, which is on a Web site referenced in Sources of additional information onEGL.

The setting for imsLogID is effective only if specified for the first program in therun unit. If you do not specify a value for imsLogID, no runtime errors ordiagnostic information is written to the IMS log for that run unit.

Related reference


includeLineNumbers

When you generate Java code, the includeLineNumbers build descriptor optionspecifies whether or not Java runtime error messages include the line number ofthe error. This helps you locate problems in the code more easily. If you set thisoption to YES, the program might run slower due to the increased informationwhich is being added.

Values

NO (the default value)When includeLineNumbers is set to this value, Java runtime errormessages look like the following example:EGL0049E Overflow during assignment of 12345 to x.EGL0002I The error occurred in MyProgram, function main.


YES When includeLineNumbers is set to this value, Java runtime errormessages look like the following example:EGL0049E Overflow during assignment of 12345 to x.EGL0003I The error occurred in MyProgram, function main,

at line 24 of file 'com.fred.MyProgram.egl'.

Related concepts



initIORecordsOnCall

This build option specifies when called program IO records are initialized.

Values

NO Called program IO records are initialized only when the program is firstloaded in the run unit. This value is not supported for Java; see″Compatibility.″

YES (the default value)Called program IO records are initialized each time the program is called.

CompatibilityTable 30. Compatibility considerations for initIORecordsOnCall

Platform Issue

Java generation Java generation recognizes the initIORecordsOnCall builddescriptor option, but only supports the default value of YES.This means, in effect, that the option is supported on byCOBOL generation.

Related concepts


“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“initNonIODataOnCall”

initNonIODataOnCall

This build option specifies when called program non-IO-record and primitivevariables are initialized.

Values

NO Called program non-IO-record and primitive variables are initialized onlywhen the program is first loaded in the run unit. This value is notsupported for Java; see ″Compatibility.″

YES (the default value)Called program non-IO-record and primitive variables are initialized eachtime the program is called.


CompatibilityTable 31. Compatibility considerations for initNonIODataOnCall

Platform Issue

Java generation Java generation recognizes the initNonIODataOnCall builddescriptor option, but only supports the default value of YES.This means, in effect, that the option is supported on byCOBOL generation.

Related concepts


“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“initIORecordsOnCall” on page 332

j2ee

When you generate Java code, the j2ee build descriptor option specifies whetherthe Java code is generated to run in a J2EE environment.

When you generate a JSF handler, J2EE is always set to YES regardless of what isspecified in this option. When you generate a Java program of typeVGWebTransaction, J2EE is always set to NO regardless of what is specified in thisoption.

Values

NO (the default value)Generates a program that will not run in a J2EE environment. The programconnects to databases directly, and the environment is defined by aproperties file.

YES Generates a program to run in a J2EE environment. The program connectsto databases using a data source, and the environment is defined by adeployment descriptor.

Related concepts

“Build descriptor part” on page 33“Deploying to a JEE environment” on page 186“Deploying to a non-JEE environment” on page 194Related reference


j2eeLevel

When you generate Java code, the j2eeLevel build descriptor option specifies theJ2EE level in the application server to which an EGL Web service is deployed.

This build descriptor option is used with the serverType build descriptor option, ifthe value of that option refers to Apache Tomcat or WebSphere Application Server.


If the j2eeLevel build descriptor option is not specified, the default is determinedby the value of the serverType build descriptor option.

Values

5.0 The default when the serverType build descriptor option is settoWebSphere Application Server version 7.x or Tomcat version 6.x.

1.4 The default when the serverType build descriptor option is settoWebSphere Application Server version 6.x, or Tomcat version 5.x.

1.3 The default when the serverType build descriptor option is settoWebSphere Application Server version 5.1.2. This value is alsoappropriate if you plan to deploy to Apache Tomcat version 4.1.

Related concepts


“Generation using the Eclipse workbench” on page 11Related reference

“Build descriptor options” on page 41“Build descriptor options used with Java” on page 144“j2ee” on page 333“serverType” on page 349

leftAlign

The leftAlign build descriptor option is used when you generate a form group thatincludes print forms. The option indicates whether to left-justify the output data onprint-form fields that have the following characteristics:v The align field property is set to left

v The field is of one of these types: CHAR, DBCHAR, or MBCHAR.

If you do not need left alignment during output, specify no to give betterperformance and to reduce the code size.

Left alignment strips leading spaces and places them at the end of the field.

Values

YES (the default value)Left-justify the output data.

NO Ddo not left-justify the output data.Related concepts




linkage

The linkage build descriptor option contains the name of the linkage options part,which guides these aspects of generation (identified by the property controllingthat aspect):

callLinkControls how a call statement is generated

transferToProgramControls how a transfer to program statement is generated.

transferToTransactionControls how a transfer to transaction statement is generated.

asynchLinkControls how the vgLib.startTransaction function is generated.

fileLinkControls remote file I/O for CICS environments.

This option is not required for generation, and no default value is available.Related concepts

“asynchLink element” on page 375“Build descriptor part” on page 33“callLink element” on page 380“fileLink element” on page 407“Linkage options part” on page 61“transferToProgram element” on page 410“transferToTransaction element” on page 416Related tasks

“Adding a linkage options part to an EGL build file” on page 63Related reference


linkEdit

When you are generating a COBOL program for z/OS, the linkEdit builddescriptor option identifies a link edit part. That part provides a way to create theinformation for a link edit file, which in turn specifies how to combine COBOLprograms into a load module.

At generation time, EGL reviews the linkEdit option with these possible results:v If the linkEdit option has a value specified, EGL searches for a link edit part

whose name matches that value. The results of that search determine the effects,as follows:– If the link edit part is found, the contents of that part are copied to a link edit

file, with the file extension LKG. If there are symbolic parameters in the linkedit file, EGL replaces them with their respective values.

– If the link edit part is not found, a generation error occurs.


v If the linkEdit option does not have a value specified, EGL searches for a linkedit part whose name matches the program being generated. The results of thatsearch determine the effects, as follows:– If EGL finds a link edit part, the contents of that part are copied to a link edit

file with the file extension LKG. If there are symbolic parameters in the linkedit file, EGL replaces them with their respective values.

– If EGL does not find a link edit part, EGL does not create a link edit part withthe extension LKG.

In all cases, EGL generates a link edit file with the file extension LED. Thisprovides the link edit information for the program, including all EGL runtimemodules that must be statically linked. When there is a link edit part and aresulting LKG link edit file, the build plan specifies that the build scripts shouldinclude an extra step in the preparation process, to relink the program using thelink edit commands from the LKG file. You can then statically link the programwith other EGL or non-EGL programs.

You can use your own symbolic parameters in the link edit part, as well as thoselisted in the topic ″Predefined symbolic parameters for EGL generation.″

Related concepts

“Build descriptor part” on page 33“Link edit part” on page 269“Linkage options part” on page 61Related tasks

“Adding a link edit part to an EGL build file” on page 273Related reference

“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“Link edit part examples” on page 270“Predefined symbolic parameters that are set automatically” on page 250“Predefined symbolic parameters that can be set by the user” on page 252

math

When you generate a COBOL program, the math build descriptor option specifieswhether to do arithmetic calculations based on CSP math, which is used in somegenerated COBOL programs that were written either with IBM Cross SystemProduct (CSP) or with VisualAge Generator. You might choose CSP math if yourEGL-generated program was originally written for CSP. Otherwise, accept thedefault, which is COBOL.

Values

COBOL (the default value)Use COBOL truncation algorithms, which may provide faster performance,smaller load module size, and better accuracy.

CSPAETruncate intermediate arithmetic values to a number of significant digits.The number is equal to the number of significant digits for the memoryarea that holds the final result.

Related concepts



Related reference


maxNumericDigits

When you generate a COBOL program, the maxNumericDigits build descriptoroption specifies the size of numeric fields. Generally, COBOL applications use 31digit numeric fields. However, if your compiler only supports a maximum of 18digits, you must specify this build descriptor option with a value of 18.

Values

31 (the default value)Sets the numeric fields to 31 digits.

18 Sets the maximum size for numeric fields to 18 digits.Related concepts



mfsDevice

When you are generating a form group for use on IMS, the mfsDevice builddescriptor option specifies information to include in the EGL-generated DEV andDFLD statements. Those statements identify characteristics of the device types thatare valid for at least one form in the form group.

The mfsDevice build descriptor option can occur from zero to many times. Theattributes in each option must be compatible with the device characteristics definedin the TERMINAL and TYPE macros in your IMS system definition.

The attributes in each mfsDevice option are shown in the following default set ofoptions:

<mfsDevice width="80", height="24",devStmtParms="TYPE=3270-A2,FEAT=(IGNORE)",extendedAttributes="YES" />

<mfsDevice width="80", height="24",devStmtParms="TYPE=(3270-2),FEAT=(IGNORE)",extendedAttributes="YES" />

<mfsDevice width="132", height="255",devStmtParms="TYPE=3270P,WIDTH=133,PAGE=(255,DEFN),FEAT=2",extendedAttributes="YES" />

Values

The following attributes are available:

height The number of lines that can be displayed on the device. This attribute isrequired.

width The number of columns that can be displayed on the device. This attributeis required.


devStmtParmsA string that contains one or more parameters for inclusion in theEGL-generated DEV statement. The information is based on that in theTERMINAL and TYPE macros in your IMS system definition. Thisattribute is required.

extendedAttributesIndicates whether the device supports extended attributes and whether acolor default (CD) extended attribute is generated for form fields that aredisplayed on monochromatic devices. Your choice affects theEGL-generated MFS DFLD statements. If you specify this attribute, thevalue of the mfsExtendedAttr build descriptor option is ignored when yougenerate form information for the device.

Valid values are as follows:

YES (the default value)Extended attributes are supported, and a color default extendedattribute is generated.

NCD Extended attributes are not supported.

NO Extended attributes are supported, but a color default extendedattribute is not generated.

For more information on the mfsDevice build descriptor option, refer to the IBMRational COBOL Runtime Guide for zSeries.

Related tasks

“Build descriptor part” on page 33“Editing mfsDevice options in a build descriptor part” on page 60Related reference

“mfsExtendedAttr”“mfsIgnore” on page 339“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234

mfsExtendedAttr

When you are generating a form group for use on IMS, the mfsExtendedAttr builddescriptor option indicates a default value for whether the devices supportextended attributes and for whether a color default (CD) extended attribute isgenerated for form fields that are defined with color = default color.

The information in this build descriptor option is included in EGL-generated MFSDFLD statements; but your decision can be overridden by the mfsDevice option (ifany) for a specific device.

Values

YES (the default value)Extended attributes are supported, and a color default extended attribute isgenerated.

NCD Extended attributes are supported, but a color default extended attribute isnot generated.

NO Extended attributes are not supported.


Related tasks


“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“mfsDevice” on page 337

mfsIgnore

When you are generating a form group for use on IMS, the mfsIgnore builddescriptor option indicates whether to include IGNORE in the SOR parameter ofthe MSG statement for the EGL-generated MID and MOD.

Values

NO (the default value)Do not include IGNORE in the SOR parameter.

YES Include IGNORE, as is appropriate only if the mfsDevice build descriptoroption attribute devStmtParms specifies FEAT=IGNORE for all of thedevices used by the form group being generated.

Related tasks


“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“mfsDevice” on page 337

mfsUseTestLibrary

When you are generating a form group for use on IMS, the mfsUseTestLibrarybuild descriptor option specifies whether the build script will cause the buildserver to place the MFS control blocks in a test library.

Values

NO (the default value)The build server places the control blocks in a staged FORMAT library.

YES The build server places the control blocks in a test library.Related tasks



msgTablePrefixWhen you generate a VGUI record bean alone, the build descriptor optionmsgTablePrefix specifies the message-table prefix that is stored in the VGUI recordbean. When combined with an NLS code, that prefix determines the name of theDataTable that is the source of runtime messages. For details on the NLS code, seethe topic for build descriptor option targetNLS.


When you generate a VGUI record bean along with a VGWebTransaction program,the value of the build descriptor option has no effect. Instead, the value of theprogram property msgTablePrefix determines what is stored in the VGUI recordbean.

The value of msgTablePrefix has no effect on DataTable generation.Related reference

“Build descriptor options” on page 41“targetNLS” on page 365

nextBuildDescriptor

The nextBuildDescriptor build descriptor option initiates a chain of builddescriptors by specifying the next build descriptor to be read in the generationprocess. This option can be used to create a chain of build descriptor parts.




oneFormItemCopybook

When you are generating a COBOL program, the oneFormItemCopybook builddescriptor option indicates whether the generated program accesses the values ofform-field properties by way of COBOL SET statements.

Values

NO (the default value)EGL generates a COBOL copybook into the definition of each form field, inthe Data Section of the COBOL program. Access is direct, not requiring useof COBOL SET statements.

YES EGL places a single copybook in the Linkage Section, and access is byCOBOL SET statements.

Accepting the default value maximizes performance, and this should be donewhen possible. However, if your program uses many forms or if the forms containmany fields, EGL generates a large number of COBOL variable names; in this case,the COBOL compiler symbol table can become so large that compilation fails.

If you need to avoid the compilation problem just described, setoneFormItemCopybook to YES. With this setting, the EGL-generated code willinvoke a COBOL SET statement whenever a form-field property value is accessed.


On z/OS, if you are setting oneFormItemCopybook to yes, you need to compilethe COBOL code with one of these:v IBM Enterprise COBOL for z/OS v3.2; orv IBM COBOL for OS390 or VM, version 2.2 or later, because earlier versions of

this product do not support the appropriate form of the COBOL SET statement.Related concepts



positiveSignIndicatorThe positiveSignIndicator build descriptor option is used only in iSeriesenvironments to improve performance.

When you generate a COBOL program for iSeries, the positiveSignIndicator builddescriptor option specifies the character that the iSeries-based ILE COBOLcompiler uses as the positive sign for zoned and packed decimal data. Thefollowing types of numeric data are affected:v DECIMALv MONEYv NUMv PACKv PACF

A potential problem is that the COBOL compiler uses the specified positive-signcharacter for all these data types. In contrast, EGL by default uses a mixture ofcharacters, as follows:v NUM and PACF default to F.v NUMC, PACK, DECIMAL, and MONEY default to C.

If the COBOL compiler sets all the positive-sign characters to C, EGL typicallychanges all the NUM and PACF variables to F at run time. Similarly, if thecompiler sets all the characters to F (the default), EGL changes all the NUMC,PACK, DECIMAL, and MONEY variables to C.

Therefore, the typical purpose of specifying the positiveSignIndicator builddescriptor option is to increase performance. If your code includes moreoccurrences of NUMC, PACK, DECIMAL, and MONEY variables (as compared toNUM and PACF variables), you can improve performance by settingpositiveSignIndicator to C. In this case, EGL will generate less code because it willhave fewer variables to change at run time.

Two additional values are available to override the default EGL behavior. SettingpositiveSignIndicator to F-ALL keeps EGL from changing all the NUMC, PACK,DECIMAL, and MONEY variables to C. Likewise, C-ALL keeps EGL fromchanging NUM and PACF variables to F.

If your code is exclusively NUM and PACF variables, or you want all variables tohave an F positive sign, a significant performance benefit can be obtained byselecting F-ALL. This prevents the generation of any of the EGL runtime calls tochange the sign. Similarily, if your code is exclusively NUMC, PACK, DECIMAL


and MONEY variables, or you want all variables to have an C positive sign, asignificant performance benefit can be obtained by selecting C-ALL.

Values

F (the default value)This specifies that the COBOL compiler should preset all DECIMAL,MONEY, NUM, NUMC, PACK, and PACF variables to use ″F″ as thepositive sign character. EGL changes the sign for NUMC, PACK,DECIMAL, and MONEY variables to C at run time.

C This specifies that the COBOL compiler should preset all DECIMAL,MONEY, NUM, NUMC, PACK, and PACF variables to use ″C″ as thepositive sign character. EGL changes the sign for NUM and PACF variablesto F at run time.

F-ALL This specifies that the COBOL compiler should preset all DECIMAL,MONEY, NUM, NUMC, PACK, and PACF variables to use ″F″ as thepositive sign character. EGL will not change any positive signs to C at runtime.

C-ALLThis specifies that the COBOL compiler should preset all DECIMAL,MONEY, NUM, NUMC, PACK, and PACF variables to use ″C″ as thepositive sign character. EGL will not change any positive signs to F at runtime.

Related concepts



prep

The prep build descriptor option specifies whether EGL begins preparation whenthe generation phase completes successfully.

Even if you set prep to NO, you can prepare code later. For details, see “Using abuild plan after generation” on page 103.

Consider these cases:v When you generate a COBOL program, EGL writes preparation messages to the

directory specified in the genDirectory build descriptor option, to the resultsfile, and to additional files that are each specific to a preparation step.

v When you generate Java code into a directory, EGL writes preparation messagesto the results file.

v When you generate Java code into a project (genProject build descriptor option),the prep build descriptor option has no effect, and preparation occurs in eitherof two situations:– Whenever you build the project– Whenever you generate the source files; but only if you selected the

workbench preference Build automatically. To set this preference:1. Click Window → Preferences to open the Preferences window.


2. At the left side of the Preferences window, expand General and clickWorkspace.

3. Select the Build automatically check box if you want EGL to build yourfiles automatically. When you select this preference, EGL performs a buildwhenever you save a file. This means that EGL validates any parts of thefile that have changed, and any other parts in the project that are calledby the changed part. Validation is done without using a build descriptorpart.

If you wish to customize the generated build plan, follow these steps:1. Set the prep build descriptor option to NO.2. Set the buildPlan build descriptor option to YES (as is the default).3. Generate the output.4. Customize the build plan.5. Invoke the build plan, as described in ″Using a build plan after generation″.

Values

NO The preparation phase is not started after the generation phase.

YES (the default value)The preparation phase is started after the generation phase.

Related concepts

“Build plan” on page 103“Build descriptor part” on page 33Related tasks

“Using a build plan after generation” on page 103Related reference

“Build descriptor options” on page 41“Build plan” on page 103“genDirectory” on page 323“genProject” on page 325

printDestination

The printDestination build descriptor option specifies the destination of printedoutput for basic programs generated for CICS.

This option sets the initial value of the converseVar.printerAssociation systemvariable.

Values

PROGRAMCONTROLLED (the default value)The printed output from CICS batch jobs is sent to the destinationspecified in the resource associations part, for the file identified as printer.

TERMINALIDThe printed output from CICS batch jobs is sent to the current CICSterminal ID.

Related concepts




programPackageName

The build descriptor option programPackageName names the Java package thatreceives EGL-generated output during program generation. The option does notchange the case of any letter in the name specified. The option is used only whengenerating Java output for an EGL program.

If you name the Java package with the same name as an EGL package, you mayoverwrite output files either when you generate parts stored in the EGL package orwhen you generate a program and use the name in option programPackageName.

There are several ways to determine the Java package name used when youspecify a call or transfer statement or when you specify a show statement thatreturns control. Those ways are as follows, in order of decreasing priority:1. Code the package name in the statement, as in the following example:

Call my.pkg.MyProgram;

2. Specify a name in the build descriptor option programPackageName.3. Do not specify the package name explicitly, but accept the EGL package name

specified in an import statement that makes available the EGL part beinginvoked.

4. Specify the package name when defining the related entry in the linkageoptions part.

5. Use the Java package that corresponds to the EGL-generated code. In mostcases, use the Java package for the EGL code that contains the call, transfer, orshow statement. However, if the invocation was inside a standalone EGLfunction, use the Java package for the EGL-generated code that invokes thefunction.Related concepts

“Bind control part” on page 264“Build descriptor part” on page 33Related reference


projectID

When you generate a COBOL program for z/OS, the projectID build descriptoroption assigns a value to the EZEPID symbolic parameter, which is used in buildscripts that run on z/OS. That parameter specifies the high-level qualifier for thedata sets that receive either source files or preparation output on the remotesystem.


“Build descriptor part” on page 33“Build scripts” on page 105“Symbolic parameters used with COBOL generation” on page 246


Related reference

“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“Build scripts delivered with EGL” on page 286“Predefined symbolic parameters that are set automatically” on page 250

reservedWord

When you generate a COBOL program, the reservedWord build descriptor optionspecifies a fully qualified path name for a text file that contains reserved wordsthat you want to add to EGL’s built-in list of COBOL, SQL, and CICS reservedwords.

There is no default value. For details, see “COBOL reserved-word file” on page258.

Related concepts


“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“COBOL reserved-word file” on page 258

resourceAssociations

The resourceAssociations build descriptor option contains the name of a resourceassociations part, which relates record parts to files and queues on the targetplatforms. This option is not required for generation, and no default value isavailable.

Related concepts

“Build descriptor part” on page 33“Resource associations part” on page 65Related tasks

“Adding a resource associations part to an EGL build file” on page 69Related reference

“Association elements” on page 71“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“Build descriptor options used with Java” on page 144Record and file type cross-reference

resourceBundleLocale

The resourceBundleLocale build descriptor option specifies a Java locale to beincluded in the name of a resource bundle that is generated for a VGUI record orfor a message table, either of which is used in a VGWebTransaction program.

For other details, see “genResourceBundle” on page 328.Related concepts



“Build descriptor options” on page 41“Build descriptor options used with Java” on page 144“genResourceBundle” on page 328

restartTransactionID

When you are generating a COBOL program, the restartTransactionID builddescriptor option indicates the transaction ID used to restart a program generatedfor CICS for z/OS. The restart occurs when the user submits data in response to aconverse statement in a VGWebTransaction program, or in a program that runs ina text application and is segmented.

The value of restartTransactionID initializes the value of the sysVar.transactionIDsystem variable. The default is a blank, which causes EGL to initializesysVar.transactionID with the transaction ID used to invoke the program.

If you specify restartTransactionID when the cicsEntries build descriptor option isset to a value other than NONE, EGL generates CICS definition entries for thetransaction, and cicsEntries indicates the format for those entries.

Related concepts


“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“CICS table files” on page 281“cicsEntries” on page 304“startTransactionID” on page 361

restoreCurrentMsgOnError

In relation to IMS BMP programs, the restoreCurrentMsgOnError build descriptoroption specifies whether, if the program ends because of an error, a message that isbeing read by an EGL statement is reinserted on the IMS message queue. Thisoption is in effect only if specified for the first program in the run unit.

If an AIBTDLI, EGLTDLI, or VGTDLI call is used to read the message queue, themessage is not reinserted.

Values

YES Reinsert the message. This is the default for a transaction-oriented IMSBMP programs.

NO Do not reinsert the message. This is the default for other IMS BMPprograms.

Related concepts




“Build descriptor options used with COBOL” on page 234

returnTransaction

When you generate a COBOL program, the returnTransaction build descriptoroption identifies the IMS/VS or CICS transaction that starts when the transactionassociated with the EGL-generated program ends without a transfer.

This option is effective at run time only if the option is specified for the firstprogram in the run unit. You usually use this option when a menu-driven programstarts the run unit and you want to return to the menu.

For CICS, only four characters are processed; if you specify more, the fifth andlater characters are ignored.

If you do not specify returnTransaction, the user’s screen is cleared when theprogram ends and does not transfer. For IMS/VS, if you want to avoid clearing thescreen, assign EZENOINS to the build descriptor option.

Related concepts



secondaryTargetBuildDescriptor

The secondaryTargetBuildDescriptor build descriptor option specifies a builddescriptor that guides the generation of code being deployed to a Web applicationserver, while code that is targeted for other environments is being generated in thesame generation request.

This is useful if you are generating a project with the following parts in the EGLsource folder:v JSF handlers which will be deployed to a Web application serverv Programs that the JSF handlers call from a platform that is outside of a Web

application server

It is also useful if you are generating a VGWebTransaction program with thegenVGUIRecords build descriptor option set to YES so that both the program(destined to run outside of a Web application server) and the VGUIRecordsreferenced by that program are generated.

If you wish to use one build descriptor to control generation of two sets ofgeneratable parts, you can:v Establish build descriptor options for the generatable parts that are not deployed

to the Web application server.v Assign a value to the secondaryTargetBuildDescriptor build descriptor option

for the generatable parts that are deployed to the Web application server.

In a case like that described earlier, the secondaryTargetBuildDescriptor builddescriptor option can reference a build descriptor part to use when you generateJSF handlers.


Only the following build descriptor options have any effect in the build descriptorpart specified by the secondaryTargetBuildDescriptor build descriptor option:v destDirectoryv destHostv destPasswordv destPortv destUserIDv genDirectoryv genProjectv genResourceBundlev msgTablePrefixv resourceBundleLocalev systemv targetNLSv tempDirectory

Related concepts



separatorSymbol

The separatorSymbol build descriptor option specifies a character used forseparating the thousands and hundreds in a numeric value.

When you generate a COBOL program, if you do not specify the separatorSymbolbuild descriptor option, the value is set by the numeric separator characterspecified in the language-dependent options module specified for your runtimeinstallation. For z/OS, refer to the program directory for your runtime product fordetails.

When you generate Java code, the separatorSymbol build descriptor optionassigns a character to the vgj.nls.number.separator Java runtime property, but onlyif the genProperties build descriptor option is set to GLOBAL or PROGRAM. Ifyou do not specify the separatorSymbol build descriptor option, the default valueis determined by the locale associated with the vgj.nls.code Java runtime property.

The separatorSymbol build descriptor option does not affect numbers in JSFHandlers. By default, JSF Handlers use the client’s locale to determine theappropriate separator symbol. You can override the default locale with thesysLib.setLocale system function. You can find more information on this and othersystem functions in the EGL Language Reference.

Related concepts




“Build descriptor options used with COBOL” on page 234“Build descriptor options used with Java” on page 144

serverCodeSet

When you generate a COBOL program, the serverCodeSet build descriptor optionspecifies the name of the coded character set that is used by the z/OS or iSeriesbuild server. This option, along with the clientCodeSet build descriptor option,causes a particular data conversion to occur when file content, file-pathinformation, and environment variables are transferred from the workstation to thebuild server.

The coded character set specified for serverCodeSet must be the one defined to theICONV conversion service on the system where the build server is started. Thedefault is IBM-037, which is a character set that is used for English (U.S.). Fordetails, see “Data conversion” on page 85.

Related concepts


“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“clientCodeSet” on page 306“Data conversion” on page 85

serverType

The serverType build descriptor option identifies the type of Web applicationserver in which your output will be deployed. The option is used to createappropriate output when you generate an EGL service, a Web service, or anapplication that accesses a Web service. This build descriptor option is only usedwith Java and has no default.

The appropriate setting depends on the platform on which you intend to deploythe generated output.

Values

WebSphere 7.xThe generated output will be deployed on WebSphere Application Serverversion 7.x.

WebSphere 6.xThe generated output will be deployed on WebSphere Application Serverversion 6.x.

WebSphere 5.1.2The generated output will be deployed on WebSphere Application Serverversion 5.1.2. (However, the minimum support required for Web services isWebSphere Application Server version 5.1.1.)

Tomcat 6.xThe generated output will be deployed on Apache Tomcat version 6.x.

Tomcat 5.xThe generated output will be deployed on Apache Tomcat version 5.x.


CICS 3.1The generated output will be deployed on CICS 3.1.

In relation to WebSphere Application Server and Apache Tomcat, this builddescriptor option is used with the j2eeLevel build descriptor option.

Related concepts


“Build descriptor options” on page 41“Build descriptor options used with Java” on page 144“j2eeLevel” on page 333

sessionBeanID

The sessionBeanID build descriptor option identifies the name of an existingsession element in the J2EE deployment descriptor. The environment entries areplaced into the session element when you act as follows:v Generate a program for a Java platform (by setting system to AIX, WIN, or USS)v Generate into an EJB project (by setting genProject to an EJB project)v Request that environment properties be generated (by setting genProperties to

GLOBAL or PROGRAM)

The sessionBeanID build descriptor option is useful in the following case:1. You generate a Java wrapper, along with an EJB session bean. In the EJB project

deployment descriptor (file ejb-jar.xml), EGL creates a session element, withoutenvironment entries.Both the EJB session bean and the session element are named as follows:

ProgramnameEJBBean

Programname is the name of the runtime program that receives data by way ofthe EJB session bean. The first letter in the name is uppercase, the other lettersare lowercase.In this example, the name of the program is ProgramA, and the name of thesession element and the EJB session bean is ProgramaEJBBean.

2. After you generate the EJB session bean, you generate the Java program itself.Because the build descriptor option genProperties is set to YES, EGL generatesJ2EE environment entries into the deployment descriptor, into the sessionelement established in step 1.

3. You generate ProgramB, which is a Java program that is used as a helper classfor ProgramA. The values of system and genProject are the same as those usedin step 2; also, you generate environment entries and set sessionBeanID to thename of the session element.Your use of sessionBeanID causes EGL to place the environment entries for thesecond program into the session element that was created in step 2; specifically,into the session element ProgramaEJBBean.

In the portion of the deployment descriptor that follows, EGL created theenvironment entries vgj.nls.code and vgj.nls.number.decimal during step 2, whenProgramA was generated; but the entry vgj.jdbc.default.database is used only byProgramB and was created during step 3:


<ejb-jar id="ejb-jar_ID"><display-name>EJBTest</display-name><enterprise-beans>

<session id="ProgramaEJBBean"><ejb-name>ProgramaEJBBean</ejb-name><home>test.ProgramaEJBHome</home><remote>test.ProgramaEJB</remote><ejb-class>test.ProgramaEJBBean</ejb-class><session-type>Stateful</session-type><transaction-type>Container</transaction-type<env-entry><env-entry-name>vgj.nls.code</env-entry-name><env-entry-type>java.lang.String</env-entry-type><env-entry-value>ENU</env-entry-value></env-entry><env-entry><env-entry-name>vgj.nls.number.decimal</env-entry-name><env-entry-type>java.lang.String</env-entry-type><env-entry-value>.</env-entry-value></env-entry><env-entry><env-entry-name>vgj.jdbc.default.database</env-entry-name><env-entry-type>java.lang.String</env-entry-type><env-entry-value>jdbc/Sample</env-entry-value></env-entry>

</session></enterprise-beans>

</ejb-jar>

A session element must be in the deployment descriptor before you can addenvironment entries. Because session elements are created during Java wrappergeneration, it is recommended that you generate the Java wrapper beforegenerating the related programs.

In the following cases, you generate a program into an EJB project, but theenvironment entries are placed into a J2EE environment file rather than into thedeployment descriptor:v sessionBeanID is set, but the session element that matches the value of

sessionBeanID is not found in the deployment descriptor; orv sessionBeanID is not set, and the session element that is named for the program

is not found in the deployment descriptor. This case occurs when the program isgenerated before the wrapper.

For EJB projects, an environment entry name (like vgj.nls.code) can appear onlyonce for each session element. If an environment entry already exists, EGL updatesthe entry type and value instead of creating a new entry.

EGL never deletes an environment entry from a deployment descriptor.

No default value is available for sessionBeanID.Related concepts




setFormItemFull

The setFormItemFull build descriptor option is used only when you generate aform group that includes print forms. The option indicates whether to displayasterisks (*) in every empty field for which you specified a set statement of theform set field full.

Values

YES (the default value)Display asterisks in the empty fields.

NO Do not display asterisks in empty fields.

If you specify NO, the set statement of format set field full is ignored forthe print forms, which may result in better performance and smaller loadmodule size, especially if the form group contains print forms with manyvariables. Specify NO if the programs that use the form group do not use aset statement of format set field full.

Related concepts



spaADF

The spaADF build descriptor option specifies whether the program beinggenerated transfers to or from an IMSADF II program.

For details, see Transferring to and from IMSADF II programs.

Values

YES The program transfers to or from an IMSADF II program.

If you specify YES, make sure that the value of the spaSize builddescriptor option is 28.

NO (the default value)The program does not transfer to or from an IMSADF II program.

Related concepts


“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“spaStatusBytePosition” on page 353“spaSize”

spaSize

The spaSize build descriptor option specifies the number of bytes in the IMSscratch-pad area (SPA). The default is 0.


If the program receives control from an IMSADF II program, the value of spaSizemust be set to 28, which is the size of the IMSADF II SPA when the IMS ADF IIwork database is used. If the program receives control as a result of an IMSmessage switch but not from an IMSADF II program, the value of spaSize must belarge enough to contain the required IMS SPA fields, the programs’s input record,and a segmentation status byte.

See also spaStatusBytePosition and (if your program receives control from anIMSADF II program) spaADF.

For an overview of program switches, see Transfers among IMS MPPs.Related concepts


“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“spaADF” on page 352“spaStatusBytePosition”

spaStatusBytePosition

The spaStatusBytePosition build descriptor option specifies the position of asegmentation status byte in the IMS scratch pad area (SPA). The byte is used byEGL runtime.

The spaStatusBytePosition build descriptor option is ignored if the value of thespaSize build descriptor option is 0 (in which case no SPA is available) or if theprogram is invoked by an immediate program switch (in which case thesegmentation status byte is the last byte of the SPA).

If the program receives control from an IMSADF II program, the value ofspaStatusBytePosition may be any integer between 15 and 28, inclusive.Otherwise, the value may be 15 or may equal the value specified for the spaSizebuild descriptor option; in the latter case, the segmentation status byte is the lastbyte of the SPA.

Related concepts


“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“spaADF” on page 352“spaSize” on page 352

spacesZero

The spacesZero build descriptor option specifies whether the generated programincludes extra code to process numeric variables that are filled with spaces. Thespecific situation concerns variables that have the following characteristics:v Were declared in EGL with primitive type NUM or NUMCv Can receive spaces, as when the variable is subordinate to a structure item of

type CHAR


The spacesZero build descriptor option has no effect on variables that receive acombination of spaces and other characters.

Values

NO (the default value)Does not include the extra code necessary to interpret the spaces as zeros.NO is appropriate if you are sure that no NUM or NUMC variables in theprogram will ever receive spaces. NO is the default because the code ismore efficient at run time.

YES Include extra code to avoid an abend when a NUM or NUMC variablecontaining spaces is processed in a program or function script. The variableis treated as if the spaces were zeros.

Related concepts



sqlCommitControl

When you generate Java code, the sqlCommitControl build descriptor optionallows generation of a Java runtime property that specifies whether a commitoccurs after every change to the default database. Regardless of the value of thisbuild descriptor option, EGL commits the changes to the database at the end ofeach run unit.

The vgj.jdbc.default.database.commitControl property is generated only if thegenProperties build descriptor option is also set to PROGRAM or GLOBAL. Youcan set the Java runtime property at deployment time regardless of your decisionat generation time.

Values

NOAUTOCOMMIT (the default)EGL does not automatically commit changes to the database. You cancommit the changes manually with the sysLib.commit() system function,or you can reverse the changes with sysLib.rollback().

For details on the rules of commit and rollback in this case, see the topic″Logical unit of work″ in the EGL Language Reference.

AUTOCOMMITAfter each successful change to the database, EGL commits the changeautomatically. This behavior is consistent with previous versions of theInformix product I4GL.

NOCOMMITEGL does not commit changes to the database. The sysLib.commit() andsysLib.rollback() system functions have no effect on the database.NOCOMMIT is appropriate for databases that do not support transactionsand for programs running within a transaction defined outside of EGL.

Related concepts



“Overview of Java runtime properties” on page 153Related reference


sqlDB

The sqlDB build descriptor option specifies the default database used by agenerated Java program that runs outside of J2EE. The value is a connection URL;for example, jdbc:db2:MyDB.

The sqlDB build descriptor option is case-sensitive, has no default value, and isused only when you are generating a non-J2EE Java program. The option assigns avalue to the vgj.jdbc.default.database Java runtime property, but only if thegenProperties build descriptor option is set to GLOBAL or PROGRAM.

To specify the default database for a J2EE program, set the sqlJNDIName builddescriptor option.

If you set the validateSQLStatements build descriptor option to YES, the locationof the database used for generation-time validation of the SQL statements isdetermined in the following manner:v If you are generating in the workbench, EGL uses the connection currently

specified in the EGL Preferences. You can find those preference settings byfollowing these steps:1. Open the Preferences window by clicking Window → Preferences.2. On the left side of the Preferences window, expand EGL and click SQL

Database Connections.3. Under Connection details, fill in the connection information in the field, or

click New to use the wizard to set up a new connection.v If you are using the EGL SDK, EGL uses the sqlJDBCDriverClass and

sqlValidationConnectionURL build descriptor options.Related concepts

“Build descriptor part” on page 33“Overview of Java runtime properties” on page 153“Generation using the Eclipse workbench” on page 11“Generation using the EGL software development kit (SDK)” on page 15Related reference

“Build descriptor options” on page 41“Build descriptor options used with Java” on page 144“Build descriptor options used with COBOL” on page 234“genProperties” on page 326“sqlID” on page 356“sqlJDBCDriverClass” on page 357“sqlJNDIName” on page 359“sqlPassword” on page 360“sqlValidationConnectionURL” on page 360“validateSQLStatements” on page 372


sqlErrorTrace

When you generate a COBOL program for z/OS, the sqlErrorTrace builddescriptor option specifies whether the generated COBOL program includes thecode necessary to trace the SQL error codes from the SQL communications area(SQLCA) that occur during I/O operations against a relational database.

To trace the actual SQL I/O statements, use the sqlIOTrace build descriptor option.To trace non-I/O statements, use the statementTrace build descriptor option.

For more information about enabling tracing and for information about obtainingthe trace output, refer to the IBM Rational Business Developer EGL Server Guidefor IBM i or IBM Rational COBOL Runtime Guide for zSeries, as appropriate foryour target runtime environment.

Values

NO (the default value)Specifies that the program will not include the code to enable tracing.

YES Specifies that you want the generated COBOL program to include thenecessary code to enable tracing. Adding trace information to the COBOLcode can increase generation time and affect runtime performance.

Related concepts


“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“sqlIOTrace” on page 357“statementTrace” on page 361

sqlID

The sqlID build descriptor option is used for the following two purposes:v When you generate either COBOL or Java code, and set the

validateSQLStatements build descriptor option to YES, the sqlID builddescriptor option specifies a user ID that is used to connect to a database duringgeneration-time validation of SQL statements.

v When you generate Java code, sqlID specifies a user ID to use when accessingthe database at runtime. If you set the sqlID build descriptor option, it assigns avalue to the vgj.jdbc.default.userid Java runtime property, but only if thegenProperties build descriptor option is set to GLOBAL or PROGRAM.

The sqlID build descriptor option is case-sensitive and has no default value.Related concepts




“genProperties” on page 326“sqlDB” on page 355“sqlJDBCDriverClass”“sqlJNDIName” on page 359“sqlPassword” on page 360“sqlValidationConnectionURL” on page 360“validateSQLStatements” on page 372

sqlIOTrace

When you generate a COBOL program for z/OS, the sqlIOTrace build descriptoroption specifies whether the generated COBOL program includes the codenecessary to trace the I/O operations done against a relational database.

To trace the SQL error codes that occur during the I/O operations on a relationaldatabase, use the sqlErrorTrace build descriptor option. To trace non-I/Ostatements, use the statementTrace build descriptor option.

For more information about enabling tracing and for information about obtainingthe trace output, refer to the IBM Rational Business Developer EGL Server Guidefor IBM i or IBM Rational COBOL Runtime Guide for zSeries, as appropriate foryour target runtime environment.

Values

NO (the default value)Specifies that the program will not include information to enable tracing.

YES Specifies that you want the generated COBOL program to include thenecessary code to enable tracing. Adding trace information to the code canincrease generation time and affect runtime performance.

Related concepts


“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“sqlErrorTrace” on page 356“statementTrace” on page 361

sqlJDBCDriverClass

The sqlJDBCDriverClass build descriptor option is used for the following twopurposes:v Specifies a driver class that is used to connect to a database during

generation-time validation of SQL statements when you generate either COBOLor Java code using the EGL SDK and set the validateSQLStatements builddescriptor option to YES. You specify the location of the database by setting thesqlValidationConnectionURL build descriptor option. Database access isthrough JDBC.

Note: When you generate either COBOL or Java code using the workbench,EGL uses the database connection currently specified in the EGL


Preferences. See the section on setting preferences in the EGL Programmer’sGuide for information on setting EGL preferences.

v Specifies a driver class to use when accessing the database at run time when yougenerate Java code. If you set the sqlJDBCDriverClass build descriptor option,it assigns a value to the vgj.jdbc.drivers Java runtime property in the programproperties file, but only if the following conditions are both true:– The genProperties build descriptor option is set to GLOBAL or PROGRAM.– The j2ee build descriptor option is set to NO.

There is no default value. The format for the value varies by driver:v For the IBM DB2 Universal Driver for Windows, the driver class is as follows

(with com in lower case):com.ibm.db2.jcc.DB2Driver

v For the IBM DB2 App Driver for Windows, the driver class is as follows:COM.ibm.db2.jdbc.app.DB2Driver

v For the Oracle JDBC thin client-side driver, the driver class is as follows:oracle.jdbc.driver.OracleDriver

v For the IBM Informix JDBC driver, the driver class is as follows:com.informix.jdbc.IfxDriver

v For the Apache Derby driver, the driver class is as follows:org.apache.derby.jdbc.EmbeddedDriver

v For the Cloudscape® driver, the driver class is as follows:com.ibm.db2j.jdbc.DB2Driver

v For the SQL Server 2000 driver, the driver class is as follows:com.microsoft.sqlserver.jdbc.SQLServerDriver

v For the SQL Server 2005 driver, the driver class is as follows:com.microsoft.jdbc.sqlserver.SQLServerDriver

For other driver classes, see the documentation for the driver.

To specify more than one driver class, separate each class name from the next witha colon (:). You might do this if one Java program makes a local call to another butaccesses a different database management system.

Related concepts


“Build descriptor options” on page 41“Build descriptor options used with Java” on page 144“Build descriptor options used with COBOL” on page 234“genProperties” on page 326“j2ee” on page 333“sqlDB” on page 355“sqlID” on page 356“sqlPassword” on page 360“sqlValidationConnectionURL” on page 360


“validateSQLStatements” on page 372

sqlJNDIName

The sqlJNDIName build descriptor option specifies the default database used by agenerated Java program that runs in J2EE. To set the value, use the name in theJNDI registry to which the default data source is bound; for example, jdbc/MyDB.

The sqlJNDIName build descriptor option is case-sensitive, has no default value,and is used only when you are generating a Java program for J2EE. The optionassigns a value to the vgj.jdbc.default.database Java runtime property, but only ifthe genProperties build descriptor option is set to GLOBAL or PROGRAM. Thisruntime property is stored in the J2EE deployment descriptor.

If you set the validateSQLStatements build descriptor option to YES, the locationof the database used for generation-time validation of the SQL statements isdetermined in the following manner:v If you are generating in the workbench, EGL uses the connection currently




sqlValidationConnectionURL build descriptor options.

To specify the database name for a non-J2EE program, set the sqlDB builddescriptor option.

Related concepts


“Build descriptor options” on page 41“Build descriptor options used with Java” on page 144“Build descriptor options used with COBOL” on page 234“genProperties” on page 326“sqlDB” on page 355“sqlID” on page 356“sqlJDBCDriverClass” on page 357“sqlPassword” on page 360“sqlValidationConnectionURL” on page 360“validateSQLStatements” on page 372


sqlPassword

The sqlPassword build descriptor option is used for the following two purposes:v Specifies a password that is used to connect to a database during

generation-time validation of SQL statements when you generate either COBOLor Java code and set the validateSQLStatements build descriptor option to YES.

v Specifies a password to use when accessing the database at runtime when yougenerate Java code. If you set the sqlPassword build descriptor option, it assignsa value to the vgj.jdbc.default.database.password Java runtime property, butonly if the genProperties build descriptor option is set to GLOBAL orPROGRAM.

The sqlPassword build descriptor option is case-sensitive and has no default value.Related concepts


“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“Build descriptor options used with Java” on page 144“genProperties” on page 326“sqlDB” on page 355“sqlID” on page 356“sqlJDBCDriverClass” on page 357“sqlJNDIName” on page 359“sqlValidationConnectionURL”“validateSQLStatements” on page 372

sqlSchema

When the genProperties build descriptor option is set to PROGRAM or GLOBAL,EGL uses the value of the sqlSchema build descriptor option to set thevgj.jdbc.schema Java runtime property. The vgj.jdbc.schema property in turn setsthe initial value of the currentSchema system variable. For more information, seecurrentSchema (EGL system variable).

Related concepts



sqlValidationConnectionURL

When you generate code using the EGL SDK, the sqlValidationConnectionURLbuild descriptor option specifies a URL for connecting to the database that EGLuses to validate SQL statements at generation time. Database access is throughJDBC.


No default is available for sqlValidationConnectionURL, and the format variesbased on the driver specified by the sqlJDBCDriverClass build descriptor option.Refer to the documentation on the database driver for information on the format itexpects for the connection URL.

Related concepts


“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“Build descriptor options used with Java” on page 144“sqlDB” on page 355“sqlID” on page 356“sqlPassword” on page 360“sqlJDBCDriverClass” on page 357“validateSQLStatements” on page 372

startTransactionID

When you generate a COBOL program for a CICS environment, thestartTransactionID build descriptor option indicates the transaction ID used tostart that program. The default is the first four characters of the program alias or,in the absence of an alias, the first four characters of the program name.

This option has no affect at run time; instead, the value of startTransactionIDidentifies the transaction ID in a CICS definition that is generated when thecicsEntries build descriptor option is set to a value other than NONE.

Related concepts


“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“CICS table files” on page 281“cicsEntries” on page 304“restartTransactionID” on page 346

statementTrace

When you generate a COBOL program for z/OS, the statementTrace builddescriptor option specifies whether the generated program includes the codenecessary to trace the non-SQL statements in your program.

To trace the SQL error codes that occur during I/O operations on a relationaldatabase, use the sqlErrorTrace build descriptor option. To trace the actual SQLI/O statements, use the sqlIOTrace build descriptor option.

You can find more information about enabling tracing, and about obtaining thetrace output, in the IBM Rational Business Developer EGL Server Guide for IBM ior IBM Rational COBOL Runtime Guide for zSeries, as appropriate for your targetruntime environment.


Values

NO (the default value)Specifies that the program will not include code to enable tracing.

YES Specifies that you want the generated program to include the necessarycode to enable tracing. Adding additional information to the code canincrease generation time and affect performance.

Related concepts


“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“sqlErrorTrace” on page 356“sqlIOTrace” on page 357

synchOnPgmTransfer

The synchOnPgmTransfer build descriptor option is used when you aregenerating a COBOL program for a CICS environment; the option lets you tominimize the differences in behavior when a transferring program is generated forCICS as compared to when that program is generated for IMS/VS.

The option specifies whether to set a commit point if the following conditions aretrue:v The generated program runs a transfer to program statement;v The target program of the transfer statement is an EGL-generated program;v A PSB is scheduled; andv The default PSB referenced in the PSB record of the transferring program

matches the default PSB referenced in the PSB record of the target program.

Note: The default PSB is the value of the defaultPSBName property, which isset in the PSB record part. To see examples of PSB records, see the topic″DL/I Support″ in the EGL Language Reference.

The synchOnPgmTransfer build descriptor option has no effect in other cases.

The following rules also apply in an EGL-generated COBOL program:v On CICS, if no PSB is scheduled for the transferring program, a commit point

never occurs for a transfer to program statement, but always occurs for atransfer to transaction statement.

v On CICS or IMS, if the transferring program and the target program havedifferent default PSB references, a commit point always occurs for either atransfer to program or a transfer to transaction statement.

v On CICS or IMS, a commit point always occurs for a show statement

Values

NO As is true on IMS, the transfer to program statement does not commitrecoverable resources, close files, or close cursors in the case describedearlier.


YES (the default value)The transfer to program statement commits recoverable resources, closesfiles, and closes cursors in the case described earlier.

Related concepts

“Build descriptor part” on page 33“Linkage options part” on page 61Related reference

“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“transferToProgram element” on page 410“transferToTransaction element” on page 416transferUsing linkage options parts in a call or transfer

synchOnTrxTransfer

The synchOnTrxTransfer build descriptor option specifies whether a commit pointoccurs when one the following kinds of programs runs a transfer to transactionstatement:v A main program (a Basic or TextUI type program) in a Java environment; orv A main program that is generated for z/OS batch or IMS BMP.

However, synchOnTrxTransfer set to YES is not supported for atransaction-oriented IMS/BMP program (a program that does a get next statementfor a serial record that is associated with the I/O PCB). Transaction-orientedIMS/BMP programs automatically commit database changes on each get nextstatement to the I/O PCB, and cannot commit changes at any other point.

Values

NO (the default value)The transfer to transaction statement starts a program in the same rununit, but does not close or commit resources, which are available to theinvoked program.

YES The transfer to transaction statement commits recoverable resources, closesfiles, closes cursors, and starts a program in the same run unit.

Related concepts



sysCodes

When you generate a COBOL program, the sysCodes build descriptor optiondetermines the source of the return code that is placed in the sysVar.errorCodesystem variable in response to a file I/O error.

For more information, including specific error values, see the topic ″errorCode″ inthe EGL Language Reference.


Values

NO (the default value)sysVar.errorCode receives return codes that are returned from EGL runtimeservices. For information about the meaning of specific error codes, see theIBM Rational Business Developer EGL Server Guide for IBM i or IBMRational COBOL Runtime Guide for zSeries, as appropriate for your targetruntime environment.

YES sysVar.errorCode receives return codes that are returned from theoperating system.

The codes are specific to the target runtime environment and to the type ofresource being accessed (for example, VSAM instead of a transient dataqueue). For details on the meaning of specific error codes, see thedocumentation for the subsystem you are using (such as VSAM or CICS).

Related concepts



system

The system build descriptor option specifies the target platform for generation.This option is required. There is no default value.

Values

AIX Indicates that generation produces a Java program that can run on AIX.

HPUX Indicates that generation produces a Java program that can run on HP-UX.

IMSBMPIndicates that generation produces a COBOL program that can run in anIMS batch message processing (BMP) region.

IMSVSIndicates that generation produces a COBOL program that can run as anIMS message processing program (MPP).

ISERIESCIndicates that generation produces a COBOL program that can run oniSeries.

ISERIESJIndicates that generation produces a Java program that can run on iSeries

JAVASCRIPTIndicates that generation produces a Rich UI application: HTML-embeddedJavaScript, for transmission to browsers

LINUXIndicates that generation produces a Java program that can run on Linux(with an Intel processor).

SOLARISIndicates that generation produces a Java program that can run on Solaris.

USS Indicates that generation produces a Java program that can run on z/OSUNIX System Services.


WIN Indicates that generation produces a Java program that can run onWindows 2000/NT/XP.

ZOSBATCHIndicates that generation produces a COBOL program that can run onz/OS under the control of JCL.

ZOSCICSIndicates that generation produces a COBOL program that can run onCICS for z/OS.

Related concepts

“Build descriptor part” on page 33“Generation output and associated files” on page 91Related reference

“Build descriptor options” on page 41“Build descriptor options used with Java” on page 144“Build descriptor options used with COBOL” on page 234“Build descriptor options used with JavaScript” on page 220This topic lists the build descriptor options used with JavaScript, which is thegenerated language for EGL Rich UI.

targetNLS

The targetNLS build descriptor option specifies the national language code used toidentify runtime messages. If the Java locale on the development system isassociated with one of the supported languages, the default value of targetNLS isthe supported language. Otherwise, targetNLS has no default value.

For COBOL programs, the code for the first program in the run unit determinesthe language used for messages for all programs in the run unit.

When you generate Java code, the targetNLS build descriptor option assigns avalue to the vgj.nls.code Java runtime property, but only if the genProperties builddescriptor option is set to GLOBAL or PROGRAM. You can also change the valueat run time using the sysLib.setLocale system function. For more informationabout system function, see the EGL Language Reference.

The following table lists the supported languages. The code page for the languageyou specify must be loaded on your target platform.

Table 32. Supported languages

Code Languages Supported forCOBOL

CHS Simplified Chinese Yes

CHT Traditional Chinese Yes

CZE Czech No

DEU German Yes

ENU US English Yes

ESP Spanish Yes

FRA French Yes

HUN Hungarian No


Table 32. Supported languages (continued)

Code Languages Supported forCOBOL

ITA Italian Yes

JPN Japanese Yes

KOR Korean Yes

PLK Polish No

PTB Brazilian Portuguese Yes

RUS Russian No

For more information about the user message table used for programs, see thesection on the messageTablePrefix property in ″Program part properties″ in theEGL Language Reference. For additional details on the message table used for VGUIrecords in VGWebTransaction programs, see the topic for the msgTablePrefix builddescriptor option.

JSF Handlers do not use a message table, but use a JavaServer Faces messageresource. For details on that resource, see the description of the msgResourceproperty in “JSF Handler″ in the EGL Language Reference,

Related concepts



tempDirectory

The tempDirectory build descriptor option specifies the location where EGL placestwo different kinds of temporary files:v If you are generating with the EGL SDK, EGL uses this option to place the

Intermediate Representation (IR) files that it creates.v When you are generating a VGWebTransaction program or VGUIRecord into a

Web project, the option identifies the directory in which to store the JSP files.

To remove the IR files from the temporary directory both before and aftergeneration, set the -clean option in the EGLSDK command.

Web transactionsEGL creates the name of each JSP file in the directory identified by tempDirectoryin the following way:

recordAlias.jsp

recordAliasThe name of the VGUI record or (if an alias is specified) the alias for thatrecord.


The tempDirectory build descriptor option is used only when a JSP file of thesame name is in the WebContent\WEB-INF directory of the project to whichoutput is generated.

If you do not specify a value for tempDirectory and if a JSP file with the namerecordAlias.jsp is already in the directory WebContent\WEB-INF, the followingstatements apply:v The new JSP file is stored with the following name, in the directory

WebContent\WEB-INF:newrecordAlias.jsp

v Subsequent generations of the same UI record override the file newrecordAlias.jsp

A benefit of receiving the most recently generated JSP file is that you can copy andpaste snippets of that file into the JSP file that you customized earlier. If you didnot specify a value for tempDirectory, however, you should remove the filenewrecordAlias.jsp from the Web project before deploying that project.

You use the genProject build descriptor option to direct output to a Web project. Ifyou use the genDirectory build descriptor option instead, the effects are as follows:v Output goes into a directory insteadv The tempDirectory build descriptor option has no effectv The prefix new is not in the name of the generated JSP filev A generated JSP file overwrites any same-named file in the directory

Related concepts


“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“Build descriptor options used with Java” on page 144“EGLSDK” on page 18

templateDir

When you generate COBOL for z/OS batch, iSeries, or IMS/BMP, the templateDirbuild descriptor option specifies the directory that contains the templates used toproduce sample runtime JCL for z/OS batch or sample runtime CL for iSeries.

For z/OS batch, the sample runtime JCL is generated if the genRunFile builddescriptor option is set to YES.

For iSeries, the sample runtime CL is generated only for called programs. Thesample runtime CL is used at runtime only if the program is called from a clientprogram running on a workstation.

Related concepts


“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“Runtime CL templates for iSeries” on page 263“Runtime JCL templates for z/OS” on page 259


transferErrorTransaction

When you generate a COBOL program for a CICS environment, thetransferErrorTransaction build descriptor option specifies the name of a CICStransaction that receives control when a transfer statement results in an error.

Related concepts



truncateExtraDecimals

When you generate Java code, the truncateExtraDecimals build descriptor optionspecifies whether additional digits will be dropped or rounded off if a givennumeric value has more digits after the decimal point than the target can store.

Values

YES (the default value)Causes digits beyond the storage limit to be dropped (for example, if thenumeric value 1123.456 was assigned to num(5,1), the result would be avalue of 1123.4).

NO Causes digits beyond the storage limit to be rounded off (for example, ifthe numeric value 1123.456 was assigned to num(5,1), the result would bea value of 1123.5).

Related concepts



twaOffset

When you generate a COBOL program for a CICS environment, the twaOffsetbuild descriptor option specifies how many bytes in the transaction work area(TWA) are reserved for use by non-EGL programs in the same CICS run unit.

The default is 0, which means that the generated program uses the first 1024 bytesof the TWA to keep track of transaction status. A positive value means thegenerated program uses a block that starts after the specified number of bytes andcontinues for 1024 bytes.

If you set the cicsEntries build descriptor option to a value other than NONE, theTWASIZE value generated in the PCT or TRANSACTION entry is set to 1024 plusthe value specified for the twaOffset build descriptor option.

Related concepts




“Build descriptor options used with COBOL” on page 234“cicsEntries” on page 304

useCurrentSchema

When you set the useCurrentSchema build descriptor option to YES, EGL willprepend the contents of the sqlLib.currentSchema system variable to all SQL tablenames at runtime. For more information, see currentSchema (EGL system variable).

The default value of the option is NO, which disables this use ofsqlLib.currentSchema. This option is available only in Java and debugenvironments.

Related concepts



userMessageFile

The userMessageFile build descriptor option specifies the generated value for thevgj.messages.file Java runtime property. This property specifies a file of messagesthat you create. This file is a properties file, with name-value paired entries similarto the following examples:v Name1=Value1v Name2=Value2v and so on.

The file is searched in these cases:v When the EGL runtime responds to the invocation of the sysLib.getMessage

system function, which returns a message that you created.v When the EGL runtime is handling a ConsoleUI application and attempts to

present help or comment text from a file identified in theconsoleLib.messageResource system variable, but that variable has no value.

v When EGL attempts to display a Java runtime message.

The vgj.messages.file property is added only if the value of the genPropertiesbuild descriptor option is PROGRAM or GLOBAL.

For more information about the system variables and functions mentioned here,see the topics ″getMessage()″ and ″messageResource (EGL system variable)″ in theEGL Language Reference.

Related concepts




useXctlForTransfer

When you generate a COBOL program for z/OS batch or IMS BMP, theuseXctlForTransfer build descriptor option indicates whether to use an XCTLcommand as the default implementation for the transfer to program statement.This option is only used if your target runtime environment is z/OS batch or IMSBMP.

Regardless of the value you specify for the useXctlForTransfer build descriptoroption, you can control the implementation for a specific transfer to programstatement by using a linkage options part. Specifically, you can indicate theimplementation by using the transferToProgram element of the linkage optionspart, and the linkType property of that element. For more information, see thetopics for the transferToProgram element and linkType property.

Use of XCTL results in slower performance than use of a dynamic COBOL call.

See also the topics ″transfer″ and ″Using linkage options parts in a call or transfer″in the EGL Language Reference.

Values

NO (the default value)Uses a dynamic COBOL call by default.

YES Uses an XCTL by default.Related topics


“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“linkType in transferToProgram element” on page 414“transferToProgram element” on page 410

vagCompatibility

The vagCompatibility build descriptor option indicates whether special programsyntax can be used in the generation process, as described in ″VisualAge Generatorcompatibility″ in the EGL Language Reference.

The setting of the vagCompatibility EGL preference determines the default valueof the build descriptor. If you are generating in the EGL SDK, no preferences areavailable, and the default value of vagCompatibility is NO.

Values

NO (the default value)

YES Specify YES only if your EGL source code uses the special syntax.Related concepts




“Build descriptor options used with COBOL” on page 234VisualAge Generator compatibility

validateMixedItems

When you generate a COBOL program, the validateMixedItems build descriptoroption specifies whether a generated program validates the integrity of DBCHARstrings when an MBCHAR variable is assigned to another MBCHAR variable.

Values

NO EGL run time services do not validate the data in an MBCHAR-to-MBCHAR assignment If your program assigns values to MBCHARvariables, but the error situation for MBCHAR-to-MBCHAR assignment isnot possible, you can set this option to NO for better runtime performance.

YES (the default value)EGL runtime services validate the data in an MBCHAR-to-MBCHARassignment. If the resulting value would contain an invalid DBCS string,such as a split DBCHAR character or a missing final shift-in character, EGLtruncates characters as needed to ensure that the target variable contains avalid string of type MBCHAR, then adds (if necessary) terminatingsingle-byte blanks.

For more information on exception handling and variable types, see the topics″Exception handling″ and ″Primitive data types″ in the EGL Language Reference.

Related concepts



validateOnlyIfModified

The validateOnlyIfModified build descriptor option specifies whether to validateonly those text-form fields for which the modified data tag is set.

Values

YES Validate only fields for which the modified data tag is set.

NO (the default value)Validate all variable fields.

You can find more information on modifying tags in the topic ″Modified data tagand modified property″ in the EGL Language Reference.

Related concepts




validateSQLStatements

The validateSQLStatements build descriptor option indicates whether SQLstatements are validated against a database at generation time. EGL connects to thedatabase in one of the following ways:v If you are generating in the workbench, EGL uses the connection currently




sqlValidationConnectionURL build descriptor options.

In either case, you might need to set the sqlID and sqlPassword build descriptoroptions.

Note: Validation of SQL statements increases the time required to generate yourcode.

When you request SQL validation, the database manager accessed from thegeneration platform prepares the SQL statements dynamically.

SQL statement validation has these restrictions:v No validation is possible for SQL statements that use dynamic SQL and are

based on SQL records.v The validation process might indicate errors that are found by the database

manager in the generation environment, but that will not be found by thedatabase manager on the target platform.

v Validation occurs only if your JDBC driver supports validation of SQL preparestatements and (in some cases) only if you have configured the driver to do suchvalidation; for information, see the documentation for your JDBC driver.

Values

NO (the default value)Validation does not occur.

YES Validation occurs.Related concepts


“Build descriptor options” on page 41“Build descriptor options used with COBOL” on page 234“Build descriptor options used with Java” on page 144“sqlID” on page 356“sqlJDBCDriverClass” on page 357“sqlPassword” on page 360“sqlValidationConnectionURL” on page 360


workDBType

The workDBType build descriptor option specifies the type of work database touse at run time. You use this option if you have set the system build descriptoroption to CICS or IMSVS and if the workDBType build descriptor option isspecified for the first program in the run unit.

If the system build descriptor option is set to ISERIESC, the work database isalways SQL, regardless of the value of workDBType.

The work database is used to:v Save the program status after you issue a converse statement in a text or Web

application.v Save the program status after you issue a show statement in a Web transaction.v Save input from a form while the user views a help form.v Save output for a text form if an error message must be displayed when you did

not specify a value for the form’s messageField property.v Save a copy of a text form when you issue a show statement that includes a

returning to clause to transfer control to another program.

Values

AUX (the default value for CICS)Save program status data in a CICS auxiliary temporary storage queue.

MAIN Save program status data in a CICS main temporary storage queue.

DLI (the default value for IMS)Save program status data in a DL/I database.

SQL Save program status data in a relational database.Related concepts



wrapperCompatibility

The build descriptor option wrapperCompatibility indicates how to regeneratewrappers that you intend to use with handwritten Java code when the wrapperswere originally generated by VisualAge Generator 4.5, EGL 5.x, or EGL 6.x.

If you change the parameters of an EGL program that was accessed by way of theJava wrapper, you must regenerate the Java wrapper with wrapperCompatibilityset to CURRENT, which is the default.

If you set wrapperCompatibility to anything other than CURRENT, you shoulduse only the current product JAR files and not the JAR files included with theprior versions of the product. For details on accessing the JAR files, see Installingthe EGL runtime code for Java.


Values

CURRENT (the default)Use this option to generate Java wrappers with the current version of EGL.In this case, the wrapper and your handwritten code require runtimeaccess to fda7.jar.

V6 Use this option to generate Java wrappers compatible with runtime classesfrom EGL 6.x. In this case, the wrapper and your handwritten code requireruntime access to fda7.jar and fda6wrappers.jar.

V5 Use this option to generate Java wrappers compatible with runtime classesfrom EGL 5.x. In this case, the wrapper and your handwritten code requireruntime access to fda7.jar and hpt.jar

V4 Use this option to generate Java wrappers compatible with runtime classesfrom VisualAge Generator 4.5. In this case, the wrapper and handwrittencode require runtime access to fda7.jar and hpt.jar.

Related tasks

“Installing the EGL runtime code for Java” on page 195Related concepts



wrapperJNDIPrefix

The wrapperJNDIPrefix build descriptor option specifies a prefix to be added toall JNDI names for generated session beans. For example, the default JNDI namefor an EJB generated for a program named prog1 is Prog1EJB. IfwrapperJNDIPrefix is set to my.company.ejbs/, the generated JNDI name wouldbe my.company.ejbs/Prog1EJB.

By default, wrapperJNDIPrefix has no value.Related concepts



wrapperPackageName

The wrapperPackageName build descriptor option specifies the package togenerate Java wrappers into. If this build descriptor option is not set (as is thedefault), the Java wrappers are generated to the same package as thecorresponding EGL part.

Related concepts




Linkage options part

A linkage options part provides the various elements that enable you to specifydetails about how you want certain statements to be implemented in yourgenerated code. The following elements can be included in the linkage optionspart:v The asynchLink element provides details on how a generated program starts a

particular program or transaction asynchronously using thevgLib.startTransaction system function.

v The callLink element provides details on how a call statement is to beimplemented when calling a particular program, or how a particular calledprogram is to be called.

v The fileLink element provides details on whether to use remote file I/O for aparticular file in the CICS environment.

v The transferToProgram element provides details on how a transfer to programstatement is to be implemented when transferring control to a particularprogram.

v The transferToTransaction element provides details on how a transfer totransaction statement is to be implemented when transferring control to aparticular transaction (or program in nontransactional environments).

In this reference section, you can find information on the various elementsavailable for use in the linkage options part. From the topics on each element, youcan find links to the property settings available for each element.

Related concepts

“Linkage options part” on page 61Related reference

“asynchLink element”“callLink element” on page 380“fileLink element” on page 407“transferToProgram element” on page 410“transferToTransaction element” on page 416

asynchLink element

An asynchLink element of a linkage options part specifies how a generated Java orCICS program starts a particular program asynchronously, as occurs when theoriginating program starts the vgLib.startTransaction system function.

You can avoid specifying an asynchLink element if you accept the defaultbehavior, which assumes that the created transaction is to be started on the sameCICS system or from the same Java package.

Each element includes the recordName property, which references a record that isalso referenced in the specific vgLib.startTransaction system function whose actionis being modified.

The following statements apply to programs that run on CICS:


v The type property indicates whether the program being invoked is local (as isthe default) or remote

v The following properties are meaningful only when the value of type is remote:– conversionTable

– locationSpec

These are both for invoking a transaction for a remote CICS region.

For Java programs, the only property is package, which is needed only if thesource for the started program is in a package that is different from the originatingprogram. You can find more information about the vgLib.startTransaction systemfunction in the topic ″startTransaction″ in the EGL Language Reference.

Related concepts


“Editing the asynchLink element of a linkage options part”Related reference

“conversionTable in asynchLink element” on page 377“locationSpec in asynchLink element” on page 378“package in asynchLink element” on page 379“recordName in asynchLink element” on page 379“type in asynchLink element” on page 379

Editing the asynchLink element of a linkage options part

An asynchLink element of a linkage options part specifies how a generated Java orCICS program starts a particular program asynchronously, as occurs when theoriginating program starts the vgLib.startTransaction system function. To edit theasynchLink element of a linkage options part:1. Locate the EGL build file you want to work with in the Project Explorer view.

To find it, open the EGL Source folder and look for a file with the extension.EGLBLD.

2. Right-click the build file and then click Open With → EGL Build Parts Editor.The Build Parts Editor opens the build descriptor part automatically; thedefault view is the General Options view.

3. If you have the Outline view open, you will see the build descriptor part listedunder the name of your build file. If you do not have the Outline view open,click Window → Show View → Other; in the Show View window, click toexpand General and select Outline.

4. In the Outline view, right-click a linkage options part and click Open. The EGLBuild Parts Editor displays the current part declaration.

5. Click the Show AsynchLink Elements button on the editor toolbar.6. To add a new asynchLink element, click Add or press the Insert key, and then

type the record name or select a record name from the Record Namedrop-down list.

7. To change the default linkage type associated with your record name, performone of the following steps:v Select the corresponding row in the AsynchLink Elements list, and then

click the Type field once to put the field into edit mode. Select the newlinkage type from the Type drop-down list.


v In the Properties of selected asynchLink elements list, click the propertyonce to put the Value field associated with that property into edit mode.Select the new linkage type from the Value drop-down list.

8. Other properties associated with your record name are listed in the Propertiesof selected asynchLink elements list based on the linkage type. To change thevalue of one of these properties:a. Select the record name.b. In the Properties of selected asynchLink elements list, click the property

you want to set once to put the Value field associated with that propertyinto edit mode.

c. Set the new value by selecting an option in the Value drop-down list or byentering the new value in the Value field. For some properties, you can onlyselect an option in a drop-down list. For other properties, you can only typea value in the Value field.

9. Modify the asynchLink elements list as needed:v To reposition an asynchLink element, select an element and click either

Move Up or Move Down.v To remove an asynchLink element, select an element and click Remove or

press the Delete key.Related topics


“Adding a linkage options part to an EGL build file” on page 63“Editing the callLink element of a linkage options part” on page 387“Editing the fileLink element of a linkage options part” on page 407“Editing the transferToProgram element of a linkage options part” on page 411“Editing the transferToTransaction element of a linkage options part” on page416“Removing a linkage options part from an EGL build file” on page 64Related reference

“asynchLink element” on page 375“EGL build-file format” on page 30

conversionTable in asynchLink element

The conversionTable property of the asynchLink element in the linkage optionspart specifies the name of the conversion table that is used to convert parameterdata when the program uses the vgLib.startTransaction system function. TheconversionTable property is meaningful only if all the following are true:v The started program is on CICSv The value of type is remote

v The started program runs on a platform that supports the ASCII character set

The default is that no conversion occurs, in which case the program must performany required conversion by calling sysLib.convert or by defining a conversiontemplate to CICS.

You can specify one of the following values:


conversion table nameThe originating platform uses the conversion table specified. For a list oftables, see “Data conversion” on page 85.

* Use the default conversion table. The name of that table is ELACNxxx, wherethe value of xxx is the value of the targetNLS build descriptor option.

PROGRAMCONTROLLEDThe caller uses the conversion table name that is in thesysVar.callConversionTable system variable at run time. IfsysVar.callConversionTable contains blanks, no conversion occurs.

For further details, see “Data conversion” on page 85; see also the topics″convert()″ and ″callConversionTable″ in the EGL Language Reference.

Related concepts

“Data conversion” on page 85“Linkage options part” on page 61Related reference

“asynchLink element” on page 375“locationSpec in asynchLink element”“package in asynchLink element” on page 379“recordName in asynchLink element” on page 379“targetNLS” on page 365“type in asynchLink element” on page 379

locationSpec in asynchLink element

The locationSpec property of the asynchLink element in the linkage options partspecifies how the CICS system identifier of a remote transaction is defined:

CICSSpecifies that the location for the remote transaction is defined in the CICSprogram control table (PCT) or in an RDO TRANSACTION entry.

PROGRAMCONTROLLEDSpecifies that the location for the remote transaction is obtained from thesysVar.remoteSystemID system variable when the program invokes thevgLib.startTransaction system function. The location is passed to CICS by wayof the SYSID keyword on the EXEC CICS command.

You can find more information on the sysVar.remoteSystemID system variable andthe vgLib.startTransaction system function in the topics ″remoteSystemID″ and″startTransaction″ in the EGL Language Reference.

Related concepts


“asynchLink element” on page 375“conversionTable in asynchLink element” on page 377“package in asynchLink element” on page 379“recordName in asynchLink element” on page 379“type in asynchLink element” on page 379


package in asynchLink element

The package property of the asynchLink element in a linkage options part is validonly for Java output and specifies the name of the package that contains theprogram being started. The default is the package of the originating program.

The package name that is used in generated Java programs is the package name ofthe EGL program, but in lower case; and when EGL generates output from theasynchLink element, the value of package is changed (if necessary) to lower case.

Related concepts


“asynchLink element” on page 375“conversionTable in asynchLink element” on page 377“locationSpec in asynchLink element” on page 378“recordName in asynchLink element”“type in asynchLink element”

recordName in asynchLink element

The recordName property of the asynchLink element in a linkage options partspecifies the name of the record that is used in the vgLib.startTransaction systemfunction. In this case, the asynchLink element provides the information needed togenerate any vgLib.startTransaction system function that corresponds to the recordspecified by the recordName property.

You can use an asterisk (*) as a global substitution character in the record name;however, that character is valid only as the last character. You can find moreinformation about the vgLib.startTransaction system function in the topic″startTransaction″ in the EGL Language Reference.

Related concepts


“asynchLink element” on page 375“conversionTable in asynchLink element” on page 377“locationSpec in asynchLink element” on page 378“package in asynchLink element”“type in asynchLink element”

type in asynchLink element

The type property of the asynchLink element of the linkage options part specifiesthe type of linkage to generate on CICS. This property is ignored for Javaprograms. The following values are valid:

local (the default)Indicates that the CICS transaction being created is in the same region as theoriginating program.

remoteIndicates that the CICS transaction being created might be in a different regionfrom the originating program.


Related concepts


“asynchLink element” on page 375“conversionTable in asynchLink element” on page 377“locationSpec in asynchLink element” on page 378“package in asynchLink element” on page 379“recordName in asynchLink element” on page 379

callLink element

The callLink element of a linkage options part specifies the type of linkage used ina call. Each element includes the following properties:v pgmName

v type

The pgmName property always relates to the program that is being called.However, the callLink element is used in the following situations:v When generating the calling program for either Java or COBOLv When generating the calling program for COBOL for the CICS environment

The value of the type property determines what additional properties are available,as shown in the next sections:v “If callLink type is localCall” on page 382v “If callLink type is remoteCall” on page 383v “If callLink type is ejbCall” on page 386

To determine the value of the type property that you need, see the table in″Choosing the correct callLink type″ later in this topic.

Some properties, such as pgmName and parmForm, affect the generation of bothJava and COBOL. Other properties, such as package, only affect the generation ofJava. In addition, some properties, such as alias, location, and package, only affectthe generation of the calling program. Other properties, such as linkType andparmForm, affect both the generation of the calling program and the generation ofthe called program, if it is generated as COBOL for the CICS environment.

If you do not specify a callLink element entry for a called program, EGL treats thecalled program as a localCall type and uses the default linkage options for thetarget runtime environment of the generated program.

Choosing the correct callLink typeThe following table shows which values for the type property of the callLinkelement are appropriate for the listed client/server combinations.


Table 33.

Client Server localCall? remoteCall/ejbCall protocol(s)

Java/Debug Java (on samemachine)

Yes (needed when the client is a Javawrapper) DIRECT, DISTINCT,TCPIP

Java (on differentmachine)

N/A TCPIP

iSeries Java N/A TCPIP

C++/DLL (32– or64–bit local DLL)

N/A DIRECT, DISTINCT

C++/DLL (32–bitremote DLL)

TCPIP

CICS N/A CICSECI, CICSJ2C, CICSSSL

IMS COBOL N/A IMSJ2C, IMSTCP

iSeries COBOL N/A JAVA400

iSeries RPG N/A JAVA400

COBOL generationfor IMS/VS, IMSBMP, z/OS Batch

PL/I type=STATIC

N/A

CICS CICS Yes Supported by CICS (ejbCall isN/A)

z/OS Batch N/A N/A

z/OS Batch CICS N/A N/ACICSEXCI (ejbCall is N/A)

z/OS Batch Yes* N/A

IMS BMP IMS BMP Yes* N/A

IMS/VS IMS/VS Yes* N/A

iSeries COBOL iSeries COBOL Yes N/A

iSeries RPG Yes N/A

iSeries RPG iSeries COBOL Yes N/A

iSeries RPG Yes N/A

* See Transfer of control across programs for more information about calling or transferringto another program.

Related concepts


“Editing the callLink element of a linkage options part” on page 387“Editing the fileLink element of a linkage options part” on page 407Related reference

“alias in callLink element” on page 389“conversionTable in callLink element” on page 389“ctgKeyStore in callLink element” on page 390“ctgKeyStorePassword in callLink element” on page 390“ctgLocation in callLink element” on page 391“ctgPort in callLink element” on page 391“library in callLink element” on page 391


“linkType in callLink element” on page 392“location in callLink element” on page 393“luwControl in callLink element” on page 395“package in callLink element” on page 396“parmForm in callLink element” on page 396“pgmName in callLink element” on page 398“providerURL in callLink element” on page 399“refreshScreen in callLink element” on page 400“remoteBind in callLink element” on page 400“remoteComType in callLink element” on page 401“remotePgmType in callLink element” on page 404“serverID in callLink element” on page 405“type in callLink element” on page 405

If callLink type is localCall

Set the type property to localCall when any of the following situations apply:v You are generating a Java program that calls a generated Java program that runs

in the same JVM as the calling program. In this case, EGL middleware is not inuse, and the following properties are meaningful for a callLink element inwhich pgmName identifies the called program:– alias

– package

– pgmName

– type

In the above case, if your called program is in the same package as the programcalling it, or if the name for the called program is identical to the part name forthat program, then you do not need to specify a callLink element for the calledprogram.

v You are generating a z/OS batch COBOL program that calls, or is called by,another COBOL program on the same system. In this case, the followingproperties are meaningful for a callLink element in which pgmName identifiesthe called program:– alias

– pgmName

– type

In the above case, you do not need to specify a callLink element for the calledprogram if the alias property has been set for the program, and you want thecall to be implemented as a dynamic COBOL call, as is appropriate for anotherCOBOL program.

Note: You must specify a callLink element for a local call for non-CICS z/OSenvironments if you need to call a PL/I program.

v You are generating a CICS COBOL program that calls, or is called by, anotherCOBOL program in the same CICS region (so long as the called program is notalso called from generated code that runs outside of the CICS region). In thiscase, the following properties are meaningful for a callLink element in whichpgmName identifies the called program:– alias


– linkType

– parmForm

– pgmName

– pgmType

– refreshScreen

– type

In the above case, you do not need to specify a callLink element for the calledprogram if the alias property has been set for the program, you want the call tobe implemented as an EXEC CICS LINK command, and the called programexpects pointers in the CICS COMMAREA.If the calling program and the called program are both generated CICS COBOLprograms, and the type property is set to localCall, the values for the linkTypeand parmForm properties must be the same when you generate both programs.The easiest way to accomplish this is to use the same linkage options part whenyou generate both the calling program and the called program. The value oftype cannot be localCall when you are generating a Java wrapper.Related concepts



“alias in callLink element” on page 389“callLink element” on page 380“conversionTable in callLink element” on page 389“ctgKeyStore in callLink element” on page 390“ctgKeyStorePassword in callLink element” on page 390“ctgLocation in callLink element” on page 391“ctgPort in callLink element” on page 391“library in callLink element” on page 391“linkType in callLink element” on page 392“location in callLink element” on page 393“luwControl in callLink element” on page 395“package in callLink element” on page 396“parmForm in callLink element” on page 396“pgmName in callLink element” on page 398“providerURL in callLink element” on page 399“refreshScreen in callLink element” on page 400“remoteBind in callLink element” on page 400“remoteComType in callLink element” on page 401“remotePgmType in callLink element” on page 404“serverID in callLink element” on page 405“type in callLink element” on page 405

If callLink type is remoteCall

Set the type property to remoteCall when any of the following situations apply:


v You are generating a Java program or Java wrapper, the call is not by way of agenerated EJB session bean, and the Java code calls a program that runs in adifferent JVM, or in the same JVM but in a different run unit, or the calledprogram is not EGL-generated Java. In this case, EGL middleware is in use, andthe following properties are meaningful for a callLink element in whichpgmName identifies the called program:– “alias in callLink element” on page 389– “conversionTable in callLink element” on page 389– “ctgKeyStore in callLink element” on page 390– “ctgKeyStorePassword in callLink element” on page 390– “ctgLocation in callLink element” on page 391– “ctgPort in callLink element” on page 391– “library in callLink element” on page 391– “location in callLink element” on page 393– “luwControl in callLink element” on page 395– “package in callLink element” on page 396 (used only if the generated code is

calling a Java program that is stored in another package)– “parmForm in callLink element” on page 396 (used only if the generated code

is calling a program that runs on CICS)– “pgmName in callLink element” on page 398– “remoteBind in callLink element” on page 400– “remoteComType in callLink element” on page 401– “remotePgmType in callLink element” on page 404– “serverID in callLink element” on page 405– “type in callLink element” on page 405

Depending on the communications protocol you specify for remoteComType,you must also specify additional properties.

v You are generating a Java program or wrapper that calls a C/C++ DLL. In thiscase, EGL middleware is in use and the following properties are meaningful fora callLink element in which pgmName identifies the C/C++ DLL:– “alias in callLink element” on page 389 (if the runtime function name is not

the same as the pgmName)– “library in callLink element” on page 391 (if the DLL name is not the same as

the pgmName)– “location in callLink element” on page 393 (if the DLL is on a different system

than the calling program, or if both programs are on iSeries)– “remoteComType in callLink element” on page 401 (set to DIRECT or

DISTINCT if the DLL is on the same system as the calling program, andTCPIP otherwise)

– “remotePgmType in callLink element” on page 404 (set toEXTERNALLYDEFINED)

– “serverID in callLink element” on page 405 (if the DLL is on a differentsystem than the calling program)

v You are generating a CICS COBOL program that calls a program in a differentCICS region (or in the same CICS region, if the called program is also called bygenerated code that runs outside of that region). In this case, EGL middleware isnot in use, and the following properties are meaningful for a callLink element inwhich pgmName identifies the called program:– “alias in callLink element” on page 389


– “conversionTable in callLink element” on page 389– “location in callLink element” on page 393– “parmForm in callLink element” on page 396– “pgmName in callLink element” on page 398– “refreshScreen in callLink element” on page 400– “remotePgmType in callLink element” on page 404– “serverID in callLink element” on page 405– “type in callLink element” on page 405

If the calling program and the called program are both generated CICS COBOLprograms, and the type property is set to remoteCall, the value for theparmForm property must be the same when you generate both programs. Theeasiest way to accomplish this is to use the same linkage options part when yougenerate both the calling program and the called program.

v You are generating a CICS COBOL program that is called by one or more of thefollowing entities:– A generated Java program– A Java wrapper that is generated to access the COBOL program (either

directly or by way of an EJB session bean)– A CICS COBOL program that resides in the same or a different regionIn this case, EGL middleware is in use (if the caller is a Java program orwrapper), and these statements apply:– The following properties are meaningful for a callLink element in which

pgmName identifies the generated, called COBOL program:- “parmForm in callLink element” on page 396- “pgmName in callLink element” on page 398- “refreshScreen in callLink element” on page 400 (if the caller is a CICS

COBOL program)- “type in callLink element” on page 405

– If the caller and called code are both generated CICS COBOL programs whentype is remoteCall, the callLink entry for the two programs must haveidentical values for parmForm.

Related concepts



“alias in callLink element” on page 389“callLink element” on page 380“conversionTable in callLink element” on page 389“ctgKeyStore in callLink element” on page 390“ctgKeyStorePassword in callLink element” on page 390“ctgLocation in callLink element” on page 391“ctgPort in callLink element” on page 391“library in callLink element” on page 391“linkType in callLink element” on page 392“location in callLink element” on page 393


“luwControl in callLink element” on page 395“package in callLink element” on page 396“parmForm in callLink element” on page 396“pgmName in callLink element” on page 398“providerURL in callLink element” on page 399“refreshScreen in callLink element” on page 400“remoteBind in callLink element” on page 400“remoteComType in callLink element” on page 401“remotePgmType in callLink element” on page 404“serverID in callLink element” on page 405“type in callLink element” on page 405

If callLink type is ejbCall

Set the type property to ejbCall when a callLink element is required to handleeither of the following situations:v You are generating a Java wrapper and intend to call the related, generated

program by way of a generated EJB session beanv You are generating a Java program and intend to call another generated program

by way of a generated EJB session bean

In this case, EGL middleware is in use, and the following properties aremeaningful for a callLink element in which pgmName identifies the calledprogram:v “alias in callLink element” on page 389v “conversionTable in callLink element” on page 389v “location in callLink element” on page 393v “package in callLink element” on page 396 (used only if the generated Java code

is calling a Java program that is stored in a package other than the package inwhich the EJB session bean resides)

v “parmForm in callLink element” on page 396 (used only if the generated Javacode is calling a program that runs on CICS)

v “pgmName in callLink element” on page 398v “providerURL in callLink element” on page 399v “remoteBind in callLink element” on page 400v “remoteComType in callLink element” on page 401v “remotePgmType in callLink element” on page 404v “serverID in callLink element” on page 405v “type in callLink element” on page 405

Related concepts



“alias in callLink element” on page 389“conversionTable in callLink element” on page 389


“ctgKeyStore in callLink element” on page 390“ctgKeyStorePassword in callLink element” on page 390“ctgLocation in callLink element” on page 391“ctgPort in callLink element” on page 391“library in callLink element” on page 391“linkType in callLink element” on page 392“location in callLink element” on page 393“luwControl in callLink element” on page 395“package in callLink element” on page 396“parmForm in callLink element” on page 396“pgmName in callLink element” on page 398“providerURL in callLink element” on page 399“refreshScreen in callLink element” on page 400“remoteBind in callLink element” on page 400“remoteComType in callLink element” on page 401“remotePgmType in callLink element” on page 404“serverID in callLink element” on page 405“type in callLink element” on page 405

Editing the callLink element of a linkage options part

The callLink element of a linkage options part specifies how a generated Java orCOBOL program calls another particular program, as occurs when the callingprogram uses the call statement. To edit the callLink element of a linkage optionspart:1. Locate the EGL build file you want to work with in the Project Explorer view.

To find it, open the EGL Source folder and look for a file with the extension.EGLBLD.

2. Right-click the build file and then click Open With → EGL Build Parts Editor.The Build Parts Editor opens the build descriptor part automatically; thedefault view is the General Options view.

3. If you have the Outline view open, you will see the build descriptor part listedunder the name of your build file. If you do not have the Outline view open,click Window → Show View → Other; in the Show View window, click toexpand General and select Outline.


5. Click the Show CallLink Elements button on the editor toolbar.6. To add a new callLink element, click Add or press the Insert key, and type the

program name or select a program name from the Program Name drop-downlist.

7. To change the default call type associated with your program name, performone of the following steps:v Select the corresponding row in the CallLink Elements list, and then click

the Type field once to make the field editable. Select the new call type fromthe Type drop-down list.

v In the Properties of selected callLink elements list, click the type propertyonce to make the Value field associated with that property editable. Selectthe new call type from the Value drop-down list.


8. Other properties associated with your program name are listed in theProperties of selected callLink elements list based on the call type. To changethe value of one of these properties, select the program name. In the Propertiesof selected callLink elements list, click the property you want to set once toput the Value field associated with that property into edit mode. Set the newvalue by selecting an option in the Value drop-down list, or by typing the newvalue in the Value field. For some properties, you can only select an option in adrop-down list. For other properties, you can only type a value in the Valuefield.

9. Modify the CallLink Elements list as needed:v To reposition a callLink element, select an element and click either Move Up

or Move Down.v To remove a callLink element, select the element and click Remove or press

the Delete key.Related topics


“Adding a linkage options part to an EGL build file” on page 63“Removing a linkage options part from an EGL build file” on page 64Related reference

“callLink element” on page 380“EGL build-file format” on page 30

csouidpwd.properties file for remote callsThe csouidpwd.properties file contains authentication details needed for a remotecall from a Java program or wrapper.

You must create and provide access to the csouidpwd.properties file when all ofthe following conditions are true:v The linkage options part, callLink element, property remoteComType is set to

JAVA400, CICSJ2C, or CICSECI.v A user ID and password are required.v One of these cases applies:

– The call is made from a Java program, but the code does not first invoke thesystem function sysLib.setRemoteUser() with values other than blanks.

– The call is made from a Java wrapper, but the Java code that includes thatwrapper has not invoked the CSOCallOptions methods setUserId() andsetPassword() with values other than blanks.

If the invocation of sysLib.setRemoteUser() (or the invocation of the appropriateCSOCallOptions method) results in a blank user ID or password, EGL looks for theinformation in csouidpwd.properties.

Your task is as follows:1. Create the csouidpwd.properties file, which can contain property settings that

are formatted as follows, each on a separate line:

CSOUID=useriduserid is the user ID for the remote call

CSOPWD=passwordpassword is the password for the remote call


2. Ensure that the file is a directory that is referenced by the classpath. Anappropriate directory is your project’s JavaSource folder.Related reference

“remoteComType in callLink element” on page 401“Java wrapper classes” on page 199

alias in callLink element

The alias property of the callLink element of the linkage options part specifies theruntime name of the program identified in the pgmName property. The aliasproperty affects the generation of the calling program.

In addition for a non-EGL called program whose name conflicts with the EGLreserved word list, you can use a fictitious (but legal) program name in the callstatement used in the program. In the callLink element, set the pgmNameproperty to the fictitious name, and set the alias property to specify the actualprogram name.

The value of this property must match the alias (if any) you specified whendeclaring the called program. If you did not specify an alias when declaring thecalled program either set the alias property to the name of the called program, ordo not set the property at all.

Related concepts


“Editing the callLink element of a linkage options part” on page 387Related reference

“callLink element” on page 380“pgmName in callLink element” on page 398

conversionTable in callLink element

The conversionTable property of the callLink element in a linkage options partspecifies the name of the conversion table that is used to convert data on a call to aprogram running on a remote server. Conversion is necessary when the code pageused for encoding text on the server is different from the encoding used on theclient. This is always the case when a Java client is calling a COBOL server, orwhen a COBOL client is calling a Java server. The conversion is performed on thecalling program. The callLink element is defined for the program being called; theconversion table specifies what conversion needs to be performed when the clientcalls that program.

Programs supporting bidirectional languages, such as Arabic and Hebrew, can usebidi conversion tables to specify reordering of text data in addition to code pageconversion. For more information, see Working with bidirectional data.

Select one of the following values:

conversion table nameThe caller uses the conversion table specified. For a list of tables, see the topic“Data conversion” on page 85.

* Uses the default conversion table. For a COBOL client, the name of that table isELAxxx, where the value of xxx is the value of the targetNLS build descriptor


option. For a Java client, the selected table is based on the locale of the clientsystem; or, if the client is running on a Web application server, it is based onthe locale of that server. If an unrecognized locale is found, English is thedefault.

PROGRAMCONTROLLEDThe calling program uses the conversion table name that is in thesysVar.callConversionTable system variable at run time. IfsysVar.callConversionTable contains blanks, no conversion occurs.

For information on system functions and system variables, see the EGL LanguageReference.

Related concepts

Working with bidirectional data“Data conversion” on page 85“Linkage options part” on page 61Related tasks


“callLink element” on page 380“pgmName in callLink element” on page 398“targetNLS” on page 365“type in callLink element” on page 405

ctgKeyStore in callLink element

The ctgKeyStore property of the callLink element of the linkage options part is thename of the key store generated with the Java tool keytool.exe or with the CICSTransaction Gateway tool IKEYMAN. The ctgKeyStore property is required whenthe value of the remoteComType property is set to CICSSSL.

Related concept


“callLink element” on page 380“ctgKeyStorePassword in callLink element”“remoteComType in callLink element” on page 401

ctgKeyStorePassword in callLink element

The ctgKeyStorePassword property of the callLink element of the linkage optionspart is the password used when generating the key store. This property is requiredwhen the value of the remoteComType property is set to CICSSSL. ThectgKeyStorePassword property affects the generation of the calling program.

This password is encrypted automatically when EGL generates the linkage. See″Encrypting your passwords″ in the EGL Programmer’s Guide.

Related concepts




“ctgKeyStore in callLink element” on page 390“remoteComType in callLink element” on page 401

ctgLocation in callLink element

The ctgLocation property of the callLink element of the linkage options part is theURL for accessing a CICS Transaction Gateway (CTG) server. It is used if the valueof the remoteComType property is CICSECI or CICSSSL. Specify the related portby setting the ctgPort property. The ctgLocation property affects the generation ofthe calling program.

Related concepts


“callLink element” on page 380“ctgPort in callLink element”“remoteComType in callLink element” on page 401

ctgPort in callLink element

The ctgPort property of the callLink element of the linkage options part is the portfor accessing a CICS Transaction Gateway (CTG) server. It is used if the value ofthe remoteComType property is CICSECI or CICSSSL. Specify the related URL bysetting the ctgLocation property. The ctgPort property affects the generation of thecalling program.

In the case of CICSSSL, the value of ctgPort is the TCP/IP port on which a CTGJSSE listener is listening for requests. If ctgPort is not specified, the CTG defaultport of 8050 is used.

Related topics


“callLink element” on page 380“ctgLocation in callLink element”“remoteComType in callLink element” on page 401

library in callLink element

The library property of the callLink element of the linkage options part specifiesthe DLL or library that contains the called program when the value of the typeproperty is ejbCall or remoteCall:v If your program is calling a remote COBOL program on iSeries, the library

property refers to the iSeries library that contains the program to be called.v If your EGL-generated Java program is calling a remote, non-EGL-generated

program on iSeries (for example, a C or C++ service program), the calledprogram belongs to an iSeries library and the library property refers to the nameof the program that contains the entry point to be called. Set the other callLinkelement properties as follows:– Set the pgmName property to the name of the entry point.– Set the remoteComType property to DIRECT or DISTINCT.– Set the remotePgmType property to EXTERNALLYDEFINED.


– Set the location property to the name of the iSeries library.v Otherwise, if the calling program is an EGL-generated Java program, the library

property refers to the name of a DLL that contains an entry point to be calledlocally as a native program. The entry point is identified by the pgmNameproperty; but you need to specify the library property only if the names of theentry point and DLL are different.Do not include a file name extension when you specify a value for the libraryproperty. For example, if the library name is libxyz.so, assign only libxyz to theproperty.

The library property affects the generation of the calling program. For informationon how to call a native DLL, see the topic ″If callLink type is remoteCall″ in thelist of related topics.

Related concepts


“callLink element” on page 380“If callLink type is remoteCall” on page 383“location in callLink element” on page 393“pgmName in callLink element” on page 398“remoteComType in callLink element” on page 401“remotePgmType in callLink element” on page 404“type in callLink element” on page 405

linkType in callLink element

The linkType property of the callLink element of the linkage options part specifiesthe type of linkage when the value of the type property is localCall. The linkTypeproperty affects the generation of the calling program. For COBOL in a CICSenvironment, the linkType property also affects the generation of the calledprogram.

Select a value from this list:

CICSLINKSpecifies that the call is from a CICS program to another program in the sameCICS region. An EXEC CICS LINK command is used, with no systemidentifier. CICSLINK is the default value for COBOL programs generated forCICS.

DYNAMICIf you are generating a COBOL program, specifies that the call is a dynamicCOBOL call. In CICS programs, a dynamic call is more efficient than an EXECCICS LINK but prevents you from using CICS CEDF to trace into the calledprogram. DYNAMIC is the default value for COBOL programs generated fornon-CICS environments.

STATICIf you are generating a COBOL program, specifies that a static COBOL calloccurs, which means that you must link edit the called program with thecalling program. For the z/OS Batch environment, STATIC is required if anEGL program calls or is called by a PL/I program.

Related concepts

“Linkage options part” on page 61


Related tasks


“callLink element” on page 380“pgmName in callLink element” on page 398“type in callLink element” on page 405

location in callLink element

The location property of the callLink element of the linkage options part specifieshow the location of a called program is determined at run time. The locationproperty affects the generation of the calling program. The location property isapplicable in the following situation:v The value of the type property is ejbCall or remoteCall;v The value of the remoteComType property is JAVA400, CICSECI, CICSSSL,

CICSJ2C, TCPIP, DIRECT, IMS2J2C, IMSTCP, or DISTINCT.v If you are generating a Java wrapper, pgmName refers to a program that is

called by way of the Java wrapper.


PROGRAMCONTROLLEDSpecifies that the location of the called program is obtained from thesysVar.remoteSystemID system function when the call occurs.

system nameSpecifies the location where the called program resides.

If you are generating a CICS COBOL program, the following rules apply forsystem name:v You can specify the name of the connection definition that has the following

characteristics:– Is installed in the CICS region where the calling program runs; and– Defines the connection with the CICS region where the called program

runs.v If you do not specify the value PROGRAMCONTROLLED or a connection

definition, the location of the called program is determined from the entryfor the called program in the CICS Processing Program Table (PPT) or RDOPROGRAM entry.

If you are generating a Java program or wrapper, the meaning of the locationproperty depends on the remoteComType property in the following ways:v If the value of the remoteComType property is JAVA400, location refers to

the iSeries system identifier.v If the value of the remoteComType property is CICSECI, CICSEXCI, or

CICSSSL, location refers to the CICS system identifier.v If the value of the remoteComType property is CICSJ2C, location refers to

the JNDI name of the ConnectionFactory object that you establish for theCICS transaction started by the call. You establish that ConnectionFactoryobject when setting up the J2EE server, as described in “Setting up the J2EEserver for CICSJ2C calls” on page 189. By convention, the name of theConnectionFactory object begins with eis/, as in the following example:eis/CICS1


v If the value of the remoteComType property is IMSJ2C, location refers tothe JNDI name of the ConnectionFactory object that you establish for theIMS transaction invoked by the call. You establish that ConnectionFactoryobject when setting up the J2EE server, as described in the topic ″Setting upthe J2EE server for IMSJ2C calls″ in the list of related topics below. Byconvention, the name of the ConnectionFactory object begins with eis/, as inthe following example:eis/IMS1

v If the value of the remoteComType property is IMSTCP, location has thefollowing value:host:portNumber/dataStoreName

hostTCP/IP host name or address that refers to the system where the calledprogram runs on IMS

portNumberNumber of the port used for TCP/IP connections by the target IMSConnect installation

dataStoreNameTarget IMS datastore name, which must match the ID parameter of theDatastore element that is specified in the IMS Connect configurationmember

v If the value of the remoteComType property is TCPIP, location refers to theTCP/IP host name or address.

v If the value of the remoteComType property is DEBUG, location refers tothe host name of the system where the Eclipse workbench is running.

v If the value of the remoteComType property is DISTINCT, location is usedonly in the iSeries environment, where it contains the name of the librarythat contains the DLL or program. The library property contains the name ofthe DLL or program.

v If all of the following conditions apply, then location refers to the library ofthe called program:– The calling program is an EGL-generated Java program that runs on

iSeries;– The value of the remoteComType property is DIRECT or DISTINCT; and– The value of remotePgmType is EXTERNALLYDEFINED;

Related concepts


“Editing the callLink element of a linkage options part” on page 387“Setting up the J2EE server for CICSJ2C calls” on page 189“Setting up the J2EE server for IMSJ2C calls” on page 190Related reference

“callLink element” on page 380“pgmName in callLink element” on page 398“remoteComType in callLink element” on page 401“remotePgmType in callLink element” on page 404“type in callLink element” on page 405


luwControl in callLink element

The luwControl property of the callLink element of the linkage options partspecifies whether the calling program or the called program controls the unit ofwork. The luwControl property affects the generation of the calling program. Thisproperty is applicable only in the following situation:v The value of the type property is remoteCall.


CLIENTSpecifies that the unit of work is under the caller’s control. Updates by thecalled program are not committed or rolled back until the caller requestscommit or rollback. If the called program issues a commit or rollback, aruntime error occurs.

CLIENT is the default value, unless a caller-controlled unit of work is notsupported on the platform where the called program resides.

CLIENT is available in these cases:v The called program is on CICS; orv The caller is a Java program or wrapper that communicates with an

iSeries-based COBOL program by way of the IBM Toolbox for Java. In thiscase, the value of remoteComType for the call is JAVA400.

SERVERSpecifies that a unit of work started by the called program is independent ofany unit of work controlled by the calling program. In the called program,these rules apply:v The first change to a recoverable resource begins a unit of work.v Use of the sysLib.commit and sysLib.rollback system functions are valid.

On a call from EGL-generated Java code to a VisualAge Generator COBOLprogram or an EGL-generated COBOL program, a commit (or rollback onabnormal termination) is issued automatically when the called programreturns. That command affects only the changes that were made by the calledprogram.

When the type property is ejbCall, the runtime behavior is as described forSERVER.

For information about system functions, see the EGL Language Reference.Related concepts



“callLink element” on page 380“pgmName in callLink element” on page 398“remoteComType in callLink element” on page 401“type in callLink element” on page 405


package in callLink element

The package property of the callLink element of the linkage options part identifiesthe Java package in which a called Java program resides. The property is usefulwhether the type property is set to localCall or remoteCall. The package propertyaffects the generation of the calling program. If you are generating a Java wrapper,package is meaningful when the pgmName property refers to the program calledby way of the Java wrapper.

If the package property is not specified, the called program is assumed to be in thesame package as the calling program.

The package name that is used in generated Java programs matches the packagename of the EGL program, but is in lower case; and when EGL generates outputfrom the callLink element, the value of the package property is changed (ifnecessary) to lower case.

Related concepts


“Editing the callLink element of a linkage options part” on page 387“Setting up the JEE runtime environment for EGL-generated code” on page 186Related reference


parmForm in callLink element

The parmForm property of the callLink element of the linkage options partspecifies the format of call parameters. The parmForm property affects thegeneration of the calling program. For COBOL programs in a CICS environment,this property also affects the generation of the called program.

If you are generating a COBOL program, parmForm is applicable when both thefollowing conditions are true:v The pgmName property refers to the generated program or to a CICS-based

program called by the generated program.v The type property is localCall or remoteCall:

– If the type is localCall, the valid parmForm values (as described later) areCICSOSLINK, COMMDATA, COMMPTR (the default), and OSLINK (thedefault for z/OS batch)

– If the type is remoteCall, the valid parmForm values are CICSOSLINK,COMMDATA (the default), (if you are referring to a COBOL program calledfrom Java code) COMMPTR, and OSLINK.

If you are generating a Java program, parmForm is applicable in this situation:v The pgmName property refers to a CICS-based program that is called by the

program being generated; andv The type property is ejbCall or remoteCall; in either case, the valid parmForm

values (as described later) are COMMDATA (the default) and COMMPTR.


If you are generating a Java wrapper, parmForm is applicable in the followingcase:v The pgmName property refers to a generated COBOL program that is called by

way of the Java wrapper; andv The type property is ejbcall or remoteCall; in either of those cases the valid

parmForm values (as described later) are COMMDATA (the default) orCOMMPTR.


CICSOSLINKSpecifies that the standard COBOL parameter-passing conventions are in effect,with the called program expecting pointers to data. The CICS EIB andCOMMAREA are always passed as the first two arguments, which arefollowed by the program-specific arguments.

Use of CICSOSLINK requires the following settings:v The type property is localCall or remoteCall

v The linkType property is STATIC or DYNAMIC

COMMDATASpecifies that the caller places business data (rather than pointers to data) inthe COMMAREA.

Each argument value is moved to the buffer adjoining the previous valuewithout regard for boundary alignment.

COMMDATA is the default value if the type property is remoteCall or ejbCall.

COMMPTRSpecifies that the caller acts as follows:v Places a series of 4-byte pointers in the COMMAREA, one pointer per

argument passedv Sets the high-order bit of the last pointer to 1

COMMPTR is the default value if the value of the type property is localCall.

OSLINKSpecifies that the standard COBOL parameter-passing conventions are in effect,with the called program expecting pointers to data, but without the CICS EIBor COMMAREA.

OSLINK is valid only when you are generating a COBOL program. Use ofOSLINK requires the following settings:v The type property is localCall or remoteCall

v The linkType property is STATIC or DYNAMICRelated concepts



“callLink element” on page 380“linkType in callLink element” on page 392“pgmName in callLink element” on page 398“type in callLink element” on page 405


pgmName in callLink element

The pgmName property of the callLink element of the linkage options partspecifies one of the following:v The name of a program part, or non-EGL program, that is being called;v The value of the linkageKey property that was specified for a call statement.

Using a linkageKey enables you to create a single callLink entry for multipleprograms that have the same characteristics for the call statement.

The pgmName property is used when generating the calling program, to identifywhich call statements have special linkage.

You can use an asterisk (*) as a global substitution character in the program name;however, that character is valid only as the last character. For details, see “Linkageoptions part” on page 61.

Related concepts




pgmType in callLink element

The pgmType property of the callLink element of the linkage options partspecifies the kind of program being called when the type property is localCall. ThepgmType property affects the generation of the calling program.


EGL (the default value)The called program is a COBOL or Java program that was generated by EGLor VisualAge Generator.

EXTERNALLYDEFINEDThe called program was not generated by EGL or VisualAge Generator. Thisoption is used only in the following cases:v The calling program is generated for COBOL, the called program runs on

CICS, and the linkType property is set to DYNAMIC.v The calling program is a Java program and the called program is a non-EGL

DLL or a C or C++ program.

If the calling program is calling a DLL, set the pgmName property to the name ofthe entry point being called within the DLL. If the name of the entry point differsfrom the name of the DLL, set the library property to the name of the DLL.

Related concepts



“callLink element” on page 380“library in callLink element” on page 391


“linkType in callLink element” on page 392“pgmName in callLink element” on page 398“type in callLink element” on page 405

providerURL in callLink element

The providerURL property of the callLink element of the linkage options partspecifies the host name and port number of the name server used by anEGL-generated Java program to locate an EJB session bean that in turn calls anEGL-generated Java program or wrapper. The property must have the followingformat:

iiop://hostName:portNumber

hostNameThe IP address or host name of the system on which the name server runs

portNumberThe port number on which the name server listens

The providerURL property is applicable only in the following situation:v The value of the type property is ejbCall; andv The pgmName property refers to the program being called from the Java

program or wrapper being generated.

Enclose the URL in double quote marks to avoid a problem either with periods orwith the colon that precedes the port number.

A default is used if you do not specify a value for providerURL. The defaultdirects an EJB client to look for the name server that is on the local host and thatlistens on port 900. The default is equivalent to the following URL:

"iiop:///"

The following providerURL value directs an EJB client to look for a remote nameserver that is called bankserver.mybank.com and that listens on port 9019:

"iiop://bankserver.mybank.com:9019"

The following property value directs an EJB client to look for a remote name serverthat is called bankserver.mybank.com and that listens on port 900:

"iiop://bankserver.mybank.com"

Related concepts


“Editing the callLink element of a linkage options part” on page 387“Setting up the JEE runtime environment for EGL-generated code” on page 186Related reference



refreshScreen in callLink element

The refreshScreen property of the callLink element of the linkage options partindicates whether an automatic screen refresh occurs when the called programreturns control. Valid values are YES (the default) and NO.

Set refreshScreen to no if the caller is in a run unit that presents text forms to ascreen and either of these situations applies:v The called program does not present a text form; orv The caller writes a full-screen text form after the call.

The property refreshScreen applies only in these cases:v The type property is localCall; orv The type property is remoteCall when the remoteComType property is direct or

distinct.

The property is ignored if you include the noRefresh indicator on the callstatement. You can find more information in the topic ″call″ in the EGL LanguageReference.

Related reference

“callLink element” on page 380“remoteComType in callLink element” on page 401

remoteBind in callLink element

The remoteBind property of the callLink element of the linkage options partspecifies whether linkage options are determined at generation time or at run time.This property is applicable only in the following situation:v The value of the type property is remoteCall or ejbCall; andv You are generating a Java program or wrapper. The pgmName property may

refer to a program called by the generated program, in which case theremoteBind property refers to the call from program to program. Alternatively,the property may refer to the program being generated, in which case the entryrefers to the call from wrapper to program.

The remoteBind property affects the generation of the calling program.


GENERATIONThe linkage options specified at generation time are necessarily in use at runtime. GENERATION is the default value.

RUNTIMEThe linkage options specified at generation time can be revised at deploymenttime. In this case, you must include a linkage properties file in the runtimeenvironment.

EGL generates a linkage properties file in the following situation:v You are generating a Java program or wrapper;v You set the remoteBind property to RUNTIME; andv You generate with the genProperties build descriptor option set to GLOBAL

or PROGRAM.Related concepts


“Linkage options part” on page 61“Linkage properties file” on page 182Related tasks


“callLink element” on page 380“genProperties” on page 326“pgmName in callLink element” on page 398“type in callLink element” on page 405

remoteComType in callLink element

The remoteComType property of the callLink element of the linkage options partspecifies the communication protocol used in the following case:v The value of the type property is remoteCall or ejbCall; andv You are generating a Java program or wrapper:

– If you are generating a Java program, the pgmName property refers to aprogram that is called by the program being generated.

– If you are generating a Java wrapper, pgmName refers to a program that iscalled by way of the Java wrapper.

The remoteComType property affects generation of the calling program.

Select one of the following values.

DEBUGCauses the called program to run in the EGL debugger, even when the callingprogram is running in a Java runtime or EGL debug environment. You mightuse this setting in the following case:v You are running a Java program that uses an EGL Java wrapper to call a

program written with EGL; orv You are running a generated program written in EGL, that calls a program

also written with EGL.

The preceding situation can occur outside the WebSphere Application Server,but can also occur within that environment, as when a JSP invokes a programwritten with EGL. In any case, the effect is to debug the EGL source, not agenerated program.

If you are using the WebSphere Application Server, the caller and calledprograms must both be running there; the call cannot be from a remote system.

When you use DEBUG, you set the following properties in the same callLinkelement:v library, which names the project that contains the called programv package, which identifies the package that contains the called program; but

you do not need to set this property if the caller and called programs are inthe same package

If the caller is not running in the EGL debugger and is not running in theWebSphere Application Server, you must set these properties of the callLinkelement:v serverId, which should specify the listener’s port number if it is not 8346;

and


v location, which must contain the host name of the system where the Eclipseworkbench is running.

DIRECTSpecifies that the called program runs in the same run unit as the callingprogram or wrapper. Otherwise this is the same as DISTINCT.

If the generated Java code is calling a non-EGL dynamic link library (DLL) or aC or C++ program, it is recommended that you use the remoteComType valueDISTINCT.

DISTINCTSpecifies that a new run unit is started when calling a program locally. The callis still considered to be remote because EGL middleware is involved.

You can use this value for an EGL Java program that calls a dynamic linklibrary (DLL) or a C or C++ program. If you set the remoteComType propertyto this value, the following properties should have the values shown:

libraryThe name of the DLL or program.

locationThe name of the library that contains the DLL or program (iSeriesonly).

CICSECISpecifies use of the CICS Transaction Gateway (CTG) ECI interface, as isneeded when you are debugging or running non-J2EE code that accesses CICS.

CTG Java classes are used to implement this protocol. To specify the URL andport for a CTG server, assign values to the ctgLocation and ctgPort propertiesof the callLink element. If you set the remoteComType property to this value,the location property should be set to system name, and the value is CICSsystem identifier.

If a password is required, you might need to set up the csouidpwd.propertiesfile. See “csouidpwd.properties file for remote calls” on page 388.

CICSEXCISpecifies use of the EXCI interface to call a program in a CICS region from theZOSBATCH system. The type must be remoteCall; use COMMDATA to passparameters.

CICSJ2CSpecifies use of a J2C connector for the CICS Transaction Gateway. If you setthe remoteComType property to this value, the location property should be setto system name, and the value is the JNDI name of the ConnectionFactory objectthat you establish for the CICS transaction started by the call.


CICSSSLSpecifies use of the Secure Socket Layer (SSL) features of CICS TransactionGateway (CTG). The JSSE implementation of SSL is supported.

CTG Java classes are used to implement this protocol. To specify additionalinformation for a CTG server, assign values to the following callLink elementproperties:v ctgKeyStore

v ctgKeyStorePassword


v ctgLocation

v ctgPort, which in this case is the TCP/IP port on which a CTG JSSE listeneris listening for requests. If ctgPort is not specified, the CTG default port of8050 is used.

If you set the remoteComType property to this value, the location propertyshould be set to system name, and the value is CICS system identifier.

JAVA400Specifies use of the IBM Toolbox for Java to communicate between a Javaprogram or wrapper and a COBOL program that was generated (by EGL orVisualAge Generator) for iSeries. If you set the remoteComType property tothis value, the location property should be set to system name, and the value isthe iSeries system identifier.


TCPIPSpecifies that the EGL middleware uses TCP/IP. If you set theremoteComType property to this value, the location property should be set tosystem name, and the value is the TCP/IP host name or address.

IMSJ2CIn a J2EE environment, specifies use of an IMS J2C connector.

IMSTCPSpecifies use of the TCP/IP connector from IMS Connect. Select this option ifyou are running non-J2EE code that accesses IMS.

Note: IMS Connect must be installed on the host system where the IMSprogram resides. On the client system, the following set of IMSConnector for Java jar files must be in the class path when the callingprogram is started:v ccf2.jarv connector.jarv imsico.jar

Related concepts


“Editing the callLink element of a linkage options part” on page 387“Setting up the J2EE server for CICSJ2C calls” on page 189“Setting up the TCP/IP listener for a called non-J2EE application” on page 198“Setting up a TCP/IP listener for J2EE called applications” on page 193Related reference

“callLink element” on page 380“csouidpwd.properties file for remote calls” on page 388The csouidpwd.properties file contains authentication details needed for aremote call from a Java program or wrapper.“ctgKeyStore in callLink element” on page 390“ctgKeyStorePassword in callLink element” on page 390“ctgLocation in callLink element” on page 391“ctgPort in callLink element” on page 391“library in callLink element” on page 391


“location in callLink element” on page 393“package in callLink element” on page 396“serverID in callLink element” on page 405

remotePgmType in callLink element

The remotePgmType property of the callLink element of the linkage options partspecifies the kind of program being called. The remotePgmType property affectsthe generation of the calling program. The property is applicable in the followingsituation:v The value of the type property is ejbcall or remoteCall; andv The called program is one of the following kinds:

– An EGL-generated Java program– A non-EGL dynamic link library (DLL) or C or C++ program– A program that runs on CICS and has CICS commands– A program that runs on IMS– A program on System i®


EGLThe called program is a COBOL or Java program, or Java wrapper,that wasgenerated by EGL or by VisualAge Generator. This value is the default.

EXTERNALLYDEFINEDThe called program was generated neither by EGL nor by VisualAgeGenerator. This option is available only in the following cases:v The caller is a COBOL or Java program, and the called program runs on

CICS and includes CICS commands.v The caller is a Java program, and the called program is a non-EGL generated

program on the System i.v The caller is a Java program, and the called program is a non-EGL-generated

DLL or a C or C++ program.If the caller is calling a DLL, set the library property to the name of theshared library if the program is not the same as the name of the functionbeing called within the DLL.

STATEFULSystem i only. Used on Web projects for pages to access stateful host programson the System i, such as RPG programs. This option bypasses the host catcherprogram. It creates and stores a connection based on the Web session;subsequent System i calls will reuse the same connection.

The following considerations apply:v Bypassing the host catcher program means that EGL does not initiate

commit or rollback operations for the host program. The user code isresponsible for commit and rollback.

v The option is allowed only when the remoteComType property is set toJAVA400 and the target is a Web project.

STATELESSSystem i only. Used to directly call a host program, bypassing the catcher. Thisoption uses connection pooling, so subsequent calls are not guaranteed to usethe same connection. The following considerations apply:


v Bypassing the host catcher program means that EGL does not initiatecommit or rollback operations for the host program. The user code isresponsible for commit and rollback.

v The option is allowed only when the remoteComType property is set toJAVA400.

Related concepts



“callLink element” on page 380“library in callLink element” on page 391“pgmName in callLink element” on page 398“type in callLink element”

serverID in callLink element

The serverID property of the callLink element of the linkage options part specifiesone of the following values:v The TCP/IP port number of a called program’s listener; but only if the TCP/IP

protocol is in use. In this case, no default exists.v The ID of a CICS transaction being called. In this case, the default is the CICS

server system mirror transaction (CPMI for all remoteComType values exceptCICSEXCI; for CICSEXCI the default is CSMI).

v The ID of an IMS transaction being invoked, but only when the value of theremoteComType property is IMSTCP.

The property is used only in the following situation:v The value of the type property is ejbCall or remoteCall

v The value of remoteComType is TCPIP, CICSECI, CICSEXCI, IMSTCP, CICSJ2C,or CICSSSLRelated concepts


“Editing the callLink element of a linkage options part” on page 387“Setting up the TCP/IP listener for a called non-J2EE application” on page 198“Setting up a TCP/IP listener for J2EE called applications” on page 193Related reference

“callLink element” on page 380“pgmName in callLink element” on page 398“remoteComType in callLink element” on page 401“type in callLink element”

type in callLink element

The type property of the callLink element of the linkage options part specifies thekind of call. Select one of the following values:


ejbCallIndicates that the generated Java program or wrapper will implement theprogram call by using an EJB session bean and that the EJB session bean willaccess the COBOL or Java program identified in the pgmName property. Thevalue ejbCall is applicable in either of two cases:v You are generating a Java wrapper for a COBOL or Java program, and the

wrapper calls that program by way of an EJB session bean. In this case, thepgmName property refers to the program called from the wrapper, and youruse of ejbCall causes generation of the EJB session bean.

v You are generating a Java program that calls a generated COBOL or Javaprogram by way of an EJB session bean. In this case, the pgmName propertyrefers to the called program, and an EJB session bean is not generated.

In either case, if you are using an EJB session bean, you must generate a Javawrapper, if only to generate the EJB session bean.

The generated session bean must be deployed on an enterprise Java server, andone of the following statements must be true:v The name server used to locate the EJB session bean resides on the same

system as the code calling that session bean; orv The providerURL property identifies where the name server resides.

If you wish to use an EJB session bean, you must generate the calling programor wrapper with a linkage options part in which the value of the type propertyfor the called program is ejbCall. You cannot make the decision to use asession bean at deployment time. If you set the remoteBind property toRUNTIME, however, you can decide at deployment time how the EJB sessionbean accesses the generated program, although making this decision atgeneration time is more efficient.

localCallSpecifies that the call does not use EGL middleware. The called program in thiscase is in the same process as the caller.

If the caller is a COBOL program, the situation is further defined by otherproperties. Most important are linkType and (for CICS COBOL programs)parmForm. Those properties have default values that you can accept oroverride.

localCall is the default value and is the only valid value for a z/OS batchCOBOL program.

remoteCallSpecifies that the call uses EGL middleware.

If the caller is a CICS COBOL program, the implications of using remoteCallare as follows:v The called program is in the same or a different CICS region and uses an

EXEC CICS LINK command with a system identifier. The source of thesystem identifier is determined by the value of the location property.

v The only valid format for the parmForm property is COMMDATA.

If the caller is Java code, communication is handled by the protocol specifiedin the remoteComType property.

If a fixed record with one or both of the properties lengthItem andnumElementsItem is passed on a call, these statements apply:v Space is reserved for the maximum length specified for the record


v If the value of the callLink property type is remoteCall or ejbCall, the fieldspecified by the lengthItem (if any) must be inside the recordRelated concepts



“callLink element” on page 380“linkType in callLink element” on page 392“location in callLink element” on page 393“parmForm in callLink element” on page 396“pgmName in callLink element” on page 398“providerURL in callLink element” on page 399“remoteComType in callLink element” on page 401

fileLink element

The fileLink element of a linkage options part specifies how CICS accesses aparticular file. Each element includes these properties:v “fileName in fileLink element” on page 409v “type in fileLink element” on page 410

If the value of the type property is remoteFile, the file might reside on a CICSregion different from the region where the program resides. In this case, EGL alsoconsiders the value of the following fileLink properties:v “conversionTable in fileLink element” on page 408v “locationSpec in fileLink element” on page 409

Related concepts


“Editing the fileLink element of a linkage options part”Related reference

“conversionTable in fileLink element” on page 408“fileName in fileLink element” on page 409“locationSpec in fileLink element” on page 409“type in fileLink element” on page 410

Editing the fileLink element of a linkage options part

The fileLink element of a linkage options part specifies how CICS accesses aparticular file. To edit the fileLink element of a linkage options part, follow thesesteps:1. Locate the EGL build file you want to work with in the Project Explorer view.






5. Click the Show FileLink Elements button on the editor toolbar.6. To add a new fileLink element, click Add or press the Insert key, and type the

file name, or select a file name from the File Name drop-down list.7. To change the default file access type associated with your file name, you can

either:v Select the corresponding row in the FileLink Elements list, then click the

Type field once to put the field into edit mode. Select the new linkage typefrom the Type drop-down list.

v In the Properties of selected fileLink elements list, click the type propertyonce to put the Value field associated with that property into edit mode.Select the new linkage type from the Value drop-down list.

8. Other properties associated with your file name are listed in the Properties ofselected fileLink elements list based on the linkage type. To change the valueof one of these properties, select the file name. In the Properties of selectedfileLink elements list, click the property you want to set once to put the Valuefield associated with that property into edit mode. Set the new value byselecting an option in the Value drop-down list, or by typing the new value inthe Value field. For some properties, you can only select an option in adrop-down list. For other properties, you can only type a value in the Valuefield.

9. Modify the FileLink Elements list as needed:v To reposition a fileLink element, select an element and click either Move Up

or Move Down.v To remove a fileLink element, select an element and click Remove or press

the Delete key.Related concepts


“Adding a linkage options part to an EGL build file” on page 63“Removing a linkage options part from an EGL build file” on page 64Related reference

“EGL build-file format” on page 30“fileLink element” on page 407

conversionTable in fileLink element

TheconversionTable property of the fileLink element of the linkage options partspecifies the name of the conversion table used to perform automatic dataconversion during access of remote files. If you do not specify this property, theprogram does not perform data conversion automatically but must perform anyrequired conversion in either of these ways:v By making explicit calls to the sysLib.convert system functionv By defining a conversion template to CICS

You can specify one of the following values:


conversion table nameConversion on the client uses the conversion table specified.

* Uses the default conversion table. The name of that table is ELANCxxx, wherethe value of xxx is the value of the targetNLS build descriptor option.

For a list of tables, see the topic ″Data conversion″.

PROGRAMCONTROLLEDConversion on the client uses the conversion table name in thesysVar.callConversionTable system variable at run time. IfsysVar.callConversionTable contains blanks, no conversion occurs.

For more information on system functions and variables, see the EGL LanguageReference.

Related concepts

“Data conversion” on page 85“Linkage options part” on page 61Related tasks

“Editing the fileLink element of a linkage options part” on page 407Related reference

“fileLink element” on page 407“targetNLS” on page 365

fileName in fileLink element

ThefileName property of the fileLink element of the linkage options part specifiesthe name of the file as identified by the fileName property of a serial, indexed, orrelative record that is used in the generated program.

You can use an asterisk (*) as a global substitution character in the name; however,that character is valid only as the last character. For details, see the topic ″Linkageoptions part″.

Related concepts



“fileLink element” on page 407

locationSpec in fileLink element

ThelocationSpec property of the fileLink element of the linkage options partspecifies how the CICS system identifier of a remote file is defined. The followingvalues can be specified:

CICSSpecifies that the location for a remote file is defined in the CICS file controltable (FCT) or destination control table (DCT).

PROGRAMCONTROLLEDSpecifies that the location for the remote file is obtained from the


sysVar.remoteSystemID system variable when an I/O operation is performedon the file. The location is passed to CICS by way of the SYSID keyword onthe EXEC CICS command.

You can find more information on system variables by referring to the EGLLanguage Reference.

Related concepts




type in fileLink element

Thetype property of the fileLink element of the linkage options part specifies thetype of file access being generated. Select from this list:

localFileSpecifies that the file resides on the same CICS region as the program. Thisvalue is the default.

remoteFileSpecifies that the file might reside on a CICS region different from the regionwhere the program resides. This value is valid only for CICS-managed VSAMfiles and transient data queues.

Related concepts




transferToProgram element

A transferToProgram element of a linkage options part specifies how a generatedJava or COBOL program transfers control to a particular program and endsprocessing, as occurs when the originating program uses the transfer to programstatement.

The element includes these properties:v fromPgm

v toPgm

v linkType

v alias (as is necessary if your code is transferring to a program whose runtimename is different from the name of the related program part)

v packageName (this is the name of the package location of the program receivingthe transfer of control)

If you are generating COBOL code, you can avoid specifying a transferToProgramelement when the target program is generated with VisualAge Generator or (in theabsence of an alias) with EGL. The default behavior is as follows:


v If the program runs on CICS for z/OS, the transfer is implemented with a CICSXCTL command.

v If the program runs on z/OS but not in CICS, EGL simulates the behavior onCICS so that the transferring program ends but the run unit continues, with nocommits or releases of locks. The transfer in this case is implemented with adynamic COBOL call, which is more efficient than XCTL but uses more memory.For z/OS batch, you can specify that you want to use an XCTL command forthe transfer by setting the useXCTLForTransfer build descriptor option to YES.

A special concern arises when you are developing COBOL code that runs outsideof CICS. The runtime simulation of CICS behavior means that you must specifythe initial program in the run unit as the one from which any transfer occurs.

Consider the case of Program01 transferring to Program02, which in turn transfersto Program03, assuming that each transfer is of type transfer to program. Whenyou are generating Program01 (unless you accept the default behavior), yourlinkage options part must include a pair of transferToProgram elements to indicatethat the following transfers occur:v From Program01 to Program02v From Program01 to Program03

In the previous situation, if Program02 can also be used as the first program inanother run unit, your linkage options part must include a differenttransferToProgram element when you are generating Program02. The purpose inthat case is straightforward, to transfer control from Program02 to Program03.

If Program02 is an EGL program and Program03 is not, the default settings areinappropriate, and you must specify the transferToProgram element that isinvolved in transferring control from Program01 to Program03.

Related concepts


“Adding a linkage options part to an EGL build file” on page 63“Editing the transferToProgram element of a linkage options part”Related reference

“alias in transferToProgram element” on page 413“fromPgm in transferToProgram element” on page 413“linkType in transferToProgram element” on page 414“packageName in transferToProgram element” on page 415“toPgm in transferToProgram element” on page 415“useXctlForTransfer” on page 370

Editing the transferToProgram element of a linkage optionspart

A transferToProgram element of a linkage options part specifies how a generatedJava or COBOL program transfers control to a particular program and endsprocessing, as occurs when the originating program uses the transfer to programstatement. To edit the transferToProgram element, follow these steps:1. Locate the EGL build file you want to work with in the Project Explorer view.





4. In the Outline view, right click a linkage options part and click Open. The EGLBuild Parts Editor displays the current part declaration.

5. Click the Show TransferLink Elements button on the editor toolbar. TheTransfer to Program and Transfer to Transaction lists display.

6. To edit the Transfer to Program list, follow these steps:a. At the bottom of the Transfer to Program list, click Add or press the Insert

key, and type a value in the From Program (fromPgm) field, or select aprogram name from the From Program name drop-down list.

b. To edit the To Program (toPgm) field, select the row in the Transfer toProgram list that you want to edit, then click the To Program field once toput the field into edit mode. Type the program name or select a programname from the To Program drop-down list.

c. If an alias name is needed, select the row in the Transfer to Program listthat you want to edit, then click the Alias field once to put the field intoedit mode. Type the alias name.

d. To change the default linkage type associated with your program name,select the row in the Transfer to Program list that you want to edit, thenclick the Link Type field once to put the field into edit mode. Select thenew linkage type from the Link Type drop-down list.

e. If a package name is needed, as might be the case for Java if the FromProgram (fromPgm) is not in your workspace or is in a different packagethan the To Program (toPgm), select the row in the Transfer to Program listthat you want to edit, then click the Package Name field once to put thefield into edit mode. Type the package name in the field.

f. Modify the Transfer to Program list as needed:v To reposition a transferToProgram element, select an element and click

either Move Up or Move Down.v To remove a transferToProgram element, select an element and click

Remove or press the Delete key.Related concepts


“Adding a linkage options part to an EGL build file” on page 63“Editing the asynchLink element of a linkage options part” on page 376“Editing the callLink element of a linkage options part” on page 387“Editing the fileLink element of a linkage options part” on page 407“Editing the transferToTransaction element of a linkage options part” on page416“Removing a linkage options part from an EGL build file” on page 64Related reference

“EGL build-file format” on page 30“transferToProgram element” on page 410“transferToTransaction element” on page 416


alias in transferToProgram element

In the transferToProgram element of the linkage options part, the alias propertyspecifies the runtime name of the program that is identified in the toPgm property.

The value of this property must match the alias (if any) you specified whendeclaring the program to which you are transferring. If you did not specify an aliaswhen declaring that program, either set the alias property to the name of theprogram part or do not set the property at all.

If the name of a called non-EGL program is an EGL reserved word, you mustspecify the name of the program in the transfer to program statement using aword that is not a reserved word and use the alias attribute to specify the actualname of the called program.

Related topics


“Adding a linkage options part to an EGL build file” on page 63“Editing the transferToProgram element of a linkage options part” on page 411Related reference

“toPgm in transferToProgram element” on page 415“fromPgm in transferToProgram element”“linkType in transferToProgram element” on page 414“packageName in transferToProgram element” on page 415“transferToProgram element” on page 410

fromPgm in transferToProgram element

The fromPgm property of the transferToProgram element of the linkage optionspart specifies the name of a program part:v If the target system is Java on CICS, the program part is the one that issues the

transfer statement.v If the target system is z/OS but not CICS and if any of the programs in the run

unit issue a transfer statement, the fromPgm property must be set to the nameof the first program in the run unit. For an example, see “transferToProgramelement” on page 410.

The value of the fromPgm property is required and cannot include an asterisk (*).

You can find more information on run units and the transfer statement in the EGLLanguage Reference.

Related topics



“alias in transferToProgram element”“linkType in transferToProgram element” on page 414“packageName in transferToProgram element” on page 415


“toPgm in transferToProgram element” on page 415“transferToProgram element” on page 410

linkType in transferToProgram element

The linkType property of the transferToProgram element of the linkage optionspart specifies the type of linkage to generate in relation to a transfer to programstatement. This property is only used with COBOL generation. Valid values are asfollows:

DYNAMIC (the default)In programs that run on CICS for z/OS, a CICS implements the transferstatement.

In programs that run on z/OS outside of CICS, the following statements apply:v a dynamic COBOL call is generated in the first program in the run unit;v the EGL run time handles processing so that the transfer simulates the

behavior of a CICS-based program.

The target program is assumed to be produced by EGL or by VisualAgeGenerator.

STATICIn programs that run on CICS for z/OS, a CICS implements the transferstatement.

In programs that run on z/OS outside of CICS, the following statements apply:v A static COBOL call is generatedv The EGL runtime handles processing so that the transfer simulates the

behavior of a CICS-based program

The value STATIC is required for target programs that call PL/I programs orthat call programs that call PL/I programs. The target program is assumed tobe produced by EGL or by VisualAge Generator.

EXTERNALLYDEFINEDSpecify the value EXTERNALLYDEFINED if you are transferring to a programthat was not produced by EGL or VisualAge Generator. In all COBOL targetsystems, an XCTL implements the transfer statement.

Alternatively, you can specify isExternal = YES on the transfer to programstatement.

You can find more information on transfer statements in the EGL LanguageReference.

Related concepts



“alias in transferToProgram element” on page 413“fromPgm in transferToProgram element” on page 413“linkType in transferToProgram element”“packageName in transferToProgram element” on page 415“toPgm in transferToProgram element” on page 415


“transferToProgram element” on page 410

packageName in transferToProgram element

The packageName property of the transferToProgram element of the linkageoptions part identifies the Java package location for a program that is transferredto Java.

If the packageName property is not specified, the transferred-to program isassumed to be in the same package as the originating program.

The package name that is used in generated Java programs is the package name ofthe EGL program, but in lower case; and when EGL generates output from thetransferToProgram element, the value of packageName is changed (if necessary) tolower case.

Related concepts



“alias in transferToProgram element” on page 413“fromPgm in transferToProgram element” on page 413“linkType in transferToProgram element” on page 414“toPgm in transferToProgram element”“transferToProgram element” on page 410

toPgm in transferToProgram element

The toPgm property of the transferToProgram element of the linkage options partis a required property that specifies one of the following:v The name of the program part (or the non-EGL program) that receives control.v The value of a linkageKey property that was specified for a transfer to program

statement. Using a linkageKey enables you to create a single transfer toprogram entry for multiple programs that have the same characteristics for thetransfer to program statement.

If the function word sysVar.transferName is specified as the target in a transferstatement, do not specify that system variable in the related toPgm property.Instead, specify the program name that will be in sysVar.transferName when theprogram runs.

You can find more information on transfer statements and the transferNamesystem variable in the EGL Language Reference.

Related concepts




“alias in transferToProgram element” on page 413“fromPgm in transferToProgram element” on page 413“linkType in transferToProgram element” on page 414“packageName in transferToProgram element” on page 415“transferToProgram element” on page 410

transferToTransaction element

A transferToTransaction element of a linkage options part specifies how agenerated program transfers control to a transaction and ends processing, as occurswhen the originating program uses the transfer to transaction statement.

The element includes the required toPgm property and may include these optionalproperties:v alias, as is necessary if your code is transferring to a program whose runtime

name is different from the name of the related program part.v externallyDefined, as is necessary if your code is transferring to a program that

was not generated with EGL or VisualAge Generator.v packageName, as is necessary for a Java program if the Java program is

transferring to a program that is not in your workspace or will be generated to adifferent package for deployment.

If you are generating COBOL code, you can avoid specifying atransferToTransaction element when the target program is generated withVisualAge Generator or (in the absence of an alias) with EGL.

Related concepts


“Adding a linkage options part to an EGL build file” on page 63“Editing the transferToTransaction element of a linkage options part”Related reference

“alias in transferToTransaction element” on page 417“externallyDefined in transferToTransaction element” on page 418“packageName in transferToTransaction element” on page 419“toPgm in transferToTransaction element” on page 419

Editing the transferToTransaction element of a linkage optionspart

A transferToTransaction element of a linkage options part specifies how agenerated program transfers control to a transaction and ends processing, as occurswhen the originating program uses the transfer to transaction statement. To editthe transferToTransaction element, follow these steps:1. Locate the EGL build file you want to work with in the Project Explorer view.






5. Click the Show TransferLink Elements button on the editor toolbar. TheTransfer to Program and Transfer to Transaction lists display.

6. To edit the Transfer to Transaction list, follow these steps:a. At the bottom of the Transfer to Transaction list, click Add or press the

Insert key, and type a value in the To Program (toPgm) field, or select aprogram name from the To Program name drop-down list.

b. If an alias name is needed, select the row in the Transfer to Transaction listthat you want to edit, then click the Alias field once to put the field intoedit mode. Type the alias name.

c. To edit the Externally Defined property associated with your programname, select the row in the Transfer to Transaction list that you want toedit, then click the Externally Defined field once to put the field into editmode. Select the externally defined property from the Externally Defineddrop-down list.

d. If a package name is needed, as might be the case for Java if the FromProgram (fromPgm) is not in your workspace or is in a different packagethan the To Program (toPgm), select the row in the Transfer to Transactionlist that you want to edit, then click the Package Name field once to put thefield into edit mode. Type the package name into the field.

e. Modify the Transfer to Transaction list as needed:v To reposition a transferToTransaction element, select an element and click

either Move Up or Move Down.v To remove a transferToTransaction element, select an element and click

Remove or press the Delete key.Related concepts


“Adding a linkage options part to an EGL build file” on page 63“Editing the asynchLink element of a linkage options part” on page 376“Editing the callLink element of a linkage options part” on page 387“Editing the fileLink element of a linkage options part” on page 407“Removing a linkage options part from an EGL build file” on page 64Related reference

“EGL build-file format” on page 30“transferToProgram element” on page 410“transferToTransaction element” on page 416

alias in transferToTransaction element

In the transferToTransaction element of the linkage options part, the alias propertyspecifies the runtime name of the program that is identified in the toPgm property.

This property is necessary if your code is transferring to a program whose runtimename is different from the name of the related program part. The value of this


property must match the alias (if any) you specified when declaring the programto which you are transferring. If you did not specify an alias when declaring thatprogram, either set the alias property to the name of the program part or do notset the property at all.

Related topics


“Adding a linkage options part to an EGL build file” on page 63“Editing the transferToTransaction element of a linkage options part” on page416Related reference

“externallyDefined in transferToTransaction element”“packageName in transferToTransaction element” on page 419“toPgm in transferToTransaction element” on page 419“transferToTransaction element” on page 416

externallyDefined in transferToTransaction element

The externallyDefined property of the transferToTransaction element of thelinkage options part indicates whether you are transferring to a program that wasproduced by software other than EGL or VisualAge Generator. This property isonly used in COBOL generation. Valid values are NO (the default) and YES.

As an alternative to using the externallyDefined property of thetransferToTransaction element, you can specify isExternal = YES on the transfer totransaction statement. If you specify YES, the transfer to transaction is done insuch a way that EGL releases resources held by the EGL runtime environment.

For COBOL environments, the transfer to transaction is done as follows:v For CICS, the transfer is implemented with an EXEC CICS START (the default)

or with an EXEC CICS RETURN IMMEDIATE if the genReturnImmediate builddescriptor option is set to YES.

v For IMS/VS, the transfer to transaction statement is implemented as animmediate program to program message switch.

v For z/OS batch and IMS BMP, the transfer is implemented using the OS XCTLmacro.

v For iSeries, using the iSeries XCTL interface.

You can find more information about transfer statements in the EGL LanguageReference.

Related concepts



“alias in transferToTransaction element” on page 417“genReturnImmediate” on page 329“packageName in transferToTransaction element” on page 419


“toPgm in transferToTransaction element”“transferToTransaction element” on page 416

packageName in transferToTransaction element

The packageName property of the transferToTransaction element of the linkageoptions part identifies the Java package in which a transferred-to Java programresides.

If the packageName property is not specified, the transferred-to program isassumed to be in the same package as the originating program.

The package name that is used in generated Java programs is the package name ofthe EGL program, but in lower case; and when EGL generates output from thetransferToProgram element, the value of packageName is changed, if necessary, tolower case.

Related concepts



“alias in transferToTransaction element” on page 417“externallyDefined in transferToTransaction element” on page 418“toPgm in transferToTransaction element”“transferToTransaction element” on page 416

toPgm in transferToTransaction element

In the transferToTransaction element of the linkage options part, the requiredtoPgm property specifies one of the following:v For Java or COBOL programs generated for a non-CICS environment, the name

of the program part (or the name of the non-EGL program) that receives control.v For COBOL generated for a CICS environment, the name of the transaction that

receives control.v The value of a linkageKey property that was specified for a transfer to

transaction statement. Using a linkageKey enables you to create a singletransferToTransaction entry for multiple programs that have the samecharacteristics for the transfer to transaction.

If the function word sysVar.transferName is specified as the target in a transferstatement, do not specify that system variable in the related toPgm property.Instead, specify the program name that will be in sysVar.transferName when theprogram runs. Alternatively, specify a linkageKey on the transfer to transactionstatement and specify the value of that linkageKey as the toPgm property.

You can find more information about the system variables and functionsmentioned here in the topics ″transfer″ and ″transferName″ in the EGL LanguageReference.

Related concepts





Appendix. Notices

This information was developed for products and services offered in the U.S.A.IBM may not offer the products, services, or features discussed in this document inother countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user’s responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not grant youany license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBMIntellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia CorporationLicensing2-31 Roppongi 3-chome, Minato-kuTokyo 106-0032, Japan

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law:INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION ″AS IS″ WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESSFOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express orimplied warranties in certain transactions, therefore, this statement may not applyto you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvementsand/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

Any references in this information to non-IBM Web sites are provided forconvenience only and do not in any manner serve as an endorsement of those Websites. The materials at those Web sites are not part of the materials for this IBMproduct and use of those Web sites is at your own risk.

Licensees of this program who wish to have information about it for the purposeof enabling: (i) the exchange of information between independently created


programs and other programs (including this one) and (ii) the mutual use of theinformation which has been exchanged, should contact:

Intellectual Property Dept. for Rational SoftwareIBM Corporation3600 Steeles Avenue EastMarkham, ON Canada L3R 9Z7

Such information may be available, subject to appropriate terms and conditions,including in some cases, payment of a fee.

The licensed program described in this document and all licensed materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement or any equivalent agreementbetween us.

Any performance data contained herein was determined in a controlledenvironment. Therefore, the results obtained in other operating environments mayvary significantly. Some measurements may have been made on development-levelsystems and there is no guarantee that these measurements will be the same ongenerally available systems. Furthermore, some measurements may have beenestimated through extrapolation. Actual results may vary. Users of this documentshould verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers ofthose products, their published announcements or other publicly available sources.IBM has not tested those products and cannot confirm the accuracy ofperformance, compatibility or any other claims related to non-IBM products.Questions on the capabilities of non-IBM products should be addressed to thesuppliers of those products.

All statements regarding IBM’s future direction or intent are subject to change orwithdrawal without notice, and represent goals and objectives only.

This information contains examples of data and reports used in daily businessoperations. To illustrate them as completely as possible, the examples include thenames of individuals, companies, brands, and products. All of these names arefictitious and any similarity to the names and addresses used by an actual businessenterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, whichillustrate programming techniques on various operating platforms. You may copy,modify, and distribute these sample programs in any form without payment toIBM, for the purposes of developing, using, marketing or distributing applicationprograms conforming to the application programming interface for the operatingplatform for which the sample programs are written. These examples have notbeen thoroughly tested under all conditions. IBM, therefore, cannot guarantee orimply reliability, serviceability, or function of these programs.

Each copy or any portion of these sample programs or any derivative work, mustinclude a copyright notice as follows:

© (your company name) (year). Portions of this code are derived from IBM Corp.Sample Programs. © Copyright IBM Corp. enter the year or years_. All rightsreserved.


If you are viewing this information in softcopy, the photographs and colorillustrations may not appear.

Programming interface informationProgramming interface information is intended to help you create applicationsoftware using this program.

General-use programming interfaces allow you to write application software thatobtain the services of this program’s tools.

However, this information may also contain diagnosis, modification, and tuninginformation. Diagnosis, modification and tuning information is provided to helpyou debug your application software.

Warning: Do not use this diagnosis, modification, and tuning information as aprogramming interface because it is subject to change.

Trademarks and service marksIBM, the IBM logo, and ibm.com are trademarks or registered trademarks ofInternational Business Machines Corporation in the United States, other countries,or both. These and other IBM trademarked terms are marked on their firstoccurrence in this information with the appropriate symbol (® or ™), indicating USregistered or common law trademarks owned by IBM at the time this informationwas published. Such trademarks may also be registered or common lawtrademarks in other countries. A current list of IBM trademarks is available on theWeb at www.ibm.com/legal/copytrade.html.

Intel is a trademark of Intel Corporation in the United States, other countries, orboth.

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in theUnited States, other countries, or both.

Linux is a trademark of Linus Torvalds in the United States, other countries, orboth.

Microsoft, Windows, and Windows NT are trademarks of Microsoft Corporation inthe United States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and othercountries.

Other company, product or service names, may be trademarks or service marks ofothers.

Appendix. Notices 423


Index

Aalias EGL property

transferToProgram element 413transferToTransaction element 417

aliasescallLink element 389COBOL programs 100Java 97Java wrappers 98overview in EGL 97

association elementscommit property 72conversionTable property 72EGL duplicates property 72fileName property 72fileType property 73formFeedOnClose EGL property 73pcbName property 73replace property 73resource parts 71system property 74systemName property 74text property 77

asynchLink elementconversionTable property 377locationSpec property 378overview 375package property 379recordName property 379type property 379

BbidiConversionTable EGL build

descriptor option 299bidiRuntime EGL build descriptor

option 299bind control files

overview 267bind control parts

adding to build file 268editing EGL build files 269overview 264removing to build file 269

bind EGL build descriptor option 300birtEngineHome EGL build descriptor

option 301build descriptor options

bidiConversionTable EGL option 299bidiRuntime EGL option 299bind EGL option 300birtEngineHome EGL option 301build parts 3buildPlan EGL option 301cancelAfterTransfer EGL option 302checkIndices EGL option 302checkNumericOverflow EGL

option 303checkToTransaction EGL option 303checkType EGL option 304

build descriptor options (continued)cicsEntries EGL options 304cicsj2cTimeout EGL option 305clientCodeSet EGL option 306COBOL 234commentLevel EGL option 306currencyLocation EGL option 307currencySymbol EGL option 307data EGL option 308dbContentSeparator EGL option 308dbms EGL option 309debugTrace EGL option 309decimalSymbol EGL option 310defaultDateFormat 221, 310defaultMoneyFormat EGL option 311defaultNumericFormat EGL

option 312defaultServiceTimeout 222, 312defaultSessionCookieID 222, 313defaultTimeFormat 223, 313defaultTimeStampFormat 224, 314deploymentDescriptor 224, 315destDirectory 315destHost 316destLibrary 317destPassword 317destPort 318destUserID 318editing options 58eliminateSystemDependentCode 225,

319enableJavaWrapperGen EGL

option 320endCommarea EGL option 320errorDestination EGL option 321fillWithNulls EGL options 321formServicePgmType EGL

option 322genDataTables EGL option 322genDDSFile EGL option 323genDirectory EGL option 323genFormGroup EGL options 324genHelpFormGroup EGL option 324genProject EGL option 325genProperties EGL options 326genResourceBundle EGL option 328genReturnImmediate EGL option 329genRunFile EGL option 329genUIRecords EGL option 330imsFastPath 330imsID EGL option 331imsLogID 331includeLineNumbers EGL option 331initIORecordsOnCall EGL option 332initNonIODataOnCall EGL

option 332J2EE EGL option 333j2eeLevel EGL option 333Java options 144leftAlign EGL option 334linkage 335

build descriptor options (continued)linkEdit EGL option 335math EGL option 336maxNumericDigits 337mfsDevice EGL option 337mfsExtendedAttr EGL option 338mfsIgnore EGL option 339mfsUseTestLibrary EGL option 339nextBuildDescriptor 226, 340oneFormItemCopybook EGL

option 340positiveSignIndicator EGL

option 341prep EGL option 342printDestination EGL option 343programming languages 41, 220programPackageName EGL

option 344projectID EGL option 344reservedWord EGL option 345resourceAssociations EGL option 345resourceBundleLocale EGL

option 345restartTransactionID EGL option 346restoreCurrentMsgOnError EGL

option 346returnTransaction EGL option 347secondaryTargetBuildDescriptor EGL

option 347separatorSymbol EGL option 348serverCodeSet EGL option 349serverType EGL option 349sessionBeanID EGL option 350setFormItemFull EGL option 352spaADF EGL option 352spacesZero EGL option 353spaSize EGL option 352spaStatusBytePosition EGL

option 353sqlCommitControl EGL option 354sqlDB EGL option 355sqlErrorTrace EGL option 356sqlID EGL option 356sqlIOTrace EGL option 357sqlJDBCDriverClass EGL option 357sqlJNDIName EGL option 359sqlPassword EGL option 360sqlSchema EGL option 360sqlValidationConnectionURL EGL

options 360startTransactionID EGL option 361statementTrace EGL option 361synchOnPgmTransfer EGL

option 362synchOnTrxTransfer EGL option 363sysCodes EGL option 363system 226, 364targetNLS EGL option 365tempDirectory EGL option 366templateDir EGL option 367


build descriptor options (continued)transferErrorTransaction EGL

option 368truncateExtraDecimals EGL

option 368twaOffset EGL option 368useCurrentSchema EGL option 369userMessageFile EGL option 369useXctlForTransfer EGL option 370using symbolic parameters 59VAGCompatibility EGL option 370validateMixedItems EGL option 371validateOnlyIfModified EGL

option 371validateSQLStatements 372workDBType EGL option 373wrapperCompatibility EGL

option 373wrapperJNDIPrefix EGL option 374wrapperPackageName EGL

option 374build descriptor part

overview 33build descriptor parts

adding 38build descriptor options

Java 144runtime environment values 3

COBOL options 245default 38editing

build options 58mfsDevice options 60symbolic parameters 59

editing Java runtime properties 157Java options 152master build descriptors 36removing 39

build filesadding EGL link edit parts 273adding parts

bind control parts 268build descriptors 38import statements 31linkage options parts 63resource associations parts 69

creating 29editing parts

bind control parts 269import statements 32resource associations part 69

EGLformat 30

linkage options partediting asynchLink element 376editing callLink element 387editing fileLink element 407editing transferToProgram

element 411editing transferToTransaction

element 416removing parts

bind control part 269build descriptor 39import statement 32link edit part 275linkage options part 64

build files (continued)removing parts (continued)

resource associations part 71build parts

bind control file 267bind control parts 264build descriptor 33default build descriptor 38link edit

editing 274examples 270overview 269

linkage optionsCOBOL 257details 61Java 170

options 3resource associations

COBOL 258Java 171overview 65

build pathsEGL SDK command 22

build plansinvoking after generation 103overview 103

build scriptsdelivered with EGL 286example modifications (EGL) 283modifying for iSeries 298modifying for z/OS 282overview 105predefined pseudo-JCL substitution

variables 252predefined symbolic parameters 250pseudo-JCL syntax 287required options (EGL) 283symbolic parameters 246

build serverEGL generation overview 107

build serversstarting on iSeries 113starting on z/OS (EGL) 109

buildPlan EGL build descriptoroption 301

CCALL statement

pseudo-JCL syntax 288callLink element

alias property 389conversionTable property 389ctgKeyStore property 390ctgKeyStorePassword property 390ctgLocation EGL property 391ctgPort property 391library property 391linkType property 392location property 393luwControl property 395overview 380package property 396parmForm property 396pgmName property 398providerURL property 399refreshScreen property 400

callLink element (continued)remoteBind property 400remoteComType property 401remotePgmType 404serverID 405type

ejbCall 386localCall 382remoteCall 383

type property 405cancelAfterTransfer EGL build descriptor

option 302checkIndices EGL build descriptor

option 302checkNumericOverflow EGL build

descriptor option 303checkToTransaction EGL build descriptor

option 303checkType EGL build descriptor

option 304cicsEntries EGL build descriptor

options 304CICSJ2C calls

J2EE server sertup 189cicsj2cTimeout EGL build descriptor

option 305clientCodeSet EGL build descriptor

option 306COBOL generation

aliases for programs 100build descriptor options 41, 234, 245control language templates 264data conversion 85inputs 233JCL templates 262output 275output location 280overview 229reserved words 258restrictions 231runtime JCL templates 259symbolic parameters 246

command filesEGL generation 16

commentLevel EGL build descriptoroption 306

commitresource association part 72

ConnectionFactoryCICSJ2C 189IMSJ2C 190

connectionsJ2EE JDBC setup 192standard JDBC 190

control language templatesiSeries 263

conversionTableasynchLink element 377callLink element 389fileLink element 408

conversionTable EGL resource associationpart 72

csouidpwd.propertiesJava runtime properties file 388

ctgKeyStore EGL property 390ctgKeyStorePassword EGL property 390ctgLocation EGL property 391


ctgPort EGL property 391currencyLocation EGL build descriptor

option 307currencySymbol EGL build descriptor

option 307curses mode

UNIX library setup 197

Ddata conversion

EGL generated code 85data EGL build descriptor option 308dbContentSeparator build descriptor

option 308dbms build descriptor option 309DD statement

pseudo-JCL syntax in EGL 290debugTrace build descriptor options 309decimalSymbol EGL build descriptor

options 310defaultDateFormat EGL build descriptor

option 221, 310defaultMoneyFormat EGL build

descriptor options 311defaultNumericFormat EGL build

descriptor options 312defaultServiceTimeout EGL build

descriptor option 222, 312defaultSessionCookieID EGL build

descriptor option 222, 313defaultTimeFormat EGL build descriptor

option 223, 313defaultTimeStampFormat EGL build

descriptor option 224, 314deployment

Java applications outside of J2EE 195Java code 182service clients

z/OS CICS 126services

z/OS CICS 124setting up runtime environments 298z/OS CICS

service clients 126services 124

deployment descriptorJEE overview in EGL 175JEE updates in EGL 175

deployment descriptor (EGL)overview 118

deployment descriptor filesEGL services 79options

service clients 122services 121

services 118deploymentDescriptor EGL build

descriptor option 224, 315destDirectory EGL build descriptor

option 315destHost EGL build descriptor

option 316destLibrary EGL build descriptor

option 317destPassword EGL build descriptor

option 317

destPort EGL build descriptoroption 318

destUserID EGL build descriptoroption 318

directoriesgenerating Java code with EGL 180

driversJDBC with EGL 191

EEAR files

eliminating duplicate JAR files inEGL 187

EGL maintenance tool 24EGL software development kit (SDK)

overview 15EGL_GENERATORS_PLUGINDIR EGL

variable 13EGLBLD file

creating 29format 30

EGLDD filesoverview 79

EGLMAINT 24eglmaster.properties file

format 37eglpath EGL build path 22EGLPREP command 22EGLSDK command

creating command files 16generating output 15overview 18syntax 18

EJB projectssetting JNDI names in EGL 189

EJB session beansgenerating in EGL 188

eliminateSystemDependentCode EGLbuild descriptor option 225, 319

enableJavaWrapperGen EGL builddescriptor option 320

endCommarea EGL build descriptoroption 320

environment filesJEE settings in EGL 173

errorDestination EGL build descriptoroption 321

EXEC statementpseudo-JCL syntax in EGL 294

externallyDefined EGL propertytransferToTransaction EGL

element 418

Ffile names

aliasing in EGL 97fileLink element

conversionTable property 408fileName property 409locationSpec property 409overview 407type property 410

fileNamefileLink element 409

fileName (continued)resource association part 72

filesbuild

adding build descriptor 38removing build descriptor 39

EGLcommands 16

Java runtime settings 177link edit

editing 274examples 270overview 269

linkage properties 182results 281

fileTyperesource association part 73

fillWithNulls EGL build descriptoroptions 321

formFeedOnClose EGL property 73formServicePgmType EGL build

descriptor option 322fromPgm

transferToProgram element 413

GgenDataTables EGL build descriptor

option 322genDDSFile EGL build descriptor

option 323genDirectory EGL build descriptor

option 323generatable parts

EGLoverview 2

generating codeJ2EE environment 186

generating outputEGL SDK batch interface 15

generationCOBOL

options 245output location 280overview 229program parts 275program restrictions 231

Eclipse workbench 11EGL build server 107EGL command file 16EGL deployment descriptor files 79EGL_GENERATORS_

PLUGINDIR 13eglpath 22EGLSDK command syntax 18initiating 8IR files 81iSeries

services 129Java

choosing options 152code 178code directories in EGL 180output 172overview 141preparation phase 178programs 172

Index 427

generation (continued)Java (continued)

wrapper output 208wrappers 199

output file names 91output types 91phases

overview 1phases after

descriptions 5results view 27service clients

deployment options 122z/OS CICS 126

servicesdeployment descriptor 118deployment options 121iSeries 129overview 117z/OS CICS 128

starting 8z/OS CICS

services 128genFormGroup EGL build descriptor

option 324genHelpFormGroup EGL build descriptor

option 324genProject EGL build descriptor

option 325genProperties EGL build descriptor

option 326genResourceBundle EGL build descriptor

option 328genReturnImmediate EGL build

descriptor option 329genRunFile EGL build descriptor

option 329genUIRecords EGL build descriptor

option 330

IIF statements

pseudo-JCL syntax 296import statements

adding to build file 31editing in build file 32removing from build file 32

imsFastPath EGL build descriptoroption 330

imsID EGL build descriptor option 331imsLogID EGL build descriptor

options 331includeLineNumbers EGL build

description option 331initIORecordsOnCall EGL build

description option 332initNonIODataOnCall EGL build

description option 332input files

Java generation 143inputs

COBOL generation 233IR files

overview 81iSeries

modifying build scripts 298

iSeries (continued)starting build servers (EGL) 113

JJ2EE

JDBC connections 192server setup for CICSJ2C 189server setup for IMSJ2C 190

J2EE EGL build descriptor option 333J2EE environment

generating code 186j2eeLevel EGL build descriptor

option 333JAR files

access to non-EGL files 187eliminating duplicates from EAR files

in EGL 187Java

aliasing names in EGL 97applications

deploying outside of J2EE 195EGL runtime code 195

build descriptor options 41deploying code 182EGL preparation phase 178generation

input files 143non-J2EE environments 194overview 141symbolic parameters 170

output overview 172runtime properties

description 159overview 153

wrappersalias names 98classes 199generating 199generation output 208

Java runtime properties filescsouidpwd.properties 388

JavaScriptbuild descriptor options 220

JavaScript generationbuild descriptor options 220

JDBCEGL driver requirements 191J2EE connections 192standard connections 190

JEEdeployment descriptor values 176runtime setup 186updating deployment descriptor in

EGL 175updating environment files in

EGL 173JEE environment file

updating in EGL 173JNDI names

EJB projects in EGL 189

Kkeys

duplicates in EGL 72

LleftAlign EGL build descriptor

option 334library

callLink element 391link edit files

editing 274parts 269

link edit partbuild files 273editing 274examples 270overview 269removing from EGL build files 275

linkage EGL build descriptor option 335linkage options part

COBOL 257editing elements

asynchLink 376callLink 387fileLink 407transferToProgram 411transferToTransaction 416

ejbCall 386elements

asynchLink 375callLink 380, 382, 383, 386fileLink 407transferToProgram 410transferToTransaction 416

Java 170localCall 382overview 61remoteCall 383removing from build file 64type

ejbCall 386localCall 382remoteCall 383

linkage options partsadding to build file 63overview 375

linkage properties filesdescription 182

linkEdit EGL build descriptoroption 335

linkTypecallLink element 392transferToProgram element 414

listenersTCP/IP

J2EE 193non-J2EE 198

locationcallLink element 393

locationSpecasynchLink element 378fileLink element 409

luwControlcallLink element 395

Mmaster build descriptor

eglmaster.properties file 37overview 36


math EGL build descriptor option 336maxNumericDigits 337mfsDevice build descriptor option 337mfsDevice options

editing 60mfsExtendedAttr EGL build descriptor

option 338mfsIgnore EGL build decriptor

option 339mfsUseTestLibrary EGL build descriptor

option 339msgTablePrefix (EGL)

build descriptor option (EGL) 339

NnextBuildDescriptor EGL build descriptor

option 226, 340

OoneFormItemCopybook EGL build

descriptor option 340output

COBOL generation 275Java wrapper generation 208

PpackageName

transferToProgram element 415transferToTransaction element 419

packagesproperties

asynchLink element 379callLink element 396

parametersJava generation 170

parmFormcallLink element 396

partsEGL

build parts 3generatable EGL parts

overview 2linkage options 375

pcbNameresource association part 73

pgmNamecallLink element 398

pgmTypecallLink element 398

phasesgeneration 1

phases after generationEGL 5

positiveSignIndicator EGL builddescriptor option 341

predefined symbolic parametersbuild scripts 250

prep EGL build descriptor option 342preparing programs

EGLPREP command 22printDestination EGL build descriptor

option 343

program partsCOBOL generation 275Java generation 172Java wrapper generation 208

program properties filesJava runtime settings 177

programPackageName EGL builddescriptor option 344

projectID EGL build descriptoroption 344

projectsgenerating Java code 178

propertiesassociation elements

commit 72conversionTable 72duplicates in EGL 72fileName 72fileType 73formFeedOnClose EGL

property 73pcbName 73replace 73system 74systemName 74text 77

asynchLink elementconversionTable 377locationSpec 378recordName 379type 379

callLink elementalias 389conversionTable 389ctgKeyStore 390ctgKeyStorePassword 390ctgPort 391library 391linkType 392location 393luwControl 395parmForm 396pgmName 398providerURL 399refreshScreen 400remoteBind 400remoteComType 401remotePgmType 404serverID 405type 405

EGLtransferToTransaction element EGL

element 418EGL callLink element

ctgLocation 391fileLink element

conversionTable 408fileName 409locationSpec 409type 410

Java runtime 159packages

asynchLink element 379callLink element 396

transferToProgram elementalias 413fromPgm 413

properties (continued)transferToProgram element (continued)

linkType 414packageName 415toPgm 415

transferToTransaction elementalias 417packageName 419toPgm 419

providerURLcallLink element 399

pseudo-JCLEGL syntax

CALL statement 288DD statement 290EXEC statement 294IF statements 296overview 287VARS statement 297

predefined substitution variables 252

RrecordName

asynchLink element 379refreshScreen

callLink element 400remoteBind

callLink element 400remoteComType

callLink element 401remotePgmType

callLink element 404replace

in resource association part 73reserved words

COBOL 258reservedWord EGL build descriptor

option 345resource associations part

associations elements 71editing in build files 69Java 171, 258overview 65removing from build file 71

resource associations partsadding to build files 69

resourceAssociations EGL builddescriptor option 345

resourceBundleLocale EGL builddescriptor option 345

restartTransactionID EGL build descriptoroption 346

restoreCurrentMsgOnError EGL builddescriptor option 346

results filesCOBOL 281

returnTransaction EGL build descriptoroption 347

Rich UIdeployment 213generation 213

runtime codeJava applications in EGL 195

runtime environmentJEE setup 186

Index 429

runtime environmentsgenerating to non-J2EE

environments 194setting up for code deployment 298

runtime propertiesfor Java 153in J2EE environment 153in non-J2EE environment 153

runtime templatescontrol language for iSeries 263

SSDK

EGL output generation 15secondaryTargetBuildDescriptor EGL

build descriptor option 347Security Manager

configuration (EGL) 109, 115overview (EGL) 108, 114setting environment (EGL) 108, 114

separatorSymbol EGL build descriptoroption 348

serverCodeSet EGL build descriptoroption 349

serverIDcallLink element 405

serverType EGL build descriptoroption 349

service clientsdeploying

z/OS CICS 126deployment descriptor options 122

z/OS CICS 126services

deployingz/OS CICS 124

deployment descriptor options 118,121

generatingiSeries 129z/OS CICS 128

sessionBeanID EGL build descriptoroption 350

setFormItemFull EGL build descriptoroption 352

Software development kit (EGL SDK)generating output 15

spaADF EGL build descriptoroption 352

spacesZero EGL build descriptoroption 353

spaSize EGL build descriptor option 352spaStatusBytePosition EGL build

descriptor option 353sqlCommitControl EGL build descriptor

options 354sqlDB EGL build descriptor option 355sqlErrorTrace EGL build descriptor

option 356sqlID EGL build descriptor option 356sqlIOTrace EGL build descriptor

option 357sqlJDBCDriverClass EGL build descriptor

option 357sqlJNDIName EGL build descriptor

option 359

sqlPassword EGL build descriptoroption 360

sqlSchema EGL build descriptoroption 360

sqlValidationConnectionURL EGL builddescriptor options 360

startTransactionID EGL build descriptoroption 361

statementsbind control

adding to build file 268removing to build file 269

importadding to build file 31editing in build file 32removing 32

linkage options parts in EGL buildfiles 63

resource associationsadding to build files 69editing in build files 69

statementTrace EGL build descriptoroption 361

symbolic paramatersJava generation 170

symbolic parametersCOBOL generation 246editing build descriptor part 59

synchOnPgmTransfer EGL builddescriptor option 362

synchOnTrxTransfer EGL build descriptoroption 363

sysCodes EGL build descriptoroption 363

systemresource association part 74

system EGL build descriptor option 226,364

systemNamein resource association part 74

Ttable files

CICS 281targetNLS EGL build descriptor

option 365TCP/IP listeners

J2EE 193non-J2EE 198

tempDirectory EGL build descriptoroption 366

templateDir EGL build descriptoroption 367

templatesCOBOL

modifying CL 264modifying JCL 262runtime JCL 259

textin resource association part 77

toPgmtransferToProgram element 415transferToTransaction element 419

trademarks 423transferErrorTransaction EGL build

descriptor option 368

transferToProgram elementalias property 413fromPgm property 413linkType property 414overview 410packageName 415packageName property 415toPgm property 415

transferToTransaction EGL elementexternallyDefined EGL property 418

transferToTransaction elementalias property 417overview 416packageName 419packageName property 419toPgm property 419

truncateExtraDecimals EGL builddescriptor option 368

twaOffset EGL build descriptoroption 368

typeasynchLink element 379callLink element 405fileLink element 410

UUNIX curses libraries

setup for EGL 194UNIX curses library

setting up 197useCurrentSchema EGL build descriptor

option 369userMessageFile EGL build descriptor

option 369useXctlForTransfer EGL build descriptor

option 370

VVAGCompatibility EGL build descriptor

option 370validateMixedItems EGL build descriptor

option 371validateOnlyIfModified EGL build

descriptor option 371validateSQLStatements 372VARS statement

pseudo-JCL syntax 297views

EGL Generation Results 27VSAM

access prerequisites 83support 83system names 83

WWeb service

generating 117Web services

deployment descriptor options 121Web transactions

gateway servlet parameters 131linkage properties 135


workbenchgenerating 11

workDBType EGL build descriptoroption 373

wrapperCompatibility EGL builddescriptor option 373

wrapperJNDIPrefix EGL build descriptoroption 374

wrapperPackageName EGL builddescriptor option 374

Zz/OS

build considerations (EGL) 111modifying build scripts 282starting build servers (EGL) 109

Index 431


��

Printed in USA