Corporate Info | News | Solutions | Products | Partners | Services | Events | Download | How To Buy
WebLogic Java Adapter for Mainframe Doc Home | Previous Topic | Next Topic | Contents | Index

Updating an Existing EJB to Service a Mainframe Request

This section contains a scenario that shows how to update an existing EJB to service a request from the mainframe. In this scenario, use the WebLogic Server basic statelessSession TraderBean and update the interface to add a dispatch function that is given control upon receipt of an inbound request. The eGen COBOL client class code generation model is used. The TraderBean is designed to run from a stand-alone client and output a list of stock trades.

This scenario is based on the general procedures presented in Developing Java Applications, It gives you practical examples for using JAM tools, presented as tasks with step-by-step procedures. This scenario depicts the development of a new application and the updating of existing applications. WebLogic Server samples are used to illustrate any existing applications. All discussions are from the application developer's point of view, presume a properly installed and configured environment, and presume an appropriate mainframe application is available.

Note: Although the sample code in this section represents typical applications, it is intended for example only and is not supported for actual use.

The following tasks are required to update and existing EJB to service a request from the mainframe:

- Task 1: Use eGen COBOL to Create a Base Class

- Task 2: Update the Trader Interface Using the Generated Class

- Task 3: Update the JAM Configurations

- Task 4: Deploy Your Application

- Task 5: Use the Application

The following section describes the sample programs required for updating an EJB to service a mainframe request:

- Sample COBOL Program to Write to Temporary Storage Queue

Task 1: Use eGen COBOL to Create a Base Class

You should have successfully run the WebLogic Server basic statelessSession TraderBean prior to attempting the updates discussed in this scenario. You must then identify the mainframe application and obtain its COBOL copybook. This is typically a CICS DFHCOMAREA or the user data portion of an IMS queue record layout. The copybook's name in this discussion is trader.cbl, as shown in Listing 11-1.

Listing 11-1 Mainframe Application COBOL Copybook trader.cbl

>     02  TRADER-RECORD.
>     	05  CUSTOMER				PIC X(24).
>     	05  SYMBOL				PIC X(6).
>     	05  SHARES				PIC 9(7) COMP-3.
>     	05  PRICE				PIC 9(7) COMP-3.

Step 1: Prepare eGen COBOL Script

The single-line script in Listing 11-2 generates the data view traderData from the copybook named trader.cbl. The script is then saved as inboundEJB.egen.

Listing 11-2 Basic eGen COBOL script

>     view traderData from trader.cbl

You are now finished creating the inboundEJB.egen script file and are ready to generate the source code.

Step 2: Generate the Java Source Code

In Listing 11-3, you invoke the eGen COBOL code generator to compile trader.cbl copybook and inboundEJB.egen. The traderData.java is the data view object for trader.cbl.

Warning: CLASSPATH should have both the WebLogic Server subdirectories and the jam.jar file; otherwise, the compile fails.

Note: You could create a script file containing the eGen COBOL command line, along with the javac command to make the invocation easier.

Listing 11-3 Generating the Java Source Code

>     egencobol inboundEJB.egen
>     ls  traderDat*.java
>     traderData.java
>     javac traderData.java

Step 3: Review the Java Source Code

It is a good idea to obtain a list of accessors for use later. Look at the eGen COBOL output to become familiar with each of the scenarios presented in this section.

The entire method of customizing the generated output is predicated on deriving the output from generated code. The base application can be regenerated without destroying the custom code.

Note: Each COBOL group item has its own accessor. This is important because the group name represents a nested inner class that must be accessed in order to retrieve the members.

In Listing 11-4, the output from the grep command shows the relationships in reverse order, for example:

>     getTraderRecord().getPrice()

This is illustrated in the actual code example shown subsequently in this scenario.

Listing 11-4 Review the Java Source Code

>     grep get traderData.java
>     	public String			getCustomer()
>     	public String			getSymbol()
>     	public BigDecimal				getShares()
>     	public BigDecimal				getPrice()
>     	public TraderRecordV					getTraderRecord()
>     grep set traderData.java
>     	public void			setCustomer(String value)
>     	public void			setSymbol(String value)
>     	public void			setShares(BigDecimal value)
>     	public void			setPrice(BigDecimal value)

Task 2: Update the Trader Interface Using the Generated Class

You are now ready to update the WebLogic Server trader example basic statelessSession bean.

Step 1: Start with Import

In Listing 11-5, the EJB interface is updated. In the Trader interface declaration, the EJBobject is replaced with gwObject. The gwObject extends EJBObject and provides the dispatch method that gets control on receipt of an incoming request.

Listing 11-5 Using Imports to Start Updating the EJB

>     import bea.sna.jcrmgw.gwObject;
>     .
>     .
>     .
>     public interface Trader extends gwObject {
>     .
>     .
>     .

Step 2: Continue with Imports

In Listing 11-6, you perform four imports to update the EJB. The bea.base.io.* import provides the mainframe reader and writer. The traderData import is the specific data view generated from the COBOL copybook. The BigDecimal class handles packed decimal COMP-3 fields. The mainframe reader and writer can generate IOExceptions.

Listing 11-6 Continuing Imports

>     import bea.base.io.*;
>     import traderData;
>     import java.math.BigDecimal;
>     import java.io.IOException;

Step 3: Update EJB with dispatch

In Listing 11-7, the gateway invokes dispatch with a byte array of mainframe EBCDIC data. The code converts the mainframe byte array to a data view using a MainFrameReader. The traderData is the generated data view class.

Listing 11-7 Update EJB with dispatch

>     .
>     .
>     .
>     public byte[] dispatch(byte[] b)
>     	{
>     		traderData td = null;
>     		try {
>     		  td = new traderData(new MainframeReader(b));
>     		} catch(IOException ie) { return b; }
>     				// error protocol required

Step 4: Continue Updating EJB with dispatch

In Listing 11-8, the code uses accessors to get input and set output. The mainframe COMMAREA is updated with the result. Note the use of an accessor to obtain the group level class prior to accessing the member variable. An application level error indicator in the data is used to convey the exception. Updating the data view member results in updates to the mainframe application. Any application exception thrown from the dispatch routine results in an abend returned to the mainframe.

Listing 11-8 Continue Updating EJB with dispatch

>     try {
>     	TradeResult tr = buy(td.getTraderRecord().getCustomer()
>     		,td.getTraderRecord().getSymbol()
>     		,td.getTraderRecord().getShares().intValue());
>     	td.getTraderRecord().setShares(new
>     			BigDecimal((long)tr.numberTraded));
>     	td.getTraderRecord().setPrice(new
>     			BigDecimal((long)tr.priceSoldAt));
>     }catch(ProcessingErrorException pe)
>     	td.getTraderRecord().setSymbol("*ERROR");}

Step 5: Finish Updating EJB with dispatch

In Listing 11-9, the code converts the data view back into a byte array to be returned to the mainframe using a MainframeWriter. The MainframeWriter and data view handle conversions. Note that the dispatch function takes a byte array and returns a byte array. This means when you set up an initial configuration, you can stub dispatch as an echo function.

Listing 11-9 Finish Updating EJB with dispatch

>     try {
>     		return td.toByteArray(new MainframeWriter());
>     	}	catch(IOException ie) {return b; }
>     					// error protocol required
>     }

Task 3: Update the JAM Configurations

Update the jcrmgw.cfg file with the service name shown in Listing 11-10. The Java gateway must be restarted for new services to take effect.

Listing 11-10 Update the jcrmgw.cfg File with Service Name

>     *JC_LOCAL_SERVICES
>     statelessSession.TraderHome					RNAME="DPL1SVR"

Task 4: Deploy Your Application

Use the build function supplied with WebLogic Server to build the basic statelessSession example. The EJB is saved in /myserver/ejb_basic_statelessSession.jar. To deploy the EJB, either use the hot deploy feature of the WebLogic Server console, or add an entry to deploy the jar file in the weblogic.ejb.deploy property in the weblogic.prperties file.

To run the client, follow the instructions in the WebLogic Server documentation.

Warning: Data view classes are not included in the jar file using the default script. You must either add traderData*.class entries to the jar file, or copy the entries to another location on the CLASSPATH. The EJB does not deploy if the traderData classes cannot be found.

Task 5: Use the Application

Listing 11-11 shows the inbound mainframe request for a "buy" transaction executed by the traderBean. If the previous tasks have been performed correctly, the result should look similar to this listing.

Listing 11-11 Inbound Mainframe Request

>     Thu Feb 17 15:31:10 CST 2000:<I> <EJB> EJB home interface: 'examples.ejb.basic.statelessSession.TraderHome' deployed bound to the JNDI name: 'statelessSession.TraderHome'

>     Thu Feb 17 15:31:10 CST 2000:<I> <EJB> 0 EJBs were deployed using .ser files.

>     Thu Feb 17 15:31:10 CST 2000:<I> <EJB> 1 EJBs were deployed using .jar files.
>     .
>     .
>     .

>     **** Inbound Mainframe Request ****

>     buy (JEFF TESTER, WEBL, 150)

>     Executing stmt: insert into tradingorders (account, stockSymbol, shares, price) VALUES ('JEFF TESTER','WEBL',150,10.0)

Sample COBOL Program to Write to Temporary Storage Queue

The simple program shown in Listing 11-12 writes the contents of the COMMAREA to a temporary storage queue. This type of simple mainframe program is useful for testing, demonstrations, and new application development.

Listing 11-12 COBOL Program for DPL1CLT

>     IDENTIFICATION DIVISION.
>     	PROGRAM-ID.    DPL1CLT.
>     	INSTALLATION.
>     	DATE-COMPILED.
>     	ENVIRONMENT DIVISION.
>     	DATA DIVISION.
>     	WORKING-STORAGE SECTION.
>     	01  STUFF.
>     		COPY INBOUND.
>     	PROCEDURE DIVISION.
>     	MAINLINE SECTION.
>     		MOVE 'JEFF TESTER' TO CUSTOMER
>     		MOVE 'WEBL'        TO SYMBOL
>     		MOVE ZEROS         TO PRICE
>     		MOVE +150          TO SHARES
>     		EXEC CICS LINK
>     			PROGRAM('DPL1SVR')
>     			COMMAREA(STUFF)
>     		END-EXEC.
>     		EXEC CICS WRITEQ TS
>     			QUEUE('TRADER')
>     			FROM(STUFF)
>     		END-EXEC.
>     		EXEC CICS RETURN
>     		END-EXEC.

Note: Some applications have extremely large COMMAREA copybooks. Distributed applications can be very sensitive to large amounts of data being transferred between components. If the Java application requires only a few fields from a large copybook, it would be advantageous to preface the target application with a simpler program passing only the data required.

Copyright © 2000 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.