Enhancing an Existing Servlet to Originate a Mainframe Request

 

This scenario illustrates how to enhance an existing servlet to originate a mainframe request. Use the WebLogic Server survey servlet and add a mainframe request to the post routine. You add the code to the postprocessing routine, creating a mainframe buffer and sending it CICS where an application writes the buffer to a temporary storage queue and returns.

This scenario is based on the general procedures presented in "Developing Java Applications." It gives 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 develop a multi-service application:

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

• Task 2: Update the Survey Servlet Using the Generated Class

• Task 3: Update the JAM Configurations and Update WebLogic Server Properties

• Task 4: Deploy Your Application

• Task 5: Use the Application

The following section describes the sample program required for the mainframe request application:

• Sample COBOL Program to Write to Temporary Storage Queue

 

---

Task 1: Use eGen COBOL to Create a Base Class

You should have successfully created the survey servlet prior to attempting the enhancement 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 survey.cbl, shown in Listing 10-1.

Listing 10-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 COBOL Script

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

Listing 10-2 Basic eGen COBOL 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

In Listing 10-3, you invoke the eGen COBOL code generator to create the base class that is then compiled. This makes class files (*.class) available for servlet customizing. The surveyData.java is the data view 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 10-3 Generating the Java Source Code

---

egencobol survey.egen
ls  *.java
SurveyServlet.java surveyData.java SurveyClient.java
javac *.java		

---

Step 3: Review the Java Source Code

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

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

getSurveyRecord().getSurveyIde()

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

Listing 10-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 2: Update the Survey Servlet Using the Generated Class

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

Step 1: Start with Imports

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

Listing 10-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 10-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 10-6 Adding New Data Members

---

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

---

Step 3: Update doPost with Mainframe Request

In Listing 10-7, add the local variables for form data and data view in doPost. The data view is the minimum requirement. The values entry has been declared previously.

Listing 10-7 Update doPost with Mainframe Request

---

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

---

Step 4: Continue Updating doPost by Extracting Form Data

In Listing 10-8, the code loops through the form using data view 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 10-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 10-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 data view that contains any response.

Listing 10-9 Continue Updating doPost

---

egc.doSurvey(sd);

---

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

Listing 10-10 Mainframe Exceptions

---

snaException
	jcrmConfigurationException
	snaCallFailureException
	snaLinkNotFoundException
	snaNoSessionAvailableException
	snaRequestTimeoutException
	snaServiceNotReadyException

---

 

---

Task 3: Update the JAM Configurations and Update WebLogic Server Properties

In Listing 10-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 10-11 Update the jcrmgw.cfg File with Service Name

---

doSurvey       RDOM="CICS410"                                        															 	               RNAME="DPLSURVY"

---

Update the weblogic.properties file with the entries shown in Listing 10-12.

Listing 10-12 Update WebLogic Server Properties File

---

weblogic.httpd.register.survey=examples.servlets.SurveyServlet

---

 

---

Task 4: Deploy Your Application

At this point, you have a basic form capable of making a maintenance request. The following are standard WebLogic Server servlet deployment steps:

1. If required, compile *.java files.

2. Copy class files to the WebLogic Server servlet directory.

3. Copy HTML form to WebLogic Server document directory.

4. If required, add URL registration to weblogic.properties file.

5. If required, restart WebLogic Server.

6. Test the result with your browser pointed at the registered URL.

 

---

Task 5: Use the Application

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

Figure 10-1 Enhanced Survey Servlet Display

 

---

Sample COBOL Program to Write to Temporary Storage Queue

The simple program shown in Listing 10-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 10-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.