BEA Home | Events | Solutions | Partners | Products | Services | Download | Developer Center | WebSUPPORT
JAM Documentation | JAM Reference Guide | Previous Topic | Next Topic | Contents | Index

JAM 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 COBOL Code 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 BEA WebLogic Java Adapter for Mainframe (JAM) product CD-ROM in the jam.jar file.

This section discusses data mapping rules in the following topics:

- Field Name Mapping Rules

- Field Type Mappings

- Group Field Accessors

- Elementary Field Accessors

- Array Field Accessors

- Fields with REDEFINES Clauses

- COBOL Data Types

- Other Access Methods for Generated DataView Classes

- Known Limitations

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. The mapping is performed by the eGen utility according to the following rules:

1. All alphabetic characters are mapped to lower case, except in the following two cases.

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

3. 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 1-1 lists some mapping examples.

Table 1-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 1-2.

Table 1-2 Numeric Field Mapping

Number of Digits

Java Type

<= 4

short

> 4 and <= 9

int

> 9 and <= 18

long

> 18

BigDecimal

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 JAM software. Table 1-3 lists the COBOL data item definitions recognized by the eGen utility. Table 1-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 1-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 1-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

JAM allows you to access DataView classes through several methods as described in the following sections:

- Mainframe Access to DataView Classes

- XML Access to DataView Classes

- Hashtable Access to DataView Classes

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 1-1 shows a sample of code that may be used to perform the extraction.

Listing 1-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 1-1.

Loading mainframe data into a DataView is a similar process, in this case requiring the use of the MainframeReader class. Listing 1-2 shows a sample of code that may be used to perform the load.

Listing 1-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.

- XmlLoader is used to load XML data into a DataView.

- XmlUnloader is used to unload data from a DataView into XML.

- If the eGen COBOL script used to produce the DataView specifies the "support xml" option, then both a DTD and an XML/Schema that describe the XML format for this DataView are produced.

Listing 1-3 shows an example of the code used to load XML data into a DataView.

Listing 1-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 1-4 shows an example of the code used to unload a DataView into XML.

Listing 1-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 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 1-5 shows a sample of a COBOL Copybook.

Listing 1-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 1-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:

- All data elements in the DataView are placed into the Hashtable.

- Each data item is stored as an object of its Java type. Elements of int/short/long type are converted to Integer/Short/Long.

- Arrays are mentioned at the appropriate level in the key as an index enclosed in "[", "]" pairs. For instance, if empAddr was an array, then one key into the Hashtable might be "empRecord.empAddr[2].empAddrStreet".

The basic rules of Hashtable loading are:

- All data elements in the DataView attempt to acquire a value from the Hashtable. If no matching key exists, the element retains its original value.

- Hashtable members of the wrong type result in a ClassCastException being thrown.

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 1-6 shows how this interface is defined.

Listing 1-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.

The HashtableLoader, HashtableUnloader, and the various name translator classes are included in the "com.bea.dmd.dataview" package.

Known Limitations

Following are some of the known limitations of this version of the JAM product.

- Continuation lines are not recognized in COBOL copybooks. This is only a problem for long character literals occurring within VALUES clauses. Comment out the relevant clause to fix the problem.

- COBOL copybooks with array (table) data items having an OCCURS DEPENDING ON clause must be structured so that the depending-on counter data item is not contained within the same group data item as the one containing the array.

- USAGE clauses on group data items in COBOL copybooks are not properly propagated to their subordinated member data items.

Copyright © 2001 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.