bea.com | products | dev2dev | support | askBEA
 Download Docs 
 Search 

Programming Guide

 Previous Next Contents Index View as PDF  

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.

  1. All dashes are removed and the character following the dash is mapped to upper case.

  2. When a prefix is added to the name (as when creating a field accessor function name), the first character of the base name is mapped to upper case.

Table  A-1 lists some mapping examples.

Table A-1 Example Field Name Mapping from COBOL to Java and Accessor

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, the data types of fields are mapped to Java data types. The mapping is performed by the eGen utility according to the following rules:

  1. Groups map to DataView subclasses.

  2. All alphanumeric fields are mapped to type String.

  3. All edited numeric fields are mapped to type String.

  4. All SIGN SEPARATE, BLANK WHEN ZERO or JUSTIFIED RIGHT fields are mapped to type String.

  5. SIGN IS LEADING is not supported.

  6. The types COMP-1, COMP-2, COMP-5, COMP-X, and PROCEDURE-POINTER fields are not supported (an error message is generated).

  7. All INDEX fields are mapped to Java type int.

  8. POINTER maps to Java type int.

  9. All numeric fields with any digits to the right of the decimal point are mapped to type BigDecimal.

  10. All COMP-3 (packed) fields are mapped to type BigDecimal.

  11. All other numeric fields are mapped as shown in Table  A-2.


     

 


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:

FieldType

is described in the Field Type Mappings section.

FieldName

is described in the Field Name Mapping Rules section.

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:

  1. The accessors may be used to get or set any instance up to the maximum array index.

  2. The controlling (DEPENDING ON) variable is evaluated when the DataView is converted to or from an external format, such as a mainframe format. The eGen utility converts only the array elements with subscripts less than the controlling value.

 


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.

Table A-3 Major COBOL Features

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


 

Table A-4 COBOL Data Types

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

Unsupported

COMP-X

Unsupported

DISPLAY numeric (zoned)

BigDecimal

BLANK WHEN ZERO (zoned)

String

SIGN IS LEADING (zoned)

Unsupported

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)

Unsupported

edited float numeric

String

DISPLAY (alphanumeric)

String

edited alphanumeric

String

INDEX

Int

POINTER

Int

PROCEDURE-POINTER

Unsupported

JUSTIFIED RIGHT

Unsupported (ignored)

SYNCHRONIZED

Unsupported (ignored)

REDEFINES

Supported

66 RENAMES

Unsupported

66 RENAMES THRU

Unsupported

77 level

Supported

88 level (condition)

Unsupported (ignored)

group record

Inner Class

OCCURS (fixed array)

Array

OCCURS DEPENDING (variable-length array)

Array

OCCURS INDEXED BY

Unsupported (ignored)

OCCURS KEY IS

Unsupported (ignored)


 

 


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

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. Table  A-6 lists the descriptions of the public interface methods that must be implemented.

Table A-6 Name Translator Interface

Method

Description

translate(String input)

This method received a String object as an input parameter and returns a String object.


 

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:

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.


 

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.

 

Back to Top Previous Next