![]() |
![]() |
![]() |
![]() |
![]() |
• The eGen utility generates a Java application by processing a script you create, called an eGen script. A Java DataView is defined by the first section of the script. This DataView is used by the application code to provide data access and conversions, as well as to perform other miscellaneous functions. The actual application code is defined by the second section of the script.Figure 1 illustrates how the eGen utility works. This illustration shows the eGen script and COBOL copybook file being used as input to the eGen utility, and the output that is generated is the DataView.Figure 1 Understanding the eGen utilityA COBOL CICS or IMS mainframe application typically uses a copybook source file to define its data layout. This file is specified in a COPY directive within the LINKAGE SECTION of the source program for a CICS application, or in the WORKING-STORAGE SECTION of an IMS program. If the CICS or IMS application does not use a copybook file, you will have to create one from the data definition contained in the program source.Each copybook's contents are parsed by the eGen utility, producing DataView sub-classes that provide facilities to:If you are producing a new application on the mainframe or modifying one, then one or more new copybooks may be required. You should keep in mind the COBOL features and data types supported by eGen as you create these copybooks. See “DataView Programming Reference” for more information.When a mainframe application has an existing DPL or APPC interface, the data for that interface is usually described in a COBOL copybook. Before using an existing COBOL Copybook, verify that the interface does not use any COBOL features or data types that eGen does not support (see “Limitations of the eGen Utility”).Figure 2 Sample emprec.cpy COBOL CopybookThe eGen utility is able to translate most COBOL copybook data types and data clauses into their Java equivalents; however, it is unable to translate some obsolete constructs and floating point data types. For information on COBOL data types that can be translated by the eGen utility, see DataView Programming Reference. If the eGen utility is unable to fully support constructs or data types, it:After you have obtained a COBOL Copybook for the mainframe applications, you are ready to write an eGen script. This eGen script and the COBOL copybook that describes your data structure will be processed by the eGen utility to generate a DataView which will serve as the basis for your custom Java application.
• DataView. The DataView section of the script generates Java DataView code from a COBOL copybook. The class file compiled from the generated code extends the Java DataView class. Generating DataViews is discussed in detail in the remainder of this section. See “Writing the DataView Section of an eGen Script” for more information.The eGen utility parses a COBOL copybook and generates Java DataView code that encapsulates the data record declared in the copybook. It does this by parsing an eGen script file containing a DataView definition similar to the example shown in Listing 1 (keywords are in bold).Listing 1 Sample DataView Section of eGen Scriptgenerate view examples.CICS.outbound.gateway.EmployeeRecord from emprec.cpyAnalyzing the parts of this line of code, we see that generate view tells the eGen utility to generate a Java DataView code file. examples.CICS.outbound.gateway.EmployeeRecord tells the eGen utility to call the DataView file EmployeeRecord.java. The package is called examples.CICS.outbound.gateway. The EmployeeRecord class defined in EmployeeRecord.java is a subclass of the DataView class. The phrase from emprec.cpy tells the eGen utility to form the EmployeeRecord DataView file from the COBOL copybook emprec.cpy.Additional generate view statements may be added to an eGen script in order to produce all the DataViews required by your application. Also, additional options may be specified in the eGen script to change details of the DataView generation. For example, the following script will generate a DataView class that uses codepage cp500 for conversions to and from mainframe format. If the codepage clause is not specified, the default codepage of cp037 is used.
Note: If a jolt client calls a COBOL service in Tuxedo on a Linux X86-64 machine, the jolt client should be compiled with the java code generated by eGen with parameter codepage ASCII and endian little in Listing 4.See “A JOLT Example” for more information.Listing 5 Sample DataView Section Supporting XML
When you process the eGen scripts and compile Java code, you must have access to the Java classes and applications used in the code generation and compilation processes. Adding the correct elements to your CLASSPATH and PATH environment variables provides this access.
•
•
•
• Add the path of your DataView class files to your CLASSPATH. You need the access to these classes when you compile your Java application code.
Note: For the eGen script shown in Listing 1, the following shell command parses the copybook file (see Figure 2) and generates EmployeeRecord.java source file in the current directory:Listing 6 Sample Copybook Parse CommandIf no error or warning messages are issued, the copybook is compatible with eGen and the source files are created. Note that no application source files are generated by processing the emprec.egen script. This is because there are no application generating commands in this script.The following example illustrates the generated Java source file, EmployeeRecord.java, with some comments and implementation details removed for clarity.You must compile the Java code generated by the eGen utility. However, there are some special circumstances to consider. Because the application code is dependent on the DataView code, you must compile the DataView code and make sure that the resulting DataView class files are in your environment's CLASSPATH before compiling your application code. You must make sure that all of the DataView class files can be referenced by the application code compilation.Simple interfaces are provided for translating data both from and to the mainframe. In addition, a simple callService() method is available for making mainframe service requests.Support for creating buffers for input to a mainframe service is provided by the com.bea.base.io.MainframeWriter class. This class functions similar to a Java java.io.DataOutputStream object. It translates Java data types and all mainframe-native data types. For numeric data types, this translation service provides a conversion from Java native numeric types to those available on the mainframe. For string data types, a translation is performed from UNICODE to EBCDIC by default, although the output codepage used is configurable.Listing 7 shows the public methods that MainframeWriter class provides.Listing 7 MainframeWriter Class Public Methods
Constructs a MainframeWriter using the specified codepage for character field translation. Returns the translated buffer constructed by writing data to the MainframeWriter class as a byte array. Translate and write a string to a fixed length character field. The passed pad character is used if the length of the passed string is less than len. If the length of the passed string is greater than len, it will be truncated to len characters. The equivalent COBOL picture clause is PIC X(len). Writes a signed 16 bit integer to the output buffer after moving the implied decimal point left by scale digits. For example, the call write16bit(100, 1) would result in the value 10 being written. The equivalent COBOL picture clause is PIC S9(4) COMP. Writes an unsigned 16 bit integer to the output buffer after moving the implied decimal point left by scale digits. For example, the call write16bitUnsigned(100, 1) would result in the value 10 being written. The equivalent COBOL picture clause is PIC 9(4) COMP. Writes a signed 32 bit integer to the output buffer after moving the implied decimal point left by scale digits. For example, the call write32bit(100L, 1) would result in the value 10 being written. The equivalent COBOL picture clause is PIC S9(8) COMP. Writes an unsigned 32 bit integer to the output buffer after moving the implied decimal point left by scale digits. For example, the call write32bitUnsigned(100L, 1) would result in the value 10 being written. The equivalent COBOL picture clause is PIC 9(8) COMP. Writes a signed 64 bit integer to the output buffer after moving the implied decimal point left by scale digits. For example, the call write64bit(100L, 1) would result in the value 10 being written. The equivalent COBOL picture clause is PIC S9(15) COMP. Writes an unsigned 64 bit integer to the output buffer after moving the implied decimal point left by scale digits. For example, the call write64bitUnsigned(100L, 1) would result in the value 10 being written. The equivalent COBOL picture clause is PIC 9(15) COMP. Writes a decimal number as an IBM signed packed data type with digits decimal digits total and prec digits to the right of the decimal point. Prior to conversion, the number is scaled to the left scale digits. The equivalent COBOL picture clause is PIC S9(digits-prec)V9(prec) COMP-3. Writes a decimal number as an IBM unsigned packed data type with digits decimal digits total and prec digits to the right of the decimal point. Prior to conversion the number is scaled to the left scale digits. The equivalent COBOL picture clause is PIC 9(digits-prec)V9(prec) COMP-3.As an example of using the MainframeWriter class to create a mainframe data buffer, assume we have a mainframe service which accepts the data record shown as below.Listing 8 Data Record05 LAST-NAME PIC X(10).05 HOURLY-RATE PIC S9(3)V9(2) COMP-3.Listing 9 shows a Java test program that creates a buffer matching this record layout using MainframeWriter translation class:Listing 9 Java Test ProgramSupport for translating data received from the mainframe to Java data types is provided by the com.bea.base.io.MainframeReader class. This class operates in a manner similar to a Java jam.io.DataInputStream, and performs translations from mainframe data types to equivalent types usable by a Java program. Like the MainframeWriter class, the codepage used for string translations may be configured and defaults to EBCDIC.Listing 10 shows the public methods that MainframeReader class provides.Listing 10 MainframeReader Class Public Methods
Constructs a MainframeReader for the passed buffer using the specified codepage for character field translation. Reads and translates a fixed length character field and returns it as a Java String. The length of the field is passed as len and the field pad character is passed as pad. Trailing instances of the pad character are removed before the data is returned. Reads a 16 bit binary integer and scales the value by 10^scale. For example, if value 10 is read via read16bit(1), the returned value would be 100. Reads a 32 bit binary integer and scales the value by 10^scale. For example, if value 10 is read via read32bit(1), the returned value would be 100. Reads an unsigned 32 bit binary integer and scales the value by 10^scale. For example, if value 10 is read via read32bit(1), the returned value would be 100. Reads an unsigned 64 bit binary integer and scales the value by 10^scale. For example, if value 10 is read via read32bit(1), the returned value would be 100. Reads an unsigned packed number consisting of digits numeric digits with prec digits to the right of the decimal. The value is scaled by 10^scale and is returned as a Java BigDecimal. Reads a signed packed number consisting of digits numeric digits with prec digits to the right of the decimal. The value is scaled by 10^scale and is returned as a Java BigDecimal.As an example of using the MainframeReader, class following is a program that translates and displays the fields in the mainframe buffer created above. Our input buffer consists of the binary data:Listing 11 shows the sample program used to process this buffer.Listing 11 Sample ProgramThe 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).Table 4 lists some mapping examples.
1. Groups map to DataView subclasses.
2.
3.
4.
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.
10.
Table 5 Numeric Field Mapping 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.Listing 12 Sample CopybookEach 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).FieldType is described in the Field Type Mappings section.FieldName is described in the Field Name Mapping Rules section.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:Array fields specified with the DEPENDING ON clause are handled the same as fixed-size arrays with the following special rules:
•
• 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 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.Listing 13 Sample CopybookThis section summarizes the COBOL data types supported by Tuxedo. Table 6 lists the COBOL data item definitions recognized by the eGen utility. Table 7 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 6 Major COBOL Features
Table 7 COBOL Data Types eGen allows you to access DataView classes through several methods as described in the following sections:Mainframe format data may be extracted from a DataView class through the use of the MainframeWriter class. Listing 14 shows a sample of code that may be used to perform the extraction.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 15.Loading mainframe data into a DataView is a similar process, in this case requiring the use of the MainframeReader class. Listing 15 shows a sample of code that may be used to perform the load.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.The following list shows an example of the code used to unload a DataView into XML.Listing 18 shows a sample of a COBOL copybook.Listing 18 Sample emprec.cpy COBOL Copybook8 04 emp-ssn pic 9(9) comp-3.11 06 emp-name-last pic x(15).12 06 emp-name-first pic x(15).13 06 emp-name-mi pic x.16 06 emp-addr-street pic x(30).17 06 emp-addr-st pic x(2).18 06 emp-addr-zip pic x(9).
Table 8 COBOL Copybook Hashtable Following is an example of the code used to unload a DataView into a Hashtable.Following is an example of the code used to load a Hashtable into an existing DataView.
• Each data item is stored as an object of its Java type. Elements of int/short/long type are converted to Integer/Short/Long.
•
• Hashtable members of the wrong type result in a ClassCastException being thrown.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 9 lists the descriptions of the public interface methods that must be implemented.
Table 9 Name Translator Interface
Table 10 Name Translator Interface The HashtableLoader, HashtableUnloader, and the various name translator classes are included in the "com.bea.dmd.dataview" package.
• 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.Program development will be accomplished according to program snippet listed in Listing 19 and according to class naming rules outlined here, although this can be adjusted depending on customer requirements.Listing 19 Program SnippetListing 20 Setup ConnectionListing 21 Input Bean UsageListing 22 Service InvocationListing 23 Output Bean UsageBelow is the COBOL copybook emprec.cpy.Listing 24 Sample COBOL copybook emprec.cpy04 emp-ssn pic 9(9) comp-3.06 emp-name-last pic x(15).06 emp-name-first pic x(15).06 emp-name-mi pic x.06 emp-addr-street pic x(30).06 emp-addr-st pic x(2).06 emp-addr-zip pic x(9).
• Next, you could process eGen script emprec.egen as below, and then java file EmployeeRecord.java is generated.
• Next, after compiling EmployeeRecord.java, you will get four java class files.
• Next, you can write jolt client java code with EmployeeRecord.java. See below for a simple example.Listing 25 Sample Java Code
• One Tuxedo server site, you can write a Tuxedo COBOL server that uses the same copybook emprec.cpy. See below for a simple example.Listing 26 Sample on Tuxedo Server Site