Enhancing an Existing Servlet to Originate a Mainframe Request

 

This scenario illustrates how to enhance an existing servlet to originate a mainframe request using WebLogic Server. 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 develop a multi-service data entry servlet

	Your action...	Refer to...
1	Verify that the prerequisite tasks have been completed.	Prerequisites
2	Create the survey servlet.	Task 1: Obtain the survey Servlet
3	Use eGen COBOL Code Generator to create an application.	Task 2: Use eGen COBOL Code Generator to Generate a Base Class
4	Update the survey servlet using the generated class.	Task 3: Update the survey Servlet Using the Generated Class
5	Update the JAM configurations and update the WebLogic Server configuration.	Task 4: Update the JAM Configurations and Update WebLogic Server web.xml File
6	Deploy your application.	Task 5: Deploy Your Application
7	Use the application.	Task 6: Use the Application

:

 

---

Prerequisites

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

	Prerequisites	Source
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 Server documentation, 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

 

---

Enhancing a Multi-Service Data Entry Servlet

To enhance a multi-service data entry servlet, complete the following tasks.

Task 1: Obtain the survey Servlet

Use the WebLogic Server survey servlet and add a mainframe request to the post routine. In future steps, you will add the code to the postprocessing routine to create a mainframe buffer and send it to CICS where an application writes the buffer to a temporary storage queue and returns.

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

Identify the mainframe application and obtain its COBOL copybook, usually a CICS DFHCOMAREA or the user data portion of an IMS queue record layout. The copybook's name in this discussion is survey.cbl, shown in Listing 2-1.

Listing 2-1 Mainframe Application COBOL Copybook survey.cbl

02  survey-record.
       05  survey-ide       pic x(12).
       05  survey-emp       pic x(12).
       05  survey-cmt       pic x(256). 

Step 1: Prepare eGen Script

In Listing 2-2, both the DataView surveyData and the client class SurveyClient are generated from the copybook survey.cbl.

Listing 2-2 Basic eGen script

view surveyData from survey.cbl
service doSurvey accepts surveyData returns surveyData
client class SurveyClient
{
       method doSurvey is service doSurvey
}

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

Step 2: Generate the Java Source Code

As shown in Listing 2-3, invoke the eGen COBOL Code Generator to create the base class. This action makes java class files (*java.class) available for servlet customizing. The surveyData.java is the DataView object for survey.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 2-3 Generating the Java Source Code

>egencobol survey.egen
>ls  *.java
SurveyServlet.java surveyData.java SurveyClient.java
>tasks	

Step 3: Review the Java Source Code

Obtain a list of accessors for later use. Review the eGen COBOL output to become familiar with the information presented in this section.

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

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

getSurveyRecord().getSurveyIde()

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

Listing 2-4 Review the Java Source Code

grep get surveyData.java
       public String        getSurveyIde()
       public String        getSurveyEmp()
       public String        getSurveyCmt()
       public SurveyRecordV getSurveyRecord()
grep set surveyData.java
       public void          setSurveyIde(String value)
       public void          setSurveyEmp(String value)
       public void          setSurveyCmt(String value)

Task 3: Update the survey Servlet Using the Generated Class

The preferred customization method is to derive a custom class from the generated application. You are now ready to update the WebLogic Server example survey servlet.

Step 1: Start with Imports

In Listing 2-5, bea.jam.egen provides the eGen COBOL client and DataView base. The surveyData is the specific DataView generated from the COBOL copybook. SurveyClient is the generated client class.

Listing 2-5 Using Imports to Start Creating the Custom Application

import bea.jam.egen.*;
import surveyData;
import SurveyClient;

Step 2: Add New Data Members

In Listing 2-6, the code adds a private member for SurveyClient, which can be created in the init() function because there is no state for it. The init() is then updated for a new member. The SurveyClient obtains a connection factory when created. A single instance of SurveyClient can serve all requests.

Listing 2-6 Adding New Data Members

init ()

//Add private member for SurveyClient 
private SurveyClient egc = null;				
//Update init() for new member
egc = new SurveyClient();

Step 3: Update doPost with Mainframe Request

Listing 2-7 shows the local variables for form data and DataView in doPost. The DataView is the minimum requirement. The values entry has been declared previously.

Listing 2-7 Update doPost with Mainframe Request

values = req.getParameterNames();
surveyData        sd  = new surveyData();

Step 4: Continue Updating doPost by Extracting Form Data

In Listing 2-8, the code loops through the form using DataView accessors to set data. The submit field is skipped. The surveyData accessors are used to set values for ide, employee, and comment. The surveyData object represents the mainframe message buffer that ultimately is used to make the request. (The surveyData class was generated using the eGen COBOL Code Generator with the mainframe COBOL copybook.)

Listing 2-8 Continue Updating doPost

while(values.hasMoreElements())
{
       String name = (String)values.nextElement();
       String value = req.getParameterValues(name)[0];
              if(name.compareTo("submit") != 0) 
              {
                if(name.compareTo("ide") == 0)
                     sd.getSurveyRecord().setSurveyIde(value);
                else if(name.compareTo("employee") == 0)
                     sd.getSurveyRecord().setSurveyEmp(value);
                else if(name.compareTo("comment") == 0)
                     sd.getSurveyRecord().setSurveyCmt(value);
              }
}

Step 5: Continue Updating doPost by Calling Mainframe Service

In Listing 2-9, the code shows how to make the mainframe request. The doSurvey command blocks until a response is provided. The call can throw either IOException or snaException. In this listing, doSurvey is in a try block that catches IOException. The doSurvey command returns a DataView that contains a response.

Listing 2-9 Continue Updating doPost

egc.doSurvey(sd);

The snaException is the base class for several exceptions, shown in Listing 2-10. A time-out is the most likely error an application would get.

Listing 2-10 Mainframe Exceptions

snaException
       jcrmConfigurationException
       snaCallFailureException
       snaLinkNotFoundException
       snaNoSessionAvailableException
       snaRequestTimeoutException
       snaServiceNotReadyException

Task 4: Update the JAM Configurations and Update WebLogic Server web.xml File

In Listing 2-11, update the jcrmgw.cfg file with the remote service name doSurvey. The Java gateway must be restarted for new services to take effect. The RNAME DPLSURVY is a CICS program that exists on the mainframe.

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

doSurvey       RDOM="CICS410"                                        															 	               RNAME="DPLSURVY"

Update the WebLogic Server web.xml file with the entries shown in Listing 2-12.

Listing 2-12 Update WebLogic Server web.xmlFile

<?xml version="1.0" ?> 
<!DOCTYPE web-app (View Source for full doctype...)> 
- <web-app> 
- <servlet> 
<servlet-name>survey</servlet-name> 
<servlet-class>examples.servlets.SurveyServlet</servlet-class> 
</servlet> 
- <servlet-mapping> 
<servlet-name>survey</servlet-name> 
<url-pattern>survey</url-pattern> 
</servlet-mapping> 
</web-app>

Task 5: Deploy Your Application

At this point, you have a basic form capable of making a maintenance request. For a complete description of how to deploy a servlet, refer to the WebLogic Server documentation. For evaluation purposes, refer to the BEA WebLogic Server Quick Start Guide.

Task 6: Use the Application

Figure 2-1 shows the HTML display of the enhanced application.

Figure 2-1 Enhanced Survey Servlet Display

 
 
 

 

---

Sample COBOL Program to Write to Temporary Storage Queue

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

Listing 2-13 COBOL Program for DPLSURVY

IDENTIFICATION DIVISION.
       PROGRAM-ID.    DPLSURVY.
       INSTALLATION.
       DATE-COMPILED.
       ENVIRONMENT DIVISION.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01  TSQ-DATA-LENGTH         PIC S9(4) COMP VALUE ZERO.
       01  TSQ-ID                  PIC X(8) VALUE SPACES.
       LINKAGE SECTION.
       01  DFHCOMMAREA.
              COPY SURVEY.
       PROCEDURE DIVISION.
       MAINLINE SECTION.
              MOVE 'SURVEY' TO TSQ-NAME
              MOVE LENGTH OF SURVEY-RECORD
              TO  TSQ-DATA-LENGTH
              EXEC CICS WRITEQ TS
                     QUEUE(TSQ-ID)
                     FROM(SURVEY-RECORD)
                     LENGTH(TSQ-DATA-LENGTH)
              END-EXEC.
              EXEC CICS RETURN
              END-EXEC.
              EXIT.

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 front-end the target application with a simpler program passing only the data required.