Generating a Stand-alone Client Application

 

This type of application produces simple Java classes that perform the appropriate conversions of data records sent between Java and the mainframe, but without all of the EJB support methods. These classes are intended to be lower-level components upon which more complicated applications are built.

 

---

Action List

Before you build a stand-alone application, see the following action list and refer to the appropriate information sources.

	Your action...	Refer to...
1	Complete all prerequisite tasks.	Prerequisites
2	Review the general steps for building a Java application	Generating a Java Application with the eGen COBOL Code Generator
3	Review an example of a script for generating a stand-alone Java application	Components of an eGen COBOL Stand-alone Application Script
4	Review script processing and sample script commands	Processing a Script
5	Review the generated files	Working with Generated Files
6	Customize the application	Customizing a Stand-Alone Java Application
7	Proceed to the next set of instructions.	What Do I Do Next?

 

 

---

Prerequisites

Before you start programming your stand-alone application, 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

 
 

 

---

Components of an eGen COBOL Stand-alone Application Script

The following listing shows the contents of a complete script for defining a stand-alone client class with multiple services.

Listing 5-1 Sample Stand-Alone Client Class Script

1  #--------------------------------------------------------
2  # empclass.egen
3  #	JAM script for an employee record.
4  #
5  # $Id: empclass.egen, v 1.1 2000/01/21 23:20:40
6  #-------------------------------------------------------------
7 
8  # DataViews (typed data records)
9
10 view sample.EmployeeRecord (Comment 1)
11	from emprec.cpy
12
13  # Services
14
15  service sampleCreate (Comment 2)
16	accepts EmployeeRecord
17	returns EmployeeRecord
18
19  service sampleRead (Comment 2)
20	accepts EmployeeRecord
21	returns EmployeeRecord
22
23  service sampleUpdate (Comment 2)
24	accepts EmployeeRecord
25	returns EmployeeRecord
26
27  service sampleDelete (Comment 2)
28	accepts EmployeeRecord
29	returns EmployeeRecord
30
31  # Clients and servers
32
33  client class sample.SampleClass (Comment 3)
34  {
35	method newEmployee (Comment 4)
36		is service sampleCreate
37
38	method readEmployee (Comment 4)
39		is service sampleRead
40  }
41
42  # End

Table 5-1 refers to the numbered comments in Listing 5-1.

Table 5-1 Script Comments

Comment 1	Defines a DataView class, specifying its corresponding copybook source file and its package name.
Comment 2	Defines a service function and its input and output parameter types.
Comment 3	Defines a simple client class.
Comment 4	Defines a client class method and its parameter types.

 

---

Processing a Script

Issue the following command to process the script.

Listing 5-2 Sample Script Process Command

egencobol empclass.egen
emprec.cpy, Lines: 21, Errors: 0, warnings: 0
Generating sample.EmployeeRecord...
Generating group emp-name
Generating group emp-addr
Generating SampleClass...

 

---

Working with Generated Files

This script command generates the following files.

Table 5-2 Sample Script Generated Files

File	Content
SampleClass.java	Source for the sample class.
EmployeeRecord.java	Source for the DataView class.

SampleClass.java Source File

The following listing contains the generated SampleClass.java source file.

Listing 5-3 Sample SampleClass.java Source File

// SampleClass.java
//
// Client class generated by eGenCobol on 24-Jan-2000.

package sample;(Comment 1)

// Imports

import com.bea.jam.egen.EgenClient;
...

/* Mainframe client class. */

public class SampleClass (Comment 2)
	extends EgenClient
{
	// newEmployee
	public EmployeeRecord newEmployee (EmployeeRecord commarea)
		throws IOException, snaException (Comment 3)
	{
		...
	}

	// readEmployee
	public EmployeeRecord readEmployee (EmployeeRecord commarea)
		throws IOException, snaException (Comment 3)
	{
		...
	}
}

// End SampleClass.java

Table 5-3 refers to the numbered comments in Listing 5-3.

Table 5-3 Script Comments

Comment 1	The package name is defined in the eGen script.
Comment 2	The data record is encapsulated in a class that extends the EgenClient class.
Comment 3	The methods convert a raw COMMAREA into a Java DataView object.

 

---

Customizing a Stand-Alone Java Application

The stand-alone client class model is the simplest JAM code generation model both in terms of the code generated and customizing the generated code.

The following figure illustrates the relationships and inheritance hierarchy between the JAM classes comprising the application.

Figure 5-1 The JAM Client EJB Class Hierarchy

 

The generated Java code for a client class application is a class that inherits class EgenClient. The EgenClient class is provided in the JAM distribution jar file. This base class, illustrated in the following listing provides the basic framework for a client to the jcrmgw. It provides the required methods for accessing the gateway.

Listing 5-4 Generated EgenClient.java Class

//==========================================================
// EgenClient.java
//	Basic functionality for clients of the jcrmgw
//
//---------------------------------------------------------------

package com.bea.jam.egen;

public class EgenClient
 {

	public byte[] callService(String service, byte[] in)
		throws snaException, IOException
	{
		// make a mainframe request through the gateway.
		...
	}
}

// End egenClientBean.java

The generated class, illustrated in the following listing, adds the methods specific to the users application

Listing 5-5 Sample SampleClient.java Class

// SampleClass.java
//
// Client class generated by eGenCobol on 02-Feb-00.
//

package sample;

// Imports
//
import java.io.IOException;
import com.bea.jam.egen.EgenClient;
import com.bea.sna.jcrmgw.snaException;
import com.bea.base.io.MainframeWriter;
import com.bea.base.io.MainframeReader;

/**
 * Mainframe client class.
 */
public class SampleClass extends EgenClient
 {
	// newEmployee
	//
	public EmployeeRecord newEmployee(EmployeeRecord commarea)
		throws IOException, snaException
	{
	  // Make the remote call.
	  //
	  byte[]  inputBuffer = commarea.toByteArray(new
		MainframeWriter());
	  byte[] rawResult = callService("sampleCreate",
		inputBuffer);
	  EmployeeRecord   result =
			new EmployeeRecord(new
			   MainframeReader(rawResult));
	  return result;
	}

	// readEmployee
	//
	public EmployeeRecord readEmployee(EmployeeRecord commarea)
		throws IOException, snaException
	{
	  // Make the remote call.
	  //
	  byte[]  inputBuffer = commarea.toButeArray(new
		MainframeWriter());
	  byte[] rawResult = callService("sampleRead", inputBuffer);
	  EmployeeRecord  result =
		new EmployeeRecord(new MainframeReader(rawResult)):
         return result
	}
]

// End SampleClass.java

Your class, which extends or uses the SampleClient class, simply overrides or calls these methods to provide additional business logic, modifying the contents of the DataView. Your class may also add additional methods, if desired.

The following listing shows an example ExtSampleClass class that extends the generated SampleClient class.

Listing 5-6 Sample ExtSampleClient.java Contents

// ExtSampleClient.java
//

package sample;

// Imports
//
import java.io.IOException;
import com.bea.jam.egen.egenClientBean;
import com.bea.sna.jcrmgw.snaException;
import com.bea.base.io.MainframeWriter;
import com.bea.base.io.MainframeReader;

/**
 * Extended Sample Class
 */
public class ExtSampleClient extends SampleClass
{
	// deleteEmployee
	//
	public EmployeeRecord deleteEmployee(EmployeeRecord
		commarea)
	throws IOException, snaException
	{
	  EmployeeRecord erec=(EmployeeRecord) in;
	  if (!isSsnValid(erec.getEmpRecord().getEmpSsn()))
	{
	  // The SSN is not valid.
	  throw new Error)"Invalid Social Security Number:"+
		erec.getEmpRecord().getEmpSsm());
	}

	// Make the remote call.
	//
	return super.deleteEmployee(commarea);
	}

	//updateEmployee
	//
	public EmployeeRecord updateEmployee(EmployeeRecord
		commarea)
		throws IOException, snaException
	{
	  EmployeeRecord erec = (EmployeeRecord) in;
	  if (!isSsnValid(erec.getEmpRecord().getEmpSsn()))
	  {
		The SSN is not valid.
		throw new Error ("Invalid Social Security Number:"+
		  erec.getEmpRecord().getEmpSsn());
	   }

		// Make the remote call.
		//
		return super.updateEmployee(commarea);
	}

	// readEmployee
	//
	public EmployeeRecord readEmployee(EmployeeRecord commarea)
		throws IOException, snaException
	{
		EmployeeRecord erec = )EmployeeRecord)in;
		if (!isSsnValid(erec.getEmpRecord().getEmpSsn()))
		{
			// The SSN is not valid.
			throw new Error("Invalid Social Security 
			Number:"+
				erec.getEmpRecord().getEmpSsn());
		}

		// Make the remote call.
		//
		return super.readEmployee(commarea);
	}

	//newEmployee
	//
	public EmployeeRecord newEmployee(EmployeeRecord commarea)
		throws IOException, snaException
	{
	  EmployeeRecord erec = (EmployeeRecord) in;
	  if (!isSsnValid(erec.getEmpRecord().getEmpSsn()))
	  {
		// The SSN is not valid.
		throw new Error("Invalid Social Security Number:"+
			erec.getEmpRecord().getEmpSsn());
	  }

         // Make the remote call.
         //
         return super.newEmployee(commarea);
	}

// Private functions

	/******************************************************
	* Validates an SSN field.
	*/

	private boolean isSsnValid(BigDecimal ssn)
	{
	  if (ssn.longValue() < 100000000)
	  {
	    // Ops, should not have a leading zero.
	    return false;
	  }

         return (true);
	}
]

// END ExtSampleClient.java
	

Once it has been written, the ExtSampleClient class and the other Java source files must be compiled and placed on to your CLASSPATH.

 

---

What Do I Do Next?

Refer to BEA Java Adapter for Mainframe Scenarios for detailed examples of some of the application models discussed in this guide.