31-bit COBOL and 64-bit Java interoperability

Software requirements

This interoperability requires specific functions from the COBOL compiler, the Language Environment, and the 64-bit IBM® Java Software Development Kit (SDK). Required software includes the following items:

• IMS APAR PH37140.
• Language Environment APAR PH28966, which provides the base support for interoperability.
• Language Environment APAR PH40444, which provides a fix for S422 ABEND (BMP region) or U4083 ABEND out of CELQLIB during IMS dependent region termination.
• COBOL APAR PH37101.
• Java IBM SDK, Java Technology Edition V8.0.6.36 (FixPack 36) or newer.

Additionally, consider the following important information regarding Java, COBOL (including Object-Oriented COBOL), and IMS.

Java considerations

The following Java considerations for IMS applications are based on IBM SDK, Java Technology Edition. To learn more, see Using 31-bit native C or C++ code with the 64-bit Java VM (z/OS only).

Limitations

• The 31-bit native application must be a single-thread. The 64-bit Java application can be multi-threaded but only a single Java application thread is allowed to interoperate across the address mode (AMODE) boundary. If a second application thread tries to load a 31-bit library or call a 31-bit C or C++ function, a java.lang.UnsatisfiedLinkError is usually thrown.
• You must compile the 31-bit native application with standard CALL linkage; XPLINK is not supported.
• Language Environment Condition handling support is not available across the AMODE boundary. Specifically, -XCEEHDLR, -Xsignal:userConditionHandler=percolate, and related options are not supported. Language Environment conditions are not converted into Java exceptions.
• Signal chaining is not supported across the AMODE boundary.
• Environment variables are copied across the AMODE boundary on the first transition only. Subsequent updates in one AMODE environment are not propagated back to the other; instead, the variables are tracked separately in each AMODE environment. To learn more, see Environment variables propagation to secondary Language Environment in Introduction to AMODE 31 and AMODE 64 programs interoperability.

COBOL considerations

The following COBOL considerations are based on COBOL technical note An enhancement in COBOL/JNI interface. To learn more, see COBOL programs in AMODE 31 interacting with Java programs in AMODE 64.

Object-Oriented (OO) COBOL

COBOL programming considerations

In a mixed 31/64-bit environment, references to Java types must be declared as PIC 9(18) COMP-5 in COBOL (that is, as an 8-byte data item). The OBJECT-REFERENCE type cannot be used because this data item maps to an incorrect 4-byte size in AMODE 31 COBOL programs. This applies to COBOL data items that interact with JNI types such as jobject, jclass, jfieldID, jmethodID, jarray, and jarray<type> when they are used as parameters in JNI calls.

Note that accesses to EXTERNAL data items and EXTERNAL files are not serialized.

Building the mixed AMODE COBOL/Java interoperability application

It is recommended that you build and run COBOL JNI applications in z/OS® UNIX.

Compiling

To compile the COBOL program, use the cob2 command in a z/OS UNIX shell. Specify the RENT, DLL and PGMNAME(LONGMIXED) compiler options. The THREAD option is not mandatory if only one COBOL program is active in the run-unit at any time.

If the COBOL program includes the file JNI.cpy by using a COPY statement, specify the include subdirectory of the COBOL install directory (typically /usr/lpp/cobol/include) in the search order for copybooks. You can specify the include subdirectory by using the -I option of the cob2 command or by setting the SYSLIB environment variable.

Linking

To prepare the COBOL program for execution, link the object file with the following two DLL side files to create an executable module:

• libjvm31.x, which is provided with your 64-bit IBM Java Software Development Kit: $JAVA_HOME/lib/s390x/j9vm.
• igzxjni2.x, which is provided in the lib subdirectory of the cobol directory in the z/OS UNIX file system (typically /usr/lpp/cobol/lib). This DLL side file is also available as the member IGZXJNI2 in the SCEELIB PDS.

Do not link with the sidedeck igzcjava.x, which is used only by object-oriented features and is not supported in the mixed AMODE environment. Linking both igzxjni2.x and igzcjava.x in the same program can lead to ABENDs.

Note that $JAVA_HOME is the home directory of the 64-bit IBM Java Software Development Kit.

IMS considerations

The following list includes known limitations, things to consider, and changes in behavior between a 31-bit only environment and a mixed address mode environment running 31-bit COBOL and 64-bit Java.

• The UMASK environment option is not supported on the 64-bit Java environment.
• Unhandled exceptions, such as divide by zero, in a COBOL first application will cause the Language Environment to terminate and trigger the IMS dependent region controller to go through termination without issuing a U0101 ABEND with reason code 'B'x (11 decimal).
• For Java application programs, only the main thread can properly interact with the IMS control region. This is an existing restriction for Java application programs.

Dependent region setup

Dependent region setup for 31-bit COBOL and 64-bit Java interoperability is slightly different than for interoperability between 31-bit COBOL and 32-bit Java. Differences include a different positional startup option for the dependent region's JCL (JVM=3164), a different IMS module (DFSJVM36), a different Java DLL (libjvm31.so), and a different JVM option (-XX:+Enable3164Interoperability), which is automatically included by DFSJVM36 when starting the JVM. IMS module DFSJVM36 will print messages that begin with "DFSJVM36:" to the dependent region's job log.

To set up a dependent region that supports 31-bit COBOL code and 64-bit Java code, make the following changes:

• Update the dependent region's JCL to include the new option JVM=3164. You can tailor the JCL examples in the following Samples section to start the different dependent region types.
• Update the dependent region's JCL to include the IMS SDFSJLIB as part of the STEPLIB concatenation. This data set contains new IMS code that is needed for proper execution of the dependent region.
• Update the LIBPATH and CLASSPATH to point to the 64-bit Java installation directories to be able to start the 64-bit JVM. See the samples of the ENVIRON= member and the JVMOPMAS= member or the STDENV DD card contents in the following section.

Samples

The following samples show JVM and other configuration information specified in the ENVIRON=DFSJVMEV and JVMOPMAS=DFSJVMMS members:

*****************************
HLQ.PROCLIB(DFSJVMEV)
*****************************
LIBPATH=/tmp:>                                          
javahome/J8.0_64/lib/s390x/j9vm/:>           
javahome/J8.0_64/lib/s390x/compressedrefs:>  
javahome/J8.0_64/lib/:>
/usr/lpp/ims/ims15/imsjava/lib/:

*****************************
HLQ.PROCLIB(DFSJVMMS)
****************************

-Xms256m                                                       
-Xmx1024m                                                      
-Djzos.logging=E                                               
-Djzos.merge.sysout=false                                      
-Djava.class.path=/tmp:>                                       
javahome/J8.0_64/:>                                 
javahome/J8.0_64/lib/:>                             
javahome/J8.0_64/lib/ext:>                          
/tmp/udbtest-0.0.1.jar:>                                       
/usr/lpp/ims/ims15/imsjava/imsudb.jar    

The alternative to using ENVIRON= and JVMOPMAS= is to use the STDENV DD card on the JCL for starting the dependent region. The following is a sample of the STDENV member that can be specified on the STDENV DD card:

*****************************
HLQ.PDS(STDENV01)
*****************************
LP=/tmp                                                         
LP="$LP":javahome/J8.0_64/lib/s390x/j9vm/
LP="$LP":javahome/J8.0_64/lib/s390x/compressedrefs/
LP="$LP":javahome/J8.0_64/lib/
LP="$LP":/usr/lpp/ims/ims15/imsjava/lib/
export LIBPATH="$LP":                                           
CP=/tmp
CP="$CP":javahome/J8.0_64/
CP="$CP":javahome/J8.0_64/lib/
CP="$CP":javahome/J8.0_64/lib/ext
CP="$CP":/tmp/udbtest-0.0.1.jar
CP="$CP":/usr/lpp/ims/ims15/imsjava/imsudb.jar
export CLASSPATH="$CP":
IJO="-Xms256m"
IJO="$IJO -Xmx512m"
IJO="$IJO -Djzos.logging=E"
IJO="$IJO -Djzos.merge.sysout=false"
export IBM_JAVA_OPTIONS="$IJO "

Troubleshooting common issues

You see message DFS529E indicating an invalid value on the JVM exec parameter. For example:

DFS529E MPP00001.REGION.MPP00001 - AN INVALID VALUE IS SPECIFIED ON THE JVM EXEC PARAMETER

• This message indicates that the job MPP00001 to start dependent region MPP00001 contains an invalid value for JVM=. This can indicate that IMS APAR PH37140 is not on the system, or that the value specified for parameter JVM= is not 31 (default) or 3164.

You see multiple messages that begin with 'DFSJVM00: Option' or 'DFSJVM64: Option' in the dependent region's job output.

• The DFSJVM00 messages indicate that the dependent region was started without the parameter JVM=3164, or with the parameter in the wrong position. The DFSJVM64 messages indicate that a JMP or JBP dependent region type was started with JVM=64.

You see message DFSJVM00 in the dependent region's job output, indicating a failure to open libjvm.so:

DFSJVM00: dlopen(libjvm.so) failed; function(JNI_CreateJavaVM); EDC5254S An AMODE31 application is attempting to load an AMODE64 DLL load module.

• This indicates that you are starting a dependent region without the parameter JVM=3164 or with the parameter in the wrong position, and that you properly configured the LIBPATH to point to the 64-bit Java SDK.

You see message DFSJVM36 in the dependent region's job output, indicating a failure to open libjvm31.so:

DFSJVM36: dlopen(libjvm31.so) failed; function(JNI_CreateJavaVM);

• This indicates that the LIBPATH is not pointing to the 64-bit Java SDK, or that the 64-bit Java SDK is not at V8.0.6.36 or newer. To resolve, ensure that you installed Java SDK V8.0.6.36 or newer and that the LIBPATH points to it.

You see messages DFSJVM36 and CEL4RO64 in the dependent region's job output, indicating a failure to start the JVM and no support for CEL4RO64:

DFSJVM36: JNI_CreateJavaVM() failed
CEL4RO64: CEL4RO64 runtime support not found.
JNI_CreateJavaVM failed. CEL4RO64 rc: 6 - CEL4RO64 runtime support not found.

• The CEL4RO64 message produced by the Java Native Interface (JNI) indicates that the Language Environment CEL4RO64 runtime support function is not present on the system. To resolve, ensure that the required Language Environment APARs are installed on the system.

The dependent region terminates with U0101 ABEND and reason code 'E'x (14 decimal).

• Reason code 'E'x (14 decimal) for U0101 ABEND indicates that the dependent region was started without the SDFSJLIB in the STEPLIB concatenation. The SDFSJLIB contains files that are needed by the IMS dependent region to support 31-bit COBOL and 64-bit Java interoperability.