bea.com | products | dev2dev | support | askBEA |
|
e-docs > WebLogic Java Adapter for Mainframe > Programming Guide > DataView Programming Reference |
Programming Guide |
DataView Programming Reference
This section provides the rules that allow you to identify what form a generated Java class takes from a given COBOL copybook processed by the eGen Application Generator (eGen utility). An understanding of the rules facilitates a programmer's ability to correctly code any custom programs that make use of the generated classes.
The eGen utility maps a COBOL copybook into a Java class. The COBOL copybook contains a data record description. The eGen utility derives the generated Java class from the com.bea.dmd.dataview.DataView class (later referred to as DataView), which is provided on your WebLogic JAM product CD-ROM in the jam.jar file.
This section discusses data mapping rules in the following topics:
You should find the COBOL terms in this section easy to understand; however, you may need to use a COBOL reference book or discuss the terms with a COBOL programmer. Also, you can process a copybook with the eGen utility and examine the generated Java code in order to understand the mapping.
Field Name Mapping Rules
When you process a COBOL copybook containing field names, they are mapped to Java names by the eGen utility. All alphabetic characters are mapped to lower case, except in the following two cases.
Table A-1 lists some mapping examples.
Field Type Mappings
When you process a COBOL copybook, the data types of fields are mapped to Java data types. The mapping is performed by the eGen utility according to the following rules:
Group Field Accessors
Each nested group in a COBOL copybook is mapped to a corresponding DataView subclass. The generated subclasses are nested exactly as the COBOL groups in the copybook. In addition, the eGen utility generates a private instance variable of this class type and a get accessor.
For example, the following copybook:
10 MY-RECORD.
20 MY-GRP.
30 ALNUM-FIELD PIC X(20).
Produces code similar to the following:
public MyGrp2V getMyGrp();
public static class MyGrp2V extends DataView
{
// Class definition
}
Elementary Field Accessors
Each elementary field is mapped to a private instance variable within the generated DataView subclass. Access to this variable is accomplished by two accessors that are generated (set and get).
These accessors have the following forms:
public void setFieldName(FieldType value);
public FieldType getFieldName();
Where:
For example, the following copybook:
10 MY-RECORD.
20 NUMERIC-FIELD PIC S9(5).
20 ALNUM-FIELD PIC X(20).
Produces the accessors:
public void setNumericField(int value);
public int getNumericField();
public void setAlnumField(String value);
public String getAlnumField();
Array Field Accessors
Array fields are handled according to the field accessor rules described in Group Field Accessors and Elementary Field Accessors, with the addition that each accessor takes an additional int argument that specifies which array entry is to be accessed, for example:
public void setFieldName(int index, FieldType value);
public FieldType getFieldName(int index);
Array fields specified with the DEPENDING ON clause are handled the same as fixed-size arrays with the following special rules:
Fields with REDEFINES Clauses
Fields that participate in a REDEFINES set are handled as a unit. A private byte[] variable is declared to hold the underlying mainframe data, as well as a private DataView variable. Each of the redefined fields has an accessor or accessors. These accessors take more CPU overhead than the normal accessors because they perform conversions to and from the underlying byte[] data.
For example the copybook:
10 MY-RECORD.
20 INPUT-DATA.
30 INPUT-A PIC X(4).
30 INPUT-B PIC X(4).
20 OUTPUT-DATA REDEFINES INPUT-DATA PIC X(8).
Produces Java code similar to the following:
private byte[] m_redef23;
private DataView m_redef23DV;
public InputDataV getInputData();
public String getOutputData();
public void setOutputData(String value);
public static class InputDataV extends DataView
{
// Class definition.
}
COBOL Data Types
This section summarizes the COBOL data types supported by WebLogic JAM software. Table A-3 lists the COBOL data item definitions recognized by the eGen utility. Table A-4 lists the syntactical features and data types recognized by the eGen utility. If a COBOL feature is unsupported and it is not listed as ignored in the table, an error message is generated.
Other Access Methods for Generated DataView Classes
WebLogic JAM allows you to access DataView classes through several methods as described in the following sections:
Mainframe Access to DataView Classes
This section describes how mainframe format data may be moved into and out of DataView classes. The eGen Application Generator writes this code for you, so this information is provided as reference.
Mainframe format data may be extracted from a DataView class through the use of the MainframeWriter class. Listing A-1 shows a sample of code that may be used to perform the extraction.
Listing A-1 Sample Code for Extracting Mainframe Format Data from a DataView Class
import com.bea.base.io.MainframeWriter;
import com.bea.dmd.dataview.DataView;
...
/**
* Get mainframe format data from a DataView into a byte[].
*/
byte[] getMainframeData(DataView dv)
{
try
{
MainframeWriter mw = new MainframeWriter();
// To override the DataView's codepage, change the
// above constructor call to something like:
// ...new MainframeWriter("cp1234");
return dv.toByteArray(mw);
}
catch (java.io.IOException e)
{
// Some conversion failure occurred
}
}
If you want to override the codepage provided when the DataView was generated, you may provide another codepage as a String argument to the MainframeWriter constructor, as shown in the comment in Listing A-2.
Loading mainframe data into a DataView is a similar process, in this case requiring the use of the MainframeReader class. Listing A-2 shows a sample of code that may be used to perform the load.
Listing A-2 Sample Code for Loading Mainframe Data into a DataView Class
import com.bea.base.io.MainframeReader;
import com.bea.dmd.dataview.DataView;
...
/**
* Put a byte[] containing mainframe format data into a DataView.
*/
MyDataView putMainframeData(byte[] buffer)
{
MainframeReader mr = new MainframeReader(buffer);
// To override the DataView's codepage, change the above
// constructor call to something like:
// new MainframeReader("cp1234", buffer);
.
.
.
MyDataView dv;
.
.
.
try
{
// Construct a new DataView with the mainframe data.
dv = new MyDataView(mr);
// Or, to load a pre-existing DataView with mainframe data.
// dv.mainframeLoad(mr);
}
catch (java.io.IOException e)
{
// Some conversion failure occurred.
}
return dv;
}
XML Access to DataView Classes
Facilities are provided to move XML data into and out of DataView classes. These operations are performed through the use of the XmlLoader and XmlUnloader classes.
Listing A-3 shows an example of the code used to load XML data into a DataView.
Listing A-3 Sample Code for Loading XML Data into a DataView
import com.bea.dmd.dataview.DataView;
import com.bea.dmd.dataview.XmlLoader;
...
void loadXmlData(String xml, DataView dv)
{
XmlLoader xl = new XmlLoader();
try
{
// Load the xml. Note that the xml argument may be either
// a String or a org.w3c.dom.Element object.
xl.load(xml, dv);
}
catch (Exception e)
{
// Some conversion error occurred.
}
}
Listing A-4 shows an example of the code used to unload a DataView into XML.
Listing A-4 Sample Code for Unloading a DataView into XML
import com.bea.dmd.dataview.DataView;
import com.bea.dmd.dataview.XmlUnloader;
...
String unloadXmlData(DataView dv)
{
XmlUnloader xu = new XmlUnloader();
try
{
String xml = xu.unload(dv);
return xml;
}
catch (Exception e)
{
// Some conversion error occurred.
}
}
Hashtable Access to DataView Classes
WebLogic JAM also provides facilities to load and unload DataView objects using Hashtable objects. Hashtable objects are most often used to move data from one DataView to another similar DataView.
When DataView fields are moved into Hashtables, each field is given a key that is a string reflecting the location of the field within the original copybook data structure. Listing A-5 shows a sample of a COBOL Copybook.
Listing A-5 Sample emprec.cpy COBOL Copybook
1 *------------------------------------------------------
2 * emprec.cpy
3 * An employee record.
4 *------------------------------------------------------
5
6 02 emp-record.
7
8 04 emp-ssn pic 9(9) comp-3.
9
10 04 emp-name.
11 06 emp-name-last pic x(15).
12 06 emp-name-first pic x(15).
13 06 emp-name-mi pic x.
14
15 04 emp-addr.
16 06 emp-addr-street pic x(30).
17 06 emp-addr-st pic x(2).
18 06 emp-addr-zip pic x(9).
19
20 * End
The fields for the COBOL Copybook in Listing A-5 are stored into a Hashtable as shown in Table A-5.
Table A-5 COBOL Copybook Hashtable
Code for Unloading and Loading Hashtables Following is an example of the code used to unload a DataView into a Hashtable. Hashtable ht = new HashtableUnloader().unload(dv); Following is an example of the code used to load a Hashtable into an existing DataView. new HashtableLoader().load(dv); Rules for Unloading and Loading Hashtables The basic rules of Hashtable unloading are:
The basic rules of Hashtable loading are:
Name Translator Interface Facility
A name translator interface facility is available to provide Hashtable name mappings. Both HashtableLoader and HashtableUnloader provide a constructor that accepts an argument of type com.bea.dmd.dataview.NameTranslator. Table A-6 lists the descriptions of the public interface methods that must be implemented.
Table A-6 Name Translator Interface
You can write classes that implement this interface for your application. These implementations are used to translate the key strings before the Hashtable is accessed. Following are some useful implementations that are included in the WebLogic JAM library:
The HashtableLoader, HashtableUnloader, and the various name translator classes are included in the "com.bea.dmd.dataview" package.
Known Limitations of WebLogic JAM working with COBOL Copybooks
Following are some of the known limitations of this version of the WebLogic JAM product.