|
|
|
|
|
|
Generating a Java Application with the eGen COBOL Code Generator
The BEA WebLogic Java Adapter for Mainframe (JAM) consists of two components:
Using JAM, BEA WebLogic Server users can make requests for mainframe services and receive responses to those requests. Also, mainframe users can make requests from Java applications (EJBs) running in WebLogic Server and receive responses to those requests.
This Programming Guide provides you with instructions on generating Java applications that make requests for mainframe services and accept the responses returning from the mainframe. One of the generated application types, the Server EJB, accepts requests from mainframe applications, then responds to those requests. Refer to the action list in the Action List section.
Action List
As you generate a Java application with the eGen COBOL Code Generator (also called the eGen utility), see the following action list and refer to the appropriate information sources.
Prerequisites
Before you start programming, you should complete the following tasks:
Understanding JAM
Figure 1-1 illustrates how the eGen utility works.
Figure 1-1 Understanding the eGen Utility
Figure 1-2 illustrates how your generated application works with JAM. Figure 1-2 Generated Application Working with JAM
Choosing an eGen Java Application Model
There are four different types or models of Java applications that can be generated by the eGen utility. These are:
Choose one of these four model types to use as the basis for your Java application.
Gathering Mainframe Applications Information
Once you have determined which eGen application model you will be using, it is time to gather information about the mainframe application with which JAM will be interacting. The mainframe information gathered will be used to complete the JAM configuration that maps mainframe components to JAM components. COBOL copybooks gathered from the mainframe application will be used to generate Java application code using the eGen utility.
Obtaining Mainframe Services Information
You will need the following mainframe information to develop a Java application that requests a mainframe service:
Listing 1-1 shows an example of how a mainframe service is defined. These service definitions can be found in the JC_REMOTE_SERVICES section of your JAM gateway configuration file (jcrmgw.cfg).
Listing 1-1 Setting a Remote Service in jcrmgw.cfg
<ServiceName> RDOM="<Remote Domain>"
RNAME="<Mainframe Application called>"
TRANTIME=<transfer time>
SCHEMA=<Schema Name>
You will need the following mainframe information to develop a Java application that responds to requests from the mainframe:
Listing 1-2 shows an example of how a JAM service invoked from the mainframe is defined. These service definitions can be found in the JC_LOCAL_SERVICES section of the jcrmgw.cfg file.
Listing 1-2 Setting a Local Service (Used by Server EJB) in jcrmgw.cfg
<Stateless Session Bean Home> RNAME="<Resource Name>"
Any mainframe service to be requested from JAM must be listed in the JAM gateway configuration file (jcrmgw.cfg). These services must be running on your mainframe, either under CICS or IMS. You will need to know the names under which these services are available, and what data formats they require. These data formats will usually be available as COBOL copybooks. If COBOL copybooks are not available, you will need to create them from whatever documentation of the data format you have available.
Mainframe data records are represented in JAM by Java DataView classes. These classes are generated by the eGen utility and provide all of the data translation necessary to communicate with mainframe applications as well as a Java-style access to your data.
The sample files listed in Table 1-1 provide examples of code that can be used to generate Java applications that can request mainframe services. These code example files can be found by extracting them from the samples.jar file in your
<JAM Installation>\examples directory, then looking in the sample directory that is created inside the examples directory.
|
COBOL Applications |
Gateway Config File |
COBOL Copybook |
|---|---|---|
|
dpldemoc.cbl |
jcrmgw1.cfg |
emprec.cpy |
eGen scripts corresponding to each of the four generation models can also be found in the samples.jar file. The applications generated from these scripts are used as examples throughout this guide and BEA Java Adapter for Mainframe Scenarios.
Obtaining a COBOL Copybook
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. If the CICS application does not use a copybook file (but simply defines the COMMAREA directly in the program source), you will have to create one from the definition contained in the program source.
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 the "COBOL Datatypes" section of the BEA Java Adapter for Mainframe Reference Guide. An eGen utility trial run will reveal any unsupported constructs or data types. If the eGen utility is unable to fully support constructs or data types, it:
If the eGen utility reports constructs or data types as errors, you must modify them, so the eGen utility can translate them.
Each copybook's contents (which define a COMMAREA record) are parsed by the eGen utility, producing DataView sub-classes that provide facilities to:
Creating a New 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 JAM as you create these copybooks.
Using an Existing COBOL Copybook
When a mainframe application has an existing DPL interface, the data for that interface is probably 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 JAM does not support. To accomplish this task, attempt to process it.
An example COBOL copybook source file is shown in Listing 1-3.
Note: Some of the code sample listings in this topic have field names in bold for easier reading. Also, comment-numbered items have corresponding comments at the bottom of each script example.
Listing 1-3 Sample emprec.cpy COBOL Copybook
1 02 emp-record. (Comment 1)
2
3 04 emp-ssn pic 9(9) comp-3.
4
5 04 emp-name.
6 06 emp-name-last pic x(15). (Comment 2)
7 06 emp-name-first pic x(15).
8 06 emp-name-mi pic x.
9
10 04 emp-addr. (Comment 3)
11 06 emp-addr-street pic x(30).
12 06 emp-addr-st pic x(2).
13 06 emp-addr-zip pic x(9).
14
15 * End
Table 1-2 refers to the numbered comments in Listing 1-3.
Writing an eGen COBOL Script
After you have gathered information about the mainframe applications and have decided on an eGen Java application model for it, you are ready to write an eGen COBOL script. This eGen script and the COBOL copybook that describes your data structure will be processed by the eGen utility to generate the basis for your custom Java application.
An eGen COBOL script has two sections. These are:
The eGen scripts that can be used to generate example applications corresponding to each of the four generation models can be found in the samples.jar file. The samples.jar file can be found in the <JAM Installation>\examples directory. The application code generated from these scripts is used as examples throughout this guide and BEA Java Adapter for Mainframe Scenarios.
Writing the DataView Section of an eGen COBOL 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 Listing 1-4. This section is only the first section of the eGen script. Application code is generated by the second section.
Listing 1-4 Sample DataView Section of an eGen COBOL Script
generate view sample.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. sample.EmployeeRecord tells the eGen utility to call the DataView file EmployeeRecord and place it in a package called sample. The code from emprec.cpy tells the eGen utility to form the EmployeeRecord DataView file from the COBOL copybook emprec.cpy.
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 1-5 Sample DataView Section with Codepage Specified
generate view sample.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 1-6 Sample DataView Section Supporting XML
generate view sample.EmployeeRecord from emprec.cpy support xml
Additional files generated for XML support are listed in Table 1-3.
Table 1-3 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. |
Writing the Application Section of an eGen COBOL Script Now that you have written the DataView section of the script and have determined which application model that you want to generate, refer to the section from the following list for instructions on writing the script and implementing the model you have chosen:
For all of the applications you generate, you must provide a script file containing definitions for the application, including the COBOL copybook file name and the DataView class names.
Processing eGen Scripts with the eGen Utility
After you have written your eGen COBOL script, you must process it. Processing the eGen COBOL script generates Java DataView and application code. This Java code must be compiled and deployed. Although processing the eGen COBOL script into DataView and application code is usually performed in one step, it will be 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
Before you create an environment for generating and compiling your Java application code, you must already have set up your environment as explained in the BEA WebLogic Server documentation and the BEA Java Adapter for Mainframe Installation Guide.
When you process the eGen COBOL 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 access to the necessary Java classes and applications.
For the eGen utility:
For compilation:
Note: UNIX users must use "/" instead of "\" when adding directory paths as specified above.
Generating the Java DataView Code
The script in Listing 1-7 specifies that the COBOL copybook file named emprec.cpy is parsed, and that the Java DataView source file named EmployeeRecord.java is generated from it. Also, this file is added to package sample. In other words, when this script is processed by the eGen utility, a file named EmployeeRecord.java is generated, and it contains the definition of class EmployeeRecord in package sample. (If you are referring to the sample files that can be extracted from samples.jar, note that this file is contained in a directory called sample.) The EmployeeRecord class is an instance of the DataView class.
Listing 1-7 Sample DataView Section of emprec.egen Script
generate view sample.EmployeeRecord from emprec.cpy
If you saved this script in a file named emprec.egen, the following shell command parses the copybook file named emprec.cpy and generates the EmployeeRecord.java source file in the current directory:
Listing 1-8 Sample Copybook Parse Command
egencobol emprec.egen
If no error or warning messages are issued, the copybook is compatible with JAM and the source files are created. If you are generating DataView code using the sample code provided in the samples.jar file, you will notice that no application source files are generated by processing the emprec.egen script. No application source files are generated because there are no application generating commands in this script.
Note: Refer to the "Error Messages" section of the BEA Java Adapter for Mainframe Reference Guide 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 1-9 Generated EmployeeRecord.java Source File
//EmployeeRecord.java
//Dataview class generated by egencobol emprec.cpy
package Sample;(Comment 1)
//Imports
import bea.dmd.DataView.DataView;
...
/**DataView class for EmployeeRecord buffers*/
public final class EmployeeRecord (Comment 2)
extends DataView
{
...
// Code for field "emp-ssn"
private BigDecimal m_empSsn;(Comment 3)
public BigDecimal getEmpSsn() {...}(Comment 4)/** DataView subclass for emp-name Group */
public final class EmpNameV (Comment 5)
extends DataView
{
...
// Code for field "emp-name-last"
private String m_empNamelast;
public void setEmpNameLast(String value) {...}
public String getEmpNameLast() {...}(Comment 6)// Code for field "emp-name-first"
private String m_empNameFirsrt;
public void setEmpnameFisrt (String value) {...}
public String getEmpNameFirst() {...}// Code for field "emp-name-mi"
private String m_empNameMi;
public void setEmpNameMi (String value) {...}
public String getEmpnameMi() {...}
}// Code for field "emp-name"
private EmpNameV m_empname; (Comment 7)
public EmpnameV getEmpname() {...}/**DataView subclass for emp-addr Group */
public final class EmpAddrV
extends DataView
{
...
// Code for field "emp-addr-street"
private String m_empAddrStreet;
public void setEmpAddrStreet(Street value) {...}
public String getEmpAddrStreet() {...}// Code for field "emp-addr-st"
private String m_empAddrSt;
public void setEmpAddrSt(String value) {...}
public String getEmpAddrSt() {...}// Code for field "emp-addr-zip"
private String m_empAddrZip;
public void setEmpAddrZip(String value) {...}
public String getEmpAddrZip() {...}
}// Code for field "emp-addr"
private EmpAddrV m_empAddr;
public EmpAddrV getEmpAddr() {...}
}//End EmployeeRecord.java
Table 1-4 refers to the numbered comments in Listing 1-9.
Generating the Java Application Code
The Java application code can be generated at the same time that you generate the Java DataView code. To generate Java application code, the eGen COBOL script that you process must contain instructions for generating the Java application along with the instructions for generating the DataView code.
Referring to the sample files in samples.jar, the following command generates EmployeeRecord.java and SampleServlet.java. EmployeeRecord.java is the DataView file, and SampleServlet.java is the application file.
> egencobol empservlet.egen
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:
All of these class files are used when compiling your application code.
Deploying Applications
Deployment is the process of implementing servlets and/or EJBs on WebLogic Server. Application deployment in WebLogic Server has evolved to the J2EE standard for web application deployment.
The following information is not intended to specifically describe how applications are deployed in WebLogic Server. For specific information, refer to Quick Start information and detailed documentation for deploying applications in the WebLogic Server 6.0 online documentation at:
http://download.oracle.com/docs/cd/E13222_01/wls/docs60/quickstart/quick_start.html
http://download.oracle.com/docs/cd/E13222_01/wls/docs60/servlet/admin.html#156888
http://download.oracle.com/docs/cd/E13222_01/wls/docs60/ejb/EJB_deployover.html
Deploying a JAM eGen Servlet (Quick-Start Deployment)
The basic JAM eGen servlet is deployed like any other WebLogic servlet. The configuration for the eGen servlet is stored in the web.xml file in an applications directory associated with a domain. The basic default configuration can be found in the following directory:
<bea_home>/<wls_home>
/config/mydomain/applications/DefaultWebApp_myserver/WEB-INF/web.xml
For the SampleServlet (generated by the egencobol empservlet.egen command), add the classes and sample directories, so the directory structure looks like the following:
<bea_home>/<wls_home>/config/mydomain
/applications/DefaultWebApp_myserver/WEB-INF/classes/sample
The eGen SampleServlet and EmployeeRecord class, which are the result of compiling the *.java files generated by the eGen utility, should be placed in the sample directory:
<bea_home>/<wls_home>/config/mydomain
/applications/DefaultWebApp_myserver/WEB-INF/classes/sample
SampleServlet can be configured with an XML entry (added to web.xml) similar to the one shown in Listing 1-10:
Listing 1-10 XML Entry to Configure the SampleServlet Servlet
<web-app>
<servlet>
<servlet-name>
SampleServlet
</servlet-name>
<servlet-class>
sample.SampleServlet
</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>
SampleServlet
</servlet-name>
<url-pattern>
/SampleServlet/*
</url-pattern>
</servlet-mapping>
</web-app>
SampleServlet can then by invoked by entering the following URL in the location field of your web browser:
http://<host>:<port>/SampleServlet
If WebLogic Server is running on your local machine and you used the default port (7001) when you installed WebLogic Server, SampleServlet can be invoked by the following URL:
http://localhost:7001/SampleServlet
Deploying a JAM eGen EJB
A JAM eGen EJB (client or server) is deployed like any other WebLogic EJB. The following instructions and examples are provided as an aid:
Listing 1-11 Script for Building empclientbean.jar
@rem --- Adjust these variables to match your environment -----------------
set TARGETJAR=empclientbean.jar
set JAVA_HOME=c:\bea\jdk130
set WL_HOME=c:\bea\wlserver6.0sp1
set JAM_HOME=c:\bea\wljam4.2
@rem ------ end of Adjustable variables ------------------------------------
set JAMJARS=%JAM_HOME%\lib\jam.jar
set CLASSPATH=%JAM_HOME%\lib\jam.jar;%JAM_HOME%\lib\tools.jar;
%WL_HOME%\lib\weblogic.jar
set PATH=%JAVA_HOME%\bin;%JAVA_HOME%\lib;%PATH%
@rem Create the build directory, and copy the deployment
@rem descriptors into it.
@rem You should have already run your egen script so your xml files
@rem are already built.
md build build\META-INF
copy SampleClient-jar.xml ejb-jar.xml
copy wl-SampleClient-jar.xml weblogic-ejb-jar.xml
copy *.xml build\META-INF
@rem Compile ejb classes into the build directory (jar preparation)
javac -d build -classpath %CLASSPATH% *.java
@rem Make a standard ejb jar file, including XML deployment
@rem descriptors
cd build
jar cvf std_%TARGETJAR% META-INF sample
cd ..
@rem Run ejbc to create the deployable jar file
java -classpath %CLASSPATH% -Dweblogic.home=%WL_HOME% weblogic.ejbc -compiler javac build\std_%TARGETJAR% %TARGETJAR%
The EJB Deployments screen appears (see Figure 1-3).
Figure 1-3 Configuring a New EJB, empclientbean.jar
The EJB Deployments Create screen appears (see Figure 1-4). Figure 1-4 New EJB Configuration Screen
Your JAM eGen EJB is now deployed.
Providing OS/390 Mainframe Access with No Data Translation
JAM may be used for OS/390 mainframe access without performing data translation. All client-side code generated by the eGen utility uses the EgenClient class to access the gateway. This class provides a raw-byte interface to the gateway. Use of the EgenClient class for gateway access has the following advantages and disadvantages:
Use the interface of the EgenClient class (shown in Listing 1-12) to perform raw mainframe requests.
Listing 1-12 Interface for Performing Raw Mainframe Requests
package com.bea.jam.egen;
import com.bea.sna.jcrmgw.snaException;
public class EgenClient
{
public EgenClient();
public byte[] callService(String service, byte[] in)
throws snaException, java.io.IOException;
}
Note: If an example of the proper use of this class is desired, the eGen utility may be used to generate a client class.
Using Client Diagnostic Features with WebLogic Server 6.0
JAM includes several features to support diagnosing problems with eGen-based client programs. While these facilities are not designed for use in a production environment, they should be useful during development. These features are enabled by adding the settings listed in Table 1-5 to the java statement at the end of your startWebLogic.cmd file for the BEA WebLogic Server domain that you are currently running.
Table 1-5 Client Diagnostic Settings
Listing 1-13 provides an example in bold of the changes that need to be made to the java statement in the startWebLogic.cmd file necessary to enable the client diagnostic loopback feature. This file can be found in the %WLS_HOME%\config\<domain> directory. The java statement can be found near the end of the file. Listing 1-13 startWebLogic.cmd Loopback Example Client Traffic Tracing When client traffic tracing is enabled, all requests from eGen clients are dumped to the WebLogic console in hexadecimal and EBCDIC characters. Listing 1-14 shows an example of an eGen client dump. Listing 1-14 Dump of eGen Client Requests Note that the dumps occur while the data is in mainframe format, and characters are usually in some variety of EBCDIC. By default, the character data is converted using cp037, but that may be changed using another property setting. Client Loopback If the client loopback feature is enabled, all requests receive a response that is exactly equal to the request data. Note that this loopback response is accomplished while the data is in mainframe format. If a service accepts one DataView subclass and returns a different one, a conversion failure in trying to construct the resulting DataView subclass may occur. When the client loopback feature is enabled, no gateway is required and the gwboot startup class does not need to be configured. Client Stub Operation The client stub operation enables you to replace the gateway with your own class, in effect providing a replacement for the entire target mainframe. This feature is valuable for testing or proof-of-concept situations where the mainframe connection is not available. Your stub class must:
...
"%JAVA_HOME%\bin\java" -hotspot -ms64m -mx64m -classpath %CLASSPATH% -Dweblogic.Domain=mydomain -Dbea.jam.client.loopback=true -Dweblogic.Name=myserver "-Dbea.home=g:\bea" "-Djava.security.policy==g:\bea\wlserver6.0sp1/lib/weblogic.policy" -Dweblogic.management.password=%WLS_PW% weblogic.Server
...---------------- Service: demoRead Input data --------------
00 00 00 00 0f e2 d4 c9 e3 c8 40 40 40 40 40 40 .....SMITH
40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40
40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40
40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40
40 40 40 40 40 40 40 40 40 40 40 40 40 00 00 00 .
01 00 00 00 00 0f 00 00 00 00 0f 00 00 00 00 00 ............
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ............
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ............
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ............
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ............
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ............
--------------------------------------------------------------
---------------- Service: demoRead Output data --------------
00 00 00 00 0f e2 d4 c9 e3 c8 40 40 40 40 40 40 .....SMITH
40 40 40 40 a7 40 40 40 40 40 40 40 40 40 40 40 x
40 40 40 a7 94 81 89 95 40 40 40 40 40 40 40 40 xmain
40 40 40 40 40 40 40 40 40 40 40 40 40 40 40 40
40 40 40 40 40 40 40 40 40 40 40 40 40 00 00 00 ..
01 00 00 00 00 0f 00 00 00 00 0f ..........
--------------------------------------------------------------
The client tracing feature can be used to help debug your stub class.
What Do I Do Next?
Refer to the chapter from the following list that corresponds to the Java application model you have chosen for your Java application:
Also, refer to BEA Java Adapter for Mainframe Scenarios for detailed examples of some of the application models discussed in this guide.
|
|
|
|
|
|
Copyright © 2001 BEA Systems, Inc. All rights reserved.
|