Generating a Java Application with the eGen Application Generator

 

This section discusses the following topics:

• Understanding eGen

• Working With COBOL Copybooks

• Processing eGen Scripts with the eGen Utility

 

---

Understanding eGen

The eGen Application Generator, also known as the eGen utility, is installed with WebLogic JAM. It generates Java applications from a COBOL copybook and a user-defined script file.

The eGen utility generates a Java application by processing a script you create, called an eGen script. A Java DataView is defined by the first section of the script. This DataView is used by the application code to provide data access and conversions, as well as to perform other miscellaneous functions. The actual application code is defined by the second section of the script.

Figure2-1 illustrates how the eGen utility works. This illustration shows the eGen script and COBOL copybook file being used as input to the eGen utility, and the output that is generated is the DataView and the Java application. The generated Java application may be used in a variety of ways. In some cases, it may be used as is. However, in most cases, you will need to extend the generated application in some way, or it may become a member of the actual user-defined application.

 

Figure 2-1 Understanding the eGen utility

 

 

---

Working With COBOL Copybooks

A COBOL CICS or IMS mainframe application typically uses a copybook source file to define its data layout. This file is specified in a COPY directive within the LINKAGE SECTION of the source program for a CICS application, or in the WORKING-STORAGE SECTION of an IMS program. If the CICS or IMS application does not use a copybook file, you will have to create one from the data definition contained in the program source.

Each copybook's contents are parsed by the eGen utility, producing DataView sub-classes that provide facilities to:

• Convert COBOL data types to and from Java data types. This includes conversions for mainframe data formats and code pages.

• Convert COBOL data structures to and from Java data structures.

• Convert the provided data structures into other arbitrary formats.

Obtaining a COBOL Copybook

The eGen utility must have a COBOL Copybook to use as input. There are two methods you can use to obtain this Copybook:

• Creating a New COBOL Copybook

• Using an Existing COBOL Copybook

Creating a New COBOL Copybook

If you are producing a new application on the mainframe or modifying one, then one or more new copybooks may be required. You should keep in mind the COBOL features and data types supported by WebLogic JAM as you create these copybooks (see eGen Application Generator Reference for more information).

Using an Existing COBOL Copybook

When a mainframe application has an existing DPL or APPC interface, the data for that interface is usually described in a COBOL copybook. Before using an existing COBOL Copybook, verify that the interface does not use any COBOL features or data types that WebLogic JAM does not support (see Limitations of the eGen Utility).

An example COBOL copybook source file is shown in Listing2-1.

Listing 2-1 Sample emprec.cpy COBOL Copybook

 

Limitations of the eGen Utility

The eGen utility is able to translate most COBOL copybook data types and data clauses into their Java equivalents; however, it is unable to translate some obsolete constructs and floating point data types. For information on COBOL data types that can be translated by the eGen utility, see DataView Programming Reference. If the eGen utility is unable to fully support constructs or data types, it:

• Treats them as alphanumeric data types (if reasonable)

• Ignores them (if their support is unimportant to WebLogic JAM's operation)

• Reports them as errors

If the eGen utility reports constructs or data types as errors, you must modify them, so they can be translated.

 

---

Writing an eGen Script

After you have obtained a COBOL Copybook for the mainframe applications, you are ready to write an eGen script. This eGen script and the COBOL copybook that describes your data structure will be processed by the eGen utility to generate a DataView and application code which will serve as the basis for your custom Java application.

An eGen script has two sections. These are:

• DataView. The DataView section of the script generates Java DataView code from a COBOL copybook. The class file compiled from the generated code extends the Java DataView class. Generating DataViews is discussed in detail in the remainder of this section.

  Note: If the purpose of your eGen script is to generate a DataView for use with the WebLogic JAM to JMS EJB, or to launch a WebLogic Integration event, you only need to create the DataView section of the script.

• Java application. The Java application section of the script generates the Java application code. This is discussed in detail in Basic Programming Techniques.

Writing the DataView Section of an eGen Script

The eGen utility parses a COBOL copybook and generates Java DataView code that encapsulates the data record declared in the copybook. It does this by parsing an eGen script file containing a DataView definition similar to the example shown in Listing2-2 (keywords are in bold). The section containing the DataView definition is the first section of the eGen script. Application code is generated by the second section.

Listing 2-2 Sample DataView Section of an eGen script

generate view examples.CICS.outbound.gateway.EmployeeRecord from emprec.cpy

Analyzing the parts of this line of code, we see that generate view tells the eGen utility to generate a Java DataView code file. examples.CICS.outbound.gateway.EmployeeRecord tells the eGen utility to call the DataView file EmployeeRecord.java. The package is called examples.CICS.outbound.gateway. The EmployeeRecord class defined in EmployeeRecord.java is a subclass of the DataView class. The phrase from emprec.cpy tells the eGen utility to form the EmployeeRecord DataView file from the COBOL copybook emprec.cpy.

Additional generate view statements may be added to an eGen script in order to produce all the DataViews required by your application. Also, additional options may be specified in the eGen script to change details of the DataView generation. For example, the following script will generate a DataView class that uses codepage cp500 for conversions to and from mainframe format. If the codepage clause is not specified, the default codepage of cp037 is used.

Listing 2-3 Sample DataView Section with Codepage Specified

generate view examples.CICS.outbound.gateway.EmployeeRecord from emprec.cpy codepage cp500

The following script will generate additional output intended to support use of the DataView class with XML data:

Listing 2-4 Sample DataView Section Supporting XML

generate view sample.EmployeeRecord from emprec.cpy support xml

Additional files generated for XML support are listed in Table 2-1.

Table 2-1 Additional Files for DataView XML Support.

File Name	File Purpose
classname.dtd	XML DTD for XML messages accepted and produced by this DataView.
classname.xsd	XML schema for XML messages accepted and produced by this DataView.

 

---

Processing eGen Scripts with the eGen Utility

After you have written your eGen script, you must process it to generate the DataView and application code. This Java code must then be compiled and deployed. The same eGen script usually contains both the definitions of the DataView and application code, and both are produced with a single processing of the script. However, in this Programming Guide, the script is explained in two steps, so the actual code generated can be analyzed in greater detail.

Creating an Environment for Generating and Compiling the Java Code

When you process the eGen scripts and compile the generated Java code, you must have access to the Java classes and applications used in the code generation and compilation processes. Adding the correct elements to your CLASSPATH and PATH environment variables provides this access.

For the eGen utility:

• Add <JAM_INSTALL_DIR>\lib\jam.jar to your CLASSPATH.

• Add <JAM_INSTALL_DIR>\bin to your PATH.

For compilation:

• Add <JAM_INSTALL_DIR>\lib\jam.jar to your CLASSPATH.

• Add <WLS_HOME>\lib\weblogic.jar to your CLASSPATH.

• Add the path of your DataView class files to your CLASSPATH . You will need access to these classes when you compile your Java application code.

Notes: UNIX users must use "/" instead of "\" when adding directory paths as specified above.

Running config\verify\setVerifyEnv.cmd (on Windows systems) or config/verify/setVerifyEnv.sh (on UNIX systems) will perform the above actions necessary for the eGen utility.

Generating the Java DataView Code

For the eGen script named emprec.egen shown in Listing2-2, the following shell command parses the copybook file named emprec.cpy (see Listing2-1) and generates the EmployeeRecord.java source file in the current directory:

Listing 2-5 Sample Copybook Parse Command

egencobol emprec.egen

If no error or warning messages are issued, the copybook is compatible with WebLogic JAM and the source files are created. Note that no application source files are generated by processing the emprec.egen script. This is because there are no application generating commands in this script.

Note: Refer to eGen Application Generator Reference for suggestions on resolving any problems encountered.

The following example illustrates the resulting generated Java source file, EmployeeRecord.java with some comments and implementation details removed for clarity.

Listing 2-6 Generated EmployeeRecord.java Source File

 

Special Considerations for Compiling the Java Code

You must compile the Java code generated by the eGen utility. However, there are some special circumstances to consider. Because the application code is dependent on the DataView code, you must compile the DataView code and make sure that the resulting DataView class files are in your environment's CLASSPATH before compiling your application code. You must make sure that all of the DataView class files can be referenced by the application code compilation.

For example, the compilation of EmployeeRecord.java results in four class files:

• EmployeeRecord.class

• EmployeeRecord$EmpRecord1V.class

• EmployeeRecord$EmpRecord1V$EmpName3V.class

• EmployeeRecord$EmpRecord1V$EmpAddr7V.class

All of these class files are used when compiling your application code.