ibm software group | rational software

IBM Software Group | Rational Software

© 2007 IBM Corporation1

COBOL Generation for System z COBOL Generation for System z

Mark [email protected]

P. Michael [email protected]



– © Copyright IBM Corporation 2006. All rights reserved.

– The information contained in these materials is provided for informational purposes only, and is provided AS IS without warranty of any kind, express or implied. IBM shall not be responsible for any damages arising out of the use of, or otherwise related to, these materials. Nothing contained in these materials is intended to, nor shall have the effect of, creating any warranties or representations from IBM or its suppliers or licensors, or altering the terms and conditions of the applicable license agreement governing the use of IBM software. References in these materials to IBM products, programs, or services do not imply that they will be available in all countries in which IBM operates.

– This information is based on current IBM product plans and strategy, which are subject to change by IBM without notice. Product release dates and/or capabilities referenced in these materials may change at any time at IBM’s sole discretion based on market opportunities or other factors, and are not intended to be a commitment to future product or feature availability in any way.

– IBM, the IBM logo, the on-demand business logo, Rational, the Rational logo, and other IBM Rational products and services are trademarks or registered trademarks of the International Business Machines Corporation, in the United States, other countries or both. Other company, product, or service names may be trademarks or service marks of others.



Agenda – EGL COBOL Generation

EGL COBOL Generation Overview

Setting up COBOL Generation

– Required Products

– Host/Mainframe Configuration

– Customization Points

– EGL Build Files

Using EGL COBOL Generation

– Coding for EGL COBOL Generation

– Looking at Results

– Miscellaneous

Demo



EGL Generation Overview EGL Generates (transforms/creates):

– Java - for J2EE or non-J2EE

– COBOL for z/OS (System z) – for batch, CICS or IMS

– COBOL for iSeries (System i)

EGL parts must be generated to produce these outputs:

– The Java code containing the EGL defined logic

– The COBOL code containing the EGL defined logic

The generation process delivers the code to the target platform

– Java – to RAD/RDz Java Project which automatically builds (compiles) code

– COBOL – to z/OS datasets or system i files where the code is built (compiled) by the build server



EGL Generation Process - Overview

•EGL Project •EGL Source Parts• Build Descriptors• Other build parts

•Java Project•containing•Java code•(compiled automatically)

•Generate Java

•Directories •containing •COBOL code,•link & bind info

•Generate COBOL

Code EGL Parts• Logic• Data• I/O• Build parts

Savew/Validation

Datasets/Files containing

COBOL code,link & bind info

Executables and

auxiliary files

Compile, link, bind

TC

P/IP

TC

P/I

P

Generation



EGL COBOL Generation Process Detail – System z

EGLCOBOLRuntime

files

EGL ProjectsEGL Projects

Preprocessor

Workstation z/OS

EGL Build

Server

EGL JCL

Build Scripts

Load Modules

DBRMs

TCP/IP

CICS

IMS

BatchEGL Build Files

1

EGL Source Files

(Programs, etc)COBOL Generator

COBOL Source

Other Files

Results Files

Listings

IDE Build Job

Generation Result

Build Client

ccublds

2 3

6

78

1011

5

12

4

13

8. Build server pulls up buildplan.xml and retrieves/parses correct EGL JCL Build Script

9. Build server starts job to build (compile,etc) the generated code

10. Build job runs and pulls files from workstation and uses files from the EGL COBOL runtime (copybooks) and then creates executables

11. Build Job sends results back to the workstation

12. Build client is notified of job completion and if successful or failure and it then notifies COBOL generator

13. COBOL Generator updates Generation Results view with success or not and if failure….location of results file

1. You have source ready to generate !!!!

2. Generate requested using source files and build files as input

3. EGL Preprocessor is run to validate EGL source for the target system (CICS, IMS, Batch)

4. The EGL COBOL generator creates COBOL and other source files including “buildplan.xml” file in local file system

5. EGL Build client code (ccubldc) is invoked

6. Build client starts up security process to encrypt passwords

7. From info in buildplan.xml, conversation with running build server is started

9



Holy Cow!!!!

How do I make all this work?

It is not that Complicated !!!

Just need to follow a few simple steps !!



EGL COBOL Generation – Basic Steps

1. Get Required EGL Components

2. Setup/Customize/Start Build Server

3. Setup Build Files

4. Write Code !! (obviously)

5. Generate the code

6. Look at Results

7. Test/Run

Hey… this is EASY!!!

Done ONCE at beginning by

Administrator!!



Step 1: Getting the Required Components



EGL COBOL Generation – Required EGL Components?

Purpose Product Required Component(s)

System z Client RAD or RSA 7.0 plus

Rational Business Developer Extension V7.0

or

Rational Developer for zSeries V7.1 plus Rational Business Developer Extension V7.0

EGL COBOL Generation

Server (z/OS) Rational COBOL Runtime for zOS V6.0.1 EGL COBOL Runtime AND EGL Build Server



Step 2: Setup/Customize the EGL COBOL Gen build process



EGL COBOL Generation: Build Server on System z

The System Programmer will need to install and customize the Runtime Environment.

Job that is supplied by EGL and runs on z/OS

– CCURUNM member in install PDS (by default)

– Specifies• Port to listen on• Authentication levels• CCUWJCL DD card specifies

member containing Build Job JCL

Build Job

– In CCUMVS member by default

– CCUPROC DD Card specifies dataset with JCL Build Scripts

Note: See for more setup information:

- Program Directories

- EGL Host Server Guide

- EGL Helps



EGL COBOL Generation: JCL Build Scripts on System z Pseudo-JCL that executes the necessary processes to

make an executable (see next chart)– Example: FDAPCL– Is a member in dataset specified in CCUPROC

Contain “VARS” which provide substitution information within build steps– Value can be set through data sent from client (see

Buildplan.xml later) – Will override any “default” value if provided– VARS provide substitution information within build steps.

Substitutions are listed as “&varname”

In this example (sample substitution variables)– &CGHLQ will equal projectID Build descriptor– &SYSTEM will equal target generation system– CCUEXT defines the file type to upload from workstation

(if it exists)



EGL COBOL Generation: JCL Build Scripts on System z

FDABCL COBOL compile, link (no DB2)

(z/OS batch, IMSBMP, and IMSVS)

FDABIND Runs bind command for generated program

FDACL COBOL compile, link (no CICS commands)

FDAMFS MFS Compile (IMSVS only)

FDALINK Linkage editor for format modules (formgroups)

FDAPCL DB2 precompile, COBOL compile, link (with DB2)

(z/OS Batch, IMSBMP, IMSVS)

FDAPTCL CICS translator, DB2 precompile, COBOL compile, link edit

FDATCL CICS translator, COBOL compile, link (No DB2 in program)



EGL COBOL Generation: Customization on System z The EGL Build Process can be customized

– JCL Build Scripts• Outcome of source and listings can be changed

– Upload source only vs save in PDS– Download listing vs throw away vs save in file

• New steps can be added• New Substitution variables can be added• JCL Procedures can be called (with substitution)

– Can control scripts via “symbolics” in build descriptors (later)• Result:

Can “modify” results from build scripts based on use of different build descriptors

AND

Enables way to do builds for different stages of development

> Example: Unit Test, Systems test, Production

– Also can have more than one build server running simultaneously• Must use different port• Could use different set of build scripts for different purposes



EGL COBOL Generation: Default z/OS datasets

Description Data set name Target environment

Database request module cghlq.env.dbrmlib All z/OS if DB2 is used

Bind commands cghlq.env.ezebind All z/OS if DB2 is used

Batch Execution JCL cghlq.env.ezejclx ZOSBATCH

Object Library cghlq.env.object All z/OS

COBOL Source Library cghlq.env.ezesrc All z/OS

Load library cghlq.env.load All z/OS

CICS PCT entries cghlq.env.ezepct ZOSCICS

CICS PPT entries cghlq.env.ezeppt ZOSCICS

Note: Datasets can be created by running CLIST ELACUSER

What Target Datasets “might” be used on z/OS (by default)???

Saving or not after generation is based on JCL Build Script



EGL COBOL Generation: Client Side Setup What runs on the client to talk to the server

– ccubldc.exe process will be started (in the background)• Build client code that interacts with build server

– CCU Security manager (EGL Java Class) starts to encrypt passwords passed to host machine

What is needed on the client machine– Required in developer’s machine settings

• CLASSPATH– <radinstall>\bin\eglbatchgen.jar

• PATH– <radinstall>\bin

NOTE: RDz adds these settings during install of EGL Feature

WDSC-AE does NOT set these during install.

(must be done manually)



Step 3: EGL Build Files for COBOL Generation

(directing the generation process)



EGL COBOL Generation - EGL Build Files

Build files

–Contain Build Parts

–Have a .eglbld file extension

Build parts include:

–Build descriptor

–Resource Associations

–Linkage options

–Link Edit (z/OS only)

–Bind Control (z/OS DB2 only)

Editing build parts

Build parts use specialized build part editors



EGL COBOL Generation – EGL Build File Editor

Visible options can be filtered

– By target system

– By intended use of descriptor

– Basic vs. All options

– Only options with values

Filter to show only options with values

Filter based ontarget system, intended use of descriptor and all vs. basic options

Options

Values



EGL COBOL Generation – Build Parts Overview

Build Descriptors

– Controls total build process

Resource Associations

– Supplies logical and physical information for file access

Linkage

– Supplies information for inter-program calls

Link Edit (z/OS only... Used rarely)

– Supplies information to control linkage editor if needed

• Example: link-edit information for static calls

Bind Control (z/OS only and program uses SQL)

– Supplies information needed to do DB2 binds



EGL COBOL Generation – Build Descriptors

A Build Descriptor part is required

– Specifies how to generate the code

– Specifies runtime options associated with the code

Composed of sets of options

– Some options identify other build parts to utilize

•Example: linkage

– Some identify other EGL parts to generate if referenced

•Example: genDataTables

Same EGL source may be associated with multiple build descriptors

– Target system generation & runtime options

• Required to generate/build code

– Debug runtime options

• If running the code in the EGL debugger



EGL COBOL Generation – Build Descriptors

The set of applicable options varies:

– By language being generated (Java vs. COBOL)

– By target system (CICS, IMS or Batch)

– By intended use of the build descriptor

• Target System • Debug

Setting up your build descriptors

– Easier if you avoid setting it up from scratch

– Good to have one as a starting point

• The “Create EGL Project” wizard can generate one for you

– Some groups prefer everyone use a common set across all projects



Common Build Descriptor Options for COBOL Gen on zBind Identifies bind part name to use

in creating bind information

destHost Host name of machine containing the EGL build server

destPort Port number on which EGL build server is listening

destPassword Password of UserID that is being used for build (case sensitive)

destUserId Host UserID used for build (case sensitive)

genDataTables Tells generator to also generate any “used” dataTables in a program

genDirectory Name of folder in file system (not workspace) that the generated output will be written to

genFormGroup Tells generator to also generate any “used” form groups in a program (for 3270 programs)

genHelpFormGroup Tells generator to also generate any “used” help form groups in a program (for 3270 programs)

prep Tells generator to send the generated output to the EGL Build Server

projectID High level qualifier of the target datasets on z/OS

System Target system for generation

Many others…see EGL Help!(hint: Select line and press f1..help will open for option



EGL COBOL Generation: Symbolic Build Descriptors EGL provides Symbolics

– Can create user-defined build descriptors

– Used in build processing• Normally supply/override substitution values for JCL

Build Scripts

– EGL-defined symbolics• Usually sets value based on EGL build descriptor• Always start with EZExxxx• Examples

– projectID EZEPID and CGHLG– System EZEENV

– Referenced by • %symbolicname% within workstation• &symbolicname in JCL build scripts• symbolicname in FDAPREP

– Example: > %EZEENV% in genDirectory > Creates folder equal to value specified for

system



EGL COBOL Generation – Bind Control parts (z/OS only) Bind Control parts are only applicable to:

–COBOL code built for z/OS

–Code accesses DB2

Provides information to create a bind control file

–Same as bind control file you would create for native COBOL code

–SQL used to create database request modules (DBRMs) to put in plan

–Can create one part used by all programs or unique to a particular program

Bind Control commands

–Default: Bind Plan

–Most people use Bind Package•Bind Control Part to be created with Bind Package (can be used by all generates)•Most information can be supplied by symbolics



Other Build Parts – Link Edit for COBOL Gen on z/OS

Default Linkage Editor commands are built

If default does not work, then create Link Edit Parts

– Are only needed when generated COBOL program:

• Has static COBOL calls to other programs

• Is called statically by another program, whether generated or not

• Want to link specific LE Runtime options to EGL generated programs

– They provide information to create a link edit file

• Same as link edit file you would create for native COBOL code

• Specifies how to package programs into load modules



Step 4: Coding considerations for COBOL Generation



EGL COBOL Generation: Limitations in the language

If you are writing source code using the Enterprise Generation Language and intend to generate output in COBOL, the following restrictions are in effect:

– Reports via integration with Jasper or other reporting tools

– BLOB and CLOB support

– Multi-dimensional arrays

– EGL Dictionaries

– JDBC access for supported database products

– Web Support

– External Types (invocation of non-EGL Java classes)

Be careful not to use Java specific libraries and functions in programs that are intended to be generated to COBOL.



Step 5: Generate the files – Just like everything else

(CNTL/G of the file or Generate from Context menu)



Step 6: Look at the Results



EGL COBOL Generation: How do I know if it works?

Look in the Generation Results View

Good

Failed Results returned to client

(more on this later)



EGL COBOL Generation – Files produced by generation for zGeneratable Part Files produced Comments

Program

<pgmname>

<pgmname>.cbl

<pgmname>.bnd

<pgmname.led

<pgmname>,jcx

<pgmname>BuildPlan.xml

COBOL source

Bind Control statement

Linkage editor statements

Execution JCL (for ZOSBATCH)

Build plan used to control build process

FormGroup

<formgpname>

<formgrpname>FM.fmt (binary)

<formgrpname>.cbl

<formgpname>FM.led

<formgpname>.cpy

<formgpname>.mfs

<formgrpname>FMBuildPlan.xml

Binary Object for Form

COBOL Source (print forms only)


Copy book for forms (IMSVS only)

MFS source for forms (IMSVS only)


DataTable

<tablename>

<tablename>.cbl

<tablename.led

<tablename>BuildPlan.xml

COBOL source



Library

<libname>

<libname>.cbl

<libname.led

<libname>BuildPlan.xml

COBOL source





EGL COBOL Generation: Buildplan.xml for System z

BuildPlan.xml file controls build server……How??

– What to run on build server• Via “command name”• Correspond to JCL Build Script Names • Name indicates type of processing

– Host information • Via “host name”• Location/port• Code Pages for conversion

– Location of generated files• Via “input files” and “dependencies”

– Substitution information• via “env” names



EGL COBOL Generation: Build Results file

What do I look at when it fails?

– Either the “results.xml” file

or

– <progname>.CCUBLDC.log

Both will be in the same directory as the generated output

If needed job name/job number is in results



EGL COBOL Generation: Where to find failures for z?

Listings can be returned to Workstation by adding these to your build file

– CCUOUT in the symbolics indicates that listings should be returned to client

– Listings are named:

• <name>.<stepname>.<listingname>

– Where stepname is “c”, “p”, “t”, etc

– Where listingname is the DDNAME for the listings of that step

• Examples:



Step 7: Test/Run your progam



To run your TUI program(Assuming the Runtime Environment is

configured correctly)

To test the application you just generated,

Log onto CICS

Enter the transaction ELAN

This performs the “New Copy”

operation on the program you just generated.

For example, if you generated a program MADELCP and its TUI

Form called MAP048

Exit the ELAN transaction, and then test/run the application.



To run your Batch program

(Assuming the Runtime Environment is configured correctly)

Note: For batch program generation there is a property you can set, genRunFile, that will create the sample runtime JCL for the program just generated. For more information on this see: Runtime JCL templates for z/OS in the RAD Help.)

To test the application you just generated,

Verify that the program compiled successfully and is in the appropriate object library.

Submit the JCL.

Verify the results.



Miscellaneous



EGL provides sample runtime templates for execution

The templates that are shipped with the product are installed in the MVSTemplates or iSeriesTemplates subdirectory:– <RADInstall>\egl_cobolgen\eclipse\plugins\com.ibm.etools.egl.generators.cobol_<ver>\MVSTemplates

– <RADInstall>\egl_cobolgen\eclipse\plugins\com.ibm.etools.egl.generators.cobol_<ver>\iSeriesTemplates

– File name used varies depending on function of program

You can customize and change location of templates by setting the build descriptor option “templateDir”

EGL COBOL Generation: Runtime Templates



EGL Batch Generation – outside workbench

The EGL software development kit (SDK) is a feature that lets you generate output in a batch environment– Enables ANT script based generate/builds

– Enables automated Builds

– Still use build descriptors and all processes still work the same way

– EGLSDK• Generates using files from a directory in the file system• Self-contained jar with no need for eclipse APIs (at least external)• Most likely one used for Batch generations

– See: Generation using the EGL Software Development Kit (SDK) in the RAD Help for more information.



Questions?



BACKUP



EGL Generation Process - Overview

EGL Project •EGL Source Parts• Build Descriptors• Other build parts

Java ProjectcontainingJava code

(compiled automatically)

Generate Java

Directories containing


Generate COBOL

Code EGL Parts• Logic• Data• I/O• Build parts

Savew/Validation

Datasets containing


Executables and

auxiliary files

Compile, link, bind

TC

P/IP



EGL COBOL Generation Process Overview

When you change certain build file options (minimally, setting J2EE to “no”, setting a genDirectory, and system to “ZOSBATCH”) generation will create COBOL from your EGL.

Note from the picture that besides creating the COBOL for an application, EGL can also automatically (when Prep=“y”) transfer the COBOL, JCL and if necessary DB2 Bind files to the mainframe for execution and test.

EGLCOBOLRuntime

files

EGL Build Descriptor (Deployment)

…System = z/OSBatch z/OSCICS IMS Prep = Y/N….

COBOL SourceLinkEdit

BindBuild Plan

Format Module ….

EGL ProjectsEGL ProjectsPreprocessor

EGL COBOL Extension for zSeries

Code Generation

z/OS Batch Z/OS CICS IMS

Workstation z/OS

EGL Build

Server

Prep =Y

EGL JCL

Build Scripts

Load Modules

DBRMs

TCP/IP

CICS

IMS

Batch



EGL COBOL Generation: Build Server on System i

Main Job that is supplied by EGL

– ccublds executable in library QEGL (supplied by EGL)

– To start, use following command on system iSBMJOB CMD(CALL PGM(*LIBL/CCUBLDS) PARM(’-p’ ’2600’)) JOB(CCUBLDS) JOBQ(QSYS/QSYSNOMAX)

Build Job

– FDAPREP in QEGL/QREXSRC

– Started by build server when request comes in

– Uses variables sent up to the System i through generation

– Runs online build commands based on information sent from the client

Note: See for more setup information:

– EGL Server Guide for iSeries (SC31-6841)• Also on EGL zone in Developerworks



EGL COBOL Generation: Customization on System i The EGL Build Process can be customized

– Modify the FDAPREP REXX program

• Contains “sections” depending on contents of program– SQL – Called program– etc

– Example customization

• Setting DB2 interface method – SQL vs System

– .evf files provide parameters



EGL COBOL Generation: Functions used on System i

PMN Main (5250/batch) programs with no SQL

PSM Main (5250/Batch) programs with SQL

PCL Called programs with no SQL

PSC Called Programs that contain SQL

PPM Print Services Programs

TCM EGL user messages or messageTable file

WCL Runtime CL’s for main programs

WSC Runtime CL’s for called programs

Function names passed to FDAPREP to drive build process



EGL COBOL Generation: Default System I filesDescription Physical file Name

Generation Variables File QVGNEVF

Table Binary Images QVGNTAB

Runtime CLs QVGNCLS

Form Group Modules QVGNMAPG

COBOL Source Library

Print Services Program

QVGNCBLS

Message Files QVGNMSGS

Data Definition Specs (DDS) QVGNDDS

Load library (physical files) destLibrary value in build file

Files MUST be created in target destination library

Can create using following command

STRREXPRC SRCMBR(EGLSETUP) PARM(xxxxxxxx)Where xxxxxxxx is the destination library



Common Build Descriptor Options for COBOL Gen on idestHost Host name of machine containing

the EGL build server

destPort Port number on which EGL build server is listening

destPassword Password of UserID that is being used for build (case sensitive)

destUserId Host UserID used for build (case sensitive)

destLibrary Library on System i to send the generated outputs

genDataTables Tells generator to also generate any “used” dataTables in a program

genDirectory Name of folder in file system (not workspace) that the generated output will be written to

genFormGroup Tells generator to also generate any “used” form groups in a program (for 5250 programs)

genHelpFormGroup Tells generator to also generate any “used” help form groups in a program (for 5250 programs)

prep Tells generator to send the generated output to the EGL Build Server

System Target system for generationMany others…see EGL Helps!(hint: Select line and press f1 help will open for option



EGL COBOL Generation: Buildplan.xml for System i BuildPlan.xml file controls

build server……How??

– What to run on build server• Via “parms”• Invokes REXX program

– Host information • Via “host name”• Location/port• Code Pages for conversion

– Location of generated files• Via “input files” and

“dependencies”

– Substitution information• via “env” names

+• .evf file



EGL COBOL Generation: Where to find failures for i?

Listings contained in:

– <genname>.ccubldc.log

ibm software group | rational software

Documents

egl generationoverview

egl cobol generation

egl cobol generation

egl cobol gen build

egl cobol runtime copybooks

cobol generator cobol

ims cobol

build serverpulls