BEA Home | Events | Solutions | Partners | Products | Services | Download | Developer Center | WebSUPPORT
JAM Documentation | JAM Scenarios Guide | 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. Practical examples for using JAM tools are presented as tasks with step-by-step procedures. In this scenario, a new application is developed and existing applications are updated. 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.

Action List

The following table lists the actions to update an existing EJB to service a mainframe request

| Your action... | Refer to...
--- | --- | ---
1 | Verify that prerequisite tasks have been completed. | Prerequisites
2 | Use eGen COBOL to create a base java class. | Task 1: Use eGen COBOL Code Generator to Generate a Base Class
3 | Update the trader interface using the generated java class. | Task 2: Update the Trader Interface Using the Generated Class
4 | Update the JAM configurations. | Task 3: Update the JAM Configurations
5 | Deploy your application. | Task 4: Deploy Your Application
6 | Use the application. | Task 5: Use the Application

:

Prerequisites

Before you begin, ensure that the following prerequisites have been completed.

| Your action... | Refer to...
--- | --- | ---
1 | Verify that the required software has been properly installed. | BEA WebLogic Server documentation, BEA WebLogic Java Adapter for Mainframe Installation Guide
2 | Verify that the environment and the software components have been properly configured. | BEA WebLogic Java Adapter for Mainframe Configuration and Administration Guide
3 | Verify the appropriate mainframe application is available. | Your mainframe system administrator
4 | Review the steps to develop a java application. | BEA WebLogic Java Adapter for Mainframe Programming Guide
5 | Create the survey servlet prior to attempting the enhancement discussed in this scenario. | BEA WebLogic Java Adapter for Mainframe Programming Guide

Update an Existing EJB to Service a Mainframe Request

To update an existing EJB to service a mainframe request, complete the following tasks.

Task 1: Use eGen COBOL Code Generator to Generate a Base Class

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.

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

Listing 3-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 3-2 generates the DataView traderData from the copybook named trader.cbl. The script is then saved as inboundEJB.egen.

Listing 3-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 3-3, the eGen COBOL Code Generator is invoked to compile trader.cbl copybook and inboundEJB.egen. The traderData.java is the DataView 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 3-3 Generating the Java Source Code

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

Step 3: Review the Java Source Code

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 based 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 3-4, the output from the grep command shows the relationships in reverse order, for example:

>     getTraderRecord().getPrice()

This relationship is illustrated in the actual code example shown in Listing 3-4.

Listing 3-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

Update the WebLogic Server trader example basic statelessSession bean.

Step 1: Start with Import

In Listing 3-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 3-5 Using Imports to Start Updating the EJB

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

Step 2: Continue with Imports

The code in Listing 3-6 performs four imports to update the EJB. The bea.base.io.* import provides the mainframe reader and writer. The traderData import is the specific DataView generated from the COBOL copybook. The BigDecimal class handles packed decimal COMP-3 fields. The mainframe reader and writer can generate IOExceptions.

Listing 3-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 3-7, the gateway invokes dispatch with a byte array of mainframe EBCDIC data. The code converts the mainframe byte array to a DataView using a MainFrameReader. The traderData is the generated DataView class.

Listing 3-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 3-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 DataView 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 3-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

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

Listing 3-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 3-10. The JAM gateway must be restarted for new services to take effect.

Listing 3-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 statelessSession example. The EJB is saved in /myserver/ejb_basic_statelessSession.jar. Deploy the EJB using the WebLogic Server Console.

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

Warning: DataView 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 3-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 3-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 3-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 3-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 © 2001 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.