Corporate Info | News | Solutions | Products | Partners | Services | Events | Download | How To Buy
WebLogic Java Adapter for Mainframe User Guide Doc Home | BEA WebLogic Java Adapter for Mainframe User Guide | Previous Topic | Next Topic | Contents | Index

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:

- 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

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:

1. All alphabetic characters are mapped to lower case.

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

####

Table 7-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 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:

1. Group fields 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 IS LEADING, SIGN IS TRAILING, BLANK WHEN ZERO or JUSTIFIED RIGHT fields are mapped to type String.

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

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

7. POINTER maps to Java type int.

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

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

10. All other numeric fields are mapped as shown in Table 7-2.

    ####

    Table 7-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 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:

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

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 COBOL tool 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 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.

####

Table 7-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 7-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 | 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

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

- 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 will also be produced.

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:

- All data elements in the DataView will be placed into the Hashtable.

- Each data item will be stored as an object of its Java type. Elements of in/short/long type will be converted to Integer/Short/Long.

- Arrays will be 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 will attempt to acquire a value from the Hashtable. If no matching key exists, the element will retain its original value.

- Hashtable members of the wrong type will result in 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 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 © 2001 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.