Start of change

Mapping between COBOL and Java data types for non-OO COBOL/Java interoperability

Start of changeThis section describes the COBOL data types and related Java™ data types in non-OO COBOL programs that interoperate with Java through use of the JAVA-CALLABLE or JAVA-SHAREABLE directives or through use of the CALL statement to call a static Java method.End of change

A COBOL program and a Java method need to pass data between one another under the following circumstances:

  • A Java method passes arguments to a COBOL native method
  • A Java method receives a returned value from a COBOL native method
  • A COBOL program passes arguments to a static Java method
  • A COBOL program receives a returned value from a static Java method
  • A Java method directly accesses a data item in a native COBOL method's working-storage
To deal with these scenarios, Enterprise COBOL defines the following legal COBOL types for Java interoperability and their corresponding Java types:
Table 1. Java-compatible elementary COBOL types
PIC X byte
PIC X(m) DISPLAY, m>1
PIC N(m) NATIONAL, m>0
PIC U(m) UTF-8, m>0
PIC U BYTE-LENGTH m, m>0
Start of changePIC X DYNAMIC [LIMIT n] (not supported by the JAVA-SHAREABLE directive and will be ignored)End of change
Start of changePIC U DYNAMIC [LIMIT n](not supported by the JAVA-SHAREABLE directive and will be ignored)End of change		 String
PIC S9(n) COMP-5, 1 ≤ n ≤ 4 short
PIC S9(n) COMP-5, 5 ≤ n ≤ 9 int
PIC S9(n) COMP-5, 10 ≤ n ≤ 18 long
COMP-1 (4-byte IBM® hex float) float (4-byte IEEE float)
COMP-2 (8-byte IBM hex float) double (8-byte IEEE float)
usage COMP-3/PACKED-DECIMAL numeric java.math.BigDecimal
usage DISPLAY numeric (zoned) java.math.BigDecimal 

01 flag pic x.
   88 flag-false value x'00'.
   88 flag-true value x'01'.
 boolean
Table 2. Java-compatible array COBOL types 

01 byte-list.
   03 b1 pic x occurs m times.
 byte[m] 

01 short-list.
   03 s1 pic s9(n) comp-5 occurs m times.

where 1 ≤ n ≤ 4.

 short[m] 

01 int-list.
   03 i1 pic s9(n) comp-5 occurs m times.

where 5 ≤ n ≤ 9.

 int[m] 

01 long-list.
   03 l1 pic s9(n) comp-5 occurs m times.

where 10 ≤ n ≤ 18.

 long[m] 

01 float-list.
   03 f1 pic comp-1 occurs m times.
 float[m] 

01 double-list.
   03 d1 pic comp-2 occurs m times.
 double[m] 

01 bool-list.
   03 b1 pic x occurs m times.
      88 flag-false value x'00'.
      88 flag-true value x'01'.
 boolean[m] 

01 dec-list.
   03 n1 pic s9(m)[v9(n))] display/comp-3 occurs j times.
 BigDecimal[j] 

01 alpha-list.
   03 s1 pic x(m) occurs n times.

where m>1.

 String[n] 

01 nat-list.
   03 n1 pic n(m) occurs n times.
 String[n] 

01 utf8-list.
   03 u1 pic u(m) occurs m times.
 String[m]
Table 3. Java-compatible alphanumeric group COBOL types
Any alphanumeric group item that does not satisfy the definition of a Java-compatible array type is considered to map to a Java byte array (byte[]) and it is the Java application's responsibility to both read and set the byte array appropriately based on the corresponding COBOL group definition. byte[]

Alphanumeric groups

An alphanumeric group item in COBOL that does not satisfy the definition of one of the Java-compatible array types can still be used as an argument in a call to a static Java method and as a parameter in a COBOL program that is callable from Java.

When the group is used as a parameter in a Java callable program, it is assumed that the data being passed from Java to the parameter is a byte array object (byte[]), and it is the responsibility of the calling Java method to set up the data in the corresponding byte array to match the byte layout of the receiving COBOL group item. Conversely, when the group is used as an argument in a call to a static Java method, the called Java method must assume that it is receiving a Java byte array object (byte[]), and it is the responsibility of the Java method to wrap the incoming byte array with a ByteBuffer in order to extract data out of the byte array in a meaningful way based on the layout of the bytes in the corresponding COBOL group.

Using general groups as parameters and arguments offers added flexibility to application developers, allowing them to achieve interoperability between Java and COBOL with complex group items for which there is no clear mapping to a Java type.
Note: When an alphanumeric group item is automatically treated as a Java byte array object because it doesn't satisfy the definition of a Java-compatible array type, the compiler produces informational message IGYPA3415I for the item.

Further considerations

  • Alphanumeric group items are only compatible with Java when used as COBOL parameters or arguments. That is, alphanumeric group items cannot be the returned value of a java-callable program or the returned value from a call to a Java static method.
  • Single-dimension arrays of each supported Java type are supported. To have the compiler treat an incoming Java argument as a single dimension array, or to treat an outgoing COBOL argument as being intended for a single dimension Java array, the COBOL parameter or argument should be defined using the following format:
    01 identifier-1 occurs n times.
    03 identifier-2 <java-compatibile-cobol-data-definition>.
    For example, the following COBOL definition corresponds to a Java int[] type:
    01 list-data occurs 10 times.
    03 num pic s9(9) comp-5.
    Note: If the number of elements in an incoming Java array argument does not match the number of elements indicated in the OCCURS clause of a fixed length table definition in the corresponding COBOL parameter, a runtime error will occur.
  • For conversions between COBOL COMP-1/COMP-2 items and Java float/double items, a loss of precision may occur due to the difference in the underlying representation. That is, COMP-1/COMP-2 are stored in IBM hex float format, and float/double are stored in IEEE binary float format:
    • Conversions between IBM hexadecimal floating point format and IEEE floating point format are done via Language Environment® special purpose C/C++ interface __fp_htob(), using rounding mode _FP_HB_BRN (biased round to nearest).
    • Conversions between IEEE floating point format and IBM hexadecimal floating point format are done via Language Environment special purpose C/C++ interface__fp_btoh(), using rounding mode _FP_HB_BRN (biased round to nearest).
  • A BigDecimal value can be received into either a zoned or packed decimal item in COBOL. Similarly, zoned and packed decimal items are both legal senders for BigDecimal receivers in Java. The conversion between zoned/packed decimal and BigDecimal (and vice versa) is handled automatically by routines in the IBM JZOS toolkit, which must be installed in the environment in which the COBOL / Java interoperable application is running.
  • Start of changeData items defined as "PIC X(m)/U(m)/N(m)" will be padded with an appropriate space character to a length of m characters when the length of the corresponding Java String object is smaller than m characters. Data items defined as "PIC U BYTE-LENGTH m" will be padded with an appropriate space character to a maximum length of m bytes when the length of the corresponding Java String object is smaller than m bytes. Data items defined as "PIC X/U DYNAMIC [LIMIT n]" will not be padded with spaces and will have the same byte length as the corresponding Java String object, up to a maximum of n bytes if the LIMIT phrase of the DYNAMIC clause is specified.End of change
End of change