Getting started with IBM Record Generator for Java

To get started with IBM® Record Generator for Java™, check that you have the prerequisite environment, then download the product. After you extract the ibm-recgen.jar file from the download and transfer it to the system where you want to run IBM Record Generator for Java, you can start to work with it.

Supported environments

To use IBM Record Generator for Java, you need:
  • A compatible Java Runtime Environment (JRE)
    • Java 8 JRE, either 32-bit (31-bit on z/OS®) or 64-bit.
    • IBM Semeru Runtime Certified Edition for z/OS version 11, 17 or 21.
  • To work with COBOL copybooks:
    • IBM Enterprise COBOL for z/OS V4.2 or later.
  • To work with assembler DSECTs:
    • IBM High Level Assembler for z/OS and z/VM and z/VSE 1.6 and future fix packs.
  • IBM JZOS Toolkit API package com.ibm.jzos.fields at V2.4.8 or later, provided by
    • IBM SDK for z/OS Java Technology Edition if using Java 8.
    • If using IBM Semeru Runtime Certified Edition for z/OS V11, V17 or V21, then the ibmjzos.jar file must be downloaded by going to the IBM Support page for Java SDK Products on z/OS.

Installing IBM Record Generator for Java

  1. Download IBM Record Generator for Java from the IBM Record Generator for Java product page.
  2. Extract the ibm-recgen.jar file from the downloaded zip file.
  3. Transfer the ibm-recgen.jar file in binary format to the system where you want to run IBM Record Generator for Java.
  4. If you are running on a non-z/OS platform, the IBM JZOS Toolkit API must be available on the non-z/OS platform by transferring the ibmjzos.jar from:
    1. The IBM SDK for z/OS Java Technology Edition if you are running Java 8.
    2. The IBM Support page for Java SDK Products on z/OS here: https://www.ibm.com/support/pages/java-sdk-products-zos if using IBM Semeru Runtime Certified Edition for z/OS V11, V17 or V21.

Using IBM Record Generator for Java

  1. Create the ADATA file from the COBOL copybook or assembler DSECT by running the z/OS Enterprise COBOL compiler or High Level Assembler with the ADATA option. For details, see, Creating ADATA files with the IBM Enterprise COBOL for z/OS compiler, or Creating ADATA files with IBM High Level Assembler.
  2. Run either the COBOL or assembler version of the RecordClassGenerator class, supplying the ADATA file as input. This produces Java source code that represents the record structure. If you are running on a non-z/OS platform, make sure that the IBM JZOS Toolkit API is also available on the non-z/OS platform. For details, see Running the COBOL RecordClassGenerator, or Running the assembler RecordClassGenerator.
  3. Transfer the generated Java class to your Java integrated development environment (IDE) and include it with your Java application that needs to access the structured record data.
  4. Within your Java application, use the accessor methods on the Java class to get and set the field values for the record data.
  5. Compile the Java application and deploy to the target system such as a CICS® JVM server, WebSphere® Application Server for z/OS, or a Java batch environment.
Optionally, you can use the RecordXMLGenerator class to create an intermediary description of the COBOL copybook or assembler DSECT. For more information, see Running the RecordXMLGenerator.

Java 21 Considerations

Record generator will run under Java 21.

An important consideration when running the generator on z/OS with Java 21 is that source files are generated with the now default UTF-8 encoding. For z/OS systems this default encoding for Java has changed at Java 21, from the previous default EBCDIC encoding.

If you generate source with Java 21 and compile it with an earlier release of the Java compiler, you will need to add the -encoding UTF-8 option to your javac command. For example,
javac -encoding UTF-8 generatedSource.java
This tells the compiler that the source code being compiled is written as UTF-8.
Conversely, if you run the generator with a Java version prior to Java 21 and you then compile the generated source with Java 21, you will need to run the compiler with the -encoding IBM-1047 option. For example,
javac -encoding IBM-1047 generatedSource.java
This tells the compiler that the source code being compiled is written as EBCDIC.

V3.0.3 Java 21 Considerations

Java source files generated by V3.0.3 on z/OS will be tagged on the Unix System Services file system as UTF-8. This will allow the Java 21 compiler to recognize the encoding of the generated Java source without having to specify the -encoding option .