|
|
|
|
|
|
Programming Reference
This section provides the rules that enable you to identify what form a generated Java class takes from a given COBOL copybook processed by the eGen COBOL tool. This facilitates your being able to correctly code any custom programs that make use of the generated classes.
The eGen COBOL tool maps a COBOL copybook into a Java class. The COBOL copybook contains a data record description. The eGen COBOL tool derives the generated Java class from the com.bea.dmd.dataview.DataView class (later referred to as DataView), which is provided on your BEA WebLogic Java Adapter for Mainframe (JAM) product CD-ROM in the jam.jar file.
This section gives you data mapping rules. The following topics are discussed:
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 COBOL tool and examine the produced 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. This is performed by the eGen COBOL tool according to the following rules:
Table 7-1 lists some mapping examples.
|
COBOL Field Name |
Java Base Name |
Sample Accessor Name |
|---|---|---|
|
EMP-REC |
empRec |
setEmpRec |
|
500-REC-CNT |
500RecCnt |
set500RecCnt |
Field Type Mappings
When you process a COBOL copybook with field types, the field types are mapped to Java field types. This is performed by the eGen COBOL tool according to the following rules:
|
Number of Digits |
Java Type |
|---|---|
|
<= 4 |
short |
|
> 4 and <= 9 |
int |
|
> 9 and <= 18 |
long |
|
> 18 |
BigDecimal |
Group Field Accessors
Each nested group field 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 COBOL tool 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 other rules in this section, 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 JAM software. Table 7-3 lists the COBOL data item definitions recognized by the eGen COBOL tool. Table 7-4 lists the syntactical features and data types recognized by the eGen COBOL tool. If a COBOL feature is unsupported, an error message is generated, unless it is listed as ignored in a table.
|
COBOL Feature |
Support |
|---|---|
|
IDENTIFICATION DIVISION |
unsupported |
|
ENVIRONMENT DIVISION |
unsupported |
|
DATA DIVISION |
partially supported |
|
WORKING-STORAGE SECTION |
partially supported |
|
Data record definition |
supported |
|
PROCEDURE DIVISION |
unsupported |
|
COPY |
unsupported |
|
COPY REPLACING |
unsupported |
|
EJECT, SKIP1, SKIP2, SKIP3 |
supported |
|
COBOL Type |
Java Type |
|---|---|
|
COMP, COMP-4, BINARY (integer) |
short/int/long |
|
COMP, COMP-4, BINARY (fixed) |
BigDecimal |
|
COMP-3, PACKED-DECIMAL |
BigDecimal |
|
COMP-5 |
not supported |
|
COMP-X |
not supported |
|
DISPLAY numeric (zoned) |
BigDecimal |
|
BLANK WHEN ZERO (zoned) |
String |
|
SIGN IS LEADING (zoned) |
String |
|
SIGN IS LEADING SEPARATE (zoned) |
String |
|
SIGN IS TRAILING (zoned) |
String |
|
SIGN IS TRAILING SEPARATE (zoned) |
String |
|
edited numeric |
String |
|
COMP-1, COMP-2 (float) |
not supported |
|
edited float numeric |
String |
|
DISPLAY (alphanumeric) |
String |
|
edited alphanumeric |
String |
|
INDEX |
int |
|
POINTER |
int |
|
PROCEDURE-POINTER |
not supported |
|
JUSTIFIED RIGHT |
not supported (ignored) |
|
SYNCHRONIZED |
not supported (ignored) |
|
REDEFINES |
supported |
|
66 RENAMES |
not supported |
|
66 RENAMES THRU |
not supported |
|
77 level |
supported |
|
88 level (condition) |
not supported (ignored) |
|
group record |
inner class |
|
OCCURS (fixed array) |
array |
|
OCCURS DEPENDING (variable-length array) |
array |
|
OCCURS INDEXED BY |
not supported (ignored) |
|
OCCURS KEY IS |
not supported (ignored) |
Other Access Methods for Generated DataView Classes
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 COBOL tool 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 7-1 shows a sample of code that may be used to perform the extraction.
Listing 7-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 wish 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 7-1.
Loading mainframe data into a DataView is a similar process, in this case requiring the use of the MainframeReader class. Listing 7-2 shows a sample of code that may be used to perform the load.
Listing 7-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 7-3 shows an example of the code to load XML data into a DataView.
Listing 7-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 7-4 shows an example of the code to unload a DataView into XML.
Listing 7-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
JAM also provides facilities to load and unload DataView objects using Hashtable objects. Hashtable objects will most often be 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 that reflects the location of the field within the original copybook data structure. Listing 7-5 shows a sample of a COBOL Copybook.
Listing 7-5 Sample emprec.cpy COBOL Copybook
1 *------------------------------------------------------
2 * emprec.cpy
3 * An employee record.
4 *------------------------------------------------------
5
6 02 emp-record. (Comment 1)
7
8 04 emp-ssn pic 9(9) comp-3.
9
10 04 emp-name.
11 06 emp-name-last pic x(15). (Comment 2)
12 06 emp-name-first pic x(15).
13 06 emp-name-mi pic x.
14
15 04 emp-addr. (Comment 3)
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 7-5 are stored into a Hashtable as shown in the following table.
|
Key String |
Content Type |
|---|---|
|
empRecord.empSsn |
BigDecimal |
|
empRecord.empName.empNameLast |
String |
|
empRecord.empName.empNameFirst |
String |
|
empRecord.empName.empNameMi |
String |
|
empRecord.empAddr.empAddrStreet |
String |
|
empRecord.empAddr.empAddrSt |
String |
|
empRecord.empAddr.empAddrZip |
String |
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". Listing 7-6 shows how this interface is defined.
Listing 7-6 Name Translator Interface
//===============================================================
// NameTranslator.java
// Name Translator interface.
//
// Copyright ©2000, BEA Systems, Inc., all rights reserved.
//---------------------------------------------------------------
package com.bea.dmd.dataview;
/****************************************************************
* Name Translator interface.
* An interface for a 'functor' object that translates field names.
*
* @version $Revision: 1.1 $
* @author Copyright ©2000, BEA Systems, Inc., all rights reserved.
*/
public interface NameTranslator
{
public String translate(String input);
}
// End NameTranslator.java
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 JAM library:
|
Class Constructor |
Purpose |
|---|---|
|
NameFlattener() |
Reduces the key to the portion following the final period character. |
|
PrefixChanger(String old, String add) |
Removes an old prefix & adds a new one. |
|
PrefixChanger(String old) |
Removes a prefix. |
Both the HashtableLoader and HashtableUnloader classes are included in the "com.bea.dmd.dataview" package, as well as the various name translator classes.
|
|
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|