Mapping COBOL Items and Java Types

Native COBOL programs can pass arguments and receive values to and from Java programs. The valid COBOL and Java type mappings during this interoperability are as follows:

COBOL	Java
Elementary COBOL types
PIC X	byte
PIC X(`n`) DISPLAY PIC N(`n`) NATIONAL PIC U(`n`) UTF-8 PIC X DYNAMIC [LIMIT `n`] PIC U DYNAMIC [LIMIT `n`] Note: For JAVA-CALLABLE programs, and COBOL programs calling Java static methods, dynamic length items are supported under both MF and ENTCOBOL dialects; however, within a JAVA-SHAREABLE block, dynamic length items must be at an 01-level and be under the MF dialect only.	String
PIC S9(`n`) COMP-5, where ≥ 1 `n` ≤ 4	short
PIC S9(`n`) COMP-5, where ≥ 5 `n` ≤ 9	int
PIC S9(`n`) COMP-5, where ≥ 10 `n` ≤ 18	long
COMP-1	float
COMP-2	double
usage COMP-3/PACKED-DECIMAL numeric	java.math.BigDecimal
usage DISPLAY numeric (zoned)	java.math.BigDecimal
01 flag pic x. 88 f-false value x'00'. 88 f-true value x'01'.	boolean
Array COBOL types
01 byte-list. 03 byte-1 pic x occurs n times.	byte[`n`]
01 short-list. 03 short-1 pic s9(n) comp-5 occurs x times. where >=1 `n` <= 4	short[`x`]
01 int-list. 03 int-1 pic s9(n) comp-5 occurs x times. where >= 5 `n` <= 9	int[`x`]
01 long-list. 03 long-1 pic s9(n) comp-5 occurs x times. where >= 10 `n` <= 18	long[`x`]
01 float-list. 03 float-1 pic comp-1 occurs n times.	float[`n`]
01 double-list. 03 dub-1 pic comp-2 occurs n times.	double[`n`]
01 bool-list. 03 bool-1 pic x occurs n times. 88 f-false value x'00'. 88 f-true value x'01'.	boolean[`n`]
01 dec-list. 03 num-1 pic s9(n)[v9(n))] display/comp-3 occurs x times.	BigDecimal[`x`]
01 alpha-list. 03 str-1 pic x(n) occurs x times. where `n` ≥ 1	String[`x`]
01 nat-list. 03 nat-1 pic n(n) occurs x times.	String[`x`]
01 utf8-list. 03 utf-1 pic u(n) occurs x times.	String[`x`]
Alphanumeric group COBOL types
Any alphanumeric group item that does not conform to a Java-compatible array type is mapped to a Java byte array (byte[]); see the note below.	byte[]

Notes on alphanumeric groups: Even if a COBOL alphanumeric group item cannot be mapped to a Java-compatible array type shown in the table above, it can still be passed as an argument to a static Java method and as a parameter in a COBOL program that can be called from Java.

When the group containing such an item is an argument used when calling a static Java method, the Java method must assume that it is receiving a Java byte array object (byte[]), and wraps it in a ByteBuffer in order to extract data out of the byte array in such a way as to conform to the same layout of bytes as the corresponding COBOL group.

When the group is a parameter of a COBOL program being called by Java, the data is also processed as a byte array object (byte[]), and the responsibility of the calling Java method to match the byte layout of the receiving COBOL group item.

This process allows greater interoperability between COBOL and Java programs when complex group items are involved for which there is no valid mapping available.

Also, any alphanumeric group being passed to Java or returned from Java under CHARSET(EBCDIC) is assumed to only contain PIC X data items.

Further notes on mapping

If a Java method returns a string, it will be truncated to the size of the picture clause for the PIC X, PIC N or PIC U item.
For PIC U byte-length n items, the maximum number of UTF-8 characters which will fit. IBM truncates to n/4 characters.
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.
If a BigDecimal object is returned and exceeds the number of integer digits for the DISPLAY or COMP-3 item, a Run-Time System error is generated.
If an array object is returned and its elements exceed the number of OCCURS in the COBOL item, a Run-Time System error is generated.
The Compiler generates a warning when COBOL items that map to Java immutable classes (BigDecimal, String, etc...) are passed BY REFERENCE, as these items cannot be modified by Java.