BEA Home | Events | Solutions | Partners | Products | Services | Download | Developer Center | WebSUPPORT
JAM Documentation | JAM Programming Guide | Previous Topic | Next Topic | Contents | Index

Generating a Java Application with the eGen COBOL Code Generator

The BEA WebLogic Java Adapter for Mainframe (JAM) consists of two components:

- JAM gateway

- Communication Resource Manager (CRM)

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.

| Your action... | Refer to...
--- | --- | ---
1 | Complete all prerequisite tasks. | Prerequisites
2 | Choose an eGen application model. | Understanding JAM and Choosing an eGen Java Application Model
3 | Gather necessary mainframe applications information. | Gathering Mainframe Applications Information
4 | Write an eGen COBOL script | Writing an eGen COBOL Script
5 | Process eGen Scripts with the eGen utility | Processing eGen Scripts with the eGen Utility
6 | Compile the Java application code. | Special Considerations for Compiling the Java Code
7 | Deploy the generated applications. | Deploying Applications
8 | Debug the generated applications. | Using Client Diagnostic Features with WebLogic Server 6.0
9 | Proceed to the next set of instructions. | What Do I Do Next?

Prerequisites

Before you start programming, you should complete the following tasks:

| Your action... | Refer to...
--- | --- | ---
1 | Install your computer systems, Windows/UNIX and mainframe, to meet your requirements. | BEA WebLogic Java Adapter for Mainframe Installation Guide
2 | Configure your computer systems, Windows/UNIX and mainframe, to meet your requirements. | BEA WebLogic Java Adapter for Mainframe Configuration and Administration Guide

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:

- Servlet Only. The servlet-only application is a servlet that presents a simple form and invokes mainframe services directly. This is the simplest model, but it may be unsuitable for production applications.

- Client EJB. The client EJB is a Stateless Session EJB that invokes mainframe services. It may be called by a servlet or other client programs. This is the normal model for building a production application with access to mainframe services. A servlet that invokes the EJB's methods may be added for testing or demonstration purposes.

- Client Class. The client class is a stand-alone Java class that invokes mainframe services. This class may be built into your own EJB or utilized in some other way within your code.

- Server EJB. The server EJB is a Stateless Session EJB that provides a service to the mainframe.

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:

- Resource names of the services to be requested. The resource name is the name of the mainframe application providing the service.

- For CICS, the resource name is the equivalent of the CICS program name.

- For IMS, the resource name is the IMS transaction name.

- COBOL copybooks that define the format of the data sent and/or received from the mainframe. The eGen utility will use these copybooks to generate DataViews.

- A service name that JAM will map to the resource name.

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:

- Resource name of the service to be requested. This name is the service name that the mainframe application (CICS or IMS) invokes to run the Java service.

- COBOL copybooks that define the data layout of data sent and/or received by the mainframe application. The eGen utility will use these copybooks to generate DataViews used by the Java server EJB.

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.

Table 1-1 Relevant Example Code from samples.jar File

COBOL Applications

Gateway Config File

COBOL Copybook

dpldemoc.cbl
dpldemor.cbl
dpldemou.cbl
dpldemod.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:

- Treats them as alphanumeric data types (if reasonable)

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

- Reports them as errors

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:

- 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.

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.

Table 1-2 Script Comments for emprec.cpy

Comment 1

Declaration of a record (group) data item.

Comment 2

An elementary item. This is the base level of the data structure.

Comment 3

An aggregate item. This is the intermediate level of the data structure.

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:

- 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.

- Java application. The Java application section of the script generates the Java application code.

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:

- Generating a Servlet-Only Application

- Generating a Client Enterprise Java Bean-based Application

- Generating a Server Enterprise Java Bean-based Application

- Generating a Stand-alone Client Application

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:

- Add <JAM Installation Directory>\lib\jam.jar to your CLASSPATH.

- Add <JAM Installation Directory>\bin to your PATH.

For compilation:

- Add <JAM Installation Directory>\lib\jam.jar to your CLASSPATH.

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

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

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.

Table 1-4 Script Comments for EmployeeRecord.java

Comment 1

The package name is defined in the eGen script.

Comment 2

The data record is encapsulated in a class that extends the DataView class.

Comment 3

Each class member variable corresponds to a field in the data record.

Comment 4

Each data field has accessor functions.

Comment 5

Each aggregate data field has a corresponding nested inner class that extends the DataView class.

Comment 6

Each data field within an aggregate data field has accessor functions.

Comment 7

Each COBOL data field name is converted into a Java identifier.

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:

- 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.

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:

1. Build your EJB deployment JAR file. Listing 1-11 will build the client EJB deployment JAR file from the components generated by the empclient.egen eGen COBOL script and emprec.cpy.

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%

2. Deploy the EJB in BEA WebLogic Server by configuring it as a new EJB in the BEA WebLogic Server Admin Console. Configure this new EJB as follows:

1. Click the EJB icon under Deployments.

The EJB Deployments screen appears (see Figure 1-3).

Figure 1-3 Configuring a New EJB, empclientbean.jar

2. Click the Configure a new EJB link.

   The EJB Deployments Create screen appears (see Figure 1-4).

   Figure 1-4 New EJB Configuration Screen

3. Enter the name of your EJB in the Name: field, the EJB Deployment JAR file in the URI: field, and the path to the EJB Deployment JAR file in the Path: field. Make sure that the Deployed checkbox is checked. Then, click Create.

   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:

- Advantages:

1. No translation infrastructure overheads are incurred

2. Simple interface

3. JAM's client diagnostic features may be used

- Disadvantages:

1. Not used for requests inbound from the mainframe

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

bea.jam.client.trace.enable | Set to "true" to enable tracing of client requests.
bea.jam.client.trace.codepage | Set to the name of a codepage to be used for the character portion of the trace dump.
bea.jam.client.loopback | Set to "true" to bypass the gateway & simply loop the request bytes back to the client.
bea.jam.client.stub | Set to the full name of a class to be used as a gateway stub.

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

>     				...
>     "%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
>     				...

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

>     ---------------- 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                  ..........
>     --------------------------------------------------------------

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:

- Provide a constructor that takes no arguments.

- Be available on your CLASSPATH.

- Contain a method for each service that is to be supported. This method must take some DataView subclass as its only argument and return a DataView subclass.

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:

- Generating a Servlet-Only Application

- Generating a Client Enterprise Java Bean-based Application

- Generating a Server Enterprise Java Bean-based Application

- Generating a Stand-alone Client 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. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.