Oracle® Tuxedo Accessing Mainframe from Java 12c Release 2 (12.2.2) April 2016 Oracle Tuxedo Accessing Mainframe from Java, 12c Release 2 (12.2.2) Copyright © 1996, 2016, Oracle and/or its affiliates. All rights reserved. This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited. The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing. If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable: U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government. This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners. This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services. Contents Generating a Java Application with the eGen Application Generator Generating a Java Application with the eGen Application Generator. .1 Overview. .2 Understanding eGen . .2 Working with COBOL Copybooks. .3 Obtaining a COBOL Copybook . .4 Limitations of the eGen Utility . .5 Writing an eGen Script . .6 Writing the DataView Section of an eGen Script . .6 Processing eGen Scripts with the eGen Utility. .8 Creating an Environment for Generating and Compiling the Java Code . .8 Generating the Java DataView Code . .9 Special Considerations for Compiling the Java Code . .11 Performing Your Own Data Translation . .11 Why Perform Your Own Data Translation? . .11 Translating Buffers from Java to Mainframe Representation. .12 MainframeWriter Public Interface. .12 Using MainframeWriter to Create Data Buffers . .17 Translating Buffers from Mainframe Format to Java . .19 MainframeReader Public Interface . .19 Using MainframeReader to Translate Data Buffers . .22 Accessing Mainframe from Java i DataView Programming Reference . 24 Field Name Mapping Rules . 25 Field Type Mappings . 25 Group Field Accessors . 26 Elementary Field Accessors. 27 Array Field Accessors . 27 Fields with REDEFINES Clauses . 28 COBOL Data Types . 29 Other Access Methods for Generated DataView Classes . 31 Mainframe Access to DataView Classes . 31 XML Access to DataView Classes . 34 Hashtable Access to DataView Classes . 36 Known Limitations of eGen working with COBOL Copybooks . 39 Program Development. 39 Important Areas . 42 A JOLT Example . 44 Tuxedo Mainframe Transaction Publisher Overview . 1 Using Tuxedo Mainframe Transaction Publisher . 2 Tuxedo Mainframe Transaction Generator . 3 Select COBOL Copybook . 4 Define Code Generation Details . 4 Configure Transaction Input and Output . 5 Enter Transaction Details . 6 Tuxedo Mainframe Transaction Publisher. 8 Pack Artifacts . 8 Publish to OSB . 9 ii Accessing Mainframe from Java Installing/Uninstalling Tuxedo Mainframe Transaction Publisher . 10 Prerequisite. 10 Installing Tuxedo Mainframe Transaction Publisher . 11 Checking Installation Status . 12 Using graphical user interface. 12 Using command lines . 12 Uninstalling Tuxedo Mainframe Transaction Publisher. 13 Installation Notes . 14 Setting up JDeveloper Project . 14 Setting up Oracle Service Bus (OSB) . 16 Installing EGen Libraries for OSB. 16 Importing Shared Resources to OSB . 16 Accessing Mainframe from Java iii iv Accessing Mainframe from Java Generating a Java Application with the eGen Application Generator This document includes the following topics: z Generating a Java Application with the eGen Application Generator z Performing Your Own Data Translation z DataView Programming Reference z Program Development z A JOLT Example Generating a Java Application with the eGen Application Generator z Overview z Understanding eGen z Working with COBOL Copybooks z Writing an eGen Script z Processing eGen Scripts with the eGen Utility Accessing Mainframe from Java 1 Overview Oracle Tuxedo supports seamless integration of CICS Transaction Gateway (CTG) application running on J2EE application servers and JCA based. With this feature, Oracle Tuxedo provides a tool to z parse COBOL copybooks used to describe CICS transactions/programs interfaces z generate Java bean style classes to populate data Therefore, users can pass those classes to a CCI (or ECI-wrapped) interface to perform ART-hosted CICS invocations. Understanding eGen eGen Application Generator, also known as the eGen utility, generates Java applications from a COBOL copybook and a user-defined script file. 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. 2 Accessing Mainframe from Java Generating a Java Application with the eGen Application Generator Figure 1 Understanding the eGen utility Working with COBOL Copybooks A 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: z Convert COBOL data types to and from Java data types. This includes conversions for mainframe data formats and code pages. Accessing Mainframe from Java 3 z Convert COBOL data structures to and from Java data structures. z Convert the provided data structures into other arbitrary formats. Obtaining a COBOL Copybook The eGen utility must have a COBOL Copybook to use as input. There are two methods you can use to obtain this Copybook: z Creating a New COBOL Copybook z Using an Existing COBOL Copybook Creating a New COBOL Copybook 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. Using an Existing COBOL Copybook 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”). See Figure 2 for an example COBOL copybook source file. 4 Accessing Mainframe from Java Generating a Java Application with the eGen Application Generator Figure 2.